@jgengine/core 0.18.1 → 0.19.0

package/skills/jgengine-world/capabilities.md

@@ -4,7 +4,11 @@
 
 Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
 
-## ai-decision-graph — Evaluate serializable selector, sequence, condition, action, and utility AI decisions.
+## action-contexts — Swap bindings live for on-foot, driving, menu or build modes by pushing and popping layered action maps.
+
+- `createActionContextStack` (function) · `import { createActionContextStack } from "@jgengine/core/input/actionContexts"`
+
+## ai-decision-graph — Evaluate serializable selector, sequence, condition, action, utility, timer, and random AI decisions with interrupt hooks.
 
 - `createDecisionGraphRuntime` (function) · `import { createDecisionGraphRuntime } from "@jgengine/core/ai/decisionGraph"`
 
@@ -20,13 +24,22 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createDriverState` (function) · `import { createDriverState } from "@jgengine/core/ai/driver"`
 
+## air-metrics — measure a vehicle's jumps and air control — apex height and time, double jump, air rotation rates
+
+- `measureAir` (function) · `import { measureAir } from "@jgengine/core/physics/handlingProbe"`
+
 ## anim-graph — data-first animation state machine with blend trees, crossfades, layers, and clip events
 
 - `createAnimGraphRuntime` (function) · `import { createAnimGraphRuntime } from "@jgengine/core/anim/animGraph"`
+- `parseAnimGraph` (function) · `import { parseAnimGraph } from "@jgengine/core/anim/animGraph"`
 
-## animation — inverse kinematics orient a bone toward a target with constrained yaw and pitch
+## animation — find thigh, shin and foot bones on a humanoid rig for foot IK
 
+- `inferLegChains` (function) · `import { inferLegChains } from "@jgengine/core/anim/footPlacement"`
 - `lookAt` (function) · `import { lookAt } from "@jgengine/core/anim/ikSolver"`
+- `placeFeet` (function) · `import { placeFeet } from "@jgengine/core/anim/footPlacement"`
+- `planBoneTexture` (function) · `import { planBoneTexture } from "@jgengine/core/anim/boneTexture"`
+- `sampleBoneTexture` (function) · `import { sampleBoneTexture } from "@jgengine/core/anim/boneTexture"`
 - `solveFabrik` (function) · `import { solveFabrik } from "@jgengine/core/anim/ikSolver"`
 - `solveTwoBone` (function) · `import { solveTwoBone } from "@jgengine/core/anim/ikSolver"`
 
@@ -101,6 +114,11 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `placeAuthoredObjects` (function) · `import { placeAuthoredObjects } from "@jgengine/core/world"`
 - `resolveAuthoredObjects` (function) · `import { resolveAuthoredObjects } from "@jgengine/core/world"`
 
+## authored-solids — collision for studio-authored world content such as city volumes
+
+- `resolveAuthoredSolids` (function) · `import { resolveAuthoredSolids } from "@jgengine/core/world/authoredSolids"`
+- `syncAuthoredSolids` (function) · `import { syncAuthoredSolids } from "@jgengine/core/world/authoredSolids"`
+
 ## authored-spawn — read spawn points and markers from the editor document
 
 - `authoredSpawnPosition` (function) · `import { authoredSpawnPosition } from "@jgengine/core/world/authoredSpawn"`
@@ -116,6 +134,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `registerBuiltinTriggerActions` (function) · `import { registerBuiltinTriggerActions } from "@jgengine/core/scene/authoredTriggers"`
 - `registerTriggerAction` (function) · `import { registerTriggerAction } from "@jgengine/core/world"`
 
+## axis-shaping — shape raw input per axis — deadzone, response curve, keyboard ramp, self-centring, speed-sensitive scaling
+
+- `createAxisShaper` (function) · `import { createAxisShaper } from "@jgengine/core/input/axisShaper"`
+
 ## behavior-actions — register named callbacks for decision graph behavior descriptors
 
 - `registerBehaviorActions` (function) · `import { registerBehaviorActions } from "@jgengine/core/world"`
@@ -128,6 +150,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `advanceBehaviors` (function) · `import { advanceBehaviors } from "@jgengine/core/world"`
 
+## boat-dynamics — force-based powered hull — hull-speed drag hump, planing, keel, rudder that needs flow or outboard thrust
+
+- `createBoatDynamics` (function) · `import { createBoatDynamics } from "@jgengine/core/physics/boatDynamics"`
+
 ## body-bind — mirror sim-body snapshots onto scene entities each tick, no per-body setPose
 
 - `createBodyBind` (function) · `import { createBodyBind } from "@jgengine/core/world"`
@@ -167,6 +193,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 ## city-district — polygon math for road-derived blocks, parcels, and buildable footprints
 
 - `Vec2` (type) · `import { Vec2 } from "@jgengine/core/world/cityGeometry"`
+- `citySolids` (function) · `import { citySolids } from "@jgengine/core/world/cityKind"`
 - `extractGraphBlocks` (function) · `import { extractGraphBlocks } from "@jgengine/core/world/cityBlocks"`
 - `rectClearsPolyline` (function) · `import { rectClearsPolyline } from "@jgengine/core/world/cityGeometry"`
 - `rectsSeparated` (function) · `import { rectsSeparated } from "@jgengine/core/world/cityGeometry"`
@@ -193,6 +220,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createTimerSet` (function) · `import { createTimerSet } from "@jgengine/core/world"`
 
+## course-metrics — measure a vehicle on driven tests — understeer gradient, skidpad g, slalom speed
+
+- `measureCourse` (function) · `import { measureCourse } from "@jgengine/core/physics/handlingProbe"`
+
 ## crouch-prone — stance/pose transitions that change the hitbox
 
 - `createPoseState` (function) · `import { createPoseState } from "@jgengine/core/world"`
@@ -241,6 +272,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `DIFFICULTY_TIERS` (const) · `import { DIFFICULTY_TIERS } from "@jgengine/core/ai/difficulty"`
 
+## doppler-pitch — pitch a moving sound up as it approaches and down as it passes, from listener and emitter velocity
+
+- `dopplerRate` (function) · `import { dopplerRate } from "@jgengine/core/audio/doppler"`
+
+## drivable-vehicle — drive a car from throttle/steer/handbrake input each tick: step the vehicle sim and pose its entity
+
+- `tickDrivableVehicle` (function) · `import { tickDrivableVehicle } from "@jgengine/core/world"`
+
 ## elevation-readout — cursor height and delta-from-reference feedback
 
 - `sampleElevation` (function) · `import { sampleElevation } from "@jgengine/core/world"`
@@ -249,6 +288,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `summarizeElevation` (function) · `import { summarizeElevation } from "@jgengine/core/world"`
 
+## engine-layers — layered engine audio: rpm-keyed samples crossfaded, with on-load and off-load sets picked by engine load
+
+- `createEngineLayers` (function) · `import { createEngineLayers } from "@jgengine/core/audio/engineLayers"`
+
 ## entity-meta — cast-free narrow of SceneEntity.meta via a type guard
 
 - `entityMetaOf` (function) · `import { entityMetaOf } from "@jgengine/core/world"`
@@ -257,9 +300,17 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createFastTravelNetwork` (function) · `import { createFastTravelNetwork } from "@jgengine/core/world"`
 
-## flight-dynamics — simulate fixed-wing, helicopter, and VTOL aircraft
+## feedback-mixer — map sim telemetry to camera, audio and haptic parameters through curves, smoothing and threshold events
+
+- `createFeedbackMixer` (function) · `import { createFeedbackMixer } from "@jgengine/core/vfx/feedbackMixer"`
+
+## fire-input — bind a key or mouse button to a named action that runs the same-named command with the aim; repeatMs auto-fires while held
+
+- `ActionCodesMap` (type) · `import { ActionCodesMap } from "@jgengine/core/input/actionBindings"`
 
-- `createAircraftDynamics` (function) · `import { createAircraftDynamics } from "@jgengine/core/world"`
+## flight-metrics — measure an aircraft's feel as numbers — roll rate, sustained turn, stall speed, climb, throttle response, hover drift
+
+- `measureFlight` (function) · `import { measureFlight } from "@jgengine/core/physics/handlingProbe"`
 
 ## follow-trail — trailing follower/snake formation that chases a leader
 
@@ -327,10 +378,22 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `grounded` (function) · `import { grounded } from "@jgengine/core/world"`
 
+## handling-metrics — measure a vehicle's feel as numbers — 0–100, braking, lateral g, turn-in, sideslip, spin
+
+- `measureHandling` (function) · `import { measureHandling } from "@jgengine/core/physics/handlingProbe"`
+
+## haptics — Continuous gamepad rumble from named channels (engine, road, impact) mixed by priority, plus fading pulses.
+
+- `createHapticChannels` (function) · `import { createHapticChannels } from "@jgengine/core/input/haptics"`
+
 ## hold-order — stand-ground order that holds position until preempted or canceled
 
 - `defineHoldOrder` (function) · `import { defineHoldOrder } from "@jgengine/core/world"`
 
+## input-buffer — buffer early presses, coyote time, hold duration and double tap for responsive controls
+
+- `createInputBuffer` (function) · `import { createInputBuffer } from "@jgengine/core/input/inputBuffer"`
+
 ## interaction-prompt — observable nearest-interactable prompt registry over the proximity-prompt resolver — register/resolve/active with priority+range and change-notified snapshot/restore
 
 - `createPromptRegistry` (function) · `import { createPromptRegistry } from "@jgengine/core/world"`
@@ -355,6 +418,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createRebindSession` (function) · `import { createRebindSession } from "@jgengine/core/input/rebindSession"`
 
+## kinematic-vehicle — arcade car/kart driving physics with throttle, brake, steer and retunable handling
+
+- `createKinematicVehicle` (function) · `import { createKinematicVehicle } from "@jgengine/core/world"`
+
+## lean-metrics — measure a motorcycle's lean — steady lean, time to lean, countersteer tip-in
+
+- `measureLean` (function) · `import { measureLean } from "@jgengine/core/physics/handlingProbe"`
+
 ## limb-health — per-body-part/region health tracked separately
 
 - `createMultiRegionHealth` (function) · `import { createMultiRegionHealth } from "@jgengine/core/procedural"`
@@ -367,8 +438,9 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `generateLock` (function) · `import { generateLock } from "@jgengine/core/world"`
 
-## locomotion-graph — build the default idle/walk/run plus one-shot graph from clip names
+## locomotion-graph — resolve the animation graph a model config plays
 
+- `animGraphFromConfig` (function) · `import { animGraphFromConfig } from "@jgengine/core/anim/locomotionGraph"`
 - `locomotionGraph` (function) · `import { locomotionGraph } from "@jgengine/core/anim/locomotionGraph"`
 
 ## map-annotations — player-drawn map annotation layer — freehand strokes, area shapes, and pinned notes, projected into the map's routes/zones props and serializable
@@ -400,6 +472,22 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `defineMoveOrder` (function) · `import { defineMoveOrder } from "@jgengine/core/world"`
 
+## movement-metrics — measure a walking character's feel as numbers — time to top speed, stop distance, jump height and apex, air control, turn-around
+
+- `measureMovement` (function) · `import { measureMovement } from "@jgengine/core/movement/movementProbe"`
+
+## nav-from-solids — block world solids on a nav grid
+
+- `populateNavGridFromSolids` (function) · `import { populateNavGridFromSolids } from "@jgengine/core/nav/navFromEnvironment"`
+
+## navmesh-bake — voxelize scene triangles into an agent-sized polygon nav mesh
+
+- `bakeNavMesh` (function) · `import { bakeNavMesh } from "@jgengine/navbake"`
+
+## navmesh-query — route, snap, and raycast on a polygon navmesh with retunable area costs and a bounded search
+
+- `createNavMeshQuery` (function) · `import { createNavMeshQuery } from "@jgengine/core/world"`
+
 ## object-slot-inventory — placed objects hold validated per-instance container contents that replicate and save with the placement
 
 - `SceneObjectSlots` (interface) · `import { SceneObjectSlots } from "@jgengine/core/world"`
@@ -497,7 +585,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `resolveActivePrompt` (function) · `import { resolveActivePrompt } from "@jgengine/core/world"`
 
-## pursuit — chase-to-reach cooldown-gated attack with optional leash-to-home; owns the attack cooldown
+## pursuit — enemy/mob aggro chase-to-reach with a cooldown-gated attack and optional leash-to-home; owns the attack cooldown
 
 - `advancePursuit` (function) · `import { advancePursuit } from "@jgengine/core/ai/pursuit"`
 
