Navigation (pathfinding)
navigationSet up pathfinding in Godot scenes: bake regions from child geometry, add agents and links, query paths, and inspect the map to verify a level is connected before running.
Instructions
Pathfinding setup: navigation regions (2D polygons / 3D navmeshes) baked from their child geometry, NavigationAgents with sane defaults and usage code, navigation links (jumps/teleports), an overview of the scene's navigation, and editor-side path queries to verify a level is connected.
Actions:
region: {type?: 2d|3d (default from parent), name?, parent?='.', outline?: [[x,y],...] | outlines?: [...] (several walkable areas, merged) | rect?: [x,y,w,h] (2D walkable area, pixels), holes?: [[[x,y],...]] (2D: unwalkable areas, added as NavigationObstacle2D children that carve the bake), sources?: [node paths] (extra geometry to bake from, e.g. a TileMapLayer whose tiles have collision, or level nodes that aren't children of the region; switches the region to group source mode), nav?: {agent_radius, cell_size, parsed_geometry_type: meshes|static_colliders|both, source_geometry_mode: root_node_children|groups_with_children|groups_explicit, collision_mask: names|numbers, agent_height, agent_max_climb, ...} (NavigationPolygon/NavigationMesh props; 2D and 3D names both accepted), bake?=true when an outline is given (2D) / always (3D), position?, props?} create a NavigationRegion2D/3D. Obstacles are the region's children (plus sources): 2D bakes carve child collision shapes/meshes out of the outline (agent_radius default 10px); 3D bakes walkable surfaces from child meshes/static bodies. Add children later (physics.body parent: region) then navigation.bake.
bake: {path: region, sources?: [node paths], nav?: {...bake settings, as in region}} (re)bake the region's navigation polygon/mesh from its source geometry (synchronous, undoable). Returns polygon/vertex counts and bounds.
agent: {parent: body node, type?: 2d|3d, name?, radius?, max_speed?, avoidance?: bool, path_desired_distance?, target_desired_distance?, props?} add a NavigationAgent2D/3D (defaults tuned: 4px / 0.5m path & target distances). Returns the movement code to use in the body's script.
link: {from: [x,y] | [x,y,z], to, parent?='.', name?, bidirectional?=true, props?: {enter_cost, travel_cost, navigation_layers}} add a NavigationLink2D/3D connecting two points (jump down a ledge, ladder, teleporter). Positions are in the parent's space.
path: {from: [x,y] | [x,y,z], to, type?: 2d|3d, navigation_layers?=1, tolerance?=8px/0.5m} query a path on the edited scene's navigation map: points, length, reachable. Use it to verify level connectivity before running the game.
info: {path?} one navigation node, or (no path) a scene overview: regions (polygons, bounds, agent radius, obstacle count), agents, links, obstacles, map cell sizes.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End point [x, y] or [x, y, z]. | |
| nav | No | NavigationPolygon / NavigationMesh bake settings (agent_radius, cell_size, parsed_geometry_type: meshes|static_colliders|both, collision_mask, ...). | |
| bake | No | Bake right after creating the region. | |
| from | No | Start point [x, y] or [x, y, z]. | |
| name | No | Node name. | |
| path | No | Node path relative to the scene root ('.' = root, 'Player/Sprite2D', '%Unique'), or a res:// file path, depending on the action. | |
| rect | No | [x, y, width, height] walkable rectangle (2D). | |
| type | No | 2d or 3d. | |
| holes | No | [[[x, y], ...], ...] unwalkable polygons inside the outline (2D). | |
| props | No | Property map. Values are coerced to the property type: numbers, [x,y], 'Vector2(1,2)', '#ff8800', 'res://file', {"type":"RectangleShape2D","size":[32,32]} for new resources, enum names as strings. | |
| scene | No | res:// scene to operate on; opened in the editor if needed. Defaults to the currently edited scene. | |
| action | Yes | What to do. See the tool description for each action's parameters. | |
| height | No | Agent height (3D). | |
| parent | No | Parent node path. | |
| radius | No | Agent radius. | |
| outline | No | [[x, y], ...] walkable outline (2D). | |
| sources | No | Extra node paths whose geometry/collision the bake uses (e.g. a TileMapLayer). | |
| outlines | No | Several walkable outlines (2D), merged. Use holes for unwalkable areas. | |
| position | No | [x, y] or [x, y, z]. | |
| avoidance | No | Enable agent avoidance (RVO). | |
| max_speed | No | Agent max speed. | |
| tolerance | No | path: max distance between path end and 'to' to count as reachable. | |
| bidirectional | No | Link usable both ways. | |
| navigation_layers | No | Navigation layer bitmask for path queries. | |
| path_desired_distance | No | Agent: distance to a path point to consider it reached. | |
| target_desired_distance | No | Agent: distance to the target to consider it reached. |