godot-ai-navigation

Decision Trees (MANDATORY script triggers)

1. Node agent vs NavigationServer RID

| Signal | Choice | Pathfinding script (MANDATORY read) |

| :--- | :--- | :--- |

| 2D top-down / side-scroller, < ~50 agents, editor-tweakable | NavigationAgent2D on CharacterBody2D | smart_navigation_agent.gd |

| 3D floor/slope nav, < ~50 agents, designer-placed regions | NavigationAgent3D on CharacterBody3D | Same script (3D branch); pair with godot-physics-3d for body collision |

| Hundreds–thousands of simple movers (2D or 3D) | RID agents on NavigationServer | server_navigation_setup.gd + low_level_avoidance.gd |

| Agents stuck / jittering | Stuck recovery before retarget spam | agent_stuck_detection.gd |

2. Bake vs obstacle

| Signal | Choice | Pathfinding script (MANDATORY read) |

| :--- | :--- | :--- |

| Walkable geometry changed (proc gen, doors) | Async parse + bake | async_dynamic_baking.gd |

| Moving platform / shifting region | Dynamic region manager | dynamic_nav_manager.gd |

| Projectile / rolling hazard pushing agents | RVO obstacle (no full rebake) | moving_obstacle_server.gd |

| Prefer roads over mud/water | Region enter/travel costs | terrain_cost_manager.gd |

3. Layers, links, crowds

| Signal | Choice | Pathfinding script (MANDATORY read) |

| :--- | :--- | :--- |

| Walk / fly / swim (or faction) filters | Navigation layers bitmasks | layer_mask_navigation.gd |

| Jump / teleport / elevator edges | NavigationLink traversal | nav_link_traversal.gd |

| Formation / anti-clump crowds | Leader-relative offsets | group_avoidance_formations.gd |

| Hot-path query allocs | Reuse query parameter/result objects | memory_optimized_queries.gd |

Do NOT Load scripts outside the chosen row (e.g. skip RID/server scripts for a single designer-tuned agent; skip async bake when only RVO obstacles move).

4. Chase / patrol retarget policy (AI layer)

• Chase: Retarget on timer (~0.2s) or distance threshold — never assign target_position every physics frame.
• Patrol: Advance waypoint only when is_navigation_finished() and is_target_reachable(); on unreachable, pick next or repath.
• State ownership: Patrol/chase/search transitions belong in godot-state-machine-advanced; this skill only decides how to retarget once a state asks for a destination.

Patrol state handoff (call site): in the patrol state's _physics_process, when the agent finishes a waypoint, call retarget_if_needed(next_waypoint) — do not set target_position directly from the state machine root.

# PatrolState.gd — state machine owns transitions; this skill owns retarget policy
func _physics_process(_delta: float) -> void:
	if nav_agent.is_navigation_finished() and nav_agent.is_target_reachable():
		_ai_nav.retarget_if_needed(_waypoints[_index])
		_index = (_index + 1) % _waypoints.size()

# Threshold retarget — AI policy, not per-frame path spam
const RETARGET_DIST := 1.5
var _last_target: Vector3

func retarget_if_needed(desired: Vector3) -> void:
	if desired.distance_to(_last_target) < RETARGET_DIST:
		return
	nav_agent.target_position = desired
	_last_target = desired

NEVER Do in AI Navigation

• NEVER set target_position before awaiting physics frame — MUST call_deferred() then await get_tree().physics_frame.
• NEVER use synchronous runtime bake — Use bake_from_source_geometry_data_async via pathfinding async_dynamic_baking.gd.
• NEVER poll chase targets every frame — Path recalculation spam.
• NEVER invent local duplicate nav scripts here — Implement from godot-navigation-pathfinding only.
• NEVER ignore is_target_reachable() / stuck recovery — Unreachable or stalled agents need policy (agent_stuck_detection.gd).
• NEVER leave avoidance radius at 0 when avoidance_enabled — Agents pass through each other.
• NEVER call get_path() every frame — Reuse path query objects (memory_optimized_queries.gd).

Fallback (godot-navigation-pathfinding not installed)

If the sibling skill is unavailable, use this minimal stuck-recovery checklist — do not paste full bake/RID tutorials from memory:

1. Defer first target_position with call_deferred + await get_tree().physics_frame.
2. Retarget on timer (~0.2s) or distance threshold — never every frame.
3. On stall: if !nav_agent.is_target_reachable() or velocity ≈ 0 for N frames, skip waypoint or call get_next_path_position() recovery.
4. Avoidance: set radius > 0 when avoidance_enabled.
5. Re-install godot-navigation-pathfinding before shipping async bake or RID crowds.

