Skip to content

RandallLiuXin/GodotMaker / skills/reviewer/navigation

navigation-review

Verified

Reviews 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.

FileKindSize
SKILL.mdskill md1.4 KB
checklist.mdmarkdown3.3 KB
gotchas.mdmarkdown3.9 KB

checklist.md

View on GitHub
# Navigation Checklist

Automated checks to run after implementation. Each check maps to a gotcha.

## Static Checks

### S1. First-frame sync pattern → G1
Grep scripts that use NavigationAgent:
- GDScript: `target_position` must NOT be set in `_ready()` without a preceding `await get_tree().physics_frame`
- C#: `TargetPosition` must NOT be set in `_Ready()` without a preceding `await ToSignal(GetTree(), SceneTree.SignalName.PhysicsFrame)`
- Acceptable: set in a deferred function that awaits a physics frame first

### S2. Navigation layer assignment → G3
For agents with custom `navigation_layers`:
- At least one NavigationRegion exists with a matching layer
- Agents of different sizes use different layers with separate baked meshes

### S3. Off-navmesh target handling → G4
Grep scripts that set `target_position` / `TargetPosition`:
- If target comes from user input, raycasts, or dynamic sources: verify there is a post-arrival distance check or navmesh reachability validation
- Hardcoded targets on known navmesh areas are acceptable

### S4. Avoidance stuck handling → G2
Grep scripts that enable `avoidance_enabled`:
- Must have stuck detection logic (e.g., progress check over N frames, or distance delta threshold)
- If NavigationObstacle is used for static blocking: must also have `affect_navigation_mesh = true` and rebake call
- Relying solely on avoidance to navigate around large or static obstacles is a G2 violation

### S5. Rebake-then-repath pattern → G5
Grep for `bake_navigation_polygon()` or `region_set_navigation_polygon()`:
- After the bake call (same function or via signal), affected agents must have `target_position` re-set
- Bake without re-pathing active agents is a G5 violation

## Runtime Checks

### R1. Path validity test → G1
```gdscript
await get_tree().physics_frame
agent.target_position = target_pos
await get_tree().physics_frame
assert(agent.get_current_navigation_path().size() > 0, "path empty after sync")
```

### R2. Arrival accuracy test → G4
```gdscript
# After agent movement completes:
assert(agent.is_navigation_finished(), "agent never reached target")
assert(agent.global_position.distance_to(intended_target) < threshold,
    "arrived at snapped position, not intended target")
```

### R3. Rebake path update test → G5
```gdscript
# Agent has path through region X → modify geometry → rebake
agent.target_position = agent.target_position  # force re-query
await get_tree().physics_frame
assert(new_path != old_path, "path did not update after rebake")
```

### R4. Multi-size agent navmesh test → G3
Two agents with different radii, each assigned to a separate navigation layer with appropriately baked meshes:
```gdscript
# Narrow corridor passable by small agent only
await get_tree().physics_frame
small_agent.target_position = narrow_target
large_agent.target_position = narrow_target
await get_tree().physics_frame
assert(small_agent.get_current_navigation_path().size() > 0, "small agent should path through narrow corridor")
assert(large_agent.get_current_navigation_path().size() == 0 or
    large_agent.global_position.distance_to(narrow_target) > threshold,
    "large agent should not reach narrow corridor target")
```

## Compilation

```bash
{godot_path} --headless --quit 2>&1
```
Pass: exit code 0, no errors referencing navigation nodes or scripts.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 323kUpdated Claude CodeCodexVerifiedInstall