NPC Component Documentation (#1137)

* NPC Callbacks

* Wrong bold format

* Mark ConnectNPC function as deprecated

* One Big Beautiful Commit for NPCs

* - begone magic numbers (thx TommyB)
- better comments in some things

* Add npc-constants.md

* remove nonexisting npc callbacks

* grammatical changes, example fixes, content changes

* NPC node docs

* add GetVehicleRotation

* Remove reference to non-existing NPC callback in NPC_SetRot documentation

* Remove references to non-existing NPC callbacks in NPC_SetFacingAngle and NPC_SetSpecialAction documentation

* Remove references to non-existing NPC callbacks in various documentation files

* Remove references to non-existing NPC callbacks in NPC_IsStreamedIn and NPC_SetSkin documentation

thanks eggy

* Fix param names and other small stuff

* Remove note about NPC pathfinding

* NPC gear docs were more confused than a pilot trying to land without landing gear

* - Teach NPCs that INVALID_VEHICLE_ID exists
- Add correct seat maps

* streamline example code for path creation

* add INVALID_OBJECT_ID to object related functions

* Update NPC_GetVehicle and NPC_GetVehicleID documentation and example code

* add INVALID_RECORD_ID

* mistake 🔏

* Add section for invalid constants, including INVALID_RECORD_ID

* General NPC docs improvements

* Add documentation for Path Nodes

* fix npc related callbacks and functions

* fix GetVehicleRotation related link GetVehicleRotationQuat

* fix npc_isValid, remove related OnNPCConnect/Disconnect

* maybe fix npc recording path

* npc and more docs prettier format

* replace OnNPCEnterVehicle with OnPlayerEnterVehicle

* deprecate or delete the following files?

* Make better snippets, fix some of the texts

* get all npcs, npc destroy, paths and enter/exit vehicles

* GetAmmo, GetAmmoInClip, GetAnimation, GetArmour

* GetArmout and GetCurrentPathPointIndex

* fix some stuff and add more documentation

* fix some issues

* add GetRot, GetSpecialAction, GetSurfingObject, GetSurfingOffsets, GetSurfingPlayerObject, GetSurfingVehicle, GetVehicle, GetVehicleGearState

* update Related Functions

* removed:
NPC_SetSurfingOffset.md
added:
NPC_SetSurfingOffsets.md
NPC_IsMovingToPlayer.md
NPC_IsSpawned.md
NPC_SetWeaponSkillLevel.md
NPC_GetPlayerAimingAt.md
NPC_GetPlayerMovingTo.md
NPC_GetSkin.md
NPC_GetVelocity.md
NPC_GetWeaponSkillLevel.md
NPC_Kill.md
NPC_SetVelocity.md
NPC_SetWeaponState.md
OnNPCFinishMovePathPoint.md

* finish all Get funcs

* going thru some more documentation

* almost there!!!

* fix mixed up examples

* all funcs done

* That's all Folks!

* forgor this file too

* fix some stuff i found while re-reading  the docs

* NPC_GetCustomSkin.md

* NPC_GetPosMovingTo.md

* improve fcnpc warnings, add missing frontmatter and also fix the linux guide

* wtf moment

* Add documentation for NPC_SetAngleToPlayer and NPC_SetAngleToPos functions

---------

Co-authored-by: iAmir <[email protected]>
Co-authored-by: edgy <[email protected]>
Co-authored-by: dockfries <[email protected]>

Author: 3 people

frontend/docs/scripting/callbacks/OnClientMessage.md

@@ -5,6 +5,12 @@ description: This callback gets called whenever the NPC sees a ClientMessage.
 tags: []
 ---
 
+:::warning
+
+This callback is deprecated.
+
+:::
+
 ## Description
 
 This callback gets called whenever the NPC sees a ClientMessage. This will be everytime a [SendClientMessageToAll](../functions/SendClientMessageToAll) function is used and everytime a [SendClientMessage](../functions/SendClientMessage) function is sent towards the NPC. This callback won't be called when someone says something. For a version of this with player text, see [NPC:OnPlayerText](OnPlayerText).

frontend/docs/scripting/callbacks/OnNPCChangeNode.md

@@ -0,0 +1,64 @@
+---
+title: OnNPCChangeNode
+sidebar_label: OnNPCChangeNode
+description: This callback is called when an NPC attempts to change from one navigation node to another during node-based movement.
+tags: ["npc", "node", "navigation"]
+---
+
+<VersionWarn version='omp v1.1.0.changemelater' />
+
+## Description
+
+This callback is called when an NPC attempts to change from one navigation node to another during node-based movement. This allows you to control whether the node change should be allowed or denied.
+
+| Name      | Description                                     |
+| --------- | ----------------------------------------------- |
+| npcid     | The ID of the NPC attempting to change nodes    |
+| newnodeid | The ID of the new node the NPC wants to move to |
+| oldnodeid | The ID of the current node the NPC is on        |
+
+## Returns
+
+Return `true` to allow the node change, or `false` to deny it.
+
+## Examples
+
+```c
+public OnNPCChangeNode(npcid, newnodeid, oldnodeid)
+{
+    printf("[NPC] NPC %d changed from node %d to node %d", npcid, oldnodeid, newnodeid);
+
+    // Notify players tracking this NPC
+    for (new playerid = 0; playerid < MAX_PLAYERS; playerid++)
+    {
+        if (!IsPlayerConnected(playerid))
+            continue;
+
+        if (PlayerNPC[playerid] == npcid)
+        {
+            SendClientMessage(playerid, 0x00FF00FF, "NPC %d changed from node %d to node %d", npcid, oldnodeid, newnodeid);
+        }
+    }
+    return 1;
+}
+```
+
+## Notes
+
+- This callback is only called when NPCs are using node-based navigation via `NPC_PlayNode`
+- Returning `false` will prevent the NPC from changing nodes and may cause it to stop navigation
+- Node files must be loaded using `NPC_OpenNode` before NPCs can navigate between them
+
+## Related Functions
+
+The following functions might be useful, as they're related to this callback in one way or another.
+
+- [NPC_PlayNode](../functions/NPC_PlayNode): Start NPC node-based navigation
+- [NPC_OpenNode](../functions/NPC_OpenNode): Open a navigation node file
+- [NPC_CloseNode](../functions/NPC_CloseNode): Close a navigation node file
+- [NPC_StopPlayingNode](../functions/NPC_StopPlayingNode): Stop NPC node navigation
+
+## Related Callbacks
+
+- [OnNPCFinishNode](OnNPCFinishNode): Called when NPC finishes navigating a complete node
+- [OnNPCFinishNodePoint](OnNPCFinishNodePoint): Called when NPC reaches a specific point in a node

frontend/docs/scripting/callbacks/OnNPCConnect.md

@@ -0,0 +1,53 @@
+---
+title: OnNPCCreate
+sidebar_label: OnNPCCreate
+description: This callback is called when an NPC is successfully created.
+tags: ["npc"]
+---
+
+<VersionWarn version='omp v1.1.0.changemelater' />
+
+## Description
+
+This callback is called when an NPC is successfully created and added to the server.
+
+| Name  | Description                        |
+| ----- | ---------------------------------- |
+| npcid | The ID of the NPC that was created |
+
+## Examples
+
+```c
+public OnNPCCreate(npcid)
+{
+    printf("[NPC] NPC %d has been created", npcid);
+
+    // Notify all connected players
+    for (new playerid = 0; playerid < MAX_PLAYERS; playerid++)
+    {
+        if (!IsPlayerConnected(playerid))
+            continue;
+
+        SendClientMessage(playerid, 0x00FF00FF, "NPC %d has been created", npcid);
+    }
+    return 1;
+}
+```
+
+## Notes
+
+- This callback is called immediately after the NPC is created but before it's spawned
+- The NPC will need to be spawned using `NPC_Spawn` to become visible in the game world
+
+## Related Functions
+
+The following functions might be useful, as they're related to this callback in one way or another.
+
+- [NPC_Create](../functions/NPC_Create): Create a new NPC
+- [NPC_Destroy](../functions/NPC_Destroy): Destroy an existing NPC
+- [NPC_Spawn](../functions/NPC_Spawn): Spawn the NPC in the game world
+
+## Related Callbacks
+
+- [OnNPCDestroy](OnNPCDestroy): Called when an NPC is destroyed
+- [OnNPCSpawn](OnNPCSpawn): Called when an NPC is spawned

frontend/docs/scripting/callbacks/OnNPCCreate.md

@@ -0,0 +1,68 @@
+---
+title: OnNPCDeath
+sidebar_label: OnNPCDeath
+description: This callback is called when an NPC dies.
+tags: ["npc"]
+---
+
+<VersionWarn version='omp v1.1.0.changemelater' />
+
+## Description
+
+This callback is called when an NPC dies.
+
+| Name     | Description                                                                 |
+| -------- | --------------------------------------------------------------------------- |
+| npcid    | The ID of the NPC that died                                                 |
+| killerid | The ID of the player/NPC that killed the NPC (or INVALID_PLAYER_ID if none) |
+| reason   | The reason for death (weapon ID or death cause)                             |
+
+## Examples
+
+```c
+public OnNPCDeath(npcid, killerid, WEAPON:reason)
+{
+    printf("[NPC] NPC %d died (killer: %d, weapon: %d)", npcid, killerid, _:reason);
+
+    // Notify players tracking this NPC
+    for (new playerid = 0; playerid < MAX_PLAYERS; playerid++)
+    {
+        if (!IsPlayerConnected(playerid))
+            continue;
+
+        if (PlayerNPC[playerid] == npcid)
+        {
+            if (killerid == INVALID_PLAYER_ID)
+            {
+                SendClientMessage(playerid, 0xFF0000FF, "Your tracked NPC %d died (weapon: %d)", npcid, _:reason);
+            }
+            else
+            {
+                SendClientMessage(playerid, 0xFF0000FF, "Your tracked NPC %d was killed by player %d (weapon: %d)", npcid, killerid, _:reason);
+            }
+        }
+    }
+    return 1;
+}
+```
+
+## Notes
+
+- The `killerid` parameter will be `INVALID_PLAYER_ID` if the NPC death was not player inflicted
+- The `reason` parameter contains the weapon ID that caused the death (255 for unknown/other causes)
+
+## Related Functions
+
+The following functions might be useful, as they're related to this callback in one way or another.
+
+- [NPC_Kill](../functions/NPC_Kill): Kill an NPC
+- [NPC_Respawn](../functions/NPC_Respawn): Respawn a dead NPC
+- [NPC_GetHealth](../functions/NPC_GetHealth): Get NPC's health
+- [NPC_SetHealth](../functions/NPC_SetHealth): Set NPC's health
+
+## Related Callbacks
+
+- [OnNPCSpawn](OnNPCSpawn): Called when an NPC spawns
+- [OnNPCRespawn](OnNPCRespawn): Called when an NPC respawns
+- [OnNPCTakeDamage](OnNPCTakeDamage): Called when an NPC takes damage
+- [OnPlayerDeath](OnPlayerDeath): Called when a player dies

frontend/docs/scripting/callbacks/OnNPCDeath.md

@@ -0,0 +1,61 @@
+---
+title: OnNPCDestroy
+sidebar_label: OnNPCDestroy
+description: This callback is called when an NPC is destroyed.
+tags: ["npc"]
+---
+
+<VersionWarn version='omp v1.1.0.changemelater' />
+
+## Description
+
+This callback is called when an NPC is destroyed and removed from the server.
+
+| Name  | Description                          |
+| ----- | ------------------------------------ |
+| npcid | The ID of the NPC that was destroyed |
+
+## Examples
+
+```c
+public OnNPCDestroy(npcid)
+{
+    printf("[NPC] NPC %d has been destroyed", npcid);
+
+    // Clear any player tracking this NPC and notify
+    for (new playerid = 0; playerid < MAX_PLAYERS; playerid++)
+    {
+        if (!IsPlayerConnected(playerid))
+            continue;
+
+        if (PlayerNPC[playerid] == npcid)
+        {
+            PlayerNPC[playerid] = INVALID_NPC_ID;
+            SendClientMessage(playerid, 0xFF0000FF, "Your tracked NPC %d has been destroyed", npcid);
+        }
+        else
+        {
+            SendClientMessage(playerid, 0xFFFF00FF, "NPC %d has been destroyed", npcid);
+        }
+    }
+    return 1;
+}
+
+```
+
+## Notes
+
+- This callback is called immediately before the NPC is removed from the server
+- The NPC will be disconnected and its player slot freed after this callback
+
+## Related Functions
+
+The following functions might be useful, as they're related to this callback in one way or another.
+
+- [NPC_Create](../functions/NPC_Create): Create a new NPC
+- [NPC_Destroy](../functions/NPC_Destroy): Destroy an existing NPC
+- [NPC_IsValid](../functions/NPC_IsValid): Check if NPC ID is valid
+
+## Related Callbacks
+
+- [OnNPCCreate](OnNPCCreate): Called when an NPC is created