AStarGrid2D in Godot 4: Complete Reference | Vav Labs Skip to main content<br>Get in touch
Back to blog<br>Interactive demo and data<br>Try the interactive playground<br>AStarGrid2D interactive playground<br>Browser playground mode for the article's visual gotchas: drag start and goal, paint solid or weighted cells, switch diagonal modes, flip jumping_enabled, and compare heuristics.<br>Open AStarGrid2D playground<br>AStarGrid2D is simple. The edge cases aren't.<br>AStarGrid2D is Godot's grid-based A* pathfinder for 2D games. You give it a rectangular cell region, call update(), mark blocked cells as solid, assign terrain costs with weight_scale, and ask for a path in grid coordinates or world positions. It's the right default for tile-based movement. It isn't a replacement for NavigationServer2D, crowd planning, clearance maps, or a production navigation workflow.<br>AStarGrid2D is a small class. You can read the whole API page in ten minutes, and most people do. Then they ship a grid where the path comes back empty, units cut through wall corners, or the route ignores the road and walks through the swamp. None of that is a Godot conspiracy. It's the gap between knowing the method names and knowing which small handful of settings decide the behavior.<br>So this is the page I'd keep open in a second tab. It walks through every property and method that changes behavior, with the gotcha attached to each one, and it ends with the question people actually came for: do I even want AStarGrid2D, or did I want NavigationServer2D?<br>If something here is wrong or out of date for your Godot version, I want to know. The API has moved across Godot 4.x, and stale navigation advice turns quickly into a debugging session.
Version notes for Godot 4.x<br>Godot's AStarGrid2D API has stayed recognizable, but a few details changed enough that older tutorials can mislead you.<br>If you're publishing code meant for current Godot, use region, not size. If you're reading an older tutorial that calls update() after marking obstacles, read the setup section twice.<br>Godot versionWhat matters for AStarGrid2D 4.0The docs use size = Vector2i(...) in the basic setup. 4.1+region: Rect2i is the preferred grid shape property; size is deprecated. 4.2+fill_solid_region() and fill_weight_scale_region() are available in the docs. 4.3+cell_shape adds square, isometric-right, and isometric-down cell placement. get_id_path() and get_point_path() support allow_partial_path. 4.7 stableCurrent stable docs as of 2026-06-21. Use these for final publish verification.
The setup that runs - and the order that matters<br>Here is the smallest setup that works. The order matters:<br>var astar := AStarGrid2D.new()<br>astar.region = Rect2i(0, 0, 64, 64) # 64x64 cells, origin at (0, 0)<br>astar.cell_size = Vector2(16, 16) # world units per cell<br>astar.update() # builds the grid
var cells: Array[Vector2i] = astar.get_id_path(Vector2i(0, 0), Vector2i(10, 8))<br>var points: PackedVector2Array = astar.get_point_path(Vector2i(0, 0), Vector2i(10, 8))<br>Apply solids and weights after update()<br>update() is the line everyone forgets. AStarGrid2D doesn't rebuild itself after shape changes until you ask it to. Set the region, set the cell size, call update(), then query. Forget it and you'll usually get an empty array with no useful gameplay explanation.<br>But the more expensive mistake is the opposite one: calling update() after you mark obstacles. update() rebuilds the grid and clears point data, including solidity and weight scales. The safe setup pattern is:<br>astar.region = Rect2i(0, 0, 64, 64)<br>astar.cell_size = Vector2(16, 16)<br>astar.update()
# Apply point data after update().<br>for cell in wall_cells:<br>astar.set_point_solid(cell, true)
for cell in mud_cells:<br>astar.set_point_weight_scale(cell, 4.0)<br>The rule worth memorizing<br>Grid shape changes need update(); point data is applied after update(). region, cell_size, offset, and cell_shape are shape or placement changes. Solids and weights are point data. If you change the shape later, replay the solids and weights from your own source of truth.
AStarGrid2D API cheat sheet<br>Use this as the quick reference before the longer explanations below.<br>APIWhat it doesNeeds update()?Gotcha regionDefines the rectangular cell areaYesPreferred over deprecated size cell_sizeMaps cell coordinates to world positionsYesAffects get_point_path(), not which cells are chosen offsetShifts returned world positionsYesUseful for visual alignment cell_shapeSquare, isometric-right, or isometric-down point placementYesPresent in 4.3+ docs set_point_solid()Blocks or unblocks one cellNoCall after update(); guard bounds fill_solid_region()Blocks or unblocks a rectangle of cellsNoPresent in 4.2+ docs set_point_weight_scale()Sets terrain traversal cost multiplierNo0.0 is allowed; negative values are rejected fill_weight_scale_region()Sets weight over a rectangleNoPresent in 4.2+ docs diagonal_modeControls diagonal neighbors and corner cuttingNoSet before querying; pair with the right heuristic...