@jgengine/shell 0.18.1 → 0.21.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,23 @@ 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"`
+- `validateAnimGraph` (function) · `import { validateAnimGraph } 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"`
 
@@ -89,10 +103,24 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `defineAttackMoveOrder` (function) · `import { defineAttackMoveOrder } from "@jgengine/core/world"`
 
+## audio-voice-budget — bound simultaneous sound playback with per-sound caps, priorities, and deterministic stealing
+
+- `createVoiceAllocator` (function) · `import { createVoiceAllocator } from "@jgengine/core/audio/voiceAllocator"`
+
+## authored-animation — consume live authored character animation with bounded per-frame work
+
+- `createAuthoredAnimationReader` (function) · `import { createAuthoredAnimationReader } from "@jgengine/core/world/authoredAnimation"`
+- `readAuthoredAnimation` (function) · `import { readAuthoredAnimation } from "@jgengine/core/world/authoredAnimation"`
+- `readAuthoredAnimationValue` (function) · `import { readAuthoredAnimationValue } from "@jgengine/core/world/authoredAnimation"`
+
 ## authored-entities — spawn authored mob/boss markers from the editor document at runtime
 
 - `authoredEntitySpawns` (function) · `import { authoredEntitySpawns } from "@jgengine/core/world/authoredEntities"`
 
+## authored-environment — compose authored weather, shelter, accumulation, fire, flocks and effects using one simulation clock
+
+- `createAuthoredSimulation` (function) · `import { createAuthoredSimulation } from "@jgengine/core/world/authoredSimulation"`
+
 ## authored-objects — marker kinds resolved as entity spawns, not static props
 
 - `ENTITY_MARKER_KINDS` (const) · `import { ENTITY_MARKER_KINDS } from "@jgengine/core/world/authoredObjects"`
@@ -100,6 +128,12 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `markerCatalogId` (function) · `import { markerCatalogId } from "@jgengine/core/world"`
 - `placeAuthoredObjects` (function) · `import { placeAuthoredObjects } from "@jgengine/core/world"`
 - `resolveAuthoredObjects` (function) · `import { resolveAuthoredObjects } from "@jgengine/core/world"`
+- `resolveAuthoredObjectsWithDiagnostics` (function) · `import { resolveAuthoredObjectsWithDiagnostics } from "@jgengine/core/world/authoredObjects"`
+
+## 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
 
@@ -116,6 +150,18 @@ 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"`
 
+## authored-weather — Sample scheduled precipitation and local wind from one authored document and simulation clock.
+
+- `createAuthoredWeather` (function) · `import { createAuthoredWeather } from "@jgengine/core/world/authoredWeather"`
+
+## authored-weather-validation — Reject invalid weather profiles, schedules, zones and wind before authoring mutations.
+
+- `validateAuthoredWeather` (function) · `import { validateAuthoredWeather } from "@jgengine/core/world/authoredWeather"`
+
+## 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"`
@@ -124,14 +170,26 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `behaviorControl` (function) · `import { behaviorControl } from "@jgengine/core/world"`
 
-## behavior-tick — auto-advance patrol/wander behaviors on spawned entities, no per-game route loop
+## behavior-tick — auto-advance spawned patrol, wander, pursuit and decision graph behaviors with lifecycle control
 
 - `advanceBehaviors` (function) · `import { advanceBehaviors } from "@jgengine/core/world"`
 
+## board-vehicle — board a rideable, freeze/hide its rider and apply caller camera policy
+
+- `boardVehicle` (function) · `import { boardVehicle } 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"`
 
+## bounded-grid-route — distinguish no path from exhausted grid search work
+
+- `findPathResult` (function) · `import { findPathResult } from "@jgengine/core/nav/navGrid"`
+
 ## build-footprint-cells — grid cells a snapped build piece footprint covers (footprintGrid occupancy bridge)
 
 - `footprintCells` (function) · `import { footprintCells } from "@jgengine/core/world/buildSockets"`
