Godot Navigation Pathfinding

Navigation & Pathfinding

NavigationServer-powered pathfinding with avoidance and dynamic obstacles define robust AI movement.

Available Scripts

dynamic_nav_manager.gd

Expert runtime navigation mesh updates for moving platforms.

server_navigation_setup.gd

Low-level NavigationServer3D usage (bypassing nodes). Creates maps, regions, and registers navmeshes entirely via RID for maximum performance.

async_dynamic_baking.gd

Expert logic for bake_from_source_geometry_data_async. Parses geometry on main thread then bakes in background to prevent procedural-gen stutters.

memory_optimized_queries.gd

Pattern for reusing NavigationPathQueryParameters3D and NavigationPathQueryResult3D objects to prevent frame-by-frame GC allocations.

terrain_cost_manager.gd

Controlling pathfinding logic using region_set_enter_cost and region_set_travel_cost to define high-penalty areas (mud, fire, water).

low_level_avoidance.gd

Direct RVO (Reciprocal Velocity Obstacles) registration using server-side agents. Uses NavigationServer3D.agent_set_avoidance_callback for high-performance avoidance.

moving_obstacle_server.gd

Dynamic obstacle registration (e.g. for projectiles or rolling hazards) that push RVO agents away without full navmesh baking.

nav_link_traversal.gd

Advanced handling of NavigationLink3D for jumps, teleports, and elevators. Detects link traversal and overrides standard movement.

layer_mask_navigation.gd

Architecture for multi-type navigation (e.g. Flying vs Walking vs Swimming) using 32-bit navigation layers and bitmasks.

agent_stuck_detection.gd

Robust AI recovery logic. Detects distance-over-time stalls and triggers jitter recovery or path recalculation.

group_avoidance_formations.gd

Coordinating crowd behavior. Strategies for avoiding individual agent clumping by using leader-relative target offsets.

NEVER Do in Navigation & Pathfinding

• NEVER set `target_position` before awaiting physics frame — NavigationServer not ready in _ready()? Path fails silently. MUST call_deferred() then await get_tree().physics_frame.
• NEVER use `NavigationRegion2D.bake_navigation_polygon()` at runtime — Synchronous baking freezes game for 100+ ms. Use NavigationServer.bake_from_source_geometry_data_async() for stutter-free updates.
• NEVER forget to check `is_navigation_finished()` — Calling get_next_path_position() after reaching target = stale path, AI walks to old position.
• NEVER use `avoidance_enabled` without setting radius — Default radius = 0, agent passes through others. Set nav_agent.radius = collision_shape.radius for proper avoidance.
• NEVER poll `target_position` every frame for chase AI — Setting target 60x/sec = path recalculation spam. Use timer (0.2s intervals) or distance threshold for updates.
• NEVER assume path exists — Target unreachable (blocked by walls)? get_next_path_position() returns invalid. Check is_target_reachable() or validate path length.
• NEVER use heavy node-based navigation for thousands of simple entities — Use NavigationServer3D/2D RIDs directly to bypass node overhead.
• NEVER call `get_path()` every frame — Use query_path() with reused NavigationPathQueryResult objects to prevent massive heap allocation and GC pressure.
• NEVER leave 'enter_cost' at 0 for high-penalty areas — Use costs to make AI prefer logical paths (roads over water) instead of just shortest geometric distance.
• NEVER ignore `agent_set_avoidance_callback` — Always use the callback for safe velocity computation to avoid synchronization issues and "jittery" movement.

---

2D Navigation

# Scene structure:
# Node2D (Level)
#   ├─ NavigationRegion2D
#   │    └─ Polygon2D (draw walkable area)
#   └─ CharacterBody2D (Enemy)
#        └─ NavigationAgent2D

Setup NavigationRegion2D: 1. Add NavigationRegion2D node 2. Create New NavigationPolygon 3. Click "Edit" → Draw walkable area 4. Bake navigation mesh

Basic AI Movement

extends CharacterBody2D

@onready var nav_agent := $NavigationAgent2D
@export var speed := 200.0

var target_position: Vector2

func _ready() -> void:
    # Wait for navigation to be ready
    call_deferred("setup_navigation")

func setup_navigation() -> void:
    await get_tree().physics_frame
    nav_agent.target_position = target_position

func _physics_process(delta: float) -> void:
    if nav_agent.is_navigation_finished():
        return
    
    var next_position := nav_agent.get_next_path_position()
    var direction := (next_position - global_position).normalized()
    
    velocity = direction * speed
    move_and_slide()

func set_target(pos: Vector2) -> void:
    target_position = pos
    nav_agent.target_position = pos

NavigationAgent Properties

# Path recalculation
nav_agent.path_desired_distance = 10.0
nav_agent.target_desired_distance = 10.0

# Avoidance
nav_agent.radius = 20.0
nav_agent.avoidance_enabled = true

# Performance
nav_agent.path_max_distance = 500.0

Advanced Patterns

Chase Player

extends CharacterBody2D

@onready var nav_agent := $NavigationAgent2D
@export var speed := 150.0
@export var chase_range := 300.0

var player: Node2D

func _physics_process(delta: float) -> void:
    if not player:
        return
    
    var distance := global_position.distance_to(player.global_position)
    
    if distance <= chase_range:
        nav_agent.target_position = player.global_position
        
        if not nav_agent.is_navigation_finished():
            var next_pos := nav_agent.get_next_path_position()
            var direction := (next_pos - global_position).normalized()
            velocity = direction * speed
            move_and_slide()

Patrol Points

extends CharacterBody2D

@onready var nav_agent := $NavigationAgent2D
@export var patrol_points: Array[Vector2] = []
@export var speed := 100.0

var current_point_index := 0

func _ready() -> void:
    if patrol_points.size() > 0:
        nav_agent.target_position = patrol_points[0]

func _physics_process(delta: float) -> void:
    if nav_agent.is_navigation_finished():
        _go_to_next_patrol_point()
        return
    
    var next_pos := nav_agent.get_next_path_position()
    var direction := (next_pos - global_position).normalized()
    velocity = direction * speed
    move_and_slide()

func _go_to_next_patrol_point() -> void:
    current_point_index = (current_point_index + 1) % patrol_points.size()
    nav_agent.target_position = patrol_points[current_point_index]

3D Navigation

extends CharacterBody3D

@onready var nav_agent := $NavigationAgent3D
@export var speed := 5.0

func _physics_process(delta: float) -> void:
    if nav_agent.is_navigation_finished():
        return
    
    var next_position := nav_agent.get_next_path_position()
    var direction := (next_position - global_position).normalized()
    
    velocity = direction * speed
    move_and_slide()

Dynamic Obstacles

# Add NavigationObstacle2D to moving objects
# Scene:
# CharacterBody2D (MovingPlatform)
#   └─ NavigationObstacle2D

# Navigation automatically updates around it

Signals

func _ready() -> void:
    nav_agent.velocity_computed.connect(_on_velocity_computed)
    nav_agent.navigation_finished.connect(_on_navigation_finished)

func _on_velocity_computed(safe_velocity: Vector2) -> void:
    velocity = safe_velocity
    move_and_slide()

func _on_navigation_finished() -> void:
    print("Reached destination")

Best Practices

1. Defer Navigation Setup

# ✅ Good - wait for navigation to initialize
func _ready() -> void:
    call_deferred("setup_nav")

func setup_nav() -> void:
    await get_tree().physics_frame
    nav_agent.target_position = target

2. Check if Path Exists

if not nav_agent.is_target_reachable():
    print("Target unreachable!")

3. Use Avoidance for Crowds

nav_agent.avoidance_enabled = true
nav_agent.radius = 20.0
nav_agent.max_neighbors = 10

Expert Navigation Architectures

1. Crowd Collision (Server-Side Avoidance)

For massive crowds, bypass node-based overhead by communicating directly with NavigationServer3D. Configure native server-side agents with RVO (Reciprocal Velocity Obstacle) parameters like neighbor_distance and max_neighbors.

class_name CrowdAgent3D extends CharacterBody3D
## A completely node-less avoidance agent using the NavigationServer3D API.

@export var max_speed: float = 4.0
var _server_agent_rid: RID

