Skip to content

Navigation & AI

Sektor generates navigation meshes with Recast and answers pathfinding queries with Detour, behind the engine's own SektorNavigation adapter. Recast and Detour are implementation details: no dependency types reach your scene data, components, or the AI protocol.

The stack is complete enough for real games: baked surfaces, weighted named areas, cross-surface links, moving agents, and deterministic local avoidance, all replay-safe.

A Navigation Surface defines where agents can walk. The bake collects source geometry from static box colliders, generated Terrain, and models that opt in with contributesToNavigation, the same shared world geometry physics collides with.

Field Notes
navigationLayer Named movement layer, so "Humanoid" and "Wolf" bake independent surfaces
halfExtents The volume this surface covers
agentRadius, agentHeight The size of agents this surface is baked for
maximumSlopeDegrees, stepHeight What counts as traversable
cellSize, cellHeight Voxel resolution of the bake
tileSizeCells Size of each cooked tile
enabled Toggle without deleting

Tiled cooking and caching

Bakes are tiled: geometry decodes and cooks off the UI lane with cancellation checkpoints, so a large world never blocks the editor. Cooked tiles are versioned and integrity-checked, source geometry is fingerprinted with SHA-256, and a persistent project-local cache reuses tiles whose sources did not change. Edit one corner of the map and only the dirty tiles rebuild.

Play and the standalone Player hold the fixed clock at tick zero until the finished navmesh is adopted atomically, so a bake finishing at a different moment can never change a replay.

Named areas and per-agent costs

Not all walkable ground is equal. A Navigation Area volume stamps a named areaType (for example Mud, Road, Danger) onto the navmesh wherever it overlaps, with priority resolving overlaps.

Each agent carries a cost table for those names, from 0.01 to 1000, default 1:

  • A scout with Mud: 4 walks around the bog.
  • A cart with Road: 0.5 prefers the long road over a short scramble.
  • Same navmesh, different routes, no extra bake.

A Navigation Link joins its own position to endOffset, bridging surfaces that are not continuously connected: gaps, ledges, ladders, doorways, teleporters.

Field Notes
linkType A name agents opt into via allowedLinkTypes
traversalMode linear (walk it), jump (arc of jumpArcHeight), or teleport
radius How close an agent must get to use it
bidirectional One-way drops or two-way ladders
costMultiplier Make a shortcut cheap or a risky jump expensive

A walking guard ignores a jump link that a wolf happily takes, and routes can span several surfaces with each link traversal marked along the way. Saves capture agents mid-link and restore them exactly.

Field Notes
navigationLayer Which baked surface set to use
radius, height Agent size
maximumSpeed, acceleration, stoppingDistance Movement profile
areaCosts The per-agent weight table above
allowedLinkTypes Which link names this agent may traverse
initialDestination, moveOnStart Author a destination without any logic
orientToMovement Face the direction of travel
avoidanceEnabled Reciprocal local avoidance (below)
avoidanceNeighborDistance, avoidanceTimeHorizon, avoidancePriority Avoidance tuning

Local avoidance

Agents now avoid each other, not just the world: spatially indexed reciprocal avoidance solves all agents simultaneously each fixed tick, handles stationary obstacles, and breaks head-on symmetry deterministically (two agents walking straight at each other will not mirror-dance). Priorities let important agents push through crowds. Telemetry streams live to Studio and AI, and an exact-restart proof guarantees replays reproduce.

Recipe: patrol that respects mud

  1. Add a Navigation Surface sized over your level (agentRadius 0.4, agentHeight 1.8 fits a human).
  2. Watch the walkable triangles appear in the viewport as the async bake finishes.
  3. Add a Navigation Area over the swamp, areaType: Mud, priority 10.
  4. Give your creature a Navigation Agent with areaCosts: [{Mud: 6}] and avoidance enabled.
  5. In Events: Every 8 Seconds, action navigation.destination.set to the next patrol point.
  6. Press Play: the patrol loops, skirts the swamp, and flows around other agents instead of clipping through them.

Automate it

Real protocol commands, exactly as the engine accepts them:

{"op":"scene.navigation_surface.create","x":0,"y":2.5,"z":8}
{"op":"component.navigation_surface.set","id":2,"navigationLayer":"Humanoid","halfExtents":[20,5,20],
 "agentRadius":0.4,"agentHeight":1.8,"maximumSlopeDegrees":50,"stepHeight":0.4,
 "cellSize":0.2,"cellHeight":0.1,"tileSizeCells":64,"enabled":true}
{"op":"scene.navigation_area.create","name":"Mud Volume","x":0,"y":1,"z":8}
{"op":"component.navigation_area.set","id":3,"navigationLayer":"Humanoid","areaType":"Mud",
 "halfExtents":[4,2,6],"priority":10,"enabled":true}
{"op":"component.navigation_agent.set","id":1,"navigationLayer":"Humanoid",
 "areaCosts":[{"areaType":"Mud","cost":4},{"areaType":"Road","cost":0.5}],
 "radius":0.4,"height":1.8,"maximumSpeed":3.5,"acceleration":12,"stoppingDistance":0.15,
 "avoidanceEnabled":true,"avoidanceNeighborDistance":5,"avoidanceTimeHorizon":2.5,
 "avoidancePriority":50,"moveOnStart":true,"orientToMovement":true,"enabled":true}
{"op":"runtime.navigation.destination.set","id":1,"destination":[-5,0,12]}
{"op":"inspect.navigation"}

inspect.navigation returns bake statistics, tile cache state, and live agent paths, and the component visualizers draw actual walkable triangles and agent routes in the viewport.

Still ahead

Package-time navmesh cooking, dynamic-obstacle tile caching, formation steering, and higher-level decision systems (behaviour trees, utility AI) build on this same adapter boundary.