2D navigation: choose a system and start moving
From a route model to physics movement and goal validation.
Start by choosing a route model. Navigation finds paths, game code moves characters, and physics checks collisions. Having one system does not create the other two.
Choose an API
| Task | Class / API |
|---|---|
| Predefined points and connections | AStar2D. |
| Movement between rectangular-grid cells | AStarGrid2D. |
| Movement inside arbitrary traversable surfaces | NavigationServer2D with a map and polygons. |
| Convenient parent path-following support | A child NavigationAgent2D; you still implement physics movement. |
Do not choose a mesh merely because it sounds more powerful. A grid can express turn-based rules more precisely. Free movement on a surface does not require manually placing a graph point at every possible position.
Surface-movement workflow
- Prepare a
NavigationPolygoncontaining actual polygons and assign it toNavigationRegion2D. For a programmatic example, see square baking. - Ensure the region and character use the same map. Assign a custom map explicitly to the agent; see maps and ownership.
- Create a
CharacterBody2DandCollisionShape2D. The collider serves physics; the navigation resource serves pathfinding. - Add a child
NavigationAgent2D. Use the executed agent example for a complete script, exact child name and shape. - After navigation publication, call that example's
SetDestinationwith a global goal. - Check movement, goal arrival and stopping. Then request a goal outside the surface and handle the partial route separately.
On the checked x=0–20, y=0–10 map, the physics body moved from (2, 5) to (18, 5). Goal (30, 5) was unreachable even though the agent finished its available route. These are distinct outcomes, rather than one IsNavigationFinished() check.
Objects you actually need
NavigationPolygon stores surface data. NavigationRegion2D places it on a map. The map combines regions for queries. NavigationAgent2D helps select the next point and optionally computes avoidance. CharacterBody2D performs physics movement through your code.
NavigationLink2D represents a special transition but does not execute a jump or teleport. NavigationObstacle2D participates in avoidance and/or bake-source parsing; adding one does not automatically update prepared paths. Add these Entities only when the task requires them.
Diagnose no movement
- No path: inspect polygons, map, layers and navigation readiness.
- A path exists but the body stands still: implement parent movement; the agent does not move it.
- A wall stops the body: align navigation and collision geometry. The checked collider blocked movement despite a straight route through it.
- Movement is too slow: supply
MoveAndSlide()velocity in units per second without multiplying bydeltaagain.
Continue with agents, regions, then area access.
The linked 2D example executes physics movement, stopping, partial-route and wall scenarios. AStar class selection was checked against SDK/source; its algorithms, editor-level setup and visual output were not evaluated by this check.