NPCs

Group npcs · 18 exports · from forks/gamexueren/scripthook.h (framework 1.0-beta7-wildm1, SH_API_VERSION 2)

Standalone NPCs by archetype, built like the engine's spawn director does (FINDINGS "NPC SPAWN WORKS").

Export	Summary
ShNpcCount	The archetype registry, read once per session on first use.
ShNpcAt	See ShNpcCount.
ShSpawnNpc	The NPC joins the population manager with the current Camp and Job, so its AI runs like a native spawn.
ShDespawn	Retire a spawned entity, NPC or vehicle, through the spawn manager.
ShNpcGroupCount	SH_NPC_GROUP_MAX.
ShNpcGroupName	"Santa Blanca", "Unidad", "Rebels", "Civilians", "Special", or "" for a group out of range.
ShNpcGroupOfArchetype	The group an archetype belongs to, or -1 for a kind no group claims (kinds 0..7 are the ones that do; see the note above).
ShNpcGroupOf	The same, looked up by id: walks the catalogue, so the first call waits for the registry like ShNpcCount does.
ShNpcGroupSize	How many archetypes the group holds.
ShNpcAtInGroup	The index-th archetype of a group, 0 based, as the group is walked.
ShNpcPlanFormation	Lay a formation out, and only that: no engine call, no lane to the game thread, and z is origin's own.
ShNpcSpawnFormation	Spawn a whole batch and wait for it.
ShNpcSpawnBegin	The same batch on a worker thread of the API's own, with a handle to poll.
ShNpcSpawnPoll	The entities a job has produced so far, copied into out, up to maxOut.
ShNpcSpawnCancel	Ask a job to stop.
ShNpcSpawnEnd	Free a job.
ShNpcSpawnSetLayout	Install the policy every later batch obeys, until it is replaced.
ShNpcSpawnGetLayout	Read back what is installed, all zero when nothing is.

ShNpcCount

SH_API int ShNpcCount(void);

The archetype registry, read once per session on first use. About 530 entries, about 150 of them kind 1.

scripthook.h, line 885

ShNpcAt

SH_API const ShNpcArchetype *ShNpcAt(int index);

Documented together with ShNpcCount just above.

scripthook.h, line 886

ShSpawnNpc

SH_API uint64_t ShSpawnNpc(uint64_t archetypeId, const ShVec3 *pos);

The NPC joins the population manager with the current Camp and Job, so its AI runs like a native spawn.

scripthook.h, line 892

ShDespawn

SH_API int ShDespawn(uint64_t entity);

Retire a spawned entity, NPC or vehicle, through the spawn manager. Entities built outside the spawn system have no spec and refuse.

Answers 1 only after the entity has been read back and is no longer in the spawn system. The retire address is the one pin in this build with no call site to confirm it, and on this build the call is accepted and does nothing: that case answers 0 with SH_ERR_NO_EFFECT, not 1.

scripthook.h, line 903

ShNpcGroupCount

SH_API int ShNpcGroupCount(void);

SH_NPC_GROUP_MAX.

scripthook.h, line 924

ShNpcGroupName

SH_API const char *ShNpcGroupName(int group);

"Santa Blanca", "Unidad", "Rebels", "Civilians", "Special", or "" for a group out of range. The faction names are the game's, and they are translation keys: pass them through ShLang.

scripthook.h, line 928

ShNpcGroupOfArchetype

SH_API int ShNpcGroupOfArchetype(const ShNpcArchetype *a);

The group an archetype belongs to, or -1 for a kind no group claims (kinds 0..7 are the ones that do; see the note above).

scripthook.h, line 932

ShNpcGroupOf

SH_API int ShNpcGroupOf(uint64_t archetypeId);

The same, looked up by id: walks the catalogue, so the first call waits for the registry like ShNpcCount does. -1 when no archetype carries that id.

scripthook.h, line 937

ShNpcGroupSize

SH_API int ShNpcGroupSize(int group);

How many archetypes the group holds. 0 for a group out of range or a catalogue that is not readable yet.

scripthook.h, line 941

ShNpcAtInGroup

SH_API int ShNpcAtInGroup(int group, int index, ShNpcArchetype *out);

The index-th archetype of a group, 0 based, as the group is walked. Fills out when it is not NULL. Returns that archetype's index in the whole catalogue, or -1 past the end.

scripthook.h, line 946

ShNpcPlanFormation

SH_API int ShNpcPlanFormation(int formation, int count, float distance,
                              const ShVec3 *origin, float yaw,
                              ShVec3 *out, int max);

Lay a formation out, and only that: no engine call, no lane to the game thread, and z is origin's own. The planning stays pure on purpose - a caller that wants the points as they are can have them - but ShNpcSpawnFormation does not spawn blind: each point is put on the ground with ShGroundHeightFrom first, so a batch stands on the terrain instead of at the player's own height. Writes up to max points, and at most SH_NPC_SPAWN_MAX. Returns how many were written, 0 on a bad argument. yaw is radians, world axes, x east y north z up.

scripthook.h, line 982

ShNpcSpawnFormation

SH_API int ShNpcSpawnFormation(const ShNpcSpawnRequest *req,
                               uint64_t *out, int maxOut);

Spawn a whole batch and wait for it. Fills out with the entities that appeared, up to maxOut and at most SH_NPC_SPAWN_MAX, and returns how many. The count is clamped to those limits rather than refused.

BLOCKING, and each NPC is waited on separately, so a batch of 50 can take a long time and the first spawn of a new archetype streams its assets in. NEVER call this from the game thread - a frame callback or a menu engine call - or from any thread the engine is waiting on: ShSpawnNpc waits for the physics pump, which runs on the game thread, and that would deadlock. Use ShNpcSpawnBegin from anywhere.

scripthook.h, line 1008

ShNpcSpawnBegin

SH_API uint32_t ShNpcSpawnBegin(const ShNpcSpawnRequest *req);

The same batch on a worker thread of the API's own, with a handle to poll. Returns a job id, 0 when no job is free or the thread could not be started.

scripthook.h, line 1014

ShNpcSpawnPoll

SH_API int ShNpcSpawnPoll(uint32_t job, uint64_t *out, int maxOut,
                          int *done);

The entities a job has produced so far, copied into out, up to maxOut. Returns how many there are, or -1 for a job id that is not live. done is set to 1 once the worker has stopped, whether it finished, failed or was cancelled. Safe to call while the job is still running.

scripthook.h, line 1021

ShNpcSpawnCancel

SH_API int ShNpcSpawnCancel(uint32_t job);

Ask a job to stop. The worker checks between NPCs, so a cancel lands within one spawn (a few seconds at worst); what it already produced stays readable through ShNpcSpawnPoll. Does not free the job - ShNpcSpawnEnd does. Safe, and a no-op, on a job that has already finished.

scripthook.h, line 1029

ShNpcSpawnEnd

SH_API int ShNpcSpawnEnd(uint32_t job);

Free a job. Refuses while it is still running, and asks it to stop first, so the caller polls until done and calls again. The job id is dead afterwards.

scripthook.h, line 1034

ShNpcSpawnSetLayout

SH_API int ShNpcSpawnSetLayout(const ShNpcSpawnLayout *layout);

Install the policy every later batch obeys, until it is replaced. NULL clears it, returning the batch to the request's own fields (and to the straight-ahead placement). Refuses a facing_mode that is not one of the enum's, and returns 0 there.

scripthook.h, line 1082

ShNpcSpawnGetLayout

SH_API int ShNpcSpawnGetLayout(ShNpcSpawnLayout *out);

Read back what is installed, all zero when nothing is.

scripthook.h, line 1085