Godot's NavigationObstacle2D has two modes (and other NavigationServer2D gotchas)

Godot's NavigationServer2D is powerful and quietly confusing. Most of the pain isn't the API — it's a handful of distinctions that look similar and behave nothing alike. The ones that eat afternoons:

• NavigationObstacle2D has two modes, and people conflate them. avoidance_enabled makes your agents steer around an obstacle, but the path query still runs straight through it — so your tower-defense blocker doesn't block the route. affect_navigation_mesh is the other one: it carves the obstacle into the navmesh at bake time, and then the path reroutes.
• The empty path. A query returns nothing even though the scene looks walkable — usually because the navmesh was never baked. It's the NavigationServer2D version of forgetting AStarGrid2D.update().
• Map-sync timing. NavigationServer changes apply at the end of the physics frame. Query in _ready() or right after editing nav data and you get a stale or empty result — then blame the agent.
• NavigationAgent2D isn't the map. The agent is a node-level helper that consumes navigation data; it doesn't make the map valid by itself.

So I wrote the full guide — regions, agents, direct path queries, both obstacle modes, links, and the map-sync trap — checked every claim against the docs and the C++ source, and built an interactive playground for the gotchas. (It's a browser illustration of how the system behaves, not the engine running, and there's no benchmark here — it's a guide, not a measurement.)

Full guide + playground: https://vav-labs.com/blog/navigationserver2d-godot-complete-guide/

If any of it's wrong or out of date for your version, tell me — the navigation API has moved across Godot 4.x, and I'd rather fix it than leave you debugging my mistake.