NavigationObstacle Avoidance vs Pathfinding in Godot

The short answer

NavigationObstacle2D avoidance does not make a Godot path query reroute by itself.

It can make agents steer around an obstacle locally, but local steering is not the same as changing the global route. If a wall, tower, closed gate, or destroyed bridge should change where a path may exist, update the navigation data that the path query reads. Then prove the route changed with an explicit spawn-to-goal query.

The practical rule is simple: avoidance changed means look at velocity; path changed means look at a route query.

The same boundary applies in 3D. NavigationObstacle3D and NavigationAgent3D use Vector3 and 3D navigation maps, but avoidance is still a safe-velocity system and pathfinding is still a route-query system.

The demo for this article makes that distinction visible. A Field Pylon makes enemies bend around it, but the chip reads PATH UNCHANGED. A Wall Tower changes the route data, and the chip reads PATH CHANGED. A sealing placement is rejected with REJECTED WOULD SEAL.

Pathfinding and avoidance are different systems

Pathfinding answers: what route exists through the current navigation data? Avoidance answers: given the velocity I wanted this frame, what velocity is safer around nearby agents and avoidance obstacles?

Those two answers can disagree visually. If an enemy follows a route down the middle of a lane but avoidance pushes it around a pylon, the enemy's visible movement changed. The route did not necessarily change.

Most bugs come from treating the avoidance layer as if it had edited the route layer. In a running game, players do not see route query and safe velocity. They see a unit go around a thing and reach the goal. That only proves movement changed; it does not prove that the path query changed.

The fastest debug test: turn avoidance off

If you do not know whether your bug is pathfinding or avoidance, run one test with avoidance disabled.

If the bad behavior remains when avoidance_enabled = false, debug route data: map sync, regions, grid solids, blockers, links, layers, and the direct route query. If the behavior disappears, debug avoidance: velocity assignment, velocity_computed, radius or vertices, layers and masks, neighbor settings, and your movement code.

This is not a shipping recommendation. It is a subsystem isolation test. Turn off local steering once so you can see whether the route itself was wrong.

# One-run diagnostic switch.
# Works the same way conceptually for NavigationAgent2D and NavigationAgent3D.
agent.avoidance_enabled = false

What NavigationAgent avoidance returns

NavigationAgent avoidance is a velocity workflow. Your movement code decides a desired velocity, assigns that velocity to the navigation agent, and the NavigationServer computes a safer velocity for registered avoidance agents. The agent then emits velocity_computed(safe_velocity), and your code moves the parent with that safe velocity.

For the smaller node-level setup contract behind that loop, see NavigationAgent2D setup and common gotchas in Godot.

The important word is velocity. Avoidance does not hand you a new global path. It hands you a safer motion vector.

In the article artifact, cyan vectors show the desired velocity and amber vectors show the safe velocity. Near the field pylon, those vectors diverge. That is the teaching moment: the movement changed, but the path query still reports the same route.

# Setup once:
# agent.avoidance_enabled = true
# agent.target_position = goal_position
# agent.velocity_computed.connect(_on_velocity_computed)

func _physics_process(_delta: float) -> void:
    var desired_velocity := _direction_to_next_route_point() * speed
    agent.velocity = desired_velocity

func _on_velocity_computed(safe_velocity: Vector2) -> void:
    position += safe_velocity * get_physics_process_delta_time()

The route query is the source of truth

When you need to know whether the route changed, ask the pathfinding system directly. Do not infer path status from whether a unit reached the goal, curved around an obstacle, left a longer visible trail, or spread out near a bottleneck. Those are movement observations, and movement can be caused by avoidance.

Use an explicit route query instead. In the demo, one route-query primitive powers the status chip, the route length delta, and the rejected sealing placement. That is deliberate. If three different pieces of code decide path status three different ways, they eventually drift.

When using NavigationServer-backed map, region, or procedural navigation changes, wait for synchronization before classifying the result. Otherwise you can compare against stale navigation data.

func query_spawn_to_base_route() -> PackedVector2Array:
    return NavigationServer2D.map_get_path(
        map,
        spawn_position,
        base_position,
        true,
        NAVIGATION_LAYERS
    )

func classify_route_change(before: PackedVector2Array, after: PackedVector2Array) -> String:
    if not _route_reaches_goal(after):
        return "REJECTED WOULD SEAL"

    var delta := _path_length(after) - _path_length(before)
    if absf(delta) > 1.0:
        return "PATH CHANGED"

    return "PATH UNCHANGED"

When a NavigationObstacle can affect pathfinding

The sentence NavigationObstacle does not affect pathfinding is too broad. The accurate version is narrower: runtime avoidance behavior does not rewrite global path queries by itself.

Godot navigation obstacles can participate in more than one workflow. They can be used for avoidance, and they can also be part of navigation mesh baking or obstacle geometry workflows when configured for that purpose. Those are different contracts.

If your object is meant to block the legal route, put that rule into the navigation data used by the query. If it is only meant to influence local steering, use avoidance.

NavigationObstacle properties: what changes what

The confusing part is that the same node family has properties for two different contracts. Some settings register an obstacle with local avoidance. Others matter when navigation mesh source geometry is parsed and baked.

Read the property by asking one question: does this change the data returned by my route query, or only the velocity used by agents this frame?

2D and 3D names

The article demo is 2D, but the boundary is the same in a 3D game. The vector type and node suffix change; the diagnostic does not.

What the demo shows

The playable artifact is a small tower-defense navigation lab. It has a zig-zag lane, enemy waves, a base, two tower types, and a status chip that reports what the path query sees.

