@jgengine/core 0.18.0 → 0.19.0

package/skills/jgengine-world/capabilities.md

@@ -4,6 +4,14 @@
 
 Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
 
+## 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"`
+
 ## ai-driver — difficulty-aware chase/route driving step producing throttle/brake/steer for the vehicle sim
 
 - `driveStep` (function) · `import { driveStep } from "@jgengine/core/ai/driver"`
@@ -16,6 +24,25 @@ 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 — 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"`
+
 ## area-effect-field — source-following area membership with enter/refresh/leave edges, stacking, and cleanup
 
 - `createAreaEffectField` (function) · `import { createAreaEffectField } from "@jgengine/core/world"`
@@ -87,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"`
@@ -102,6 +134,14 @@ 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"`
+
 ## behavior-control — pause/disable/resume/seek/inspect behavior instances per entity
 
 - `behaviorControl` (function) · `import { behaviorControl } from "@jgengine/core/world"`
@@ -110,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"`
@@ -142,9 +186,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createCameraShake` (function) · `import { createCameraShake } from "@jgengine/core/world"`
 
+## character-controller — capsule walk over the physics backend — slide, step-up, slopes, crouch, platforms
+
+- `createCharacterController` (function) · `import { createCharacterController } from "@jgengine/core/movement/characterController"`
+
 ## 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"`
@@ -171,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"`
@@ -219,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"`
@@ -227,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"`
@@ -235,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
 
@@ -279,6 +352,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `DEFAULT_FORWARD` (const) · `import { DEFAULT_FORWARD } from "@jgengine/core/world"`
 
+## free-flight — camera-relative creative/spectator/noclip/hover flight with correct strafe, sprint, and optional gravity
+
+- `createFreeFlightController` (function) · `import { createFreeFlightController } from "@jgengine/core/world"`
+
+## gamepad-input — Resolve sampled gamepad input into actions with deadzones and response curves.
+
+- `resolveGamepadFrame` (function) · `import { resolveGamepadFrame } from "@jgengine/core/input/gamepadModel"`
+
 ## glide — gliding/wingsuit descent control from a launch
 
 - `createGlideModel` (function) · `import { createGlideModel } from "@jgengine/core/world"`
@@ -297,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"`
@@ -325,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"`
@@ -337,6 +438,11 @@ 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 — 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"`
@@ -366,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"`
@@ -378,6 +500,10 @@ 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
+
+- `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
 
 - `createParticleSystem` (function) · `import { createParticleSystem } from "@jgengine/core/world"`
@@ -403,6 +529,22 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `definePatrolOrder` (function) · `import { definePatrolOrder } from "@jgengine/core/world"`
 
+## perception-service — retain sight, sound, and damage observations with range, cone, occlusion, and decay policy
+
+- `createPerception` (function) · `import { createPerception } from "@jgengine/core/sensor/perception"`
+
+## physics-backend — one interface over interchangeable rigid-body solvers — bodies, joints, raycast, shapecast, snapshot
+
+- `PhysicsBackend` (interface) · `import { PhysicsBackend } from "@jgengine/core/physics/physicsBackend"`
+
+## physics-backend-conformance — the shared test contract a physics adapter runs to prove it matches the seam
+
+- `runPhysicsBackendConformance` (function) · `import { runPhysicsBackendConformance } from "@jgengine/core/physics/physicsBackendConformance"`
+
+## physics-world-backend — the zero-dependency PhysicsWorld solver exposed through the PhysicsBackend seam
+
+- `createPhysicsWorldBackend` (function) · `import { createPhysicsWorldBackend } from "@jgengine/core/physics/physicsWorldBackend"`
+
 ## piece-sockets-from-model — derive build-piece snap sockets from a model's named attach points
 
 - `pieceSocketsFromModel` (function) · `import { pieceSocketsFromModel } from "@jgengine/core/world/buildSockets"`
@@ -443,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"`
 
@@ -451,6 +593,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `evaluateQteSequence` (function) · `import { evaluateQteSequence } from "@jgengine/core/world"`
 