Expert insights (WHY — keep in body)

• Deferred first target — WHY: NavigationAgent maps/regions are not ready in _ready(). call_deferred + await physics_frame prevents first-path failure.
• Retarget policy — WHY: per-frame target_position rebakes paths and spikes CPU. Timer (~0.2 s) or distance threshold only.
• Unreachable waypoints — WHY: patrol loops stall forever without is_target_reachable() + skip/repath policy.
• Avoidance radius 0 — WHY: enabled avoidance with zero radius disables separation; agents stack.

Golden Path

1. Classify the AI need with the decision trees above.
2. MANDATORY open each linked pathfinding script for the chosen rows — Do NOT Load the rest of that skill's scripts.
3. Wire retarget/state policy here (timer/threshold + state machine), movement via CharacterBody.
4. Do NOT Load Official Docs intro recipes unless first-time region bake UI is required (use Reference links).

Deep recipes (on demand)

| Topic | Reference / script |

|-------|-------------------|

| Chase / patrol / crowd AI recipes | [ai-movement-recipes.md](references/ai-movement-recipes.md) |

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Navigation overview — Tutorial index for maps, regions, agents, meshes, links, obstacles, and performance before diving into class pages.
• Navigation introduction (2D) — Minimal NavigationRegion2D + NavigationAgent2D setup, baking walkable polygons, and first-frame readiness.
• Navigation introduction (3D) — Parallel 3D bootstrap with NavigationRegion3D / NavigationAgent3D and mesh baking expectations.
• Using NavigationAgents — target_position, get_next_path_position, avoidance radius, and velocity_computed safe-velocity flow for chase/patrol AI.
• Using NavigationServers — RID maps/regions/agents for node-less crowds and custom server setups at scale.
• Using navigation meshes — Parse/bake source geometry, async baking, and projected obstructions for dynamic carving.
• Using NavigationRegions — Region ownership, enter/travel costs, and chunked/runtime region updates for terrain penalties.
• Using NavigationObstacles — RVO push obstacles vs bake-time carving without full remesh every frame.
• Using NavigationLinks — Jump/teleport/elevator edges and manual link traversal on agents.
• Using navigation layers — 32-bit layer bitmasks for walk/fly/swim (or faction) path filters.
• Using navigation path query objects — Reuse NavigationPathQueryParameters/Result to avoid per-frame GC in crowds.
• Optimizing navigation performance — Bake cost, agent/obstacle counts, and server query budgets for large AI populations.

Related Skills

Prerequisites

• godot-navigation-pathfinding — MANDATORY authoritative NavigationServer scripts (async bake, RID setup, query reuse, stuck detection); this skill has no local scripts/.
• godot-characterbody-2d — Path corners become CharacterBody velocity via move_and_slide; agent scripts assume a body parent.
• godot-2d-physics — Collision layers/shapes still block bodies; navmesh is not a physics substitute for walls and triggers.
• godot-physics-3d — 3D agents share the same split: NavigationServer paths vs RigidBody/CharacterBody collision and slopes.

Complements

• godot-raycasting-queries — Line-of-sight, aim cones, and hit prediction sit beside pathfinding for chase/stealth AI.
• godot-state-machine-advanced — Patrol/chase/search states own when to retarget NavigationAgent and when to stop.
• godot-tilemap-mastery — TileMap/TileSet geometry often feeds NavigationPolygon baking in 2D levels.
• godot-3d-world-building — Static meshes and GridMaps are the usual NavigationMesh source geometry for baked regions.
• godot-procedural-generation — Runtime layouts require parse + bake_from_source_geometry_data_async after generation.
• godot-signal-architecture — velocity_computed / navigation_finished wiring stays clean when AI systems emit typed signals instead of polling.

Downstream / consumers

• godot-genre-rts — Unit move commands and RVO crowds consume NavigationAgent/Server patterns directly.
• godot-genre-tower-defense — Lane/path enemies and dynamic blockers depend on regions, costs, and obstacle updates.
• godot-genre-stealth — Guard patrols and investigate points are NavigationAgent routes gated by detection state.
• godot-combat-system — Engage/kite/flank movement issues new targets and stuck recovery on top of paths.
• godot-monte-carlo-balancer — Simulate chase reachability, travel-time bands, and crowd pressure when tuning AI difficulty.

Master

• godot-master — Library router and mirrored module entry for this Domain Skill.