@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/gamedev-pathing/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: gamedev-pathing
+description: "Use when making NPCs, enemies, or units navigate a level — grid vs waypoint vs navmesh, A*/JPS, navmesh baking and agent radius, off-mesh links, steering, RVO crowd avoidance, and flow fields in Godot 4.x, Unity, Unreal. NOT collision response or character controllers (that is gamedev-physics), NOT aggro or difficulty design (that is game-design)."
+tags: [pathfinding, navmesh, navigation, steering, a-star]
+recommends: [godot, unity, unreal, gamedev-physics]
+profiles: [full]
+origin: ai-hub
+---
+
+# Game AI navigation & pathfinding
+
+Move agents through a level intelligently and per-engine-correctly: pick a world representation,
+run the right search, then follow the result with steering + local avoidance. This skill owns the
+**navigation stack**; it stops where physics collision response and high-level behaviour design begin.
+
+## Version targets & the API ban-list (read first)
+
+Navigation APIs were renamed hard between engine generations. Emitting an old name compiles into
+nothing or silent breakage. Target these versions; never emit the banned column.
+
+| Engine (target) | NEVER emit (deprecated / removed) | Use instead |
+| --- | --- | --- |
+| **Godot 4.x** | `Navigation` / `NavigationMeshInstance` / `Navigation2D` nodes | `NavigationServer2D/3D` + `NavigationRegion2D/3D` |
+| Godot 4.x | `agent.get_next_location()` | `agent.get_next_path_position()` |
+| Godot 4.x | `NavigationAgent.set_target_location()` | set the `target_position` property |
+| Godot 4.x | reading `velocity` directly when avoidance is on | feed `set_velocity()`, read the `velocity_computed(safe)` signal |
+| **Unity (AI Navigation pkg)** | the legacy **Navigation window** static bake, `Navigation Static` flag, built-in `OffMeshLink` component | `NavMeshSurface` (`com.unity.ai.navigation`), `NavMeshLink`, `NavMeshModifier` |
+| Unity | `agent.destination = p` then reading a path same frame | `SetDestination(p)`, then gate on `!pathPending && remainingDistance <= stoppingDistance` |
+| **Unreal (UE5)** | hand-rolling A* over your own grid for pawns | `AAIController::MoveTo*` over `RecastNavMesh`; BT `MoveTo` task |
+| Unreal | expecting a **Static** navmesh to react to spawned geometry | set RecastNavMesh **Runtime Generation = Dynamic** (or Dynamic Modifiers Only) |
+
+## The two-layer mental model (center of gravity)
+
+The single most common navigation bug is collapsing two jobs into one. Keep them separate:
+
+1. **Global pathfinding — *where* to go.** A discrete search (A* / navmesh query) over a static-ish
+   representation, run *occasionally* (on new goal, or throttled), returns a **corridor of waypoints**.
+2. **Local steering + avoidance — *how* to move this frame.** A cheap per-frame vector: follow the
+   corridor, dodge other agents and dynamic obstacles, respect acceleration. Runs *every frame*.
+
+Path for the map, steering for the moment. Symptoms of merging them: re-running A* every frame (CPU
+melts), or agents that walk the path but pile into each other (no local avoidance). Every engine's
+`NavMeshAgent` / `NavigationAgent` bundles both — know which layer you are configuring.
+
+## Choosing a representation
+
+| Representation | Fits | Cost / caveat |
+| --- | --- | --- |
+| **Uniform grid** | tile/2D games, RTS, roguelikes, destructible terrain | many nodes; needs path smoothing to avoid staircase paths; JPS accelerates it |
+| **Waypoint graph** | sparse hand-placed routes, patrol nets, rails, racing lines | cheap; agents snap to nodes, off-graph space is invisible — brittle for open areas |
+| **Navmesh** | 3D and most open 2D worlds; the default for character movement | bake step; represents *walkable surface* as convex polys — fewer nodes, natural paths |
+
+Rule: **navmesh for free-roaming characters, grid for tile-locked/destructible worlds, waypoint graph
+only for constrained routes.** Detail & path-smoothing (funnel algorithm) → `references/search-algorithms.md`.
+
+## Search algorithms (essentials)
+
+- **A\*** — the default. Dijkstra + a heuristic `h(n)` that estimates remaining cost. Admissible `h`
+  (never *over*-estimates) ⇒ optimal path; use **octile** distance on 8-connected grids, **Euclidean**
+  on navmesh/any-angle. `h` must also stay ≤ true edge costs (consistency) to skip re-expansions.
+- **Dijkstra** — A* with `h=0`. Use when there is **no single goal** (nearest of many exits) or you need
+  the full cost field (see flow fields). Slower than A* to one target.
+- **Weighted / greedy** — inflate `h` (`f = g + w·h`, `w>1`) for faster, slightly suboptimal paths when
+  frame budget beats optimality.
+- **JPS (Jump Point Search)** — A* speedup for **uniform-cost grids only**; skips symmetric paths, often
+  10×+ fewer expansions. Not for weighted terrain or navmeshes.
+- **Hierarchical / HPA\*** — for **huge maps**: partition into clusters, path cluster-to-cluster, refine
+  locally. Reach for it when a single flat A* blows the frame budget or you have thousands of tiles.
+
+Always run search off a **binary-heap open set** and a closed set. Pseudocode, tie-breaking, any-angle
+(Theta*), and the funnel string-pull → `references/search-algorithms.md`.
+
+## Navmesh workflow (essentials)
+
+1. **Bake** the walkable surface from level geometry. Key params: **agent radius** (how far the mesh is
+   shrunk from walls — the #1 knob), **agent height**, **max step/climb**, **max slope**, cell size.
+2. **One navmesh per agent size.** A tank and a rat need different bakes; do not share one mesh and hope.
+3. **Regions / areas + costs** — tag surfaces (water, mud, road) with a traversal cost so paths prefer
+   roads and avoid hazards, rather than deleting the area outright.
+4. **Off-mesh / nav links** — explicit edges for jumps, ladders, teleporters, doors: places agents move
+   but no polygon connects. Godot `NavigationLink`, Unity `NavMeshLink`, Unreal `NavLinkProxy`.
+5. **Dynamic obstacles** — two tools, do not confuse them:
+   - **Carving obstacle** (Unity `NavMeshObstacle` carving, Godot `NavigationObstacle`, Unreal
+     `NavModifier`): punches a hole so *global* paths route around a placed prop. Costs a re-carve on move.
+   - **Local avoidance** (RVO/ORCA): agents dodge *without* touching the mesh — for other moving agents.
+6. **Re-baking** — full rebake is expensive; prefer **tile/partial** rebake or carving for runtime
+   changes. Bake offline for static levels. Full param table + per-engine baking → `references/navmesh-workflow.md`.
+
+## Steering & local avoidance (essentials)
+
+Steering = a desired-velocity vector combined and clamped to max force/speed. Primitives:
+
+- **Seek / Flee** — accelerate toward / away from a target point.
+- **Arrive** — seek that ramps speed down inside a slowing radius (no overshoot/jitter at the goal).
+- **Pursue / Evade** — seek/flee the target's *predicted future* position, not its current one.
+- **Wander** — smoothed random heading for idle/ambient motion.
+- **Path following** — steer toward a look-ahead point along the A*/navmesh corridor, not the far goal.
+- **Flocking** = separation + alignment + cohesion (Reynolds boids) for groups.
+
+Combine either as a **weighted sum** (simple) or **priority/arbitration** (avoidance wins over cohesion).
+
+**Local avoidance (RVO / ORCA):** each agent picks a velocity that is collision-free assuming neighbours
+share the burden (*reciprocal* — hence no oscillating "dance"). This is avoidance, **not** collision
+*response*: it changes intended velocity *before* moving; the physics/collision solver is a separate,
+last-resort backstop (→ [`gamedev-physics`](../gamedev-physics/SKILL.md)). For dense crowds use the
+engine's crowd/avoidance system.
+
+**Flow fields** — for **many agents → one (or few) goals** (RTS swarm, tower-defense creeps): run one
+**Dijkstra from the goal** over the grid to build a cost/integration field, derive a per-cell direction
+vector once, then every agent just samples its cell. O(1) per agent vs one A* each. Full derivation,
+boids weights, and RVO intuition → `references/steering-and-avoidance.md`.
+
+## Per-engine mapping
+
+### Godot 4.x (`NavigationAgent3D` — 2D is identical with `2D` suffix)
+
+```gdscript
+extends CharacterBody3D
+@onready var agent: NavigationAgent3D = $NavigationAgent3D
+@export var speed := 4.0
+
+func _ready() -> void:
+    agent.avoidance_enabled = true                       # RVO local avoidance
+    agent.velocity_computed.connect(_on_velocity_computed)
+
+func set_goal(p: Vector3) -> void:
+    agent.target_position = p                            # property, NOT set_target_location()
+
+func _physics_process(_delta: float) -> void:
+    if agent.is_navigation_finished():
+        return
+    var next := agent.get_next_path_position()           # 4.x name (was get_next_location)
+    var desired := global_position.direction_to(next) * speed
+    agent.set_velocity(desired)                          # feed RVO; result via signal
+
+func _on_velocity_computed(safe: Vector3) -> void:       # only fires while avoidance enabled
+    velocity = safe
+    move_and_slide()
+```
+
+One-off query without an agent: `NavigationServer3D.map_get_path(map_rid, from, to, true)`. Rebake a
+region at runtime: `$NavigationRegion3D.bake_navigation_mesh()`. Off-mesh: `NavigationLink3D`. If
+avoidance is **off**, skip the signal and `move_and_slide()` with `desired` directly.
+
+### Unity (AI Navigation package + `NavMeshAgent`)
+
+```csharp
+using UnityEngine;
+using UnityEngine.AI;
+
+[RequireComponent(typeof(NavMeshAgent))]
+public class Chaser : MonoBehaviour {
+    NavMeshAgent agent;
+    void Awake() => agent = GetComponent<NavMeshAgent>();
+
+    public void Chase(Transform target) => agent.SetDestination(target.position);
+
+    public bool ReachedGoal() =>
+        !agent.pathPending && agent.remainingDistance <= agent.stoppingDistance
+        && (!agent.hasPath || agent.velocity.sqrMagnitude < 0.01f);
+}
+```
+
+Bake: add a **`NavMeshSurface`** to a scene root and Bake (the legacy Navigation window is gone).
+Runtime rebake: `surface.BuildNavMesh()`. Dynamic blockers: **`NavMeshObstacle`** (enable *Carving* for
+stationary props, leave off for moving agents so RVO handles them). Off-mesh: **`NavMeshLink`**. Local
+avoidance quality: `agent.obstacleAvoidanceType`. Area costs: `agent.SetAreaCost(area, cost)`.
+
+### Unreal (UE5 — `RecastNavMesh` + `AIController` + Behavior Tree / EQS)
+
+1. Drop a **`NavMeshBoundsVolume`** around playable space → a `RecastNavMesh` auto-generates. For
+   runtime changes set its **Runtime Generation = Dynamic** (or *Dynamic Modifiers Only*); spawned
+   geometry must have collision + **Can Ever Affect Navigation**.
+2. Possess the pawn with an **`AAIController`**. Movement:
+
+```cpp
+AAIController* AICon = Cast<AAIController>(GetController());
+AICon->MoveToActor(TargetActor, /*AcceptanceRadius*/ 50.f);   // or MoveToLocation(FVector)
+```
+
+3. **Behavior Tree + Blackboard** for decisions; the **`MoveTo`** task walks the navmesh. **EQS**
+   (Environment Query System) picks *where* to go (cover, flank, nearest item) via scored queries.
+4. Costs/holes: **`NavModifierVolume`** + `NavArea` classes. Off-mesh: **`NavLinkProxy`**. Crowd
+   avoidance: enable the **Detour Crowd** manager (or `DetourCrowdAIController`) for RVO on many agents.
+
+> High-level BT *design* (states, aggro, difficulty) is [`game-design`](../game-design/SKILL.md); this skill wires the BT's
+> movement/EQS tasks to navigation, not the decision tree's semantics.
+
+## Anti-patterns
+
+| Anti-pattern | Do instead |
+| --- | --- |
+| Running a full A* every frame | Path on goal-change (or throttled) and steer between frames — per-frame search melts CPU at scale. |
+| One navmesh bake shared by every unit | Radius/height differ; bake per agent size or use agent-type profiles. |
+| Baking with a placeholder agent radius | Bake with the real radius — mismatch is the top "stuck in doorways / clipping walls" cause. |
+| Treating agents that clip through each other as a physics bug | Missing **local avoidance**; enable RVO/crowd — that is the navigation layer. |
+| Expecting RVO to prevent every overlap | Avoidance ≠ collision. Agents can still overlap under pressure; that is expected, not a physics bug. |
+| Expecting a **static** bake to see runtime-spawned geometry | Set Dynamic runtime generation / rebake, or add a carving obstacle or nav link. |
+| Hand-rolling your own grid A* in Unity/Unreal | Reinvents the built-in navmesh; use `NavMeshAgent` / `AAIController::MoveTo`. |
+| 500 zombies each running A* to the player | That's a **flow field**: one Dijkstra from the goal, agents sample cells. |
+| Setting `agent.destination` and reading the path the same frame | Path is async (`pathPending`); gate on it before trusting `remainingDistance`. |
+| Inflating `h` because a bigger heuristic seems smarter | Over-estimating `h` breaks A* optimality; keep it admissible (or weight it *knowingly*). |
+| Trusting a path query that came back empty | Start/end are **off the navmesh** or in disconnected islands — snap to the nearest poly and check reachability first. |
+| Assuming an off-mesh link works both ways | Links are **directional and manual** — a jump-down link does not imply a jump-up link. |
+| Feeding raw grid paths to the mover | Smooth them (funnel / string-pull) or agents walk visible zig-zag staircases. |
+
+## Related skills
+
+- [`godot`](../godot/SKILL.md) — GDScript/scene specifics; this skill owns the navigation subsystem it plugs into.
+- [`unity`](../unity/SKILL.md) — Unity/C# project setup; here for the NavMesh + AI Navigation package details.
+- [`unreal`](../unreal/SKILL.md) — UE5/Blueprint/C++; here for RecastNavMesh + AIController/BT/EQS wiring.
+- [`gamedev-physics`](../gamedev-physics/SKILL.md) — collision *response*, rigidbodies, character controllers; steering decides intended velocity, physics resolves the contact.
+- [`game-design`](../game-design/SKILL.md) — high-level enemy behaviour, aggro, encounter/difficulty design (what the AI *decides*, not how it *moves*).
+
+## Checklist
+
+- [ ] Representation chosen deliberately (navmesh / grid / waypoint) and justified for the world type.
+- [ ] Global path and local steering are **separate layers**; A* is not per-frame.
+- [ ] Navmesh baked with the correct **agent radius/height/step/slope** (per agent size if they differ).
+- [ ] Area costs set for hazards/terrain instead of hard-deleting walkable space.
+- [ ] Off-mesh/nav links placed for every jump/ladder/teleport gap (correct direction).
+- [ ] Dynamic obstacles handled by carving *or* rebake *or* local avoidance — the right one for each case.
+- [ ] Local avoidance / crowd enabled if multiple agents share space; flow field used for many→one-goal.
+- [ ] Correct **current** engine APIs (no banned names from the version table); paths validated for reachability.
+- [ ] Grid paths smoothed (funnel) so movement isn't staircased.
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+When this runs in a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) wiki), record
+the project's navigation decisions in `02-DOCS/wiki/stack/gamedev-pathing.md` (indexed from
+`02-DOCS/wiki/index.md`): engine + version, chosen representation, bake settings (agent sizes, cell
+size), avoidance/crowd choice, custom links/areas. Read it first on every use; bump its `Updated` date
+when a convention changes. No `02-DOCS/` layer? Skip silently — conventions are *recorded, not gated*.

package/skills/shared/gamedev-pathing/evals/README.md

@@ -0,0 +1,14 @@
+# Eval harness — `gamedev-pathing` skill
+
+`cases.yaml` is a human/CI-readable trigger-and-capability spec, not an automated runner. It asserts two
+things. **Triggering**: the skill fires on real navigation asks — engine-specific ("enemies stuck in
+Godot 4", "Unreal navmesh won't see a spawned crate"), representation/algorithm theory (A* heuristics,
+grid vs navmesh), crowd/avoidance ("units dance and pile up"), and a Catalan off-mesh-link phrasing — and
+stays quiet on near-misses that route to `gamedev-physics` (collision response), `game-design` (what the
+AI decides), `unity` (lightmap baking — the "bake" false friend), `godot` (animation state machine), and
+`gamedev-multiplayer` (netcode). **Capability**: with `SKILL.md` + references loaded, the answer uses
+the current Godot 4.x API (`target_position`, `get_next_path_position`, `velocity_computed` — never the
+Godot-3 names), separates global pathfinding from per-frame steering, and reaches for a flow field for
+many-agents-to-one-goal. Run 3–5 trials per prompt (LLM routing is non-deterministic); a prompt passes on
+a majority. Judge `capability` by reading the output against `must_include`; the with-skill answer should
+clearly beat a no-skill baseline.

package/skills/shared/gamedev-pathing/evals/cases.yaml

@@ -0,0 +1,49 @@
+skill: gamedev-pathing
+
+should_trigger:
+  - prompt: "My enemies in Godot 4 keep getting stuck on walls and never reach the player. How do I get them to actually path around the level?"
+    why: "Core trigger: AI navigation in Godot 4.x. Should produce a NavigationAgent3D loop with target_position + get_next_path_position, and flag agent-radius baking as the stuck-on-walls cause."
+  - prompt: "I've got 400 zombies all chasing the player in my Unity horde game and the framerate tanks because each one runs its own pathfinding. What's the right approach?"
+    why: "Many-agents-to-one-goal is the flow-field trigger; should recommend a Dijkstra-from-goal flow field instead of per-agent A*, plus local avoidance."
+  - prompt: "In Unreal my AI won't walk around a crate I spawn at runtime — it just walks straight through where it should be. The navmesh doesn't seem to update."
+    why: "Dynamic-obstacle / re-bake trigger; should point to RecastNavMesh Runtime Generation = Dynamic (or a NavModifier), Can Ever Affect Navigation, not a static bake."
+  - prompt: "What's the difference between using a grid, a waypoint graph, and a navmesh for pathfinding, and when should I pick each?"
+    why: "Representation trade-offs are a named core section; should give the grid/waypoint/navmesh table with the 'navmesh for free-roaming characters' rule."
+  - prompt: "My squad of units all pile onto the exact same spot and jitter against each other when they reach the destination. How do I make them spread out and stop dancing?"
+    why: "Local avoidance / crowd trigger (RVO/ORCA reciprocal avoidance); should distinguish avoidance from collision and enable the engine's crowd/avoidance system, plus arrive-behaviour to stop jitter."
+  - prompt: "Explain A* — how the heuristic works, what admissible means, and when I'd use JPS or a hierarchical version instead."
+    why: "Search-algorithm core section; should cover f=g+h, admissibility/consistency, octile vs Euclidean h, JPS for uniform grids, HPA* for huge maps."
+  - prompt: "Els meus NPCs no saben baixar d'una plataforma a una altra al navmesh, com els connecto?"
+    why: "Catalan off-mesh-link trigger; should recommend an explicit directional nav link (NavigationLink / NavMeshLink / NavLinkProxy)."
+
+should_not_trigger:
+  - prompt: "My character controller sinks into the floor and bounces off walls weirdly — the rigidbody collision response feels wrong."
+    route_to: "gamedev-physics"
+    why: "Collision response / rigidbody / character-controller tuning is physics, not navigation; steering only sets intended velocity, physics resolves the contact."
+  - prompt: "Design my enemy AI: when should the boss enrage, how does aggro/threat work, and how do difficulty tiers change its behaviour?"
+    route_to: "game-design"
+    why: "High-level behaviour/encounter/difficulty design is what the AI decides, not how it moves through space — belongs to game-design."
+  - prompt: "Write a GDScript state machine for my player's idle/run/jump/attack animation states in Godot."
+    route_to: "godot"
+    why: "General GDScript / animation state machine is engine-language work, not the navigation subsystem."
+  - prompt: "Set up a dedicated server so multiple players' positions stay in sync with low latency."
+    route_to: "gamedev-multiplayer"
+    why: "Netcode / replication / lag compensation is multiplayer networking, unrelated to pathfinding."
+  - prompt: "How do I bake lighting and set up baked global illumination for my Unity level?"
+    route_to: "unity"
+    why: "'Baking' here is lightmaps, not a navmesh; near-miss on the word 'bake' that must route to the engine skill, not navigation."
+
+capability:
+  - scenario: "In Godot 4.x, make a CharacterBody3D enemy chase the player across a baked navmesh, pathing around static geometry and avoiding other enemies, without getting stuck in doorways."
+    must_include:
+      - "Uses a NavigationAgent3D with the `target_position` property (NOT the removed set_target_location) to set the goal"
+      - "Calls `get_next_path_position()` each physics frame (NOT the Godot-3 `get_next_location()`) and moves toward it"
+      - "Enables avoidance (`avoidance_enabled = true`), feeds `set_velocity(desired)`, and reads the safe velocity from the `velocity_computed` signal before move_and_slide()"
+      - "Separates global pathfinding (occasional, on new goal) from per-frame steering/movement — does not re-run a full search every frame"
+      - "Names agent radius in the navmesh bake as the fix for getting stuck in doorways / clipping walls"
+      - "Notes that local avoidance (RVO) is distinct from physics collision response"
+  - scenario: "Advise on moving 500+ units to a single rally point in an RTS efficiently."
+    must_include:
+      - "Recommends a flow field instead of per-agent A*"
+      - "Describes building it via Dijkstra/BFS from the goal to make an integration/cost field, then a per-cell direction vector agents sample in O(1)"
+      - "Layers local avoidance / separation on top so units don't stack on the goal cell"

