Navigation meshes, path corridors, and local avoidance

A route is not movement

A successful path query does not mean an agent can execute every movement the game requests. Navigation describes allowed travel, steering chooses an immediate direction, and locomotion applies that choice. Debug these responsibilities separately before repeatedly rebuilding a mesh to solve a movement problem.

Corridors and avoidance

Detour represents a path as a polygon corridor that can adapt as the agent and its target move. Local updates have limits and may require replanning. [1] Local avoidance adjusts immediate velocity around neighbors. Godot explicitly separates its avoidance space from navigation meshes and physics collision; an avoidance radius describes the avoidance body. [2]

Worked example

Consider an illustrative circular agent with radius 0.3 m approaching a doorway 0.5 m wide. Its diameter is 0.6 m, so the physical opening is too narrow even if a centerline path crosses it. Changing steering priorities cannot create the missing clearance. The navigation representation must match the agent's movement dimensions and required margin.

Widen the doorway to 0.9 m. One such agent can geometrically fit, but two cannot pass side by side because their combined diameters total 1.2 m, before margins. If agents approach from opposite directions, local velocity adjustments may stall them. A reservation, yielding rule, or alternate route is a gameplay solution to this bottleneck. It should be explicit rather than hidden inside a growing avoidance radius.

Practical workflow

Establish agent radius, height, slope, and step capabilities together with navigation-build settings. Test one unobstructed route first. Then visualize the chosen polygons, steering target, preferred velocity, avoidance output, and actual displacement in distinct colors.

Feed actual movement back into the path-following state. Define when a changed door, removed polygon, teleport, or persistent lack of progress triggers route validation or replanning. A requested destination may be projected onto a reachable surface; report whether the agent reached the requested goal or only that substitute.

Limits and diagnostics

Avoidance does not guarantee global progress, solve all crowds, or repair a route through a blocked corridor. Conversely, expensive replanning every frame can mask a steering or locomotion defect. Track route-query cost, avoidance cost, waiting time, and completion separately.

Test narrow bidirectional passages, moving goals, mixed agent sizes, and dynamic closures. Keep collision geometry, navigation clearance, and avoidance dimensions intentionally consistent without assuming they are the same setting. If the game requires queues or right-of-way, encode that policy and expose it in debugging tools.

Sources

[1] Path corridor reference — Recast Navigation contributors.

[2] Using NavigationAgents — Godot Engine documentation.