@jgengine/shell 0.33.0 → 0.35.0

package/dist/audio/audioEngine.js

@@ -1,5 +1,7 @@
+import { activeAmbienceZone, ambienceWeights } from "@jgengine/core/audio/ambience";
 import { distance3, resolveEmitterGain } from "@jgengine/core/audio/audioFalloff";
 import { dopplerRate } from "@jgengine/core/audio/doppler";
+import { resolveOcclusionConfig } from "@jgengine/core/audio/occlusion";
 import { patchDuration } from "@jgengine/core/audio/synth";
 import { createVoiceAllocator } from "@jgengine/core/audio/voiceAllocator";
 import { createDisposer } from "@jgengine/core/game/defineGame";
@@ -8,11 +10,16 @@ import { MusicDirector } from "./musicDirector.js";
 import { createNoiseBuffer, realizeSynthPatch } from "./synthEngine.js";
 /** setTargetAtTime time constant (~20 ms) for zipper-free live rate/gain ramps on retained loops (#1051). */
 const LOOP_PARAM_SMOOTH_TC = 0.02;
+/** Ambient beds ramp over ~80 ms so crossing a zone boundary never steps a gain. */
+const BED_SMOOTH_TC = 0.08;
+/** Ducking ramps over ~30 ms: fast enough to feel like a cut, slow enough not to click. */
+const DUCK_SMOOTH_TC = 0.03;
 const ZERO_VELOCITY = { x: 0, y: 0, z: 0 };
 /** Cues held while the browser keeps the audio context suspended, before any user gesture. */
 export const MAX_PENDING_CUES = 16;
 function createNoopEngine() {
     const level = { rms: 0, peak: 0 };
+    const stats = { tests: 0, blocked: 0, testMs: 0, perTestMs: 0, lastTest: null };
     return {
         setListenerPose: () => undefined,
         setVoiceLimit: () => undefined,
@@ -20,6 +27,10 @@ function createNoopEngine() {
         playOneShot: () => undefined,
         playLoop: () => null,
         playMusic: () => undefined,
+        setOcclusionSource: () => undefined,
+        occlusionStats: () => stats,
+        ambience: () => ({ zone: null, levels: [] }),
+        duck: () => () => undefined,
         setBusGain: () => undefined,
         setBusMute: () => undefined,
         setMasterGain: () => undefined,
@@ -102,7 +113,8 @@ export function createAudioEngine(config = {}) {
         return createNoopEngine();
     }
     const busGains = new Map();
-    // Authored gain survives a mute, so unmuting restores the player's volume exactly.
+    // Authored gain survives a mute, so unmuting restores the player's volume exactly. `duck` is a
+    // separate multiplier a cue applies for its own duration, so it never overwrites that volume.
     const busMix = new Map();
     let masterVolume = 1;
     let masterMuted = false;
@@ -115,7 +127,7 @@ export function createAudioEngine(config = {}) {
     function busMixOf(busId) {
         let mix = busMix.get(busId);
         if (mix === undefined) {
-            mix = { gain: busDefs[busId]?.gain ?? 1, muted: false };
+            mix = { gain: busDefs[busId]?.gain ?? 1, muted: false, duck: 0 };
             busMix.set(busId, mix);
         }
         return mix;
@@ -124,7 +136,9 @@ export function createAudioEngine(config = {}) {
         const mix = busMix.get(busId);
         if (mix === undefined)
             return busDefs[busId]?.gain ?? 1;
-        return mix.muted ? 0 : mix.gain;
+        if (mix.muted)
+            return 0;
+        return mix.gain * (1 - mix.duck);
     }
     function busGainNode(busId) {
         let node = busGains.get(busId);
@@ -147,6 +161,73 @@ export function createAudioEngine(config = {}) {
         if (node !== undefined)
             node.gain.value = busLevel(busId);
     }
+    const duckHolds = new Map();
+    /** Recompute the strongest hold on one bus; release restores the player's gain by construction. */
+    function applyDuck(busId) {
+        const holds = duckHolds.get(busId);
+        let amount = 0;
+        if (holds !== undefined) {
+            for (const hold of holds)
+                amount = Math.max(amount, hold.amount);
+        }
+        const mix = busMixOf(busId);
+        mix.duck = Math.min(1, Math.max(0, amount));
+        const node = busGains.get(busId);
+        if (node === undefined)
+            return;
+        const level = busLevel(busId);
+        if (typeof node.gain.setTargetAtTime === "function") {
+            node.gain.setTargetAtTime(level, context.currentTime, DUCK_SMOOTH_TC);
+        }
+        else {
+            node.gain.value = level;
+        }
+    }
+    function duckBus(busId, options = {}) {
+        if (disposed)
+            return () => undefined;
+        const amount = Math.min(1, Math.max(0, options.amount ?? 0.6));
+        if (amount <= 0)
+            return () => undefined;
+        const hold = { amount, timer: undefined };
+        let holds = duckHolds.get(busId);
+        if (holds === undefined) {
+            holds = new Set();
+            duckHolds.set(busId, holds);
+        }
+        holds.add(hold);
+        applyDuck(busId);
+        let released = false;
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            if (hold.timer !== undefined)
+                clearTimeout(hold.timer);
+            const current = duckHolds.get(busId);
+            current?.delete(hold);
+            if (current !== undefined && current.size === 0)
+                duckHolds.delete(busId);
+            applyDuck(busId);
+        };
+        const seconds = options.seconds;
+        if (seconds !== undefined && Number.isFinite(seconds) && seconds > 0 && typeof setTimeout === "function") {
+            hold.timer = setTimeout(release, seconds * 1000);
+            hold.timer.unref?.();
+        }
+        return release;
+    }
+    /** A cue's own `duck` policy: hold the named buses for its duration, then release. */
+    function applyCueDuck(sound, durationSeconds) {
+        const policy = sound.duck;
+        if (policy === undefined)
+            return;
+        const seconds = policy.seconds !== undefined && Number.isFinite(policy.seconds) ? policy.seconds : durationSeconds;
+        const buses = policy.buses ?? ["music"];
+        for (const busId of buses) {
+            duckBus(busId, seconds > 0 ? { amount: policy.amount, seconds } : { amount: policy.amount });
+        }
+    }
     let noiseBuffer = null;
     function sharedNoiseBuffer() {
         if (noiseBuffer === null)
@@ -214,6 +295,139 @@ export function createAudioEngine(config = {}) {
         setAudioParam(param, value);
         return true;
     }
+    const occlusionConfig = resolveOcclusionConfig(config.occlusion);
+    let occlusionBlocked = null;
+    let occlusionTestsLeft = occlusionConfig.maxTestsPerTick;
+    const occlusionStatsState = { tests: 0, blocked: 0, testMs: 0, lastTest: null };
+    const occlusionTargets = new Set();
+    function clockMs() {
+        return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+    }
+    /**
+     * One budgeted test for one retained loop. Skipped while the loop is too close (the listener is
+     * inside its own engine hum), too far, or re-tested inside the interval; once the tick's budget
+     * is spent every other loop simply stays on distance-only attenuation.
+     */
+    function requestOcclusionTest(target) {
+        if (occlusionBlocked === null || occlusionConfig.maxTestsPerTick <= 0) {
+            target.set(0);
+            return;
+        }
+        const distance = distance3(target, listenerPosition);
+        if (distance < 1 || distance > occlusionConfig.maxDistance) {
+            target.set(0);
+            return;
+        }
+        const now = context.currentTime;
+        if (now - target.lastTest < occlusionConfig.intervalMs / 1000)
+            return;
+        if (occlusionTestsLeft <= 0) {
+            if (!target.tested)
+                target.set(0);
+            return;
+        }
+        occlusionTestsLeft -= 1;
+        target.lastTest = now;
+        target.tested = true;
+        const started = clockMs();
+        let blocked = false;
+        const from = { x: listenerPosition.x, y: listenerPosition.y, z: listenerPosition.z };
+        const to = { x: target.x, y: target.y, z: target.z };
+        try {
+            blocked = occlusionBlocked(from, to);
+        }
+        catch {
+            blocked = false;
+        }
+        occlusionStatsState.testMs += clockMs() - started;
+        occlusionStatsState.tests += 1;
+        occlusionStatsState.lastTest = { from, to, blocked };
+        if (blocked)
+            occlusionStatsState.blocked += 1;
+        target.set(blocked ? 1 : 0);
+    }
+    function stepOcclusion() {
+        occlusionTestsLeft = occlusionConfig.maxTestsPerTick;
+        for (const target of occlusionTargets)
+            requestOcclusionTest(target);
+    }
+    const zones = config.zones ?? [];
+    const zoneBeds = new Map();
+    const ambienceScratch = [];
+    let ambienceActive = null;
+    let ambienceInitialized = false;
+    function zoneWeight(id) {
+        for (const entry of ambienceScratch) {
+            if (entry.id === id)
+                return entry.weight;
+        }
+        return 0;
+    }
+    function ensureBed(zone, sound) {
+        const existing = zoneBeds.get(zone.id);
+        if (existing !== undefined)
+            return existing;
+        let bus;
+        try {
+            bus = busGainNode(sound.bus);
+        }
+        catch {
+            return null;
+        }
+        const gain = context.createGain();
+        gain.gain.value = 0;
+        gain.connect(bus);
+        const bed = { gain, source: null, level: -1 };
+        zoneBeds.set(zone.id, bed);
+        const pending = sound.synth !== undefined
+            ? renderSynthBuffer(zone.sound, sound.synth)
+            : sound.url !== undefined
+                ? loadBuffer(sound.url)
+                : Promise.resolve(null);
+        void pending.then((buffer) => {
+            if (disposed || buffer === null || zoneBeds.get(zone.id) !== bed) {
+                gain.disconnect();
+                return;
+            }
+            try {
+                // A looping AudioBufferSourceNode repeats sample-accurately, so the bed has no gap at the seam.
+                const source = context.createBufferSource();
+                source.buffer = buffer;
+                source.loop = true;
+                source.connect(gain);
+                source.start();
+                bed.source = source;
+                applyAmbience();
+            }
+            catch {
+                gain.disconnect();
+            }
+        }).catch(() => undefined);
+        return bed;
+    }
+    function applyAmbience() {
+        if (zones.length === 0)
+            return;
+        ambienceWeights(zones, listenerPosition.x, listenerPosition.y, listenerPosition.z, ambienceScratch);
+        ambienceActive = activeAmbienceZone(ambienceScratch);
+        for (const zone of zones) {
+            const weight = zoneWeight(zone.id);
+            const existing = zoneBeds.get(zone.id);
+            if (weight <= 0 && existing === undefined)
+                continue;
+            const sound = sounds[zone.sound];
+            if (sound === undefined)
+                continue;
+            const bed = existing ?? ensureBed(zone, sound);
+            if (bed === null)
+                continue;
+            const level = weight * (zone.gain ?? 1) * (sound.gain ?? 1);
+            if (level === bed.level)
+                continue;
+            bed.level = level;
+            bed.gain.gain.setTargetAtTime(level, context.currentTime, BED_SMOOTH_TC);
+        }
+    }
     // Browser autoplay: until the first user gesture the context stays suspended and a played cue
     // would vanish. Hold a bounded FIFO of ids (preallocated slots) and flush it on resume.
     const pendingCues = Array.from({ length: MAX_PENDING_CUES }, () => ({
@@ -336,6 +550,7 @@ export function createAudioEngine(config = {}) {
         }
         const currentPosition = { ...(position ?? listenerPosition) };
         if (sound.synth !== undefined && !loop) {
+            applyCueDuck(sound, patchDuration(sound.synth));
             let cueGain = null;
             let panner = null;
             let playback = null;
@@ -400,6 +615,7 @@ export function createAudioEngine(config = {}) {
         let currentUserGain = 1;
         let currentLowpass = MAX_LOOP_CUTOFF;
         let currentHighpass = MIN_LOOP_CUTOFF;
+        let currentOcclusion = 0;
         let currentVelocity = { x: 0, y: 0, z: 0 };
         const dopplerFactor = loop ? sound.doppler ?? 0 : 0;
         let sourceNode = null;
@@ -417,6 +633,24 @@ export function createAudioEngine(config = {}) {
         let writtenGain = NaN;
         let writtenLowpass = NaN;
         let writtenHighpass = NaN;
+        function applyOcclusionAmount(amount) {
+            const next = Math.min(1, Math.max(0, Number.isFinite(amount) ? amount : 0));
+            if (next === currentOcclusion)
+                return;
+            currentOcclusion = next;
+            applyUserGain();
+            applyLowpass();
+        }
+        const occlusionTarget = {
+            x: initialPosition.x,
+            y: initialPosition.y,
+            z: initialPosition.z,
+            lastTest: -Infinity,
+            tested: false,
+            set: applyOcclusionAmount,
+        };
+        if (loop)
+            occlusionTargets.add(occlusionTarget);
         function effectiveRate() {
             if (dopplerFactor === 0)
                 return currentRate;
@@ -432,6 +666,34 @@ export function createAudioEngine(config = {}) {
             writtenRate = rate;
             sourceNode.playbackRate.setTargetAtTime(rate, context.currentTime, LOOP_PARAM_SMOOTH_TC);
         }
+        /** Player/loop gain composed with occlusion; the game's own gain is never overwritten by it. */
+        function effectiveUserGain() {
+            const blocked = occlusionConfig.attenuation + (1 - occlusionConfig.attenuation) * (1 - currentOcclusion);
+            return clampLoopGain(currentUserGain) * blocked;
+        }
+        function applyUserGain() {
+            const gain = effectiveUserGain();
+            if (gain === writtenGain)
+                return;
+            writtenGain = gain;
+            if (userGainNode !== null)
+                userGainNode.gain.setTargetAtTime(gain, context.currentTime, LOOP_PARAM_SMOOTH_TC);
+        }
+        /** Darkest of the game's own cutoff and the occlusion floor, blended by the blocked amount. */
+        function effectiveLowpass() {
+            if (currentOcclusion <= 0)
+                return currentLowpass;
+            const floor = Math.min(currentLowpass, occlusionConfig.lowpassHz);
+            return currentLowpass - (currentLowpass - floor) * currentOcclusion;
+        }
+        function applyLowpass() {
+            const cutoff = clampLoopCutoff(effectiveLowpass(), MAX_LOOP_CUTOFF, nyquist);
+            if (cutoff === writtenLowpass)
+                return;
+            writtenLowpass = cutoff;
+            if (lowpassNode !== null)
+                lowpassNode.frequency.setTargetAtTime(cutoff, context.currentTime, LOOP_PARAM_SMOOTH_TC);
+        }
         function updateFalloff() {
             if (falloffGain !== null && spatial === undefined) {
                 const gain = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
@@ -458,6 +720,7 @@ export function createAudioEngine(config = {}) {
                 applyRate();
         }
         disposer.onDispose(() => {
+            occlusionTargets.delete(occlusionTarget);
             if (sourceNode !== null)
                 sourceNode.onended = null;
             try {
@@ -485,6 +748,8 @@ export function createAudioEngine(config = {}) {
                 handle.stop();
                 return;
             }
+            if (!loop)
+                applyCueDuck(sound, buffer.duration);
             const src = context.createBufferSource();
             sourceNode = src;
             src.buffer = buffer;
@@ -494,7 +759,7 @@ export function createAudioEngine(config = {}) {
             // Spatial panners own distance attenuation; the scalar stage keeps only authored gain.
             const uGain = context.createGain();
             userGainNode = uGain;
-            writtenGain = currentUserGain;
+            writtenGain = effectiveUserGain();
             uGain.gain.value = writtenGain;
             const fGain = context.createGain();
             falloffGain = fGain;
@@ -504,7 +769,7 @@ export function createAudioEngine(config = {}) {
                 const lp = context.createBiquadFilter();
                 lowpassNode = lp;
                 lp.type = "lowpass";
-                writtenLowpass = clampLoopCutoff(currentLowpass, MAX_LOOP_CUTOFF, nyquist);
+                writtenLowpass = clampLoopCutoff(effectiveLowpass(), MAX_LOOP_CUTOFF, nyquist);
                 lp.frequency.value = writtenLowpass;
                 const hp = context.createBiquadFilter();
                 highpassNode = hp;
@@ -536,6 +801,8 @@ export function createAudioEngine(config = {}) {
             src.start();
         }).catch(() => handle.stop());
         activeSpatialUpdaters.add(updateFalloff);
+        if (loop)
+            requestOcclusionTest(occlusionTarget);
         const handle = {
             isPlaying: () => !stopped,
             setPosition(next) {
@@ -544,7 +811,12 @@ export function createAudioEngine(config = {}) {
                 currentPosition.x = next.x;
                 currentPosition.y = next.y;
                 currentPosition.z = next.z;
+                occlusionTarget.x = next.x;
+                occlusionTarget.y = next.y;
+                occlusionTarget.z = next.z;
                 updateFalloff();
+                if (loop)
+                    requestOcclusionTest(occlusionTarget);
             },
             setRate(rate) {
                 currentRate = clampLoopRate(rate);
@@ -552,11 +824,7 @@ export function createAudioEngine(config = {}) {
             },
             setLowpass(hz) {
                 currentLowpass = clampLoopCutoff(hz, MAX_LOOP_CUTOFF, nyquist);
-                if (currentLowpass === writtenLowpass)
-                    return;
-                writtenLowpass = currentLowpass;
-                if (lowpassNode !== null)
-                    lowpassNode.frequency.setTargetAtTime(currentLowpass, context.currentTime, LOOP_PARAM_SMOOTH_TC);
+                applyLowpass();
             },
             setHighpass(hz) {
                 currentHighpass = clampLoopCutoff(hz, MIN_LOOP_CUTOFF, nyquist);
@@ -575,11 +843,10 @@ export function createAudioEngine(config = {}) {
             },
             setGain(gain) {
                 currentUserGain = clampLoopGain(gain);
-                if (currentUserGain === writtenGain)
-                    return;
-                writtenGain = currentUserGain;
-                if (userGainNode !== null)
-                    userGainNode.gain.setTargetAtTime(currentUserGain, context.currentTime, LOOP_PARAM_SMOOTH_TC);
+                applyUserGain();
+            },
+            setOcclusion(amount) {
+                applyOcclusionAmount(amount);
             },
             stop() {
                 if (stopped)
@@ -605,6 +872,9 @@ export function createAudioEngine(config = {}) {
             if (disposed)
                 return;
             const pose = "position" in position ? position : { position, forward: { x: 0, y: 0, z: -1 }, up: { x: 0, y: 1, z: 0 } };
+            const positionChanged = listenerPosition.x !== pose.position.x ||
+                listenerPosition.y !== pose.position.y ||
+                listenerPosition.z !== pose.position.z;
             listenerPosition.x = pose.position.x;
             listenerPosition.y = pose.position.y;
             listenerPosition.z = pose.position.z;
@@ -613,6 +883,10 @@ export function createAudioEngine(config = {}) {
             listenerVelocity.y = velocity.y;
             listenerVelocity.z = velocity.z;
             const listener = context.listener;
+            if (positionChanged || !ambienceInitialized) {
+                ambienceInitialized = true;
+                applyAmbience();
+            }
             let listenerMoved = writeChanged(listenerWritten, 0, listener.positionX, pose.position.x);
             listenerMoved = writeChanged(listenerWritten, 1, listener.positionY, pose.position.y) || listenerMoved;
             listenerMoved = writeChanged(listenerWritten, 2, listener.positionZ, pose.position.z) || listenerMoved;
@@ -626,6 +900,8 @@ export function createAudioEngine(config = {}) {
             let velocityChanged = writeChanged(listenerVelocityWritten, 0, undefined, velocity.x);
             velocityChanged = writeChanged(listenerVelocityWritten, 1, undefined, velocity.y) || velocityChanged;
             velocityChanged = writeChanged(listenerVelocityWritten, 2, undefined, velocity.z) || velocityChanged;
+            if (positionChanged)
+                stepOcclusion();
             if (!listenerMoved && !velocityChanged)
                 return;
             for (const updateGain of activeSpatialUpdaters)
@@ -646,6 +922,31 @@ export function createAudioEngine(config = {}) {
             void context.resume().catch(() => undefined);
             musicDirector()?.crossfadeTo(themeId, options);
         },
+        setOcclusionSource(blocked) {
+            if (disposed)
+                return;
+            occlusionBlocked = blocked;
+            if (blocked === null) {
+                for (const target of occlusionTargets)
+                    target.set(0);
+                return;
+            }
+            stepOcclusion();
+        },
+        occlusionStats() {
+            const { tests, blocked, testMs, lastTest } = occlusionStatsState;
+            return { tests, blocked, testMs, perTestMs: tests > 0 ? testMs / tests : 0, lastTest };
+        },
+        ambience() {
+            const levels = [];
+            for (const zone of zones) {
+                const weight = zoneWeight(zone.id);
+                if (weight > 0)
+                    levels.push({ id: zone.id, level: weight * (zone.gain ?? 1) });
+            }
+            return { zone: ambienceActive, levels };
+        },
+        duck: duckBus,
         setBusGain(busId, gain) {
             if (disposed)
                 return;
@@ -688,6 +989,24 @@ export function createAudioEngine(config = {}) {
             for (const stop of [...activeVoices.values()])
                 stop();
             activeSpatialUpdaters.clear();
+            occlusionTargets.clear();
+            for (const bed of zoneBeds.values()) {
+                try {
+                    bed.source?.stop();
+                }
+                catch {
+                }
+                bed.source?.disconnect();
+                bed.gain.disconnect();
+            }
+            zoneBeds.clear();
+            for (const holds of duckHolds.values()) {
+                for (const hold of holds) {
+                    if (hold.timer !== undefined)
+                        clearTimeout(hold.timer);
+                }
+            }
+            duckHolds.clear();
             director?.dispose();
             for (const node of busGains.values())
                 node.disconnect();

package/dist/audio/audioProbe.d.ts

@@ -1,12 +1,16 @@
-import type { AudioEngine, AudioLevel } from "./audioEngine.js";
+import type { AudioAmbienceState, AudioEngine, AudioLevel, AudioOcclusionStats } from "./audioEngine.js";
 /** The read-only handle a capture script or devtools uses to prove the mix is producing sound. */
 export interface AudioProbe {
     /** Master RMS and peak since the last read, `0..1`. Non-zero RMS means audio reached the output. */
     measure(): AudioLevel;
     /** Master gain after volume and mute. */
     masterLevel(): number;
-    /** One bus's effective gain after its volume and mute. */
+    /** One bus's effective gain after its volume, mute and any active duck. */
     busLevel(busId: string): number;
+    /** Current zone mix, so a capture can state which zone bed is audible and at what level. */
+    ambience(): AudioAmbienceState;
+    /** Cumulative geometry-occlusion cost, so a capture can state the measured per-test price. */
+    occlusion(): AudioOcclusionStats;
 }
 declare global {
     interface Window {
@@ -14,9 +18,10 @@ declare global {
     }
 }
 /**
- * Publish the audio engine's own level readout on `window.__jgengineAudio`, so a headless capture can
- * state a measured RMS instead of guessing from a screenshot. Reads only; it never plays or changes a bus.
+ * Publish the audio engine's own level, ambience and occlusion readouts on `window.__jgengineAudio`,
+ * so a headless capture can state measured values instead of guessing from a screenshot. Reads only;
+ * it never plays or changes a bus.
  *
- * @capability audio-probe read the live master RMS/peak and bus gains from a running page for capture and diagnostics
+ * @capability audio-probe read the live master RMS/peak, bus gains, ambience zone mix and occlusion cost from a running page for capture and diagnostics
  */
 export declare function installAudioProbe(engine: AudioEngine): () => void;

package/dist/audio/audioProbe.js

@@ -1,8 +1,9 @@
 /**
- * Publish the audio engine's own level readout on `window.__jgengineAudio`, so a headless capture can
- * state a measured RMS instead of guessing from a screenshot. Reads only; it never plays or changes a bus.
+ * Publish the audio engine's own level, ambience and occlusion readouts on `window.__jgengineAudio`,
+ * so a headless capture can state measured values instead of guessing from a screenshot. Reads only;
+ * it never plays or changes a bus.
  *
- * @capability audio-probe read the live master RMS/peak and bus gains from a running page for capture and diagnostics
+ * @capability audio-probe read the live master RMS/peak, bus gains, ambience zone mix and occlusion cost from a running page for capture and diagnostics
  */
 export function installAudioProbe(engine) {
     if (typeof window === "undefined")
@@ -11,6 +12,8 @@ export function installAudioProbe(engine) {
         measure: () => engine.measure(),
         masterLevel: () => engine.masterLevel(),
         busLevel: (busId) => engine.busLevel(busId),
+        ambience: () => engine.ambience(),
+        occlusion: () => engine.occlusionStats(),
     };
     window.__jgengineAudio = probe;
     return () => {

package/dist/audio/occlusion.d.ts

@@ -0,0 +1,11 @@
+import type { SceneRaycastHit, SceneRaycastInput } from "@jgengine/core/scene/sceneRaycast";
+import type { Vec3 } from "./audioEngine.js";
+/** The narrow slice of the scene a line-of-hearing test needs. */
+export interface BlockingRaycastSource {
+    raycast(input: SceneRaycastInput): SceneRaycastHit | null;
+}
+/**
+ * Whether blocking world geometry (objects and wall segments, never creatures or terrain) lies
+ * between the listener and an emitter. One scene query per call; the engine owns how often it runs.
+ */
+export declare function sceneLineBlocked(source: BlockingRaycastSource, from: Vec3, to: Vec3): boolean;

package/dist/audio/occlusion.js

@@ -0,0 +1,20 @@
+/**
+ * Whether blocking world geometry (objects and wall segments, never creatures or terrain) lies
+ * between the listener and an emitter. One scene query per call; the engine owns how often it runs.
+ */
+export function sceneLineBlocked(source, from, to) {
+    const dx = to.x - from.x;
+    const dy = to.y - from.y;
+    const dz = to.z - from.z;
+    const length = Math.hypot(dx, dy, dz);
+    if (!(length > 0.001))
+        return false;
+    const hit = source.raycast({
+        origin: [from.x, from.y, from.z],
+        direction: [dx / length, dy / length, dz / length],
+        maxDistance: length - 0.001,
+        filter: { entities: false, terrain: false },
+        accept: (candidate) => candidate.blocks,
+    });
+    return hit !== null;
+}

package/dist/play/index.d.ts

@@ -0,0 +1,3 @@
+export { createPlayScript, PLAY_MOVE_ACTIONS, type PlayAimStep, type PlayCommandStep, type PlayExpectation, type PlayFireStep, type PlayMove, type PlayMoveStep, type PlayScript, type PlayScriptSpec, type PlayStep, type PlayUseStep, type PlayValue, type PlayWaitStep, } from "./script.js";
+export { playTimelineDigest, formatPlayTimelineEntry, type PlayExpectationResult, type PlayRunResult, type PlayTimelineEntry, type PlayTimelineKind, } from "./timeline.js";
+export { runPlayScript, type PlayRunOptions } from "./run.js";

package/dist/play/index.js

@@ -0,0 +1,3 @@
+export { createPlayScript, PLAY_MOVE_ACTIONS, } from "./script.js";
+export { playTimelineDigest, formatPlayTimelineEntry, } from "./timeline.js";
+export { runPlayScript } from "./run.js";

package/dist/play/run.d.ts

@@ -0,0 +1,27 @@
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { PlayableGame } from "../registry.js";
+import { type PlayScript, type PlayScriptSpec } from "./script.js";
+import { type PlayRunResult } from "./timeline.js";
+/** Options for one scripted play run. */
+export interface PlayRunOptions {
+    /** Local player id the script acts as. Default `"player"`. */
+    userId?: string;
+    /** Override the script's fixed tick length, in seconds. */
+    dt?: number;
+    /** Stop recording world events after this many rows so a long run stays readable. Default 1000. */
+    maxEvents?: number;
+    /** Called after `setup` and after every tick, for a script that wants to watch the run (progress bars, debug output). */
+    onTick?: (tick: number, ctx: GameContext) => void;
+}
+/**
+ * Play a real game without a browser: boot its `PlayableGame` through the headless runner, apply a
+ * tick-based {@link PlayScript}, and return what happened plus whether the script's assertions held.
+ *
+ * Runs the shell's own per-tick pipeline, not an imitation of it — held movement actions reach the walk
+ * controller, a held `fire` (or any game action) resolves to its bound command on the press tick and on
+ * its repeat cadence, `interact` picks the active proximity prompt, and a hotbar press activates the
+ * slot. So a script proves the same code path a player's hands prove, in seconds.
+ *
+ * @capability play-script play a real game from a deterministic script — spawn, move, aim, fire, command, and assert world state with no browser and no wall clock
+ */
+export declare function runPlayScript(playable: PlayableGame, spec: PlayScript | PlayScriptSpec, options?: PlayRunOptions): PlayRunResult;