Quick Setup

No need to waste hours upon hours to implement your own turrets when rTurret does all the work for you.

Flexible

rTurret come with 50+ functions to help you customize your turret down to the last detail.

Player Targeting

Turrets are able to aim at players with preference based on a predefined behavior or your own custom behavior.

Accuracy

Predictive aiming algorithm allows your turrets to aim ahead of the player according to their speed and direction, almost guaranteeing bullets of any speed will hit players moving in a constant direction.

AI

Turret AI is somewhat similar to how turrets behave in other games, most notably turrets in TF2. With LoS capabilities, turrets will shoot if they're able to "see" a player, or remain inactive otherwise, i.e. hide behind a wall and the turret won't know you're there.

Bullet

The default bullet is non-solid so you won't have camera collision or sudden knock-backs and small enough to resemble an actual projectile. Bullets are able to "collide" with solid objects, meaning you can safely take cover behind a wall without the bullet passing through it.

All turrets have a defined behavior. Behaviors prefixed with TURRET_BEHAVIOR_AIM_* aim at their intended target and feature LoS+predictive aim capabilities by default. Use one of these macros when creating a turret (for the "behavior" parameter) or for setting a turret behavior.

pawn Code:

TURRET_BEHAVIOR_STATIONARY              (0) 
TURRET_BEHAVIOR_ROTATE_CLOCKWISE        (1)
TURRET_BEHAVIOR_ROTATE_COUNTERCLOCKWISE (2)
TURRET_BEHAVIOR_AIM_CLOSEST             (3)
TURRET_BEHAVIOR_AIM_FARTHEST            (4)
TURRET_BEHAVIOR_AIM_WEAKEST             (5)
TURRET_BEHAVIOR_AIM_STRONGEST           (6)
TURRET_BEHAVIOR_AIM_RANDOM              (7)
TURRET_BEHAVIOR_AIM_SINGLE              (8)
TURRET_BEHAVIOR_AIM_CUSTOM              (9)

TURRET_BEHAVIOR_STATIONARY - Turret aims and shoots in one direction.
TURRET_BEHAVIOR_ROTATE_CLOCKWISE - Turret shoots while rotating clockwise.
TURRET_BEHAVIOR_ROTATE_COUNTERCLOCKWISE - Turret shoots while rotating counterclockwise.
TURRET_BEHAVIOR_AIM_CLOSEST - Turret aims and shoots at the closest player within its range.
TURRET_BEHAVIOR_AIM_FARTHEST - Turret aims and shoots at the farthest player within its range.
TURRET_BEHAVIOR_AIM_WEAKEST - Turret aims and shoots at the player with the lowest health and armor within its range.
TURRET_BEHAVIOR_AIM_STRONGEST - Turret aims and shoots at the player with the highest health and armor within its range.
TURRET_BEHAVIOR_AIM_RANDOM - Turret aims and shoots at a random player within its range.
TURRET_BEHAVIOR_AIM_SINGLE - Turret aims and shoots at a predefined player within its range, which can be set with SetTurretSingleTarget(turretid, targetid).
TURRET_BEHAVIOR_AIM_CUSTOM - Turret aims and shoots at a player whose id is the return value of OnTurretCustomShoot(turretid).

Turrets have LoS capabilities! To enable, install ColAndreas and set your turret behavior to one of the aiming behaviors prefixed as TURRET_BEHAVIOR_AIM_*. By default, turrets with aiming behaviors will shoot only if there is a line of sight to a player. For all behaviors, bullets will collide with solid objects if there are any in their path (this can be disabled with the ToggleTurretLOS function). Thanks to the creators of ColAndreas for making this possible!

CreateTurret(behavior = TURRET_BEHAVIOR_STATIONARY, playerid = INVALID_PLAYER_ID, Float:x = 0.0, Float:y = 0.0, Float:z = 0.0, Float:rx = 0.0, Float:ry = 0.0, Float:rz = 1000.0, world = -1, interior = -1, rate = 100, Float:speed = 20.0, Float:dmg = 25.0, Float:range = 50.0, Float:streamdistance = 200.0);

Description: Creates a turret. Note that all parameters are optional.

