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¶

class SgNavMesh¶

module:

static create(options, parent)¶

Create a new navmesh object in the scenegraph.

Parameters:

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

Returns:

a promise which will resolve to the created object

Return type:

Promise

Usage:

-- 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
})

regenerate()¶

Regenerate the navmesh according to its configuration

Returns:: Returns true in case of success, otherwise false
Return type:: boolean

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:

the path

Return type:

table

findClosestPoint(position)¶

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

Parameters:: position (Vector3) – the position
Returns:: the position closest to the input position or nil if none is found
Return type:: Vector3

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:

the random position or nil of none can be found

Return type:

Vector3

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:

an agent ID

Return type:

str

Usage:

-- 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(agentId, position)¶

Move the agent to a new position

Parameters:

agentId (str) – the agent to move
position (Vector3) – the new position to move to

resetAgentMoveTarget(agentId)¶

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

Parameters:: agentId (str) – the agent to stop

getAgentInfo(agentId)¶

Return agent info

Parameters:: agentId (str) – the agent to query.
Returns:: the information about the agent. The table will contain position, velocity, target and nextTargetInPath, all Vector3
Return type:: table

Usage:

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

removeAgent(agentId)¶

Remove an agent from the navmesh

Parameters:: agentId (str) – the agent to remove

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:

the obstacle ID or nil in case of failure

Return type:

str

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:

the obstacle ID or nil in case of failure

Return type:

str

removeObstacle(obstacleId)¶

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

Parameters:: obstacleId (str) – the obstacle to remove

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:: true, if the cache is up to date, false otherwise
Return type:: boolean