@ericrisco/rsc 0.1.34 → 0.1.36

package/skills/gamedev-multiplayer/references/unity-and-unreal-netcode.md

@@ -0,0 +1,166 @@
+# Unity & Unreal netcode
+
+Per-engine deep dive for the two C#/C++ engines. Godot lives in its own reference.
+
+---
+
+## Unity — Netcode for GameObjects (NGO)
+
+NGO is Unity's first-party high-level netcode. **UNet / HLAPI is removed** — never emit `NetworkIdentity`,
+`[Command]`, `[SyncVar]`, `NetworkServer`, or anything under `UnityEngine.Networking`. (Mirror is a
+community fork with a UNet-like API; if a repo uses it, name it, but this reference targets NGO.)
+
+### Setup & session
+
+- One `NetworkManager` in the scene, with a chosen transport (Unity Transport / UTP).
+- Start a session: `NetworkManager.Singleton.StartHost()` (server + local client), `.StartServer()`
+  (dedicated/headless), or `.StartClient()`.
+- Networked prefabs need a `NetworkObject` and must be registered in the NetworkManager prefab list;
+  the **server** spawns them: `Instantiate(...).GetComponent<NetworkObject>().Spawn()`.
+
+### NetworkBehaviour, roles, lifecycle
+
+Networked scripts derive from `NetworkBehaviour`. Use `OnNetworkSpawn()` / `OnNetworkDespawn()` instead of
+`Start` for network-aware init. Role/ownership properties: `IsServer`, `IsClient`, `IsHost`, `IsOwner`,
+`OwnerClientId`, `NetworkObjectId`.
+
+### NetworkVariable — replicated state
+
+```csharp
+public class PlayerState : NetworkBehaviour {
+    // Default: read Everyone, write Server → authoritative health.
+    public NetworkVariable<int> Health = new(100);
+
+    // Client convenience state: owner writes, everyone reads.
+    public NetworkVariable<int> SkinIndex =
+        new(0, NetworkVariableReadPermission.Everyone, NetworkVariableWritePermission.Owner);
+
+    // Hidden-from-others: owner reads, owner writes.
+    public NetworkVariable<int> Ammo =
+        new(default, NetworkVariableReadPermission.Owner, NetworkVariableWritePermission.Owner);
+
+    public override void OnNetworkSpawn() {
+        Health.OnValueChanged += (prev, cur) => UpdateHealthBar(cur);
+    }
+}
+```
+
+`NetworkVariableReadPermission` is `Everyone` | `Owner`; `NetworkVariableWritePermission` is `Server` |
+`Owner`. Default (no perms arg) = read Everyone, write Server — the right default for authoritative gameplay
+values. Only the permitted writer may assign `.Value`; a client writing a server-write variable is ignored.
+
+### RPCs
+
+NGO 2.x's unified attribute is preferred:
+
+```csharp
+[Rpc(SendTo.Server)]                 // client → server
+void FireRpc(Vector3 target) { /* runs on server; validate + apply */ }
+
+[Rpc(SendTo.ClientsAndHost)]         // server → all clients (+ host)
+void PlayFxRpc(Vector3 at) { /* cosmetic */ }
+
+[Rpc(SendTo.Owner)]                  // server → the owning client only
+void YouWereHitRpc(int dmg) { }
+```
+
+`SendTo` options include `Server`, `ClientsAndHost`, `Everyone`, `Owner`, `NotServer`, `SpecifiedInParams`.
+The **legacy** attributes still compile and enforce method-name suffixes:
+
+```csharp
+[ServerRpc(RequireOwnership = true)]  void FireServerRpc(Vector3 t) { }   // name MUST end in ServerRpc
+[ClientRpc]                           void PlayFxClientRpc(Vector3 a) { } // name MUST end in ClientRpc
+```
+
+Prefer `[Rpc(SendTo.X)]` on new code; recognize the legacy pair in existing code. RPCs are unreliable by
+default for some configs — mark reliability via the attribute's `Delivery` where consistency matters.
+
+### Transforms & movement
+
+`NetworkTransform` replicates position/rotation/scale (server-authoritative by default; an
+`OwnerNetworkTransform`/authority setting allows client-authoritative). For server-authoritative movement
+with responsiveness you add prediction yourself (NGO does not ship full prediction; see
+prediction-and-latency.md). `NetworkAnimator` syncs Animator state.
+
+### Gotchas
+
+- Only the **server** may `Spawn()`/`Despawn()` NetworkObjects.
+- Writing a `NetworkVariable` you don't have write permission for silently no-ops — check perms first.
+- `IsOwner` ≠ `IsServer`; on a listen host both can be true. Gate authoritative logic on `IsServer`.
+- Legacy RPC name-suffix rule is a compile error if violated; the unified `[Rpc]` has no such rule.
+
+---
+
+## Unreal Engine 5.x — Actor replication
+
+Replication is per-`AActor`. Turn it on (`bReplicates = true` in the constructor or `SetReplicates(true)`),
+mark properties, and register them. RPCs are `UFUNCTION`s with network specifiers.
+
+### Replicated properties
+
+```cpp
+// Header
+UPROPERTY(Replicated)
+int32 Score = 0;
+
+UPROPERTY(ReplicatedUsing = OnRep_Health)     // RepNotify: OnRep_Health() runs on clients on change
+float Health = 100.f;
+
+UFUNCTION() void OnRep_Health();
+
+// Cpp — every replicated prop MUST be registered here
+void AMyPawn::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& Out) const {
+    Super::GetLifetimeReplicatedProps(Out);
+    DOREPLIFETIME(AMyPawn, Score);
+    DOREPLIFETIME(AMyPawn, Health);
+    // DOREPLIFETIME_CONDITION(AMyPawn, Ammo, COND_OwnerOnly);   // owner-only relevancy
+}
+```
+
+`ReplicatedUsing` (RepNotify) is how you react to a change — use it instead of polling the value in `Tick`.
+The **push model** (`SetReplicatedByCondition` / `MARK_PROPERTY_DIRTY`) avoids per-frame comparison for
+high-count actors.
+
+### RPCs
+
+```cpp
+UFUNCTION(Server, Reliable, WithValidation)   // client → server (validated)
+void ServerFire(FVector Target);
+bool ServerFire_Validate(FVector Target) { return Target.SizeSquared() < 1e8f; }
+void ServerFire_Implementation(FVector Target) { /* server applies */ }
+
+UFUNCTION(Client, Reliable)                    // server → owning client
+void ClientNotifyHit(int32 Dmg);
+
+UFUNCTION(NetMulticast, Unreliable)            // server → all relevant clients
+void MulticastMuzzleFx(FVector At);
+```
+
+- `Server` RPCs run on the server, callable by the owning client; add `WithValidation` for gameplay-critical
+  ones and reject cheating inputs in `_Validate`.
+- `Client` RPCs run on the actor's owning client only.
+- `NetMulticast` runs on the server and all relevant clients — cosmetic events; keep unreliable.
+- `Reliable` vs `Unreliable`: reliable is guaranteed+ordered but can saturate; reserve for gameplay.
+
+### Roles, authority, relevancy
+
+- `HasAuthority()` → true on the server (or standalone). Guard server logic with it.
+- `GetLocalRole()`: `ROLE_Authority` (server), `ROLE_AutonomousProxy` (the owning client's predicted pawn),
+  `ROLE_SimulatedProxy` (an observed remote actor). Prediction lives on autonomous proxies.
+- **Relevancy** controls what each client receives: `NetCullDistanceSquared`, `bAlwaysRelevant`,
+  `bOnlyRelevantToOwner`, override `IsNetRelevantFor`, and **dormancy** (`SetNetDormancy(DORM_DormantAll)`)
+  to stop replicating quiescent actors. This is the main bandwidth/anti-wallhack lever.
+
+### Movement & prediction
+
+`UCharacterMovementComponent` already implements client-side prediction + server reconciliation for
+character movement — use `ACharacter` and let it do the work rather than hand-rolling. For abilities, the
+Gameplay Ability System (GAS) has prediction; the Network Prediction plugin generalizes it (experimental).
+
+### Gotchas
+
+- Forgetting `DOREPLIFETIME` = the property silently never replicates.
+- RPC specifiers are directional: calling a `Server` RPC from the server, or a `Client` RPC from a client,
+  does nothing useful — respect the flow (client→Server, server→Client/Multicast).
+- Actors only replicate if `bReplicates` is true *and* the actor is net-relevant to that client.
+- On a listen server the host is authority + local player; `HasAuthority()` is your gate.

package/skills/gamedev-pathing/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: gamedev-pathing
+description: "Use when implementing AI navigation or pathfinding in a game - moving enemies/NPCs/units toward goals, \"how do enemies navigate the level\", A*/Dijkstra/JPS/HPA* search, choosing grid vs waypoint-graph vs navmesh, baking a navmesh and tuning agent radius/height, off-mesh/nav links, dynamic obstacles and re-baking, steering (seek/flee/arrive/pursue/wander/path-following/flocking), local avoidance (RVO/ORCA, crowds), and flow fields for many agents to one goal. Per-engine: Godot 4.x (NavigationServer2D/3D, NavigationRegion, NavigationAgent, get_next_path_position), Unity (NavMeshAgent + NavMeshObstacle + AI Navigation baking), Unreal (RecastNavMesh + AIController + Behavior Trees/EQS). Triggers: \"my enemies get stuck\", \"units clump together\", \"navmesh not updating\", \"agentes se atascan\". NOT physics/rigidbody collision response or character-controller tuning (gamedev-physics), and NOT high-level enemy AI behaviour design like aggro/states/difficulty (game-design)."
+tags: [pathfinding, navmesh, navigation, steering, a-star]
+recommends: [godot, unity, unreal, gamedev-physics]
+profiles: [full]
+origin: risco
+---
+
+# 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`). 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`; this skill wires the BT's
+> movement/EQS tasks to navigation, not the decision tree's semantics.
+
+## Guardrails / gotchas
+
+- **Agent radius mismatch** is the top "stuck in doorways / clipping walls" cause — bake with the real radius.
+- Bake covers **static** geometry; runtime-spawned meshes need a rebake, a carving obstacle, or a nav link.
+- Path returns empty when start/end are **off the navmesh** or in disconnected islands — snap to nearest poly and check reachability first.
+- Avoidance (RVO) ≠ collision (physics). Agents can still overlap under pressure; that is expected, not a physics bug.
+- Off-mesh links are **directional and manual** — a jump-down link does not imply a jump-up link.
+- Smooth grid paths (funnel / string-pull) or agents walk visible zig-zag staircases.
+
+## Anti-patterns / rationalizations → STOP
+
+| Rationalization | Reality / do instead |
+| --- | --- |
+| "Just A* every frame, it's fine" | Melts CPU at scale; path on goal-change, steer between frames. |
+| "One navmesh bake works for every unit" | Radius/height differ; bake per agent size or use agent-type profiles. |
+| "Agents clip through each other — physics bug" | Missing **local avoidance**; enable RVO/crowd, that's the navigation layer. |
+| "Navmesh doesn't see my spawned wall" | Static bake; set Dynamic/rebake, or add a carving obstacle/nav link. |
+| "I'll grid-search my own A* in Unity/Unreal" | Reinvents the built-in navmesh; use `NavMeshAgent` / `AAIController::MoveTo`. |
+| "500 zombies each run A* to the player" | That's a **flow field**: one Dijkstra from the goal, agents sample cells. |
+| "Set `agent.destination` and read the path same frame" | Path is async (`pathPending`); gate on it before trusting `remainingDistance`. |
+| "Bigger heuristic = smarter" | Over-estimating `h` breaks A* optimality; keep it admissible (or weight it *knowingly*). |
+
+## 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` — 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*.
+
+## See Also — local references (read when)
+
+- `references/search-algorithms.md` — representations, A*/Dijkstra/JPS/HPA* pseudocode, heuristics & admissibility, tie-breaking, any-angle, funnel smoothing.
+- `references/navmesh-workflow.md` — bake-parameter table, areas/costs, off-mesh links, obstacles vs carving vs partial rebake, per-engine baking, debugging.
+- `references/steering-and-avoidance.md` — steering primitives, path following, boids weights, RVO/ORCA intuition, crowds, flow-field construction.

package/skills/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/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/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.