• behavior - The behavior of the turret (see "Turret Behaviors" above).
• playerid - The id of the player (turret owner) that the kill will be attributed to under OnPlayerDeath if a target is killed by the turret. The turret owner will also be immune to the turret.
• Float:x - The X coordinate to create the turret at.
• Float:y - The Y coordinate to create the turret at.
• Float:z - The Z coordinate to create the turret at.
• Float:rx - The X rotation of the turret object.
• Float:ry - The Y rotation of the turret object.
• Float:rz - The Z rotation of the turret object.
• world - The ID of the virtual world to create the turret in.
• interior - The ID of the interior to create the turret in.
• rate - The rate (in milliseconds) at which the turret fires bullets.
• Float:speed - The speed (in units per second) of the turret bullets.
• Float:dmg - The amount of damage a player takes when hit (health and armor combined).
• Float:range - The max distance (in units) bullets travel and the range in which the turret will shoot.
• Float:streamdistance - The stream distance of the turret object.

Returns:

On success: The id of the turret created
On failure: INVALID_TURRET_ID

DestroyTurret(turretid, &iter_next = -1);

Description: Destroys a turret.

• turretid - The id of the turret.
• iter_next - The variable to store the next iterator continue value. For destroying turrets in the foreach loop of the "rTurrets" iterator. (optional)

Returns:

On success: 1
On failure: 0

IsValidTurret(turretid);

Description: Checks if the given turret id is valid (exists).

• turretid - The id of the turret.

Returns:

On success: 1
On failure: 0

OnTurretCreate(turretid);

Description: Called right after a turret is created. An ideal place to customize your turret.

• turretid - The id of the turret.

Returning:

Not handled.

OnTurretDestroy(turretid);

Description: Called right before a turret is destroyed.

• turretid - The id of the turret.

Returning:

Not handled.

OnTurretDeath(turretid, killerid, weaponid);

Description: Called right before a turret is destroyed by a player.

• turretid - The id of the turret.
• killerid - The id of the player that killed the turret
• weaponid - The weapon used by the player

Returning:

Not handled.

OnTurretHitPlayer(turretid, playerid);

