2D Pathfinding in Godot 4: Grid, Graph, or Navmesh?

The three representations of space

Godot has three practical built-in representations for ordinary 2D pathfinding. The useful difference is not the node name. It is where the actor is legally allowed to stand.

AStarGrid2D is a ready-made regular grid. Its cells are addressed with integer Vector2i IDs such as (12, 7). Godot creates the ordinary neighbour connections; you decide which cells are solid, what they cost, and whether diagonal movement is legal. It is not literally your game's two-dimensional array, and it does not read a TileMapLayer automatically.

AStar2D is a custom graph. You add points anywhere in 2D space, give them stable integer IDs, and connect the pairs that are legal. The points do not need to form rows, columns, or a complete surface.

NavigationServer2D works with navigation maps made from polygonal walkable regions. An actor can stand anywhere inside the valid area rather than only on a cell or waypoint. NavigationAgent2D is the scene-facing helper that follows those paths and can optionally participate in local avoidance.

If units must end on exact cells, do not start with a navmesh because it looks convenient in the editor. If they can stop anywhere in a room, do not turn the floor into ten thousand tiles just to give A* something to read.

The downloadable Godot 4.7.1 project runs all three approaches over one small arena. It is a correctness comparison, not a speed test.

Choose the movement model before the node

Pathfinding does not decide your movement rules. It answers a route query over rules you already encoded.

A tactical unit may occupy (12, 7), pay two action points to enter mud, and be forbidden from cutting a diagonal corner. Those are cell rules. They map cleanly to AStarGrid2D.

A train may travel from station A to station B but not stop in the field between them. A platform enemy may jump from one ledge marker to another only when a scripted traversal exists. Those are graph rules. They fit AStar2D.

A top-down character may stand at any pixel inside an irregular room and steer around another moving character. That is continuous walkable space. It fits a 2D navigation mesh. The grid-versus-navmesh guide owns the deeper production tradeoff.

Keep pathfinding, path following, and avoidance separate

These jobs are easy to blend together because NavigationAgent2D puts a friendly node around more than one of them.

AStarGrid2D.get_id_path() and AStar2D.get_point_path() return paths but move nothing. NavigationAgent2D also moves nothing by itself: read get_next_path_position() and move its parent body. A NavigationObstacle2D affects avoidance velocity, not the global path, unless it is deliberately used as bake input and the mesh is rebuilt.

A cyan line crossing a wall is a representation or query problem. A correct line with a stationary body is a movement-controller problem. A correct line with two bodies shoving each other into a doorway is an avoidance or crowd-resolution problem.

• Pathfinding: returns a route through the legal representation.
• Path following: moves a body toward the next point and decides when it has been reached.
• Avoidance: adjusts local velocity around nearby agents or obstacles.

The two-question decision tree

Start with the legal positions. Then ask whether a continuous-space actor also needs local real-time steering.

1. Must actors occupy regular cells? Yes: use AStarGrid2D. No: continue.
2. Can actors stand anywhere inside a continuous walkable area? Yes: use NavigationServer2D and optionally NavigationAgent2D. No: if legal positions are authored points and connections, use AStar2D.
3. Do continuous-space actors need local real-time steering around each other? Enable avoidance only for the actors that need it. It does not replace the global route.

When to use the forgotten AStar2D

AStar2D is an explicit weighted graph in 2D space. It does not scan the scene, read collision shapes, or infer which waypoint connects to which. Add the points, connect the legal pairs, and keep those IDs stable if other game data refers to them.

It fails as a design choice when the graph is really a regular grid in disguise. Manually generating one point per tile and four or eight connections per point adds topology bookkeeping that AStarGrid2D already owns.

The verified fixture stores its graph points in the same world-space coordinate system used for clicks and drawing. A production scene can use local space instead; pick one boundary and keep it consistent. AStar2D does not know which one you meant.

This is also a better starting point for a 2D platformer than a flat navmesh when jumps, drops, ladders, and one-way ledges must become explicit edges with custom execution. The AStar2D complete reference covers weights, disabled points, partial paths, custom costs, and runtime topology audits.

