Skip to content

NPC Component Documentation#1137

Merged
AmyrAhmady merged 58 commits intoopenmultiplayer:masterfrom
itsneufox:NPC-Documentation
Dec 17, 2025
Merged

NPC Component Documentation#1137
AmyrAhmady merged 58 commits intoopenmultiplayer:masterfrom
itsneufox:NPC-Documentation

Conversation

@itsneufox
Copy link
Collaborator

@itsneufox itsneufox commented Aug 31, 2025 •
edited
Loading

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_IsSpawned
  • 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
  • NPC_SetVelocity
  • NPC_GetVelocity

Movement

  • NPC_Move
  • NPC_MoveToPlayer
  • NPC_StopMove
  • NPC_IsMoving
  • NPC_IsMovingToPlayer

Appearance

  • NPC_SetSkin
  • NPC_GetSkin
  • NPC_IsStreamedIn
  • NPC_IsAnyStreamedIn

Health / Armour / Invulnerability

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

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_SetWeaponState
  • NPC_Shoot
  • NPC_IsShooting
  • NPC_AimAt
  • NPC_AimAtPlayer
  • NPC_StopAim
  • NPC_IsAiming
  • NPC_IsAimingAtPlayer
  • NPC_GetPlayerAimingAt
  • NPC_GetPlayerMovingTo
  • NPC_SetWeaponAccuracy
  • NPC_GetWeaponAccuracy
  • NPC_SetWeaponReloadTime
  • NPC_GetWeaponReloadTime
  • NPC_GetWeaponActualReloadTime
  • NPC_SetWeaponShootTime
  • NPC_GetWeaponShootTime
  • NPC_SetWeaponClipSize
  • NPC_GetWeaponClipSize
  • NPC_GetWeaponActualClipSize
  • NPC_SetWeaponSkillLevel
  • NPC_GetWeaponSkillLevel

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_SetSurfingOffsets
  • NPC_GetSurfingOffsets
  • 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

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

@itsneufox itsneufox requested a review from a team as a code owner August 31, 2025 16:23
@itsneufox
Copy link
Collaborator Author

itsneufox commented Aug 31, 2025

To any team member: don't merge it yet

@itsneufox
Copy link
Collaborator Author

itsneufox commented Sep 5, 2025 •
edited
Loading

TODO: Add deprecation notice on ConnectNPC

@itsneufox
Copy link
Collaborator Author

itsneufox commented Sep 8, 2025

Missing manual review by someone and nodes documentation

itsneufox and others added 12 commits September 8, 2025 08:57
@itsneufox
- begone magic numbers (thx TommyB)
74ffe85 
- better comments in some things
@itsneufox
Add npc-constants.md
a3468be
@AmyrAhmady
remove nonexisting npc callbacks
096bdfc
@AmyrAhmady
grammatical changes, example fixes, content changes
cad0f7f
@AmyrAhmady
NPC node docs
86f2b4f
@AmyrAhmady
add GetVehicleRotation
b7c03ee
@itsneufox
Remove reference to non-existing NPC callback in NPC_SetRot documenta…
9ab0630 
…tion
@itsneufox
Remove references to non-existing NPC callbacks in NPC_SetFacingAngle…
76545b6 
… and NPC_SetSpecialAction documentation
@itsneufox
Remove references to non-existing NPC callbacks in various documentat…
5777a79 
…ion files
@itsneufox
Remove references to non-existing NPC callbacks in NPC_IsStreamedIn a…
f07ae51 
…nd NPC_SetSkin documentation

thanks eggy
@itsneufox
Fix param names and other small stuff
5f6a8de
@itsneufox
Remove note about NPC pathfinding
196440e
@itsneufox
Copy link
Collaborator Author

itsneufox commented Sep 9, 2025 •
edited
Loading

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

@itsneufox
Copy link
Collaborator Author

itsneufox commented Oct 24, 2025

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