@@ -521,6 +609,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createResourceNodeField` (function) · `import { createResourceNodeField } from "@jgengine/core/world/resourceNode"`
 
+## ride-metrics — measure a sprung vehicle's ride — settle time, dive, roll per g, landing bounce
+
+- `measureRide` (function) · `import { measureRide } from "@jgengine/core/physics/handlingProbe"`
+
+## rigid-aircraft — force-and-torque aircraft — lifting surfaces with stall and drag polar, control surfaces, inertia, loops and rolls
+
+- `createRigidAircraft` (function) · `import { createRigidAircraft } from "@jgengine/core/physics/aircraftDynamics"`
+
 ## rts-control-groups — map Ctrl+digit / digit / double-tap presses onto selection-bookmark bind / recall / focus intents
 
 - `controlGroupKey` (function) · `import { controlGroupKey } from "@jgengine/core/world"`
@@ -560,6 +656,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 ## solid-obstacles — the one blocking-geometry query the player resolver and NPC movers share
 
+- `obstacleFromSolid` (function) · `import { obstacleFromSolid } from "@jgengine/core/movement/solidObstacles"`
 - `solidObstaclesNear` (function) · `import { solidObstaclesNear } from "@jgengine/core/movement/solidObstacles"`
 
 ## spatial-region-box — sample uniformly within an axis-aligned 3D box
@@ -683,6 +780,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `setTouchControlsMode` (function) · `import { setTouchControlsMode } from "@jgengine/core/input/touchControlsMode"`
 - `touchButtonShape` (function) · `import { touchButtonShape } from "@jgengine/core/input/touchScheme"`
 
+## vehicle-backend-link — collide a vehicle sim with a physics backend — shove props, stop at walls, slide along them
+
+- `createVehicleBackendLink` (function) · `import { createVehicleBackendLink } from "@jgengine/core/physics/vehicleBackendLink"`
+
+## vehicle-dynamics — force-based car handling — tires, load transfer, drivetrain, assists — tuned with physical numbers
+
+- `createVehicleDynamics` (function) · `import { createVehicleDynamics } from "@jgengine/core/physics/vehicleDynamics"`
+
+## vehicle-seats — enter, exit and swap seats in a car or mount (GTA-style boarding) with driver and passenger slots
+
+- `createVehicleSeats` (function) · `import { createVehicleSeats } from "@jgengine/core/world"`
+
 ## visibility-field — per-viewer-group observed/remembered/hidden fog-of-war knowledge with terrain memory and authoritative entity disclosure
 
 - `createVisibilityField` (function) · `import { createVisibilityField } from "@jgengine/core/world"`
@@ -729,3 +838,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 ## world-seed — derive a deterministic generator/scatter seed from world id + save/run seed
 
 - `seedForPlace` (function) · `import { seedForPlace } from "@jgengine/core/world"`
+
+## world-solid-bounds — world AABB and nav footprint of a world solid
+
+- `worldSolidBounds` (function) · `import { worldSolidBounds } from "@jgengine/core/world/worldSolids"`
+- `worldSolidFootprint` (function) · `import { worldSolidFootprint } from "@jgengine/core/world/worldSolids"`
+
+## world-solids — collision for generated and authored world geometry (buildings, city lots, walls)
+
+- `createWorldSolids` (function) · `import { createWorldSolids } from "@jgengine/core/world/worldSolids"`
+
+## world-solids-from-data — derive collision boxes from generated buildings and wall runs
+
+- `buildingSolids` (function) · `import { buildingSolids } from "@jgengine/core/world/worldSolids"`
+- `structureSolids` (function) · `import { structureSolids } from "@jgengine/core/world/worldSolids"`
+- `wallSolids` (function) · `import { wallSolids } from "@jgengine/core/world/worldSolids"`

package/skills/jgengine-world/recipes/character-animation.md

@@ -0,0 +1,39 @@
+# Recipe — character animation (graph → rig → ground)
+
+**What this wires:** a rigged character that moves the way the game plays: clips chosen by data, feet that meet the ground, and gameplay moments keyed to animation frames. There is no default hero, soldier or NPC rig: every game picks its clips, parameters and corrections.
+
+## The seams
+
+- **Clips on a model.** `ModelConfig.animation` on an entity kind. A catalog model with indexed `clips` animates automatically through semantic clip roles; `"none"` holds the bind pose. `{ clip, paused, time }` holds one pose.
+- **Graph.** `animation.graph` is an `AnimGraph` (`@jgengine/core/anim/animGraph`): layers, each a state machine of `clip`, `blend1D` and `blend2D` states joined by transitions with `when` conditions, `trigger`s, crossfade `duration` and `exitTime`. It is plain data, so it saves, diffs and can be authored in the editor.
+  - `locomotionGraph({ idle, walk, run, walkSpeed, runSpeed, fadeSec, oneShots })` builds the idle/walk/run blend plus one-shots; `states`/`oneShots` configs are converted through it.
+  - Upper-body actions (aim, reload, wave) go on a second layer with `mask: ["spine", "arm", ...]` bone prefixes, `additive` for recoil or breathing on top of the base.
+  - `createAnimGraphRuntime(graph)` runs the same graph headless: `advance(dt, params, clips)`, `trigger`, `snapshot`/`restore`, `retune`. Test transitions with it before looking at pixels.
+- **Authoring in the editor.** A placement's graph is inspected, previewed and stored from the editor's Animation workspace (see `jgengine-editor` reference, "Placement animation"). `animGraphFromConfig(config)` gives the graph any config plays, so tools and tests see what the shell plays. `parseAnimGraph(json)` validates a stored one.
+- **Parameters.** The shell feeds the entity's smoothed ground speed as `speed`. Anything else (aiming, crouched, strafe x/y) goes on the entity blackboard under `ANIM_PARAMS_KEY`.
+- **Triggers.** `ctx.game.playEntityAnimation(id, name)` arms a trigger; `hit` and `death` arm from their combat events.
+- **Events.** `graph.events: [{ clip, atSec, name }]` emit `animation.event` when a clip crosses that time. Hook footstep audio, the damage frame of a swing or the magazine swap of a reload to the event, not to a timer.
+- **Root motion.** `rootMotion: true` on a state moves the entity by the clip's horizontal root-bone travel, turned by the entity's facing and scaled with the model, instead of playing it in place. The root bone's vertical motion stays in the clip, and other states keep their root animation untouched. Use it for dodges, vaults and attacks with lunges whose distance must match the feet. `output.rootMotion` reports when a root-motion state is current.
+- **Foot IK.** `ModelConfig.ik` runs after the mixer each frame.
+  - `ik: "auto"` finds thigh → shin → foot chains by bone name. Pass `{ feet: [{ root, mid, tip }] }` when the rig's names are unusual, and `feet: []` to keep only `lookAt`.
+  - Each foot keeps its animated swing and moves by its ground's height above or below the model origin. The pelvis drops so the lower leg can reach, soles never end under the ground, and planted feet tilt to the ground normal (`alignToGround`, `0..1`). The correction fades out while the feet are clear of the ground.
+  - `maxAdjust` caps the correction as a fraction of leg length (default `0.4`). Probes hit terrain and blocking physical objects, never the model's own entity.
+  - The pure pieces are `placeFeet` and `inferLegChains` (`@jgengine/core/anim/footPlacement`) and `solveTwoBone`/`solveFabrik`/`lookAt` (`@jgengine/core/anim/ikSolver`), for a custom host or a non-leg chain (a hand on a ledge, a tail).
+- **Crowds.** `<SkinnedInstances url instances clips once fps modelScale />` (`@jgengine/shell/render/SkinnedInstances`) draws hundreds of animated copies of one rig in one instanced draw per material. Each `CrowdInstance` has `position`, `rotationY`, `scale`, `clip`, `timeOffset` and `speed`.
+  - Every clip is baked once to a bone-matrix texture (layout from `planBoneTexture`, `@jgengine/core/anim/boneTexture`) and sampled on the GPU. Clips in `once` hold their last pose. A member changes clip when the game passes a new `instances` array.
+  - Only skinned meshes are baked. Static props parented to bones (a weapon in a hand slot, a hat) are dropped, and a mesh with several materials keeps its first.
+  - Crowd members have no graph, IK or attachments. Promote the few near the camera or near the player to entity models.
+  - `bakeSkinnedCrowd` and `patchCrowdMaterial` are exported for a custom renderer.
+
+## Symptom → knob
+
+| Symptom | Knob |
+| --- | --- |
+| Feet slide at walk or run speed | `walkSpeed`/`runSpeed` to the clip's authored stride speed, or blend1D `at` points |
+| Pop between states | transition `duration`; `exitTime` on one-shots returning to locomotion |
+| Feet float or sink on slopes and steps | `ik: "auto"` |
+| Knees buckle on steep ground | lower `ik.maxAdjust` |
+| Feet tilt wrongly on rubble or props | lower `ik.alignToGround` |
+| Attack damage lands before the swing | `graph.events` on the hit frame instead of a timer |
+| Lunge distance doesn't match the feet | `rootMotion: true` on that state |
+| Hundreds of animated characters cost thousands of draw calls | `SkinnedInstances` for the background crowd |

package/skills/jgengine-world/recipes/controls.md

@@ -0,0 +1,44 @@
+# Recipe — controls (bindings → contexts → devices → feel)
+
+**What this wires:** a game's controls from small parts: named actions, layered contexts that swap bindings live, keyboard/mouse and gamepad on the same actions, and per-axis feel. There are no control presets; every game names its own actions and codes.
+
+## The seams
+
+- **Actions.** `defineGame({ input: { action: codes } })` maps action names to codes. Keyboard codes are `KeyboardEvent.code` (`KeyW`), pad buttons are `pad:<index>` and stick or trigger directions are `padaxis:<index>+`/`-` in the standard mapping. `bindingLabel(code, "xbox")` gives the glyph text for prompts. Sim code reads actions only: `ctx.input.isDown`, `justPressed`, `value` (0..1, analog when a stick or trigger drives it) and `axis(bindings)`.
+- **Contexts.** `actionContextStack(ctx)` (`@jgengine/core/game/controlGate`) layers action maps over the base input. `push({ id, codes, passthrough, axes?, shaping? })` swaps bindings immediately: the shell re-binds keyboard, touch and pad on the next frame, and a key held across the swap keeps counting toward whatever it maps to now. `passthrough: false` hides everything below (menus, a parked vehicle); `passthrough: true` adds or overrides a few actions (a build mode on top of on-foot). The stack has `snapshot`/`restore`, so the current mode survives a save.
+- **Axes and feel per context.** A context can carry `axes` (axis bindings by action name) and `shaping` (serializable `createAxisShaper` profiles). Read them with `activeAxes()` when `version()` changes and `retune` the shaper, so on-foot movement and driving steer each get their own ramp and curve without a branch per mode.
+- **Pad feel.** `defineGame({ gamepad: { deadzone, curve, triggerDeadzone } })` shapes sticks and triggers before values reach `ctx.input`; the axis shaper only adds ramps and speed scaling on top.
+- **Timing.** `createInputBuffer` (`@jgengine/core/input/inputBuffer`) buffers early presses, coyote time, hold duration and double taps.
+- **Local seats (couch co-op).** `defineGame({ localPlayers: { maxSlots: 4 } })` opens seats on one screen. The first pad to press a button shares the primary seat with keyboard and touch (`claimPrimary: "none"` keeps the primary keyboard-only); each further pad hot-joins its own seat, and the shell calls `loop.onNewPlayer(ctx, { userId, isNew: true })` for it, so spawn with `player?.userId ?? ctx.player.userId`. Read a seat with `localPlayers(ctx).local(slotId)` → `{ userId, input }` (`@jgengine/core/runtime/localPlayers`); iterate `slots()` in `onTick`. Seats use the same bindings and contexts as the primary, and the shell's walk controller moves every seat's entity. The table has `snapshot`/`restore`/`retune`.
+- **Split-screen.** `defineGame({ viewports: { layout: "auto", split: "vertical" } })` draws one viewport per joined seat (`@jgengine/core/game/viewports`: `splitViewports`, `resolveViewports`, `viewportPixels`). The primary seat keeps the main camera rig; other seats get a chase or top-down follow camera (`viewports.camera`, defaulting to top-down when the main rig is), and the walk controller moves each seat relative to its own camera. `ViewportHuds` (`@jgengine/shell/camera/Viewports`) gives each seat its own HUD root. Post-processing is skipped while the screen is split. `bun run drive couch --param gamepad=2` shows two seats.
+- **Haptics.** `ctx.input.haptics(userId)` holds named rumble channels: `set(name, { strong, weak }, priority?)` each tick for continuous feel, `pulse(name, { strong, weak, ms }, priority?)` for a fading hit. Higher priority ducks lower channels. The shell drives each seat's own pad; channels are local and never saved or sent.
+- **Rebinding.** `createRebindSession` drives a conflict-aware "press a key" flow; overrides persist per game and apply under the context stack.
+
+## Wiring a mode swap
+
+```ts
+const DRIVING: ActionContext = {
+  id: "driving",
+  codes: { exit: ["KeyF", "pad:3"] },
+  passthrough: true,
+  axes: { steer: { positive: ["steerRight"], negative: ["steerLeft"] } },
+  shaping: { steer: { digital: { riseRate: 3, returnRate: 6 }, analog: { deadzone: 0.08, curve: 1.5 } } },
+};
+
+// enter: actionContextStack(ctx).push(DRIVING); leave: actionContextStack(ctx).pop("driving")
+if (state.contextVersion !== contexts.version()) {
+  state.contextVersion = contexts.version();
+  const layer = contexts.activeAxes();
+  state.bindings = { steer: layer.bindings.steer ?? { positive: [] } };
+  state.shaper.retune({ axes: { steer: layer.shaping.steer ?? {} } });
+}
+const raw = ctx.input.axis(state.bindings);
+const axis = state.shaper.shape(dt, raw, { analog: analogAxes(state.bindings, ctx.input.analog()) });
+```
+
+`bun run drive handling` runs this: F pops the driving context and a held W stops reaching the engine.
+
+## Pitfalls
+
+- Actions that exist only inside a context are published to `ctx.input` while the context is active, but the base `input` map is what the touch dock and settings menu list. Keep an action in the base map when touch players need it.
+- `shaping` has no `scale` callback because contexts are serializable; apply speed-sensitive scaling on the shaper the game owns.

package/skills/jgengine-world/recipes/flight-feel.md

@@ -0,0 +1,76 @@
+# Recipe — flight feel (aircraft as physical numbers)
+
+**What this wires:** an aircraft that flies the way the brief says. There is no default jet or plane: every aircraft is a mass, an inertia tensor, a set of surfaces and an engine the game picks, checked against numbers it writes down first.
+
+## The seams
+
+- **Sim.** `createRigidAircraft(tuning, { position, velocity, heading | orientation, wind?, groundHeight?, gravityField?, airDensity? })` from `@jgengine/core/physics/aircraftDynamics`. It is a quaternion rigid body: surface forces act at their mount points on the inertia tensor, so nothing commands a rotation rate. `snapshot()`/`restore()` for prediction and replay, `retune()` for damage, upgrades and staging, per-tick `modifiers` (`thrustScale`, `liftScale`, `dragScale`, extra `force`/`torque`).
+- **Body frame.** `[left, up, forward]` about the centre of mass. A wing panel sits at `[±semiSpan/2, 0, 0]`, a tailplane at `[0, 0, -tailArm]`, a fin at `[0, finHeight, -tailArm]` with `normal: [1, 0, 0]`.
+- **Surfaces.** Each one has `area` (m²), `liftSlope` (per rad), `stallAngle` (rad), `postStallLift` (share of peak kept past the stall), `incidence` (trim), and the drag polar `cd0` + `inducedDrag·CL²`. Split the wing into left and right panels so ailerons have a roll arm.
+- **Controls.** `control: { pitch?, roll?, yaw? }` on a surface is AoA change per rad of that channel's deflection. The sim signs it from the lever arm, so positive input is always nose up, right roll, nose right. Elevons are one surface with both `pitch` and `roll`. `controls.<channel>` sets `maxDeflection` and actuator `rate`.
+- **Rotors.** A `rotor` block makes the same body a helicopter: `maxThrust` (N, full collective and rotor speed), `radius` (m), hub `at`, `torque` (N·m at full collective, positive yaws the nose left), `cyclic` disc tilt, `damping`, `spoolRate` and an optional `tail` rotor (`maxThrust`, `at`, `sideDamping`).
+  - Throttle spins the rotor up; `input.collective` sets thrust; the pitch and roll channels tilt the disc; yaw drives the tail rotor.
+  - Neutral pedal gives no tail thrust, so the nose swings with the torque until the pilot (or SAS) holds it. Hover pedal is `torque·collective / (tail.maxThrust · tailArm)`.
+  - Thrust follows momentum theory: translational lift once clean air reaches the induced velocity `√(T/2ρA)`, less thrust while climbing through the disc, and Cheeseman–Bennett ground effect below about one rotor diameter.
+  - The step's `rotor` telemetry (`speed`, `thrust`, `torque`, `groundEffect`, `translationalLift`) drives rotor sound, dust and HUD.
+- **Rockets.** A `motor` block: `thrustCurve` (`[seconds, N]` points over burn time), `propellantKg` on top of `massKg`, `massFlow` (kg/s at peak thrust; it scales with thrust), nozzle `at` and `gimbal` (rad, on the pitch and yaw actuators).
+  - Throttle above zero burns and advances the burn clock; throttle `0` coasts with the clock held.
+  - Mass and inertia fall as propellant leaves (inertia scales with total over dry mass), so acceleration and turn rate rise through the burn.
+  - Stage by `retune(nextStage)`: a new `motor` object loads its propellant and restarts its clock; the same object keeps both. Move the pose to the new stage's centre of mass with `restore` first if the stages differ in length.
+  - The step reports `massKg` and `motor` (`thrust`, `burnTime`, `propellantKg`, `burnedOut`).
+- **Assists.** An `assists` block is a flight computer on the same actuators, so it never exceeds the airframe's authority, and full stick on an axis is always the pilot's.
+  - `sas: { pitch, roll, yaw }` (`0..1`) damps body rates and, hands-off, holds the attitude or heading at release with a learned trim. `sasRate` sets how firm (rad/s for full control). On a helicopter, `sas.yaw` holds heading against rotor torque with no pedal.
+  - `autoLevel` (`0..1`) flies the wings level and the nose to the horizon hands-off.
+  - `maxAngleOfAttack` (rad) and `maxG` cut the pitch command before the limit; `step.limited` reports it.
+  - `hoverHold` (`0..1`) flies hands-off cyclic to a stop over the ground: position → velocity → attitude → rate.
+  - `policy(context, command)` runs last and returns the command the actuators get: replace any built-in with the game's own.
+  - `step.command` is what the actuators got. Toggle assists with `retune({ ...aircraft.tuning(), assists })`.
+- **Pose.** Set the entity's `rotationY` from `step.heading` and apply the rest of `step.orientation` to the mesh (the heading-free part: `qY(-heading) · orientation`). `step.pitch`/`step.bank` match three.js `Euler(-pitch, heading, bank, "YXZ")`; `aircraftAttitudeQuaternion(heading, pitch, bank)` goes the other way for spawns.
+- **Camera.** The chase rig (`rig: "chase"`) follows heading; give it `frustum: { far }` in the thousands and a `yawResponse` around 4 so the boom swings smoothly over the top of a loop.
+- **Telemetry.** `airspeed`, `angleOfAttack`, `sideslip`, `gLoad`, `stalled`/`stallFraction`, `thrust`, body rates and `deflection` drive the HUD, stall horn, wind noise and camera shake.
+
+## Workflow
+
+1. **Write the feel as numbers** on the `FlightReport` fields. Some examples:
+   - "Nimble aerobatic" is `rollRateDeg > 300` and `sustainedTurnRateDeg > 18`.
+   - "Heavy transport" is `rollRateDeg` 40–80 and `stallSpeed` 50–70.
+   - "Responsive jet" is `throttleResponse < 2`.
+   - "Easy hover" is `hoverDriftMeters < 5` with the game's assists on.
+2. **Put them in a test** next to the tuning: `measureFlight((spawn) => createRigidAircraft(tuning, spawn), { cruiseSpeed })` from `@jgengine/core/physics/handlingProbe`. It flies deterministic autopilots through a full-aileron roll, full-throttle banked turns, an idle deceleration, a speed-held climb, a throttle step and a hands-off hover. Fields that don't apply are `NaN`: turn and stall need wings, hover drift needs a rotor.
+3. **Start from the real aircraft**: mass, wing area, span, tail arm, thrust. Inertia is roughly `m·(span/4)²` for roll and `m·(length/4)²` for pitch and yaw.
+4. **Trim it.** With the wing on the centre of mass, set wing `incidence` to the cruise lift coefficient over the lift slope, `W / (½ρV²·S·a)`, and leave the tail at `0`. It then flies level hands-off at that speed.
+5. **Drive it**: `bun run drive flight --key KeyR+KeyS:10500 --key KeyD:1500 --record <name> --record-fps 20`, or `bun run drive flight-heli --key KeyR:1500 --wait 3000 --key KeyE:3500 --record <name> --record-fps 20` for the helicopter, or `bun run drive flight-rocket --key KeyR:400 --wait 12000 --record <name> --record-fps 20` for the two-stage rocket.
+
+## Symptom → knob
+
+| Symptom | Knob (direction) |
+| --- | --- |
+| Pitches up or down hands-off | wing `incidence` ↓ / ↑; wing further aft of the centre of mass ↑ stability |
+| Loops too slowly | tail `control.pitch` ↑ (more AoA), entry speed or thrust ↑, `inertia.pitch` ↓ |
+| Stalls in every hard pull | tail `control.pitch` ↓ so the elevator can't reach the stall angle, or wing `stallAngle` ↑ |
+| Stall is a cliff / too gentle | `postStallLift` ↓ / ↑ |
+| Rolls too slowly / too fast | aileron `control.roll` ↑ / ↓, wing panel `at` further out ↑ damping; `inertia.roll` sets how fast it gets there |
+| Nose wanders, won't track | fin `area` ↑ or fin further aft |
+| Controls feel laggy | `controls.<channel>.rate` ↑ |
+| Top speed wrong | `engine.maxThrust`, `dragArea`, surface `cd0` |
+| Bleeds speed in turns | `inducedDrag` ↓, wing `area` ↑ (lower CL for the same lift) |
+| Throttle feels sluggish | `engine.spoolRate` ↑ |
+| Helicopter won't hover / climbs away | hover collective is `weight / maxThrust` out of ground effect; `rotor.maxThrust` sets how much margin there is |
+| Nose swings too hard without pedal | `rotor.torque` ↓, `inertia.yaw` ↑, `tail.sideDamping` ↑ |
+| Pedal too weak to stop a swing | `tail.maxThrust` ↑ or tail rotor further aft |
+| Cyclic twitchy / sluggish | `rotor.cyclic` ↓ / ↑, hub height (`rotor.at[1]`) ↓ / ↑, `rotor.damping` ↑ / ↓ |
+| Pedal also rolls the body | tail rotor `at[1]` above the centre of mass; move it down or trim with cyclic |
+| Rocket weathercocks too hard / tumbles | fin `area` ↓ / ↑, fins further aft for more stability |
+| Gimbal too twitchy / can't steer | `motor.gimbal` ↓ / ↑; lighter late in the burn it turns faster on its own |
+| Burns too long / short | `propellantKg` over `massFlow` sets burn time; the curve's last point cuts it off first |
+| Helicopter too hard to hover on a keyboard | `assists.sas.yaw` 1 for heading hold, `assists.hoverHold` for cyclic; collective stays the pilot's |
+| Assisted aircraft oscillates | `assists.sasRate` ↑ (softer), strengths ↓ |
+| Players stall it pulling hard | `assists.maxAngleOfAttack` just under the wing `stallAngle`, or `maxG` |
+| Sinks when it slows down | that is translational lift going away; `rotor.translationalLift` sets how much |
+
+## Traps
+
+- `createAircraftDynamics` (`physics/flightDynamics`) is deprecated: it commands rotation and can't loop. The CHANGELOG Migrate note maps its fields onto `createRigidAircraft`.
+- Setting orientation or angular velocity by hand defeats the model. Change a surface, the inertia or the control authority.
+- A single centreline wing has no roll arm, so ailerons on it do nothing. Split it into left and right panels.
+- For multiplayer, send inputs, not poses. Predict with the same tuning and `restore(serverState)` on correction.

package/skills/jgengine-world/recipes/npc-senses.md

@@ -0,0 +1,43 @@
+# Recipe — NPC senses (perceive → remember → decide → route)
+
+**What this wires:** an NPC that notices things, remembers where they were, acts on
+that memory, and gives up when it goes stale. A guard that hears a sprint and
+checks it out, a mob that leashes home, a pedestrian that flees a gunshot and a
+patrol car that drives to the last sighting are all this loop with different
+facts, graphs and speeds. No archetypes: the NPC is data plus a few named actions.
+
+Working example: the `guard-probe` dev demo (`apps/dev/src/demo/guardProbe.ts`),
+`bun run drive guard-probe`.
+
+## The seams
+
+- **Perceive → memory.** One `createPerception` per group of NPCs that share
+  senses. Each tick, push the stimuli your game produces (`sound` with a
+  `loudness` that scales range, `damage`) and call `observe(npc, candidates, nowMs)`
+  with a *bounded* candidate list from a spatial query, never every entity. Pass
+  `occluded` for walls. Memory decays linearly over `memorySeconds`; each observer
+  judges a stimulus once.
+- **Memory → blackboard.** A small system copies the facts the graph needs into
+  the NPC's persistent blackboard: `behaviorControl(ctx).blackboard(id)`. Write
+  plain scalars (`alerted`, `lastKnownX`, `lastKnownZ`, `confidence`). Actions
+  and conditions read facts; they do not query the world for them.
+- **Blackboard → decision.** The NPC's `decisionGraph` behavior is data:
+  conditions on blackboard keys, `memory` sequences for multi-step errands
+  (go → `wait` → give up), `cooldown` for barks, `random` (drawn from `ctx.rng`)
+  for idle variety. Register actions by name with `registerBehaviorActions`, and
+  release movement or claims in `onAbort` when a higher branch pre-empts them.
+  Set `thinkInterval` so a crowd thinks a few times a second.
+- **Decision → route.** Actions that move ask one `createNavMeshQuery(mesh)` per
+  mesh for `findPath` and replan only when the goal moves. Bake the mesh from
+  scene geometry with `@jgengine/navbake` (`await initNavBake()`, then
+  `bakeNavMesh`) and store it as an editor `nav` bake; price hazards or lock doors
+  with `areaCosts` through `retune`.
+
+## Gotchas
+
+- Hand the graph facts, not objects: the blackboard serializes with the behavior,
+  so saves and replays keep an NPC mid-investigation.
+- Judge footstep noise on speed averaged over a window, not one frame; frame-time
+  jitter otherwise reads as a sprint.
+- Record the stimulus you handled (`handledAt`) so giving up does not
+  re-alert on the same memory next tick.

package/skills/jgengine-world/recipes/vehicle-feel.md

@@ -0,0 +1,85 @@
+# Recipe — vehicle feel (feel target → metrics → physical knobs)
+
+**What this wires:** a ground vehicle that feels the way the brief says, from sim to camera, sound and rumble. There is no default car: every vehicle is a set of physical numbers the game picks for its own feel, checked against metrics it writes down first.
+
+## The seams
+
+- **Sim.** `createVehicleDynamics(tuning, { surfaceFriction?, clampMove?, groundHeight? })` from `@jgengine/core/physics/vehicleDynamics`. Yaw comes from tire forces, so balance, slides and recovery are outcomes of the numbers, not special cases. It has `snapshot()`/`restore()` for prediction and replay, `retune()` for upgrades and damage, and per-tick modifiers (`driveScale`, `gripScale`, `steerScale`, `brakeScale`, `thrust` for boost).
+- **Terrain.** Add a `suspension` block (spring and damper rates, travel, ride height, anti-roll) and pass `groundHeight` for ramps, hills and jumps. Each wheel then samples the ground, the body heaves, pitches and rolls on real springs, slopes pull the car downhill, and the step reports `airborne`, `landingSpeed` and per-corner `wheelLoads`. Without the block the car stays on a flat plane.
+- **Input.** Put `createAxisShaper` (`@jgengine/core/input/axisShaper`) between `ctx.input.axis(...)` and the sim. Keys get `riseRate`/`returnRate`, so a tap steers a little and a hold builds up; sticks get `deadzone`/`curve` with no lag. Pass `{ analog: analogAxes(bindings, ctx.input.analog()) }` each frame so each axis picks the right profile.
+- **Pad feel.** Set the stick deadzone, curve and trigger deadzone once in `defineGame({ gamepad: { deadzone, curve, triggerDeadzone } })`. The shell applies it before any analog value reaches `ctx.input`, so per-axis shaping in `createAxisShaper` only adds ramps and speed scaling on top.
+- **Jumps and air.** With `suspension`, a `jump` block (`speed`, `count` for double jumps, `window`) enables `car.jump()`, and an `air` block (`pitchAccel`/`yawAccel`/`rollAccel`, `damping`, `maxRate`) rotates the body in flight. Air input comes from `modifiers.air`; without it, throttle−brake pitches and steer yaws, which suits Rocket League-style play. Pass `{ pitch: 0, yaw: axis.steer, roll: 0 }` if W should keep driving instead of nosing down. `applyAngularImpulse` composes dodges and flips. The body stays near level, so full flips and wall-driving wait for the rigid-body backend.
+- **Boats.** `createBoatDynamics` (`@jgengine/core/physics/boatDynamics`) takes the same axis input and returns a step `tickDrivableVehicle` and `measureHandling` accept. Its knobs are mass, length, beam, prop thrust and prop speed, `planingSpeed`, `keel` and `steering` (`rudder` with an area, or `outboard`). A tug and a speedboat differ only in those numbers.
+- **Collision.** In a `PhysicsBackend` world (Rapier or `PhysicsWorld`), `createVehicleBackendLink` gives the car a kinematic chassis that shoves props, and a `clampMove` that stops it at walls. The sim keeps the handling, so the feel numbers above still hold.
+- **Two wheels.** A `lean` block (`maxLean`, `leanRate`, optional `countersteer`) turns the same sim into a motorcycle or bicycle.
+  - Steer asks for a lean, and the bar steers the balanced turn that lean needs.
+  - The bike tips the other way briefly as the lean starts, which is countersteer.
+  - The step reports the balance lean `atan(lateral g)` as `lean`, with `bodyRoll = -lean`. The requested lean is capped at what grip can hold.
+  - `wheelie`/`stoppie` flags come from axle loads. `assists.antiWheelie` and `assists.antiStoppie` cap drive and braking just under the pitch-over limit, and on springs they also back off as the axle goes light. A sprung bike needs them to stay playable.
+  - `measureLean` reports steady lean, time to lean and counter-lean.
+- **Pose.** `tickDrivableVehicle(car, dt, ctx.input.axis(bindings, ranges), { groundHeight })` returns a `setPose` patch. Pitch and roll come from load transfer, or from the springs when `suspension` is set.
+- **Camera.** `camera: { rig: "chase", chase: { fov, lead, bank, velocityYaw, yawResponse } }`. `velocityYaw` shows the car's side in a slide, and `fov` widens with speed.
+  - Speed comes from the entity's sim `velocity`, so publish poses with `setPose({ ..., dt })` (`tickDrivableVehicle` does). `fov.response` eases the FOV.
+  - The boom holds its length at any speed. `distanceBySpeed: { extra }` pulls it back on purpose; `ctx.camera.kickFov(deg)` adds a decaying punch for landings and hits.
+  - `pitchFollow` tilts the boom with `rotationX` on ramps and slopes. `lookBackAction` names an input action that looks behind while held.
+  - The boom stops short of objects, terrain and walls through `ctx.scene.raycast`; `collision: false` turns that off.
+  - Switch views at runtime with `ctx.camera.setChaseTuning({ ...ctx.camera.chaseTuning(), view: nextChaseView(view) })` (`@jgengine/core/runtime/cameraDirector`).
+- **Sound.** Call `ctx.game.audio.loop(id, sound)` once, then `setLoop` every tick:
+  - Engine: `rate` from `step.rpm`, `gain` from `step.engineLoad`.
+  - Tires: `gain` from how far `max(step.frontSaturation, step.rearSaturation)` exceeds ~0.85.
+  - Real engine samples: `createEngineLayers` (`@jgengine/core/audio/engineLayers`) takes N loops keyed by the rpm they were recorded at, crossfades the two around the current rpm, and picks on-load or off-load sets by `engineLoad`. Call `update(dt, { rpm, load })` then `play(ctx.game.audio, { at, velocity, gain, lowpass })` each tick.
+  - `setLoop` also takes `lowpass`/`highpass` cutoffs in Hz (muffle off-throttle) and `velocity`; a sound with `doppler: 1` pitches by listener and emitter velocity.
+- **One place for all of it.** `createFeedbackMixer` (`@jgengine/core/vfx/feedbackMixer`) declares these mappings as routes: `{ signal, target, curve, attack, release }`, with `max` or `sum` combining and threshold `events` for one-shots like a landing thud. Update it with the step's telemetry each tick and apply its targets to `setLoop`, the chase camera and `haptics`, instead of hand-writing the glue.
+- **Rumble.** Set continuous channels each tick on `ctx.input.haptics(userId)`: `set("road", { strong: rearSaturation, weak: frontSaturation })`, an `engine` hum from load and rpm, and `pulse("impact", { strong, weak, ms }, 1)` on a landing so it ducks the rest. The shell mixes them by priority onto that player's pad. `ctx.input.rumble` stays for a single fire-and-forget effect.
+- **Sound.** Play a one-shot on `step.landingSpeed` (thud, suspension clunk).
+- **Proof.** For jumps and air control, `measureAir` reports apex height and time, double-jump height, and air rotation rates.
+- **Proof.** `measureHandling(() => createVehicleDynamics(tuning), options?)` from `@jgengine/core/physics/handlingProbe` returns deterministic numbers. Assert them in a test. For a sprung car, `measureRide` adds settle time, brake dive, roll per g and landing bounces.
+
+## Workflow
+
+1. **Write the feel as numbers before tuning.** Turn the brief into target ranges on the `HandlingReport` fields. Some examples:
+   - "Snappy" is `turnIn < 0.2`.
+   - "Planted" is `maxLateralG` close to the tire μ with `stepPeakSideslipDeg < 8`.
+   - "Drifty but safe" is `handbrakePeakSideslipDeg` 40–70 with `spun === false`.
+   - "Keyboard-friendly" is `spun` and `powerSteerSpun` both `false`, including at `cornerSpeed: 40`.
+   - "Neutral balance" is `measureCourse(...).understeerGradient` near 0–0.5 deg/g; "tail-happy" is below 0.
+   - "Agile" is a high `measureCourse(...).slalomSpeed`; "forgiving" is a short `handbrakeRecoverySeconds`.
+2. **Put those ranges in a test first**, next to the tuning.
+3. **Start from the real vehicle's physical numbers**: mass, wheelbase, weight split, CoM height, driven axle, torque and gears. Then move one knob at a time using the table below, rerunning the test after each change.
+4. **Drive it.**
+   - In the engine repo: `bun run drive <game> --key KeyW:4000 --probe a --key KeyW+KeyD:1500 --probe b --record <name>`. Chords hold throttle and steer together.
+   - `--record-fps 20` keeps game time at 1:1, because each recorded frame advances at most one 50 ms step.
+   - Tests prove the numbers; the drive proves the camera and sound.
+
+## Symptom → knob
+
+| Symptom | Knob (direction) |
+| --- | --- |
+| `understeerGradient` too high | front tire `peakSlipAngle` ↓ or rear ↑ (tire stiffness split is what moves it at moderate g) |
+| Pushes wide, won't turn in | `rollStiffnessFront` ↓, rear `peakGrip` ↓ relative to front, `yawInertiaIndex` ↓, `steering.rate` ↑ |
+| Snaps into oversteer | `rollStiffnessFront` ↑, rear `peakGrip` ↑, `slideGrip` ↑ (gentler breakaway), `assists.stability` ↑ |
+| Spins holding throttle and steer | `assists.tractionControl` ↑ (budgets for cornering grip), `driveFront` ↑, peak torque ↓ |
+| Slides feel uncatchable | `steering.selfAlign` ↑ (caster catches the slide), `slideGrip` ↑, `assists.maxSideslip` ↑ with `stability` ↑ |
+| Too twitchy at speed | `steering.highSpeedAngle` ↓, `steering.rate` ↓, `yawInertiaIndex` ↑, shaper steer `digital.riseRate` ↓ |
+| Keyboard steering is all-or-nothing | shaper steer `digital.riseRate` 2–4/s, `returnRate` 5–8/s |
+| Stick feels twitchy on centre | shaper steer `analog.curve` 1.3–2, `analog.deadzone` 0.05–0.12 |
+| Sluggish, boat-like | `yawInertiaIndex` ↓, `peakSlipAngle` ↓ (stiffer tire), `comHeight` ↓ |
+| Handbrake does nothing / spins every time | `handbrakeGrip` ↓ / ↑, with `selfAlign` to set how it recovers |
+| No top speed ceiling / wrong ceiling | `aero.dragArea`, power (`maxPower` or torque × gearing); `speedLimit` only for a hard governor |
+| Boost or supersonic above the cap | `modifiers.thrust` (bypasses tires and the governor) |
+| Floaty, wallowy body | `suspension.springRate` ↑, `damperRate` ↑ |
+| Harsh, skips over bumps | `springRate` ↓, `travel` ↑ |
+| Landings bounce back into the air | `suspension.reboundRate` ↑ (defaults to 1.5 × `damperRate`), `travel` ↑ |
+| Leans too much / feels flat | `suspension.antiRoll` ↑ / ↓; `rollStiffnessFront` still sets which axle takes it |
+| Jump too floaty / too short | `jump.speed` (apex ≈ speed² / 2g); `jump.count: 2` plus `window` for a double jump |
+| Air rotation too twitchy / sluggish | `air.*Accel` for how fast it builds, `air.maxRate` for the ceiling, `air.damping` for how fast it stops |
+| Bike wheelies on launch / flips over the bars braking | `assists.antiWheelie` / `assists.antiStoppie` ↑ (1 keeps both wheels down; 0.6 lets it lift briefly) |
+| Bike tips in lazily / nervously | `lean.leanRate` ↑ / ↓ (2 tourer … 5 sport); `lean.countersteer` sets the wrong-way tip at the start |
+| Rolls over in corners | `comHeight` ↓ or `trackWidth` ↑: it tips over at about `trackWidth / (2 · comHeight)` g |
+
+## Traps
+
+- Hand-editing `yawRate` or heading to "fix" a turn defeats the model. Change a physical knob instead.
+- `speedLimit` fades drive out and never clamps velocity. A car pinned at its cap can still turn, and thrust can carry it past the cap.
+- A slide that looks right on a gamepad can spin on a keyboard. Assert `powerSteerSpun` and `spun` with the default `stepSteer: 1`, which is a held key.
+- For multiplayer, send inputs, not poses. Predict locally with the same tuning, and on a correction call `restore(serverState)` and replay the buffered inputs.