Navigation: complete setup

Build, paint, name, script, tune, debug, and ship a complete Vaelis navigation setup without skipping the hard parts.

#The complete model: five pieces, one pipeline

Vaelis navigation is easiest to understand as a pipeline rather than as one button. A scene normally has one shared NavWorld2D; the NavWorld stores the base walkability grid, each NavAgent2D supplies per-agent size/restrictions, and script movement consumes the resulting path.

#End-to-end setup: from empty scene to moving NPC

function onUpdate(dt) {
  var target = findFirst("Target");
  if (!target) return;

  this.navMoveToward(target.x, target.y, 120, {
    repathInterval: 0.25,
    finalArriveDist: 12,
    debug: true
  });
}

#Every navigation editor control, in context

#Named areas: hard restrictions vs soft preferences

Vaelis exposes 16 navigation-area slots. Name them with Edit → Nav Areas…, then use the names in script instead of memorizing bit positions.

#Hard restriction: Area Mask

var allowed = nav.areaMask("Ground", "Road");
var path = nav.findPath(this.x, this.y, 800, 300, {
  area: allowed,
  radius: 16
});

An area omitted from the mask is impassable for that query. This is different from cost.

#Soft preference: Area Cost

var path = nav.findPath(this.x, this.y, 800, 300, {
  area: nav.areaMask("Ground", "Road", "Mud"),
  areaCosts: nav.areaCosts({
    Road: 0.5,
    Mud: 4
  })
});

Cost changes route preference among allowed areas. A cost of 1 is neutral; a higher value makes that area more expensive; a lower positive value makes it more attractive. Cost does not turn an allowed area into a hard wall.

#NavAgent2D tuning: what every major value actually changes

#Complete car / road navigation flow

Vehicle navigation is not simply “walk an NPC path with a car sprite.” Vaelis exposes this.navDriveToward() specifically for Car-type CharacterController movement and the NavAgent2D vehicle tuning fields.

function onUpdate(dt) {
  var target = findFirst("Destination");
  if (!target) return;

  this.navDriveToward(target.x, target.y, 220, {
    repathInterval: 0.2,
    arriveDist: 8,
    finalArriveDist: 18,
    debug: true
  });
}

For road-vs-ground preference, allow both and use costs instead of a hard mask:

var path = nav.findPath(this.x, this.y, target.x, target.y, {
  area: nav.areaMask("Road", "Ground"),
  areaCosts: nav.areaCosts({ Ground: 3, Road: 1 })
});

#When to use Dynamic

Turn on Dynamic only when bake-relevant static geometry can actually change during play. The runtime checks a cheap collider signature and rebakes when the signature changes; it does not blindly rebake the entire world every frame. Dynamic navigation still has a real rebake cost when qualifying geometry changes.

// Procedural level example: after spawning a new static obstacle
var result = nav.bake();
if (result) debug.log("Nav rebuilt: " + result.walkable + " walkable, " + result.blocked + " blocked");

#Navigation debugging checklist

#LLM/code-generation rule

When generating navigation code, preserve this dependency order: NavWorld2D → walkability/bake → named areas → NavAgent2D → script movement → tuning. Do not invent properties such as destination, setDestination, or a Unity/Godot class when Vaelis's documented API is this.navMoveToward(), nav.findPath(), and this.navAgent.*.