SgNavMesh

SgNavMesh represents a navigation mesh used by AI agents to find paths over walkable space. It stores a set of connected polygons and exposes fast queries such as “nearest walkable point”, “path from A to B”, and “move agents across the map”. Navmeshes are created on the fly from the scenegraph data, then can be updated with temporary obstacles (doors, props) without rebaking the whole mesh.

Typical uses:

• Offline path planning with A* over the mesh.
• Steering toward successive waypoints along a smoothed path.
• Validating spawn points and clamping agent positions to walkable areas.

Inherits from

SceneObject

Usage

To use this class, add the following require at the top of your script:

local SgMesh = require 'engine/sceneobjects/sgnavmesh'

Reference

create

static create(self, options, parent)

Create a new navmesh object in the scenegraph.

Parameters

• self
• options (table): A table of options to fill the parameters
• parent (SceneObject): The parent scene object to add this to

Returns

• Promise: promise which will resolve to the created object

Example

-- Options can be omitted. This example shows the defaults,
-- only specify the ones you want different.
SgNavMesh.create({
    active = true,
    name = "",
    transform = Transform.new(),
    layers = {0},
    tags = {},
    type = SgNavMesh.Type.Solo,
    mode = SgNavMesh.Mode.FromChildren,
    navmeshLayers = {0},
    navmeshTags = {},
    autoGenerate = false,
    alwaysRenderHelper = false,
    regenerateNow = false,
    borderSize = 0,
    cellHeight = 0.2,
    cellSize = 0.2,
    chunkyTriMeshTrisPerChunk = 256,
    detailSampleDist = 6,
    detailSampleMaxError = 1,
    expectedLayersPerTile = 4,
    maxObstacles = 128,
    maxEdgeLen = 12,
    maxSimplificationError = 1.3,
    maxVertsPerPoly = 6,
    mergeRegionArea = 20,
    minRegionArea = 8,
    walkableClimb = 2,
    walkableHeight = 2,
    walkableRadius = 0.5,
    walkableSlopeAngle = 60.
    buildBvTree = true,
    tileSize = 32,
    enableCrowd = true,
    maxAgentCount = 100,
    maxAgentRadius = 1
})

Properties

You can access these properties directly on the object or through :get("propertyName") or :set("propertyName", value) methods.

regenerate

regenerate()

Regenerate the navmesh according to its configuration

Returns

• boolean: true in case of success, otherwise false

computePath

computePath(startPosition, endPosition)

Compute a path from a start position to an end position.

Parameters

• startPosition (Vector3): the position to start from
• endPosition (Vector3): the position to end at

Returns

• table: path

findClosestPoint

findClosestPoint(position)

Find the closest point on the navmesh from the position passed to the function

Parameters

• position (Vector3): the position

Returns

• Vector3: position closest to the input position or nil if none is found

findRandomPointAroundCircle

findRandomPointAroundCircle(position, radius)

Returns a random point on the navmesh in a radius around the input position

Parameters

• position (Vector3): the input position
• radius (number): the radius

Returns

• Vector3: random position or nil of none can be found

addAgent

addAgent(position, radius, height, options)

Add a new agent to the navmesh

Parameters

• position (Vector3): the position to add the agent to
• radius (number): the radius of the agent
• height (number): the height of the agent
• options (AgentOptions): additional options for the agent or nil of not required

Returns

• string: agent ID

Example

-- Options can be omitted. This example shows the defaults,
-- only specify the ones you want different.
local agentId = navMesh:addAgent(Vector3.new(0, 0, 0), 0.5, {
    maxAcceleration = 4,
    maxSpeed = 1,
    collisionQueryRange = 0.5,
    pathOptimizationRange = 0,
    separationWeight = 1
})

moveAgent

moveAgent(agentId, position)

Move the agent to a new position

Parameters

• agentId (string): the agent to move
• position (Vector3): the new position to move to

resetAgentMoveTarget

resetAgentMoveTarget(agentId)

Reset the move target of an agent. The agent will stop moving

Parameters

• agentId (string): the agent to stop

getAgentInfo

getAgentInfo(agentId)

Return agent info

Parameters

• agentId (string): the agent to query.

Returns

• table: information about the agent. The table will contain position, velocity, target and nextTargetInPath, all Vector3

Example

local info = navMesh:getAgentInfo(agentId)
printDump(info.position)
printDump(info.velocity)
printDump(info.target)
printDump(info.nextTargetInPath)

removeAgent

removeAgent(agentId)

Remove an agent from the navmesh

Parameters

• agentId (string): the agent to remove

addBoxObstacle

addBoxObstacle(position, halfExtends, angle)

Add a new box obstacle to a navmesh in tile cache mode. Call updateTileCache() afterwards.

Parameters

• position (Vector3): The position of the box
• halfExtends (Vector3): The half extends of the box.
• angle (number): The angle of the box around the Y axis

Returns

• string: obstacle ID or nil in case of failure

addCylinderObstacle

addCylinderObstacle(position, radius, height)

Add a new cylinder obstacle to a navmesh in tile cache mode. Call updateTileCache() afterwards.

Parameters

• position (Vector3): The position of the cylinder
• radius (number): Radius of the cylinder
• height (number): Height of the cylinder

Returns

• string: obstacle ID or nil in case of failure

removeObstacle

removeObstacle(obstacleId)

Remove an obstacle from the tile cache. Call updateTileCache() afterwards.

Parameters

• obstacleId (string): the obstacle to remove

updateTileCache

updateTileCache()

Update the tile cache after modifying obstacles. This function will return true if the tile cache is up to date, false if it still needs updating. In that case call the function again until it returns true

Returns

• boolean: if the cache is up to date, false otherwise

Enum: Type

Enumeration of all navmesh types

Enum: Mode

Enumeration of all navmesh modes