SetNpcRoute - Revision history

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

2026-09-12T11:51:46Z

Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

← Older revision		Revision as of 11:51, 12 September 2026
Line 18:		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-~~256~~ points. Every point has x, y and z in metres and may have yaw in degrees and waitMs from 0 to 3600000.		\| <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, 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.		\| <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 42:		Line 42:
	* 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.		* 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]]

QCherry: Document Lua APIs available or improved from G1R:MP 0.1.2

2026-09-03T18:40:33Z

Document Lua APIs available or improved from G1R:MP 0.1.2

← Older revision		Revision as of 18:40, 3 September 2026
Line 1:		Line 1:
	~~<!-- This page is generated automatically from the function definition: setNpcRoute. -->~~
	= 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 16:		Line 20:
	\| <code>points</code> \|\| <code>table</code> \|\| yes \|\| A one-based array of 1-256 points. Every point has x, y and z in metres and may have yaw in degrees and waitMs from 0 to 3600000.		\| <code>points</code> \|\| <code>table</code> \|\| yes \|\| A one-based array of 1-256 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>.

QCherry: Complete Lua function catalog

2026-08-15T09:55:10Z

Complete Lua function catalog

← Older revision		Revision as of 09:55, 15 August 2026
Line 36:		Line 36:
	* 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>.

			[[Category:Lua Functions]]
	[[Category:Server Functions]]		[[Category:Server Functions]]
	[[Category:World Functions]]		[[Category:World Functions]]
	[[Category:NPC Functions]]		[[Category:NPC Functions]]

QCherry: Update Lua API reference

2026-08-15T09:48:58Z

Update Lua API reference

New page

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

== Syntax ==
<syntaxhighlight lang="lua">
bool setNpcRoute(int npcId, table points [, table options])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <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-256 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.
|}

== Returns ==
Returns <code>true</code> when the complete route is validated and started; otherwise returns <code>false</code>.

== Examples ==
Patrol between two guard posts:
<syntaxhighlight lang="lua" line>
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 })
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* Movement is simulated by the server and replicated as normal smoothed remote snapshots.
* Route progress emits <code>onNpcRoutePoint</code> and non-looping completion emits <code>onNpcRouteComplete</code>.

[[Category:Server Functions]]
[[Category:World Functions]]
[[Category:NPC Functions]]