+## rapier-physics-backend — native capsules, shapecasts, rotation, CCD, joints, and collision queries
+
+- `createRapierBackend` (function) · `import { createRapierBackend } from "@jgengine/rapier"`
+
+## rate-window-policy — Evaluate deterministic request windows with retry timing.
+
+- `decideRateWindow` (function) · `import { decideRateWindow } from "@jgengine/core/time/rateWindow"`
+
 ## reputation — faction standing that crosses named reputation tiers
 
 - `tierForStanding` (function) · `import { tierForStanding } from "@jgengine/core/world"`
@@ -459,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"`
@@ -498,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
@@ -560,6 +719,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `surfaceRing` (function) · `import { surfaceRing } from "@jgengine/core/world"`
 
+## tactical-cover-points — derive cover candidates from navigation-mesh boundaries
+
+- `coverPoints` (function) · `import { coverPoints } from "@jgengine/core/ai/tacticalQueries"`
+
+## tactical-position-score — rank bounded tactical positions with caller-defined weights
+
+- `scorePositions` (function) · `import { scorePositions } from "@jgengine/core/ai/tacticalQueries"`
+
 ## target-acquirer — stateful held-target wrapper over an acquisition policy with retention
 
 - `createTargetAcquirer` (function) · `import { createTargetAcquirer } from "@jgengine/core/world"`
@@ -584,11 +751,47 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `raycastHeightField` (function) · `import { raycastHeightField } from "@jgengine/core/world/terrain"`
 
+## territory-cell-chunk — Map ownership cells to persisted world chunks.
+
+- `territoryChunkKey` (function) · `import { territoryChunkKey } from "@jgengine/core/world/territory"`
+
+## territory-footprint — Resolve exactly the ownership cells touched by a placement footprint.
+
+- `territoryFootprintCells` (function) · `import { territoryFootprintCells } from "@jgengine/core/world/territory"`
+
+## territory-owner-query — Read a loaded land cell owner for authoritative placement checks.
+
+- `territoryOwnerOf` (function) · `import { territoryOwnerOf } from "@jgengine/core/world/territory"`
+
+## territory-ownership — Claim, release and query land through host-owned snapshot storage.
+
+- `createTerritory` (function) · `import { createTerritory } from "@jgengine/core/world/territory"`
+
+## territory-placement — Purchase footprint cells atomically with object placement.
+
+- `placeWithTerritory` (function) · `import { placeWithTerritory } from "@jgengine/core/world/territory"`
+
+## territory-read-scope — Load the footprint and foreign-owner gap without scanning the world.
+
+- `territoryChunkKeys` (function) · `import { territoryChunkKeys } from "@jgengine/core/world/territory"`
+
 ## touch-controls — switch the on-screen touch control set when gameplay context changes (enter/exit vehicle, mount, build mode)
 
 - `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"`
@@ -601,6 +804,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `resolveWalkerStep` (function) · `import { resolveWalkerStep } from "@jgengine/core/movement/solidObstacles"`
 
+## walker-solid-step-source — slide a step against solid geometry from a pure rules package
+
+- `resolveSourceWalkerStep` (function) · `import { resolveSourceWalkerStep } from "@jgengine/core/movement/solidObstacles"`
+
 ## wave-runner — observable serializable wave/spawn runner over the seeded spawn director — WAVE N, wave progress, budget/alert readout, onSpawn sink, snapshot/restore
 
 - `createWaveRunner` (function) · `import { createWaveRunner } from "@jgengine/core/world"`
@@ -620,6 +827,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `buildTrimmedIntersections` (function) · `import { buildTrimmedIntersections } from "@jgengine/core/world"`
 - `trimBandAtJunctions` (function) · `import { trimBandAtJunctions } from "@jgengine/core/world"`
 
+## world-physics-colliders — Synchronize terrain and authored static colliders with a physics backend.
+
+- `syncWorldColliders` (function) · `import { syncWorldColliders } from "@jgengine/core/physics/worldColliders"`
+
 ## world-place — declare the place a game happens in — flat/round/voxel/board ground, surface laws, per-place physics
 
 - `world` (function) · `import { world } from "@jgengine/core/world"`
@@ -627,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.