@@ -167,6 +225,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 +252,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 +304,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,17 +320,33 @@ 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"`
 
+## environment-motion — apply capped spatial wind and vortex forces to game-selected actors through shared motion intents
+
+- `installEnvironmentMotion` (function) · `import { installEnvironmentMotion } from "@jgengine/core/world/environmentForces"`
+
 ## fast-travel — network of fast-travel destinations with discovery, distance-sorted queries, nearest lookup, a travel gate, and serializable state
 
 - `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"`
 
-- `createAircraftDynamics` (function) · `import { createAircraftDynamics } from "@jgengine/core/world"`
+## 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"`
+
+## 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
 
@@ -269,6 +356,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createFootprintGrid` (function) · `import { createFootprintGrid } from "@jgengine/core/world"`
 
+## force-field-validation — reject invalid localized force authoring before simulation
+
+- `validateForceField` (function) · `import { validateForceField } from "@jgengine/core/physics/forceVolume"`
+
 ## formation-assignment — stable deterministic member-to-slot matching for a group formation
 
 - `assignFormationSlots` (function) · `import { assignFormationSlots } from "@jgengine/core/world"`
@@ -327,10 +418,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 +458,18 @@ 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"`
+
+## leave-vehicle — leave a rideable beside its current pose and restore on-foot camera/movement
+
+- `leaveVehicle` (function) · `import { leaveVehicle } from "@jgengine/core/world"`
+
 ## limb-health — per-body-part/region health tracked separately
 
 - `createMultiRegionHealth` (function) · `import { createMultiRegionHealth } from "@jgengine/core/procedural"`
@@ -363,18 +478,36 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `resolveLocalAvoidance` (function) · `import { resolveLocalAvoidance } from "@jgengine/core/world"`
 
+## localized-forces — sample signed attraction, directional force, vortex spin and axial lift with target masks and caps
+
+- `sampleForceField` (function) · `import { sampleForceField } from "@jgengine/core/physics/forceVolume"`
+
 ## lockpick — a solvable grid depth-puzzle with fog-of-war, gates, and hidden traps
 
 - `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
 
 - `createAnnotationLayer` (function) · `import { createAnnotationLayer } from "@jgengine/core/world"`
 
+## material-appearance-signals — adapt selected surface response to sampled wetness and local card exposure
+
+- `resolveMaterialAppearance` (function) · `import { resolveMaterialAppearance } from "@jgengine/core/material/appearanceSignals"`
+- `sampleMaterialAppearance` (function) · `import { sampleMaterialAppearance } from "@jgengine/core/material/appearanceSignals"`
+
+## merge-footprint-regions — pool adjacent compatible footprints with serializable capacity provenance
+
+- `mergeFootprints` (function) · `import { mergeFootprints } from "@jgengine/core/world"`
+
+## mergeable-footprint-regions — check compatible adjacent regions within caller work budgets
+
+- `canMerge` (function) · `import { canMerge } from "@jgengine/core/world"`
+
 ## mesh-hitboxes — shots pass through holes in concave models — opted-in catalog assets raycast their actual triangles instead of the fitted box.
 
 - `ColliderShape` (type) · `import { ColliderShape } from "@jgengine/core/scene/colliders"`
@@ -400,6 +533,34 @@ 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"`
+
+## movement-telemetry — read physical grounded, vertical velocity and crouch state without animation-store writes
+
+- `playerMovementTelemetry` (function) · `import { playerMovementTelemetry } from "@jgengine/core/movement/playerMovement"`
+
+## moving-box-sweep — detect contact with boxes crossing a projectile segment between simulation poses
+
+- `sweepMovingBounds` (function) · `import { sweepMovingBounds } from "@jgengine/core/physics/ballisticSweep"`
+
+## moving-sphere-sweep — detect contact with spheres crossing a projectile segment between simulation poses
+
+- `sweepMovingSphere` (function) · `import { sweepMovingSphere } from "@jgengine/core/physics/ballisticSweep"`
+
+## 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"`
@@ -412,11 +573,19 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createOrderRegistry` (function) · `import { createOrderRegistry } from "@jgengine/core/world"`
 
-## particle-director — game-reachable VFX seam: queue one-shot particle bursts and keyed follow-capable standing emitters as serializable data for the shell to render
+## particle-binding-validation — validate named particle follow spaces, render outputs, environment influence, and bounded collision child effects
+
+- `validateParticleAttachOptions` (function) · `import { validateParticleAttachOptions } from "@jgengine/core/vfx/particleDirector"`
+
+## particle-director — named particle start/stop/burst/retune lifecycle, local/world following, render outputs, bounded cosmetic event exchange, and serializable emitter definitions
 
 - `createParticleDirector` (function) · `import { createParticleDirector } from "@jgengine/core/vfx/particleDirector"`
 
-## particle-system — deterministic pooled particle emitter with SoA render buffers, burst/continuous emission, gravity/drag, size/color/alpha-over-life, and serializable state
+## particle-emitter-validation — validate finite spawn volumes, force fields, lifetimes, appearance curves, and bounded particle collision policies
+
+- `validateEmitterConfig` (function) · `import { validateEmitterConfig } from "@jgengine/core/vfx/particles"`
+
+## particle-system — deterministic pooled particle emitter with spawn volumes, force fields, bounded collision/death events, live tuning, SoA render buffers, and serializable state
 
 - `createParticleSystem` (function) · `import { createParticleSystem } from "@jgengine/core/world"`
 
@@ -497,7 +666,11 @@ 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
+## pursue-behavior — scheduled pursuit with bounded target acquisition and saved cooldown/leash state
+
+- `pursue` (function) · `import { pursue } from "@jgengine/core/world"`
+
+## 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 +694,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,8 +741,17 @@ 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"`
 
