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

package/skills/shared/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/shared/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 and masks, character controllers, joints, forces versus impulses, raycasts and shapecasts, or when a simulation is unstable (tunnelling, jitter, missed overlaps). Covers the Godot, Unity and Unreal equivalents. NOT rendering or shader-driven visual jitter (that is `gamedev-shaders`), NOT navigation, pathfinding or navmesh (that is `gamedev-pathing`)."
+tags: [physics, collision, rigidbody, character-controller, colliders]
+recommends: [godot, unity, unreal, gamedev-pathing]
+profiles: [full]
+origin: ai-hub
+---
+
+# 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/shared/gamedev-physics/evals/README.md

@@ -0,0 +1,12 @@
+# Eval harness — `gamedev-physics` skill
+
+These cases are read by the ai-hub 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.

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

@@ -0,0 +1,54 @@
+skill: gamedev-physics
+
+should_trigger:
+  - prompt: "My player keeps falling through the floor when he moves fast, but it's fine when he walks slowly. Godot 4."
+    why: "Classic tunneling symptom (speed-dependent fall-through); routes here for CCD / fixed-tick + shapecast-then-move, not a generic debugger."
+  - prompt: "Two crates that should bump into each other just pass straight through. How do I set up the collision layer and mask so they collide?"
+    why: "Direct collision layer/mask filtering question — the #1-confusion section this skill owns."
+  - prompt: "In Unity should I put my rigidbody movement in Update or FixedUpdate? My box vibrates against the ground."
+    why: "Fixed-timestep placement + jitter stability, both core determinism topics; also touches the Unity version contract."
+  - prompt: "What's the difference between AddForce with Impulse mode, VelocityChange, and just setting velocity on a rigidbody?"
+    why: "Forces vs impulses vs direct velocity is an explicit section with a per-engine table."
+  - prompt: "I want a coin pickup that detects when the player walks over it but doesn't physically block them. What component do I use?"
+    why: "Trigger/Area overlap-with-no-response — colliders/triggers section; must not be treated as solid collision."
+  - prompt: "Building a first-person character controller in Godot 4 — how do I do gravity, jumping, and slopes with CharacterBody3D?"
+    why: "Character controller with move_and_slide/velocity and slope/step handling; also exercises the Godot 4 no-args move_and_slide version contract."
+  - prompt: "My rigidbody physics 'explodes' whenever a heavy object rests on a light one, or when I move the object by setting its transform each frame."
+    why: "Mass-ratio instability + writing transform on a dynamic body — two determinism guardrails this skill owns."
+
+should_not_trigger:
+  - prompt: "My water surface shader is shimmering and the reflections flicker at grazing angles. Fix the material."
+    route_to: "gamedev-shaders"
+    why: "Visual/material jitter from a shader, not simulated physics; explicitly delegated in the NOT-when clause."
+  - prompt: "My enemies need to find a path around obstacles to the player using a navmesh and avoid each other."
+    route_to: "gamedev-pathing"
+    why: "Navigation/pathfinding decides where to go; physics only executes the move. Delegated to gamedev-pathing."
+  - prompt: "How do I set up the Godot editor, import my project, and configure export templates for Android?"
+    route_to: "godot"
+    why: "Engine setup/editor/export tooling belongs to the godot engine skill, not the cross-engine physics concept skill."
+  - prompt: "Sync player movement across clients with server-authoritative netcode and rollback so it stays consistent."
+    route_to: "gamedev-multiplayer"
+    why: "Netcode/rollback is multiplayer's domain; this skill only supplies the deterministic fixed-tick foundation."
+  - prompt: "Design the combat loop and difficulty curve for my roguelike."
+    route_to: "game-design"
+    why: "Gameplay/systems design, no physics simulation, colliders, or bodies involved."
+
+capability:
+  - scenario: "User's fast bullet tunnels through thin walls in Unity 6, and they ask why and how to fix it, including a code snippet."
+    must_include:
+      - "Explains tunneling: the body moves more than its own thickness in one physics tick so no overlap is tested (discrete collision)"
+      - "Recommends enabling Continuous Collision Detection via Rigidbody.collisionDetectionMode = Continuous (or ContinuousDynamic/ContinuousSpeculative) on the fast body"
+      - "Offers the raycast/shapecast-then-move alternative for very small, very fast projectiles as more reliable than CCD"
+      - "Places physics movement in FixedUpdate, not Update"
+      - "Uses linearVelocity (not the deprecated Rigidbody.velocity) if it sets velocity directly, per Unity 6"
+  - scenario: "User asks for a Godot 4 CharacterBody3D controller with gravity, jump, and slope handling."
+    must_include:
+      - "Uses CharacterBody3D with a velocity property and calls move_and_slide() with NO arguments (Godot 4), not the Godot 3 move_and_slide(velocity, ...) signature"
+      - "Runs the movement in _physics_process(delta), the fixed-tick callback"
+      - "Adds gravity as velocity += gravity * delta but does NOT multiply the whole velocity by delta before move_and_slide()"
+      - "Uses is_on_floor() for grounded/jump checks and mentions floor_max_angle and/or floor_snap_length for slopes/steps"
+  - scenario: "User cannot get a pickup trigger and a colliding wall filtered correctly and asks about layers/masks."
+    must_include:
+      - "States layer = what the object is, mask = what it scans for, as independent bit sets"
+      - "Gives the correct per-engine mechanism: Godot collision_layer/collision_mask (mask must include the other's layer), Unity Layer Collision Matrix + LayerMask, or Unreal object channels + Block/Overlap/Ignore responses"
+      - "Uses a trigger/Area (Godot Area, Unity IsTrigger, Unreal Overlap response) for the detect-but-don't-block pickup, and notes a Unity trigger needs a Rigidbody on one object"

