RandallLiuXin/GodotMaker / skills/reviewer/navigation
navigation-review
VerifiedReviews Godot navigation implementation for known pitfalls. Triggers AFTER implementation, when code involves NavigationAgent2D, NavigationAgent3D, NavigationRegion2D, NavigationRegion3D, NavigationLink2D, NavigationLink3D, NavigationObstacle2D, NavigationObstacle3D, target_position, TargetPosition, avoidance_enabled, bake_navigation_polygon, navigation_layers, velocity_computed, safe_velocity, is_navigation_finished. Do NOT use this skill for planning or teaching — only for post-implementation review.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 1.4 KB |
| checklist.md | markdown | 3.3 KB |
| gotchas.md | markdown | 3.9 KB |
gotchas.md
View on GitHub# Navigation Gotchas
Design-level constraints — intentional engine behaviors, not bugs. Stable across Godot 4.x.
## G1. First-frame navigation query returns empty path [GDScript] [C#]
**Symptom**: agent path is empty and agent doesn't move, despite valid target and baked navmesh.
**Root cause**: NavigationServer synchronizes region data after the first physics frame. Any query before that sync returns empty.
**Correct approach**:
```gdscript
# GDScript
func _ready():
actor_setup.call_deferred()
func actor_setup():
await get_tree().physics_frame
navigation_agent.target_position = target
```
```csharp
// C#
public override void _Ready() { CallDeferred(MethodName.ActorSetup); }
private async void ActorSetup() {
await ToSignal(GetTree(), SceneTree.SignalName.PhysicsFrame);
_navigationAgent.TargetPosition = _target;
}
```
**Wrong approach**:
- Setting `target_position` directly in `_ready()` / `_Ready()`
- Setting it in `_ready()` with `call_deferred` but without `await physics_frame`
- Setting it in `_enter_tree()` (fires even earlier)
## G2. Avoidance does not reroute paths [GDScript] [C#]
**Symptom**: agent follows original path toward obstacle, gets stuck or oscillates despite `avoidance_enabled = true`.
**Root cause**: RVO avoidance only adjusts frame-by-frame velocity. It never recalculates the underlying path.
**Correct approach**: for static blocking, use `NavigationObstacle` with `affect_navigation_mesh = true` and rebake. For dynamic blocking, detect stuck agents (no progress over N frames) and re-set `target_position`.
**Wrong approach**:
- Relying solely on `avoidance_enabled` to navigate around large or static obstacles
- Assuming `NavigationObstacle` with only `avoidance_enabled` will make agents path around it
- Not implementing any stuck detection when using avoidance in tight spaces
## G3. agent_radius is baked into mesh — no runtime adjustment [GDScript] [C#]
**Symptom**: small agent can't reach visually passable narrow areas, or large agent clips walls at tight corners.
**Root cause**: `agent_radius` shrinks traversable area at bake time. The baked mesh permanently reflects that radius. No runtime per-agent override exists.
**Correct approach**: bake separate meshes per agent size. Use `navigation_layers` to assign agents to size-appropriate meshes.
**Wrong approach**:
- Sharing one navmesh among agents of different sizes
- Expecting the agent's `radius` property to affect pathfinding (it only affects avoidance)
- Trying to set `agent_radius` at runtime expecting path changes
## G4. Off-navmesh target snaps silently [GDScript] [C#]
**Symptom**: agent "arrives" at wrong position. `is_navigation_finished()` returns true while agent is far from intended target.
**Root cause**: if `target_position` is outside the navmesh, pathfinding silently snaps it to the nearest navmesh point. Agent considers itself arrived at the snapped point.
**Correct approach**: after `navigation_finished`, check distance to intended target and handle the unreachable case.
**Wrong approach**:
- Using `is_navigation_finished()` as proof the agent reached the intended destination
- Setting targets from user input / raycasts without navmesh reachability validation
- No post-arrival distance check when targets come from dynamic sources
## G5. Navmesh rebake does not update existing agent paths [GDScript] [C#]
**Symptom**: after rebaking (e.g., wall destroyed), agents continue old paths ignoring newly opened areas.
**Root cause**: agent paths are computed once and cached. Rebaking updates the server graph but does not invalidate existing paths.
**Correct approach**: after rebake, re-set `target_position` on affected agents to trigger fresh path queries.
**Wrong approach**:
- Assuming agents automatically reroute after `bake_navigation_polygon()` or `region_set_navigation_polygon()`
- Rebaking without re-pathing any active agents
- Only rebaking via signal without a follow-up `target_position` re-assignment
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |