godot-ai-navigation

Decision Trees (MANDATORY script triggers)

1. Node agent vs NavigationServer RID

2. Bake vs obstacle

3. Layers, links, crowds

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)

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.