Navigation

const Navigation: object

Defined in: server/api.d.ts:7130

Queries the level’s navigation mesh on the server. The mesh includes walkable floors, bridges and stairs.

Copy the game’s Data/Levels/<level>/recast.pak to the server’s files/<level>/ directory. The server searches files/ recursively at startup. An optional mod.navmesh in server.json takes priority and can name a game install, level folder or pak file. The game data must be supplied separately. Without a mesh, ready is false and geometry queries return null or false. Points are world-space metres, Z up. Every query takes an optional options object. searchRadius and searchHeight limit how far a point may be from the mesh, across the ground and up or down: 2 metres by default, up to 64, and 4 by default, up to 128. Keep searchHeight under a storey’s height, or a point on one floor snaps to the floor above. doors picks which doors a query walks through: unlocked, the default, is how an NPC treats a door – open or shut, it goes through unless the door is locked; open only through doors that stand open; any ignores locks; none treats every doorway as a wall. Door states are read in the global world, except validatePatrol with an actor, which uses that actor’s world. A field given with the wrong type or out of range throws.

Type Declaration

activeOverlays

readonly activeOverlays: string[]

Enabled overlays in activation order. Initially empty; the level starts with its base mesh.

overlays

readonly overlays: string[]

Available overlay names, sorted. Overlays contain replacement navigation data for quest states. Enabling one replaces the covered part of the mesh. Empty without a mesh.

ready

readonly ready: boolean

Whether a mesh loaded from mod.navmesh or the server’s files/ directory. False when no usable copy is found; the server log gives the reason.

canReach()

canReach(from, to, options?): boolean

Checks reachability by calling findPath.

Parameters

from

Vector3 | Partial<Vector3>

Where the walk starts; omitted components default to zero.

to

Vector3 | Partial<Vector3>

Where it should end; omitted components default to zero.

options?

How far to look for each end, and which doors to walk through.

doors?

"unlocked" | "open" | "any" | "none"

searchHeight?

number

searchRadius?

number

Returns

boolean

True when a complete path exists; false otherwise, including when no mesh is loaded.

closestPoint()

closestPoint(point, options?): Vector3 | null

Snaps a point to the nearest walkable surface.

Parameters

point

Vector3 | Partial<Vector3>

The point to snap; omitted components default to zero.

options?

How far to look, and which doors count.

doors?

"unlocked" | "open" | "any" | "none"

searchHeight?

number

searchRadius?

number

Returns

Vector3 | null

The nearest point within the search limits, or null when none is found or no mesh is loaded.

disableOverlay()

disableOverlay(name): boolean

Disables an overlay, restoring the previous enabled overlay or the base mesh in that area.

Parameters

name

string

An entry of activeOverlays.

Returns

boolean

False for a name that is not enabled, or when part of the area could not be restored (the server log says why); the overlay is disabled either way.

enableOverlay()

enableOverlay(name): boolean

Enables an overlay. Where overlays overlap, the last enabled takes precedence. Subsequent queries use the updated mesh.

Parameters

name

string

An entry of overlays.

Returns

boolean

False for a name the level does not ship, one already enabled, one whose tiles cannot be read or loaded (the server log says why), or without a mesh.

findPath()

findPath(from, to, options?): NavigationPath | null

Plans a path around obstacles on the mesh. Plan when a destination changes; avoid recalculating every NPC’s path each tick.

Parameters

from

Vector3 | Partial<Vector3>

Where the walk starts; omitted components default to zero.

to

Vector3 | Partial<Vector3>

Where it should end; omitted components default to zero.

options?

How far to look for each end, and which doors to walk through.

doors?

"unlocked" | "open" | "any" | "none"

searchHeight?

number

searchRadius?

number

Returns

NavigationPath | null

The path, or null when an endpoint cannot be found, the query fails or no mesh is loaded. A partial path has complete: false.

floorAt()

floorAt(point, options?): number | null

Returns the height of the nearest walkable surface, including upper floors, bridges and stairs.

Parameters

point

Vector3 | Partial<Vector3>

The point to measure; omitted components default to zero. Its z estimates the floor height and selects the storey.

options?

How far to look.

doors?

"unlocked" | "open" | "any" | "none"

searchHeight?

number

searchRadius?

number

Returns

number | null

The height in metres, or null when none is found or no mesh is loaded.

randomPoint()

randomPoint(center?, radius?, options?): Vector3 | null

Returns a random walkable point reachable from center and no further from it across the ground than radius. A point drawn outside the circle is drawn again, a bounded number of times. Without a centre, samples the whole level, choosing each tile with equal probability.

Parameters

center?

Vector3 | Partial<Vector3>

The point to scatter around; it has to be on the mesh, and omitted components default to zero. Omitted entirely, the point can be anywhere on the level’s mesh; pass undefined for it and for radius to give options.

radius?

number

How far from center, in metres, up to 512. Required with a centre.

options?

How far to look for center, and which doors the point may lie behind.

doors?

"unlocked" | "open" | "any" | "none"

searchHeight?

number

searchRadius?

number

Returns

Vector3 | null

The point, or null when center is off the mesh, no draw lands within radius, the query fails or no mesh is loaded.

raycast()

raycast(from, to, options?): NavigationRay | null

Checks a straight line across the mesh and reports where it stops.

Parameters

from

Vector3 | Partial<Vector3>

Where the walk starts; omitted components default to zero.

to

Vector3 | Partial<Vector3>

Where it heads; only its x and y are used, the walk follows the surface.

options?

How far to look for from, and which doors let the walk through.

doors?

"unlocked" | "open" | "any" | "none"

searchHeight?

number

searchRadius?

number

Returns

NavigationRay | null

The result, or null when from is off the mesh, the query fails or no mesh is loaded.

validatePatrol()

validatePatrol(route, options?): object

Checks all legs, including the closing leg of a loop and reverse legs of ping-pong. Uses the patrol runner’s search budget. A single waypoint is checked against itself. Missing mesh reports available false; partial paths are incomplete. This does not start or change an actor’s order.

Parameters

route

string | PatrolRoute

A registered route or its id.

options?

Optional actor chooses door policy in its virtual world: unlocked doors for humanoids, no doorways for horses and animals.

actor?

Npc | Horse

Returns

object

available

available: boolean

complete

complete: boolean

legs

legs: object[]