@itsneufox
GetArmout and GetCurrentPathPointIndex
01d96b7
@itsneufox
fix some stuff and add more documentation
7a8f948
@itsneufox
fix some issues
761a0ee
@itsneufox
add GetRot, GetSpecialAction, GetSurfingObject, GetSurfingOffsets, Ge…
575de39 
…tSurfingPlayerObject, GetSurfingVehicle, GetVehicle, GetVehicleGearState
@itsneufox
update Related Functions
d42bb25
@itsneufox
removed:
a8a1086 
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
@itsneufox
finish all Get funcs
d240922
@itsneufox
going thru some more documentation
8a6c970
@dockfries
Copy link
Contributor

dockfries commented Nov 5, 2025 •
edited
Loading

last commit
NPC_IsSpawned example error, same as NPC_IsShooting
NPC_PausePlayback example error, same as NPC_OpenNode

@itsneufox
Copy link
Collaborator Author

itsneufox commented Nov 5, 2025

last commit NPC_IsSpawned example error, same as NPC_IsShooting NPC_PausePlayback example error, same as NPC_OpenNode

dunno where's the error, works fine here, can you tell me what are the errors?
https://github.com/itsneufox/NPC-bare-test-omp-gamemode

https://youtu.be/LLA9Qy6KHgo

@dockfries
Copy link
Contributor

dockfries commented Nov 6, 2025 •
edited
Loading

Sorry, I meant that the content of the examples sections of these two markdown files was incorrect, not that there was an error in the gamemode code.

NPC_IsSpawned should use "/checkspawned" instead of "/checkshooting".
NPC_PausePlayback should not use "/npcopennode".

@itsneufox
Copy link
Collaborator Author

itsneufox commented Nov 6, 2025

Sorry, I meant that the content of the examples sections of these two markdown files was incorrect, not that there was an error in the gamemode code.

NPC_IsSpawned should use "/checkspawned" instead of "/checkshooting". NPC_PausePlayback should not use "/npcopennode".

@dockfries thanks, now i understood, sorry! It's fixed

thanks for the heads up!

@itsneufox
Copy link
Collaborator Author

itsneufox commented Nov 7, 2025

Done.

@NexiusTailer
Copy link
Contributor

NexiusTailer commented Nov 23, 2025 •
edited
Loading

Just wanted to say it's a great job already done, but I also remembered about a couple of articles which probably will need to be a bit edited too.

Namely this one:

web/frontend/docs/server/Installation.md

Line 5 in 4323fb1

If you are using the FCNPC plugin, please stop for now because this plugin does not work for open.mp currently.

and this one too:

web/frontend/docs/server/LinuxServerInstallation.md

Line 12 in 4323fb1

If you are using the FCNPC plugin, please stop for now because this plugin does not work for open.mp currently.

Since there will be some porting guide from FCNPC to native omp NPCs, these lines may probably be changed with some link on this tutorial or something similar.

@itsneufox
Copy link
Collaborator Author

itsneufox commented Dec 1, 2025 •
edited
Loading

Just wanted to say it's a great job already done, but I also remembered about a couple of articles which probably will need to be a bit edited too.

Namely this one:

web/frontend/docs/server/Installation.md

Line 5 in 4323fb1

If you are using the FCNPC plugin, please stop for now because this plugin does not work for open.mp currently.

and this one too:

web/frontend/docs/server/LinuxServerInstallation.md

Line 12 in 4323fb1

If you are using the FCNPC plugin, please stop for now because this plugin does not work for open.mp currently.

Since there will be some porting guide from FCNPC to native omp NPCs, these lines may probably be changed with some link on this tutorial or something similar.

Thanks!
I added a new message, when a conversion guide or wrapper exists, someone or i can update it again and add a link.

@AmyrAhmady AmyrAhmady merged commit a668c4a into openmultiplayer:master Dec 17, 2025
1 check passed
@AmyrAhmady AmyrAhmady deleted the NPC-Documentation branch December 17, 2025 10:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@itsneufox @dockfries @NexiusTailer @AmyrAhmady @edgyaf