SetNpcRoute

setNpcRoute

IMPROVED FROM UPDATE 0.1.2

This function is available in earlier releases and has corrected or expanded behavior in G1R:MP 0.1.2 and later. The contract below describes the updated behavior.

Assigns an ordered, optionally looping movement route to a resource-owned NPC.

Syntax

bool setNpcRoute(int npcId, table points [, table options])

Parameters

Name	Type	Required	Description
npcId	int	yes	The server-assigned NPC identifier returned by spawnNpc or getNpcs.
points	table	yes	A one-based array of 1-1024 points. Every point has x, y and z in metres and may have yaw in degrees and waitMs from 0 to 3600000.
options	table	no	Optional { loop = bool, speed = number, obstacleBehavior = string }; speed is 0.1-12 metres per second and defaults to 1. Available since update 0.1.2, obstacleBehavior accepts "wait" or "avoid". When omitted, the NPC keeps its current mode; a newly spawned NPC starts in "wait" mode.

Returns

Returns true when the complete route is validated and started; otherwise returns false.

Examples

Patrol between two guard posts:

setNpcRoute(npcId, {
    { x = 10, y = 5, z = 2, yaw = 90, waitMs = 1500 },
    { x = 18, y = 5, z = 2, yaw = 270, waitMs = 1500 },
}, { loop = true, speed = 1.8, obstacleBehavior = "avoid" })

Notes

• Available only in server-side resource scripts.
• Movement is simulated by the server and replicated as normal smoothed remote snapshots.
• Every ground route leg is resolved through the conservative server navigation-blocker layer. An unreachable route is rejected; movement never falls back to the authored straight line through a blocker.
• Dynamic capsule spacing keeps NPCs separate from players, monsters and other NPCs. It never permits an NPC to pass through another character.
• The obstacleBehavior option is available since update 0.1.2. Its default "wait" mode stops the NPC until a blocking dynamic capsule clears. "avoid" attempts a safe detour and continues toward the waypoint, falling back to waiting when no valid detour exists.
• Route progress emits onNpcRoutePoint and non-looping completion emits onNpcRouteComplete.
• Expanded limits apply from update 0.1.3 BUILD81. See Scripting limits; earlier 0.1.3 binaries retain their old limits.