Rnpc
From SA-MP Wiki
This page explains the functions provided by the RNPC plugin by User:Mauzen RNPC (Recordfree NPCs) is a server plugin. Its purpose is to create the NPC record files in runtime, so they dont need to be recorded manually. This way the NPCs can be controlled dynamically from the script-side. It is based on the knowledge about the Rec-files.
This article is based on Version 0.4. For earlier Versions check the wiki history.
It can be found in this forum thread: http://forum.sa-mp.com/showthread.php?t=355849
Contents |
Scripting functions
General
ConnectRNPC
Description:
Connects a new RNPC to the server. This, or at least using the RNPC npcscript is needed for any other functions.
Parameters:(name[])
| name[] | Name of the NPC. |
Return Values:
ID of the connected NPC
MoveRNPC
Description:
Simply moves the NPC to the given position. This works without entering build mode first.
Parameters:(npcid, Float:x, Float:y, Float:z, Float:speed)
| npcid | ID of the NPC to move. |
| x,y,z | Target coordinates. |
| speed | Movement speed. See the define section for fix values. |
Return Values:
1 on success, 0 on fail
Record generation
RNPC_CreateBuild
Description:
Use this function to enter "build mode".
Parameters:It creates the record file for the given NPC and so allows the other function to write to it.
It is important to stop the current playback of a NPC before building a new one, or the NPC will crash. To avoid this you can create the build in another slot.(npcid, type, slot)
| npcid | The ID of the NPC who should be controlled. |
| type | The recording type, either PLAYER_RECORDING_TYPE_ONFOOT or PLAYER_RECORDING_TYPE_VEHICLE |
| slot | The recording slot that should be created. Every slot got its own file, so you can keep multiple recordings for a NPC at once, and later choose which one should be played back. Default value is 0 |
Return Values:
1 on success, 0 if build mode is already active.
RNPC_FinishBuild
Description:
Finishes the currently active build and ends the "build mode". This is needed before playing the generated record back.
Parameters:(clear)
| npcid | Determines if a last segment should be added at the end to clear things like velocity and movement, so the NPC just stands still after the playback. Default value is 1 |
Return Values:
1 on success, 0 if there is no active build.
RNPC_AddMovement
Description:
Appends a movement from (x1,y1,z1) to (x2,y2,z2) to the current build. Good to set the NPCs initial position
Parameters:(Float:x1, Float:y1, Float:z1, Float:x2, Float:y2, Float:z2, Float:speed, use_zmap)
| x1,y1,z1 | The coordinates where the NPC should start to move. |
| x2,y2,z2 | The target coordinates. |
| speed | Movement speed. See the define section for fix values. |
| use_zmap | If true, RNPC will get the z-coordinates from MapAndreas. |
Return Values:
1 on success, 0 on fail
RNPC_AddMovementAlt
Description:
Appends a movement from (x1,y1,z1) to (x2,y2,z2) to the current build. Also supports previously set acceleration.
Theres no real reason to use this for OnFoot-NPCs.
Parameters:(Float:x1, Float:y1, Float:z1, Float:x2, Float:y2, Float:z2, Float:speed)
| x1,y1,z1 | The coordinates where the NPC should start to move. |
| x2,y2,z2 | The target coordinates. |
| speed | Movement speed. See the define section for fix values. |
| lock | Lock the vehicle to the ground, if MapAndreas was initalized. |
Return Values:
1 on success, 0 on fail
RNPC_ConcatMovement
Description:
Appends a movement from the NPCs last position to (x,y,z) to the current build.
Parameters:(Float:x, Float:y, Float:z, Float:speed, use_zmap)
| x,y,z | The target coordinates. |
| speed | Movement speed. For OnFoot-Running 0.006 is a good value. |
| use_zmap | If true, RNPC will get the z-coordinates from MapAndreas. |
Return Values:
1 on success, 0 on fail
RNPC_AddPause
Description:
Adds a pause to the current build. The NPC wont move, but continue with his current attributes (e.g. keeps shooting).
Parameters:(Ftime)
| time | Time [ms] to pause. |
Return Values:
1 on success, 0 on fail
Attribute setters
Theres a whole bunch of simple setter functions. They are meant to be used in build mode, and affect all following actions of the NPC for that build, until changed again. They should be quite self-explaining, so heres just a plain list of all OnFoot-Setters:
native RNPC_SetLRKeys(lr); native RNPC_SetUDKeys(ud); native RNPC_SetKeys(keys); native RNPC_SetQuat1(Float:w); // Better use SetAngleQuats than this native RNPC_SetQuat2(Float:x); native RNPC_SetQuat3(Float:y); native RNPC_SetQuat4(Float:z); native RNPC_SetHealth(hp); // This health value is pretty much useless native RNPC_SetArmour(arm); // This armor value is pretty much useless native RNPC_SetSpecialAction(sp); native RNPC_SetWeaponID(weaponid); native RNPC_SetAnimID(anim); native RNPC_SetAnimParams(params); // Not sure how the params work yet native RNPC_SetAngleQuats(Float:a, Float:h, Float:b); // a, h and b are degree angles, where h is the onfoot facing angle native RNPC_SetSirenState(siren); native RNPC_SetDriverHealth(health); native RNPC_SetInternalPos(Float:x, Float:y, Float:z); // For debugging native RNPC_SetAcceleration(Float:acc); // Accleration in speed/second for AddMovementAlt native RNPC_SetUpdateRate(rate); // The interval in ms in which segments are written. Default of 100ms should be fine. native RNPC_GetBuildLength(); // Returns the lentgh of the currently active, or last finished build in ms
Playback control
RNPC_StartBuildPlayback
Description:
Starts playing a preciously generated recording.
Parameters:(npcid, slot)
| npcid | The ID of the NPC who should play his recording. |
| slot | The slot of the build that should be played back. Default value is 0 |
| vehicleid | If this is set, the NPC will be forced to enter the vehicle twice, to fix issues with vehicles being far away from their recorded position. |
Return Values:
This function does not return any specific values.
RNPC_StartPlayback
Description:
Makes the NPC play back any recording file in the npcmodes directory. Be aware that the NPC will crash if the specified recording file does not exist or is invalid (e.g. vehicle recording when the NPC isnt in a vehicle).
Parameters:(npcid, rec[])
| npcid | The ID of the NPC who should play the recording. |
| slot | The name of the recording that should be played. |
Return Values:
This function does not return any specific values.
RNPC_StopPlayback
Description:
Stops any running playback for the given NPC. Once the stopping finished, OnRNPCPlaybackStopped will be called.
Parameters:(npcid)
| npcid | The ID of the NPC who should stop. |
Return Values:
This function does not return any specific values.
RNPC_PauseRecordingPlayback
Description:
Pauses the recording playback. Due to SA-MP limitations this has a delay of about 200ms.
Parameters:(npcid)
| npcid | The ID of the NPC who should pause. |
Return Values:
This function does not return any specific values.
RNPC_ResumeRecordingPlayback
Description:
Resumes a previously paused recording playback.
Parameters:(npcid)
| npcid | The ID of the NPC who should resume playback. |
Return Values:
This function does not return any specific values.
RNPC_SetAutorepeat
Description:
Sets whether the NPC should restart his playback after finishing it.
Parameters:(npcid, repeat)
| npcid | The ID of the NPC to control |
| repeat | 1/0 to set repeating. |
Return Values:
This function does not return any specific values.
Damage management
Since 0.4 NPCs can handle different kinds of damage, and can get killed. This is disabled by default, the following functions are used to enable and customize it:
RNPC_SetShootable
Description:
Sets whether a NPC should automatically take damage from guns. The damage dealt is the default GTA/SA-MP damage.
Alternatively, use SetRNPCHealth in OnPlayerGiveDamage to use your own damage values.
Parameters:(npcid, enable)
| npcid | The ID of the NPC to control |
| toggle | Enable/disable gun damage |
Return Values:
This function does not return any specific values.
RNPC_ToggleVehicleCollisionCheck
Description:
Sets whether a NPC should report if he got hit by a car. (Call OnRNPCVehicleHit).
This can be a pretty intensive task for big servers, so it should be used with caution.
Parameters:(npcid, enable)
| npcid | The ID of the NPC to control |
| toggle | Enable/disable vehicle collision check |
Return Values:
This function does not return any specific values.
SetRNPCHealth
Description:
Sets the health of the NPC. This value is independent from the Set/GetPlayerHealth health values.
If health is set to a value smaller or equal to 0, the NPC dies.
Parameters:(npcid, Float:health, issuer, reason)
| npcid | The ID of the NPC to control |
| health | New health value for the NPC. |
| issuer | ID of the player responsible for the damage, for OnRNPCDeath (default: INVALID_PLAYER_ID) |
| reason | Reason for the damage, for OnRNPCDeath (default: 53) |
Return Values:
This function does not return any specific values.
GetRNPCHealth
Description:
Returns the current health of the NPC.
Parameters:(npcid)
Return Values:
The current health of the NPC as Float
RespawnRNPC
Description:
Just a public wrapper function for SpawnPlayer, to be used for timers.
Parameters:(npcid)
Return Values:
This function does not return any specific values.
Callbacks
OnRNPCPlaybackFinished
Description:
Called when a NPC finished playing back his current recording file.
Parameters:(npcid)
| npcid | The ID of the NPC who finished playback. |
Return Values:
This callback does not handle returns.
OnRNPCPlaybackStopped
Description:
Called when a NPC stopped playing back his current recording file (via script).
As there is some syncing time between RNPC_StopPlayback and the actual stop, this callback should be used for further NPC instructions.
Parameters:(npcid)
| npcid | The ID of the NPC who stopped playback. |
Return Values:
This callback does not handle returns.
OnRNPCDeath
Description:
Called when a NPC died.
Parameters:(npcid, killerid, reason)
| npcid | The ID of the NPC who died. |
Return Values:
Return 0 to perform the RNPC standard actions (death animation, respawn in 4 seconds, calling OnPlayerDeath), or return 1 to skip them.
OnRNPCVehicleHit
Description:
Called when a NPC is hit by a car.
Parameters:(npcid, driverid, vehicleid, times)
| npcid | The ID of the NPC who was hit. |
| driver | The ID of the player who drove the car that hit the NPC |
| vehicleid | The ID of the vehicle that hit the NPC |
| times | Specifies how long the vehicle is already standing on the NPC in 100ms. Check this for 0 to detect the initial vehicle hit |
Return Values:
Return 0 to apply the RNPC standard vehicle damage, or return 1 to skip them.
Value-Defines
// Types for RNPC_CreateBuild #define PLAYER_RECORDING_TYPE_NONE 0 // Unused #define PLAYER_RECORDING_TYPE_DRIVER 1 #define PLAYER_RECORDING_TYPE_ONFOOT 2 // Movementspeed values // Walking animation will be set accordingly #define RNPC_SPEED_SPRINT (0.0095) #define RNPC_SPEED_RUN (0.0057) #define RNPC_SPEED_WALK (0.0015)
Structural defines
In order to customize RNPC easily, there are several optional defines to deactivate/active certain parts of RNPC. In order to use them they must be defined in the script before #include <rnpc>
#define RNPC_DEBUG // Prints detailled debug information to the console. Useful for bug reports #define RNPC_NO_VERSION_CHECK // Deactivates the version check on startup, and any statistic communication with mauzen.org #define RNPC_NO_STATUPDATES // Still check for RNPC updates, but dont send statistics to mauzen.org #define RNPC_DONT_USE_DEAD_STREAMIN_FIX // Dead NPCs normally replay a death-animation when streaming in. This one disables that behavior. #define RNPC_DONT_PAUSE_ON_VEHICLEHIT // Disables autopause/resume on vehiclehits. rnpcData[npcid][RNPC_VEHICLEHIT] needs to be reset to 0 manually then. // Dont use this unless you know what you're doing.
Example code
The "build mode-thingy" might be hard to understand just from explaining the single functions. So heres some example code that should make it more clear.
Walk a bit and rage-shoot
SetPlayerPos(npcid, 0.0, 0.0, 0.0); RNPC_CreateBuild(npcid, PLAYER_RECORDING_TYPE_ONFOOT); // start build mode RNPC_SetWeaponID(32); // Set weapon RNPC_AddPause(500); // wait a bit RNPC_AddMovement(0.0, 0.0, 0.0, 20.0, 20.0, 0.0); // start moving RNPC_ConcatMovement(0.0, 20.0, 0.0); // Continue walking RNPC_AddPause(200); // wait a bit again RNPC_SetKeys(128); // aim straight forward RNPC_AddPause(500); RNPC_SetKeys(128 + 4); // Start shooting straight forward RNPC_AddPause(500); for (new i = 0; i < 360; i+=20) { // Makes the NPC rotate slowly RNPC_SetAngleQuats(0.0, i, 0.0); RNPC_AddPause(150); } RNPC_SetKeys(128); // stop shooting RNPC_AddPause(500); RNPC_SetKeys(0); // stop aiming RNPC_FinishBuild(); // end the build mode and finish the build RNPC_StartBuildPlayback(npcid); // start playback
Simple following script
stock FollowPlayer(npcid, targetid) { SetTimerEx("Follower", 500, 1, "ii", npcid, targetid); } public Follower(npcid, targetid) { new Float:x, Float:y, Float:z; GetPlayerPos(targetid, x, y, z); MoveRNPC(npcid, x, y, z, 0.006); }
Flying drag race
new npc = ConnectRNPC("Racer"); new veh = CreateVehicle(420, 0.0, 0.0, 25.0, 0.0, -1, -1, 0); PutPlayerInVehicle(npc, veh, 0); RNPC_CreateBuild(npc, PLAYER_RECORDING_TYPE_DRIVER); RNPC_SetAcceleration(0.003); RNPC_AddMovementAlt(0.0, 0.0, 25.0, 0.0, 500.0, 25.0, 0.15, false); RNPC_FinishBuild(); RNPC_StartBuildPlayback(npc);
