@jgengine/core 0.14.0 → 0.15.0

package/dist/physics/kinematicVehicle.js

@@ -1,9 +1,9 @@
 import { steerYaw } from "../movement/steering.js";
 import { DEFAULT_GRIP_CURVE, sampleGripCurve } from "./vehicleBody.js";
-export function createKinematicVehicle(tuning, options = {}) {
-    const grip = tuning.grip ?? DEFAULT_GRIP_CURVE;
-    const chassis = tuning.chassis;
-    const rollingResistance = tuning.rollingResistance ?? 0;
+export function createKinematicVehicle(initialTuning, options = {}) {
+    // Mutable so `retune` can swap the whole block without disturbing the integrator's state; every
+    // read below is per-tick rather than captured at construction for the same reason.
+    let tuning = initialTuning;
     const surfaceFriction = options.surfaceFriction ?? (() => 1);
     const dragAt = options.dragAt ?? (() => 0);
     const clampMove = options.clampMove;
@@ -21,11 +21,17 @@ export function createKinematicVehicle(tuning, options = {}) {
     let previousForwardSpeed = 0;
     let bodyPitch = 0;
     let bodyRoll = 0;
+    let airOffset = 0;
+    let verticalVelocity = 0;
     function forward() {
         return [Math.sin(heading), Math.cos(heading)];
     }
     return {
         tick(dt, axis, modifiers) {
+            const grip = tuning.grip ?? DEFAULT_GRIP_CURVE;
+            const chassis = tuning.chassis;
+            const rollingResistance = tuning.rollingResistance ?? 0;
+            const hopGravity = tuning.hopGravity ?? 0;
             const topSpeed = tuning.topSpeed * (modifiers?.topSpeedScale ?? 1);
             const engineAccel = tuning.engineAccel * (modifiers?.accelScale ?? 1);
             const turnRate = tuning.turnRate * (modifiers?.turnRateScale ?? 1);
@@ -50,6 +56,20 @@ export function createKinematicVehicle(tuning, options = {}) {
                 yawRate += (targetYaw - yawRate) * yawResponse;
                 heading += yawRate * dt;
             }
+            // Handbrake rear-lock oversteer: pure grip bleed leaves a bicycle car going mostly straight
+            // while sliding. Extra yaw from steer×handbrake is what makes drifts initiate and hold
+            // (GTA/NFS-style street feel) without needing a dual-axle tire model.
+            if (axis.handbrake > 0.05 && Math.abs(speed) > HANDBRAKE_OVERSTEER_MIN_SPEED && Math.abs(axis.steer) > 0.02) {
+                const speedFactor = Math.min(1, Math.abs(speed) / HANDBRAKE_OVERSTEER_REF_SPEED);
+                const oversteerYaw = -Math.sign(speed === 0 ? 1 : speed) *
+                    axis.steer *
+                    axis.handbrake *
+                    HANDBRAKE_OVERSTEER_YAW *
+                    speedFactor;
+                // Integrate immediately so this tick's heading (and next-frame velocity basis) rotate with the slide.
+                heading += oversteerYaw * dt;
+                yawRate += oversteerYaw * 0.65;
+            }
             const [fx, fz] = forward();
             let accel = 0;
             let tractionLimited = false;
@@ -81,6 +101,15 @@ export function createKinematicVehicle(tuning, options = {}) {
                 const normalizedRpm = (rpm - powertrain.idleRpm) / Math.max(1, powertrain.redlineRpm - powertrain.idleRpm);
                 const torque = sampleGripCurve(powertrain.torqueCurve, normalizedRpm);
                 torqueFactor = torque * (shiftRemaining > 0 ? 0.32 : 1);
+                // Launch clutch floor: at crawl speeds the idle end of a torque curve under-reads what a
+                // clutched street car actually puts down. Fade the floor out by {@link LAUNCH_TORQUE_FADE_SPEED}
+                // so mid-range power still comes from the curve.
+                if (axis.throttle > 0) {
+                    const launchBlend = 1 - Math.min(1, Math.abs(speed) / LAUNCH_TORQUE_FADE_SPEED);
+                    if (launchBlend > 0) {
+                        torqueFactor = Math.max(torqueFactor, LAUNCH_TORQUE_FLOOR * launchBlend + torqueFactor * (1 - launchBlend));
+                    }
+                }
             }
             if (axis.throttle > 0 && speed < topSpeed) {
                 accel += chassis === undefined
@@ -90,16 +119,20 @@ export function createKinematicVehicle(tuning, options = {}) {
             if (axis.brake > 0) {
                 if (speed > 0.2) {
                     const abs = tuning.dynamics?.abs ?? 0;
-                    const brakeScale = Math.max(0.15, 1 - abs * Math.max(0, Math.abs(speed) / Math.max(1, topSpeed) - 0.72));
-                    absActive = brakeScale < 0.999;
+                    const brakeScale = Math.max(0.15, 1 - abs * Math.max(0, Math.abs(speed) / Math.max(1, topSpeed) - 0.72)) *
+                        (modifiers?.brakeScale ?? 1);
+                    absActive = brakeScale < 0.999 * (modifiers?.brakeScale ?? 1);
                     accel -= chassis === undefined
                         ? axis.brake * tuning.brakeAccel * brakeScale
                         : (axis.brake * chassis.brakeForce * brakeScale) / chassis.massKg;
                 }
                 else if (speed > -tuning.reverseSpeed) {
+                    // Reverse is intentionally softer than forward — full engineForce made performance cars
+                    // hit reverse top in ~2 s and felt like a second highway gear.
+                    const reverseScale = chassis?.reverseForceScale ?? tuning.reverseForceScale ?? DEFAULT_REVERSE_FORCE_SCALE;
                     accel -= chassis === undefined
-                        ? axis.brake * engineAccel
-                        : (axis.brake * chassis.engineForce * (modifiers?.accelScale ?? 1)) / chassis.massKg;
+                        ? axis.brake * engineAccel * reverseScale
+                        : (axis.brake * chassis.engineForce * reverseScale * (modifiers?.accelScale ?? 1)) / chassis.massKg;
                 }
             }
             const traction = tuning.dynamics?.tractionControl ?? 0;
@@ -121,11 +154,27 @@ export function createKinematicVehicle(tuning, options = {}) {
             // never push the car backwards.
             if (chassis !== undefined && dt > 0 && Math.abs(speed) > 1e-4) {
                 let resistDecel = ROLLING_RESISTANCE_COEFFICIENT * GRAVITY;
-                if (axis.throttle <= 0 && tuning.powertrain !== undefined) {
+                // Engine braking is a coast/lift-off load only. Applying it while the brake axis is driving
+                // reverse (speed ≤ 0.2 + brake) would fight reverse accel and leave cars crawling backwards.
+                const reverseDriving = axis.brake > 0 && speed <= 0.2;
+                if (axis.throttle <= 0 && !reverseDriving && tuning.powertrain !== undefined) {
                     resistDecel += ENGINE_BRAKE_COEFFICIENT * GRAVITY * gearLeverage;
                 }
                 accel -= Math.sign(speed) * Math.min(resistDecel, Math.abs(speed) / dt);
             }
+            // Arcade coast road-load: a flat deceleration while genuinely coasting — no throttle and no
+            // brake — capped at |speed|/dt so it can never drag the vehicle backwards through zero. The
+            // `chassis` path above derives the same feel from mass and gearing, so the two are mutually
+            // exclusive by construction rather than by convention.
+            const coastDeceleration = tuning.coastDeceleration ?? 0;
+            if (chassis === undefined &&
+                coastDeceleration > 0 &&
+                dt > 0 &&
+                axis.throttle <= 0 &&
+                axis.brake <= 0 &&
+                Math.abs(speed) > 1e-4) {
+                accel -= Math.sign(speed) * Math.min(coastDeceleration, Math.abs(speed) / dt);
+            }
             vx += fx * accel * dt;
             vz += fz * accel * dt;
             let forwardSpeed = vx * fx + vz * fz;
@@ -136,7 +185,8 @@ export function createKinematicVehicle(tuning, options = {}) {
             const downforce = 1 + (tuning.dynamics?.downforce ?? 0) * Math.min(1, Math.abs(forwardSpeed) / Math.max(1, topSpeed));
             const gripValue = sampleGripCurve(grip, slip) * surface * handbrakeFactor * downforce;
             const keep = Math.max(0, 1 - gripValue * tuning.gripStrength * dt);
-            const stability = tuning.dynamics?.stabilityControl ?? 0;
+            // ESC fights intentional slides — ease it off while the handbrake is held so drift stays steerable.
+            const stability = (tuning.dynamics?.stabilityControl ?? 0) * (1 - 0.85 * axis.handbrake);
             let keptLateral = lateralSpeed * keep * Math.max(0, 1 - stability * Math.abs(axis.steer) * dt);
             if (chassis !== undefined) {
                 // Friction budget (#1051): total tire force F = μeff * m * g, with μeff = tireGrip * gripValue
@@ -212,6 +262,17 @@ export function createKinematicVehicle(tuning, options = {}) {
             const targetRoll = clampSigned(-yawRate * forwardSpeed * (tuning.dynamics?.bodyRollFactor ?? 0) * comScale, tuning.dynamics?.maxBodyRoll ?? 0.16);
             bodyPitch += (targetPitch - bodyPitch) * attitudeResponse;
             bodyRoll += (targetRoll - bodyRoll) * attitudeResponse;
+            // Hop/air state is a pure vertical offset above the ground plane, deliberately independent of
+            // the planar sim: a hopping vehicle still steers, still slides, and still follows the terrain
+            // underneath it. Without `hopGravity` there is no state to integrate and `airOffset` stays 0.
+            if (hopGravity > 0 && (airOffset > 0 || verticalVelocity > 0)) {
+                verticalVelocity -= hopGravity * dt;
+                airOffset += verticalVelocity * dt;
+                if (airOffset <= 0) {
+                    airOffset = 0;
+                    verticalVelocity = 0;
+                }
+            }
             return {
                 position: [x, y, z],
                 heading,
@@ -229,6 +290,8 @@ export function createKinematicVehicle(tuning, options = {}) {
                 wheelspin,
                 bodyPitch,
                 bodyRoll,
+                airOffset,
+                airborne: airOffset > 0,
             };
         },
         pose: () => ({ position: [x, y, z], heading }),
@@ -237,6 +300,15 @@ export function createKinematicVehicle(tuning, options = {}) {
             vx *= factor;
             vz *= factor;
         },
+        hop(impulse) {
+            if ((tuning.hopGravity ?? 0) <= 0 || airOffset > 0 || verticalVelocity > 0)
+                return false;
+            verticalVelocity = impulse;
+            return true;
+        },
+        retune(next) {
+            tuning = next;
+        },
         resetTo(position, nextHeading) {
             x = position[0];
             y = position[1];
@@ -252,11 +324,28 @@ export function createKinematicVehicle(tuning, options = {}) {
             previousForwardSpeed = 0;
             bodyPitch = 0;
             bodyRoll = 0;
+            airOffset = 0;
+            verticalVelocity = 0;
         },
     };
 }
 /** Gravitational acceleration, m/s², for the chassis friction budget and weight-transfer ratio (#1051). */
 const GRAVITY = 9.81;
+/** Default reverse drive force as a fraction of forward `engineForce` / `engineAccel`. */
+export const DEFAULT_REVERSE_FORCE_SCALE = 0.48;
+/**
+ * Minimum torque-curve factor under throttle near standstill (launch clutch). Fades out by
+ * {@link LAUNCH_TORQUE_FADE_SPEED} so it only fills the weak idle end of the curve.
+ */
+const LAUNCH_TORQUE_FLOOR = 0.9;
+/** Forward speed (world units/s) by which the launch torque floor has fully faded. */
+const LAUNCH_TORQUE_FADE_SPEED = 9;
+/** Minimum |forward speed| before handbrake oversteer yaw kicks in. */
+const HANDBRAKE_OVERSTEER_MIN_SPEED = 2.5;
+/** Speed at which handbrake oversteer reaches full strength. */
+const HANDBRAKE_OVERSTEER_REF_SPEED = 12;
+/** Peak extra yaw rate (rad/s) from full steer + full handbrake at {@link HANDBRAKE_OVERSTEER_REF_SPEED}. */
+const HANDBRAKE_OVERSTEER_YAW = 3.1;
 /**
  * Tyre rolling-resistance coefficient μ_rr (#1051). The always-present coast force is `μ_rr · m · g`
  * (the road-load floor) — a little high vs. a real ~0.013 tyre so a lifted-off car settles to a stop

package/dist/physics/vehicleObstacles.js

@@ -29,6 +29,7 @@ export function createVehicleObstacleClamp(options) {
     // Grow-only scratch of Y-normalised solids, reused across ticks so a sustained crash allocates nothing
     // after warm-up. Per-clamp (closure-local) so concurrent cars never share it.
     const scratch = [];
+    const offsetScratch = [];
     let pending = null;
     function vehicleView(source) {
         const n = source.length;
@@ -43,6 +44,24 @@ export function createVehicleObstacleClamp(options) {
             entry.position[1] = CAR_BODY_MID_Y;
             entry.position[2] = from.position[2];
             entry.halfExtents = from.halfExtents;
+            // Keep the collider's XZ offset (a fitted body centred away from the placement point) but zero
+            // its Y: with the body pinned to CAR_BODY_MID_Y a vertical offset would push the box out of the
+            // stepper's pedestrian-span gate and the car would drive through a tall building's collider.
+            const fromOffset = from.offset;
+            if (fromOffset !== undefined && (fromOffset[0] !== 0 || fromOffset[2] !== 0)) {
+                let flat = offsetScratch[i];
+                if (flat === undefined) {
+                    flat = [0, 0, 0];
+                    offsetScratch[i] = flat;
+                }
+                flat[0] = fromOffset[0];
+                flat[2] = fromOffset[2];
+                entry.offset = flat;
+            }
+            else {
+                entry.offset = undefined;
+            }
+            entry.boxes = from.boxes;
         }
         if (scratch.length > n)
             scratch.length = n;

package/dist/random/resolveRng.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolves an optional injected `[0,1)` generator, falling back to `Math.random` — and says so, once
+ * per call site.
+ *
+ * Every primitive that rolls dice takes an `rng`, but the default was silent: a caller who forgot to
+ * pass `ctx.rng` got a simulation that cannot replay, lockstep, roll back, or be pinned by a test,
+ * with nothing on screen or in the log to say why. The fallback stays (a portable helper called
+ * outside a game context is a real use), but it is now loud instead of invisible.
+ *
+ * @capability resolve-rng resolve an optional injected RNG, warning once per site when it falls back to `Math.random`
+ */
+export declare function resolveRng(provided: (() => number) | undefined, site: string): () => number;
+/** Clears the warned-site memo. Tests only — the warning is once-per-site for the life of the process. */
+export declare function resetRngFallbackWarnings(): void;

package/dist/random/resolveRng.js

@@ -0,0 +1,31 @@
+import { isProductionEnvironment } from "../devtools/saveEndpoint.js";
+const warned = new Set();
+/** Narrow structural view of the ambient console — core never pulls in the DOM lib. */
+function consoleWarn(message) {
+    const host = globalThis;
+    host.console?.warn?.(message);
+}
+/**
+ * Resolves an optional injected `[0,1)` generator, falling back to `Math.random` — and says so, once
+ * per call site.
+ *
+ * Every primitive that rolls dice takes an `rng`, but the default was silent: a caller who forgot to
+ * pass `ctx.rng` got a simulation that cannot replay, lockstep, roll back, or be pinned by a test,
+ * with nothing on screen or in the log to say why. The fallback stays (a portable helper called
+ * outside a game context is a real use), but it is now loud instead of invisible.
+ *
+ * @capability resolve-rng resolve an optional injected RNG, warning once per site when it falls back to `Math.random`
+ */
+export function resolveRng(provided, site) {
+    if (provided !== undefined)
+        return provided;
+    if (!warned.has(site) && !isProductionEnvironment()) {
+        warned.add(site);
+        consoleWarn(`[jgengine:rng] ${site} fell back to Math.random — this run cannot replay, lockstep, roll back, or be pinned by a test. Pass \`ctx.rng\` (the per-world seeded stream), or \`seededRng(seed)\` outside a game context.`);
+    }
+    return Math.random;
+}
+/** Clears the warned-site memo. Tests only — the warning is once-per-site for the life of the process. */
+export function resetRngFallbackWarnings() {
+    warned.clear();
+}

package/dist/render/postProcessing.d.ts

@@ -47,7 +47,13 @@ export interface DofConfig {
     maxBlur?: number;
 }
 /**
- * Declarative post-processing chain (RenderPass → AO → Bloom → tone-map output →
+ * Edge antialiasing for the post chain. SMAA runs in linear-sRGB before the output
+ * tone-map and cleans alpha-tested foliage/particles that MSAA samples alone leave crawling.
+ * `"msaa"` keeps only the render-target multisample resolve; `false` disables AA stages.
+ */
+export type PostAaMode = "smaa" | "msaa" | false;
+/**
+ * Declarative post-processing chain (RenderPass → AO → Bloom → SMAA → tone-map output →
  * Grade). Present on a game means the shell mounts an `EffectComposer` and owns
  * the render; absent means the renderer draws directly (unchanged). Each stage is
  * a config object, `false` to skip, or omitted for its default. Pure data — no
@@ -60,6 +66,11 @@ export interface PostProcessingConfig {
     toneMapping?: ToneMappingMode;
     /** Exposure multiplier applied before tone mapping. Default 1. */
     exposure?: number;
+    /**
+     * Antialiasing. Default `"smaa"` (plus a light MSAA resolve on the beauty target).
+     * Set `"msaa"` to skip the SMAA pass, or `false` for neither.
+     */
+    aa?: PostAaMode;
     bloom?: BloomConfig | false;
     /** Ambient occlusion. Heavier than the other stages — omit or `false` on low-end targets. Default off (omitted). */
     ao?: AoConfig | false;

package/dist/runtime/cameraDirector.d.ts

@@ -1,6 +1,6 @@
 import type { ChaseCameraConfig, CinematicCameraConfig } from "../game/playableGame.js";
-/** Runtime patch over the static `camera.chase` config — distance/height/fov retuning from gameplay events (#286.11). */
-export type ChaseCameraTuning = Partial<Pick<ChaseCameraConfig, "distance" | "height" | "lookHeight" | "springDamping" | "fov" | "lead" | "bank">>;
+/** Runtime patch over the static `camera.chase` config — distance/height/fov retuning from gameplay events (#286.11), or a whole driving-feel overlay (speed→FOV, lead, bank, speed shake, drift-lag) applied only while a vehicle is piloted (#1299). */
+export type ChaseCameraTuning = Partial<Pick<ChaseCameraConfig, "distance" | "height" | "lookHeight" | "springDamping" | "fov" | "lead" | "bank" | "shakePerSpeed" | "velocityYaw" | "yawResponse">>;
 export interface CameraDirector {
     follow(entityId: string | null): void;
     /** `undefined` means no runtime override — the shell falls back to the static `playable.camera.followEntityId`. `null` means explicitly follow nothing. */

package/dist/runtime/context/combat.js

@@ -34,6 +34,13 @@ export function createCombatSubsystem(d) {
         statPools: createEntityStatsApi((instanceId) => statsByInstance.get(instanceId)),
         getStat: weapon.getStat,
         spatial: combatSpatial,
+        resolveSlainIdentity(instanceId) {
+            const entity = entities.get(instanceId);
+            if (entity === null)
+                return null;
+            // `entity.name` is the spawn kind/catalog id, matching the `entity.died` event.
+            return { catalogId: entity.name, name: entity.name };
+        },
         onLethal(instanceId, lethalCtx) {
             // Capture identity + onDeath *before* resolveDeath despawns the entity.
             const dyingEntity = entities.get(instanceId);
@@ -117,6 +124,7 @@ export function createCombatSubsystem(d) {
                 at: [report.at[0], report.at[1], report.at[2]],
                 effect: report.effect,
                 hit: report.hit,
+                ballistic: report.ballistic,
             });
         },
     }), ["fireProjectile", "settleProjectile"], signalNotify);

package/dist/runtime/gameContext.js

@@ -19,6 +19,7 @@ import { createRuntimeSave } from "./runtimeSave.js";
 import { isOffline } from "./adapter.js";
 import { localSaveBackend, memorySaveBackend } from "../game/saveStore.js";
 import { createSimClock } from "../time/simClock.js";
+import { seededRng } from "../random/rng.js";
 import { createCameraDirector } from "./cameraDirector.js";
 import { createInputSnapshot } from "./inputSnapshot.js";
 import { baselineDescriptors } from "./descriptors/baseline.js";
@@ -32,6 +33,9 @@ export function createGameContext(options) {
     const { definition, content, player } = options;
     const now = options.now ?? Date.now;
     const occluder = options.occluder;
+    // Per-world deterministic stream — never Math.random on simulation paths (#1545).
+    const rng = options.rng ??
+        seededRng(options.seed ?? `jg:${definition.name.trim().length > 0 ? definition.name : "game"}`);
     const signal = createChangeSignal();
     let actingUserId = null;
     const activeUserId = () => actingUserId ?? player.userId;
@@ -60,7 +64,7 @@ export function createGameContext(options) {
     // --- Shared game services (weapon, feed, features bag, commands, item use) ---
     const weapon = createWeaponStats((itemId) => content.itemById?.(itemId));
     const feed = createGameFeed(definition.feed);
-    const lootRegistry = createLootRegistry();
+    const lootRegistry = createLootRegistry({ rng });
     /**
      * Single feature-activation path (G9): `definition.features` is already the final map after
      * `defineGame` OR-merged explicit boolean sugar (`features: { quest: true }`) with system-implied
@@ -322,6 +326,7 @@ export function createGameContext(options) {
     }
     // --- Assemble public GameContext ---
     const ctx = {
+        rng,
         scene: {
             object: sceneObjects,
             entity: {

package/dist/runtime/gameContextTypes.d.ts

@@ -107,6 +107,16 @@ export interface GameContextOptions<TAssetRef extends ModelAssetRef = ModelAsset
     };
     now?: () => number;
     occluder?: (from: EntityPosition, to: EntityPosition) => boolean;
+    /**
+     * Seed for {@link GameContext.rng}. Defaults to the game name so two contexts of the same
+     * definition share a stream unless a host passes a unique seed per world/session.
+     */
+    seed?: string | number;
+    /**
+     * Injected `[0,1)` generator for this world. Defaults to a {@link seededRng} from {@link seed}.
+     * Never use `Math.random` on simulation paths — pass `ctx.rng` into pure helpers instead.
+     */
+    rng?: () => number;
     /** Bind `ctx.game.save` to a pluggable backend (offline/single-player whole-world save). The shell resolves this from `defineGame({ save })`; multiplayer leaves it off (the host persists). */
     save?: RuntimeSaveOptions;
     /**
@@ -414,6 +424,14 @@ export interface GameContext {
         raycastAll(input: SceneRaycastInput): readonly SceneRaycastHit[];
     };
     world: GameContextWorld;
+    /**
+     * Deterministic `[0,1)` stream for this world — loot, AI, combat rolls, and any sim path that
+     * needs randomness. Same seed → same sequence. Never fall back to `Math.random` in systems;
+     * pass this into pure helpers (`rollCheck`, `autoTarget`, loot tables, …).
+     *
+     * @capability game-context-rng per-world seeded randomness for replay, lockstep, and multi-world hosts
+     */
+    rng: () => number;
     game: {
         commands: GameContextCommands;
         events: GameEvents;

package/dist/runtime/inputSnapshot.d.ts

@@ -4,12 +4,16 @@ import { type AxisBinding, type AxisRange } from "../input/axisInput.js";
 export interface InputFrame {
     held: readonly string[];
     pointer: PointerAxisState | null;
+    /** Analog per-action magnitudes (0..1) for actions driven by a continuous source (virtual joystick, gamepad stick); absent/null means every held action is fully pressed. */
+    analog?: Readonly<Record<string, number>> | null;
 }
 export interface InputSnapshot {
     /** Replaces the held-action set for this frame, rolling the previous held set forward for edge detection (#671). Called by the shell before `onTick` each frame; does not bump `ctx.version()` or notify `ctx.subscribe` listeners — per-frame publishes would storm subscribers. */
     publish(held: readonly string[]): void;
     /** Replaces the normalized pointer-position state for this frame (#293). Same no-notify contract as `publish`. */
     publishPointer(state: PointerAxisState | null): void;
+    /** Replaces the analog per-action magnitudes for this frame (#1370) — the virtual joystick's continuous vector, split into 0..1 values per movement action. `null` clears back to digital-only. Same no-notify contract as `publish`. */
+    publishAnalog(values: Readonly<Record<string, number>> | null): void;
     isDown(action: string): boolean;
     /** The held-action set for this frame — an owned, frozen array; the array {@link publish} was called with is never aliased or returned. */
     held(): readonly string[];
@@ -17,13 +21,18 @@ export interface InputSnapshot {
     justPressed(action: string): boolean;
     /** True only on the frame `action` transitions from down to up (#671); mirrors {@link justPressed}. */
     justReleased(action: string): boolean;
+    /** This frame's magnitude for `action`: its published analog value when one exists, else 1 while held / 0 while up. What `axis()` samples per code, so an analog stick steers proportionally where a key is all-or-nothing. */
+    value(action: string): number;
+    /** The published analog map for this frame, `null` when input is digital-only — an owned, frozen copy. */
+    analog(): Readonly<Record<string, number>> | null;
     /** Pointer position over the play surface, `[-1, 1]` per axis with `+y` down, published by the shell each frame; `null` until the first pointer move. Frozen — an owned copy of what {@link publishPointer} was called with. */
     pointer(): Readonly<PointerAxisState> | null;
     /**
      * Instantaneous analog axis sample against the held-action set and current pointer (#533.7) — bind
      * throttle/steer/handbrake (or any axes) to *action names*, not raw key codes, since the held set is
      * semantic actions. Feed the result into an `AxisChannel` for smoothing; unlisted ranges default to
-     * bipolar `[-1, 1]`, so pass `{ min: 0, max: 1 }` for one-directional pedals.
+     * bipolar `[-1, 1]`, so pass `{ min: 0, max: 1 }` for one-directional pedals. Actions with a published
+     * analog magnitude contribute that value instead of 0/1, so a virtual joystick steers proportionally.
      */
     axis<TAxes extends string>(bindings: Record<TAxes, AxisBinding>, ranges?: Partial<Record<TAxes, AxisRange>>): Record<TAxes, number>;
 }

package/dist/runtime/inputSnapshot.js

@@ -4,6 +4,13 @@ export function createInputSnapshot() {
     let previousHeldSet = new Set();
     let heldList = [];
     let pointerState = null;
+    let analogValues = null;
+    const value = (action) => {
+        const analog = analogValues?.[action];
+        if (analog !== undefined)
+            return analog;
+        return heldSet.has(action) ? 1 : 0;
+    };
     return {
         publish(held) {
             previousHeldSet = heldSet;
@@ -13,10 +20,15 @@ export function createInputSnapshot() {
         publishPointer(state) {
             pointerState = state === null ? null : Object.freeze({ ...state });
         },
+        publishAnalog(values) {
+            analogValues = values === null ? null : Object.freeze({ ...values });
+        },
         isDown: (action) => heldSet.has(action),
         held: () => heldList,
         pointer: () => pointerState,
-        axis: (bindings, ranges) => sampleAxisBindings(bindings, (action) => heldSet.has(action), pointerState, ranges),
+        value,
+        analog: () => analogValues,
+        axis: (bindings, ranges) => sampleAxisBindings(bindings, (action) => heldSet.has(action), pointerState, ranges, value),
         justPressed: (action) => heldSet.has(action) && !previousHeldSet.has(action),
         justReleased: (action) => !heldSet.has(action) && previousHeldSet.has(action),
     };

package/dist/runtime/runtimeSave.d.ts

@@ -12,7 +12,7 @@ export interface RuntimeSaveTarget {
     hydrate(snapshot: WorldSnapshot): void;
     subscribe(listener: () => void): () => void;
 }
-/** `"autosave"` writes a fresh capture on a debounce after any world change; `"manual"` writes only on an explicit `save()`/`checkpoint()` — the save-point / quest-trigger model. */
+/** `"autosave"` writes a fresh capture on a trailing timer while the world changes (at most once per `autosaveMs`, so a never-idle world still persists); `"manual"` writes only on an explicit `save()`/`checkpoint()` — the save-point / quest-trigger model. */
 export type RuntimeSaveMode = "autosave" | "manual";
 /** How {@link createRuntimeSave} is wired — the live world `target`, the `backend` it persists through, and optional mode/slot/versioning/cadence knobs. */
 export interface RuntimeSaveConfig {
@@ -29,7 +29,7 @@ export interface RuntimeSaveConfig {
     /** Save-format version; bump + pass {@link migrate} on a breaking world-shape change. */
     version?: number;
     migrate?: (data: unknown, fromVersion: number) => WorldSnapshot;
-    /** Debounce for `autosave` mode. Default `3000`. */
+    /** Trailing autosave interval (ms) for `autosave` mode — the world persists at most once per interval and always within one interval of its first unsaved change. Default `3000`. */
     autosaveMs?: number;
     now?: () => number;
     timers?: SaveTimers;
@@ -41,7 +41,7 @@ export type RuntimeSaveOptions = Omit<RuntimeSaveConfig, "target">;
  * Whole-world save/load bound to a live world and a pluggable backend. `save()`
  * captures `target.snapshot()` and writes it; `load()` reads it back and
  * `target.hydrate()`s the whole world. In `autosave` mode it also writes on a
- * debounce after any change. Named slots, versioned migration, and offline↔cloud
+ * trailing timer while the world keeps changing. Named slots, versioned migration, and offline↔cloud
  * (backend swap) all come for free from the underlying save store.
  */
 export interface RuntimeSave {

package/dist/runtime/runtimeSave.js

@@ -51,10 +51,19 @@ export function createRuntimeSave(config) {
         store.set(config.target.snapshot());
         return store.save();
     }
+    /**
+     * Arm a trailing autosave. A living world (AI, physics, the day/night clock)
+     * changes every frame, so a debounce that *reset* its timer on every change
+     * would never elapse and the game would never persist — the timer would be
+     * pushed forward faster than it could fire. Instead the first change since the
+     * last write arms a single timer and later changes ride that same timer; when
+     * it fires it captures the latest snapshot. The result is at most one write per
+     * `autosaveMs`, and always within `autosaveMs` of the first unsaved change,
+     * even while the world never stops moving.
+     */
     function scheduleAutosave() {
-        if (disposed || restoring)
+        if (disposed || restoring || pendingTimer !== null)
             return;
-        clearTimer();
         pendingTimer = timers.set(() => {
             pendingTimer = null;
             void persist();

package/dist/scene/assetDiagnostics.js

@@ -92,11 +92,11 @@ export function classifyAssetResponse(probe) {
     });
     if (status !== undefined && (status === 0 || status >= 400)) {
         const suffix = statusText === undefined || statusText.length === 0 ? "" : ` ${statusText}`;
-        return finish("missing", `Asset ${who} did not load: HTTP ${status}${suffix}. The file is not being served — provision the pack (e.g. \`assets pull <source>\`) or check the model path.`);
+        return finish("missing", `Asset ${who} did not load: HTTP ${status}${suffix}. The bytes are not being served at that path — run \`assets pull <source>\`, which provisions the pack into the dev server's served models dir (\`apps/dev/public/models\` in the jgengine monorepo) so no manual copy is needed; or check the model path.`);
     }
     const htmlContentType = contentType !== undefined && contentType.toLowerCase().includes("text/html");
     if (signature === "html" || (htmlContentType && signature !== "glb" && signature !== "gltf-json")) {
-        return finish("html", `Asset ${who} resolved to an HTML page, not a model — the dev server returned its fallback document because the file is missing. Provision the pack (\`assets pull <source>\`) so the bytes exist under the served path.`);
+        return finish("html", `Asset ${who} resolved to an HTML page, not a model — the dev server returned its fallback document because the file is missing. Run \`assets pull <source>\` to provision the pack into the served models dir (\`apps/dev/public/models\` in the jgengine monorepo); the bytes must exist there, no manual copy needed.`);
     }
     if (signature === "glb" || signature === "gltf-json")
         return finish("ok", `Asset ${who} loaded (${signature}).`);

package/dist/scene/autoTarget.js

@@ -1,3 +1,4 @@
+import { resolveRng } from "../random/resolveRng.js";
 function metric(policy, fromId, toId, deps) {
     switch (policy) {
         case "nearest":
@@ -21,7 +22,7 @@ export function selectAutoTarget(policy, fromId, deps) {
     if (candidates.length === 0)
         return null;
     if (policy === "random") {
-        const rng = deps.rng ?? Math.random;
+        const rng = resolveRng(deps.rng, "autoTarget");
         return candidates[Math.min(candidates.length - 1, Math.floor(rng() * candidates.length))];
     }
     const higher = prefersHigher(policy);

package/dist/scene/captureCheck.js

@@ -1,3 +1,4 @@
+import { resolveRng } from "../random/resolveRng.js";
 function clamp01(value) {
     return Math.min(1, Math.max(0, value));
 }
@@ -6,6 +7,6 @@ export function captureChance(input) {
     const hpFactor = 1 - clamp01(input.hpFraction) * 0.6;
     return clamp01((input.catchPower * hpFactor) / Math.max(difficulty, 0.0001));
 }
-export function rollCapture(input, rng = Math.random) {
-    return rng() < captureChance(input);
+export function rollCapture(input, rng) {
+    return resolveRng(rng, "rollCapture")() < captureChance(input);
 }

package/dist/scene/entityStore.d.ts

@@ -22,6 +22,8 @@ export interface SceneEntity<TMeta = unknown> {
     role: EntityRole;
     movement: EntityMovement;
     behaviors: readonly BehaviorDescriptor[];
+    /** Render-only visibility: `true` skips the entity's visual entirely (seated vehicle riders, cutscene actors, stealth cloaks) while the entity keeps simulating — position, stats, AI targeting, and queries are untouched. Absent/`false` renders normally. */
+    hidden?: boolean;
     /** Game-defined per-instance data set at `spawn`/`update` and carried to `renderEntity`/queries — narrow with {@link entityMetaOf} (or a type guard) on read (#286.1); never encode state in the id/name string. */
     meta: TMeta;
 }
@@ -44,6 +46,7 @@ export interface SpawnOptions<TMeta = unknown> {
     role?: EntityRole;
     movement?: EntityMovement;
     behaviors?: readonly BehaviorDescriptor[];
+    hidden?: boolean;
     meta?: TMeta;
     /** When `id` is already spawned: `"throw"` (default), `"replace"` (fresh spawn over it — remount-safe world setup, #284.10), or `"keep"` (leave it untouched and return the id). */
     onExisting?: "throw" | "replace" | "keep";
@@ -68,7 +71,7 @@ export interface PoseConstraintFrame {
 }
 /** Return a replacement position to constrain the step, or nothing to accept it. */
 export type PoseConstraint = (frame: PoseConstraintFrame) => readonly [number, number, number] | undefined | void;
-export type EntityUpdatePatch<TMeta = unknown> = Partial<Pick<SceneEntity<TMeta>, "name" | "rotationY" | "rotationX" | "rotationZ" | "role" | "movement" | "behaviors" | "meta">> & {
+export type EntityUpdatePatch<TMeta = unknown> = Partial<Pick<SceneEntity<TMeta>, "name" | "rotationY" | "rotationX" | "rotationZ" | "role" | "movement" | "behaviors" | "hidden" | "meta">> & {
     /** Accepts the same friendly shapes as `spawn`/`setPose` (#286.13). Raw patch semantics — velocity is not derived; use `setPose` with `dt` for that. */
     position?: SpawnPositionInput;
 };

package/dist/scene/entityStore.js

@@ -91,6 +91,7 @@ export function createEntityStore() {
                 role: options.role ?? "prop",
                 movement: options.movement ?? {},
                 behaviors: options.behaviors ?? [],
+                ...(options.hidden === undefined ? {} : { hidden: options.hidden }),
                 meta: options.meta,
             });
             spawnPoses.set(id, { position, rotationY });
@@ -124,6 +125,8 @@ export function createEntityStore() {
                 current.movement = patch.movement;
             if (patch.behaviors !== undefined)
                 current.behaviors = patch.behaviors;
+            if (patch.hidden !== undefined)
+                current.hidden = patch.hidden;
             if (patch.meta !== undefined)
                 current.meta = patch.meta;
             store.set(id, current);