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.