godot-navigation-ai
Skill2 starsChanged 4 months agoMITView on GitHub
Godot 4.x pathfinding and movement-intent AI using NavigationRegion2D, NavigationAgent2D, avoidance, RTS unit selection, formations, target acquisition, and chase states. Use when requests concern navigation maps, unreachable targets, path jitter, local avoidance, unit commands, or crowd movement; defer damage and combat mechanics to godot-2d-gameplay.
In this repository14 other files it gives its agents.
- game-balanceSkill
- game-design-vocabularySkill
- gamedev-mathSkill
- game-mechanics-designSkill
- game-systems-designSkill
- godot-2d-gameplaySkill
- godot-3d-gameplaySkill
- godot-desktop-appsSkill
- godot-fundamentalsSkill
- godot-game-architectureSkill
- godot-mobileSkill
- godot-procedural-generationSkill
- godot-programming-patternsSkill
- godot-uiSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. About 0 are common, 10 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Treat pathfinding, movement, selection, commands, targeting, combat, and local avoidance as separate systems with explicit handoffs.
- Very specific: line 23
Search for direct position writes, move_and_slide(), target updates, physics queries, and navigation-server calls.
- Very specific: line 30
Do not replace a working AStarGrid2D grid with a navigation mesh without a gameplay reason.
- Very specific: line 44
Use AStarGrid2D for strict cell movement or cheap grid costs.
- Very specific: line 57
Implement one unit and one static destination: Call get_next_path_position() once per physics tick until navigation finishes.
- Very specific: line 61
Add selection behind UI: Use _unhandled_input() or equivalent event routing so gameplay does not consume clicks handled by Controls.
- Distinctive: line 68
Scale test: Verify unreachable targets, narrow passages, opposing flows, formations, target death, pause, and the maximum expected crowd.
- Very specific: line 85
Update a moving target's path only after it moved a threshold or a repath interval elapsed.
- Distinctive: line 88
Keep selected units in a typed collection and remove invalid/freed entries.
- Very specific: line 92
Use game delta or Timer for attack cadence and scans.
- Distinctive: line 94
Use acquire/disengage hysteresis so targets do not toggle at one exact radius.
- Very specific: line 111
Keep path_max_distance sensible and test map boundaries.
- Distinctive: line 117
Test a reachable point, an unreachable point, a point outside the map, and a destination across every intended link/layer boundary.
- Distinctive: line 121
Test selection and drag selection under camera pan/zoom and over UI.
- Distinctive: line 122
Test move, attack, cancel, additive selection, target death, friendly clicks, and commands issued while units are moving.
- Distinctive: line 124
Test avoidance with crossing streams and dense formations, then profile at the target unit count.
- Distinctive: line 126
Run existing tests and a headless parse/import check with the inspected Godot version when available.
- Distinctive: line 149
Crowds stall: all units share one destination, horizons/radii are too conservative, or the map has a bottleneck narrower than the formation.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Godot Navigation and AI
Treat pathfinding, movement, selection, commands, targeting, combat, and local avoidance as separate systems with explicit handoffs.
Inspect the Project First
- Locate
project.godot, read its Godot feature/version tag, and confirm the runtime version when a project-compatible executable is available. - Inspect navigation regions, polygons, tile navigation data, links, obstacles,
maps, layers, and existing
NavigationAgent2Dsettings. - Inspect unit roots, collision shapes, teams, groups/registries, selection UI, input actions, camera transforms, combat APIs, and pause behavior.
- Search for direct position writes,
move_and_slide(), target updates, physics queries, and navigation-server calls. Identify which script currently owns movement. - Preserve existing scene inheritance and command interfaces. Prefer
CharacterBody2DplusNavigationAgent2Dfor new colliding units when the inspected project supports that architecture.
Do not replace a working AStarGrid2D grid with a navigation mesh without a
gameplay reason. Do not migrate APIs solely to match these examples.
Keep the Models Distinct
- A navigation map describes traversable polygons and links.
NavigationAgent2Drequests and advances a path, but never moves its parent.CharacterBody2Downs collision-aware movement and final velocity.- Static geometry belongs in baked or tile-provided navigation data.
- Avoidance modifies desired velocity around moving agents and avoidance obstacles; it does not change the path or understand physics collision.
- Selection identifies command recipients. Commands set intent; AI executes it.
- Combat range, line of sight, cooldown, and team rules are not pathfinding.
Use AStarGrid2D for strict cell movement or cheap grid costs. Use navigation
maps and agents for continuous movement through polygonal walkable space.
Implementation Workflow
- Define locomotion constraints. Record unit radius, speed, stopping distance, legal terrain, static/dynamic obstacles, and expected unit count.
- Build one valid map. Author a
NavigationRegion2Dwith aNavigationPolygon, or use inspected TileSet navigation data. Verify debug geometry before adding AI. - Wait for synchronization. Navigation-server changes usually become
usable on a later physics update. Do not assume a path queried in
_ready()is valid. - Implement one unit and one static destination. Call
get_next_path_position()once per physics tick until navigation finishes. - Add explicit commands. A move order clears attack intent; an attack order owns a valid hostile target; stop/cancel clears both.
- Add selection behind UI. Use
_unhandled_input()or equivalent event routing so gameplay does not consume clicks handled by Controls. - Add target/combat states. Acquire on a timer or registry event, chase with throttled repaths, stop in range, attack on game-time cooldown, and recover safely when the target leaves or dies.
- Enable avoidance only where needed. Connect
velocity_computed, submit desired velocity, and apply the returned safe velocity through the body. - Scale test. Verify unreachable targets, narrow passages, opposing flows, formations, target death, pause, and the maximum expected crowd.
Typed Navigation Unit
See the complete typed navigation unit for a pattern that guards map synchronization, avoids querying a finished path, and keeps the physics body as the sole movement authority.
Set path_desired_distance and target_desired_distance from speed, physics
tick, body radius, and desired stop behavior. Values that are too small cause
overshoot/backtracking; values that are too large skip corners.
Command and AI Rules
- Commands use global positions. Project ground clicks to a legal destination when the design allows clamping; otherwise reject unreachable orders visibly.
- Update a moving target's path only after it moved a threshold or a repath
interval elapsed. Assigning
target_positionevery frame can produce path churn and direction flicker. - Keep selected units in a typed collection and remove invalid/freed entries.
- Give multi-unit moves distinct formation slots instead of one identical point.
- Validate team and target liveness both when accepting an attack order and immediately before dealing damage.
- Use game delta or
Timerfor attack cadence and scans. System wall time does not naturally honor pause and time scale. - Use acquire/disengage hysteresis so targets do not toggle at one exact radius.
- Scan on a timer or maintain a registry; do not search the entire scene for every unit every frame.
Avoidance Rules
avoidance_enabledhas a cost. Enable it for active movers in crowds, not automatically for every dormant unit.- Set agent
max_speedto at least the submitted desired speed. radiusdescribes avoidance size only. Path clearance comes from navigation geometry and its bake settings; different body sizes may need separate maps.- Tune
neighbor_distance,max_neighbors, and time horizons downward from defaults while preserving required behavior. - Avoidance layers/masks are independent of physics and navigation layers.
- Feed the safe velocity back through
CharacterBody2D.move_and_slide()so physics remains a final barrier. - RVO can move a unit away from the path or even outside navigable polygons.
Keep
path_max_distancesensible and test map boundaries.
Verification Gate
- Show navigation debug geometry and each test agent's path.
- Assert the agent map iteration ID is nonzero before evaluating a path.
- Test a reachable point, an unreachable point, a point outside the map, and a destination across every intended link/layer boundary.
- Distinguish
is_navigation_finished()fromis_target_reached(); an unreachable path can finish at its closest reachable endpoint. - Test selection and drag selection under camera pan/zoom and over UI.
- Test move, attack, cancel, additive selection, target death, friendly clicks, and commands issued while units are moving.
- Test avoidance with crossing streams and dense formations, then profile at the target unit count.
- Run existing tests and a headless parse/import check with the inspected Godot version when available.
- Report files changed, maps/scenes exercised, commands run, unit counts tested, and checks blocked by missing assets or executable.
Common Failure Modes
- Empty path at startup: map has not synchronized. Queue the command until a map update is observed or the iteration ID is nonzero.
- Unit never moves: the agent only computes path data; parent movement code is missing, or navigation layers/maps do not match.
- Unit dances or looks backward: target is reassigned too often, distances are below per-tick travel, or the agent is repeatedly forced off-path.
- Unit cuts corners or exits the map: path distance is too large, avoidance dominates steering, or physics/navigation geometry disagree.
- Avoidance returns zero: avoidance is disabled, no map is assigned, desired velocity/target was not supplied, or layers do not match.
- Large units clip walls: avoidance radius was mistaken for pathfinding clearance; rebake or use an appropriate map.
- Selection clicks through UI: input is handled too early or UI mouse filters are wrong.
- Dead target crashes combat: references are not checked with
is_instance_valid()or cleared on target exit/death. - Crowds stall: all units share one destination, horizons/radii are too conservative, or the map has a bottleneck narrower than the formation.
References
- Navigation maps, agents, and avoidance
- Unit selection and commands
- Targeting, combat AI, and tests
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

