@ericrisco/rsc 0.1.35 → 0.1.36

package/skills/gamedev-multiplayer/references/prediction-and-latency.md

@@ -0,0 +1,104 @@
+# Prediction, reconciliation & latency hiding
+
+The whole reason netcode is hard: the speed of light. A round trip (RTT) of 60–150 ms is normal, and if the
+owning client had to wait a full RTT to see its own movement, the game would feel broken. The techniques
+below keep it responsive **without** giving up server authority. This is engine-agnostic theory; the
+per-engine references show where the hooks live.
+
+## The authoritative loop (mental model)
+
+1. Client samples input each tick, tags it with a **sequence number**, sends it to the server, and **applies
+   it locally immediately** (prediction).
+2. Server receives inputs, simulates them on its fixed tick, and produces authoritative state. It stamps each
+   state snapshot with the last input sequence number it processed for that client.
+3. Client receives the authoritative snapshot, **reconciles**: snap to the server state, then re-apply every
+   input *after* the acknowledged sequence number (they haven't reached the server yet).
+4. Other (remote) entities are rendered from buffered snapshots, **interpolated** slightly in the past.
+
+Server is always the source of truth. The client only ever *guesses ahead* and gets corrected.
+
+## 1. Client-side prediction
+
+The owning client runs the same movement code the server will run, on the same fixed timestep, the instant it
+presses a key — no waiting. Requirements:
+
+- **Deterministic** movement/simulation for the predicted entity (same input + same state → same result).
+  This is why `gamedev-physics` determinism matters here.
+- A **ring buffer** of unacknowledged inputs (`{seq, dt, input}`), kept until the server acknowledges them.
+- Predict only what the client owns (its pawn). Never predict other players — interpolate them instead.
+
+## 2. Server reconciliation
+
+When an authoritative snapshot arrives tagged "processed up to input N":
+
+```
+clientState = serverState               # trust the server
+discard buffered inputs with seq <= N   # server already applied these
+for each remaining buffered input (seq > N):
+    clientState = simulate(clientState, input)   # replay the unacknowledged ones
+```
+
+If the replayed result matches what the client already had, the correction is invisible. If it diverges (the
+server disagreed — lag, a missed collision, a rejected move), the entity snaps: the visible **rubber-band**.
+Goal is to *minimize* divergence, not to suppress the correction — hiding a legitimate correction is how you
+get players walking through walls on their screen.
+
+- **Smoothing**: for small corrections, blend toward the corrected position over a few frames instead of
+  hard-snapping, so a 2 cm disagreement isn't a visible pop. Hard-snap large ones.
+
+## 3. Snapshot interpolation (remote entities)
+
+You receive remote entities' state only every send-tick (e.g. every 50 ms) — rendering the latest packet
+directly makes them teleport. Instead, keep a small buffer and render them ~1–2 snapshots **in the past**:
+
+- **Interpolation delay** ≈ 100 ms (2× send interval + jitter margin). Render remote entities at
+  `now − delay`, interpolating between the two snapshots that straddle that time.
+- Trade-off: everyone else is shown slightly in the past. That is fine and standard.
+- **Extrapolation** (dead reckoning) predicts a remote entity forward when a packet is late — cheaper on
+  bandwidth but wrong on direction changes; prefer interpolation and only extrapolate briefly to cover a gap.
+
+So on one client, three clocks coexist: **its own pawn** = present (predicted), **remote entities** = past
+(interpolated), **the server** = the arbiter reconciling the two.
+
+## 4. Lag compensation (server-side rewind)
+
+For instant/hitscan hits, the shooter aimed at where they *saw* the target — which is `interpolation delay +
+½ RTT` in the past. If the server tests the hit against the target's *present* position, the shooter misses
+despite a perfect aim. Fix: the server keeps a short **history** of every entity's recent positions and, when
+processing a shot, **rewinds** the world to the shooter's view time before testing the hit.
+
+- Store ~1 second of position history per entity (a ring of transforms per tick).
+- On a shot: reconstruct positions at `clientRenderTime`, run the trace, then restore.
+- Trade-off: the victim can be hit just after ducking behind cover ("shot behind the wall"). This is an
+  accepted fairness choice favoring the shooter; cap how far back you rewind to bound the unfairness.
+
+## 5. Tick rate, send rate, netrate
+
+- **Simulation tick** — fixed Hz the server steps the world (20 / 30 / 60+; higher = more precise + more CPU).
+- **Send rate / snapshot rate** — how often state goes on the wire; often lower than sim tick, and independent
+  of client render FPS. This is the "netrate/updaterate/cmdrate" family in shooters.
+- **Client render FPS** — decoupled from both; render via interpolation between fixed-step states.
+- Bandwidth ≈ replicated-bytes × send-rate × relevant-peers. Shrink it with relevancy/visibility scoping,
+  quantized/delta-compressed fields, and lower send rates for distant or unimportant actors.
+
+**Never run gameplay in a variable `_process`/`Update`/`Tick` on a networked game** — use a fixed timestep
+(`_physics_process`, `NetworkUpdate`/`FixedUpdate`, Unreal's fixed sim) so prediction and reconciliation
+replay identically on client and server.
+
+## Alternative model: deterministic lockstep / rollback
+
+For fighting games and some RTS: no per-frame state replication at all — every peer runs the identical
+deterministic simulation and only **inputs** are exchanged. **Lockstep** waits for all inputs before advancing
+(one slow peer stalls everyone). **Rollback** (GGPO-style) predicts absent inputs, then rolls back and
+re-simulates when the real inputs arrive — excellent feel, but demands *bit-perfect determinism* (watch
+floats, iteration order, RNG) and bounded state you can snapshot/restore cheaply. Choose it only when you can
+guarantee that determinism; otherwise the client-server model above is the safer default.
+
+## Checklist for a responsive authoritative game
+
+- [ ] Owning pawn predicted locally on a fixed timestep; inputs buffered with sequence numbers.
+- [ ] Server acks the last processed input seq in each snapshot; client replays unacknowledged inputs.
+- [ ] Small corrections smoothed, large ones snapped; corrections never fully suppressed.
+- [ ] Remote entities interpolated ~100 ms in the past from a snapshot buffer.
+- [ ] Hitscan uses server-side rewind bounded to ~1 s of history.
+- [ ] Sim tick / send rate / render FPS all decoupled; bandwidth scoped by relevancy.

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"