Skip to content

Callbacks

Jump to bottom
Sergei Marochkin edited this page Aug 26, 2023 · 65 revisions

Home ▸ Callbacks

General

FCNPC_OnInit()

  • Return values: This callback does not handle returns.

Gets called when an FCNPC plugin are fully initialized (call FCNPC_Create here).

FCNPC_OnCreate(npcid)

  • Parameters:
    • npcid: The ID of the NPC that connected to the server.
  • Return values: This callback does not handle returns.

Gets called when an NPC gets created.

FCNPC_OnDestroy(npcid)

  • Parameters:
    • npcid: The ID of the NPC that disconnected from the server.
  • Return values: This callback does not handle returns.

Gets called when an NPC gets destroyed, or when an NPC gets disconnected from the server (kicked/banned).

FCNPC_OnSpawn(npcid)

  • Parameters:
    • npcid: The ID of the NPC that spawned.
  • Return values: This callback does not handle returns.

Gets called when an NPC gets spawned for the first time.

FCNPC_OnRespawn(npcid)

  • Parameters:
    • npcid: The ID of the NPC that respawned.
  • Return values: This callback does not handle returns.

Gets called when an NPC gets respawned.

FCNPC_OnDeath(npcid, killerid, reason)

  • Parameters:
    • npcid: The ID of the NPC that died.
    • killerid: The ID of the player that killed the NPC who died, or INVALID_PLAYER_ID if there was none.
    • reason: The ID of the reason/weapon for the player's death.
  • Return values: This callback does not handle returns.

Gets called when an NPC gets killed programmatically, or when an NPC gets killed by another player, or when an NPC gets killed by being inside an exploding vehicle.

FCNPC_OnUpdate(npcid)

  • Parameters:
    • npcid: The ID of the NPC that updated.
  • Return values:
    • 1: The update from this NPC will be sent to players.
    • 0: The update from this NPC will not be sent to players.
  • Notes:
    • The NPC has to be spawned and alive for this callback to be called.
    • This callback is called many times per second for each NPC. Only use it when you know what it's meant for (or more importantly what it's NOT meant for).
    • The frequency with which this callback is called for each NPC is determined by FCNPC_SetUpdateRate.

Gets called when an NPC gets updated by the plugin.

Survivability

FCNPC_OnTakeDamage(npcid, issuerid, Float:amount, weaponid, bodypart)

  • Parameters:
    • npcid: The ID of the NPC that took damage.
    • issuerid: The ID of the player or NPC that caused damage.
    • weaponid: The reason that caused damage.
    • Float:amount: The amount of health/armour the npcid has lost (combined).
    • bodypart: The body part that was hit.
  • Return values:
    • 1: The NPC will receive the damage.
    • 0: The NPC will not receive the damage.
  • Notes:
    • The amount is always the maximum damage the weaponid can do, even when the health left is less than that maximum damage. So when an NPC has 100.0 health and gets shot with a Desert Eagle which has a damage value of 46.2, it takes 3 shots to kill that NPC. All 3 shots will show an amount of 46.2, even though when the last shot hits, the NPC only has 7.6 health left. This is conform with OnPlayerTakeDamage.
    • See this wiki page for some exeptions regarding the weaponid.
    • When a player is in a different interior than an NPC, the NPC is still visible and can thus also take damage from that player.
    • This callback is not called when the NPC is invulnerable.

Gets called when an NPC takes damage from a player or other NPC.

FCNPC_OnGiveDamage(npcid, damagedid, Float:amount, weaponid, bodypart)

  • Parameters:
    • npcid: The ID of the NPC that gave damage.
    • damagedid: The ID of the player or NPC that received damage.
    • Float:amount: The amount of health/armour the damagedid has lost (combined).
    • weaponid: The reason that caused damage.
    • bodypart: The body part that was hit.
  • Return values: This callback does not handle returns.
  • Notes:
    • The amount is always the maximum damage the weaponid can do, even when the health left is less than that maximum damage. So when an NPC has 100.0 health and gets shot with a Desert Eagle which has a damage value of 46.2, it takes 3 shots to kill that NPC. All 3 shots will show an amount of 46.2, even though when the last shot hits, the NPC only has 7.6 health left. This is conform with OnPlayerGiveDamage.
    • See this wiki page for some exeptions regarding the weaponid.
    • When a player is in a different interior than an NPC, the NPC is still visible and can thus also deal damage to that player.

Gets called when an NPC gives damage to a player or other NPC.

Movement

