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.