package/skills/shared/gamedev-pathing/references/navmesh-workflow.md

@@ -0,0 +1,110 @@
+# Navmesh workflow — baking, links, dynamic obstacles, per-engine
+
+Depth for the "Navmesh workflow" section of SKILL.md. A navmesh is the walkable surface expressed as
+convex polygons; search runs over polygon adjacency, and movement follows the corridor via the funnel
+algorithm (see `search-algorithms.md`).
+
+## Bake parameters (the knobs that matter)
+
+Every engine bakes by voxelizing collision geometry and reconstructing walkable polys (Recast under the
+hood in Unity and Unreal; Godot has its own baker). The parameters map closely across engines:
+
+| Parameter | What it does | Getting it wrong |
+| --- | --- | --- |
+| **Agent radius** | Shrinks the mesh away from walls by this radius | Too small → agents clip walls / stick in doorways; too large → valid gaps vanish |
+| **Agent height** | Min vertical clearance a poly must have | Agents path under geometry they can't fit beneath |
+| **Max step / climb** | Tallest ledge treated as walkable (stairs, curbs) | Stairs become walls, or agents "climb" impossible ledges |
+| **Max slope** | Steepest walkable incline (degrees) | Ramps drop out, or agents walk up cliffs |
+| **Cell size / voxel size** | Bake resolution | Coarse → missing thin walkways; fine → slow bake, huge data |
+| **Min region area** | Discards tiny isolated islands | Noise polys, or losing small legit platforms |
+
+**One bake per agent size.** A large enemy and a small one need different radius/height; share a mesh
+only if their footprints truly match. Unity/Unreal support multiple **agent types/profiles**; Godot uses
+separate `NavigationMesh` resources or navigation layers.
+
+## Regions, areas & costs
+
+Tag surfaces with an **area type** carrying a traversal **cost multiplier** so paths *prefer* or *avoid*
+terrain instead of it being all-or-nothing:
+
+- Road = 0.5, grass = 1, mud = 4, water = 8 → agents naturally favour roads, cross mud only if shorter.
+- Set an area's cost to *very high* rather than deleting it when you want "avoid unless no alternative".
+- **Navigation layers / area masks** let different agents see different areas (e.g. only amphibious units
+  path through water) by filtering which polygons a query considers.
+
+## Off-mesh / nav links
+
+Explicit connections where an agent can move but no polygon adjacency exists: jump-downs, ladders,
+teleporters, ziplines, doorways between disconnected meshes.
+
+- **Directional**: define both directions if the agent can traverse both ways (a fall-down link is often
+  one-way). Give it a cost so pathing weighs it against walking around.
+- The link only tells pathfinding the two ends connect — you still play the **traversal animation/motion**
+  yourself when the agent reaches the link (jump arc, climb, teleport).
+- Godot `NavigationLink2D/3D` · Unity `NavMeshLink` · Unreal `NavLinkProxy` (with smart-link events).
+
+## Dynamic obstacles: three different tools
+
+Do not confuse these — each solves a different problem:
+
+1. **Carving obstacle** — cuts a hole in the navmesh so *global* paths route around a placed object
+   (a dropped crate, a closed gate). Global and correct, but re-carving on every move is costly → use for
+   **stationary / rarely-moving** props. Unity `NavMeshObstacle` (Carve on) · Godot `NavigationObstacle`
+   (with vertices) · Unreal `NavModifierComponent` / `NavModifierVolume`.
+2. **Local avoidance (RVO/ORCA)** — agents steer around each other and moving obstacles *without*
+   touching the mesh, every frame. For **other agents** and small moving things. See `steering-and-avoidance.md`.
+3. **Re-bake** — regenerate the mesh (or affected tiles) when the level geometry itself changes
+   (destruction, procedural build). Prefer **tile/partial** rebake over full.
+
+Rule of thumb: **moving agents → RVO; placed static blockers → carving; geometry changed → rebake.**
+
+## Re-baking strategy
+
+- **Static levels**: bake once at author time; ship the baked data. No runtime cost.
+- **Occasional changes**: rebake the affected **tiles/region** only, ideally async/off the main thread.
+- **Constant small changes** (a patrolling door): a carving obstacle beats rebaking.
+- Full-map rebake every frame is never the answer — it is the "navmesh not updating, so I rebake
+  constantly" anti-pattern.
+
+## Per-engine baking specifics
+
+### Godot 4.x
+
+- `NavigationRegion2D/3D` holds a `NavigationMesh` (3D) / `NavigationPolygon` (2D). Bake in-editor, or at
+  runtime with `region.bake_navigation_mesh()`.
+- Source geometry: configure the `NavigationMesh` geometry parsing (parsed geometry type, collision mask,
+  source group) so the baker knows which nodes to voxelize.
+- Advanced/procedural: build a `NavigationMeshSourceGeometryData3D` and call
+  `NavigationServer3D.bake_from_source_geometry_data(...)`, then assign to the region.
+- Query directly: `NavigationServer3D.map_get_path(map, from, to, optimize, navigation_layers)`.
+- Debug: enable **Visible Navigation** (Debug menu) to draw the mesh in-game.
+
+### Unity (AI Navigation package, `com.unity.ai.navigation`)
+
+- The legacy Navigation window / `Navigation Static` flag is deprecated. Add a **`NavMeshSurface`**
+  component to a root object; set its **Collect Objects** (All / Children / by layer) and **Agent Type**,
+  then **Bake**.
+- Runtime: `surface.BuildNavMesh()` rebakes; combine with a data source for large worlds.
+- `NavMeshModifier` overrides area/inclusion per-object; `NavMeshModifierVolume` does it by volume.
+- Multiple agent sizes = multiple Agent Types (Navigation → Agents) + one surface each.
+- Query without moving: `NavMesh.CalculatePath(from, to, areaMask, NavMeshPath)`; sample the mesh with
+  `NavMesh.SamplePosition` to snap a point onto it.
+
+### Unreal (UE5, `RecastNavMesh`)
+
+- A **`NavMeshBoundsVolume`** defines where navigation is generated; a `RecastNavMesh-Default` actor
+  appears (tune agent radius/height/step/slope in Project Settings → Navigation System / its details).
+- **Runtime Generation** modes: **Static** (fastest, no runtime change), **Dynamic Modifiers Only**
+  (can only *remove* nav via modifiers at runtime), **Dynamic** (any change, rebuilds affected tiles).
+- The mesh is **tiled**; runtime edits rebuild only overlapping tiles. Spawned geometry must have
+  collision + **Can Ever Affect Navigation** to influence it.
+- `NavModifierVolume` + `NavArea` subclasses set cost/exclusion. Debug with the **`P`** key (Show
+  Navigation) in PIE.
+
+## Common failure modes
+
+- **Empty path**: start or end is off the mesh, or the two are on disconnected islands. Snap both to the
+  nearest polygon and test reachability before trusting the result.
+- **Agents hug walls / stick in doors**: agent radius in the bake ≠ real collider radius.
+- **Spawned wall ignored**: static bake — carve it, add a link, or switch to a dynamic/rebake mode.
+- **Path exists but agent won't take a jump**: missing or wrong-direction off-mesh link.