func _ready() -> void:
    # Create the agent on the server and assign it to the default map.
    _server_agent_rid = NavigationServer3D.agent_create()
    NavigationServer3D.agent_set_map(_server_agent_rid, get_world_3d().get_navigation_map())
    
    # Enable avoidance and set physical dimensions.
    NavigationServer3D.agent_set_avoidance_enabled(_server_agent_rid, true)
    NavigationServer3D.agent_set_radius(_server_agent_rid, 0.5)
    NavigationServer3D.agent_set_max_speed(_server_agent_rid, max_speed)
    
    # Crowd Tuning: Configure neighbor detection.
    NavigationServer3D.agent_set_neighbor_distance(_server_agent_rid, 50.0)
    NavigationServer3D.agent_set_max_neighbors(_server_agent_rid, 20)
    
    # Time horizons: How far ahead to predict agent/obstacle collisions.
    NavigationServer3D.agent_set_time_horizon_agents(_server_agent_rid, 1.0)
    NavigationServer3D.agent_set_time_horizon_obstacles(_server_agent_rid, 0.5)
    
    # Bind callback to safely receive computed velocity.
    NavigationServer3D.agent_set_avoidance_callback(_server_agent_rid, _on_velocity_computed)

func _physics_process(_delta: float) -> void:
    # Determine desired velocity towards target.
    var preferred_velocity: Vector3 = Vector3.FORWARD * max_speed 
    NavigationServer3D.agent_set_velocity(_server_agent_rid, preferred_velocity)

func _on_velocity_computed(safe_velocity: Vector3) -> void:
    velocity = safe_velocity
    move_and_slide()

func _exit_tree() -> void:
    if _server_agent_rid.is_valid():
        NavigationServer3D.free_rid(_server_agent_rid)

2. Projected Obstacles (Dynamic NavMesh Carving)

To remove areas from the navigation mesh dynamically (e.g., impact craters), inject a "Projected Obstruction" into the NavigationMeshSourceGeometryData3D. Setting carve to true cuts a hole precisely matching the geometry.

class_name NavMeshCarver3D extends Node3D
## Dynamically carves holes into the NavMesh for permanent environmental changes.

@export var nav_region: NavigationRegion3D

var _source_geometry := NavigationMeshSourceGeometryData3D.new()
var _is_baking: bool = false

func carve_projectile_impact(impact_pos: Vector3, radius: float) -> void:
    if _is_baking: return
    _is_baking = true
    _source_geometry.clear()
    
    # Parse existing geometry and add a carved obstruction.
    NavigationServer3D.parse_source_geometry_data(nav_region.navigation_mesh, _source_geometry, nav_region)
    
    var outline := PackedVector3Array([
        impact_pos + Vector3(-radius, 0, -radius),
        impact_pos + Vector3(radius, 0, -radius),
        impact_pos + Vector3(radius, 0, radius),
        impact_pos + Vector3(-radius, 0, radius)
    ])
    
    _source_geometry.add_projected_obstruction(outline, impact_pos.y, 10.0, true)
    
    # Bake asynchronously to prevent frame stuttering.
    NavigationServer3D.bake_from_source_geometry_data_async(
        nav_region.navigation_mesh, 
        _source_geometry, 
        _on_bake_finished
    )

func _on_bake_finished() -> void:
    NavigationServer3D.region_set_navigation_mesh(nav_region.get_rid(), nav_region.navigation_mesh)
    _is_baking = false

3. NavMesh Performance Profiler (Bake-Time Benchmarks)

Benchmark bake times and topological complexity (polygon/edge counts) using Time.get_ticks_usec() and NavigationServer3D.get_process_info().

class_name NavMeshProfiler extends Node
## A benchmarking tool to validate NavMesh complexity and bake times.

func run_benchmark(nav_mesh: NavigationMesh, source_geometry: NavigationMeshSourceGeometryData3D) -> void:
    var start_time_usec: float = Time.get_ticks_usec()
    
    # Synchronous bake for linear benchmarking (main thread stall expected).
    NavigationServer3D.bake_from_source_geometry_data(nav_mesh, source_geometry)
    
    var elapsed_ms: float = (Time.get_ticks_usec() - start_time_usec) / 1000.0
    var poly_count: int = NavigationServer3D.get_process_info(NavigationServer3D.INFO_POLYGON_COUNT)
    var edge_count: int = NavigationServer3D.get_process_info(NavigationServer3D.INFO_EDGE_COUNT)
    
    print("Bake Time: %f ms | Polygons: %d | Edges: %d" % [elapsed_ms, poly_count, edge_count])

Reference

• Godot Docs: Navigation

Related

• Master Skill: godot-master