+## solid-route — bounded local planning over indexed collision geometry
+
+- `planSolidRoute` (function) · `import { planSolidRoute } from "@jgengine/core/nav/solidRoute"`
+
+## spatial-incremental — Update one entity's spatial cell after a committed write without scanning the population
+
+- `createSpatialApi` (function) · `import { createSpatialApi } from "@jgengine/core/scene/spatial"`
+
 ## spatial-region-box — sample uniformly within an axis-aligned 3D box
 
 - `boxRegion` (function) · `import { boxRegion } from "@jgengine/core/world"`
@@ -602,6 +792,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `sampleStratified` (function) · `import { sampleStratified } from "@jgengine/core/world"`
 
+## split-footprint-regions — split pooled regions along retained contributions without area-based capacity loss
+
+- `splitRegion` (function) · `import { splitRegion } from "@jgengine/core/world"`
+
 ## stop-order — halt-and-complete order that brings a unit to an immediate standstill
 
 - `defineStopOrder` (function) · `import { defineStopOrder } from "@jgengine/core/world"`
@@ -622,6 +816,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `surfaceRing` (function) · `import { surfaceRing } from "@jgengine/core/world"`
 
+## sync-authored-objects — synchronize edited catalog prop poses, elevation and removal through the existing object store
+
+- `syncAuthoredObjects` (function) · `import { syncAuthoredObjects } from "@jgengine/core/world/authoredObjects"`
+
 ## tactical-cover-points — derive cover candidates from navigation-mesh boundaries
 
 - `coverPoints` (function) · `import { coverPoints } from "@jgengine/core/ai/tacticalQueries"`
@@ -683,6 +881,22 @@ 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"`
 