package/skills/shared/gamedev-physics/references/character-controllers.md

@@ -0,0 +1,120 @@
+# Character controllers — kinematic vs dynamic, per engine
+
+A "character controller" is the code that turns intent (move left, jump) into collision-resolved
+motion. Two approaches; pick one and commit.
+
+## Kinematic vs dynamic — the trade
+
+| | Kinematic character | Dynamic (rigidbody) character |
+| --- | --- | --- |
+| Motion | you set velocity, a sweep resolves it | forces/impulses, solver resolves it |
+| Feel | precise, snappy, fully authored | physical, momentum-y, harder to make crisp |
+| Pushed by physics | no (you handle it) | yes, for free |
+| Pushes dynamics | yes | yes |
+| Gravity | you add it manually | automatic |
+| Typical use | platformers, shooters, most players | ragdoll-ish, vehicles, physics puzzles |
+| Pain points | you re-implement gravity/slopes/steps | tipping, sliding, jitter — needs constraints + friction |
+
+Default to **kinematic** for a controllable character. Reach for dynamic only when physical
+interaction *is* the gameplay.
+
+## Godot 4 — CharacterBody (kinematic)
+
+`CharacterBody2D/3D` exposes a `velocity` property and `move_and_slide()`, which sweeps by
+`velocity` (already delta-scaled) and slides along surfaces.
+
+```gdscript
+extends CharacterBody3D
+
+const SPEED := 5.0
+const JUMP_VELOCITY := 4.5
+
+func _physics_process(delta: float) -> void:
+    if not is_on_floor():
+        velocity += get_gravity() * delta          # get_gravity() is 4.3+; else read ProjectSettings
+    if Input.is_action_just_pressed("jump") and is_on_floor():
+        velocity.y = JUMP_VELOCITY
+    var input := Input.get_vector("left", "right", "up", "down")
+    var dir := (transform.basis * Vector3(input.x, 0, input.y)).normalized()
+    velocity.x = dir.x * SPEED
+    velocity.z = dir.z * SPEED
+    move_and_slide()
+```
+
+Tuning knobs on the node:
+- `up_direction` — defines "up" for floor/wall/ceiling classification (default `Vector3.UP`).
+- `floor_max_angle` — steepest slope treated as floor (radians; default 45°). Steeper = wall.
+- `floor_snap_length` — pulls the body to the ground while descending ramps/stairs (kills
+  launch-off-ramp and airborne-on-stairs). Requires `floor_stop_on_slope` behavior tuning.
+- `is_on_floor()` / `is_on_wall()` / `is_on_ceiling()`, `get_floor_normal()`,
+  `get_slide_collision_count()` + `get_slide_collision(i)` to inspect what was hit.
+- `move_and_collide(motion)` — lower-level single sweep returning a `KinematicCollision`; use when
+  you want full manual control (custom slide, wall-jump math).
+
+For one-off exact motion (dashes, kinematic bodies not needing slide) use `move_and_collide`.
+
+## Unity 6 — CharacterController (kinematic) and the dynamic alternative
+
+`CharacterController` is a built-in kinematic capsule with sweeping `Move`. It handles steps and
+slopes via `stepOffset` and `slopeLimit`; it does **not** apply gravity — you do.
+
+```csharp
+[RequireComponent(typeof(CharacterController))]
+public class Player : MonoBehaviour {
+    public float speed = 6f, jumpVelocity = 5f, gravity = -20f;
+    CharacterController cc;
+    Vector3 vel;               // world-space velocity we integrate ourselves
+
+    void Awake() => cc = GetComponent<CharacterController>();
+
+    void Update() {            // CharacterController is kinematic: Update is fine
+        if (cc.isGrounded && vel.y < 0f) vel.y = -2f;               // keep grounded
+        Vector3 wish = transform.right * Input.GetAxis("Horizontal")
+                     + transform.forward * Input.GetAxis("Vertical");
+        if (cc.isGrounded && Input.GetButtonDown("Jump")) vel.y = jumpVelocity;
+        vel.y += gravity * Time.deltaTime;                          // integrate gravity
+        cc.Move((wish * speed + Vector3.up * vel.y) * Time.deltaTime);
+    }
+}
+```
+
+Key fields: `isGrounded`, `slopeLimit` (max walkable slope), `stepOffset` (max step height),
+`skinWidth` (small penetration tolerance — keep ~10% of radius; too small causes jitter),
+`center`/`radius`/`height`. `Move` returns `CollisionFlags`; hook `OnControllerColliderHit` to push
+dynamic rigidbodies.
+
+**Dynamic rigidbody character** instead: `Rigidbody` with `freezeRotation = true` (or constrain
+X/Z rotation), a high-friction physics material, movement via `AddForce`/target-velocity in
+`FixedUpdate`, and a grounded raycast. More physical, more tuning.
+
+## Unreal (UE5) — Character + CharacterMovementComponent
+
+`ACharacter` bundles a capsule + `UCharacterMovementComponent` (CMC), a sophisticated kinematic
+controller. It sweeps, handles Walking / Falling / Swimming / Flying **movement modes**, and applies
+its own gravity scale.
+
+- **Input → movement:** `AddMovementInput(WorldDirection, ScaleValue)`; jump via `Jump()` /
+  `StopJumping()` (`ACharacter` overrides).
+- **Slopes/steps:** CMC `MaxStepHeight`, `SetWalkableFloorAngle` / `GetWalkableFloorAngle`,
+  `MaxWalkSpeed`, `GravityScale`, `JumpZVelocity`, `AirControl`.
+- **Ground state:** `Movement->IsMovingOnGround()`, `IsFalling()`; `CurrentFloor` holds the hit.
+- Moving platforms are handled by CMC's base-relative movement when the character stands on a
+  movable primitive set as its movement base.
+
+For non-Character pawns you can drive a movable component manually or add a `PawnMovementComponent`.
+
+## Ground detection, slopes, steps, moving platforms — the recurring problems
+
+- **Ground detection** must be robust: a single downward ray can miss on ledges. Use the built-in
+  `is_on_floor()` / `isGrounded` / `IsMovingOnGround()` where possible; if rolling your own, use a
+  short **shapecast** (capsule/sphere) slightly wider than the character, not a thin ray.
+- **Slopes:** set the max-walkable-angle knob so steep slopes read as walls; add slide-down on
+  too-steep surfaces if desired. Project intended velocity onto the floor plane to avoid bumpy speed
+  on ramps.
+- **Steps/stairs:** rely on `stepOffset` / `MaxStepHeight` / `floor_snap_length`. A capsule collider
+  climbs small steps far more smoothly than a box.
+- **Moving platforms:** the platform must be a **kinematic mover** that reports motion (Godot
+  `AnimatableBody` with `sync_to_physics = true`; Unity kinematic `Rigidbody.MovePosition` in
+  `FixedUpdate`; Unreal movable primitive as movement base). A **static** body will not carry a
+  character. For a kinematic character on a moving platform, add the platform's per-tick delta to the
+  character before moving, or parent to the platform's motion.