package/skills/shared/gamedev-pathing/references/search-algorithms.md

@@ -0,0 +1,135 @@
+# Search algorithms & world representations
+
+Depth for the "Search algorithms" and "Choosing a representation" sections of SKILL.md. Read this when
+you are hand-rolling a search (a grid game, a custom graph, or a debugging session where the engine's
+navmesh isn't enough).
+
+## Representations in detail
+
+### Uniform grid
+
+Cells are nodes; neighbours are the adjacent cells. **4-connected** (N/E/S/W) gives Manhattan movement;
+**8-connected** adds diagonals. On 8-connected grids, forbid *corner-cutting*: only allow a diagonal move
+if both orthogonal neighbours are also walkable, or agents clip wall corners.
+
+- Pros: trivial to build/edit, supports destructible/procedural terrain, weighted cells (mud=cost 3).
+- Cons: node count explodes with resolution; raw paths look blocky and hug walls — smooth them (funnel).
+
+### Waypoint graph
+
+Hand- or tool-placed nodes with explicit edges. Agents path node-to-node, then steer between.
+
+- Pros: tiny node count, full designer control (patrol loops, cover-to-cover, racing lines).
+- Cons: movement is confined to edges; anything off-graph is invisible. Poor for large open spaces —
+  an agent can't cut across a room the graph didn't anticipate.
+
+### Navmesh
+
+A set of convex polygons covering the walkable surface. Search runs over the polygon adjacency graph
+(few, large nodes), then the **funnel algorithm** pulls a straight path through the polygon corridor.
+
+- Pros: compact, natural any-angle paths, handles 3D height/slopes, one representation for a whole level.
+- Cons: needs a bake step; representing fine dynamic change means re-baking or carving.
+
+## A* — the workhorse
+
+```text
+function A*(start, goal, h):
+    open   = min-heap keyed by f;  push start with g=0, f=h(start,goal)
+    gScore = { start: 0 }
+    came   = {}
+    while open not empty:
+        current = open.pop()                  # lowest f
+        if current == goal: return reconstruct(came, current)
+        for (nbr, stepCost) in neighbours(current):
+            tentative = gScore[current] + stepCost
+            if tentative < gScore.get(nbr, +inf):
+                came[nbr]   = current
+                gScore[nbr] = tentative
+                f = tentative + h(nbr, goal)
+                open.push_or_decrease(nbr, f)
+    return NO_PATH                              # goal unreachable
+```
+
+`f(n) = g(n) + h(n)`: `g` is known cost from start, `h` is the estimated cost to goal.
+
+- Use a **binary heap** (or pairing heap) for the open set — a linear scan is the classic "A* is slow" bug.
+- Track a closed/visited set (or the `gScore` map above) so nodes aren't re-expanded needlessly.
+- `neighbours` returns `(node, stepCost)`; diagonal step cost is `√2` (~1.414), not 1.
+
+### Heuristics & admissibility
+
+- **Admissible**: `h(n)` never *over*-estimates the true remaining cost ⇒ A* returns the optimal path.
+- **Consistent (monotone)**: `h(n) ≤ stepCost(n,m) + h(m)` for every edge ⇒ no node is ever re-opened
+  (strictly stronger than admissible). Standard grid/navmesh heuristics below are both.
+- Match `h` to the movement:
+  - 4-connected grid → **Manhattan** `|dx|+|dy|`.
+  - 8-connected grid → **octile** `max(dx,dy) + (√2−1)·min(dx,dy)`.
+  - any-angle / navmesh → **Euclidean** `√(dx²+dy²)`.
+- **Tie-breaking**: many nodes share the same `f`, giving ugly wandering paths. Break ties toward lower
+  `h`, or nudge `h` up by a tiny factor (`h *= 1.0 + ε`) so the search leans goalward. This trades strict
+  optimality for straighter, faster searches — usually worth it.
+
+### Weighted / greedy A*
+
+`f = g + w·h` with `w > 1` inflates the heuristic: fewer expansions, path at most `w×` optimal. Good when
+frame budget beats perfection. `w → ∞` degenerates to **greedy best-first** (fast, often ugly, not optimal).
+
+## Dijkstra
+
+A* with `h = 0`: expands uniformly outward by cost. Reach for it when:
+
+- There is **no single target** — find the nearest of several exits/items in one search.
+- You need the **whole cost field** from a source (the basis of flow fields — see steering reference).
+
+Slower than A* to one goal because it explores in all directions. **BFS** is the unweighted special case
+(all step costs equal) — fine for simple grids, but Dijkstra/A* generalize to terrain costs.
+
+## JPS (Jump Point Search)
+
+An A* accelerator for **uniform-cost grids only** (every walkable cell same cost). It exploits grid
+symmetry: instead of expanding every cell, it "jumps" in a straight line until it hits a *jump point* (a
+cell with a forced neighbour caused by an obstacle). Often 10×+ fewer node expansions with the **same
+optimal** result, and it stores fewer nodes.
+
+- Requires a uniform-cost, 8-connected grid; **not** applicable to weighted terrain or navmeshes.
+- Pairs well with JPS+ / precomputed jump distances for static maps.
+
+## Hierarchical / HPA*
+
+For very large maps where a single flat A* misses the frame budget:
+
+1. Partition the map into **clusters** (e.g. 10×10 tiles).
+2. Precompute **entrances** between adjacent clusters and intra-cluster distances (an abstract graph).
+3. Search the small abstract graph cluster-to-cluster, then refine each segment with a local A* only
+   when/where the agent actually reaches it.
+
+Trades a little path optimality for a large speedup and enables **path caching** and streaming. Reach for
+it at thousands-of-tiles scale, or when many agents share long routes.
+
+## Any-angle paths (Theta*)
+
+Grid A* paths bend only at 45°/90°. **Theta\*** relaxes this: when expanding, if the parent has
+line-of-sight to the neighbour, it links directly to the parent instead of the current cell — yielding
+straight, any-angle paths without a separate smoothing pass. Cheaper alternative: run grid A* then smooth.
+
+## Path smoothing — the funnel (string-pulling)
+
+Raw grid/navmesh paths waste motion. Two fixes:
+
+- **Line-of-sight smoothing** (grids): walk the path; if node `i` has clear LoS to node `i+2`, drop `i+1`.
+  Repeat. Removes staircase kinks cheaply.
+- **Funnel algorithm** (navmesh): given the polygon corridor, pull a taut string through the shared
+  edges (portals), advancing left/right apexes — produces the shortest path inside the corridor. This is
+  what quality navmesh systems run after the polygon search; emulate it if you build your own.
+
+## Choosing quickly
+
+| Situation | Pick |
+| --- | --- |
+| Free-roaming characters, 3D or open 2D | Navmesh + A* over polys + funnel |
+| Tile-locked / destructible / RTS grid | Grid + A* (or JPS if uniform cost) |
+| Constrained routes, patrols, rails | Waypoint graph + A* |
+| Nearest of many goals / cost field | Dijkstra |
+| Thousands of tiles, long shared routes | HPA* / hierarchical |
+| Many agents → one goal | Flow field (steering reference) |