NPC Component Documentation

[itsneufox]

This PR adds documentation for the NPC component.

The open.mp branch for beta testing can be found here:
openmultiplayer/open.mp#916

Bugs while testing? Report them here: openmultiplayer/open.mp#1134

A test gamemode built using the wiki snippets is available here:
https://github.com/itsneufox/NPC-bare-test-omp-gamemode

The goal is for the NPCs wiki code to be fully reusable so anyone can copy and paste it on the gamemode with minimal effort

Core / Lifecycle

• NPC_Create
• NPC_Destroy
• NPC_IsValid
• NPC_IsDead
• NPC_Spawn
• NPC_Respawn
• NPC_GetAll

Position / Rotation / World

• NPC_SetPos
• NPC_GetPos
• NPC_SetRot
• NPC_GetRot
• NPC_SetFacingAngle
• NPC_GetFacingAngle
• NPC_SetVirtualWorld
• NPC_GetVirtualWorld
• NPC_SetInterior
• NPC_GetInterior

Movement

• NPC_Move
• NPC_MoveToPlayer
• NPC_StopMove
• NPC_IsMoving

Appearance

• NPC_SetSkin
• NPC_IsStreamedIn
• NPC_IsAnyStreamedIn

Health / Armour / Invulnerability

• NPC_SetHealth
• NPC_GetHealth
• NPC_SetArmour
• NPC_GetArmour
• NPC_SetInvulnerable
• NPC_IsInvulnerable

Weapons / Combat

• NPC_SetWeapon
• NPC_GetWeapon
• NPC_SetAmmo
• NPC_GetAmmo
• NPC_SetAmmoInClip
• NPC_GetAmmoInClip
• NPC_SetKeys
• NPC_GetKeys
• NPC_MeleeAttack
• NPC_StopMeleeAttack
• NPC_IsMeleeAttacking
• NPC_SetFightingStyle
• NPC_GetFightingStyle
• NPC_EnableReloading
• NPC_IsReloadEnabled
• NPC_IsReloading
• NPC_EnableInfiniteAmmo
• NPC_IsInfiniteAmmoEnabled
• NPC_GetWeaponState
• NPC_Shoot
• NPC_IsShooting
• NPC_AimAt
• NPC_AimAtPlayer
• NPC_StopAim
• NPC_IsAiming
• NPC_IsAimingAtPlayer
• NPC_SetWeaponAccuracy
• NPC_GetWeaponAccuracy
• NPC_SetWeaponReloadTime
• NPC_GetWeaponReloadTime
• NPC_GetWeaponActualReloadTime
• NPC_SetWeaponShootTime
• NPC_GetWeaponShootTime
• NPC_SetWeaponClipSize
• NPC_GetWeaponClipSize
• NPC_GetWeaponActualClipSize

Vehicle

• NPC_EnterVehicle
• NPC_ExitVehicle
• NPC_PutInVehicle
• NPC_RemoveFromVehicle
• NPC_GetVehicle
• NPC_GetVehicleID
• NPC_GetVehicleSeat
• NPC_GetEnteringVehicle
• NPC_GetEnteringVehicleID
• NPC_GetEnteringVehicleSeat
• NPC_IsEnteringVehicle
• NPC_UseVehicleSiren
• NPC_IsVehicleSirenUsed
• NPC_SetVehicleHealth
• NPC_GetVehicleHealth
• NPC_SetVehicleHydraThrusters
• NPC_GetVehicleHydraThrusters
• NPC_SetVehicleGearState
• NPC_GetVehicleGearState
• NPC_SetVehicleTrainSpeed
• NPC_GetVehicleTrainSpeed

Animations

• NPC_ResetAnimation
• NPC_SetAnimation
• NPC_GetAnimation
• NPC_ApplyAnimation
• NPC_ClearAnimations
• NPC_SetSpecialAction
• NPC_GetSpecialAction

Playback / Records

• NPC_StartPlayback
• NPC_StartPlaybackEx
• NPC_StopPlayback
• NPC_PausePlayback
• NPC_IsPlayingPlayback
• NPC_IsPlaybackPaused
• NPC_LoadRecord
• NPC_UnloadRecord
• NPC_IsValidRecord
• NPC_GetRecordCount
• NPC_UnloadAllRecords

Surfing

• NPC_SetSurfingOffset
• NPC_GetSurfingOffset
• NPC_SetSurfingVehicle
• NPC_GetSurfingVehicle
• NPC_SetSurfingObject
• NPC_GetSurfingObject
• NPC_SetSurfingPlayerObject
• NPC_GetSurfingPlayerObject
• NPC_ResetSurfingData

