TestNpcMove

testNpcMove

AVAILABLE FROM UPDATE 0.1.2

This function is available in G1R:MP 0.1.2 and later. The contract below includes the compatibility guarantees introduced in that update.

Tests a direct NPC move against the current authoritative world and character collision state without changing movement.

Syntax

table|false testNpcMove(int npcId, number x, number y, number z)

Parameters

Name	Type	Required	Description
npcId	int	yes	The server-assigned NPC identifier returned by spawnNpc or getNpcs.
x	number	yes	Test destination X coordinate in metres.
y	number	yes	Test destination Y coordinate in metres.
z	number	yes	Test ground-location Z reference in metres.

Returns

Returns a table with allowed, reason, blockerType and blockerId, or false when the arguments, ownership or service are invalid. Reasons are clear, unknown-npc, invalid-input, distance-limit, world-collision or dynamic-collision. Blocker types are none, world, player, npc, monster or unknown; blockerId is an identifier string and is empty when no dynamic entity is identified.

Examples

Inspect a direct goal before assigning it:

local result = testNpcMove(npcId, 20.0, -7.5, 2.0)
if result and result.allowed then
    setNpcMoveGoal(npcId, 20.0, -7.5, 2.0)
elseif result then
    outputDebugString(result.reason .. " blocker=" .. result.blockerType .. ":" .. result.blockerId)
end

Notes

• Available only in server-side resource scripts.
• Only the resource that created the NPC may test its movement.
• This is a read-only, ground-only direct-segment test. It does not run route path finding, mutate a goal or provide moving-platform vertical control.
• World and dynamic occupancy may change after the test. setNpcMoveGoal and every simulation step still perform authoritative validation.