@jgengine/core 0.34.0 → 0.35.0

package/CHANGELOG.md

@@ -26,6 +26,33 @@ 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
@@ -34,6 +61,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/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.34.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,12 +1,35 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.34.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: [],

package/dist/runtime/headlessRunner.d.ts

@@ -26,6 +26,8 @@ export interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultipl
     };
     /** Wall-clock source for the sim clock — inject a deterministic counter for reproducible runs. */
     now?: () => number;
+    /** Seed for `ctx.rng` — pass one so a recorded run and its replay draw the same numbers. Defaults to the definition's name. */
+    seed?: string | number;
     /** Per-step real-dt clamp in seconds, matching the shell's frame cap so one long stall can't fast-forward the sim. Default `0.05`. */
     maxStepSeconds?: number;
     /**
@@ -36,7 +38,9 @@ export interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultipl
     playerMovement?: boolean;
     /** Movement tuning — when `playerMovement` is on, the shell resolves from `definition.world`/`physics`; pass a direct config to test flight or other movement overrides headlessly. */
     movement?: import("../game/playableGame.js").PlayerMovementConfig;
-    /** Yaw heading (radians) fed to the movement controller when `playerMovement` is on; the shell supplies its camera yaw. */
+    /** Voxel collision config (`defineGame({ collision })`) — the shell's walk controller reads it, so a headless caller passes the same object to walk the same geometry. */
+    collision?: import("../game/playableGame.js").VoxelCollisionConfig;
+    /** Yaw heading (radians) fed to the movement controller when `playerMovement` is on; the shell supplies its camera yaw. Change it mid-run with {@link HeadlessRunner.aim}. */
     heading?: number;
     /** Pitch (radians) fed alongside yaw for 6DOF spectator flight when `alignWithLook` is set. */
     pitch?: number;
@@ -78,6 +82,11 @@ export interface HeadlessRunner {
     publishInput(input: HeadlessInput): void;
     /** Drive the game's own UI commands / intents headlessly — the same registry `ctx.game.commands` and the shell's command sink dispatch into. No renderer, no pointer simulation: dispatch an intent, then read reactive state off `ctx`. */
     readonly ui: HeadlessCommandInterface;
+    /** Point the movement controller at a yaw/pitch mid-run — what the shell does when the camera turns, so a scripted run can walk one way and then another. */
+    aim(look: {
+        heading?: number;
+        pitch?: number;
+    }): void;
     /** Capture the whole simulation (world, clock, loop, rng cursor) for {@link restore}; with a fixed `simulation.hz` and recorded input, replaying from it reproduces the run exactly. */
     snapshot(): SimSnapshot;
     restore(snapshot: SimSnapshot): void;

package/dist/runtime/headlessRunner.js

@@ -12,13 +12,16 @@ export function createHeadlessRunner(options) {
         content,
         player,
         ...(options.now === undefined ? {} : { now: options.now }),
+        ...(options.seed === undefined ? {} : { seed: options.seed }),
         ...(options.models === undefined ? {} : { models: options.models }),
     });
     loop?.onInit?.(ctx);
     loop?.onNewPlayer?.(ctx);
     const simSnapshot = createContextSimSnapshot(ctx);
