@ericrisco/rsc 0.1.35 → 0.1.36

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.

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

package/skills/gamedev-pathing/references/steering-and-avoidance.md

@@ -0,0 +1,120 @@
+# Steering, local avoidance & flow fields
+
+Depth for the "Steering & local avoidance" section of SKILL.md. Steering is the **local** layer: given a
+global path (from A*/navmesh), produce a per-frame velocity that follows it while dodging neighbours. All
+formulas below assume a max speed and a max steering force (acceleration clamp).
+
+## The steering model (Reynolds)
+
+Each behaviour returns a **steering force** = `desired_velocity − current_velocity`, clamped to
+`max_force`. Apply it as acceleration, integrate velocity (clamped to `max_speed`), integrate position.
+
+```text
+steering = clamp(desired - velocity, max_force)
+velocity = clamp(velocity + steering, max_speed)
+position = position + velocity * dt
+```
+
+## Primitives (desired velocity per behaviour)
+
+- **Seek**: `desired = normalize(target - pos) * max_speed`.
+- **Flee**: seek negated — `desired = normalize(pos - target) * max_speed`.
+- **Arrive**: seek that ramps down inside a slowing radius, so the agent settles instead of orbiting:
+  ```text
+  to_target = target - pos;  dist = length(to_target)
+  speed = (dist < slow_radius) ? max_speed * dist/slow_radius : max_speed
+  desired = to_target/dist * speed
+  ```
+- **Pursue**: seek the target's **predicted** position: `predict = target_pos + target_vel * T`, where
+  `T` scales with distance (`T = dist / max_speed`). **Evade** = flee that prediction.
+- **Wander**: keep a point on a small circle projected ahead of the agent, jitter it slightly each frame,
+  seek it — gives smooth, non-robotic idle motion (unlike raw random which twitches).
+- **Obstacle avoidance**: cast a probe (feeler) ahead; if it hits a static obstacle, add a lateral force
+  away from the obstacle's center. This is a *steering* dodge, distinct from navmesh carving.
+
+## Combining behaviours
+
+- **Weighted sum**: `total = Σ wᵢ · forceᵢ`, then clamp. Simple; can average into indecision (two forces
+  cancel and the agent freezes between them).
+- **Priority / arbitration**: evaluate in order (avoidance → separation → path-follow → cohesion) and
+  take the first non-trivial force, or accumulate with a running-force budget until clamp is hit. More
+  robust for "avoidance must win".
+
+## Path following
+
+Do **not** seek the far goal — seek a moving point along the corridor:
+
+1. Find the point on the path polyline nearest the agent.
+2. Advance a **look-ahead** distance along the path from there → target point.
+3. **Arrive** at that target; when close to the final waypoint, arrive at the true goal.
+
+Look-ahead too short = the agent hugs corners and jitters; too long = it cuts corners and leaves the
+corridor. Tune to roughly one agent radius + a fraction of current speed. Engine agents
+(`NavigationAgent.get_next_path_position`, `NavMeshAgent`) do this internally — you feed the corridor,
+they hand back the next point.
+
+## Flocking (boids)
+
+Three neighbour-based forces within a perception radius; sum with weights:
+
+- **Separation** — steer away from the average offset to close neighbours (usually the strongest weight;
+  prevents overlap).
+- **Alignment** — steer toward the average heading of neighbours (group moves as one).
+- **Cohesion** — steer toward the average position of neighbours (group stays together).
+
+Typical starting weights: separation 1.5, alignment 1.0, cohesion 1.0 — then tune. Combine with
+path-following (the flock follows a global path while holding formation).
+
+## Local avoidance: RVO / ORCA
+
+Reynolds separation is reactive and oscillates in crowds. **Velocity-obstacle** methods are the modern
+answer:
+
+- A **velocity obstacle (VO)** for a neighbour is the set of your velocities that would collide with it
+  within a time horizon. **RVO** (Reciprocal VO) assumes *both* agents share the avoidance effort, so
+  each takes half the correction — this kills the "two agents dance side-to-side" oscillation.
+- **ORCA** (Optimal Reciprocal Collision Avoidance) formulates each neighbour as a half-plane constraint
+  on your velocity and picks, via linear programming, the collision-free velocity nearest your desired
+  one. It scales to dense crowds and is what most engine crowd systems implement.
+- Key idea: avoidance adjusts the **intended velocity before you move**. It is *not* collision response
+  — the physics solver (see `gamedev-physics`) is the last-resort backstop when agents still overlap
+  under pressure. Overlap under crush is expected, not a bug.
+
+**Per-engine:** Godot `NavigationAgent` avoidance (`avoidance_enabled` + `set_velocity` →
+`velocity_computed` signal, RVO2-based). Unity `NavMeshAgent.obstacleAvoidanceType` (quality levels,
+RVO). Unreal **Detour Crowd** manager / `DetourCrowdAIController` (RVO/ORCA-style for many pawns);
+`RVOAvoidance` on `CharacterMovementComponent` for a lighter option.
+
+## Flow fields — many agents, one goal
+
+When hundreds/thousands of agents share a goal (RTS swarm, tower-defense creeps), one A* *per agent* is
+wasteful. Build the field once, then every agent samples O(1):
+
+1. **Cost field**: per-cell traversal cost (walls = impassable, terrain = weighted).
+2. **Integration field**: run **Dijkstra/BFS from the goal** outward, storing each cell's cheapest total
+   cost to reach the goal. (This is why Dijkstra, not A* — you want the whole field, not one path.)
+3. **Flow field**: for each cell, store a direction vector pointing to the lowest-cost neighbour.
+4. **Per agent, per frame**: sample the flow vector at the agent's cell, use it as the desired direction,
+   then layer local avoidance (separation/RVO) so they don't stack.
+
+Rebuild only when the goal or the cost field changes. Multiple goals = seed the Dijkstra from all goal
+cells at once (agents flow to the nearest). Flow fields also smooth naturally (bilinear-sample the
+vectors across cells).
+
+When to choose it: **many agents → few goals**. For a handful of agents to distinct goals, per-agent A*
+or navmesh is simpler and gives better individual paths.
+
+## Combining the two layers (the whole loop)
+
+```text
+on new goal:            path = search(start, goal)      # global, occasional
+every frame per agent:
+    look = lookahead_point(path, pos)                   # follow the corridor
+    desired = arrive(look)                              # path following
+    desired += separation + rvo(neighbours)             # local avoidance
+    velocity = integrate(clamp(desired))                # steer, don't teleport
+    move(velocity); resolve_collisions()                # physics backstop
+```
+
+Global path answers *where*; steering + avoidance answer *how to move now*; physics is the final contact
+resolver. Keep them distinct and each stays cheap and debuggable.

