godot-navigation-pathfinding

NEVER Do in Navigation & Pathfinding

• NEVER set targetposition before awaiting physics frame — NavigationServer not ready in ready()? Path fails silently. MUST calldeferred() then await gettree().physics_frame.
• NEVER use NavigationRegion2D.bakenavigationpolygon() at runtime — Synchronous baking freezes game for 100+ ms. Use NavigationServer.bakefromsourcegeometrydata_async() for stutter-free updates.
• NEVER forget to check isnavigationfinished() — Calling getnextpath_position() after reaching target = stale path, AI walks to old position.
• NEVER use avoidanceenabled without setting radius — Default radius = 0, agent passes through others. Set navagent.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)? getnextpathposition() returns invalid. Check istarget_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 getpath() every frame — Use querypath() 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 agentsetavoidance_callback — Always use the callback for safe velocity computation to avoid synchronization issues and "jittery" movement.

Decision Tree → Scripts

MANDATORY for the chosen path. Do NOT Load editor-intro / Official Docs bootstrap recipes from this skill body (use Reference links when you need first-time region setup).

Chase / Retarget Rule (never contradict NEVER)

Do not assign target_position every physics frame. Retarget on a timer (~0.2s) or when the chased body moves beyond a distance threshold:

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

func _physics_process(_delta: float) -> void:
    var desired := prey.global_position
    if desired.distance_to(_last_target) >= RETARGET_DIST:
        nav_agent.target_position = desired
        _last_target = desired
    if nav_agent.is_navigation_finished():
        return
    var next := nav_agent.get_next_path_position()
    velocity = (next - global_position).normalized() * speed
    move_and_slide()

Available Scripts

[asyncdynamicbaking.gd](scripts/asyncdynamicbaking.gd)

bakefromsourcegeometrydata_async — parse on main, bake off-thread.

[agentstuckdetection.gd](scripts/agentstuckdetection.gd)

Distance-over-time stall detection and recovery.

[lowlevelavoidance.gd](scripts/lowlevelavoidance.gd)

Server-side RVO agents + avoidance callbacks.

[dynamicnavmanager.gd](scripts/dynamicnavmanager.gd)

Runtime navmesh updates for moving platforms.

[servernavigationsetup.gd](scripts/servernavigationsetup.gd)

Node-less maps/regions via NavigationServer RIDs.

[memoryoptimizedqueries.gd](scripts/memoryoptimizedqueries.gd)

Reuse path query parameter/result objects.

[terraincostmanager.gd](scripts/terraincostmanager.gd)

entercost / travelcost for preferred routes.

[movingobstacleserver.gd](scripts/movingobstacleserver.gd)

Dynamic RVO obstacles without full rebake.

[navlinktraversal.gd](scripts/navlinktraversal.gd)

NavigationLink jump/teleport/elevator handling.

[layermasknavigation.gd](scripts/layermasknavigation.gd)

Multi-domain navigation layers (walk/fly/swim).

[groupavoidanceformations.gd](scripts/groupavoidanceformations.gd)

Leader-relative offsets to reduce clumping.

[smartnavigationagent.gd](scripts/smartnavigationagent.gd)

Production NavigationAgent wrapper patterns.

Expert Pointers

• Prefer Official Docs intros for first NavigationRegion bake UI; this skill owns async bake, server RVO, costs, and stuck recovery.
• Thousands of simple agents → RID server path ([servernavigationsetup.gd](scripts/servernavigationsetup.gd) + [lowlevelavoidance.gd](scripts/lowlevelavoidance.gd)), not one NavigationAgent node each.
• Crowd RVO / carve / bake benchmark samples → [crowdagent3d.gd](scripts/crowdagent3d.gd), [navmeshcarver3d.gd](scripts/navmeshcarver3d.gd), [navmeshprofiler.gd](scripts/navmeshprofiler.gd)

Deep dives (on demand)

• 2D/3D chase, patrol, avoidance signals → [agent-movement-patterns.md](references/agent-movement-patterns.md)
• Server RVO crowds, projected carving, bake benchmarks → [expert-nav-architectures.md](references/expert-nav-architectures.md)

Reference

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

Official Documentation

• 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 — targetposition, getnextpathposition, avoidance radius, and velocity_computed safe-velocity flow.
• Using NavigationServers — RID maps/regions/agents for node-less crowds and custom server setups.
• 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.
• 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-characterbody-2d — Path corners become CharacterBody velocity via moveandslide; 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 + bakefromsourcegeometrydata_async after generation.
• godot-performance-optimization — Crowds push toward server RIDs, query reuse, and avoidance tuning called out in this skill.

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.