Clean resets the board to the plain zig-zag path. Pylon places a field pylon. It has a range ring, fires at enemies, and changes local movement, but it does not change the route contract. Enemies bend around it while the chip still reads PATH UNCHANGED.

Reroute places a wall tower. It is also a weapon, but it changes the walkable representation used by the route query. The current build reports about PATH CHANGED +130px, enough for the bend to be visible instead of only numeric.

Rejected stages a sealing placement. The game shows the rejected attempt and the chip reads REJECTED WOULD SEAL.

The attached scenario receipt records the same contract in JSON: Clean 1171.27px, Pylon 0.00px route delta, Reroute +129.73px, and Rejected candidate_rejected_by_runtime = true.

The full tower-defense placement transaction belongs in Stop Players from Blocking the Path in a Godot Tower Defense. This article only needs the contrast: a blocker changes route data; an avoidance obstacle changes local movement.

Static obstacles, dynamic obstacles, and jams

Avoidance is not a hard maze solver. Godot's navigation obstacle docs distinguish static and dynamic avoidance cases. Stationary avoidance obstacles are represented with vertices. Dynamic avoidance obstacles use radius and velocity. The dynamic case is useful for things that move, but it is not a reliable way to enforce hard corridors in crowded or narrow spaces.

This matters in games because avoidance can look correct in an empty test and fail under crowd pressure. A single unit may steer around a pylon. A wave of units may bunch, jitter, or squeeze badly if you are using local avoidance as if it were a route constraint.

Avoidance also has per-agent cost because registered agents participate in the RVO-style avoidance simulation. Enable it where the agent actually needs local steering; for crowd-scale pathfinding work, see the Godot 10,000-agent pathfinding benchmark.

If the design rule is you cannot pass here, do not rely on avoidance. Change the route data. If the design rule is try not to collide while passing nearby, avoidance is the right tool.

What went wrong in the demo build

The artifact had a real bug while the zig-zag version was being built. Some enemies looked like they were stuck on pylons for a long time, and a few could be pushed outside the visible board when I added many obstacles.

The root cause was not that Godot avoidance had secretly become pathfinding. The route query, the movement clamp, and the corner-progress code did not describe exactly the same corridor at the zig-zag turns. The query still had a connected route, but movement recovery was trying to keep units inside a slightly different shape. That made local avoidance look like a pathfinding failure.

The fix was to make the route probe, placement validation, unit clamp, and progress logic share the same corridor primitive, then record a small motion receipt. In the current receipt, the pylon scenario keeps the route unchanged, spawns 24 active units in the 5-second probe, records escaped_units = 0, and caps stall recovery at 0.14s.

NavigationServer sync still matters

If you change NavigationServer maps, regions, polygons, or procedural navigation data, do not assume the next route query sees the change in the same line of code.

Godot's navigation server updates are synchronized with the engine's navigation step. In practice, route queries after server-backed changes should wait for the navigation data to sync before classifying the result.

The exact wait policy depends on your architecture, but the principle is stable: do not classify a path change before the navigation system has seen the navigation change.

func _query_after_navigation_sync() -> void:
    _apply_navigation_change()
    await get_tree().physics_frame

    var route := NavigationServer2D.map_get_path(
        map,
        spawn_position,
        base_position,
        true
    )

Grid games have the same boundary

This article uses NavigationServer2D language because NavigationObstacle2D and NavigationAgent2D live in that navigation family. The boundary also exists in grid games.

For a tile tower defense, a wall tower is usually a grid occupancy change: astar_grid.set_point_solid(cell, true). That is a pathfinding change. The route query should see a different graph.

The source of the solid rule might come from a TileSet custom data layer, covered in TileMapLayer Custom Data for Walkability in Godot. The grid API details belong in AStarGrid2D in Godot 4: Complete Reference.

The concept is the same: route blocker means edit the route data; avoidance obstacle means edit local steering.

Common failure modes

My agent goes around the obstacle, so the path must have changed. Not necessarily. That can be avoidance. Query the path before and after placement to prove route change.

My NavigationObstacle2D does not block the path. If it is only configured for runtime avoidance, that is expected. Avoidance influences safe velocity. It does not make the route query treat the obstacle as a wall.

My crowd jams near an avoidance obstacle. You may be using avoidance as a hard route constraint. Local avoidance can steer around nearby objects, but it is not a guarantee that a crowd can pass a narrow space.

The path query says unchanged, but the visible route looks different. Check whether your drawing code is rendering actual query points or the enemy's recent movement trail. A movement trail shows where an agent moved. A route line should show what the path query returned.

The query changed, but the agent still follows the old path. The agent or movement controller may be following cached route points. Update the route cache after the path query changes, and make sure NavigationServer changes have synchronized before you compare results.

Implementation checklist

Use this checklist when deciding whether an object should be a path blocker or an avoidance obstacle.

1. If the object changes legal route topology, represent it in the navigation data.
2. Wait for server sync when using NavigationServer-backed changes.
3. Query the required route explicitly.
4. Reject or revert if the route contract fails.
5. Update the displayed route from the query result.
6. If the object only changes local movement, enable avoidance on the agents that need it.
7. Set desired velocity in the physics loop and move with safe_velocity.
8. Do not claim the path changed unless a route query changed.
9. Draw the path query result separately from unit trails.
10. Check whether movement clamping describes the same world as the path query.

Practical rule

Use a route query for path truth. Use avoidance velocity for movement truth.

If you remember only one sentence, make it this: a NavigationObstacle2D used for avoidance can change where the agent moves this frame, but it does not prove the route changed.