15.07.2014, 03:50
(
Last edited by Corekt; 18/07/2015 at 08:45 PM.
)
rTurret v1.5
Highly customizable turrets for SA-MP!
Highly customizable turrets for SA-MP!
rTurret allows you to easily create your own fully-automated turrets. With hundreds of customization possibilities, you can tweak the turrets for your own server needs. rTurret features player targeting and LoS capabilities, resulting in AI similar to ones you've seen in other games such as TF2.
Summary
Quick SetupNo need to waste hours upon hours to implement your own turrets when rTurret does all the work for you.FlexiblerTurret come with 50+ functions to help you customize your turret down to the last detail.Player TargetingTurrets are able to aim at players with preference based on a predefined behavior or your own custom behavior.AccuracyPredictive 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.AITurret 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.BulletThe 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.
Video
[ame]http://www.youtube.com/watch?v=xwecWGMMADE[/ame] (Outdated)
Turret Behaviors
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.
TURRET_BEHAVIOR_STATIONARY - Turret aims and shoots in one direction.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_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).
Line of Sight
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!
Core Functions
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.Returns:
- 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.
On success: The id of the turret created
On failure: INVALID_TURRET_ID
DestroyTurret(turretid, &iter_next = -1);
Description: Destroys a turret.Returns:
- 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)
On success: 1
On failure: 0
IsValidTurret(turretid);
Description: Checks if the given turret id is valid (exists).Returns:
- turretid - The id of the turret.
On success: 1
On failure: 0
Callbacks
OnTurretCreate(turretid);
Description: Called right after a turret is created. An ideal place to customize your turret.Returning:
- turretid - The id of the turret.
Not handled.
OnTurretDestroy(turretid);
Description: Called right before a turret is destroyed.Returning:
- turretid - The id of the turret.
Not handled.
OnTurretDeath(turretid, killerid, weaponid);
Description: Called right before a turret is destroyed by a player.Returning:
- turretid - The id of the turret.
- killerid - The id of the player that killed the turret
- weaponid - The weapon used by the player
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)Returning:
- turretid - The id of the turret.
- playerid - The id the player that was hit by the bullet.
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.Returning:
- 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)
Not handled.
OnPlayerShootTurret(playerid, weaponid, turretid, Float:fX, Float:fY, Float:fZ);
Description: Called when the player's bullet hits the turret.Returning:
- 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.
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).Returning:
- turretid - The id of the turret.
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).Returning:
- turretid - The id of the turret.
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.Returning:
- 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.
Not handled.
Getter Functions
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);
Setter Functions
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);
Toggle Functions[INDENT]
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);
*/
Extra Functions
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);
*/
foreach Iterators
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>;
British English Definitions
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
Notes
- 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.
Changelog
Requirements
- 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.7Installation
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
