@jgengine/core 0.13.0 → 0.15.0-next.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/context/scene.d.ts

@@ -5,6 +5,7 @@ import { type EntityStatsApi, type StatValueMap } from "../../scene/entityStats.
 import { type EntityPosition, type EntityStore, type SceneEntity, type SpawnOptions } from "../../scene/entityStore.js";
 import { type Forms } from "../../scene/form.js";
 import { type EntityColliderSet, type MeasuredBounds } from "../../scene/colliders.js";
+import { type CollisionMeshSource } from "../../scene/collisionMesh.js";
 import { type ObjectStore } from "../../scene/objectStore.js";
 import { type PaintLayer } from "../../scene/paintLayer.js";
 import { type SceneRaycastApi } from "../../scene/sceneRaycast.js";
@@ -42,6 +43,7 @@ export interface SceneSubsystem {
     entityCollidersOf: (instanceId: string) => EntityColliderSet | null;
     objectCollidersOf: (instanceId: string) => EntityColliderSet | null;
     reportEntityBounds: (kind: string, bounds: MeasuredBounds | null) => boolean;
+    reportEntityCollisionMesh: (kind: string, mesh: CollisionMeshSource | null) => boolean;
     entityVisualScaleOf: (instanceId: string) => number;
     forms: Forms;
     paintLayer: PaintLayer;

package/dist/runtime/context/scene.js

@@ -2,7 +2,8 @@ import { createBodyBind } from "../../scene/bodyBind.js";
 import { createEntityStatsApi, seedStatValues, } from "../../scene/entityStats.js";
 import { createEntityStore, } from "../../scene/entityStore.js";
 import { createForms } from "../../scene/form.js";
-import { fittedEntityColliders, fittedObjectColliders, measuredEntityColliders, measuredObjectColliders, scaledEntityColliders, scaledObjectColliders, } from "../../scene/colliders.js";
+import { fittedEntityColliders, fittedObjectColliders, hasMeshColliderShape, measuredEntityColliders, measuredObjectColliders, meshEntityColliders, meshObjectColliders, scaledEntityColliders, scaledObjectColliders, } from "../../scene/colliders.js";
+import { prepareCollisionMeshSource } from "../../scene/collisionMesh.js";
 import { raycastObjects, raycastObjectsAll } from "../../scene/objectQuery.js";
 import { createObjectStore, objectVisualScale } from "../../scene/objectStore.js";
 import { createPaintLayer } from "../../scene/paintLayer.js";
@@ -98,6 +99,38 @@ export function createSceneSubsystem(d) {
         signalNotify();
         return true;
     }
+    const meshEntityByKind = new Map();
+    const meshObjectByCatalogId = new Map();
+    function reportEntityCollisionMesh(kind, mesh) {
+        if (mesh === null) {
+            const existed = meshEntityByKind.delete(kind);
+            if (existed)
+                signalNotify();
+            return existed;
+        }
+        const prepared = prepareCollisionMeshSource(mesh);
+        const set = prepared === null ? null : meshEntityColliders(prepared);
+        if (set === null)
+            return false;
+        meshEntityByKind.set(kind, set);
+        signalNotify();
+        return true;
+    }
+    function reportObjectCollisionMesh(catalogId, mesh) {
+        if (mesh === null) {
+            const existed = meshObjectByCatalogId.delete(catalogId);
+            if (existed)
+                signalNotify();
+            return existed;
+        }
+        const prepared = prepareCollisionMeshSource(mesh);
+        const set = prepared === null ? null : meshObjectColliders(prepared);
+        if (set === null)
+            return false;
+        meshObjectByCatalogId.set(catalogId, set);
+        signalNotify();
+        return true;
+    }
     function reportObjectBounds(catalogId, bounds) {
         if (bounds === null) {
             const existed = measuredObjectByCatalogId.delete(catalogId);
@@ -122,6 +155,13 @@ export function createSceneSubsystem(d) {
         const kind = entities.get(instanceId)?.name;
         if (kind !== undefined) {
             const fitted = fittedEntitySetFor(kind);
+            // Index-derived mesh shapes win (identical on a headless host); otherwise a runtime-reported
+            // collision mesh upgrades the fitted/measured bounding box to the rendered triangles.
+            if (fitted !== null && hasMeshColliderShape(fitted))
+                return fitted;
+            const runtimeMesh = meshEntityByKind.get(kind);
+            if (runtimeMesh !== undefined)
+                return runtimeMesh;
             if (fitted !== null)
                 return fitted;
             const measured = measuredEntityByKind.get(kind);
@@ -149,6 +189,11 @@ export function createSceneSubsystem(d) {
         if (object === null)
             return null;
         const fitted = fittedObjectSetFor(object.catalogId);
+        if (fitted !== null && hasMeshColliderShape(fitted))
+            return fitted;
+        const runtimeMesh = meshObjectByCatalogId.get(object.catalogId);
+        if (runtimeMesh !== undefined)
+            return runtimeMesh;
         if (fitted !== null)
             return fitted;
         const measured = measuredObjectByCatalogId.get(object.catalogId);
@@ -291,6 +336,7 @@ export function createSceneSubsystem(d) {
         },
         collidersOf: objectCollidersOf,
         reportBounds: reportObjectBounds,
+        reportCollisionMesh: reportObjectCollisionMesh,
         selection: objectSelection,
     };
     return {
@@ -310,6 +356,7 @@ export function createSceneSubsystem(d) {
         entityCollidersOf,
         objectCollidersOf,
         reportEntityBounds,
+        reportEntityCollisionMesh,
         entityVisualScaleOf,
         forms,
         paintLayer,

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;
@@ -56,11 +60,11 @@ export function createGameContext(options) {
         ...(occluder !== undefined ? { occluder } : {}),
         ...(options.models !== undefined ? { models: options.models } : {}),
     });
-    const { entities, objects, statsByInstance, entityStats, ensureInstanceStats, catalogEntry, spatial, combatSpatial, sceneRaycast, targeting, entityColliders, entityCollidersOf, objectCollidersOf, reportEntityBounds, entityVisualScaleOf, forms, paintLayer, spawnEntity, despawnEntity, moveEntityTowardCommit, resetAllToSpawn, bind, sceneObjects, } = scene;
+    const { entities, objects, statsByInstance, entityStats, ensureInstanceStats, catalogEntry, spatial, combatSpatial, sceneRaycast, targeting, entityColliders, entityCollidersOf, objectCollidersOf, reportEntityBounds, reportEntityCollisionMesh, entityVisualScaleOf, forms, paintLayer, spawnEntity, despawnEntity, moveEntityTowardCommit, resetAllToSpawn, bind, sceneObjects, } = scene;
     // --- 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: {
@@ -369,6 +374,7 @@ export function createGameContext(options) {
                 },
                 collidersOf: entityCollidersOf,
                 reportBounds: reportEntityBounds,
+                reportCollisionMesh: reportEntityCollisionMesh,
                 visualScaleOf: entityVisualScaleOf,
                 form: forms,
                 paint: paintLayer,

package/dist/runtime/gameContextTypes.d.ts

@@ -35,6 +35,7 @@ import type { EntityStatsApi, StatCatalog } from "../scene/entityStats.js";
 import type { EntityBlackboard, EntityPose, EntityPosition, EntityStore, SceneEntity, SpawnOptions, SpawnPose } from "../scene/entityStore.js";
 import type { Forms } from "../scene/form.js";
 import type { EntityColliderSet, MeasuredBounds, ModelBodySource } from "../scene/colliders.js";
+import type { CollisionMeshSource } from "../scene/collisionMesh.js";
 import type { ObjectRaycastHit, ObjectRaycastInput } from "../scene/objectQuery.js";
 import type { ObjectStore } from "../scene/objectStore.js";
 import type { Roster } from "../scene/roster.js";
@@ -106,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;
     /**
@@ -145,6 +156,15 @@ export interface SceneObjectContext extends ObjectStore {
      * @capability measured-colliders hitboxes and blocking bodies wrap what the renderer actually mounted — custom render props and dims-less models stop falling back to fixed-size boxes.
      */
     reportBounds(catalogId: string, bounds: MeasuredBounds | null): boolean;
+    /**
+     * Report the entity-local triangle soup the renderer actually mounted for `catalogId` — stored per
+     * catalog id as a blocking physical body whose raycasts hit the real surface (a BVH over the
+     * triangles) while movement obstruction keeps the conservative AABB. Consulted right after
+     * authored `colliders` / index collision meshes and before the fitted-box, measured-bounds, and
+     * visual-scale fallbacks. The shell reports rendered models automatically. Pass `null` to clear.
+     * Returns `false` when no valid triangle survives.
+     */
+    reportCollisionMesh(catalogId: string, mesh: CollisionMeshSource | null): boolean;
     /**
      * Per-instance selection/highlight state for placed objects — the reactive counterpart to
      * `worldHealthBars`/`nameplates` (entities), so a build-mode or RTS selection ring reads
@@ -275,6 +295,17 @@ export interface SceneEntityContext {
      * @capability measured-hitboxes an entity rendered with a custom mesh takes hits in a box matching its rendered bounds, not the fixed humanoid rectangle.
      */
     reportBounds(kind: string, bounds: MeasuredBounds | null): boolean;
+    /**
+     * Report the entity-local triangle soup the renderer actually mounted for `kind` — stored per kind
+     * as a damage hitbox that raycasts the model's own triangles (BVH), so shots aimed between a
+     * character's feet or past its shoulder miss instead of hitting a bounding box. Consulted right
+     * after authored `colliders` / index collision meshes and before the fitted-box and
+     * measured-bounds fallbacks. The shell reports rendered models automatically; authoritative hosts
+     * that never render should author `colliders` or index collision meshes for identical results.
+     * Pass `null` to clear. Returns `false` when no valid triangle survives.
+     * @capability conforming-hitboxes shots aimed between a character's feet or past its shoulder MISS — damage raycasts hit the rendered model's triangles, not its bounding box.
+     */
+    reportCollisionMesh(kind: string, mesh: CollisionMeshSource | null): boolean;
     /** Uniform visual scale from the entity's catalog entry (1 when unscaled). */
     visualScaleOf(instanceId: string): number;
     form: Forms;
@@ -393,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),
     };