• Patrol networks where guards move only between named posts.
• Subway or road graphs where stations and junctions matter.
• Room-to-room roguelike routing where the question is which door leads where.
• Platformer graphs with directed jumps, drops, ladders, and one-way ledges.
• Point-and-click movement constrained to authored waypoints. Free movement to any pixel in an irregular room is a navmesh case instead.

func _build_graph() -> void:
	var points := {
		0: Vector2(90, 210),
		1: Vector2(280, 55),
		2: Vector2(560, 55),
		3: Vector2(280, 365),
		4: Vector2(560, 365),
		5: Vector2(750, 210),
	}
	for id in points:
		_graph.add_point(id, _board_to_world(points[id]))
	_graph.connect_points(0, 1)
	_graph.connect_points(0, 3)
	_graph.connect_points(1, 2, false)
	_graph.connect_points(3, 4)
	_graph.connect_points(2, 5)
	_graph.connect_points(4, 5)
	_graph_path = _graph.get_id_path(0, 5)

Performance bottlenecks and dynamic worlds

Do not reduce this comparison to “AStarGrid2D is C++ and navmesh is expensive.” That mixes a path query with a topology rebuild. The useful question is what work the game requests when the world changes.

For a tile-locked building game, a new wall usually maps to a few AStarGrid2D.set_point_solid() calls. Changing solidity or weight scale does not require another update(); structural properties such as region or cell_size do.

For AStar2D, disable a waypoint when the point itself is unavailable. Disconnect or reconnect an edge when the traversal between two still-valid points changes. The class cannot infer either rule from physics geometry.

For a navmesh, decide whether the blocker is soft or hard. Another moving actor is usually an avoidance concern. A closed door or player-built wall that must make the route illegal is navigation topology: change region or polygon data, or rebake the affected polygon. A background-thread bake still has parsing, baking, synchronization, and map-update cost.

The Navigation Process monitor covers navigation-server updates and avoidance, but Godot documents that it does not include path-query performance. Measure queries separately. The frame-spike guide owns budgets and profiler workflow; the runtime grid-update guide owns point edits versus structural rebuilds.

There is no honest universal “fastest” row. That requires equivalent maps, query sets, update patterns, agent counts, and measured builds.

1. Path-query cost: query count and how much grid, graph, or mesh each request searches.
2. Topology-update cost: solidity edits, connection edits, region changes, or rebakes.
3. Path-following cost: controller work for each moving actor.
4. Avoidance cost: per-frame work for registered avoidance agents and obstacles.

Summary matrix: the cheat sheet

Use this matrix as a starting point, not a permanent architecture. Hybrid systems are normal: a strategy game can use a room graph for long-distance planning, a grid for tactical legality, and local steering for the last few pixels.

Build the AStarGrid2D version

Use AStarGrid2D when the board itself is a grid and cell identity matters. Godot creates the points and ordinary neighbour connections; you declare the region, diagonal policy, solid cells, and weights.

Configure the grid shape, call update(), then apply solids and weights. A structural rebuild clears point solidity and weights, so replay those layers after a dirty update.

The proof deliberately starts its grid at (-2, -1). The unweighted route uses the lower opening; a weight of 6 on the lower strip moves the verified route to the upper opening.

func _build_grid() -> void:
	_grid.region = GRID_REGION
	_grid.cell_size = CELL_SIZE
	_grid.offset = BOARD_RECT.position + CELL_SIZE * 0.5 - Vector2(GRID_REGION.position) * CELL_SIZE
	_grid.diagonal_mode = AStarGrid2D.DIAGONAL_MODE_NEVER
	_grid.update()
	for y in range(0, 5):
		_grid.set_point_solid(Vector2i(WALL_X, y), true)
	_unweighted_grid_path = _grid.get_id_path(START_CELL, GOAL_CELL)
	for x in range(1, 7):
		_grid.set_point_weight_scale(Vector2i(x, 5), 6.0)
	_grid_path = _grid.get_id_path(START_CELL, GOAL_CELL)

Adapt the grid to TileMapLayer data