FCNPC_OnReachDestination(npcid)

  • Parameters:
    • npcid: The ID of the NPC that reached his destination.
  • Return values: This callback does not handle returns.
  • Notes:
    • This callback is not called when FCNPC_Stop is used.

Gets called when an NPC reaches his FCNPC_GoTo or FCNPC_GoToPlayer destination, or when an NPC goes to enter a vehicle, it has moved when he reaches the position the vehicle should be at.

Weapons

FCNPC_OnWeaponShot(npcid, weaponid, hittype, hitid, Float:fX, Float:fY, Float:fZ)

  • Parameters:
    • npcid: The ID of the NPC that shot a weapon.
    • weaponid: The ID of the weapon shot by the NPC.
    • hittype: The type of thing the shot hit.
    • hitid: The ID of the thing that was hit.
    • Float:fX: The X coordinate that the shot hit.
    • Float:fY: The Y coordinate that the shot hit.
    • Float:fZ: The Z coordinate that the shot hit.
  • Return values:
    • 1: The shot from this NPC will cause damage.
    • 0: The shot from this NPC will not cause damage.
  • Notes:

Gets called when an NPC fires a shot from a weapon, or when FCNPC_TriggerWeaponShot is called.

FCNPC_OnWeaponStateChange(npcid, weapon_state)

  • Parameters:
    • npcid: The ID of the NPC that changed weapon state.
    • weapon_state: The new weapon state.
  • Return values: This callback does not handle returns.
  • Notes:
    • This callback is not called when the weapon state changes to WEAPONSTATE_UNKNOWN.

Gets called when an NPC changes weapon state or when FCNPC_SetWeaponState is called.

Streaming

FCNPC_OnStreamIn(npcid, forplayerid)

  • Parameters:
    • npcid: The ID of the NPC that streamed in.
    • forplayerid: The ID of the player that streamed the NPC in.
  • Return values: This callback does not handle returns.
  • Notes:
    • NPCs can't stream each other, only players can stream NPCs.

Gets called when an NPC is streamed in by a player.

FCNPC_OnStreamOut(npcid, forplayerid)

  • Parameters:
    • npcid: The ID of the NPC that streamed out.
    • forplayerid: The ID of the player that streamed the NPC out.
  • Return values: This callback does not handle returns.
  • Notes:
    • NPCs can't stream each other, only players can stream NPCs.

Gets called when an NPC is streamed out by a player.

Vehicles

FCNPC_OnVehicleEntryComplete(npcid, vehicleid, seatid)

  • Parameters:
    • npcid: The ID of the NPC that entered a vehicle.
    • vehicleid: The ID of the vehicle that the NPC entered.
    • seatid: The ID of the seat of that vehicle.
  • Return values: This callback does not handle returns.
  • Notes:

Gets called when an NPC enters a vehicle.

FCNPC_OnVehicleExitComplete(npcid, vehicleid)

  • Parameters:
    • npcid: The ID of the NPC that exited a vehicle.
    • vehicleid: The ID of the vehicle that the NPC exited.
  • Return values: This callback does not handle returns.
  • Notes:

Gets called when an NPC exits a vehicle.

FCNPC_OnVehicleTakeDamage(npcid, issuerid, vehicleid, Float:amount, weaponid, Float:fX, Float:fY, Float:fZ)

  • Parameters:
    • npcid: The ID of the NPC whose vehicle took damage.
    • issuerid: The ID of the player or NPC that caused damage.
    • vehicleid: The ID of the NPC's vehicle that took damage.
    • Float:amount: The amount of health the vehicleid has lost.
    • weaponid: The reason that caused damage.
    • Float:fX: The X coordinate that the shot hit.
    • Float:fY: The Y coordinate that the shot hit.
    • Float:fZ: The Z coordinate that the shot hit.
  • Return values:
    • 1: The NPC's vehicle will receive the damage.
    • 0: The NPC's vehicle will not receive the damage.
  • Notes:
    • The amount is always the maximum damage the weaponid can do, even when the health left is less than that maximum damage. So when a vehicle has 1000.0 health and gets shot with a Desert Eagle which has a damage value of 46.2, it takes 22 shots to kill that vehicle. All 22 shots will show an amount of 46.2, even though when the last shot hits, the vehicle only has 29.8 health left. This is conform with OnPlayerTakeDamage.
    • Lag compensation has to be enabled in server.cfg if not done already. Otherwise NPC vehicle damage will not work and this callback will not be called.
    • When a player is in a different interior than an NPC, the NPC's vehicle can still take damage from that player.
    • This callback will still be called when the NPC is invulnerable.