Description: Called right after a turret bullet hits a player but before the player takes damage. (The turret's equivalent of OnPlayerWeaponShot)

• turretid - The id of the turret.
• playerid - The id the player that was hit by the bullet.

Returning:

1 will allow the turret to damage the player.
0 will prevent the turret from damaging the player.

OnPlayerTakeTurretDamage(playerid, turretid, Float:damage);

Description: Called right after a player takes damage from a turret.

• playerid - The id of the player that took damage from the bullet.
• turretid - The id of the turret.
• Float:damage - The amount of damage playerid took. (health and armor)

Returning:

Not handled.

OnPlayerShootTurret(playerid, weaponid, turretid, Float:fX, Float:fY, Float:fZ);

Description: Called when the player's bullet hits the turret.

• playerid - The id of the player that shot the turret.
• weaponid - The id of the weapon used by the player.
• turretid - The id of the turret.
• Float:fX - The x offset of the point of impact.
• Float:fY - The y offset of the point of impact.
• Float:fZ - The z offset of the point of impact.

Returning:

0 will prevent the bullet from causing damage.
1 will allow the bullet to cause damage

OnTurretMoved(turretid);

Description: Called right after a turret has finished moving with MoveTurret (see "Extra Functions" below).

• turretid - The id of the turret.

Returning:

Not handled.

OnTurretCustomShoot(turretid);

Description: This is a special callback for the behavior TURRET_BEHAVIOR_AIM_CUSTOM. It's called right before the turret shoots a bullet. The return value of this callback is the id of the player the turret will shoot. Since the turret will only be able to shoot players within its range, you have to either iterate through valid targets using foreach(new i : rTurretTargets[turretid]) or check if the return value is a valid target within the turret's range using Iter_Contains(rTurretTargets[turretid], playerid).

• turretid - The id of the turret.

Returning:

The value will be the id of the player the turret shoots at.

Example Usage:

pawn Code:

public OnTurretCustomShoot(turretid)
{
    // For example purposes only
    // Shoot player with the highest level
    // Note that GetPlayerLevel isn't an actual function in this include!
    new
        highestLevel = -1,
        targetid = INVALID_PLAYER_ID;

    foreach(new i : rTurretTargets[turretid])
        if (GetPlayerLevel(i) > highestLevel)
            targetid = i;

    return targetid;
}

OnTurretBulletCollision(turretid, Float:x, Float:y, Float:z);

Description: Called when a bullet collides with a solid object.

• turretid - The id of the turret.
• Float:x - The x coordinate of the point of collision.
• Float:y - The y coordinate of the point of collision.
• Float:z - The z coordinate of the point of collision.

Returning:

Not handled.

pawn Code:

GetTurretObject(turretid);
GetTurretOwner(turretid);
GetTurretBehavior(turretid);
GetTurretTeam(turretid);
Float:GetTurretHealth(turretid);
GetTurretPos(turretid, &Float:x, &Float:y, &Float:z);
GetTurretRot(turretid, &Float:rotx, &Float:roty, &Float:rotz);
Float:GetTurretRotSpeed(turretid);
Float:GetTurretBulletRadius(turretid);
GetTurretWorld(turretid);
GetTurretInterior(turretid);
GetTurretText(turretid, text[], maxlength = sizeof(text));
GetTurretTextOffset(turretid, &Float:offsetx, &Float:offsety, &Float:offsetz);
GetTurretFireRate(turretid);
Float:GetTurretBulletSpeed(turretid);
Float:GetTurretDamage(turretid);
Float:GetTurretRange(turretid);
GetTurretMaterial(turretid, materialindex, &modelid, txdname[], texturename[], &materialcolor, maxtxdname = sizeof txdname, maxtexturename = sizeof texturename);
Float:GetTurretStreamDistance(turretid);
GetTurretBulletModel(turretid);
GetTurretBulletColor(turretid);
GetTurretBulletOffset(turretid, &Float:offsetx, &Float:offsety, &Float:offsetz);
GetTurretBulletRot(turretid, &Float:rx, &Float:ry, &Float:rz);
GetTurretVisibleBullets(turretid);
GetTurretMaxVisibleBullets(turretid);
GetTurretSound(turretid);
GetTurretKiller(playerid);

pawn Code:

SetTurretOwner(turretid, playerid);
SetTurretBehavior(turretid, behavior);
SetTurretTeam(turretid, team);
SetTurretHealth(turretid, Float:health);
SetTurretPos(turretid, Float:x, Float:y, Float:z);
SetTurretRot(turretid, Float:rotx, Float:roty, Float:rotz);
SetTurretRotSpeed(turretid, Float:speed);
SetTurretBulletRadius(turretid, Float:radius);
SetTurretWorld(turretid, world);
SetTurretInterior(turretid, interior);
SetTurretText(turretid, color, const text[]);
SetTurretTextOffset(turretid, Float:offsetx, Float:offsety, Float:offsetz, Float:drawdistance = -1.0, testlos = -1);
SetTurretFireRate(turretid, rate);
SetTurretBulletSpeed(turretid, Float:speed);
SetTurretDamage(turretid, Float:damage);
SetTurretRange(turretid, Float:range);
SetTurretMaterial(turretid, materialindex, modelid, const txdname[], const texturename[], materialcolor = 0);
SetTurretStreamDistance(turretid, Float:streamdistance);
SetTurretBulletModel(turretid, modelid);
SetTurretBulletColor(turretid, color = 0);
SetTurretBulletOffset(turretid, Float:offsetx, Float:offsety, Float:offsetz);
SetTurretBulletRot(turretid, Float:rx, Float:ry, Float:rz);
SetTurretMaxVisibleBullets(turretid, maxbullets);
SetTurretSound(turretid, soundid);
SetTurretSingleTarget(turretid, targetid);

pawn Code:

/*
Toggle whether the turret will shoot bullets.
Default: On
ToggleTurretActive(turretid, toggle);

Toggle whether the turret will take bullet damage from players. Turret's health will be set to sethealth once toggled, or if sethealth is -1.0, health will remain what it was previously.
Default: Off
ToggleTurretHealth(turretid, toggle, Float:sethealth = -1.0);

Toggle whether the turret will shoot only if there is at least one player in range.
Default: On
ToggleTurretCheckArea(turretid, toggle);

Toggle whether the turret will play a sound per shot.
Default: On
ToggleTurretPlaySound(turretid, toggle);

Toggle whether players can see the turret.
Default: On
ToggleTurretVisible(turretid, toggle);

Toggle whether the turret will aim in 3D space.
Default: On
ToggleTurretAim3dSpace(turretid, toggle);

Toggle whether the turret will have predictive aim.
Default: On
ToggleTurretPredictiveAim(turretid, toggle);

Toggle whether the turret's bullets will end their path against a solid object.
Default: On
ToggleTurretLOS(turretid, toggle);

Applicable to aim behaviors only, toggles whether the turret will shoot once there is a line of sight to a player, otherwise will remain inactive. Must have turret LoS toggled on.
Default: On
ToggleTurretLOSAim(turretid, toggle);

Toggles whether the turret reserves its damage for the player it's aiming at while ignoring other targets.

If enabled, only the specified target set by the turret's aiming behavior (TURRET_BEHAVIOR_AIM_*) will take damage, even if the bullet hits a different player in its path.
Default: Off
ToggleTurretTargetFocus(turretid, toggle);
*/

pawn Code:

/*
Set the turret text position to the turret's.
UpdateTurretTextPos(turretid);

Use this instead of MoveDynamicObject
MoveTurret(turretid, Float:X, Float:Y, Float:Z, Float:Speed, Float:RotX = -1000.0, Float:RotY = -1000.0, Float:RotZ = -1000.0);

Force turret damage to a player, regardless of the player's location
TurretDamagePlayer(turretid, playerid);
*/

pawn Code:

// Contains all turret IDs
Iterator:rTurrets<MAX_TURRETS>;

// Contains all players within the turret's shooting range
Iterator:rTurretTargets[MAX_TURRETS]<MAX_PLAYERS>;

// Contains all players who can hear the turret fire bullets
Iterator:rTurretPlayersInBigArea[MAX_TURRETS]<MAX_PLAYERS>;

pawn Code:

#define TURRET_BEHAVIOUR_STATIONARY                 TURRET_BEHAVIOR_STATIONARY
#define TURRET_BEHAVIOUR_ROTATE_CLOCKWISE           TURRET_BEHAVIOR_ROTATE_CLOCKWISE
#define TURRET_BEHAVIOUR_ROTATE_COUNTERCLOCKWISE    TURRET_BEHAVIOR_ROTATE_COUNTERCLOCKWISE
#define TURRET_BEHAVIOUR_AIM_CLOSEST                TURRET_BEHAVIOR_AIM_CLOSEST
#define TURRET_BEHAVIOUR_AIM_FARTHEST               TURRET_BEHAVIOR_AIM_FARTHEST
#define TURRET_BEHAVIOUR_AIM_WEAKEST                TURRET_BEHAVIOR_AIM_WEAKEST
#define TURRET_BEHAVIOUR_AIM_STRONGEST              TURRET_BEHAVIOR_AIM_STRONGEST
#define TURRET_BEHAVIOUR_AIM_RANDOM                 TURRET_BEHAVIOR_AIM_RANDOM
#define TURRET_BEHAVIOUR_AIM_SINGLE                 TURRET_BEHAVIOR_AIM_SINGLE
#define TURRET_BEHAVIOUR_AIM_CUSTOM                 TURRET_BEHAVIOR_AIM_CUSTOM

#define GetTurretBehaviour                          GetTurretBehavior
#define SetTurretBehaviour                          SetTurretBehavior
#define GetTurretBulletColour                       GetTurretBulletColor
#define SetTurretBulletColour                       SetTurretBulletColor

• By default a turret has no set team. Setting a turret's team with SetTurretTeam(turretid, team) will allow all players in that team to be immune to the turret's damage. Even if the team is not the turret owner's, the turret owner will still be immune to the turret's damage (and always will be).
• 3D space aiming allows bullets to travel to different elevations. 2D space aiming restricts bullets to horizontal paths parallel to a straight ground. By default turrets aim at players in 3D space. To disable 3D space aiming, use ToggleTurretAim3dSpace(turretid, 0).
• Predictive aim causes turrets to aim ahead of the player depending on the player's speed and direction. As of v1.5, predictive aim is enabled by default.
• GetTurretKiller(playerid) only works under OnPlayerDeath and OnPlayerSpawn. Other than that it returns INVALID_TURRET_ID. It's useful for getting the id of the turret that killed you.
• 3D Text Label positions will automatically be updated if you set the turret's position with SetTurretPos(turretid, Float:x, Float:y, Float:z). However if you move the turret with MoveTurret or SetDynamicObjectPos, the text position won't update because 3D text labels cannot be attached to objects. To update the text's position to the turret's, use UpdateTurretTextPos(turretid).
• Setting the turret's X and Y rotations to values other than 0.0 will cause the bullet's origin to be incorrect.
• Using rTurret in a filterscript and gamemode at the same time may crash your server! It will also spam "*** Streamer_IsInArrayData: Invalid ID specified" messages to your console every time a turret bullet is destroyed.
• You can set the turret health while it has its health toggled off; it'll take effect the next time you toggle it on.
• Due to bullet hit inaccuracies with idle players, idle players instantly lose health instead of a physical bullet being created, assuming the turret has a targeting behavior.
• You cannot use MoveTurret with any of the rotating behaviors as they will conflict.

• Version 1.5.1 (7/18/2015)
  • Fixed bugs and removed warnings
  • Added TurretDamagePlayer
  • Added (Get/Set)TurretBulletOffset
  • Added (Get/Set)TurretBulletRot
• Version 1.5 (7/1/2015)
  • Improved predictive aim algorithm
  • Added Turret Health system:
  • GetTurretHealth
  • SetTurretHealth
  • ToggleTurretHealth
  • OnPlayerShootTurret
  • OnTurretDeath
  • Added LoS feature (requires ColAndreas):
  • ToggleTurretLOS
  • ToggleTurretLOSAim
  • OnTurretBulletCollision
  • Minor bug fixes/tweaks
  • More details
• Version 1.1 (7/19/2014)
  • Added ToggleTurretTargetFocus,
  • Added GetTurretOwner, SetTurretOwner,
  • Added SetTurretMaterial, GetTurretMaterial
  • Added definitions for British English spelling
  • Minor bug fixes
  • More details
• Version 1.0 (7/14/2014)
  • First release

SA-MP Version 0.3.7
Streamer Plugin - by Incognito
ColAndreas Plugin - by [uL]Slice, [uL]Chris420, [uL]Pottus
foreach - by ******

Include v1.5.1 (Latest)
Pastebin
If using this in a filterscript, define FILTERSCRIPT before the include.

Example Filterscript v1.5
Pastebin (requires ZCMD, sscanf2 and this include)
Use this optional filterscript to test out the functions and figure out how you want to customize your turret.

Previous Versions
Include v1.1
Include v1.0

Quote:

Originally Posted by CuervO Note: I didn't read the code but you don't specify this in any part of your thread. The only problem with automatic turrets is the LoS. As I said I didn't read the code and you don't mention it on your thread, do the turrets have a LoS? Will they still aim and kill you if you hide behind a wall, vehicle or anything like it that would obstruct the vision and bullet impacts? The script is great but without a LoS solution it's practically useless on true DM/TDM enviroments. This is also the reason of why the engineer turrets on my TF GM are manual and not automated, while there are some ways to check for LoS it not only requires MapAndreas but it would also be uneffective in custom maps or under the map maps.

GetTurretOwner(turretid);
GetTurretMaterial(turretid, materialindex, &modelid, txdname[], texturename[], &materialcolor, maxtxdname = sizeof txdname, maxtexturename = sizeof texturename);

SetTurretOwner(turretid, playerid);
SetTurretMaterial(turretid, materialindex, modelid, const txdname[], const texturename[], materialcolor = 0);

ToggleTurretTargetFocus(turretid, toggle);

#define TURRET_BEHAVIOUR_STATIONARY                 TURRET_BEHAVIOR_STATIONARY
#define TURRET_BEHAVIOUR_ROTATE_CLOCKWISE           TURRET_BEHAVIOR_ROTATE_CLOCKWISE
#define TURRET_BEHAVIOUR_ROTATE_COUNTERCLOCKWISE    TURRET_BEHAVIOR_ROTATE_COUNTERCLOCKWISE
#define TURRET_BEHAVIOUR_AIM_CLOSEST                TURRET_BEHAVIOR_AIM_CLOSEST
#define TURRET_BEHAVIOUR_AIM_FARTHEST               TURRET_BEHAVIOR_AIM_FARTHEST
#define TURRET_BEHAVIOUR_AIM_WEAKEST                TURRET_BEHAVIOR_AIM_WEAKEST
#define TURRET_BEHAVIOUR_AIM_STRONGEST              TURRET_BEHAVIOR_AIM_STRONGEST
#define TURRET_BEHAVIOUR_AIM_RANDOM                 TURRET_BEHAVIOR_AIM_RANDOM
#define TURRET_BEHAVIOUR_AIM_SINGLE                 TURRET_BEHAVIOR_AIM_SINGLE
#define TURRET_BEHAVIOUR_AIM_CUSTOM                 TURRET_BEHAVIOR_AIM_CUSTOM

#define GetTurretBehaviour                          GetTurretBehavior
#define SetTurretBehaviour                          SetTurretBehavior
#define GetTurretBulletColour                       GetTurretBulletColor
#define SetTurretBulletColour                       SetTurretBulletColor

• Fixed a bug where the turret bullets disappeared even if they hit its owner or a player on its team.
• Turret damages greater than a player's health and armor combined now instantly kill the player whereas previously it took two hits to do so.
• Turrets now don't shoot upon creation if checkarea is enabled and there are no targets in its range.

Quote:

Originally Posted by Onfroi Also, if you want to add line-of-sight check this out.

Quote:

Originally Posted by Crayder Eww. That's one of the worst way to do this. This is precisely why ColAndreas was created.

Quote:

Originally Posted by Onfroi Sorry for bump. But why does my console spam with "*** Streamer Plugin: Streamer_IsInArrayData: Invalid ID specified" when the turret is active?