@jgengine/shell 0.25.0 → 0.27.0

package/skills/jgengine-world/capabilities.md

@@ -462,6 +462,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createKinematicVehicle` (function) · `import { createKinematicVehicle } from "@jgengine/core/world"`
 
+## lane-graph — directed lane topology with junctions, signals and parking for vehicle traffic
+
+- `createLaneGraph` (function) · `import { createLaneGraph } from "@jgengine/core/world"`
+
+## lane-graph-from-scene — read an authored lane graph, signals and parking out of the scene document
+
+- `laneGraphFromDocument` (function) · `import { laneGraphFromDocument } 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"`
@@ -549,14 +557,26 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `sweepMovingSphere` (function) · `import { sweepMovingSphere } from "@jgengine/core/physics/ballisticSweep"`
 
+## nav-crowd — move many agents across an editor-baked nav mesh with avoidance
+
+- `createNavCrowd` (function) · `import { createNavCrowd } from "@jgengine/core/world"`
+
 ## nav-from-solids — block world solids on a nav grid
 
 - `populateNavGridFromSolids` (function) · `import { populateNavGridFromSolids } from "@jgengine/core/nav/navFromEnvironment"`
 
+## nav-runtime — route agents on an editor-baked nav mesh with authored links and re-bakes that keep polygon identity
+
+- `createNavRuntime` (function) · `import { createNavRuntime } from "@jgengine/core/world"`
+
 ## navmesh-bake — voxelize scene triangles into an agent-sized polygon nav mesh
 
 - `bakeNavMesh` (function) · `import { bakeNavMesh } from "@jgengine/navbake"`
 
+## navmesh-from-scene — read the editor's baked nav mesh off a scene document
+
+- `navMeshFromBake` (function) · `import { navMeshFromBake } from "@jgengine/core/world"`
+
 ## 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"`
@@ -610,9 +630,9 @@ 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
+## perception-service — retain sightings, sounds and damage with cone, range, occlusion, decaying memory and shared squad knowledge
 
-- `createPerception` (function) · `import { createPerception } from "@jgengine/core/sensor/perception"`
+- `createPerception` (function) · `import { createPerception } from "@jgengine/core/world"`
 
 ## physics-backend — one interface over interchangeable rigid-body solvers — bodies, joints, raycast, shapecast, snapshot
 
@@ -707,6 +727,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `controlGroupKey` (function) · `import { controlGroupKey } from "@jgengine/core/world"`
 - `resolveControlGroupIntent` (function) · `import { resolveControlGroupIntent } from "@jgengine/core/world"`
 
+## rvo-avoidance — reciprocal collision avoidance between many steering agents
+
+- `createRvoCrowd` (function) · `import { createRvoCrowd } from "@jgengine/core/world"`
+
 ## scatter-coverage — shared density/budget semantics for scatterable kinds
 
 - `ScatterCoverageKind` (type) · `import { ScatterCoverageKind } from "@jgengine/core/world"`
@@ -881,6 +905,10 @@ 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"`
 
+## traffic — lane-graph traffic with car following, signals, right-of-way, lane changes and parking
+
+- `createTraffic` (function) · `import { createTraffic } from "@jgengine/core/world"`
+
 ## ui-sound-cues — default procedural click/hover/open/close/confirm/deny/notify cues on a "ui" bus, overridable per game
 
 - `withUiCueSounds` (function) · `import { withUiCueSounds } from "@jgengine/core/audio/uiCues"`
@@ -889,14 +917,26 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `resolveTerrainGradeStep` (function) · `import { resolveTerrainGradeStep } from "@jgengine/core/movement/terrainGrade"`
 
+## utility-brain — pick actions by decaying-need appeal with response curves, hysteresis and interrupts
+
+- `createUtilityBrain` (function) · `import { createUtilityBrain } from "@jgengine/core/world"`
+
 ## 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-damage — fixed-zone crash damage that changes handling and shows a bounded dent, serializable
+
+- `createVehicleDamage` (function) · `import { createVehicleDamage } from "@jgengine/core/world"`
+
 ## 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-parts — compose data-driven tuning parts (tires, engine, brakes) onto a vehicle tuning and read the resulting feel
+
+- `applyVehicleParts` (function) · `import { applyVehicleParts } from "@jgengine/core/world"`
+
 ## 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"`

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

@@ -15,8 +15,14 @@ Working example: the `guard-probe` dev demo (`apps/dev/src/demo/guardProbe.ts`),
   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.