package/skills/gamedev-physics/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: gamedev-physics
+description: "Use when working with a game engine's physics — rigid bodies, colliders, collision layers/masks, character controllers, joints, forces vs impulses, raycasts/shapecasts, or when physics is unstable. Triggers: \"my character falls through the floor\", \"bullet tunnels through walls at high speed\", \"rigidbody jitters / vibrates / explodes\", \"objects that should collide pass through each other\", \"which collision layer and mask do I set\", \"kinematic vs dynamic body\", \"move_and_slide / CharacterBody\", \"AddForce vs impulse vs setting velocity\", \"physics in FixedUpdate or _physics_process\", \"slope and step detection\", \"trigger / Area overlap not firing\", Godot RigidBody/StaticBody/CharacterBody/Area, Unity Rigidbody/Collider/CharacterController, Unreal Chaos/collision presets. NOT rendering, materials, or visual jitter from shaders (use gamedev-shaders); NOT AI navigation, pathfinding, or navmesh (use gamedev-pathing)."
+tags: [physics, collision, rigidbody, character-controller, colliders]
+recommends: [godot, unity, unreal, gamedev-pathing]
+profiles: [full]
+origin: risco
+---
+
+# Game physics & collision
+
+Make bodies collide, move, and stay stable across Godot, Unity, and Unreal. This skill owns the
+mental model (body types, colliders, layers/masks, character controllers, joints, queries,
+determinism) and maps every concept onto each engine's real API. When physics "feels broken" —
+jitter, tunneling, sinking, ghost collisions — the cause is almost always one of: wrong body type,
+a layer/mask mismatch, or moving/integrating outside the fixed physics tick. Check those first.
+
+## Version contract — read first (never emit these)
+
+| Engine | Target | Banned / deprecated | Use instead |
+| --- | --- | --- | --- |
+| **Godot** | 4.x | `move_and_slide(velocity, up, ...)` with arguments (that is Godot 3) | Godot 4 `move_and_slide()` takes **no args**; set the `velocity` property first |
+| Godot | 4.x | `KinematicBody2D/3D`, `RayShape`, `WorldMarginShape`, `linear_velocity *= delta` before `move_and_slide()` | `CharacterBody2D/3D`, `SeparationRayShape2D/3D`, `WorldBoundaryShape2D/3D`; `move_and_slide()` is already delta-scaled |
+| **Unity** | Unity 6 (6000.x) | `Rigidbody.velocity` / `Rigidbody2D.velocity`, `rb.drag`, `rb.angularDrag` | `linearVelocity` (+ `linearVelocityX/Y`), `linearDamping`, `angularDamping`; new `AddForceX/Y` |
+| Unity | Unity 6 | moving a dynamic `Rigidbody` from `Update`; `transform.position =` on a physics body | move in `FixedUpdate`; use `MovePosition`/`AddForce`, never write `transform` on a simulated body |
+| **Unreal** | UE5 (Chaos) | any PhysX/APEX API, `bUseAsyncScene`, `NvCloth` | Chaos is the only physics backend in UE5; use `UPrimitiveComponent` physics + `PhysicsConstraintComponent` |
+
+If you are unsure a symbol exists in the user's exact version, say so instead of inventing it.
+
+## When to use / When NOT to use
+
+**Use when:** designing which body type a thing should be; something falls through, sinks into, or
+passes through geometry; a rigid body jitters, drifts, or launches; setting up collision
+layers/masks/channels; building or fixing a character/player controller; adding joints; casting
+rays/shapes or overlap tests; or physics behaves differently at different frame rates.
+
+**When NOT to use (delegate):**
+- Visual-only wobble, shader/vertex animation, material or lighting issues → **gamedev-shaders**.
+- AI moving along a path, navmesh, A*, steering, avoidance → **gamedev-pathing** (physics only
+  *executes* the move; pathing decides *where*).
+- Deep, engine-specific project setup / editor / build questions → **godot**, **unity**, **unreal**.
+- Netcode, lockstep sync, server-authoritative movement → **gamedev-multiplayer** (this skill gives
+  you the *deterministic fixed-tick* foundation multiplayer builds on).
+
+## 1. Body types — pick before you touch anything
+
+Three categories exist in every engine; choosing wrong is the root of most bugs.
+
+- **Static** — never moves, infinite mass, cheap. Level geometry, walls, floors. Do **not** move a
+  static body every frame; the broadphase caches it. If it must move, it is not static.
+- **Kinematic / character** — moved *by you* (code/animation), pushes dynamics but is not pushed by
+  them, ignores forces and gravity unless you add them. Players, moving platforms, doors, elevators.
+- **Dynamic (rigid)** — fully simulated: gravity, forces, impulses, collision response. Crates,
+  ragdolls, debris, vehicles. You influence it with forces/impulses, never by writing its transform.
+
+**Move each the right way:**
+
+| | Static | Kinematic / character | Dynamic |
+| --- | --- | --- | --- |
+| Godot | `StaticBody2D/3D` (leave still) | `CharacterBody2D/3D` + `move_and_slide()`; `AnimatableBody2D/3D` for platforms (set `sync_to_physics`) | `RigidBody2D/3D` (`apply_impulse`, `apply_force`) |
+| Unity | Collider, no Rigidbody (or `Rigidbody2D` bodyType Static) | `CharacterController.Move()`, or `Rigidbody.isKinematic=true` + `MovePosition` in `FixedUpdate` | `Rigidbody` (`AddForce`) |
+| Unreal | `Static`/`Movable` mobility, Simulate Physics off | `Character` + `CharacterMovementComponent`; movable component moved by code | Simulate Physics on (`SetSimulatePhysics(true)`) |
+
+A Godot `RigidBody` can be temporarily frozen: set `freeze = true` with `freeze_mode =
+FREEZE_MODE_KINEMATIC` to move it by transform without waking the solver wrongly. Prefer
+`AnimatableBody` for a permanent kinematic mover.
+
+## 2. Colliders / shapes
+
+Collider ≠ visual mesh. Give every body a **separate, simpler** collision shape.
+
+- **Primitives** (box, sphere/circle, capsule) — cheapest and most stable. Prefer a **capsule** for
+  characters (rounded ends slide over steps and seams). Use these whenever possible.
+- **Convex hull** — dynamic bodies can use a convex approximation; a concave prop needs **multiple
+  convex pieces** (a compound), not one concave hull.
+- **Concave / trimesh** — exact triangle mesh, but **static-only** in every engine. A moving
+  concave-mesh collider is a top cause of tunneling and solver blowups. Never put a trimesh on a
+  dynamic body.
+- **Compound** — several child shapes on one body. Godot: multiple `CollisionShape` children. Unity:
+  multiple `Collider` components. Unreal: multiple primitives / a body setup.
+- **Triggers / areas** — detect overlap, **no physical response**. Godot `Area2D/3D` (signals
+  `body_entered` / `area_entered`); Unity collider `Is Trigger` (`OnTriggerEnter/Stay/Exit`); Unreal
+  set response to **Overlap** + `Generate Overlap Events` (`OnComponentBeginOverlap`). Use for
+  pickups, damage zones, checkpoints, sensors.
+
+## 3. Collision layers & masks — the #1 confusion
+
+**Layer = "what I am." Mask = "what I scan for."** They are separate bit sets.
+
+- **Godot:** two bodies interact when **one's `collision_mask` includes the other's
+  `collision_layer`** — it is an **OR**, so detection can be asymmetric (A sees B without B seeing
+  A). Keep them symmetric unless you deliberately want one-way detection. An `Area`'s `mask` decides
+  what it detects; its `layer` decides what detects *it*.
+- **Unity:** GameObject **Layers** + the **Layer Collision Matrix** (Project Settings → Physics)
+  decide which layer pairs collide. Raycasts/overlaps take a `LayerMask` argument. Toggle a pair at
+  runtime with `Physics.IgnoreLayerCollision`.
+- **Unreal:** **Object Type** (channel) = what I am; per-channel **Response** = Block / Overlap /
+  Ignore. Package as a reusable **Collision Preset**. Trace channels (Visibility, Camera) are for
+  queries; object channels are for physical collision.
+
+Full worked examples (player/enemy/pickup/wall, bit math, one-way platforms) →
+`references/layers-and-masks.md`.
+
+## 4. Character controllers
+
+Two philosophies — decide up front, don't mix:
+
+- **Kinematic character** (recommended for most players): you compute velocity and move via a
+  sweeping helper that resolves collisions and slides. Precise, snappy, no solver fighting. Godot
+  `CharacterBody`, Unity `CharacterController`, Unreal `CharacterMovementComponent`.
+- **Dynamic (rigidbody) character**: physical pushing/being-pushed for free, but needs high friction
+  or a physics material, angular constraints (freeze rotation), and tuning to stop tipping/sliding.
+
+Godot 4 (2D — the 3D version is identical with `Vector3` and `get_gravity()`):
+
+```gdscript
+extends CharacterBody2D
+
+const SPEED := 300.0
+const JUMP_VELOCITY := -400.0
+
+func _physics_process(delta: float) -> void:
+    if not is_on_floor():
+        velocity += get_gravity() * delta        # accumulate accel: scale by delta
+    if Input.is_action_just_pressed("jump") and is_on_floor():
+        velocity.y = JUMP_VELOCITY
+    var dir := Input.get_axis("move_left", "move_right")
+    velocity.x = dir * SPEED if dir else move_toward(velocity.x, 0.0, SPEED)
+    move_and_slide()                              # Godot 4: NO args, uses `velocity`, already delta-scaled
+```
+
+`is_on_floor()` / `is_on_wall()`, `floor_max_angle` (slope limit), `floor_snap_length` (stick to
+ground on ramps/stairs), and `up_direction` handle ground/slope/step behavior. `get_gravity()` is
+Godot 4.3+; on older 4.x read `ProjectSettings` gravity. Full per-engine controllers (Unity
+`CharacterController` + custom gravity, Unreal movement modes, ground detection, slopes, steps,
+moving platforms) → `references/character-controllers.md`.
+
+## 5. Joints/constraints & how to apply motion
+
+**Joints** connect two bodies with a constraint. Godot: `PinJoint`, `HingeJoint3D`, `SliderJoint3D`,
+`Generic6DOFJoint3D`, `DampedSpringJoint2D`. Unity: `HingeJoint`, `FixedJoint`, `SpringJoint`,
+`ConfigurableJoint`, `CharacterJoint`. Unreal: `PhysicsConstraintComponent` (one 6-DOF constraint
+covers hinge/slider/ball). Keep connected bodies' **mass ratios close** — a heavy body chained to a
+light one is the classic joint-explosion.
+
+**Force vs impulse vs direct velocity** (apply all in the fixed tick):
+
+| Want | Use | Godot | Unity | Unreal |
+| --- | --- | --- | --- | --- |
+| Continuous push (thrust, wind), mass-scaled | **Force** | `apply_central_force` | `AddForce(f, Force)` | `AddForce` |
+| Instant kick (jump, explosion, hit), mass-scaled | **Impulse** | `apply_central_impulse` | `AddForce(f, Impulse)` | `AddImpulse` |
+| Instant velocity change, **ignoring mass** | mass-independent impulse | set `linear_velocity` | `AddForce(f, VelocityChange)` | `SetPhysicsLinearVelocity` |
+
+Setting velocity directly on a *dynamic* body teleports its momentum and can fight the solver — fine
+for character/kinematic bodies, use sparingly on dynamics (prefer forces/impulses).
+
+## 6. Queries — raycasts, shapecasts, overlaps
+
+Run queries from the **fixed physics tick** so results match the simulated state.
+
+- **Godot:** get `get_world_2d().direct_space_state` (or 3d), build
+  `PhysicsRayQueryParameters2D/3D` / `PhysicsShapeQueryParameters2D/3D`, call `intersect_ray`,
+  `intersect_shape`, `cast_motion`. Node helpers: `RayCast2D/3D`, `ShapeCast2D/3D`. Queries respect
+  `collision_mask`.
+- **Unity:** `Physics.Raycast`, `SphereCast`/`CapsuleCast`, `OverlapSphere`, `CheckSphere` (2D:
+  `Physics2D.*`). Always pass a `LayerMask`; prefer non-allocating `RaycastNonAlloc`/`RaycastAll`.
+- **Unreal:** `LineTraceSingleByChannel`, `SweepSingleByChannel`, `OverlapMultiByChannel` (and
+  `...ByObjectType`). Use a **trace channel**, set the query params (`bTraceComplex`).
+
+Details, snippets, and the tunneling-safe shapecast pattern → `references/determinism-and-queries.md`.
+
+## 7. Determinism & stability
+
+The rules that keep physics from jittering, drifting, or tunneling:
+
+1. **Physics lives in the fixed tick.** Godot `_physics_process(delta)`, Unity `FixedUpdate()`,
+   Unreal substepping / async physics tick. Read input in the frame update, *apply* it in the fixed
+   tick. Never simulate in the render frame.
+2. **Scale by delta.** Multiply forces/accelerations/manual position changes by the tick's `delta` /
+   `fixedDeltaTime` — but **not** the output of a helper that already integrates time (Godot
+   `move_and_slide()`, Unity `CharacterController.Move` when you pass a per-second velocity).
+3. **CCD for fast/thin things.** Small fast projectiles + thin walls tunnel. Enable Continuous
+   Collision Detection: Godot `continuous_cd`, Unity `collisionDetectionMode = Continuous*`, Unreal
+   `Use CCD`. Enable only on the fast bodies (it costs). Or use a shapecast/raycast-then-move.
+4. **Keep mass ratios sane.** Stacks and joints between wildly different masses (100:1+) blow up.
+5. **Never scale a collider at runtime**, and never write `transform`/`position` on a dynamic body —
+   both corrupt the broadphase and cause explosions or ghost collisions. Move via the API.
+6. **Interpolate for smooth visuals** at high frame rates: Godot physics interpolation, Unity
+   `Rigidbody.interpolation = Interpolate`. This is visual only — it never changes the simulation.
+
+Deeper: fixed-timestep math, substepping, sleeping, why `transform` writes break things →
+`references/determinism-and-queries.md`.
+
+## Guardrails / gotchas
+
+- Falling through a thin floor at speed → CCD off, or moving in the render frame. Fix both.
+- A moving platform doesn't carry the player → use a kinematic mover (Godot `AnimatableBody` with
+  `sync_to_physics`, Unity kinematic Rigidbody `MovePosition`), not a static body.
+- "Ghost" collisions / catching on seams between tiles → merge colliders or use a capsule character.
+- Trigger never fires → in Unity a trigger pair needs at least one **Rigidbody**; in Godot the
+  Area's `mask` must include the body's `layer`; in Unreal enable Generate Overlap Events on **both**.
+- Rigidbody vibrates against the ground → mass ratio, too-soft solver iterations, or you're also
+  writing its transform. Stop writing the transform.
+- Character launches off ramps → enable floor snapping (`floor_snap_length` / stop-on-slope).
+
+## Related skills
+
+- **godot** / **unity** / **unreal** — engine setup, editor, language, and build specifics.
+- **gamedev-pathing** — decides *where* to move; this skill *executes* the move and collisions.
+- **gamedev-multiplayer** — builds on the deterministic fixed-tick foundation here.
+- **gamedev-shaders** — for visual/material issues that only look like physics.
+
+## Checklist
+
+- [ ] Every moving thing has the right **body type** (static / kinematic / dynamic).
+- [ ] Colliders are **primitives/capsules**; no trimesh on a dynamic body; compound = many convex.
+- [ ] Layers/masks (or channels/presets) set so exactly the intended pairs collide; triggers use
+      overlap/Area, not solid response.
+- [ ] All physics motion and queries run in the **fixed tick**; deltas scaled correctly (helper
+      output not double-scaled).
+- [ ] Forces/impulses/velocity chosen deliberately; no `transform`/`position` writes on dynamics; no
+      runtime collider scaling.
+- [ ] Fast/thin bodies have **CCD**; character has floor/slope/step handling; mass ratios are sane.
+- [ ] Correct API for the stated engine **version** (Godot 4 `move_and_slide()` no args; Unity 6
+      `linearVelocity`; UE5 Chaos — no PhysX).

package/skills/gamedev-physics/evals/README.md

@@ -0,0 +1,12 @@
+# Eval harness — `gamedev-physics` skill
+
+These cases are read by the rsc skill-eval harness (a Claude agent with the full catalog loaded), or
+by hand. They check two things. **Triggering:** the description fires on real physics symptoms —
+tunneling, jitter, layer/mask filtering, forces-vs-impulses, character controllers — and stays quiet
+on near-misses, routing shader shimmer to `gamedev-shaders`, navmesh/pathfinding to
+`gamedev-pathing`, editor/export setup to `godot`, netcode to `gamedev-multiplayer`, and gameplay
+design to `game-design`. **Capability:** with `SKILL.md` and its references loaded, the answer uses
+the version-correct API (Godot 4 `move_and_slide()` with no args, Unity 6 `linearVelocity`, UE5
+Chaos), puts simulation in the fixed tick, scales delta correctly, and picks the right body type /
+collider / layer-mask / CCD fix. Routing is non-deterministic — run 3–5 trials per prompt and pass
+on a majority; capability is judged by reading the output against the `must_include` bullets.