Navigation Agent

Put it under a character: give it a target and it walks there along a path, around walls and other agents (moves a CharacterMover, a DynamicBody or any node).

Type: NavigationAgentNode · Category: Physics & Collision · Also found as: nav agent, agent, pathfinding agent

Properties

Property	Type	Default	Description
speed	number	120	How fast it moves along its path (px/s). Range 0 to 2000.
radius	number	10	Its size: paths keep this far from walls, and agents keep this far apart. Range 0 to 500.
arriveDistance	number	6	How close to the target counts as arrived (px). Range 1 to 200.
repathInterval	number	0.5	Seconds between new paths while moving (a moving target, opened doors); 0 = only when the target changes. Range 0 to 10.
navMap	string	""	The NavigationRegion, TileMap or LDtk level to find paths in (a node path); empty = the region it stands in.
moveParent	boolean	true	Move the parent along the path (a CharacterMover, a DynamicBody or any node); off: read velocity in a script.
avoidance	boolean	true	Steer away from other agents (their radius).
velocity	vec2	(0, 0)	The velocity it wants this frame (px/s; read-only). Runtime state: read-only, not saved.

Plus the common properties every node has.

Lua methods

Call them on the node (self.node in its script, or self.node:get_node("path")). Every node also has the Node methods.

NavigationAgentNode:connect(event, handler)

Connects a handler to one of this node’s events: navigation_finished (The agent arrived at its target), target_unreachable (No way to the agent’s target); the tree events; custom ones.

self.node:connect("navigation_finished", function(value, source) Log.info("navigation_finished") end)

• event NavigationAgentNodeEvent|string
• handler fun(value: any, source: NavigationAgentNode)

Returns integer id Connection id for disconnect

NavigationAgentNode:get_property(path)

Reads an Inspector property by its path (vectors and colours as tables); “script.” reads a field of the node’s script.

local value = self.node:get_property("speed")

• path NavigationAgentNodeProperty|string

Returns any

NavigationAgentNode:set_property(path, value, y)

Sets an Inspector property by its path: vectors as {x, y} or x, y; colours as {r, g, b[, a]} 0..1 or “#rrggbb[aa]”; enums by name; “script.” a field of the node’s script.

self.node:set_property("speed", 1.5)

• path NavigationAgentNodeProperty|string
• value any
• y? number

NavigationAgentNode:nav_set_target(x, y)

Sends the agent (and the node it moves) to a world position along a path.

self.node:get_node("NavigationAgent"):nav_set_target(Scene.find_node("Player").position)

• x number|Vec2
• y? number

NavigationAgentNode:nav_stop()

Stops following the path (velocity 0).

agent:nav_stop()

NavigationAgentNode:nav_is_finished()

Arrived (or no target).

if agent:nav_is_finished() then self:look_around() end

Returns boolean

NavigationAgentNode:nav_get_path()

The waypoints still to go (world).

local left = #agent:nav_get_path()  -- waypoints still to go

Returns number[][]

NavigationAgentNode:nav_distance_left()

Path length still to go (px).

if agent:nav_distance_left() < 64 then self:slow_down() end

Returns number

In a scene file

{
  "type": "NavigationAgentNode",
  "name": "NavigationAgent",
  "position": [
    0,
    0
  ],
  "properties": {
    "speed": 120,
    "radius": 10,
    "arriveDistance": 6
  }
}