SetNpcRoute: Difference between revisions
Jump to navigation
Jump to search
Complete Lua function catalog |
Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81 |
||
| (One intermediate revision by the same user not shown) | |||
| Line 1: | Line 1: | ||
= setNpcRoute = | = setNpcRoute = | ||
<div style="background:#fff5f5; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111111; padding:0.85rem 1rem; margin:0.75rem 0 1rem;"> | |||
<div style="color:#111111; font-weight:bold; letter-spacing:0.04em;">IMPROVED FROM UPDATE 0.1.2</div> | |||
<div style="color:#111111; margin-top:0.25rem;">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.</div> | |||
</div> | |||
Assigns an ordered, optionally looping movement route to a resource-owned NPC. | Assigns an ordered, optionally looping movement route to a resource-owned NPC. | ||
| Line 14: | Line 18: | ||
| <code>npcId</code> || <code>int</code> || yes || The server-assigned NPC identifier returned by <code>spawnNpc</code> or <code>getNpcs</code>. | | <code>npcId</code> || <code>int</code> || yes || The server-assigned NPC identifier returned by <code>spawnNpc</code> or <code>getNpcs</code>. | ||
|- | |- | ||
| <code>points</code> || <code>table</code> || yes || A one-based array of 1- | | <code>points</code> || <code>table</code> || 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. | ||
|- | |- | ||
| <code>options</code> || <code>table</code> || no || Optional <code>{ loop = bool, speed = number }</code>; speed is 0.1-12 metres per second and defaults to 1. | | <code>options</code> || <code>table</code> || no || Optional <code>{ loop = bool, speed = number, obstacleBehavior = string }</code>; speed is 0.1-12 metres per second and defaults to 1. Available since update 0.1.2, <code>obstacleBehavior</code> accepts <code>"wait"</code> or <code>"avoid"</code>. When omitted, the NPC keeps its current mode; a newly spawned NPC starts in <code>"wait"</code> mode. | ||
|} | |} | ||
| Line 28: | Line 32: | ||
{ x = 10, y = 5, z = 2, yaw = 90, waitMs = 1500 }, | { x = 10, y = 5, z = 2, yaw = 90, waitMs = 1500 }, | ||
{ x = 18, y = 5, z = 2, yaw = 270, waitMs = 1500 }, | { x = 18, y = 5, z = 2, yaw = 270, waitMs = 1500 }, | ||
}, { loop = true, speed = 1.8 }) | }, { loop = true, speed = 1.8, obstacleBehavior = "avoid" }) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| Line 34: | Line 38: | ||
* Available only in server-side resource scripts. | * Available only in server-side resource scripts. | ||
* Movement is simulated by the server and replicated as normal smoothed remote snapshots. | * 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 <code>obstacleBehavior</code> option is available since update 0.1.2. Its default <code>"wait"</code> mode stops the NPC until a blocking dynamic capsule clears. <code>"avoid"</code> attempts a safe detour and continues toward the waypoint, falling back to waiting when no valid detour exists. | |||
* Route progress emits <code>onNpcRoutePoint</code> and non-looping completion emits <code>onNpcRouteComplete</code>. | * Route progress emits <code>onNpcRoutePoint</code> and non-looping completion emits <code>onNpcRouteComplete</code>. | ||
* Expanded limits apply from update 0.1.3 BUILD81. See [[Scripting limits]]; earlier 0.1.3 binaries retain their old limits. | |||
[[Category:Lua Functions]] | [[Category:Lua Functions]] | ||
Latest revision as of 11:51, 12 September 2026
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
obstacleBehavioroption 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
onNpcRoutePointand non-looping completion emitsonNpcRouteComplete. - Expanded limits apply from update 0.1.3 BUILD81. See Scripting limits; earlier 0.1.3 binaries retain their old limits.