+  `isSegmentClear` for walls — a caller function over your collision layer that
+  returns true when nothing blocks the line; it is only called for pairs already
+  inside range and cone, so keep that cheap. Memory decays linearly over
+  `memorySeconds`; each observer judges a stimulus once. Pass `squadMates` so one
+  member's sighting lands in every mate's memory stamped with `sourceId` and
+  `sourceTick`; `maxSharesPerTick` caps the broadcast. `memoryOf(id, target)` is
+  the one question "is this still known, and how sure", and `stats()` says what
+  the pass cost (pairs, range prunes, line checks, shares).
 - **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

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

@@ -5,6 +5,10 @@
 ## The seams
 
 - **Sim.** `createVehicleDynamics(tuning, { surfaceFriction?, clampMove?, groundHeight? })` from `@jgengine/core/physics/vehicleDynamics`. Yaw comes from tire forces, so balance, slides and recovery are outcomes of the numbers, not special cases. It has `snapshot()`/`restore()` for prediction and replay, `retune()` for upgrades and damage, and per-tick modifiers (`driveScale`, `gripScale`, `steerScale`, `brakeScale`, `thrust` for boost).
+- **Arcade sim.** `createKinematicVehicle(tuning, { surfaceFriction?, dragAt?, clampMove? })` from `@jgengine/core/physics/kinematicVehicle` is the cheap steer-yaw model for chases and ambient cars. Its grip is a `GripCurve` (slip → force) sampled each tick against surface friction, handbrake and downforce; `weightTransfer: { comHeight, wheelbase, trackWidth, sensitivity? }` cuts that curve as weight moves under braking/traction/cornering and reports `weightTransfer`/`loadGrip`. `retune()` swaps handling in play, and `gripScale` on the per-tick modifiers is the one-frame hook. Use the force model above when balance has to come out of the numbers.
+- **Parts.** `applyVehicleParts(base, parts)` (`@jgengine/core/physics/vehicleParts`) folds data-driven parts onto a tuning — `{ id, slot, effects: { engineAccel: { scale, add } }, gripCurve? }` — in install order, and returns the composed tuning plus a comparable `VehicleFeel`. `withPart` swaps one part in its slot, `feelOf(tuning)` reads the numbers out of anything, and `vehicle.retune(setup.tuning)` installs it mid-play without losing momentum.
+- **Damage.** `createVehicleDamage({ zones, disableAt?, onTransition? })` (`@jgengine/core/physics/vehicleDamage`) takes local hit points and impulses, steps fixed zones through thresholds, and returns bounded `deformation()` (a per-zone offset the renderer applies, plus `detached`) and `effect()` (grip/drive/brake/top-speed scales, `steerPull`, `drag`). Feed `effect()` through `damagedTuning(base, effect)` + `retune` for lasting damage, or `modifiers()` for one frame; `damagedAxis(axis, effect)` applies the bent-frame pull. It serializes, so a save or a host correction resumes mid-crash. There is no mesh editing: every zone has one authored `deform` limit.
+  - The dent is rendered by the game's own `renderEntity` (it already receives the entity each render) — the zone's `offset` displaces that part, and `detached` hides it. No shell seam is needed.
 - **Terrain.** Add a `suspension` block (spring and damper rates, travel, ride height, anti-roll) and pass `groundHeight` for ramps, hills and jumps. Each wheel then samples the ground, the body heaves, pitches and rolls on real springs, slopes pull the car downhill, and the step reports `airborne`, `landingSpeed` and per-corner `wheelLoads`. Without the block the car stays on a flat plane.
 - **Input.** Put `createAxisShaper` (`@jgengine/core/input/axisShaper`) between `ctx.input.axis(...)` and the sim. Keys get `riseRate`/`returnRate`, so a tap steers a little and a hold builds up; sticks get `deadzone`/`curve` with no lag. Pass `{ analog: analogAxes(bindings, ctx.input.analog()) }` each frame so each axis picks the right profile.
 - **Pad feel.** Set the stick deadzone, curve and trigger deadzone once in `defineGame({ gamepad: { deadzone, curve, triggerDeadzone } })`. The shell applies it before any analog value reaches `ctx.input`, so per-axis shaping in `createAxisShaper` only adds ramps and speed scaling on top.
@@ -36,6 +40,7 @@
 - **Sound.** Play a one-shot on `step.landingSpeed` (thud, suspension clunk).
 - **Proof.** For jumps and air control, `measureAir` reports apex height and time, double-jump height, and air rotation rates.
 - **Proof.** `measureHandling(() => createVehicleDynamics(tuning), options?)` from `@jgengine/core/physics/handlingProbe` returns deterministic numbers. Assert them in a test. For a sprung car, `measureRide` adds settle time, brake dive, roll per g and landing bounces.
+- **Proof.** For the arcade sim, `feelOf(setup.tuning)` gives comparable numbers per build, and a test drives the same scripted inputs on two `surfaceFriction` values (or before/after `damagedTuning`) and asserts the grip difference — slip and lateral speed retained, and top speed reached.
 
 ## Workflow