Gets called when an NPC's vehicle that that NPC is driving takes damage from a player or other NPC.

Playback

Playback or recording files are .rec files containing information regarding various player actions, including movement. The plugin can utilise these files to let an NPC reproduce these actions, in the same way standard NPCs can. To learn more about recording such a file, see the SA-MP native StartRecordingPlayerData. The files should be put in the npcmodes/recordings folder. To learn more about recording files and their structure, see this page on the SA-MP wiki.

FCNPC_OnFinishPlayback(npcid)

  • Parameters:
    • npcid: The ID of the NPC that finished playback.
  • Return values: This callback does not handle returns.

Gets called when an NPC finishes playing back a recording file, or when FCNPC_StopPlayingPlayback is called, or when an NPC gets destroyed, or when an NPC gets killed programatically or via damage, or when an NPC starts playing a node.

Nodes

Nodes are .dat files containing information regarding ped on foot and vehicle paths. They are used by the game to let peds walk and drive on roads. The plugin can utilise these files to let an NPC move on the same paths from the game. The needed files are included in the download and should be put in the scriptfiles/FCNPC/nodes folder. To learn more about nodes and their structure, see this page on the GTAModding wiki.

FCNPC_OnFinishNode(npcid, nodeid)

  • Parameters:
    • npcid: The ID of the NPC that finished playing a node.
    • nodeid: The ID of the node that the NPC finished playing.
  • Return values: This callback does not handle returns.

Gets called when an NPC finishes playing a complete node file, or when FCNPC_StopPlayingNode is called, or when an NPC gets destroyed, or when an NPC gets killed programatically or via damage, or when an NPC starts playing another node, or when FCNPC_OnFinishNodePoint returns 0, or when FCNPC_OnChangeNode returns 0, or when the plugin can't find a new node for the NPC to play.

FCNPC_OnFinishNodePoint(npcid, nodeid, pointid)

  • Parameters:
    • npcid: The ID of the NPC that passed a point in a node.
    • nodeid: The ID of the node that the NPC passed a point of.
    • pointid: The ID of the point in the node that the NPC passed.
  • Return values:
    • 1: The NPC will continue playing the node.
    • 0: The NPC will stop playing the node.

Gets called when an NPC passes a point in a node.

FCNPC_OnChangeNode(npcid, newnodeid, oldnodeid)

  • Parameters:
    • npcid: The ID of the NPC that is about to change nodes.
    • newnodeid: The ID of the new node that the NPC is about to change to.
    • oldnodeid: The ID of the old node that the NPC is about to change from.
  • Return values:
    • 1: The NPC will start playing the new node.
    • 0: The NPC will stop playing any nodes.
  • Notes:
    • When an NPC is at the end of a node, the plugin will try to find a new node for him to play and thus change to that new node.

Gets called when an NPC is about to change nodes.

Move Paths

Move paths are a sequence of coordinates that an NPC can move along. With normal movement, you can move an NPC from his current position to point A. Using move paths, you can move an NPC from his current position to point A, then from point A to point B, then from point B to point C, and so on.

FCNPC_OnFinishMovePath(npcid, pathid)

  • Parameters:
    • npcid: The ID of the NPC that finished moving along a move path.
    • pathid: The ID of the move path that the NPC finished moving along.
  • Return values: This callback does not handle returns.

Gets called when an NPC finishes moving along a complete move path, or when FCNPC_OnFinishMovePathPoint returns 0.

FCNPC_OnFinishMovePathPoint(npcid, pathid, pointid)

  • Parameters:
    • npcid: The ID of the NPC that passed a point in a move path.
    • pathid: The ID of the move path that the NPC passed a point of.
    • pointid: The ID of the point in the move path that the NPC passed.
  • Return values:
    • 1: The NPC will continue moving along the move path.
    • 0: The NPC will stop moving along the move path.

Gets called when an NPC passes a point in a move path.

MapAndreas & ColAndreas

FCNPC_OnChangeHeightPos(npcid, Float:newz, Float:oldz)

  • Parameters:
    • npcid: The ID of the NPC that changed height position.
    • Float:new_z: The new height position of the NPC.
    • Float:old_z: The old height position of the NPC.
  • Return values:
    • 1: The NPC will change height position.
    • 0: The NPC will not change height position and remain at the current height position.
  • Notes:

Gets called when an NPC changes height position while moving, or when an NPC changes height position while under the influence of a velocity change.

Wiki written by Freaksken.

Clone this wiki locally