Rnpc

From SA-MP Wiki

Jump to: navigation, search

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

1 Scripting functions
2 Example code

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".

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.

Parameters:

(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);

Retrieved from "https://wiki.sa-mp.com/wiki/Rnpc"

Category: Plugin Documentation

Views

Personal tools

Search

Toolbox