Paths

• NPC_CreatePath
• NPC_DestroyPath
• NPC_DestroyAllPath
• NPC_GetPathCount
• NPC_AddPointToPath
• NPC_RemovePointFromPath
• NPC_ClearPath
• NPC_GetPathPointCount
• NPC_GetPathPoint
• NPC_IsValidPath
• NPC_GetCurrentPathPointIndex
• NPC_MoveByPath
• NPC_HasPathPointInRange

Nodes

• NPC_OpenNode
• NPC_CloseNode
• NPC_IsNodeOpen
• NPC_GetNodeType
• NPC_SetNodePoint
• NPC_GetNodePointPosition
• NPC_GetNodePointCount
• NPC_GetNodeInfo
• NPC_PlayNode
• NPC_StopPlayingNode
• NPC_PausePlayingNode
• NPC_ResumePlayingNode
• NPC_IsPlayingNode
• NPC_ChangeNode
• NPC_IsPlayingNodePaused
• NPC_UpdateNodePoint

Callbacks / Events

• OnNPCCreate
• OnNPCDestroy
• OnNPCSpawn
• OnNPCRespawn
• OnNPCWeaponStateChange
• OnNPCTakeDamage
• OnNPCGiveDamage
• OnNPCDeath
• OnNPCPlaybackStart
• OnNPCPlaybackEnd
• OnNPCWeaponShot
• OnNPCFinishMove
• OnNPCFinishNodePoint
• OnNPCFinishNode
• OnNPCChangeNode
• OnNPCFinishMovePath
• OnNPCFinishMovePathPoint

[itsneufox]

To any team member: don't merge it yet

[itsneufox]

TODO: Add deprecation notice on ConnectNPC

[itsneufox]

Missing manual review by someone and nodes documentation

[itsneufox]

TODO:
- return values in vehicle related natives are wrong (0 instead of INVALID_VEHICLE_ID)
- Check seats ids

[dockfries]

NPC_StartPlayback may usually specify the filename directly without suffix .rec, = npcmodes/recordings/${fileName}.rec
NPC_StartPlaybackEx with recordId can specify a complete path without suffix .rec? = npcmodes/recordings/${filePath+fileName}.rec. I'm not sure, I may wrong.

NPC_LoadRecord has a similar path problem.

https://github.com/openmultiplayer/open.mp/blob/b876feb66a7b8be4081125e873eb6657ac26109c/Server/Components/NPCs/NPC/npc.cpp#L91

For some deleted documents, links to other related should be removed, for example, OnNPCDisconnect should be changed to OnNPCDestroy etc..

callbacks/**/*.md ---> Related Functions error link, should be ../functions/***
function/**/*.md ---> Related Callbacks error link, should be ../callbacks/***

GetVehicleRotation.md -> Related funtions -> GetVehicleRotation -> GetVehicleRotationQuat.

All files need be format like prettier.

OnNPCEnter/ExitVehicle has been deleted, so NPC_ResetSurfingData need update, btw, are these two callbacks no longer available or missing?

---

What about some past APIs? Do those need to be changed or deleted?
For example, GetMyFacingAngle, GetMyPos, OnClientMessage, StartRecordingPlayback, StopRecordingPlayback, etc.

Dont forget global replace <VersionWarn version='omp v1.1.0.changemelater' /> after new version released.

[itsneufox]

thanks @dockfries

[itsneufox]

Ready to review:

NPC_AimAt.md
NPC_AimAtPlayer.md
NPC_ApplyAnimation.md
NPC_ClearAnimations.md
NPC_Create.md
NPC_EnableInfiniteAmmo.md
NPC_EnableReloading.md
NPC_Spawn.md

In case testing is needed, the gamemode is here with those functions implemented:
https://github.com/itsneufox/NPC-bare-test-omp-gamemode

[itsneufox]

Ready to review:

NPC_AddPointToPath.md
NPC_ClearPath.md
NPC_CreatePath.md
NPC_Destroy.md
NPC_DestroyAllPath.md
NPC_DestroyPath.md
NPC_EnterVehicle.md
NPC_ExitVehicle.md
NPC_GetAll.md
NPC_MoveByPath.md

In case testing is needed, the gamemode with all these functions implemented is here:
https://github.com/itsneufox/NPC-bare-test-omp-gamemode

[itsneufox]

Ready to review:

NPC_GetAmmo.md
NPC_GetAmmoInClip.md
NPC_GetAnimation.md
NPC_GetArmour.md

In case testing is needed, the gamemode with all these functions implemented is here:
https://github.com/itsneufox/NPC-bare-test-omp-gamemode