@jgengine/core 0.34.0 → 0.36.0

package/CHANGELOG.md

@@ -26,6 +26,65 @@ 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.36.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.36.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.33.0`; `@jgengine/github` is `0.23.0`.
+
+### Added
+
+- `createAgentSystem` (`@jgengine/core/agents/system`) takes a game's needs, options, mood weights, members and
+  schedules once and returns a running cast: one `tick(dt)` for everyone, one target selector for the whole system,
+  a fallback declared once, and a plain-JSON `save()`/`load()` that rides the game's own save.
+- `--quick` on `bun run shoot` and `bun run drive` is the 960x540 iteration preset: one settled frame (a 2s settle window in drive), no video, no perf pass, written as `<name>-quick.png` and timed on its own line. It refuses a 1600x900 pixel claim, a frame-time claim, a non-desktop device and a recording flag by name instead of producing weaker evidence; full stays the default for PR shots. On a warm daemon a two-shot `drive` of ember-command went 9.3s to 8.2s and 4316KB to 1383KB of PNG.
+- `createPlayScript` / `runPlayScript` (`@jgengine/shell/play`) play a real `PlayableGame` headlessly from a tick-based script: `move`, `aim`, `fire`, `use`, `wait` and `command` steps plus `setup`/`onTick` hooks, `expect` assertions read after setup and on their own tick, a tick timeline, and an FNV digest for replay comparison. It replays the shell's own frame pipeline — held movement through the walk controller, a bound action resolving to its command on press and repeat, interact prompts, hotbar — so a script proves the same code path a player's hands do. No browser, no wall clock, fixed `dt`.
+- `bun run simulate <game> <script>` runs a committed `<game>/scripts/*.play.ts` against a game under `./Games`, prints the timeline, names a failed assertion and exits 1. It merges the game's own tsconfig `paths` with this checkout's source packages, so the game imports and the engine under test are one module graph.
+- `HeadlessRunner.aim()` steers the walk controller mid-run; `HeadlessRunnerOptions` gains `seed` (deterministic `ctx.rng`) and `collision` (the shell's voxel config, previously dropped on the headless path).
+
+Play scripts prove play in seconds instead of minutes of browser play, and the three proofs land beside their games: Scrap Signal (an enemy takes damage and closes in), Beacon Bastion (a composed wave is reached, its bounty scales, a boss phase flips) and Harbor Heat (heat is witness-gated, the search area is set, a courier is swept).
+
+### Changed
+
+- The graphics quality tier now costs what it claims on the render path. A tier's post chain renders at its own resolution scale (`low` 0.7, `medium` 0.85, `high`/`ultra` native) instead of always at the canvas size, and a game's authored `shadowMapSize` and `cascades` are a ceiling the tier caps rather than a value it ignored — every reference game authored 3 cascades and 1024/2048, so no tier changed a shadow before this. `low` and `medium` also stretch the far cascades' refresh interval, and the smallest caster worth a depth draw grows as the map shrinks. `high` and `ultra` keep native resolution, the authored shadow sizes and the measured cadence, so their frames are unchanged.
+- Measured uncapped at 1600x900: whole-frame draws at `low` fell 53% in harbor-heat (515 → 242) and 63% in drift-foundry (1,098 → 408), with the shadow pass there down from 911 ms to 344 ms over a 6 s window; `high` and `ultra` held their draw counts.
+
+### Fixed
+
+- Terrain build no longer scans every road and path segment for every vertex. A baked path corridor, a draped road and a painted polyline region each answer "how far is this point?" from a precomputed segment grid, so Scrap Signal's world build drops from 16.6 s to 0.51 s on the same machine and its longest boot stall from 11.6–18.4 s to 1.2 s. Sampled heights and palettes are bit-identical to the previous full scan, and `withPathProfiles` still composes profiles in order.
+- Load-time shader warmup compiles against the render state the first frame actually draws with. A scene whose post chain renders into its own buffer was linking two programs per material, one linear untone-mapped set the frame draws and one canvas set nothing ever drew; the cover no longer waits for the second set. Harbor Heat links 84 programs to 58 and Scrap Signal 124 to 83 before the cover lifts, with no visual change.
+
+### Performance
+
+- `createTerrainPaletteSampler` (`@jgengine/core/world/terrain`) tests only the material regions whose painted core or blend ring covers a sample, so a world with hundreds of authored regions no longer pays for all of them at every vertex.
+
+## 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
@@ -34,6 +93,7 @@ At publish, rename this heading to the new version and mirror the entries into
 
 ### 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

package/dist/agents/system.d.ts

@@ -0,0 +1,135 @@
+import type { UtilityInterrupt, UtilityOption, UtilityTunables } from "../ai/utilityBrain.js";
+import type { NeedDefinition } from "../sim/needs.js";
+import type { Vec3 } from "../world/geometry.js";
+import { type Agent, type AgentFallback, type AgentFrame, type AgentSnapshot, type AgentTarget } from "./agent.js";
+import type { Mood, MoodTier, MoodWeight } from "./mood.js";
+import type { AgentScheduleConfig } from "./schedule.js";
+export type { Agent, AgentAction, AgentFallback, AgentFrame, AgentSnapshot, AgentTarget } from "./agent.js";
+export type { AgentScheduleConfig, AgentScheduleStop, AgentSchedulePhase } from "./schedule.js";
+export type { Mood, MoodTier, MoodWeight } from "./mood.js";
+export type { NeedDefinition } from "../sim/needs.js";
+export type { UtilityInterrupt, UtilityOption, UtilityTunables } from "../ai/utilityBrain.js";
+/** The mood policy a member runs on: which needs matter, and the game's own words for the bands. */
+export interface AgentMoodConfig {
+    readonly weights?: readonly MoodWeight[];
+    readonly tiers?: readonly MoodTier[];
+}
+/** What a selector is told about the member asking: who it is, its live agent, and where it stands. */
+export interface AgentSelectView {
+    readonly id: string;
+    /** The live agent, for a selector that reads needs, mood or the held action. */
+    readonly agent: Agent;
+    /** Body position from the system's `position` reader, or `null` when the game has no body for it. */
+    readonly at: Vec3 | null;
+    readonly now: number;
+    /** True while the member is off camera and takes no utility pass this tick. */
+    readonly far: boolean;
+}
+/** Everything the member could do right now, as the game's world offers it. Declared once per system. */
+export type AgentSelector = (view: AgentSelectView) => readonly AgentTarget[];
+/** Where a system keeps its save data: a key-value store, a save slot, or a test's map. */
+export interface AgentSystemStorage {
+    read(): AgentSystemState | undefined;
+    write(next: AgentSystemState): void;
+}
+/** One member's saved state: its agent snapshot plus the off-camera flag the snapshot does not carry. */
+export interface AgentMemberState {
+    readonly agent: AgentSnapshot;
+    readonly far: boolean;
+}
+/** The whole system as plain JSON - drop it in a save, read it back with {@link AgentSystem.load}. */
+export interface AgentSystemState {
+    readonly version: 1;
+    readonly members: Readonly<Record<string, AgentMemberState>>;
+}
+/** One member: an id, and only what differs from the system's defaults. */
+export interface AgentMemberSpec extends UtilityTunables {
+    readonly id: string;
+    /** Needs for this member; defaults to the system's. */
+    readonly needs?: readonly NeedDefinition[];
+    /** Scored actions for this member; defaults to the system's. */
+    readonly options?: readonly UtilityOption[];
+    readonly interrupts?: readonly UtilityInterrupt[];
+    /** The member's authored day; omit for one that only reacts to targets. */
+    readonly schedule?: AgentScheduleConfig;
+    readonly mood?: AgentMoodConfig;
+    /** Targets for this member instead of the system's selector. */
+    readonly select?: AgentSelector;
+    /** `[0,1)` source; defaults to the system's `rng`. */
+    readonly rng?: () => number;
+    readonly devtoolsName?: string;
+    /** Start off camera: schedule and needs only, no utility pass, until `setFar(id, false)`. */
+    readonly far?: boolean;
+}
+/** The game's data, in one place: what its people need, what they can do, and how they feel. */
+export interface AgentSystemConfig {
+    /** Needs every member carries unless it declares its own. */
+    readonly needs: readonly NeedDefinition[];
+    /** Scored actions every member chooses between unless it declares its own. */
+    readonly options: readonly UtilityOption[];
+    readonly interrupts?: readonly UtilityInterrupt[];
+    readonly mood?: AgentMoodConfig;
+    /** Members present at creation; more join later with {@link AgentSystem.add}. */
+    readonly members?: readonly AgentMemberSpec[];
+    /** Resolve every member's targets. Called once per on-camera member per tick, never per option. */
+    readonly select?: AgentSelector;
+    /** Fallback given to every target that declares none - one fallback per system, not per target. */
+    readonly fallback?: AgentFallback;
+    /** The world clock, so `tick(dt)` needs no `now` argument. */
+    readonly clock?: {
+        now(): number;
+    };
+    /** Where a member's body is, handed to the selector as `at`. */
+    readonly position?: (id: string) => Vec3 | null;
+    /** Save storage, hydrated on the first tick and written by {@link AgentSystem.save}. */
+    readonly storage?: AgentSystemStorage;
+    /** Deterministic source shared by members that do not declare their own. */
+    readonly rng?: () => number;
+    /** Dials every member starts with; a member may override any of them. */
+    readonly defaults?: UtilityTunables;
+    /** Devtools prefix: member `x` registers as `<devtoolsName>.x`. */
+    readonly devtoolsName?: string;
+}
+/**
+ * A whole cast of agents behind one factory and one tick.
+ *
+ * Feed it a game's data once - needs, options, mood weights, the members and their schedules - and it
+ * owns the parts a game should not write: the roster, lazy creation, one tick for everyone, where a
+ * target came from, and a save blob that is plain JSON. Everything an individual {@link Agent} can do
+ * stays reachable through {@link get}.
+ */
+export interface AgentSystem {
+    /** Create and register one member; a member saved under this id resumes instead of starting fresh. */
+    add(spec: AgentMemberSpec): Agent;
+    get(id: string): Agent | null;
+    has(id: string): boolean;
+    remove(id: string): void;
+    /** Member ids in creation order. */
+    ids(): readonly string[];
+    size(): number;
+    /** One call per game tick: decay, day plan and decision for every member, near or far. */
+    tick(dt: number, now?: number): void;
+    /** What the last tick produced for a member, or `null` before it has ticked. */
+    frame(id: string): AgentFrame | null;
+    /** A member's mood, readable before its first tick. */
+    mood(id: string): Mood | null;
+    /** Mean mood across members, or `null` for an empty system. */
+    moodMean(): number | null;
+    /** Action of a member, `null` before its first tick. */
+    action(id: string): AgentFrame["action"] | null;
+    setFar(id: string, far: boolean): void;
+    isFar(id: string): boolean;
+    /** Plain-JSON state, also written to `storage` when one was given. */
+    save(): AgentSystemState;
+    /** Restore members saved under ids this system knows, and hold the rest until they join. */
+    load(next: AgentSystemState | undefined): void;
+    dispose(): void;
+}
+/**
+ * One call for a whole cast: a game hands over its needs, options, mood weights, schedules and one
+ * target selector, and gets back a running system with a single `tick(dt)` and a save blob that goes
+ * into the game's own save.
+ *
+ * @capability agents a needs, thought, action and mood loop an agent runs on the world clock
+ */
+export declare function createAgentSystem(config: AgentSystemConfig): AgentSystem;

