@waica/engine 0.12.0 → 0.13.0

package/dist/archetype.d.ts

@@ -16,6 +16,8 @@ export interface ArchetypeArt {
     file: string;
     /** Registry URI resolved by the archetype at runtime. */
     uri: string;
+    /** What kind of asset this is — a sprite sheet or texture, or a sound file. */
+    kind: 'image' | 'sound';
 }
 /** The conventional contract exported by every archetype package. */
 export interface ArchetypeManifest {
@@ -40,6 +42,15 @@ export interface ArchetypeManifest {
     bundle: ArchetypeBundle;
     /** Directional animation contract, for genres where characters face around. */
     animation?: DirectionalAnimation;
+    /**
+     * The archetype's own looping music bed, as a "waica:" registry uri —
+     * absent for archetypes that ship no music (G8). A host starts it itself
+     * (`game.audio.play(manifest.music, { channel: 'music', loop: true, scope:
+     * 'session' })`) when present; `installArchetype(bundle)` runs before
+     * `new Game(...)` exists, so the bundle has no `game` to call, and this
+     * field is what tells the host what to ask for instead.
+     */
+    music?: string;
 }
 /** Browser manifest enriched with URLs produced by an asset-aware bundler. */
 export interface BrowserArchetypeManifest extends ArchetypeManifest {

package/dist/audio/audio-subsystem.d.ts

@@ -0,0 +1,141 @@
+import type { AudioBackend } from './backend.js';
+import type { AudioChannelState, AudioPlayOptions, LiveSoundInfo, SoundHandle } from './types.js';
+export interface AudioSubsystemOptions {
+    /** The game's canvas — the audio unlock listens for a pointerdown on it (CA-6). */
+    canvas: HTMLCanvasElement;
+    /** Replaces the real WebAudio implementation (ADR 0013); defaults to it. */
+    backend?: AudioBackend;
+    /**
+     * Resolves a uri the same way the scene loader resolves every prefab's
+     * string prop (`resolveProps` in scene.ts), but for direct `play()`/
+     * `preload()` calls — a project role or the host, not a spawned prefab.
+     * Looked up on every call rather than captured once, since `Game` wires
+     * this to its registered scene catalog, which can be (re)registered at
+     * any time and — unlike `Game.registry` — survives `unloadScene()`.
+     * Defaults to identity, so an unresolvable or already-resolved uri (a
+     * pre-resolving caller) passes through unchanged either way.
+     */
+    resolveAsset?: (uri: string) => string;
+}
+/**
+ * The engine's audio mixer (`game.audio`). Talks to WebAudio only through
+ * the AudioBackend seam (ADR 0013), so the whole contract is assertable in
+ * `happy-dom` against an injected fake. A sound dies with its scene unless
+ * it says `{ scope: 'session' }` — the opposite default from GameUi, on
+ * purpose (ADR 0012); `unloadScene()` is Game's hook for that (CA-7).
+ * `updatePlacements()` is Game's per-frame hook for positional audio (CA-8).
+ */
+export declare class AudioSubsystem {
+    private readonly backend;
+    private readonly canvas;
+    private readonly resolveAsset;
+    private readonly channelsMap;
+    private readonly live;
+    /**
+     * Loops requested before unlock (defect: a music bed started at boot,
+     * before any gesture, used to be discarded forever). Each is already in
+     * `live` and already has a real handle; only its attach() to the backend
+     * is deferred until the unlock latch flips. A non-looping call before
+     * unlock is still discarded exactly as before — see `play()`.
+     */
+    private readonly pendingUnlock;
+    private readonly resourceStates;
+    private readonly resourcePromises;
+    private masterVolume;
+    private active;
+    private silenced;
+    private unlocked;
+    /** Whether the backend was last told to be resumed (true) or suspended (false). */
+    private outputLive;
+    constructor(options: AudioSubsystemOptions);
+    /**
+     * Starts a sound. Before the first unlock (CA-6), a one-shot registers
+     * nothing and touches no backend at all — the returned handle just
+     * reports `playing: false` forever. A *looping* call is different: it is
+     * remembered (a deliberate, singular bed, unlike a burst of one-shots
+     * that would all fire at once and sound broken) and started once the
+     * unlock happens, on this same handle — nothing reaches the backend
+     * until then either way. `opts.at` (CA-8, positional audio) sets up
+     * placement tracking; Game calls updatePlacements() once per frame to
+     * actually compute pan/attenuation and forward them to the backend.
+     */
+    play(uri: string, opts?: AudioPlayOptions): SoundHandle;
+    /** Every channel name, factory and runtime-created, in creation order. */
+    channels(): string[];
+    /** A channel's current volume/mute. Reading an unnamed channel reports defaults without creating it. */
+    channelState(name: string): AudioChannelState;
+    setChannelVolume(name: string, volume: number): void;
+    /** Silences (or restores) every sound on the channel without stopping them. */
+    setChannelMuted(name: string, muted: boolean): void;
+    get master(): number;
+    /** Scales every channel's effective output. */
+    set master(value: number);
+    /**
+     * Fetches and decodes every uri ahead of time. Resolves even if one (or
+     * all) of them fail to load — each failure still only warns once, the
+     * same as a failing play() (CA-9).
+     */
+    preload(uris: string[]): Promise<void>;
+    /**
+     * Every sound currently registered with the subsystem — not "every sound
+     * currently audible". A sound enters this set in play() and leaves only
+     * when the backend reports onEnded or drop() removes it, so it also
+     * reports: a loop retained before the autoplay unlock (no backend touched
+     * yet, CA-6); a sound whose load() has not resolved yet; and even one
+     * whose fetch/decode is about to fail, which drops out a tick later once
+     * attach() catches up and calls drop(). Sorted by uri then channel.
+     */
+    liveSounds(): LiveSoundInfo[];
+    /** Called by Game from runFrame: the editor's pause suspends output without touching sounds in flight (CA-4). */
+    setActive(active: boolean): void;
+    /**
+     * Called by Game when a Runtime Bridge registers/unregisters (CA-5).
+     * Registering also counts as an unlock: the Runtime Bridge drives the
+     * game programmatically (injectAction/injectClick), never through a real
+     * trusted keydown/pointerdown, so CA-6's gesture-gate would otherwise
+     * discard every sound for the whole life of an automated run. Silencing
+     * keeps the same run producing no audio output regardless.
+     */
+    setSilenced(silenced: boolean): void;
+    /**
+     * Stops every scene-scoped sound; a sound started with `{ scope: 'session'
+     * }` keeps playing, untouched (CA-7, ADR 0012). Called by Game.unloadScene().
+     */
+    unloadScene(): void;
+    /**
+     * Recomputes pan and distance attenuation for every live sound started
+     * with `at` (CA-8) — called by Game once per frame. `listener` and every
+     * placement's source position are logical coordinates, so attenuation
+     * reflects real game distance; `toRenderSpace` (`game.renderPoint`)
+     * converts both to render space for panning, so an isometric source that
+     * reads to the right on screen pans right regardless of its logical
+     * distance. A sound with no placement (a flat sound) is never touched.
+     */
+    updatePlacements(listener: {
+        x: number;
+        y: number;
+    }, toRenderSpace: (x: number, y: number) => {
+        x: number;
+        y: number;
+    }): void;
+    /** Stops every live sound — including session-scoped ones — and closes the backend (CA-10). */
+    dispose(): void;
+    private ensureChannel;
+    private attach;
+    private startPlayback;
+    private drop;
+    private ensureLoading;
+    private stopSound;
+    private handleFor;
+    private handleUnlockEvent;
+    /**
+     * Flips the one-way unlock latch, detaches the DOM listeners, and releases
+     * every loop that was retained while locked (the boot-music-bed fix) —
+     * without syncing output. Callers decide when to sync so a silencing
+     * change arriving in the same call (setSilenced) composes into a single,
+     * correct resume/suspend decision instead of a spurious resume-then-
+     * suspend pair.
+     */
+    private markUnlocked;
+    private syncOutput;
+}

package/dist/audio/audio-subsystem.js

@@ -0,0 +1,398 @@
+import { Entity } from '../entity.js';
+import { attenuationForDistance, panForOffset } from './spatial.js';
+import { WebAudioBackend } from './web-audio-backend.js';
+function resolvePlacement(at) {
+    if (!at)
+        return null;
+    if (at instanceof Entity)
+        return { kind: 'entity', entity: at };
+    return { kind: 'point', x: at.x, y: at.y };
+}
+const FACTORY_CHANNELS = ['music', 'sfx'];
+/**
+ * The engine's audio mixer (`game.audio`). Talks to WebAudio only through
+ * the AudioBackend seam (ADR 0013), so the whole contract is assertable in
+ * `happy-dom` against an injected fake. A sound dies with its scene unless
+ * it says `{ scope: 'session' }` — the opposite default from GameUi, on
+ * purpose (ADR 0012); `unloadScene()` is Game's hook for that (CA-7).
+ * `updatePlacements()` is Game's per-frame hook for positional audio (CA-8).
+ */
+export class AudioSubsystem {
+    backend;
+    canvas;
+    resolveAsset;
+    channelsMap = new Map();
+    live = new Set();
+    /**
+     * Loops requested before unlock (defect: a music bed started at boot,
+     * before any gesture, used to be discarded forever). Each is already in
+     * `live` and already has a real handle; only its attach() to the backend
+     * is deferred until the unlock latch flips. A non-looping call before
+     * unlock is still discarded exactly as before — see `play()`.
+     */
+    pendingUnlock = new Set();
+    resourceStates = new Map();
+    resourcePromises = new Map();
+    masterVolume = 1;
+    active = true;
+    silenced = false;
+    unlocked = false;
+    /** Whether the backend was last told to be resumed (true) or suspended (false). */
+    outputLive = false;
+    constructor(options) {
+        this.backend = options.backend ?? new WebAudioBackend();
+        this.canvas = options.canvas;
+        this.resolveAsset = options.resolveAsset ?? ((uri) => uri);
+        for (const name of FACTORY_CHANNELS)
+            this.channelsMap.set(name, { volume: 1, muted: false });
+        window.addEventListener('keydown', this.handleUnlockEvent);
+        this.canvas.addEventListener('pointerdown', this.handleUnlockEvent);
+    }
+    /**
+     * Starts a sound. Before the first unlock (CA-6), a one-shot registers
+     * nothing and touches no backend at all — the returned handle just
+     * reports `playing: false` forever. A *looping* call is different: it is
+     * remembered (a deliberate, singular bed, unlike a burst of one-shots
+     * that would all fire at once and sound broken) and started once the
+     * unlock happens, on this same handle — nothing reaches the backend
+     * until then either way. `opts.at` (CA-8, positional audio) sets up
+     * placement tracking; Game calls updatePlacements() once per frame to
+     * actually compute pan/attenuation and forward them to the backend.
+     */
+    play(uri, opts = {}) {
+        const resolvedUri = this.resolveAsset(uri);
+        const channel = opts.channel ?? 'sfx';
+        const volume = opts.volume ?? 1;
+        const loop = opts.loop ?? false;
+        const scope = opts.scope === 'session' ? 'session' : 'scene';
+        const placement = resolvePlacement(opts.at);
+        this.ensureChannel(channel);
+        if (!this.unlocked && !loop)
+            return inertHandle(volume);
+        const sound = {
+            uri: resolvedUri,
+            channel,
+            scope,
+            loop,
+            volume,
+            attenuation: 1,
+            pan: 0,
+            placement,
+            ended: false,
+            backendHandle: null,
+            fading: false,
+        };
+        this.live.add(sound);
+        if (this.unlocked)
+            this.attach(resolvedUri, sound);
+        else
+            this.pendingUnlock.add(sound);
+        return this.handleFor(sound);
+    }
+    /** Every channel name, factory and runtime-created, in creation order. */
+    channels() {
+        return [...this.channelsMap.keys()];
+    }
+    /** A channel's current volume/mute. Reading an unnamed channel reports defaults without creating it. */
+    channelState(name) {
+        const state = this.channelsMap.get(name);
+        return state ? { ...state } : { volume: 1, muted: false };
+    }
+    setChannelVolume(name, volume) {
+        this.ensureChannel(name).volume = volume;
+        this.backend.setChannelVolume(name, volume);
+    }
+    /** Silences (or restores) every sound on the channel without stopping them. */
+    setChannelMuted(name, muted) {
+        this.ensureChannel(name).muted = muted;
+        this.backend.setChannelMuted(name, muted);
+    }
+    get master() {
+        return this.masterVolume;
+    }
+    /** Scales every channel's effective output. */
+    set master(value) {
+        this.masterVolume = value;
+        this.backend.setMasterVolume(value);
+    }
+    /**
+     * Fetches and decodes every uri ahead of time. Resolves even if one (or
+     * all) of them fail to load — each failure still only warns once, the
+     * same as a failing play() (CA-9).
+     */
+    async preload(uris) {
+        await Promise.all(uris.map((uri) => this.ensureLoading(this.resolveAsset(uri))));
+    }
+    /**
+     * Every sound currently registered with the subsystem — not "every sound
+     * currently audible". A sound enters this set in play() and leaves only
+     * when the backend reports onEnded or drop() removes it, so it also
+     * reports: a loop retained before the autoplay unlock (no backend touched
+     * yet, CA-6); a sound whose load() has not resolved yet; and even one
+     * whose fetch/decode is about to fail, which drops out a tick later once
+     * attach() catches up and calls drop(). Sorted by uri then channel.
+     */
+    liveSounds() {
+        return [...this.live]
+            .map(({ uri, channel, scope }) => ({ uri, channel, scope }))
+            .sort((a, b) => (a.uri === b.uri ? a.channel.localeCompare(b.channel) : a.uri.localeCompare(b.uri)));
+    }
+    /** Called by Game from runFrame: the editor's pause suspends output without touching sounds in flight (CA-4). */
+    setActive(active) {
+        if (this.active === active)
+            return;
+        this.active = active;
+        this.syncOutput();
+    }
+    /**
+     * Called by Game when a Runtime Bridge registers/unregisters (CA-5).
+     * Registering also counts as an unlock: the Runtime Bridge drives the
+     * game programmatically (injectAction/injectClick), never through a real
+     * trusted keydown/pointerdown, so CA-6's gesture-gate would otherwise
+     * discard every sound for the whole life of an automated run. Silencing
+     * keeps the same run producing no audio output regardless.
+     */
+    setSilenced(silenced) {
+        if (silenced)
+            this.markUnlocked();
+        if (this.silenced === silenced)
+            return;
+        this.silenced = silenced;
+        this.syncOutput();
+    }
+    /**
+     * Stops every scene-scoped sound; a sound started with `{ scope: 'session'
+     * }` keeps playing, untouched (CA-7, ADR 0012). Called by Game.unloadScene().
+     */
+    unloadScene() {
+        for (const sound of [...this.live]) {
+            if (sound.scope === 'session')
+                continue;
+            this.stopSound(sound, undefined);
+        }
+    }
+    /**
+     * Recomputes pan and distance attenuation for every live sound started
+     * with `at` (CA-8) — called by Game once per frame. `listener` and every
+     * placement's source position are logical coordinates, so attenuation
+     * reflects real game distance; `toRenderSpace` (`game.renderPoint`)
+     * converts both to render space for panning, so an isometric source that
+     * reads to the right on screen pans right regardless of its logical
+     * distance. A sound with no placement (a flat sound) is never touched.
+     */
+    updatePlacements(listener, toRenderSpace) {
+        if (this.live.size === 0)
+            return;
+        let listenerRender = null;
+        for (const sound of this.live) {
+            if (sound.fading)
+                continue;
+            const placement = sound.placement;
+            if (!placement)
+                continue;
+            const source = placement.kind === 'entity'
+                ? { x: placement.entity.position.x, y: placement.entity.position.y }
+                : placement;
+            sound.attenuation = attenuationForDistance(Math.hypot(source.x - listener.x, source.y - listener.y));
+            listenerRender ??= toRenderSpace(listener.x, listener.y);
+            const sourceRender = toRenderSpace(source.x, source.y);
+            sound.pan = panForOffset(sourceRender.x - listenerRender.x);
+            sound.backendHandle?.setVolume(sound.volume * sound.attenuation);
+            sound.backendHandle?.setPan(sound.pan);
+        }
+    }
+    /** Stops every live sound — including session-scoped ones — and closes the backend (CA-10). */
+    dispose() {
+        window.removeEventListener('keydown', this.handleUnlockEvent);
+        this.canvas.removeEventListener('pointerdown', this.handleUnlockEvent);
+        for (const sound of [...this.live]) {
+            sound.ended = true;
+            sound.backendHandle?.stop();
+        }
+        this.live.clear();
+        this.pendingUnlock.clear();
+        this.backend.close();
+    }
+    ensureChannel(name) {
+        let state = this.channelsMap.get(name);
+        if (!state) {
+            state = { volume: 1, muted: false };
+            this.channelsMap.set(name, state);
+        }
+        return state;
+    }
+    attach(uri, sound) {
+        const state = this.resourceStates.get(uri);
+        if (state?.status === 'ready') {
+            this.startPlayback(sound, state.resource);
+            return;
+        }
+        if (state?.status === 'failed') {
+            this.drop(sound);
+            return;
+        }
+        this.ensureLoading(uri)
+            .then(() => {
+            if (sound.ended)
+                return;
+            const resolved = this.resourceStates.get(uri);
+            if (resolved?.status === 'ready')
+                this.startPlayback(sound, resolved.resource);
+            else
+                this.drop(sound);
+        })
+            .catch(() => {
+            // ensureLoading never rejects; this is defensive, never expected to run.
+            this.drop(sound);
+        });
+    }
+    startPlayback(sound, resource) {
+        sound.backendHandle = this.backend.play(resource, {
+            channel: sound.channel,
+            volume: sound.volume * sound.attenuation,
+            loop: sound.loop,
+            onEnded: () => {
+                if (sound.ended)
+                    return;
+                sound.ended = true;
+                this.live.delete(sound);
+            },
+        });
+        // A placement update may have already run while this sound was still
+        // loading (CA-8) — carry its pan over now that a backend handle exists.
+        if (sound.placement)
+            sound.backendHandle.setPan(sound.pan);
+    }
+    drop(sound) {
+        sound.ended = true;
+        this.live.delete(sound);
+    }
+    ensureLoading(uri) {
+        const existing = this.resourcePromises.get(uri);
+        if (existing)
+            return existing;
+        this.resourceStates.set(uri, { status: 'pending' });
+        const promise = this.backend.load(uri).then((resource) => {
+            this.resourceStates.set(uri, { status: 'ready', resource });
+        }, (error) => {
+            console.warn(`[waica] audio: failed to load "${uri}"`, error);
+            this.resourceStates.set(uri, { status: 'failed' });
+        });
+        this.resourcePromises.set(uri, promise);
+        return promise;
+    }
+    stopSound(sound, fadeMs) {
+        if (sound.ended)
+            return;
+        if (!sound.backendHandle) {
+            // Still loading: nothing audible exists yet to fade, so cancel
+            // outright — it must never start once the load resolves.
+            this.drop(sound);
+            return;
+        }
+        if (fadeMs && this.outputLive) {
+            sound.fading = true;
+            sound.backendHandle.stop(fadeMs);
+            // playing stays true until the backend's onEnded fires, once the ramp completes.
+        }
+        else {
+            // Either no fade was requested, or output is currently suspended
+            // (setActive(false) / setSilenced(true)): the real backend schedules
+            // the ramp and the source's stop() against context.currentTime, which
+            // does not advance while suspended, so neither would ever come due —
+            // onEnded would never fire and the sound would stay `playing: true`
+            // forever. Falling back to an immediate stop sidesteps that: this
+            // branch never waits for the backend's onEnded anyway, it finishes
+            // the sound in the model synchronously right here.
+            sound.ended = true;
+            this.live.delete(sound);
+            sound.backendHandle.stop();
+        }
+    }
+    handleFor(sound) {
+        const subsystem = this;
+        return {
+            get playing() {
+                return !sound.ended;
+            },
+            get volume() {
+                return sound.volume;
+            },
+            set volume(value) {
+                sound.volume = value;
+                // While a fade-out ramp is running (fading), skip the backend write:
+                // a plain gain assignment is equivalent to a setValueAtTime inserted
+                // before the ramp's end (Web Audio spec), which jumps the gain back
+                // up and only then resumes descending — cutting the fade short,
+                // same mechanism updatePlacements() already guards against. The
+                // stored value above is updated regardless, so the sound reads back
+                // correctly however long it stays `fading` before it truly ends.
+                if (!sound.fading)
+                    sound.backendHandle?.setVolume(value * sound.attenuation);
+            },
+            stop(opts = {}) {
+                subsystem.stopSound(sound, opts.fadeMs);
+            },
+        };
+    }
+    handleUnlockEvent = () => {
+        this.markUnlocked();
+        this.syncOutput();
+    };
+    /**
+     * Flips the one-way unlock latch, detaches the DOM listeners, and releases
+     * every loop that was retained while locked (the boot-music-bed fix) —
+     * without syncing output. Callers decide when to sync so a silencing
+     * change arriving in the same call (setSilenced) composes into a single,
+     * correct resume/suspend decision instead of a spurious resume-then-
+     * suspend pair.
+     */
+    markUnlocked() {
+        if (this.unlocked)
+            return;
+        this.unlocked = true;
+        window.removeEventListener('keydown', this.handleUnlockEvent);
+        this.canvas.removeEventListener('pointerdown', this.handleUnlockEvent);
+        const pending = [...this.pendingUnlock];
+        this.pendingUnlock.clear();
+        for (const sound of pending) {
+            // stop() while still pending drops the sound outright (no backend
+            // handle to fade) and marks it ended — it must never start.
+            if (sound.ended)
+                continue;
+            this.attach(sound.uri, sound);
+        }
+    }
+    syncOutput() {
+        const desired = this.unlocked && this.active && !this.silenced;
+        if (desired === this.outputLive)
+            return;
+        this.outputLive = desired;
+        if (desired)
+            this.backend.resume();
+        else
+            this.backend.suspend();
+    }
+}
+/**
+ * Returned by play() for a non-looping call made before the first unlock:
+ * registers nothing in `live`, touches no backend, and reports `playing`
+ * false forever. A uri already known to have failed takes a different path
+ * — it still registers a real sound (attach() -> drop()), so play() returns
+ * a handleFor() handle whose `sound.ended` is already true instead of this one.
+ */
+function inertHandle(initialVolume) {
+    let volume = initialVolume;
+    return {
+        get playing() {
+            return false;
+        },
+        get volume() {
+            return volume;
+        },
+        set volume(value) {
+            volume = value;
+        },
+        stop() { },
+    };
+}

package/dist/audio/backend.d.ts

@@ -0,0 +1,69 @@
+/**
+ * A decoded, backend-specific playback resource (e.g. a real AudioBuffer).
+ * Opaque to the audio subsystem: it caches these by uri and hands them back
+ * to `play()` unchanged.
+ */
+export type AudioResource = unknown;
+export interface BackendPlayOptions {
+    /** Mixer channel this sound plays through (e.g. 'sfx', 'music'). */
+    channel: string;
+    /** The sound's own gain, independent of the channel/master mix. */
+    volume: number;
+    loop: boolean;
+    /**
+     * Called exactly once, when the sound truly stops producing audio:
+     * reaching its natural end, or after stop()/a fade-out ramp completes.
+     * Never called for a sound still looping.
+     */
+    onEnded: () => void;
+}
+export interface BackendPlayHandle {
+    /** Changes the sound's own gain while it plays. */
+    setVolume(volume: number): void;
+    /**
+     * Sets the stereo pan in [-1, 1] (-1 fully left, 0 centered, 1 fully
+     * right). Only ever called for a sound started with `at` (CA-8); a flat
+     * sound never receives a call.
+     */
+    setPan(pan: number): void;
+    /**
+     * Stops the sound. With no fadeMs, releases immediately (onEnded still
+     * fires, but the caller doesn't wait for it). With fadeMs, ramps gain to
+     * zero over that many milliseconds before releasing — onEnded fires once
+     * the ramp completes, not before. Idempotent.
+     */
+    stop(fadeMs?: number): void;
+}
+/**
+ * The seam ADR 0013 exists for: everything Game needs from WebAudio,
+ * abstracted so `happy-dom` — which has no AudioContext, AudioBuffer or
+ * GainNode at all — can exercise the whole audio contract against an
+ * injected fake. The real implementation (see web-audio-backend.ts) is the
+ * default; a host replaces it via `GameOptions.audio`, e.g. to test its own
+ * project's audio without a browser.
+ */
+export interface AudioBackend {
+    /**
+     * Fetches and decodes a uri into an opaque resource. The subsystem calls
+     * this at most once per uri — the result is cached and reused.
+     */
+    load(uri: string): Promise<AudioResource>;
+    /** Starts playing a decoded resource. */
+    play(resource: AudioResource, options: BackendPlayOptions): BackendPlayHandle;
+    /** Sets a channel's own gain (independent of mute). */
+    setChannelVolume(channel: string, volume: number): void;
+    /** Silences (true) or restores (false) every sound on a channel without stopping them. */
+    setChannelMuted(channel: string, muted: boolean): void;
+    /** Scales every channel's effective output. */
+    setMasterVolume(volume: number): void;
+    /** Freezes all output; sounds in flight are neither stopped nor restarted. */
+    suspend(): void;
+    /**
+     * Resumes output. The real implementation lazily creates its underlying
+     * AudioContext here (or at load()) — never eagerly, and never in a
+     * constructor — so nothing touches the device before an unlock (CA-6).
+     */
+    resume(): void;
+    /** Stops everything permanently and releases the underlying context. */
+    close(): void;
+}

package/dist/audio/backend.js

@@ -0,0 +1 @@
+export {};

package/dist/audio/spatial.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Engine constants for CA-8 positional audio. There are no public tuning
+ * knobs (spec decision 20): the curve is picked once, in the spirit of
+ * `CAMERA_DEFAULTS` (`camera.ts`), and frozen — CA-21 is the human-only
+ * game-feel pass that may revisit these numbers by ear, never a per-call or
+ * per-channel option.
+ *
+ * The attenuation curve mirrors WebAudio's own `PannerNode` "linear"
+ * distance model: full volume at or inside `referenceDistance`, a straight
+ * ramp down to silence at `maxDistance`, silent beyond it. `panDistance` is
+ * the render-space horizontal offset (world units) that reaches full
+ * left/right pan.
+ */
+export declare const AUDIO_SPATIAL_DEFAULTS: {
+    readonly referenceDistance: 3;
+    readonly maxDistance: 16;
+    readonly panDistance: 6;
+};
+/** 1 at/inside referenceDistance, 0 at/beyond maxDistance, linear in between. */
+export declare function attenuationForDistance(distance: number): number;
+/** Maps a render-space horizontal offset (source minus listener) to a [-1, 1] stereo pan. */
+export declare function panForOffset(dx: number): number;

package/dist/audio/spatial.js

@@ -0,0 +1,32 @@
+/**
+ * Engine constants for CA-8 positional audio. There are no public tuning
+ * knobs (spec decision 20): the curve is picked once, in the spirit of
+ * `CAMERA_DEFAULTS` (`camera.ts`), and frozen — CA-21 is the human-only
+ * game-feel pass that may revisit these numbers by ear, never a per-call or
+ * per-channel option.
+ *
+ * The attenuation curve mirrors WebAudio's own `PannerNode` "linear"
+ * distance model: full volume at or inside `referenceDistance`, a straight
+ * ramp down to silence at `maxDistance`, silent beyond it. `panDistance` is
+ * the render-space horizontal offset (world units) that reaches full
+ * left/right pan.
+ */
+export const AUDIO_SPATIAL_DEFAULTS = {
+    referenceDistance: 3,
+    maxDistance: 16,
+    panDistance: 6,
+};
+/** 1 at/inside referenceDistance, 0 at/beyond maxDistance, linear in between. */
+export function attenuationForDistance(distance) {
+    const { referenceDistance, maxDistance } = AUDIO_SPATIAL_DEFAULTS;
+    if (distance <= referenceDistance)
+        return 1;
+    if (distance >= maxDistance)
+        return 0;
+    return 1 - (distance - referenceDistance) / (maxDistance - referenceDistance);
+}
+/** Maps a render-space horizontal offset (source minus listener) to a [-1, 1] stereo pan. */
+export function panForOffset(dx) {
+    const { panDistance } = AUDIO_SPATIAL_DEFAULTS;
+    return Math.max(-1, Math.min(1, dx / panDistance));
+}

package/dist/audio/types.d.ts

@@ -0,0 +1,42 @@
+import type { Entity } from '../entity.js';
+export interface AudioPlayOptions {
+    /** Mixer channel; defaults to 'sfx'. Naming any other channel creates it at volume 1. */
+    channel?: string;
+    /** The sound's own gain, independent of the channel/master mix. Defaults to 1. */
+    volume?: number;
+    loop?: boolean;
+    /**
+     * 'session' survives Game.unloadScene() (CA-7); omitted means scene-scoped
+     * — the default, and the common case (ADR 0012).
+     */
+    scope?: 'session';
+    /**
+     * Positional playback (CA-8). An `Entity` tracks its current position
+     * every frame; a plain `{ x, y }` fixes the placement. Omitted, the sound
+     * is flat: no panning, no distance attenuation. Attenuation is computed
+     * from the distance to the listener (the camera) in logical coordinates;
+     * panning is computed from both positions after `game.renderPoint()`, so
+     * an isometric source that reads to the right on screen pans right even
+     * though its volume reflects real (logical) game distance.
+     */
+    at?: Entity | {
+        x: number;
+        y: number;
+    };
+}
+export interface SoundHandle {
+    stop(opts?: {
+        fadeMs?: number;
+    }): void;
+    readonly playing: boolean;
+    volume: number;
+}
+export interface AudioChannelState {
+    volume: number;
+    muted: boolean;
+}
+export interface LiveSoundInfo {
+    uri: string;
+    channel: string;
+    scope: 'scene' | 'session';
+}

package/dist/audio/types.js

@@ -0,0 +1 @@
+export {};

package/dist/audio/web-audio-backend.d.ts

@@ -0,0 +1,39 @@
+import type { AudioBackend, AudioResource, BackendPlayHandle, BackendPlayOptions } from './backend.js';
+/**
+ * The real WebAudio implementation (ADR 0013's default). Builds a small
+ * mixing graph — one GainNode per sound feeding a StereoPannerNode, feeding
+ * a per-channel GainNode, feeding a single master GainNode — so
+ * muting/volume/master changes are plain WebAudio gain assignments, and
+ * positional panning (CA-8) is a plain WebAudio pan assignment, neither
+ * something this class recomputes by hand for every live sound.
+ *
+ * The AudioContext itself is never created eagerly: `happy-dom` (this
+ * repo's test environment) has no AudioContext/AudioBuffer/GainNode at all,
+ * and real browsers block unsolicited audio output before a user gesture.
+ * `ensureContext()` is the one lazy constructor, reached only from
+ * `resume()` (the unlock, CA-6) or `load()` (so `preload()` can decode
+ * ahead of an unlock). If AudioContext isn't available in the current
+ * environment, every method degrades to a safe no-op / rejected load
+ * instead of throwing — the audio subsystem's own load-failure handling
+ * (CA-9) turns that rejection into a single warning, never a crash.
+ */
+export declare class WebAudioBackend implements AudioBackend {
+    private context;
+    private masterGain;
+    private masterVolume;
+    private readonly channelGains;
+    private readonly channelVolumes;
+    private readonly channelMuted;
+    load(uri: string): Promise<AudioResource>;
+    play(resource: AudioResource, options: BackendPlayOptions): BackendPlayHandle;
+    setChannelVolume(channel: string, volume: number): void;
+    setChannelMuted(channel: string, muted: boolean): void;
+    setMasterVolume(volume: number): void;
+    suspend(): void;
+    resume(): void;
+    close(): void;
+    private ensureContext;
+    private ensureChannelGain;
+    private applyChannelGain;
+    private effectiveChannelGain;
+}

package/dist/audio/web-audio-backend.js

@@ -0,0 +1,149 @@
+/**
+ * The real WebAudio implementation (ADR 0013's default). Builds a small
+ * mixing graph — one GainNode per sound feeding a StereoPannerNode, feeding
+ * a per-channel GainNode, feeding a single master GainNode — so
+ * muting/volume/master changes are plain WebAudio gain assignments, and
+ * positional panning (CA-8) is a plain WebAudio pan assignment, neither
+ * something this class recomputes by hand for every live sound.
+ *
+ * The AudioContext itself is never created eagerly: `happy-dom` (this
+ * repo's test environment) has no AudioContext/AudioBuffer/GainNode at all,
+ * and real browsers block unsolicited audio output before a user gesture.
+ * `ensureContext()` is the one lazy constructor, reached only from
+ * `resume()` (the unlock, CA-6) or `load()` (so `preload()` can decode
+ * ahead of an unlock). If AudioContext isn't available in the current
+ * environment, every method degrades to a safe no-op / rejected load
+ * instead of throwing — the audio subsystem's own load-failure handling
+ * (CA-9) turns that rejection into a single warning, never a crash.
+ */
+export class WebAudioBackend {
+    context = null;
+    masterGain = null;
+    masterVolume = 1;
+    channelGains = new Map();
+    channelVolumes = new Map();
+    channelMuted = new Map();
+    async load(uri) {
+        const context = this.ensureContext();
+        if (!context)
+            throw new Error('AudioContext is not available in this environment');
+        const response = await fetch(uri);
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status} fetching "${uri}"`);
+        const data = await response.arrayBuffer();
+        return context.decodeAudioData(data);
+    }
+    play(resource, options) {
+        const context = this.ensureContext();
+        if (!context)
+            return noopHandle();
+        const source = context.createBufferSource();
+        source.buffer = resource;
+        source.loop = options.loop;
+        const soundGain = context.createGain();
+        soundGain.gain.value = options.volume;
+        const panner = context.createStereoPanner();
+        source.connect(soundGain);
+        soundGain.connect(panner);
+        panner.connect(this.ensureChannelGain(options.channel));
+        let ended = false;
+        const finish = () => {
+            if (ended)
+                return;
+            ended = true;
+            options.onEnded();
+        };
+        source.onended = finish;
+        source.start();
+        return {
+            setVolume: (volume) => {
+                soundGain.gain.value = volume;
+            },
+            setPan: (pan) => {
+                panner.pan.value = pan;
+            },
+            stop: (fadeMs) => {
+                if (ended)
+                    return;
+                const now = context.currentTime;
+                if (fadeMs && fadeMs > 0) {
+                    soundGain.gain.linearRampToValueAtTime(0, now + fadeMs / 1000);
+                    source.stop(now + fadeMs / 1000);
+                }
+                else {
+                    source.stop();
+                }
+            },
+        };
+    }
+    setChannelVolume(channel, volume) {
+        this.channelVolumes.set(channel, volume);
+        this.applyChannelGain(channel);
+    }
+    setChannelMuted(channel, muted) {
+        this.channelMuted.set(channel, muted);
+        this.applyChannelGain(channel);
+    }
+    setMasterVolume(volume) {
+        this.masterVolume = volume;
+        if (this.masterGain)
+            this.masterGain.gain.value = volume;
+    }
+    suspend() {
+        void this.context?.suspend();
+    }
+    resume() {
+        void this.ensureContext()?.resume();
+    }
+    close() {
+        void this.context?.close();
+        this.context = null;
+        this.masterGain = null;
+        this.channelGains.clear();
+    }
+    ensureContext() {
+        if (this.context)
+            return this.context;
+        if (typeof AudioContext === 'undefined')
+            return null;
+        const context = new AudioContext();
+        this.context = context;
+        const masterGain = context.createGain();
+        masterGain.gain.value = this.masterVolume;
+        masterGain.connect(context.destination);
+        this.masterGain = masterGain;
+        for (const channel of this.channelVolumes.keys())
+            this.ensureChannelGain(channel);
+        return context;
+    }
+    ensureChannelGain(channel) {
+        const existing = this.channelGains.get(channel);
+        if (existing)
+            return existing;
+        // Safe: only called once ensureContext() has already produced a context.
+        const context = this.context;
+        const gain = context.createGain();
+        gain.gain.value = this.effectiveChannelGain(channel);
+        gain.connect(this.masterGain);
+        this.channelGains.set(channel, gain);
+        return gain;
+    }
+    applyChannelGain(channel) {
+        const gain = this.channelGains.get(channel);
+        if (gain)
+            gain.gain.value = this.effectiveChannelGain(channel);
+    }
+    effectiveChannelGain(channel) {
+        if (this.channelMuted.get(channel))
+            return 0;
+        return this.channelVolumes.get(channel) ?? 1;
+    }
+}
+/** Returned when the environment has no AudioContext at all: inert, never throws. */
+function noopHandle() {
+    return {
+        setVolume: () => { },
+        setPan: () => { },
+        stop: () => { },
+    };
+}

package/dist/component.d.ts

@@ -10,7 +10,7 @@ export interface ParamSpec {
     /** Allowed values for a string param; rendered as a dropdown. Takes precedence over ref. */
     options?: string[];
     /** Project value this string param names; rendered and validated as a typed reference. */
-    ref?: 'prefab' | 'stat' | 'action' | 'clip';
+    ref?: 'prefab' | 'stat' | 'action' | 'clip' | 'sound';
 }
 export interface ComponentClass<T extends Component = Component> {
     new (): T;

package/dist/game.d.ts

@@ -1,4 +1,6 @@
 import * as THREE from 'three';
+import type { AudioBackend } from './audio/backend.js';
+import { AudioSubsystem } from './audio/audio-subsystem.js';
 import { type SceneCameraJson } from './camera.js';
 import type { Component } from './component.js';
 import { Entity } from './entity.js';
@@ -26,6 +28,14 @@ export interface GameOptions {
     bindings?: InputBindings;
     /** Initial stat values (points, lives…) from the project's stats.json. */
     stats?: Record<string, StatValue>;
+    /**
+     * Replaces the real WebAudio implementation (ADR 0013) — mainly for a
+     * project's own tests, since `happy-dom` has no AudioContext, AudioBuffer
+     * or GainNode at all. Defaults to the real backend either way; `game.audio`
+     * always exists, and the real AudioContext is constructed lazily, at the
+     * first unlock (CA-6), never eagerly here.
+     */
+    audio?: AudioBackend;
 }
 export type UpdateFn = (dt: number) => void;
 export interface SpawnPrefabOptions {
@@ -53,6 +63,8 @@ export declare class Game {
     readonly stats: Stats;
     /** The HTML UI layer: presentation-only pieces toggled from code. */
     readonly ui: GameUi;
+    /** The audio mixer: channels, master, playback. See ADR 0012, ADR 0013. */
+    readonly audio: AudioSubsystem;
     /** Registry retained by loadScene for runtime prefab spawning. */
     registry: SceneRegistry | null;
     paramOverrides: ParamOverrides;
@@ -156,6 +168,14 @@ export declare class Game {
     private componentUpdateSchedule;
     private updateSceneCamera;
     private renderPoint;
+    /**
+     * The audio listener's position (CA-8) in logical coordinates. The camera
+     * itself only ever holds render-space coordinates (see `updateSceneCamera`,
+     * `setSceneCamera`), so under `projection: 'isometric'` this is the exact
+     * inverse of `renderPoint` — without it, distance-based attenuation would
+     * measure render-space distance instead of real game distance.
+     */
+    private audioListenerPosition;
     private dispatchCollisions;
     private resize;
 }

package/dist/game.js

@@ -1,4 +1,5 @@
 import * as THREE from 'three';
+import { AudioSubsystem } from './audio/audio-subsystem.js';
 import { collisionOverlap } from './collision-shape.js';
 import { isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera, } from './camera.js';
 import { resolveComponentUpdateSchedule } from './component-update-schedule.js';
@@ -9,7 +10,7 @@ import { Input } from './input.js';
 import { Pointer } from './pointer.js';
 import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.js';
 import { RuntimeInspector } from './runtime-inspection.js';
-import { projectIsometric } from './projection.js';
+import { projectIsometric, unprojectIsometric } from './projection.js';
 import { isYSortParticipant, ySortZ } from './render-sort.js';
 import { loadScene, registryEntry, spawnFromJson, } from './scene.js';
 import { Stats } from './stats.js';
@@ -28,6 +29,8 @@ export class Game {
     stats;
     /** The HTML UI layer: presentation-only pieces toggled from code. */
     ui;
+    /** The audio mixer: channels, master, playback. See ADR 0012, ADR 0013. */
+    audio;
     /** Registry retained by loadScene for runtime prefab spawning. */
     registry = null;
     paramOverrides = {};
@@ -66,6 +69,15 @@ export class Game {
         this.input = new Input(options.bindings);
         this.stats = new Stats(options.stats);
         this.ui = new GameUi(this.stats, () => canvas.parentElement ?? document.body);
+        this.audio = new AudioSubsystem({
+            canvas,
+            backend: options.audio,
+            // The catalog registered via registerSceneCatalog, never game.registry:
+            // unloadScene() nulls the latter but leaves the catalog (and its
+            // resolver) untouched, which is exactly what a { scope: 'session' }
+            // music bed needs across a scene swap.
+            resolveAsset: (uri) => this.sceneCatalog?.registry.resolveAsset?.(uri) ?? uri,
+        });
         this.renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
         this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
         this.scene.background = new THREE.Color(background);
@@ -119,6 +131,7 @@ export class Game {
      */
     unloadScene() {
         this.ui.unloadScene();
+        this.audio.unloadScene();
         // An explicit unload means "no scene": a swap queued earlier this frame
         // would otherwise flush next frame and resurrect one.
         this.pendingSceneLoad = null;
@@ -266,6 +279,7 @@ export class Game {
                     availableScenes: () => this.availableScenes,
                 });
                 activation.register(this.runtimeBridge);
+                this.audio.setSilenced(true);
                 window.addEventListener('pagehide', this.unregisterRuntimeBridge);
             }
             this.renderSurface();
@@ -302,6 +316,7 @@ export class Game {
         this.pointer.dispose();
         this.resizeObserver.disconnect();
         this.ui.dispose();
+        this.audio.dispose();
         for (const entity of [...this.entities])
             entity.destroy();
         this.renderer.dispose();
@@ -340,6 +355,11 @@ export class Game {
             }
             // The UI must react to the pause itself (hide until resumed).
             this.ui.setActive(this.simulate);
+            this.audio.setActive(this.simulate);
+            // Positional audio (CA-8): recomputed every frame, on this same pass —
+            // never a second walk of `this.entities`, since `this.audio` already
+            // holds direct references to whichever entities are tracked.
+            this.audio.updatePlacements(this.audioListenerPosition(), (x, y) => this.renderPoint(x, y));
             for (const fn of this.updateFns)
                 fn(dt);
             this.input.endFrame();
@@ -360,6 +380,7 @@ export class Game {
         window.removeEventListener('pagehide', this.unregisterRuntimeBridge);
         this.runtimeBridge?.unregister();
         this.runtimeBridge = null;
+        this.audio.setSilenced(false);
     };
     /** Under y-sort, re-derives every participant's z from layer band + entity Y. */
     applyYSort() {
@@ -456,6 +477,17 @@ export class Game {
     renderPoint(x, y) {
         return this.sceneProjection === 'isometric' ? projectIsometric(x, y) : { x, y };
     }
+    /**
+     * The audio listener's position (CA-8) in logical coordinates. The camera
+     * itself only ever holds render-space coordinates (see `updateSceneCamera`,
+     * `setSceneCamera`), so under `projection: 'isometric'` this is the exact
+     * inverse of `renderPoint` — without it, distance-based attenuation would
+     * measure render-space distance instead of real game distance.
+     */
+    audioListenerPosition() {
+        const { x, y } = this.camera.position;
+        return this.sceneProjection === 'isometric' ? unprojectIsometric(x, y) : { x, y };
+    }
     dispatchCollisions() {
         const boxed = this.entities.filter((e) => e.has(Hitbox));
         for (let i = 0; i < boxed.length; i++) {

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 export { Game } from './game.js';
 export type { GameOptions, GameResolution, SceneCatalog, SpawnPrefabOptions, UpdateFn, ParamOverrides, } from './game.js';
+export { AudioSubsystem } from './audio/audio-subsystem.js';
+export type { AudioSubsystemOptions } from './audio/audio-subsystem.js';
+export type { AudioBackend, AudioResource, BackendPlayHandle, BackendPlayOptions } from './audio/backend.js';
+export type { AudioChannelState, AudioPlayOptions, LiveSoundInfo, SoundHandle } from './audio/types.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export type { AnimationFacingProvider, DirectionalAnimation, DirectionalFallback, ResolvedDirectionalClip, } from './animation/directional.js';
 export { isYSortParticipant, ySortZ } from './render-sort.js';
@@ -25,7 +29,7 @@ export type { PointerCamera, PointerDeps, PointerPick, PointerResolution } from
 export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export type { RuntimeBridge, RuntimeBridgeActivation, RuntimeControlRequest, RuntimeControlResult, RuntimeMetadata, RuntimeMode, } from './runtime-bridge.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
-export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotFilters, RuntimeTransformSnapshot, } from './runtime-inspection.js';
+export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotAudio, RuntimeSnapshotFilters, RuntimeTransformSnapshot, } from './runtime-inspection.js';
 export type { ArchetypeArt, ArchetypeManifest, BrowserArchetypeManifest, EntityTemplate, } from './archetype.js';
 export { Stats } from './stats.js';
 export type { StatValue } from './stats.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { Game } from './game.js';
+export { AudioSubsystem } from './audio/audio-subsystem.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export { isYSortParticipant, ySortZ } from './render-sort.js';
 export { projectIsometric, screenInputToLogical, unprojectIsometric } from './projection.js';

package/dist/runtime-inspection.d.ts

@@ -1,3 +1,4 @@
+import type { AudioChannelState, LiveSoundInfo } from './audio/types.js';
 import type { Game } from './game.js';
 import type { RuntimeMetadata } from './runtime-bridge.js';
 import type { StatValue } from './stats.js';
@@ -48,12 +49,29 @@ export interface RuntimeEntitySnapshot {
     transform: RuntimeTransformSnapshot;
     components: RuntimeComponentSnapshot[];
 }
+/**
+ * The mixer's state (CA-15): `master` and every channel's volume/mute,
+ * sorted by name, plus `playing` — `game.audio.liveSounds()` verbatim,
+ * already sorted (by uri then channel). Despite the name, `playing` is not
+ * "every currently-audible sound": per `liveSounds()`'s own docstring it
+ * also carries a loop retained before the autoplay unlock, a sound still
+ * loading, and even one about to fail to load (gone a tick later). Emitted
+ * unconditionally, like every other snapshot section —
+ * `[DEVIATION 2026-09-08]` in the spec: no section of RuntimeSnapshot is
+ * filterable today, so audio does not invent the first one.
+ */
+export interface RuntimeSnapshotAudio {
+    master: number;
+    channels: Record<string, AudioChannelState>;
+    playing: LiveSoundInfo[];
+}
 export interface RuntimeSnapshot extends RuntimeMetadata {
     stats: Record<string, StatValue>;
     /** The live scene's name (its catalog key), or null with no scene loaded. */
     scene: string | null;
     entities: RuntimeEntitySnapshot[];
     projectionIssues: ProjectionIssue[];
+    audio: RuntimeSnapshotAudio;
 }
 export declare const RUNTIME_PROJECTION_LIMITS: {
     readonly depth: 5;
@@ -68,6 +86,7 @@ export declare class RuntimeInspector {
     private nextId;
     constructor(game: Game);
     snapshot(metadata: RuntimeMetadata, filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
+    private audioSnapshot;
     private capSnapshot;
     private idFor;
 }

package/dist/runtime-inspection.js

@@ -237,8 +237,20 @@ export class RuntimeInspector {
             scene: this.game.sceneName,
             entities,
             projectionIssues,
+            audio: this.audioSnapshot(),
         });
     }
+    audioSnapshot() {
+        const channels = {};
+        for (const name of this.game.audio.channels().sort()) {
+            channels[name] = this.game.audio.channelState(name);
+        }
+        return {
+            master: this.game.audio.master,
+            channels,
+            playing: this.game.audio.liveSounds(),
+        };
+    }
     capSnapshot(snapshot) {
         if (utf8Bytes(JSON.stringify(snapshot)) <= RUNTIME_PROJECTION_LIMITS.snapshotBytes) {
             return snapshot;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",