+    const look = { heading: options.heading ?? 0, pitch: options.pitch ?? 0 };
     const tuning = options.playerMovement === true
         ? { ...resolvePlayerMovementTuning({
+                collision: options.collision,
                 physics: definition.physics,
                 world: definition.world,
                 movement: options.movement,
@@ -48,6 +51,12 @@ export function createHeadlessRunner(options) {
             names: () => ctx.game.commands.names(),
             has: (name) => ctx.game.commands.has(name),
         },
+        aim(next) {
+            if (next.heading !== undefined && Number.isFinite(next.heading))
+                look.heading = next.heading;
+            if (next.pitch !== undefined && Number.isFinite(next.pitch))
+                look.pitch = next.pitch;
+        },
         step(dtSeconds, input) {
             if (input !== undefined)
                 publishInput(input);
@@ -58,7 +67,7 @@ export function createHeadlessRunner(options) {
                 total += gameDt;
                 ctx.sim.runStages("beforeMovement", stepDt);
                 if (tuning !== null && gameDt > 0) {
-                    stepPlayerMovement(ctx, player.userId, { held: ctx.input.held(), pointer: ctx.input.pointer() }, gameDt, tuning, options.heading, options.pitch);
+                    stepPlayerMovement(ctx, player.userId, { held: ctx.input.held(), pointer: ctx.input.pointer() }, gameDt, tuning, look.heading, look.pitch);
                 }
                 ctx.sim.runStages("afterMovement", stepDt);
                 loop?.onTick?.(ctx, gameDt);

package/dist/world/pathTerrain.js

@@ -1,3 +1,4 @@
+import { buildPolylineIndex } from "./polylineIndex.js";
 function clamp01(value) {
     return value < 0 ? 0 : value > 1 ? 1 : value;
 }
@@ -15,34 +16,28 @@ function buildCorridor(points) {
         const b = points[i];
         cumulative.push(cumulative[i - 1] + Math.hypot(b[0] - a[0], b[1] - a[1]));
     }
-    return { points, cumulative, total: cumulative[cumulative.length - 1] ?? 0 };
+    return { points, cumulative, total: cumulative[cumulative.length - 1] ?? 0, index: buildPolylineIndex(points) };
 }
 /**
- * Closest point on the corridor to `(x, z)`: unsigned lateral distance and arc-length position. Self-
- * contained (each segment projects independently and the minimum lateral wins) so a vertex always reports
- * a near-zero lateral, regardless of which side of the line the neighbours fall.
+ * Closest point on the corridor to `(x, z)` within `limit`: unsigned lateral distance and arc-length
+ * position. Self-contained (each segment projects independently and the minimum lateral wins) so a
+ * vertex always reports a near-zero lateral, regardless of which side of the line the neighbours fall.
+ * Beyond `limit` the corridor cannot change the sample, so the answer is `null`.
  */
-function nearestOnCorridor(corridor, x, z) {
-    let bestLateral = Number.POSITIVE_INFINITY;
-    let bestAlong = 0;
-    let bestPoint = corridor.points[0] ?? [x, z];
-    for (let i = 1; i < corridor.points.length; i += 1) {
-        const a = corridor.points[i - 1];
-        const b = corridor.points[i];
-        const abx = b[0] - a[0];
-        const abz = b[1] - a[1];
-        const segLenSq = abx * abx + abz * abz;
-        const t = segLenSq <= 0 ? 0 : Math.max(0, Math.min(1, ((x - a[0]) * abx + (z - a[1]) * abz) / segLenSq));
-        const px = a[0] + abx * t;
-        const pz = a[1] + abz * t;
-        const lateral = Math.hypot(x - px, z - pz);
-        if (lateral < bestLateral) {
-            bestLateral = lateral;
-            bestAlong = corridor.cumulative[i - 1] + t * Math.sqrt(segLenSq);
-            bestPoint = [px, pz];
-        }
-    }
-    return { lateral: bestLateral, along: bestAlong, point: bestPoint };
+function nearestOnCorridor(corridor, x, z, limit) {
+    const hit = corridor.index.nearest(x, z, limit);
+    if (hit === null)
+        return null;
+    const a = corridor.points[hit.segment];
+    const b = corridor.points[hit.segment + 1];
+    const abx = b[0] - a[0];
+    const abz = b[1] - a[1];
+    const segLenSq = abx * abx + abz * abz;
+    return {
+        lateral: hit.distance,
+        along: corridor.cumulative[hit.segment] + hit.t * Math.sqrt(segLenSq),
+        point: hit.point,
+    };
 }
 function resolveProfile(profile) {
     if (profile.points.length < 2 || profile.width <= 0)
@@ -94,10 +89,10 @@ function centerlineTarget(profile, along, point, base) {
     return base(point[0], point[1]);
 }
 function applyProfileAt(profile, x, z, surrounding, base) {
-    const hit = nearestOnCorridor(profile.corridor, x, z);
-    const lateral = hit.lateral;
-    if (lateral > profile.reach)
+    const hit = nearestOnCorridor(profile.corridor, x, z, profile.reach);
+    if (hit === null)
         return surrounding;
+    const lateral = hit.lateral;
     const target = clampCutFill(centerlineTarget(profile, hit.along, hit.point, base), surrounding, profile.maxCut, profile.maxFill);
     // Inside the core: carve a channel below the target, deepest at the centerline, level at the edge.
     if (lateral <= profile.half) {

package/dist/world/polylineIndex.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Nearest-point queries against a polyline within a distance bound. The corridor sampler, road
+ * draping and the palette's polyline regions ask "is this vertex near that line?" for every vertex of
+ * a terrain mesh, so a linear scan of every segment per vertex turned one authored road into seconds
+ * of boot time. This keeps the exact same arithmetic as a full scan while visiting only the segments
+ * that can possibly win: a query returns the same segment, the same `t` and the same distance a scan
+ * would, and `null` only when the whole polyline is farther away than the bound.
+ * @internal
+ */
+import type { Vec2 } from "./geometry.js";
+/** Where the polyline comes closest to the query, within the query's bound. @internal */
+export interface PolylineHit {
+    /** Index of the winning segment, i.e. the one from `points[segment]` to `points[segment + 1]`. */
+    segment: number;
+    /** Position along that segment, 0..1. */
+    t: number;
+    /** Distance from the query to the projected point. */
+    distance: number;
+    /** Projected point on the polyline. */
+    point: Vec2;
+}
+/** @internal */
+export interface PolylineIndex {
+    /** Exact nearest segment sample within `limit`, or null when the polyline stays farther away. */
+    nearest(x: number, z: number, limit: number): PolylineHit | null;
+    /** Segments tested by the most recent query — the bounded-work invariant tests assert on. */
+    examined(): number;
+}
+/** @internal */
+export declare function buildPolylineIndex(points: readonly Vec2[]): PolylineIndex;

package/dist/world/polylineIndex.js

@@ -0,0 +1,80 @@
+import { buildSpatialBuckets } from "./spatialBuckets.js";
+/** @internal */
+export function buildPolylineIndex(points) {
+    const count = Math.max(0, points.length - 1);
+    const ax = new Float64Array(count);
+    const az = new Float64Array(count);
+    const abx = new Float64Array(count);
+    const abz = new Float64Array(count);
+    const lengthSq = new Float64Array(count);
+    let minX = Number.POSITIVE_INFINITY;
+    let minZ = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxZ = Number.NEGATIVE_INFINITY;
+    for (let i = 0; i < count; i += 1) {
+        const a = points[i];
+        const b = points[i + 1];
+        ax[i] = a[0];
+        az[i] = a[1];
+        abx[i] = b[0] - a[0];
+        abz[i] = b[1] - a[1];
+        lengthSq[i] = abx[i] * abx[i] + abz[i] * abz[i];
+        minX = Math.min(minX, a[0], b[0]);
+        maxX = Math.max(maxX, a[0], b[0]);
+        minZ = Math.min(minZ, a[1], b[1]);
+        maxZ = Math.max(maxZ, a[1], b[1]);
+    }
+    const span = count === 0 ? 1 : Math.max(maxX - minX, maxZ - minZ, 1);
+    // Twice the average segment length keeps a typical reach inside one or two cells, so a query tests a
+    // handful of segments; the 256-cell cap bounds memory on a very long, very dense polyline.
+    const buckets = buildSpatialBuckets(Math.max(1, span / 256, (span / Math.max(1, count)) * 2));
+    for (let i = 0; i < count; i += 1) {
+        buckets.insert(i, Math.min(ax[i], ax[i] + abx[i]), Math.min(az[i], az[i] + abz[i]), Math.max(ax[i], ax[i] + abx[i]), Math.max(az[i], az[i] + abz[i]));
+    }
+    const candidates = [];
+    let examined = 0;
+    return {
+        nearest(x, z, limit) {
+            if (count === 0 || !(limit >= 0)) {
+                examined = 0;
+                return null;
+            }
+            if (x < minX - limit || x > maxX + limit || z < minZ - limit || z > maxZ + limit) {
+                examined = 0;
+                return null;
+            }
+            // A segment closer than `limit` passes through this box, so it is registered in one of its cells.
+            // Clamping to the polyline's own box keeps an infinite bound from walking an infinite grid.
+            const reach = limit * (1 + 1e-9) + 1e-9;
+            buckets.query(Math.max(minX, x - reach), Math.max(minZ, z - reach), Math.min(maxX, x + reach), Math.min(maxZ, z + reach), candidates);
+            examined = candidates.length;
+            if (candidates.length === 0)
+                return null;
+            let bestSegment = -1;
+            let bestT = 0;
+            let bestDistance = Number.POSITIVE_INFINITY;
+            let bestX = 0;
+            let bestZ = 0;
+            for (const segment of candidates) {
+                const offsetX = x - ax[segment];
+                const offsetZ = z - az[segment];
+                const segLengthSq = lengthSq[segment];
+                const t = segLengthSq <= 0 ? 0 : Math.max(0, Math.min(1, (offsetX * abx[segment] + offsetZ * abz[segment]) / segLengthSq));
+                const px = ax[segment] + abx[segment] * t;
+                const pz = az[segment] + abz[segment] * t;
+                const distance = Math.hypot(x - px, z - pz);
+                if (distance < bestDistance) {
+                    bestDistance = distance;
+                    bestSegment = segment;
+                    bestT = t;
+                    bestX = px;
+                    bestZ = pz;
+                }
+            }
+            if (bestSegment < 0 || bestDistance > limit)
+                return null;
+            return { segment: bestSegment, t: bestT, distance: bestDistance, point: [bestX, bestZ] };
+        },
+        examined: () => examined,
+    };
+}

package/dist/world/spatialBuckets.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Uniform XZ grid over items with a rectangular footprint: insert once, then ask which items cover a
+ * box. One mechanism behind the two sampling hot paths — a corridor's segments and a palette's regions
+ * — so a per-vertex query tests the handful of items nearby instead of every item in the world.
+ * @internal
+ */
+/** @internal */
+export interface SpatialBuckets {
+    /** Register `id` under every cell its rectangle overlaps. Ids are returned in insertion order. */
+    insert(id: number, minX: number, minZ: number, maxX: number, maxZ: number): void;
+    /** Ids whose rectangle overlaps the query box, ascending and deduped, written into `out`. */
+    query(minX: number, minZ: number, maxX: number, maxZ: number, out: number[]): number[];
+}
+/** @internal */
+export declare function buildSpatialBuckets(cellSize: number): SpatialBuckets;

package/dist/world/spatialBuckets.js

@@ -0,0 +1,80 @@
+/**
+ * Uniform XZ grid over items with a rectangular footprint: insert once, then ask which items cover a
+ * box. One mechanism behind the two sampling hot paths — a corridor's segments and a palette's regions
+ * — so a per-vertex query tests the handful of items nearby instead of every item in the world.
+ * @internal
+ */
+/** @internal */
+export function buildSpatialBuckets(cellSize) {
+    const cell = Math.max(1e-6, cellSize);
+    const columns = new Map();
+    let marks = new Int32Array(16);
+    let generation = 0;
+    let highest = -1;
+    const mark = (id) => {
+        if (id <= highest)
+            return;
+        highest = id;
+        if (id < marks.length)
+            return;
+        let size = marks.length;
+        while (size <= id)
+            size *= 2;
+        const grown = new Int32Array(size);
+        grown.set(marks);
+        marks = grown;
+    };
+    return {
+        insert(id, minX, minZ, maxX, maxZ) {
+            mark(id);
+            const cx0 = Math.floor(minX / cell);
+            const cx1 = Math.floor(maxX / cell);
+            const cz0 = Math.floor(minZ / cell);
+            const cz1 = Math.floor(maxZ / cell);
+            for (let cx = cx0; cx <= cx1; cx += 1) {
+                let column = columns.get(cx);
+                if (column === undefined) {
+                    column = new Map();
+                    columns.set(cx, column);
+                }
+                for (let cz = cz0; cz <= cz1; cz += 1) {
+                    const bucket = column.get(cz);
+                    if (bucket === undefined)
+                        column.set(cz, [id]);
+                    else
+                        bucket.push(id);
+                }
+            }
+        },
+        query(minX, minZ, maxX, maxZ, out) {
+            out.length = 0;
+            generation += 1;
+            if (generation >= 2147483647) {
+                marks.fill(0);
+                generation = 1;
+            }
+            const cx0 = Math.floor(minX / cell);
+            const cx1 = Math.floor(maxX / cell);
+            const cz0 = Math.floor(minZ / cell);
+            const cz1 = Math.floor(maxZ / cell);
+            for (let cx = cx0; cx <= cx1; cx += 1) {
+                const column = columns.get(cx);
+                if (column === undefined)
+                    continue;
+                for (let cz = cz0; cz <= cz1; cz += 1) {
+                    const bucket = column.get(cz);
+                    if (bucket === undefined)
+                        continue;
+                    for (const id of bucket) {
+                        if (marks[id] === generation)
+                            continue;
+                        marks[id] = generation;
+                        out.push(id);
+                    }
+                }
+            }
+            out.sort((a, b) => a - b);
+            return out;
+        },
+    };
+}

package/dist/world/terrain.js

@@ -1,5 +1,6 @@
 import { withPathProfiles } from "./pathTerrain.js";
-import { isOnRoad, nearestOnPath } from "./roads.js";
+import { buildPolylineIndex } from "./polylineIndex.js";
+import { buildSpatialBuckets } from "./spatialBuckets.js";
 function clamp01(value) {
     return value < 0 ? 0 : value > 1 ? 1 : value;
 }
@@ -321,10 +322,15 @@ export function flattenFieldAround(base, zones) {
 export function roadDrapedField(base, roads) {
     if (roads.length === 0)
         return base;
+    const draped = roads.map((road) => ({
+        elevation: road.elevation,
+        half: road.width / 2,
+        index: buildPolylineIndex(road.path),
+    }));
     const sampleHeight = (x, z) => {
         let lift = 0;
-        for (const road of roads) {
-            if (road.elevation > lift && isOnRoad(road.path, road.width, x, z))
+        for (const road of draped) {
+            if (road.elevation > lift && road.index.nearest(x, z, road.half) !== null)
                 lift = road.elevation;
         }
         return base.sampleHeight(x, z) + lift;
@@ -680,9 +686,13 @@ export function createTerrainPaletteSampler(descriptor) {
     }));
     if (regions.length === 0 && bandSampler === null)
         return () => base;
+    const buckets = buildSpatialBuckets(PALETTE_REGION_CELL);
+    regions.forEach((region, index) => buckets.insert(index, region.minX, region.minZ, region.maxX, region.maxZ));
+    const nearby = [];
     return (x, z) => {
         let palette = bandSampler === null ? base : bandSampler(z);
-        for (const region of regions) {
+        for (const index of buckets.query(x, z, x, z, nearby)) {
+            const region = regions[index];
             const distance = region.coreDistance(x, z);
             if (distance <= 0) {
                 palette = region.palette;
@@ -695,20 +705,44 @@ export function createTerrainPaletteSampler(descriptor) {
         return palette;
     };
 }
+/**
+ * Cell size for the palette's region index, in world units: coarse enough that inserting a small
+ * region touches one cell, fine enough that a vertex only tests the handful of regions over it.
+ */
+const PALETTE_REGION_CELL = 32;
 /**
  * Resolves a `TerrainMaterialRegion` of any shape to a `coreDistance(x, z)` — 0 inside the painted
- * core, growing positive outward — plus its blend-ring `falloff`, so the palette sampler blends every
- * shape through one shape-agnostic loop.
+ * core, growing positive outward — plus its blend-ring `falloff` and the box a region can paint
+ * inside (core plus blend ring), so the palette sampler blends every shape through one shape-agnostic
+ * loop that only visits regions covering the sample.
  */
 function resolveRegionShape(region) {
     if (region.shape === "polyline") {
         const half = region.width * 0.5;
+        const falloff = region.falloff ?? half;
+        const index = buildPolylineIndex(region.points);
+        const limit = half + falloff;
+        let minX = Number.POSITIVE_INFINITY;
+        let minZ = Number.POSITIVE_INFINITY;
+        let maxX = Number.NEGATIVE_INFINITY;
+        let maxZ = Number.NEGATIVE_INFINITY;
+        for (const point of region.points) {
+            minX = Math.min(minX, point[0]);
+            maxX = Math.max(maxX, point[0]);
+            minZ = Math.min(minZ, point[1]);
+            maxZ = Math.max(maxZ, point[1]);
+        }
+        const empty = region.points.length < 2;
         return {
-            falloff: region.falloff ?? half,
+            falloff,
             coreDistance: (x, z) => {
-                const sample = nearestOnPath(region.points, x, z);
-                return sample === null ? Number.POSITIVE_INFINITY : Math.max(0, sample.distance - half);
+                const hit = index.nearest(x, z, limit);
+                return hit === null ? Number.POSITIVE_INFINITY : Math.max(0, hit.distance - half);
             },
+            minX: empty ? 0 : minX - limit,
+            minZ: empty ? 0 : minZ - limit,
+            maxX: empty ? -1 : maxX + limit,
+            maxZ: empty ? -1 : maxZ + limit,
         };
     }
     if (region.shape === "rect") {
@@ -716,8 +750,11 @@ function resolveRegionShape(region) {
         const angle = region.rotationY ?? 0;
         const cos = Math.cos(angle);
         const sin = Math.sin(angle);
+        const falloff = region.falloff ?? Math.min(hx, hz) * 0.5;
+        const extentX = Math.abs(hx * cos) + Math.abs(hz * sin) + falloff;
+        const extentZ = Math.abs(hx * sin) + Math.abs(hz * cos) + falloff;
         return {
-            falloff: region.falloff ?? Math.min(hx, hz) * 0.5,
+            falloff,
             coreDistance: (x, z) => {
                 const dx = x - region.center[0];
                 const dz = z - region.center[1];
@@ -725,11 +762,21 @@ function resolveRegionShape(region) {
                 const lz = -dx * sin + dz * cos;
                 return Math.hypot(Math.max(0, Math.abs(lx) - hx), Math.max(0, Math.abs(lz) - hz));
             },
+            minX: region.center[0] - extentX,
+            minZ: region.center[1] - extentZ,
+            maxX: region.center[0] + extentX,
+            maxZ: region.center[1] + extentZ,
         };
     }
+    const falloff = region.falloff ?? region.radius * 0.5;
+    const extent = region.radius + falloff;
     return {
-        falloff: region.falloff ?? region.radius * 0.5,
+        falloff,
         coreDistance: (x, z) => Math.max(0, Math.hypot(x - region.center[0], z - region.center[1]) - region.radius),
+        minX: region.center[0] - extent,
+        minZ: region.center[1] - extent,
+        maxX: region.center[0] + extent,
+        maxZ: region.center[1] + extent,
     };
 }
 function withFlattenMasks(sampleHeight, masks) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.34.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.35.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.34.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.35.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -436,7 +436,7 @@
 - `HeadlessCommandInterface` (interface): interface HeadlessCommandInterface — Canvas-free command/intent surface for {@link HeadlessRunner} — invoke a game's registered UI commands and read the resulting reactive state off `ctx`.
 - `HeadlessInput` (interface): interface HeadlessInput — One step's worth of player intent handed to {@link HeadlessRunner.step} — the held-action set and pointer state the shell would otherwise publish from the browser each frame.
 - `HeadlessRunner` (interface): interface HeadlessRunner — A renderer-free driver for a game loop: builds a {@link GameContext} from a {@link GameDefinition}, runs the init hooks, then advances the simulation one step at a time from injected input. No React, R3F, or three.js — the whole play path (time, input, `onTick`, behaviour nav, optional player movement) runs from `core` primitives alone, so a non-React host (a server tick, a test, a CLI replay) can play a real game and read its world snapshot. The shell's FrameDriver is one such driver bolted to `useFrame`; this is the same step distilled out of the render tree.
-- `HeadlessRunnerOptions` (interface): interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> { definition: GameDefinition<TAssetRef, TMultiplayer>; content?: GameContextContent; loop?: GameLoop<GameContext>; player?: {userId: string; isNew: boolean}; now?: () => number; maxStepSeconds?: number; playerMovement?: boolean; movement?: … — ⚠ undocumented
+- `HeadlessRunnerOptions` (interface): interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> { definition: GameDefinition<TAssetRef, TMultiplayer>; content?: GameContextContent; loop?: GameLoop<GameContext>; player?: {userId: string; isNew: boolean}; now?: () => number; seed?: string | number; maxStepSeconds?: number; playerMovemen… — ⚠ undocumented
 - `createHeadlessRunner` (function): function createHeadlessRunner<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HeadlessRunnerOptions<TAssetRef, TMultiplayer>): HeadlessRunner — ⚠ undocumented
 
 ## @jgengine/core/runtime/hostPersistence

package/skills/jgengine-world/api.md

@@ -455,13 +455,22 @@
 - `sumMagnitude` (function): function sumMagnitude<P>(memberships: readonly AreaMembership<P>[], magnitudeOf: MagnitudeOf<P>): number — Sum a numeric magnitude across memberships — additive aggregation for a total field strength (total damage per tick, total slow). A terminal reducer, not a filter, so it returns the number.
 - `uniqueByStackKey` (function): function uniqueByStackKey<P>(magnitudeOf?: MagnitudeOf<P>): AreaStackPolicy<P> — Keep at most one membership per `stackKey`. With `magnitudeOf` the strongest per key wins (ties broken by `sourceId` for determinism); without it the first-seen per key wins. Use for unique-by-key buffs where reapplying the same aura should not stack.
 
+## @jgengine/core/audio/ambience
+
+- `AmbienceWeight` (interface): interface AmbienceWeight — One zone's share of the ambience mix at a listener position, 0..1.
+- `AmbienceZoneDef` (interface): interface AmbienceZoneDef — One ambience zone: a sound bed keyed to a volume of the scene.
+- `AmbienceZoneShape` (type): type AmbienceZoneShape = | { kind: "sphere"; center: readonly [number, number, number]; radius: number } | { kind: "box"; min: readonly [number, number, number]; max: readonly [number, number, number] } — A world-space volume whose sound bed plays while the listener is inside it.
+- `activeAmbienceZone` (function): function activeAmbienceZone(weights: readonly AmbienceWeight[]): string | null — The loudest zone in a weight list, or null when every zone is silent.
+- `ambienceWeights` (function): function ambienceWeights(zones: readonly AmbienceZoneDef[], x: number, y: number, z: number, out: AmbienceWeight[] = []): AmbienceWeight[] — 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.
+- `zoneSignedDistance` (function): function zoneSignedDistance(shape: AmbienceZoneShape, x: number, y: number, z: number): number — Distance from a point to a zone boundary, positive inside and negative outside. Spheres measure from the surface; boxes use the nearest face.
+
 ## @jgengine/core/audio/audioFalloff
 
 - `AudioBusDef` (interface): interface AudioBusDef { id: AudioBusId; gain?: number } — ⚠ undocumented · used by `withFeedbackCueSounds` (@jgengine/core/audio/feedbackCues): Merge the default feedback reactions into a game's sound catalog.
 - `AudioBusId` (type): type AudioBusId = string — ⚠ undocumented
 - `AudioFalloffConfig` (interface): interface AudioFalloffConfig { minDistance?: number; maxDistance?: number; curve?: FalloffCurve } — ⚠ undocumented
 - `FalloffCurve` (type): type FalloffCurve = "linear" | "inverse" | "none" — ⚠ undocumented
-- `SoundDef` (interface): interface SoundDef { id: string; url?: string; synth?: SynthPatch; bus: AudioBusId; gain?: number; loop?: boolean; maxVoices?: number; priority?: number; positional?: boolean; falloff?: AudioFalloffConfig; doppler?: number; spatial?: {panning: "hrtf" | "equal… — ⚠ undocumented · used by `DEFAULT_FEEDBACK_CUE_SOUNDS` (@jgengine/core/audio/feedbackCues): Short procedural reactions - no samples to load, so every game has impact feedback without authoring audio.
+- `SoundDef` (interface): interface SoundDef { id: string; url?: string; synth?: SynthPatch; bus: AudioBusId; gain?: number; loop?: boolean; maxVoices?: number; priority?: number; duck?: {buses?: readonly string[]; amount?: number; seconds?: number;}; positional?: boolean; falloff?: A… — ⚠ undocumented · used by `DEFAULT_FEEDBACK_CUE_SOUNDS` (@jgengine/core/audio/feedbackCues): Short procedural reactions - no samples to load, so every game has impact feedback without authoring audio.
 - `computeFalloffGain` (function): function computeFalloffGain(distance: number, config: AudioFalloffConfig = {}): number — ⚠ undocumented
 - `distance3` (function): function distance3(a: { x: number; y: number; z: number }, b: { x: number; y: number; z: number }): number — ⚠ undocumented
 - `resolveEmitterGain` (function): function resolveEmitterGain(distance: number, sound: Pick<SoundDef, "gain" | "positional" | "falloff">, busGain: number): number — ⚠ undocumented
@@ -513,6 +522,13 @@
 - `createMusicState` (function): function createMusicState(): MusicStateSnapshot — Fresh state with no tier entered, so the first resolve always settles and reports `changed`.
 - `resolveMusicState` (function): function resolveMusicState(state: MusicStateSnapshot, input: MusicStateInput, config: MusicStateConfig): MusicStateResult — Pick the theme for the current intensity. Escalation is immediate; de-escalation waits for the tier's `holdMs` and needs the intensity to fall a `release` margin below the tier it is leaving.
 
+## @jgengine/core/audio/occlusion
+
+- `AUDIO_OCCLUSION_DEFAULTS` (const): const AUDIO_OCCLUSION_DEFAULTS: { readonly maxTestsPerTick: 8; readonly intervalMs: 150; readonly attenuation: 0.55; readonly lowpassHz: 1200; readonly maxDistance: 60; } — Defaults for {@link AudioOcclusionConfig}.
+- `AudioOcclusionConfig` (interface): interface AudioOcclusionConfig — 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.
+- `ResolvedAudioOcclusionConfig` (interface): interface ResolvedAudioOcclusionConfig — A fully specified occlusion policy, with every unset field replaced by its default.
+- `resolveOcclusionConfig` (function): function resolveOcclusionConfig(config: AudioOcclusionConfig | false = {}): ResolvedAudioOcclusionConfig — 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`.
+
 ## @jgengine/core/audio/stepCadence
 
 - `StepCadenceConfig` (interface): interface StepCadenceConfig — Distance-driven footstep cadence. Pure state-in/state-out: feed it how far a mover travelled this frame and it tells you how many steps landed, so foley stays locked to ground distance instead of a wall-clock timer that desyncs when speed changes.
@@ -2859,7 +2875,7 @@
 - `SnapMode` (type): type SnapMode = "grid" | "free" | "surface" — ⚠ undocumented
 - `SnowEnvironmentDescriptor` (type): type SnowEnvironmentDescriptor = { kind: "snow" } & Required< Pick<SnowEnvironmentConfig, "area" | "density" | "speed" | "flakeSize" | "drift" | "wind" | "color" | "opacity"> > — ⚠ undocumented · used by `snow`: Declares a snowfall weather effect for `environment()` — area, density, drift, wind, and flake opacity.
 - `SoilRules` (interface): interface SoilRules — Fully-defaulted soil params parsed from a volume's `meta`.
-- `SoundDef` (interface): interface SoundDef { id: string; url?: string; synth?: SynthPatch; bus: AudioBusId; gain?: number; loop?: boolean; maxVoices?: number; priority?: number; positional?: boolean; falloff?: AudioFalloffConfig; doppler?: number; spatial?: {panning: "hrtf" | "equal… — ⚠ undocumented · used by `DEFAULT_FEEDBACK_CUE_SOUNDS` (@jgengine/core/audio/feedbackCues): Short procedural reactions - no samples to load, so every game has impact feedback without authoring audio.
+- `SoundDef` (interface): interface SoundDef { id: string; url?: string; synth?: SynthPatch; bus: AudioBusId; gain?: number; loop?: boolean; maxVoices?: number; priority?: number; duck?: {buses?: readonly string[]; amount?: number; seconds?: number;}; positional?: boolean; falloff?: A… — ⚠ undocumented · used by `DEFAULT_FEEDBACK_CUE_SOUNDS` (@jgengine/core/audio/feedbackCues): Short procedural reactions - no samples to load, so every game has impact feedback without authoring audio.
 - `SpatialGrid` (class): class SpatialGrid — A uniform-grid broad-phase over the x/z plane, separate from the rigid-body sim, for cheap same-tick proximity across hundreds–thousands of simple movers (swarm enemies). Rebuild each tick from the caller's own position arrays, then `queryCircle` (enemies hitting the player / an AoE) or `forEachPair` (mutual separation). Both are precise: no false negatives, no false positives beyond the exact distance test.
 - `SpawnDirectorConfig` (interface): interface SpawnDirectorConfig { waves: readonly WaveManifest[]; maxAlive?: number; escalationPerSecond?: number; alertBudgetPerSecond?: number; alertDecayPerSecond?: number; playerBudgetPerSecond?: number; maxSpawnsPerTick?: number; loop?: boolean; seed?: number; spawnP… — ⚠ undocumented
 - `SpawnDirectorState` (interface): interface SpawnDirectorState { wave: number; elapsed: number; waveElapsed: number; budget: number; alert: number; spawnedThisWave: number; spawnedTotal: number; rng: RandomSeed; done: boolean } — ⚠ undocumented

package/skills/jgengine-world/capabilities.md

@@ -28,6 +28,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `measureAir` (function) · `import { measureAir } from "@jgengine/core/physics/handlingProbe"`
 
+## 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.
+
+- `AmbienceZoneDef` (interface) · `import { AmbienceZoneDef } from "@jgengine/core/audio/ambience"`
+
 ## anim-graph — data-first animation state machine with blend trees, crossfades, layers, and clip events
 
 - `createAnimGraphRuntime` (function) · `import { createAnimGraphRuntime } from "@jgengine/core/anim/animGraph"`
@@ -109,6 +113,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `defineAttackMoveOrder` (function) · `import { defineAttackMoveOrder } from "@jgengine/core/world"`
 
+## 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.
+
+- `AudioOcclusionConfig` (interface) · `import { AudioOcclusionConfig } from "@jgengine/core/audio/occlusion"`
+
 ## audio-voice-budget — bound simultaneous sound playback with per-sound caps, priorities, and deterministic stealing
 
 - `createVoiceAllocator` (function) · `import { createVoiceAllocator } from "@jgengine/core/audio/voiceAllocator"`