package/dist/agents/system.js

@@ -0,0 +1,195 @@
+import { createAgent, } from "./agent.js";
+/**
+ * One call for a whole cast: a game hands over its needs, options, mood weights, schedules and one
+ * target selector, and gets back a running system with a single `tick(dt)` and a save blob that goes
+ * into the game's own save.
+ *
+ * @capability agents a needs, thought, action and mood loop an agent runs on the world clock
+ */
+export function createAgentSystem(config) {
+    const agents = new Map();
+    const frames = new Map();
+    const selectors = new Map();
+    const saved = new Map();
+    const order = [];
+    let hydrated = false;
+    let lastNow = 0;
+    function selectFor(id) {
+        return selectors.get(id) ?? config.select;
+    }
+    function restoreInto(agent, state) {
+        agent.restore(state.agent);
+        if (state.far)
+            agent.setFar(true);
+    }
+    function hydrate() {
+        if (hydrated)
+            return;
+        const state = config.storage?.read();
+        if (state === undefined)
+            return;
+        hydrated = true;
+        loadState(state);
+    }
+    function loadState(next) {
+        if (next === undefined)
+            return;
+        for (const [id, state] of Object.entries(next.members)) {
+            const agent = agents.get(id);
+            if (agent === undefined) {
+                saved.set(id, state);
+                continue;
+            }
+            restoreInto(agent, state);
+            saved.delete(id);
+        }
+    }
+    function create(spec) {
+        const defaults = config.defaults;
+        const tuned = (key) => spec[key] ?? defaults?.[key];
+        const devtoolsName = spec.devtoolsName ?? (config.devtoolsName === undefined ? undefined : `${config.devtoolsName}.${spec.id}`);
+        const agent = createAgent({
+            id: spec.id,
+            needs: spec.needs ?? config.needs,
+            options: spec.options ?? config.options,
+            ...optional("interrupts", spec.interrupts ?? config.interrupts),
+            ...optional("schedule", spec.schedule),
+            mood: {
+                ...optional("weights", spec.mood?.weights ?? config.mood?.weights),
+                ...optional("tiers", spec.mood?.tiers ?? config.mood?.tiers),
+            },
+            ...optional("switchMargin", tuned("switchMargin")),
+            ...optional("minHoldSeconds", tuned("minHoldSeconds")),
+            ...optional("costWeight", tuned("costWeight")),
+            ...optional("jitter", tuned("jitter")),
+            ...optional("rng", spec.rng ?? config.rng),
+            ...optional("devtoolsName", devtoolsName),
+        });
+        agents.set(agent.id, agent);
+        order.push(agent.id);
+        if (spec.select !== undefined)
+            selectors.set(agent.id, spec.select);
+        if (spec.far === true)
+            agent.setFar(true);
+        const pending = saved.get(spec.id);
+        if (pending !== undefined) {
+            restoreInto(agent, pending);
+            saved.delete(spec.id);
+        }
+        return agent;
+    }
+    const system = {
+        add(spec) {
+            const existing = agents.get(spec.id);
+            if (existing !== undefined)
+                return existing;
+            return create(spec);
+        },
+        get: (id) => agents.get(id) ?? null,
+        has: (id) => agents.has(id),
+        remove(id) {
+            const agent = agents.get(id);
+            if (agent === undefined)
+                return;
+            agent.dispose();
+            agents.delete(id);
+            frames.delete(id);
+            selectors.delete(id);
+            saved.delete(id);
+            const at = order.indexOf(id);
+            if (at >= 0)
+                order.splice(at, 1);
+        },
+        ids: () => order,
+        size: () => order.length,
+        tick(dt, now) {
+            hydrate();
+            const time = now ?? config.clock?.now() ?? lastNow;
+            lastNow = time;
+            for (const id of order) {
+                const agent = agents.get(id);
+                if (agent === undefined)
+                    continue;
+                let targets = [];
+                if (!agent.isFar()) {
+                    const selector = selectFor(id);
+                    if (selector !== undefined) {
+                        targets = selector({
+                            id,
+                            agent,
+                            at: config.position?.(id) ?? null,
+                            now: time,
+                            far: false,
+                        });
+                        if (config.fallback !== undefined)
+                            targets = withFallback(targets, config.fallback);
+                    }
+                }
+                frames.set(id, agent.update({ dt, now: time, targets }));
+            }
+        },
+        frame: (id) => frames.get(id) ?? null,
+        mood: (id) => agents.get(id)?.mood() ?? null,
+        moodMean() {
+            if (order.length === 0)
+                return null;
+            let total = 0;
+            for (const id of order) {
+                const agent = agents.get(id);
+                if (agent !== undefined)
+                    total += agent.mood().score;
+            }
+            return total / order.length;
+        },
+        action: (id) => frames.get(id)?.action ?? null,
+        setFar(id, far) {
+            const agent = agents.get(id);
+            if (agent === undefined)
+                return;
+            agent.setFar(far);
+            if (far)
+                frames.delete(id);
+        },
+        isFar: (id) => agents.get(id)?.isFar() ?? false,
+        save() {
+            hydrate();
+            const members = {};
+            for (const id of order) {
+                const agent = agents.get(id);
+                if (agent !== undefined)
+                    members[id] = { agent: agent.snapshot(), far: agent.isFar() };
+            }
+            const state = { version: 1, members };
+            config.storage?.write(state);
+            return state;
+        },
+        load: loadState,
+        dispose() {
+            for (const agent of agents.values())
+                agent.dispose();
+            agents.clear();
+            frames.clear();
+            saved.clear();
+            order.length = 0;
+        },
+    };
+    hydrate();
+    for (const spec of config.members ?? [])
+        create(spec);
+    return system;
+}
+/** Targets keep their own fallback; the rest inherit the system's one. */
+function withFallback(targets, fallback) {
+    let changed = false;
+    const next = targets.map((target) => {
+        if (target.fallback !== undefined)
+            return target;
+        changed = true;
+        return { ...target, fallback };
+    });
+    return changed ? next : targets;
+}
+/** Spread a config field only when the game set it, so `createAgent`'s own default stands otherwise. */
+function optional(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}

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>;