+## uphill-grade-step — constrain sampled heightfield ascent with axis sliding and a configurable terrain-policy sampler
+
+- `resolveTerrainGradeStep` (function) · `import { resolveTerrainGradeStep } from "@jgengine/core/movement/terrainGrade"`
+
+## 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"`
@@ -707,6 +921,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createWaypointStore` (function) · `import { createWaypointStore } from "@jgengine/core/world"`
 
+## weather-environment-field — Connect authored precipitation and temperature changes to spatial environment queries.
+
+- `createWeatherEnvironmentField` (function) · `import { createWeatherEnvironmentField } from "@jgengine/core/world/authoredWeather"`
+
+## weather-surface-accumulation — Persist and retune bounded surface wetness, snow, temperature and exposure independently of rendering.
+
+- `createWeatherExposure` (function) · `import { createWeatherExposure } from "@jgengine/core/world/authoredWeather"`
+
 ## world-environment — compose editor/preset-derived outdoor dressing — terrain, weather, water, structures — into a legacy environment feature
 
 - `environment` (function) · `import { environment } from "@jgengine/core/world"`
@@ -729,3 +951,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,62 @@
+# 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. Equivalent same-order animation data survives ordinary React rerenders without restarting gait, pending triggers or visual variant choices. The hook retains a private serialized snapshot; intentional clip, playback or graph edits restart that model’s playback. Keep authored one-shot order: it decides priority among simultaneous non-death triggers. Changing the scene, imported clips, context or instance identity starts a new animation lifecycle.
+- **Playback clock.** An entity-bound model (`instanceId` with a game context) holds its animation while game time is paused or has zero timescale. Resume continues the existing mixer/graph and queued triggers. Omitted `animation.clock` or `clock: "real"` retains real-time playback. Choose `{ auto: true, clock: "game" }` for a character whose gait and clip progress should follow locally accepted simulation time. The shell samples `ctx.time.advancedSeconds()` rather than multiplying the raw render delta: clamped frames, fixed steps with no accepted tick and dropped catch-up time cannot advance clips ahead of movement. Accepted seconds already include play speed and timescale, exclude calendar compression, and never hydrate or serialize with saved clock offsets. Held frames checkpoint progress so resume does not replay their elapsed time; `animation.timeScale` remains a separate authored visual rate. Context-hosted unbound previews and previews without a context keep using real time.
+  - `createSimClock` supplies the allocation-free progress getter. The getter is optional on external structural clocks; selecting game playback without one produces a repair warning and holds the pose. Provide that clock capability or choose real-time playback.
+  - This is local accepted progress. Hosted prediction with `advanceTime: false` contributes no progress; it does not supply an accepted remote timeline. Keep real-time playback for those clients unless their clock supplies the intended progress. No snapshot, persistence or signaling format changes are required by the local policy.
+- **Automatic roles with controls.** `animation: "auto"` retains the existing defaults. `{ auto: true, clock: "game" }` derives those same roles and one-shot variants from the loaded rig, then applies explicit configuration fields. Explicit `states`, `oneShots` and `graph` replace their whole fields rather than merging mappings; empty maps retain their meaning. A rig without an identifiable idle does not acquire a guessed first-clip fallback. In the inspector's Custom playback controls, select the clock and optionally derive loaded clip roles; selecting a single clip clears automatic derivation. Both settings are ordinary `meta.animation` data and use the same strict reader, undo, save and reload path as other animation controls.
+- **Modular visibility.** `ModelConfig.hiddenNodes: ["Knife", "Rogue_Cape"]` hides named visual subtrees on that model instance. Ordinary entity models and custom `useModelInstance` hosts share the selection. Names resolve through `resolveRigNode`; missing or ambiguous names warn and leave the body intact. Malformed lists reject before model or texture allocation. Imported invisible nodes stay invisible, and omitting the field or passing `[]` preserves imported visibility. This does not delete bones, retarget clips or mask skinned vertices. The selected visible bind bounds drive `targetHeight` and grounding before animation; catalog dimensions remain source metadata. Reordered or duplicate names retain the clone; a changed selection replaces only that instance and restarts its visual animation lifecycle. Choose names from the actual asset; instanced crowd/scatter renderers do not implement this selection.
+- **Placement.** `targetHeight` normalizes skin-applied imported bind bounds and grounds them at `ModelConfig.y`, then `scale` multiplies that height. The renderer caches skin-applied vertices before animation and shares them between clones, so skin deformation cannot change normalization or fitted collision triangles. Imported root transforms stay inside a separate placement frame shared by render bounds and collision triangles; clips keep binding to the imported root.
+  - Editor clip and graph previews use this same placement frame through `useModelInstance`; they pose its `content` and mount its `scene` with the returned `scale` and `position`. Clip metadata uses the shared loader cache, and closing a preview releases only its own materials and bone textures.
+  - Heightfield player collision has its own `movement.collisionHeight` (positive meters from feet; default 1.8). Choose it for the game's physical body and author it through a supplied `createMovementSchema` catalog field. Rendered `targetHeight`/`scale` and camera target/eye height remain independent; they do not silently resize the motor. Capsule and voxel controllers keep their declared dimensions.
+- **Movement authoring.** A game-named movement catalog can expose the motor's existing jump buffer, coyote grace, release factor, apex/fall gravity and landing recovery controls through supplied `createMovementSchema` defaults. Deeper controls appear in a collapsed **Jump response** group; the common setup does not acquire unused controls. Consume the saved row with `bindAuthoredMovement` to tune `movement.feel` live while retaining the game's callbacks and physics. These are physical movement controls; graph clips and transition choices remain authored separately.
+- **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. One-shot arrays retain every variant. `death` takes priority over simultaneous triggers and holds until the graph is reset; later hit/attack triggers cannot release 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.
+  - Each layer owns its clip times and weights. Within one layer, two states using the same clip still resolve to one clip time; blending separate times of that same clip is unsupported.
+  - `createAnimGraphRuntime(graph, { rng })` runs the same graph headless: `advance(dt, params, clips)`, `trigger`, `snapshot`/`restore`, `retune`. A clip state's `variants` are chosen once on entry; snapshots preserve that choice. Omit `rng` for the first variant. Runtime models use independent seeded visual streams keyed by instance id and imported clip names, so rendering or culling models cannot advance gameplay randomness. Remounting restarts that visual stream; gameplay-critical clip choices belong in a caller-owned headless runtime and its saved state. Outgoing clips keep advancing during crossfades. 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. A missing/blank idle role leaves a named single clip active (or the bind pose if none is named); a missing/blank walk role holds the named idle at walking speeds. The inspector seeds supported semantic roles from the actual asset when enabling locomotion; imported assets without such roles need explicit choices. `validateAnimGraph(json)` rejects malformed saved graphs with located repairs, preserving valid graph data and transition order. `parseAnimGraph(json)` remains the permissive import path that drops malformed entries.
+- **Static character placements.** Catalog placements validate saved `meta.animation` with the same strict value reader as dynamic characters and the inspector. A malformed override is omitted so the original catalog animation remains active; the saved document and placement stay unchanged. `resolveAuthoredObjectsWithDiagnostics(document)` returns the ordinary objects plus located repairs in one scan, and `<AuthoredObjects>` reports those repairs at runtime. Valid partial roles, empty maps, signed rates, ordered variants and extension fields keep their authored meaning. Asset clip and rig compatibility still belongs to the model diagnostics.
+- **Dynamic character authoring.** Store animation on the game-selected marker at `meta.animation` through ordinary editor commands, then use `createAuthoredAnimationReader(() => getDocumentLiveSync()?.getDocument() ?? editorLayers, markerId, gameDefault)` (`@jgengine/core/world/authoredAnimation`). A game-owned `ModelConfig.animation` getter returns `read().animation`; the game chooses the actor-to-marker association, rig and defaults. The reader validates only after immutable document identity changes. Authored objects replace defaults rather than merging their roles, graph or combat triggers; explicit `"auto"`/`"none"` and in-progress empty/partial roles survive save/reload. Omitted or malformed overrides retain the exact game default, and `read().diagnostics` supplies document paths and repairs. Surface those diagnostics during inspection; asset clip and rig compatibility still use `diagnoseModelAnimation`.
+- **Parameters.** The shell feeds the entity's smoothed ground speed as `speed`. For shared player movement it also reads physically resolved `grounded`, `verticalSpeed` and `crouched` through `playerMovementTelemetry(ctx, entityId)`; these values override conflicting blackboard extras. Custom movers retain their authored extras under `ANIM_PARAMS_KEY` when telemetry is unavailable. `readModelAnimationParams(ctx, entityId, speed, out)` gives custom render hosts the same rule, clearing and reusing their own dictionary without writing game state. The names are exported as `LOCOMOTION_SPEED_PARAM`, `LOCOMOTION_GROUNDED_PARAM`, `LOCOMOTION_VERTICAL_SPEED_PARAM` and `LOCOMOTION_CROUCHED_PARAM`.
+  - Jump clips remain explicit rig choices in the game's graph. A supported rig can enter its start clip on `!grounded && verticalSpeed > 0`, its air loop at the physical apex, and its landing clip on ground contact. Let an airborne or landing state return to takeoff when vertical speed becomes positive so a buffered re-jump is visible even if rendering misses the grounded frame. Use `verticalSpeed < 0` for falling from locomotion so unavailable movement data does not invent a fall. Verify those transitions against that rig and the game's physical motor; no automatic jump mapping or universal compatibility is supplied.
+- **Placement discontinuities.** The shell uses the live simulation `snapDistance` to discard inferred gait speed when a character moves farther than that distance in three dimensions between visual samples. Retune it through `ctx.sim.retune({ snapDistance })` with the game's existing interpolation policy; `Infinity` permits continuous fast motion. Sampling resets the speed history while preserving graph time, triggers, variants and terminal states. The shared motor clears its retained state when its driven actor despawns. Raw position updates retain physical motor state; a reconstruction policy can call `forgetPlayerMovement` explicitly.
+- **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 an influencing clip crosses that time. Full-cycle frames still fire; multiple missed cycles coalesce to one event per advance. 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` extracts local root-bone travel into `output.rootDelta` and plays the rig in place horizontally. The in-place flag remains active while a fading-out root-motion clip influences the pose, including interrupted fades and restored graph snapshots. The renderer never changes entity position: the movement/collision owner must consume the headless delta, transform it through the imported rig's parent/facing/scale with `takeRootMotion`, and resolve it through its controller. The bone's vertical motion remains animated. `createGraphPose.apply(output.clips, output.rootMotion)` gives editor/custom previews the same in-place policy. Existing graphs that relied on renderer-driven movement must migrate to a collision-authoritative host; no automatic vault or dodge motor is supplied. Extraction currently assumes the first bone has a matching `.position` track. Root deltas sample the current state's travel; they do not integrate outgoing travel or transition fade weights. Hosts needing collision-authoritative blended root travel must implement that policy explicitly; the in-place visual guarantee does not imply blended root-delta support.
+- **Diagnostics.** `diagnoseModelAnimation(scene, config, clips)` checks incomplete locomotion roles, missing active clip mappings, masks that match no used tracks and unsupported root-track assumptions. Explicit graphs take precedence over dormant role/single-clip settings, so inactive settings do not produce misleading warnings. Runtime and graph previews warn with the same repair guidance. An explicit invalid single clip retains the bind pose rather than playing an arbitrary first clip.
+  - Inspector and Graph panels validate saved `meta.animation` with the same strict reader. A malformed override shows its document path and repair, leaves the saved data intact, and blocks ordinary playback edits and graph preview. Diagnostics remain visible without imported clip metadata. Explicit replacement discards the invalid override through an undoable marker edit; Custom derivation requires the rig's real clip list. Valid partial roles, signed playback values, variant order and extension fields survive unrelated edits.
+- **Imported rig slots.** `ModelConfig.attachments[].slot` uses an exact runtime node name first, then a unique original imported name (`userData.name`). GLTFLoader can sanitize `handslot.r` to `handslotr`; authored slot references keep working without renaming animated bones.
+  - `resolveRigNode(rig, name)` (`@jgengine/shell/render/rigNode`) returns the instance node or a missing/ambiguous-name diagnostic. Duplicate references need a unique runtime name or repaired imported names; no arbitrary target is selected.
+  - Resolve on model load or slot changes and keep the node with its own instance. Attachments retain their local offsets under the animated slot and the model's placement, facing and scale; cleanup removes only that instance's attachment.
+  - This resolves node identity; it does not retarget animations or make different rigs share attachment proportions.
+- **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`.
+  - Explicit joint, `pelvis` and `lookAt.bone` references use exact runtime names first, then the same unique original imported-name lookup as attachments. A name such as `upperleg.r` can resolve after GLTFLoader sanitizes it to `upperlegr`; this preserves node identity and does not supply rig retargeting.
+  - Each named joint must resolve uniquely and descend from the preceding joint; intermediate helper transforms are allowed. Missing, ambiguous, disconnected or overlapping chains produce a resolution warning and are skipped. Missing `pelvis` and `lookAt.bone` names also warn. Automatic pelvis correction uses the resolved legs' common ancestor; an explicit `pelvis` retains the authored selection. Auto detection is a naming convention, not compatibility with every rig.
+  - 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.
+  - Disabling or replacing IK clears its previous corrections and resets smoothing; unmount restores untouched joint poses while preserving newer animation writes. This keeps editor play/adjust loops from leaving an offset pelvis after IK is removed.
+  - 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 | extract `rootMotion: true` travel and resolve it through the collision owner |
+| Hundreds of animated characters cost thousands of draw calls | `SkinnedInstances` for the background crowd |

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

@@ -0,0 +1,48 @@
+# 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.
+- **Overlapping menus.** `suspendPlayControls(ctx)` returns one idempotent release function per owner. Acquire while a menu is open and release on close, context replacement or unmount; controls resume only after the final owner releases and the existing play gate permits it. Shell settings own this lease automatically. Binding snapshots omit leases, and restoring bindings preserves the current context's live owners. Suspension clears held keyboard, pointer and analog input, so resuming requires fresh input; it does not pause a shared realm. Ordinary binding-context swaps retain held input.
+- **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.
+- **Simulation edges.** The shell retains a press released before the next fixed step; `ctx.input.justPressed` samples it on that step while `isDown` already reflects release. Headless callers can supply `presses` to `publishInput`; record/replay applies those edges only on the recorded tick. Canvas mouse bindings use `mouse0`/`mouse1`/`mouse2`, including native button chords; overlays do not begin gameplay presses. Focus loss, suspension and owner teardown clear pending local presses.
+- **Hosted saves.** Persist `HostedGameRunner.state()` for reconstruction. Its host-only input admission and pending-edge state prevents retransmitted stored input from replaying a consumed press; `snapshot()` and client replication omit that bookkeeping.
+- **Hosted retention.** Join or resume a member before publishing input; nonmember frames are ignored. The runner compacts elapsed input in memory while retaining continuous intent and every unconsumed future replay tick; a standalone `InputRecorder` keeps its full log. `inputRetention` configures departed admission marks (default 256 users, 5 minutes; either limit can be zero), with `nowMs` in wall-clock milliseconds. Recent reconnect protection is process-local and ends on expiry or oldest-entry eviction. `inputStats()` reports actual retained recorders, frames and admission marks for host health checks.
+- **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.