@jgengine/core 0.33.0 → 0.35.0

package/CHANGELOG.md

@@ -26,6 +26,44 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.35.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.35.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.32.0`; `@jgengine/github` is `0.22.0`.
+
+### Added
+
+- `ModelLodConfig.crowdCapacity` declares how many characters of one model a batch draws (default 128). A character past the cap keeps its own rig at its distance tier instead of disappearing.
+- `ModelLodConfig.crowdDistance` accepts `0`, which batches a character at every distance instead of only past 25 m. A game with a near crowd or a close-quarters army sets it to batch members in front of the camera too.
+- `characterRigTier` (`@jgengine/shell/render/characterLod`) resolves the distance tier a character poses its own rig on, which is the fallback for an over-cap crowd.
+- `audio.zones` (`@jgengine/core/game/playableGame`): a scene declares world-space ambience zones, one looping bed per zone. The shell crossfades bed levels from the listener position on each sound's own bus, so entering, leaving and walking between zones hand over instead of cutting.
+- `audio.occlusion` (`@jgengine/core/audio/occlusion`): budgeted geometry occlusion for retained positional loops. A blocked line attenuates the loop and darkens it through a low-pass; the per-tick test budget and interval bound the cost, and a loop that cannot be tested stays on distance-only.
+- `SoundDef.duck`: a cue can lower named buses for its own duration. `AudioEngine.duck` returns a release, and the player's own gain is restored exactly even when they move the slider mid-duck.
+- `AudioEngine.ambience()`, `AudioEngine.occlusionStats()` and `window.__jgengineAudio` report the zone mix, the newest occlusion test and the measured per-test cost for capture and diagnostics.
+
+### Changed
+
+- The character batch path now covers every drawable character model, not only skinned locomotion rigs: a node-transform character (rotating limbs, no skin) rides the node a clip moves, and a model with no clips at all batches as a static geometry. Both still bake to one geometry per material, so a crowd draws once per model and material.
+- Batched characters are pickable: the batch carries the entity ids of the instances it drew, so `worldHit().entity` and a click on a batched character resolve to the character instead of falling through to the ground.
+
+### Fixed
+
+- Load-time shader warmup compiles what the first frame can reach, reveals as soon as those programs are linked, and finishes the rest in background rounds, so a scene no longer holds the loading cover for its whole model stream and no longer drops a compile onto a frame that is already showing. The loading cover names the shader count, the seconds waited and the work left for the background.
+- A crowd batch silently dropped members past its fixed 128 instances while their markers still hid them, so a full scene lost characters. Members past the declared capacity now keep their own rigs.
+- A crowd batch's clock now follows the game clock when one is bound, so a paused game no longer keeps its crowd walking.
+
+## 0.34.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.34.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.31.0`; `@jgengine/github` is `0.21.0`.
+
+### Added
+
+- `PaceBand` on `DriverGoal` (`paceBand` + caller-measured `paceGap`) gives catch-up pacing an owner in `@jgengine/core/ai/driver`: a dead zone around `margin` (`tolerance`), `ease` shedding pace for a car ahead over `easeAt`, `push` adding it for a car behind over `pushAt`, and `scale` as the per-car share. `paceBandFactor(band, gap)` exposes the rule on its own. Deterministic scalar math, no allocation per step; the push never outdrives `DriverTuning.maxSpeed`. First adopter: Drift Foundry's rival field, which deletes its own `paceBand`; second: Harbor Heat's interceptors.
+- `createRunLoop` (`@jgengine/core/run/runLoop`) holds a run's at-risk haul, banks it scaled by the line or loses it on a failure, and draws one authored change for each next run from a seeded table, so the same seed and run history replay the same sequence. State round-trips through `snapshot`/`restore`; the money stays in `progression/careerBank`.
+
 ## 0.33.0
 
 ### Migrate

package/dist/ai/driver.d.ts

@@ -28,7 +28,44 @@ export interface DriverGoal {
     stopAtGoal?: boolean;
     /** Cap on desired speed for this goal (a speed limit, a formation speed); default unlimited. */
     speedLimit?: number;
+    /**
+     * This car's catch-up pacing band, applied to the goal's pace. The caller measures {@link paceGap}
+     * (it owns the spatial query) and tunes the band; {@link paceBandFactor} is the rule.
+     */
+    paceBand?: PaceBand;
+    /** Signed gap to the band's reference: positive when this car is ahead of it; default `0`. */
+    paceGap?: number;
 }
