Godot's AStarGrid2D is a ten-minute read and a month of gotchas. The API page is small, you skim it, and then your path comes back empty, your units cut through wall corners, or your weighted swamp gets ignored. None of it is a bug. It's the gap between knowing the method names and knowing which handful of settings actually decide the behavior.
The five that get almost everyone:
- You forget
update(). Change the region or cell size, skip the rebuild, and you get an empty array with no error.
update() wipes your point data. It clears every solid cell and weight, so you have to set those after you call it.- Diagonal corner-cutting.
DIAGONAL_MODE_ALWAYS lets units squeeze diagonally between two walls. You usually want ONLY_IF_NO_OBSTACLES.
jumping_enabled silently ignores weight scale. Turn on JPS and your weighted terrain stops mattering. It's in the docs. People still lose an afternoon to it.- Manhattan overestimates with diagonals. On an 8-direction grid it counts a diagonal as two steps, so your "shortest" path isn't. Reach for Octile.
So I wrote the reference I actually wanted (every property and method, the gotcha attached to each, version-honest across Godot 4.0 → 4.7, checked against the official docs and the C++ source), and built an interactive sandbox for the parts you have to see: drag the goal, paint solid and weighted cells, flip diagonal modes, toggle jumping, and watch the path recompute live. (It's a browser illustration of how AStarGrid2D behaves, not the engine itself running in a tab.)
Full reference and the sandbox: https://vav-labs.com/blog/astargrid2d-complete-reference/
If any of it's wrong or out of date for your version, tell me. The API moved across Godot 4.x, and I'd rather fix it than leave you debugging my mistake.
