QCherry: Document G1R:MP 0.1.2 navigation collision

2026-09-04T13:52:45Z

Document G1R:MP 0.1.2 navigation collision

New page

{{DISPLAYTITLE:NPC and monster navigation collision}}

<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;">AVAILABLE FROM UPDATE 0.1.2</div>
<div style="color:#111111; margin-top:0.25rem;">This navigation-collision system and the APIs described below are available in G1R:MP 0.1.2 and later.</div>
</div>

NPCs and monsters share one authoritative server navigation-collision service. It combines two selectable static layers with mandatory dynamic character separation:

* <code>builtin</code>: verified MainMap blockers baked into the server package;
* <code>custom</code>: bounded blockers created by server-side Lua resources;
* dynamic capsules: connected players, NPCs and monsters; always enabled.

The baked MainMap layer is a conservative 2.5D no-go representation. It is not a Recast navmesh or terrain heightfield. It includes verified navigation-exclusion volumes and exact supported collision primitives for relevant world objects such as tree trunks; it does not infer blockers from broad mesh bounds or tree crowns.

== Collision-source modes ==

Every NPC and monster uses <code>combined</code> by default:

{| class="wikitable"
! Mode !! Static collision sources
|-
| <code>combined</code> || Baked MainMap blockers and enabled custom blockers
|-
| <code>builtin</code> || Baked MainMap blockers only
|-
| <code>custom</code> || Enabled custom blockers only
|}

Mode values are case-sensitive. Select the mode at spawn time when the initial position must be validated against a specific layer:

<syntaxhighlight lang="lua" line>
local monsterId = spawnMonster("scavenger", 20, 5, 2, 0, {
navigationCollisionMode = "custom",
})

local npcId = spawnNpc("Gate Guard", "guard_01", 24, 5, 2, 180, {
navigationCollisionMode = "combined",
})
</syntaxhighlight>

The mode can be changed later:

<syntaxhighlight lang="lua" line>
setMonsterNavigationCollisionMode(monsterId, "builtin")
setNpcNavigationCollisionMode(npcId, "custom")
</syntaxhighlight>

The current value is exposed as <code>getMonsterData(monsterId).navigationCollisionMode</code> or <code>getNpcData(npcId).navigationCollisionMode</code>.

<code>navigationCollisionMode</code> is independent from <code>navigationMode</code>. Collision mode selects the static geometry that must be respected. Navigation mode selects built-in AI decisions or direct scripted movement goals. Player, NPC and monster capsule separation remains active in every combination, and clients never become authoritative.

Changing a collision mode invalidates the entity's cached path. Material custom-blocker changes selectively revalidate affected cached paths; spatially unrelated paths are not globally rebuilt.

== Resource-owned blocker API ==

<syntaxhighlight lang="lua">
createAiNavigationBlocker(definition) -- string ID or false
updateAiNavigationBlocker(blockerId, definition) -- bool
setAiNavigationBlockerEnabled(blockerId, enabled) -- bool
destroyAiNavigationBlocker(blockerId) -- bool
getAiNavigationBlockerData(blockerId) -- table or false
getAiNavigationBlockers() -- table
</syntaxhighlight>

Blocker IDs are opaque decimal strings and must not be converted to Lua 5.1 numbers. A resource can inspect or mutate only blockers it created. Enabled geometry participates in the shared custom layer seen by all AI entities that use <code>custom</code> or <code>combined</code>. Stopping or restarting a resource removes all blockers owned by that resource.

All coordinates and dimensions use metres. Supported definitions are boxes, cylinders and simple convex polygons:

<syntaxhighlight lang="lua" line>
local gate = createAiNavigationBlocker({
shape = "box",
x = 125.0, y = -48.0, z = 2.0,
width = 2.5, depth = 0.8, height = 4.0,
yaw = 30,
enabled = true,
})

local pillar = createAiNavigationBlocker({
shape = "cylinder",
x = 130.0, y = -45.0, z = 2.0,
radius = 1.5, height = 4.0,
})

local restrictedArea = createAiNavigationBlocker({
shape = "polygon",
points = {
{ x = 10.0, y = 10.0 },
{ x = 14.0, y = 10.0 },
{ x = 14.0, y = 13.0 },
{ x = 10.0, y = 13.0 },
},
minZ = -1.0,
maxZ = 5.0,
})
</syntaxhighlight>

Shape names are case-sensitive. Dimensions must be finite and between 0.01 and 10,000 metres. Polygon definitions accept 3-16 finite vertices and must be simple and convex. World coordinates are bounded to +/-100,000 metres.

Getters return canonical polygon data even when the input shape was a box or cylinder. <code>getAiNavigationBlockers()</code> is sorted deterministically by ID and includes disabled blockers. Omitting <code>enabled</code> from an update preserves the current state.

== Runtime limits and intended use ==

The default hard limits are:

* 1,024 blockers per resource;
* 4,096 custom blockers across the server;
* 4,096 broad-phase cells per blocker;
* 1,000,000 combined custom spatial-index entries.

Invalid or over-limit creates and updates return <code>false</code> without partially changing geometry.

Custom blockers affect AI navigation only. They do not create visible meshes, Unreal physics objects, player collision, or client-side world geometry. They are intended for static geometry and occasional changes such as opening or closing a gate. Do not move or toggle them every server tick; use the mandatory dynamic capsule layer for moving players, NPCs and monsters.

== Related functions ==

* [[spawnMonster]], [[getMonsterData]], [[setMonsterNavigationMode]], [[setMonsterNavigationCollisionMode]], [[setMonsterMoveGoal]], [[walkMonsterTo]], [[testMonsterMove]]
* [[spawnNpc]], [[getNpcData]], [[setNpcNavigationMode]], [[setNpcNavigationCollisionMode]], [[setNpcMoveGoal]], [[setNpcRoute]], [[testNpcMove]]
* [[createAiNavigationBlocker]], [[updateAiNavigationBlocker]], [[setAiNavigationBlockerEnabled]], [[destroyAiNavigationBlocker]], [[getAiNavigationBlockerData]], [[getAiNavigationBlockers]]

[[Category:Lua API]]
[[Category:Navigation Functions]]

NPC and monster navigation collision - Revision history

QCherry: Document G1R:MP 0.1.2 navigation collision