The TileMapLayer and AStarGrid2D are separate structures. Painting a wall does not automatically make a point solid. Copy one explicit rule such as a walkable custom-data flag into the query grid after update().

The full TileMapLayer-to-AStarGrid2D guide owns negative origins, custom data, runtime updates, and failure cases. The AStarGrid2D reference owns heuristics, diagonals, jumping, and partial paths.

@onready var ground: TileMapLayer = $Ground

func build_grid_from_tiles() -> void:
	grid.region = ground.get_used_rect()
	grid.cell_size = Vector2(ground.tile_set.tile_size)
	grid.diagonal_mode = AStarGrid2D.DIAGONAL_MODE_NEVER
	grid.update()

	for y in range(grid.region.position.y, grid.region.end.y):
		for x in range(grid.region.position.x, grid.region.end.x):
			var cell := Vector2i(x, y)
			var tile_data := ground.get_cell_tile_data(cell)
			var walkable := tile_data != null and bool(tile_data.get_custom_data("walkable"))
			grid.set_point_solid(cell, not walkable)

Convert coordinates at one boundary

get_id_path() expects grid IDs. Your actor and mouse use world positions. Put both conversions in named helpers instead of scattering arithmetic through the controller.

This preserves a negative get_used_rect() origin. Normalizing every tile coordinate to zero is optional bookkeeping, not an AStarGrid2D requirement.

func _cell_top_left(cell: Vector2i) -> Vector2:
	return BOARD_RECT.position + Vector2(cell - GRID_REGION.position) * CELL_SIZE


func _cell_center(cell: Vector2i) -> Vector2:
	return _cell_top_left(cell) + CELL_SIZE * 0.5


func _world_to_cell(world_position: Vector2) -> Vector2i:
	return Vector2i(((world_position - BOARD_RECT.position) / CELL_SIZE).floor()) + GRID_REGION.position

NavigationServer2D: when the walkable area is continuous

For free movement inside rooms and irregular outdoor shapes, create a NavigationRegion2D, assign a NavigationPolygon, and bake the walkable area. Put a NavigationAgent2D under the moving CharacterBody2D.

The navigation mesh describes where the actor's centre may travel. Physics collision still decides whether the body can execute that route, so leave enough clearance around walls for the real collision shape.

The downloadable proof uses the equivalent direct-server form: one map RID, one region RID, a baked polygon, and two agents assigned to that map. It disables async map iterations and calls map_force_update() only inside the deterministic fixture. The scene-tree baseline remains simpler for ordinary game code.

Godot's TileMap documentation warns that built-in per-tile navigation has practical pathfinding and path-following limitations and recommends baking to a NavigationRegion2D or using NavigationServer2D for a more optimized mesh. The NavigationServer2D guide owns direct RID queries, links, synchronization, and rebuild cost.

World (Node2D)
├── NavigationRegion2D
├── Player (CharacterBody2D)
│   ├── CollisionShape2D
│   ├── Sprite2D
│   └── NavigationAgent2D
├── TargetMarker
└── PathLine

Wait for the navigation map before the first target

Navigation maps synchronize changes on physics frames. A target assigned as soon as _ready() runs can query before the region has reached the server.

For a static starter scene, waiting one physics frame is the baseline. The downloadable project uses the map iteration as an explicit readiness check.

Godot also exposes a direct map force-update call for controlled procedural tooling. It should not become the default fix for ordinary scene initialization; normal physics synchronization is cheaper and easier to reason about.

func _wait_for_initial_navigation_sync() -> void:
	for _frame in range(180):
		await get_tree().physics_frame
		if NavigationServer2D.map_get_iteration_id(_nav_map) > 0:
			_navigation_is_ready = true
			_set_navigation_target(_board_to_world(Vector2(750, 210)))
			navigation_ready.emit()
			_refresh_status()
			return
	_refresh_status("Navigation map did not synchronize")

Normalize the target, then move the parent yourself

A click may land outside the navigation polygon. Clamp it to the map, assign it only when the target changes, and keep get_next_path_position() in _physics_process().