+/**
+ * Catch-up pacing for one car in a field: the gap it tries to hold to a reference car (a rival, the
+ * player, a convoy lead) and how its pace bends when it drifts off that gap. Past `margin` by
+ * `tolerance` it sheds up to `ease` of its pace; short of it by `tolerance` it gains up to `push`;
+ * inside that tolerance it leaves the car alone. The push never outdrives `DriverTuning.maxSpeed`,
+ * so a band changes how hard a car tries, never what it is built to do.
+ */
+export interface PaceBand {
+    /** Gap to the reference this car aims to hold, world units; default `0` (level with it). */
+    margin?: number;
+    /** Gap error either side of `margin` the car leaves alone; default `0`. */
+    tolerance?: number;
+    /** Gap error past `tolerance` where the ease reaches full strength; default `0` (at once). */
+    easeAt?: number;
+    /** Fraction of the goal's pace shed at full ease; default `0`. */
+    ease?: number;
+    /** Gap error past `tolerance` where the push reaches full strength; default `0` (at once). */
+    pushAt?: number;
+    /** Fraction of the goal's pace added at full push; default `0`. */
+    push?: number;
+    /** Share of the band this car accepts, `0..1`; default `1`. */
+    scale?: number;
+}
+/**
+ * The pace multiplier a {@link PaceBand} asks for at `gap`: `1` inside the tolerance, `1 - ease *
+ * scale` fully ahead of it, `1 + push * scale` fully behind it, ramped linearly across `easeAt` /
+ * `pushAt` in between. Pure scalar math, so a band is deterministic and costs no allocation per
+ * step; the result never goes negative.
+ */
+export declare function paceBandFactor(band: PaceBand, gap: number): number;
 /** Vehicle-feel numbers the game supplies; everything has a sensible default except `maxSpeed`. */
 export interface DriverTuning {
     /** Top desired speed on a straight, world units/second. */
@@ -86,8 +123,10 @@ export interface DriverStep extends AxisInput {
  * `speed * reactionSeconds`, so easy tiers brake at the last moment and expert tiers with proper
  * margin. The steering target is a delay-line over the goal — resampled every `reactionSeconds`,
  * so it trails a moving goal by up to that long, which is what makes an easy chaser visibly cut
- * toward where the target *was*. When throttle produces no motion for a tier-scaled while the
- * driver reverses out with counter-steer (brake past standstill — the shared sim's reverse).
+ * toward where the target *was*. A {@link PaceBand} on the goal eases a car ahead of its margin and
+ * pushes one behind it, bounded by the car's own top speed. When throttle produces no motion for a
+ * tier-scaled while the driver reverses out with counter-steer (brake past standstill — the shared
+ * sim's reverse).
  *
  * @capability ai-driver difficulty-aware chase/route driving step producing throttle/brake/steer for the vehicle sim
  */

package/dist/ai/driver.js

@@ -1,4 +1,30 @@
 import { executionError } from "./difficulty.js";
+/**
+ * The pace multiplier a {@link PaceBand} asks for at `gap`: `1` inside the tolerance, `1 - ease *
+ * scale` fully ahead of it, `1 + push * scale` fully behind it, ramped linearly across `easeAt` /
+ * `pushAt` in between. Pure scalar math, so a band is deterministic and costs no allocation per
+ * step; the result never goes negative.
+ */
+export function paceBandFactor(band, gap) {
+    const scale = band.scale ?? 1;
+    if (scale <= 0)
+        return 1;
+    const error = gap - (band.margin ?? 0);
+    const tolerance = band.tolerance ?? 0;
+    if (error > tolerance) {
+        const ease = band.ease ?? 0;
+        if (ease <= 0)
+            return 1;
+        return Math.max(0, 1 - ease * scale * Math.min(1, (error - tolerance) / (band.easeAt ?? 0)));
+    }
+    if (error < -tolerance) {
+        const push = band.push ?? 0;
+        if (push <= 0)
+            return 1;
+        return Math.max(0, 1 + push * scale * Math.min(1, (-error - tolerance) / (band.pushAt ?? 0)));
+    }
+    return 1;
+}
 /**
  * Fresh driver state committed to an initial target (usually the spawn-time goal or the spawn
  * position itself).
@@ -32,8 +58,10 @@ const clamp01 = (value) => (value < 0 ? 0 : value > 1 ? 1 : value);
  * `speed * reactionSeconds`, so easy tiers brake at the last moment and expert tiers with proper
  * margin. The steering target is a delay-line over the goal — resampled every `reactionSeconds`,
  * so it trails a moving goal by up to that long, which is what makes an easy chaser visibly cut
- * toward where the target *was*. When throttle produces no motion for a tier-scaled while the
- * driver reverses out with counter-steer (brake past standstill — the shared sim's reverse).
+ * toward where the target *was*. A {@link PaceBand} on the goal eases a car ahead of its margin and
+ * pushes one behind it, bounded by the car's own top speed. When throttle produces no motion for a
+ * tier-scaled while the driver reverses out with counter-steer (brake past standstill — the shared
+ * sim's reverse).
  *
  * @capability ai-driver difficulty-aware chase/route driving step producing throttle/brake/steer for the vehicle sim
  */
@@ -75,6 +103,9 @@ export function driveStep(state, dt, pose, goal, profile, tuning, rng, obstacleA
     const cornerSlowdown = tuning.cornerSlowdown ?? 0.75;
     const cornerFactor = 1 - cornerSlowdown * Math.min(1, Math.abs(headingError) / (Math.PI / 2));
     let desiredSpeed = Math.min(tuning.maxSpeed, goal.speedLimit ?? Number.POSITIVE_INFINITY);
+    if (goal.paceBand !== undefined) {
+        desiredSpeed = Math.min(tuning.maxSpeed, desiredSpeed * paceBandFactor(goal.paceBand, goal.paceGap ?? 0));
+    }
     desiredSpeed *= cornerFactor;
     if (goal.stopAtGoal === true) {
         // Ease in over the last stretch so the stop lands inside the radius instead of overshooting.

package/dist/audio/ambience.d.ts

@@ -0,0 +1,47 @@
+/** A world-space volume whose sound bed plays while the listener is inside it. */
+export type AmbienceZoneShape = {
+    kind: "sphere";
+    center: readonly [number, number, number];
+    radius: number;
+} | {
+    kind: "box";
+    min: readonly [number, number, number];
+    max: readonly [number, number, number];
+};
+/** One ambience zone: a sound bed keyed to a volume of the scene.
+ * @capability ambience-zones a scene declares looping sound beds keyed to world volumes; walking between them crossfades bed levels on the existing buses instead of cutting.
+ */
+export interface AmbienceZoneDef {
+    /** Stable id; the shell retains one looping bed per zone for the engine's lifetime. */
+    id: string;
+    /** Sound id in the playable's `audio.sounds` catalog. The shell loops it regardless of the sound's `loop` flag. */
+    sound: string;
+    shape: AmbienceZoneShape;
+    /**
+     * World units over which the bed fades across the boundary, measured on both sides. Default 4.
+     * Two zones that share a boundary hand over their full level exactly across this band.
+     */
+    crossfade?: number;
+    /** Bed level multiplier, 0..1. Default 1. */
+    gain?: number;
+}
+/** One zone's share of the ambience mix at a listener position, 0..1. */
+export interface AmbienceWeight {
+    id: string;
+    weight: number;
+}
+/**
+ * Distance from a point to a zone boundary, positive inside and negative outside.
+ * Spheres measure from the surface; boxes use the nearest face.
+ */
+export declare function zoneSignedDistance(shape: AmbienceZoneShape, x: number, y: number, z: number): number;
+/**
+ * Every zone's mix weight at a listener position. A zone is at full level `crossfade` units
+ * inside its boundary, at half level on the boundary and silent `crossfade` units outside, so a
+ * listener walking between two zones that share a boundary hears a constant-sum handover.
+ * Weights that would sum above 1 (overlapping zones) are normalized so total bed level never
+ * exceeds unity. Writes into `out` when given, so a per-frame caller allocates nothing.
+ */
+export declare function ambienceWeights(zones: readonly AmbienceZoneDef[], x: number, y: number, z: number, out?: AmbienceWeight[]): AmbienceWeight[];
+/** The loudest zone in a weight list, or null when every zone is silent. */
+export declare function activeAmbienceZone(weights: readonly AmbienceWeight[]): string | null;

package/dist/audio/ambience.js

@@ -0,0 +1,75 @@
+const DEFAULT_CROSSFADE = 4;
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+/**
+ * Distance from a point to a zone boundary, positive inside and negative outside.
+ * Spheres measure from the surface; boxes use the nearest face.
+ */
+export function zoneSignedDistance(shape, x, y, z) {
+    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
+        return -Infinity;
+    if (shape.kind === "sphere") {
+        if (!(shape.radius > 0))
+            return -Infinity;
+        const dx = x - shape.center[0];
+        const dy = y - shape.center[1];
+        const dz = z - shape.center[2];
+        return shape.radius - Math.hypot(dx, dy, dz);
+    }
+    const min = shape.min;
+    const max = shape.max;
+    const values = [x, y, z];
+    let outsideSquared = 0;
+    let nearestFace = Infinity;
+    for (let axis = 0; axis < 3; axis += 1) {
+        const lo = min[axis];
+        const hi = max[axis];
+        const value = values[axis];
+        if (value < lo)
+            outsideSquared += (lo - value) * (lo - value);
+        else if (value > hi)
+            outsideSquared += (value - hi) * (value - hi);
+        else
+            nearestFace = Math.min(nearestFace, value - lo, hi - value);
+    }
+    if (outsideSquared > 0)
+        return -Math.sqrt(outsideSquared);
+    return Number.isFinite(nearestFace) ? nearestFace : 0;
+}
+/**
+ * Every zone's mix weight at a listener position. A zone is at full level `crossfade` units
+ * inside its boundary, at half level on the boundary and silent `crossfade` units outside, so a
+ * listener walking between two zones that share a boundary hears a constant-sum handover.
+ * Weights that would sum above 1 (overlapping zones) are normalized so total bed level never
+ * exceeds unity. Writes into `out` when given, so a per-frame caller allocates nothing.
+ */
+export function ambienceWeights(zones, x, y, z, out = []) {
+    out.length = 0;
+    let total = 0;
+    for (const zone of zones) {
+        const crossfade = zone.crossfade ?? DEFAULT_CROSSFADE;
+        const signed = zoneSignedDistance(zone.shape, x, y, z);
+        if (!Number.isFinite(signed))
+            continue;
+        const weight = crossfade > 0 ? clamp01(0.5 + signed / (2 * crossfade)) : signed >= 0 ? 1 : 0;
+        if (weight <= 0)
+            continue;
+        out.push({ id: zone.id, weight });
+        total += weight;
+    }
+    if (total > 1) {
+        for (const entry of out)
+            entry.weight /= total;
+    }
+    return out;
+}
+/** The loudest zone in a weight list, or null when every zone is silent. */
+export function activeAmbienceZone(weights) {
+    let best = null;
+    for (const entry of weights) {
+        if (best === null || entry.weight > best.weight)
+            best = entry;
+    }
+    return best !== null && best.weight > 0.01 ? best.id : null;
+}

package/dist/audio/audioFalloff.d.ts

@@ -28,6 +28,18 @@ export interface SoundDef {
     maxVoices?: number;
     /** Playback priority; higher priorities survive voice-budget pressure. Default 0. */
     priority?: number;
+    /**
+     * Ducking policy for this cue: while it plays, the named buses drop so a hit, explosion or voice
+     * line cuts through the music and ambience, then return to exactly the player's own level.
+     */
+    duck?: {
+        /** Buses to lower. Default `["music"]`. */
+        buses?: readonly string[];
+        /** How far to lower them, 0..1 (0.6 leaves 40% of the player's level). Default 0.6. */
+        amount?: number;
+        /** Seconds to hold the duck. Default the cue's own length: synth patch duration or decoded sample length. */
+        seconds?: number;
+    };
     /** Positional emitters attenuate by distance from the listener; non-positional sounds (UI, music) play at flat gain. Default true. */
     positional?: boolean;
     falloff?: AudioFalloffConfig;

package/dist/audio/occlusion.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Geometry occlusion for retained positional loops: a cheap line test between the listener and an
+ * emitter behind blocking geometry, bounded so a busy scene can never turn audio into a raycast
+ * pass. The shell runs the test against the scene's blockable colliders; the engine applies the
+ * resulting attenuation and low-pass to the loop it already owns.
+ * @capability audio-occlusion an emitter behind blocking world geometry is attenuated and darkened by a budgeted line test, and falls back to distance-only once the tick's budget is spent.
+ */
+export interface AudioOcclusionConfig {
+    /** Geometry tests shared by every retained loop in one listener tick. Default 8; 0 keeps distance-only. */
+    maxTestsPerTick?: number;
+    /** Minimum milliseconds before the same loop is tested again. Default 150. */
+    intervalMs?: number;
+    /** Gain multiplier at full blockage; 1 disables attenuation. Default 0.55. */
+    attenuation?: number;
+    /** Low-pass cutoff at full blockage in Hz. Default 1200; a loop already darker keeps its own cutoff. */
+    lowpassHz?: number;
+    /** Loops farther than this from the listener are never tested. Default 60. */
+    maxDistance?: number;
+}
+/** Defaults for {@link AudioOcclusionConfig}. */
+export declare const AUDIO_OCCLUSION_DEFAULTS: {
+    readonly maxTestsPerTick: 8;
+    readonly intervalMs: 150;
+    readonly attenuation: 0.55;
+    readonly lowpassHz: 1200;
+    readonly maxDistance: 60;
+};
+/** A fully specified occlusion policy, with every unset field replaced by its default. */
+export interface ResolvedAudioOcclusionConfig {
+    maxTestsPerTick: number;
+    intervalMs: number;
+    attenuation: number;
+    lowpassHz: number;
+    maxDistance: number;
+}
+/**
+ * Fill in the occlusion defaults and clamp each field to a workable range: a finite test budget,
+ * a non-negative retest interval and distance cap, and an attenuation in `0..1`.
+ */
+export declare function resolveOcclusionConfig(config?: AudioOcclusionConfig | false): ResolvedAudioOcclusionConfig;

package/dist/audio/occlusion.js

@@ -0,0 +1,27 @@
+/** Defaults for {@link AudioOcclusionConfig}. */
+export const AUDIO_OCCLUSION_DEFAULTS = {
+    maxTestsPerTick: 8,
+    intervalMs: 150,
+    attenuation: 0.55,
+    lowpassHz: 1200,
+    maxDistance: 60,
+};
+function finite(value, fallback) {
+    return value !== undefined && Number.isFinite(value) ? value : fallback;
+}
+/**
+ * Fill in the occlusion defaults and clamp each field to a workable range: a finite test budget,
+ * a non-negative retest interval and distance cap, and an attenuation in `0..1`.
+ */
+export function resolveOcclusionConfig(config = {}) {
+    if (config === false) {
+        return { ...AUDIO_OCCLUSION_DEFAULTS, maxTestsPerTick: 0 };
+    }
+    return {
+        maxTestsPerTick: Math.max(0, Math.floor(finite(config.maxTestsPerTick, AUDIO_OCCLUSION_DEFAULTS.maxTestsPerTick))),
+        intervalMs: Math.max(0, finite(config.intervalMs, AUDIO_OCCLUSION_DEFAULTS.intervalMs)),
+        attenuation: Math.min(1, Math.max(0, finite(config.attenuation, AUDIO_OCCLUSION_DEFAULTS.attenuation))),
+        lowpassHz: Math.max(10, finite(config.lowpassHz, AUDIO_OCCLUSION_DEFAULTS.lowpassHz)),
+        maxDistance: Math.max(0, finite(config.maxDistance, AUDIO_OCCLUSION_DEFAULTS.maxDistance)),
+    };
+}

package/dist/game/playableGame.d.ts

@@ -1,5 +1,7 @@
 import type { AnimGraph } from "../anim/animGraph.js";
+import type { AmbienceZoneDef } from "../audio/ambience.js";
 import type { AudioBusDef, SoundDef } from "../audio/audioFalloff.js";
+import type { AudioOcclusionConfig } from "../audio/occlusion.js";
 import type { MusicTheme } from "../audio/music.js";
 import type { UiCueOverrides } from "../audio/uiCues.js";
 import type { FeedbackCueOverrides } from "../audio/feedbackCues.js";
@@ -315,10 +317,19 @@ export interface ModelLodConfig {
     fullRateDistance?: number;
     /** Within this distance the rig poses every other frame, carrying the accumulated time. Default 40. */
     halfRateDistance?: number;
-    /** Beyond this distance a crowd-eligible rig renders through the GPU crowd path and updates no bones. Default 25. */
+    /**
+     * At or beyond this distance a crowd-eligible character renders through the GPU batch path and
+     * updates no bones. Default 25. `0` batches it at every distance, which is what a crowd or an army
+     * wants: near members then draw from the same instance buffer instead of one rig each.
+     */
     crowdDistance?: number;
     /** Metres a character must come back inside `crowdDistance` before it returns to its own rig, so the swap cannot flicker at the boundary. Default 2. */
     crowdHysteresis?: number;
+    /**
+     * Characters of this model one batch can draw. A character past the cap keeps its own rig, so a
+     * crowded scene loses draws rather than characters. Default 128.
+     */
+    crowdCapacity?: number;
 }
 /** Wind sway for a foliage model; see {@link ModelConfig.wind}. */
 export interface ModelWindConfig {
@@ -789,6 +800,15 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
         uiCues?: UiCueOverrides;
         /** Default gameplay reactions (`feel.hit`, `feel.kill`, `feel.pickup`, ...) on an "sfx" bus, played by the shell from the events the engine announces. A sound named `feel.<cue>` in `sounds` replaces one; a map entry replaces or (`false`) silences one; `false` silences all. */
         feedbackCues?: FeedbackCueOverrides;
+        /**
+         * World-space ambience zones. While the listener is inside a zone the shell loops its bed on
+         * the sound's own bus; walking between zones hands over across each floor's `crossfade`
+         * distance, and leaving every zone fades to silence. Beds are retained, so a zone you return to
+         * resumes without a seam.
+         */
+        zones?: readonly AmbienceZoneDef[];
+        /** Geometry occlusion for retained positional loops. Unset uses the engine defaults; `false` keeps distance-only attenuation everywhere. */
+        occlusion?: AudioOcclusionConfig | false;
     };
     /** Continuous positional emitter keyed by entity kind name: while a matching entity exists, the shell plays and repositions the mapped `audio.sounds` id (looping engine hum, campfire crackle, footstep loop) with listener-distance falloff. */
     entitySounds?: Record<string, string>;

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.33.0";
+export declare const VERSION = "0.35.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];

package/dist/meta/changelog.js

@@ -1,7 +1,40 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.33.0";
+export const VERSION = "0.35.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.35.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.35.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.32.0`; `@jgengine/github` is `0.22.0`.",
+        ],
+        added: [
+            "`ModelLodConfig.crowdCapacity` declares how many characters of one model a batch draws (default 128). A character past the cap keeps its own rig at its distance tier instead of disappearing.",
+            "`ModelLodConfig.crowdDistance` accepts `0`, which batches a character at every distance instead of only past 25 m. A game with a near crowd or a close-quarters army sets it to batch members in front of the camera too.",
+            "`characterRigTier` (`@jgengine/shell/render/characterLod`) resolves the distance tier a character poses its own rig on, which is the fallback for an over-cap crowd.",
+            "`audio.zones` (`@jgengine/core/game/playableGame`): a scene declares world-space ambience zones, one looping bed per zone. The shell crossfades bed levels from the listener position on each sound's own bus, so entering, leaving and walking between zones hand over instead of cutting.",
+            "`audio.occlusion` (`@jgengine/core/audio/occlusion`): budgeted geometry occlusion for retained positional loops. A blocked line attenuates the loop and darkens it through a low-pass; the per-tick test budget and interval bound the cost, and a loop that cannot be tested stays on distance-only.",
+            "`SoundDef.duck`: a cue can lower named buses for its own duration. `AudioEngine.duck` returns a release, and the player's own gain is restored exactly even when they move the slider mid-duck.",
+            "`AudioEngine.ambience()`, `AudioEngine.occlusionStats()` and `window.__jgengineAudio` report the zone mix, the newest occlusion test and the measured per-test cost for capture and diagnostics.",
+        ],
+        changed: [
+            "The character batch path now covers every drawable character model, not only skinned locomotion rigs: a node-transform character (rotating limbs, no skin) rides the node a clip moves, and a model with no clips at all batches as a static geometry. Both still bake to one geometry per material, so a crowd draws once per model and material.",
+            "Batched characters are pickable: the batch carries the entity ids of the instances it drew, so `worldHit().entity` and a click on a batched character resolve to the character instead of falling through to the ground.",
+            "Load-time shader warmup compiles what the first frame can reach, reveals as soon as those programs are linked, and finishes the rest in background rounds, so a scene no longer holds the loading cover for its whole model stream and no longer drops a compile onto a frame that is already showing. The loading cover names the shader count, the seconds waited and the work left for the background.",
+            "A crowd batch silently dropped members past its fixed 128 instances while their markers still hid them, so a full scene lost characters. Members past the declared capacity now keep their own rigs.",
+            "A crowd batch's clock now follows the game clock when one is bound, so a paused game no longer keeps its crowd walking.",
+        ],
+        removed: [],
+    },
+    "0.34.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.34.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.31.0`; `@jgengine/github` is `0.21.0`.",
+        ],
+        added: [
+            "`PaceBand` on `DriverGoal` (`paceBand` + caller-measured `paceGap`) gives catch-up pacing an owner in `@jgengine/core/ai/driver`: a dead zone around `margin` (`tolerance`), `ease` shedding pace for a car ahead over `easeAt`, `push` adding it for a car behind over `pushAt`, and `scale` as the per-car share. `paceBandFactor(band, gap)` exposes the rule on its own. Deterministic scalar math, no allocation per step; the push never outdrives `DriverTuning.maxSpeed`. First adopter: Drift Foundry's rival field, which deletes its own `paceBand`; second: Harbor Heat's interceptors.",
+            "`createRunLoop` (`@jgengine/core/run/runLoop`) holds a run's at-risk haul, banks it scaled by the line or loses it on a failure, and draws one authored change for each next run from a seeded table, so the same seed and run history replay the same sequence. State round-trips through `snapshot`/`restore`; the money stays in `progression/careerBank`.",
+        ],
+        changed: [],
+        removed: [],
+    },
     "0.33.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.33.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.30.0`; `@jgengine/github` is `0.20.0`.",

package/dist/run/runLoop.d.ts

@@ -0,0 +1,88 @@
+/** How a run ended: what it carried reached the bank, or it was lost. */
+export type RunOutcome = "banked" | "lost";
+/**
+ * One change the next run can open with. `T` is the game's own payload (a tighter rival line, an
+ * unlocked part, a route modifier) - the loop only draws and remembers which id was drawn.
+ */
+export interface RunChange<T> {
+    id: string;
+    value: T;
+    /** Relative draw weight (default `1`); a non-positive weight is never drawn. */
+    weight?: number;
+    /** Completed runs this change needs before it can be drawn (default `0`). */
+    after?: number;
+}
+/** The change a run opens with, and which run it is. */
+export interface RunOffer<T> {
+    /** 1-based run number: `1` is the first run, before anything has been banked. */
+    run: number;
+    changeId: string | null;
+    change: T | null;
+}
+/** Everything a run loop stores as plain JSON: the run in progress plus lifetime totals. */
+export interface RunLoopState {
+    /** The run in progress, or `0` before the first `start`. */
+    run: number;
+    /** Runs settled so far; also the number `after` gates are read against. */
+    completed: number;
+    /** What the run in progress carries and can still lose. */
+    haul: number;
+    /** Change drawn for the run in progress, or `null`. */
+    changeId: string | null;
+    bankedTotal: number;
+    lostTotal: number;
+    bestHaul: number;
+}
+/** What one closed run banked or lost, and what the next run changes. */
+export interface RunSettlement<T> {
+    outcome: RunOutcome;
+    /** What the run carried before the multiplier. */
+    haul: number;
+    /** What reached the bank: the haul after the line multiplier on a bank, `0` on a loss. */
+    banked: number;
+    /** What the run lost: the whole haul on a loss, `0` on a bank. */
+    lost: number;
+    completed: number;
+    bestHaul: number;
+    /** The next run's change, drawn here so a results screen can name it. */
+    next: RunOffer<T>;
+}
+/** Configuration for {@link createRunLoop}. */
+export interface RunLoopConfig<T> {
+    /** Seed for the run-to-run draw: the same seed and history replay the same sequence. */
+    seed: string | number;
+    /** Authored table of next-run changes; omit a table for a loop that never varies. */
+    changes?: readonly RunChange<T>[];
+}
+/**
+ * A run's lifecycle: what it carries and can lose, and the change it hands the next run.
+ */
+export interface RunLoop<T> {
+    /** Open the next run and hand back its offer. Calling it on an open run returns that run's offer and keeps its haul. */
+    start(): RunOffer<T>;
+    /** Add to what the run in progress carries; negative or non-finite amounts are ignored. Returns the haul. */
+    carry(amount: number): number;
+    /** What the run in progress carries. */
+    haul(): number;
+    /** The run in progress's offer, or the offer the next `start` would open. */
+    offer(): RunOffer<T>;
+    /**
+     * Close the run in progress: bank the haul scaled by `multiplier`, or lose it. Throws when no run
+     * is open, so a double settle cannot bank the same haul twice.
+     */
+    settle(outcome: RunOutcome, multiplier?: number): RunSettlement<T>;
+    snapshot(): RunLoopState;
+    restore(next: RunLoopState): void;
+}
+/**
+ * Bank-or-lose between runs, with one deterministic change per run drawn from an authored table.
+ *
+ * A run's haul banks when it ends in a bank and is lost when it ends in a loss; the money itself stays
+ * with the game (pair it with `progression/careerBank`). After each settled run the loop draws the next
+ * run's change from `changes`: eligible when `after <= completed`, never the change just played unless
+ * it is the only one eligible, weighted by `weight`. The draw is `seededRng(seed:run:N)`, so the same
+ * seed and the same run history give the same sequence, before or after a save/load.
+ *
+ * @capability run-loop bank or lose what a run carries, with one deterministic change per run
+ */
+export declare function createRunLoop<T>(config: RunLoopConfig<T>): RunLoop<T>;

package/dist/run/runLoop.js

@@ -0,0 +1,92 @@
+import { pickWeighted } from "../random/pick.js";
+import { seededRng } from "../random/rng.js";
+function positive(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+/**
+ * Bank-or-lose between runs, with one deterministic change per run drawn from an authored table.
+ *
+ * A run's haul banks when it ends in a bank and is lost when it ends in a loss; the money itself stays
+ * with the game (pair it with `progression/careerBank`). After each settled run the loop draws the next
+ * run's change from `changes`: eligible when `after <= completed`, never the change just played unless
+ * it is the only one eligible, weighted by `weight`. The draw is `seededRng(seed:run:N)`, so the same
+ * seed and the same run history give the same sequence, before or after a save/load.
+ *
+ * @capability run-loop bank or lose what a run carries, with one deterministic change per run
+ */
+export function createRunLoop(config) {
+    const table = config.changes ?? [];
+    const known = new Set();
+    for (const change of table) {
+        if (known.has(change.id))
+            throw new Error(`run change "${change.id}" is declared twice`);
+        known.add(change.id);
+    }
+    let run = 0;
+    let completed = 0;
+    let haul = 0;
+    let changeId = null;
+    let bankedTotal = 0;
+    let lostTotal = 0;
+    let bestHaul = 0;
+    function drawFor(index, previous) {
+        const eligible = table.filter((change) => (change.after ?? 0) <= index - 1);
+        const fresh = eligible.filter((change) => change.id !== previous);
+        // A one-entry table still offers its change rather than nothing.
+        const pool = fresh.length > 0 ? fresh : eligible;
+        const rng = seededRng(`${config.seed}:run:${index}`);
+        const drawn = pickWeighted(rng, pool, (change) => change.weight ?? 1) ?? null;
+        return { run: index, changeId: drawn?.id ?? null, change: drawn?.value ?? null };
+    }
+    function offer() {
+        // An open run's change was adopted at `start`, so the offer repeats it instead of redrawing.
+        if (run > completed) {
+            const adopted = table.find((change) => change.id === changeId);
+            return { run, changeId, change: adopted?.value ?? null };
+        }
+        return drawFor(completed + 1, changeId);
+    }
+    return {
+        start() {
+            if (run > completed)
+                return offer();
+            const next = offer();
+            run = next.run;
+            haul = 0;
+            changeId = next.changeId;
+            return next;
+        },
+        carry(amount) {
+            haul += positive(amount);
+            return haul;
+        },
+        haul: () => haul,
+        offer,
+        settle(outcome, multiplier) {
+            if (run <= completed)
+                throw new Error("run loop: no run is open to settle");
+            const settledHaul = haul;
+            const scale = Number.isFinite(multiplier) ? Math.max(0, multiplier ?? 1) : 1;
+            const banked = outcome === "banked" ? Math.round(settledHaul * scale) : 0;
+            const lost = outcome === "lost" ? settledHaul : 0;
+            bankedTotal += banked;
+            lostTotal += lost;
+            bestHaul = Math.max(bestHaul, banked);
+            completed = run;
+            haul = 0;
+            return { outcome, haul: settledHaul, banked, lost, completed, bestHaul, next: drawFor(completed + 1, changeId) };
+        },
+        snapshot: () => ({ run, completed, haul, changeId, bankedTotal, lostTotal, bestHaul }),
+        restore(next) {
+            run = Math.max(0, Math.floor(next.run));
+            completed = Math.max(0, Math.floor(next.completed));
+            if (run < completed)
+                run = completed;
+            haul = positive(next.haul);
+            changeId = next.changeId !== null && known.has(next.changeId) ? next.changeId : null;
+            bankedTotal = positive(next.bankedTotal);
+            lostTotal = positive(next.lostTotal);
+            bestHaul = positive(next.bestHaul);
+        },
+    };
+}