NavMesh and NavMeshAgent

NavMesh performs bounded queries against baked surfaces. NavMeshAgent controls a root GameObject with an enabled NavMesh Agent component assigned to one surface.

Path Queries

NavMesh.FindPath(sx, sy, sz, ex, ey, ez) returns a table of Vec3 points. A successful result is always complete and contains at most 32 points; an empty table means no complete route fits the current bake and runtime limit.

local points = NavMesh.FindPath(0.0, 0.0, 0.0, 6.0, 0.0, -4.0)
for index, point in ipairs(points) do
  Log.Print(tostring(index) .. ": " .. point.x .. ", " .. point.y .. ", " .. point.z)
end

NavMesh.SamplePosition(x, y, z, maxDistance[, surfaceGameObjectId]) returns found, sampleX, sampleY, sampleZ. Provide a surface ID when more than one NavMesh Surface exists or the query must stay on a specific bake.

Agent Movement

targetGameObjectId = -1

function Start(gameObjectId)
  local target = Transform.GetPosition(targetGameObjectId)
  if target ~= nil then
    NavMeshAgent.SetDestination(gameObjectId, target.x, target.y, target.z)
  end
end

function Update(gameObjectId, deltaTime)
  if NavMeshAgent.HasReachedDestination(gameObjectId) then
    NavMeshAgent.Stop(gameObjectId)
  end
end

Queries include IsMoving, HasPath, HasReachedDestination, IsOnNavMesh, GetRemainingDistance, GetSpeed, and GetPathStatus. NavMeshAgent.PathComplete identifies a complete route; NavMeshAgent.PathInvalid means no valid route is owned.

An agent must remain a root GameObject because the bake and movement use world space. SetDestination returns false for a missing/disabled component, an invalid surface, an unreachable destination, or a route that exceeds 32 points. It does not add Character Controller response, local avoidance, dynamic obstacle rebaking, or links between separate surfaces.

See Rooms, Portals, and Navigation for bake authoring and validation.