Setting target_position does not move the body. Your controller still owns velocity, acceleration, collision response, animation, and stopping distance.

Do not call path-update methods from waypoint_reached or another agent callback. The class reference warns that this can trigger recalculation and recurse. The physics step is the boring place that works. The NavigationAgent2D setup guide goes deeper on reachability, jitter, and distance tuning.

func _set_navigation_target(requested: Vector2) -> void:
	if not _navigation_is_ready:
		return
	_normalized_nav_target = NavigationServer2D.map_get_closest_point(_nav_map, requested)
	_main_agent.target_position = _normalized_nav_target
	_nav_path = _server_path(_main_body.global_position, _normalized_nav_target)

Avoidance is optional, and it is not repathing

Enable avoidance only when the actor needs local steering around other avoidance agents or obstacles. It adds work and another movement contract.

With avoidance enabled, send desired velocity to the agent and move the body with the velocity_computed result.

NavigationObstacle2D does not make the agent calculate a different global path. It constrains avoidance velocity. If a closed door or tower must make a route illegal, mark grid cells solid, change graph connections, or update navmesh/region data. The avoidance-versus-pathfinding guide owns that distinction.

func _move_navigation_body(body: CharacterBody2D, agent: NavigationAgent2D, main: bool) -> void:
	if agent.is_navigation_finished():
		body.velocity = Vector2.ZERO
		return
	var next_position := agent.get_next_path_position()
	var desired := body.global_position.direction_to(next_position) * MOVE_SPEED
	if main:
		_main_desired_velocity = desired
	else:
		_crowd_desired_velocity = desired
	if agent.avoidance_enabled:
		agent.velocity = desired
	else:
		body.velocity = desired
		body.move_and_slide()


func _on_main_velocity_computed(safe_velocity: Vector2) -> void:
	_main_safe_velocity = safe_velocity
	if safe_velocity.distance_to(_main_desired_velocity) > 0.5:
		_avoidance_adjusted = true
	_main_body.velocity = safe_velocity
	_main_body.move_and_slide()

Common symptoms and the first thing to inspect

For a longer empty-path investigation, use the Godot no-path report guide or the runtime navigation debug panel.

When the built-ins stop being the whole answer

The built-in classes are enough for many games. You need another layer when the game asks for rules the representation does not own.

Do not replace a built-in because a first tutorial was awkward. Replace or wrap it when the game rule is clear and the missing contract has a name.

This article is part of the maintained Game Pathfinding guide, which routes deeper grid, graph, navmesh, tactical, crowd, and diagnostic questions to their dedicated pages.

• Multiple footprint sizes over one grid.
• Scheduled query budgets across large crowds.
• Hierarchical planning over very large worlds.
• Deterministic reservations for simultaneous turns.
• Shared flow fields or Dijkstra maps.
• Structured failure reports instead of empty arrays.
• Runtime topology edits with explicit ownership and replay.

Run the verified three-mode starter

The lazy-loaded browser export above runs the same three-mode scene without requiring the editor. It is an interaction proof, not a replacement for the downloadable project or its headless verifier.

The downloadable project puts all three representations in one Godot 4.7.1 scene. Grid mode snaps to valid cell centres. Graph mode follows six authored points and exposes the one-way 1 → 2 edge. Navmesh mode accepts any reachable point inside the polygon. The avoidance toggle adds a second agent and shows safe-velocity adjustment without changing the fixed global route.

Download the source ZIP and inspect its machine-readable verification receipt. The ZIP contains the visible scene, its controller, a standalone project.godot, and the headless verifier.

The receipt reports 15 passes on Godot 4.7.1: negative-origin conversion, valid solid and weighted routing, directional graph routing, explicit invalid-target diagnosis, synchronized navmesh queries, endpoint normalization, parent movement, avoidance behavior, scene smoke, and the extracted-package rerun.

The final ZIP is 11,188 bytes with SHA-256 8ff236be11cf03bd0f4d24b4cd98da99aafd72a74007776f118324b0058877d7. Measurement-gap: this verifies representation and behavior. It does not compare throughput or claim that one stack is universally faster.