@waica/engine 0.11.0 → 0.13.0

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;
@@ -69,6 +69,11 @@ export declare abstract class Component {
     onCollide?(other: Entity): void;
     /** Runs when this entity's DynamicBody physically contacts a Solid. */
     onContact?(contact: SolidContact): void;
+    /**
+     * Runs when this entity wins the nearest-Interactable scan and the
+     * initiator interacts with it (a keypress or a click-to-move NPC order).
+     */
+    onInteract?(initiator: Entity): void;
     /** Runs when the entity is destroyed or the component removed. */
     onDestroy?(): void;
 }

package/dist/game.d.ts

@@ -1,11 +1,13 @@
 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';
 import { Emitter } from './events.js';
 import { Input, type InputBindings } from './input.js';
 import { Pointer } from './pointer.js';
-import { type SceneRegistry, type SceneRenderJson } from './scene.js';
+import { type SceneJson, type SceneRegistry, type SceneRenderJson } from './scene.js';
 import { Stats, type StatValue } from './stats.js';
 import { GameUi } from './ui.js';
 /** Fixed game resolution: the view keeps this aspect, letterboxed. */
@@ -26,12 +28,25 @@ 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 {
     name?: string;
     position?: [number, number];
 }
+/** The Project's scenes by name (a file's stem), plus the registry shared by all of them. */
+export interface SceneCatalog {
+    scenes: Record<string, SceneJson>;
+    registry: SceneRegistry;
+}
 /** Persisted overrides: entity → componentName → prop → value. */
 export type ParamOverrides = Record<string, Record<string, Record<string, number | boolean | string>>>;
 /**
@@ -48,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;
@@ -61,12 +78,22 @@ export declare class Game {
     private readonly updateFns;
     private readonly invalidUpdateCompositions;
     private readonly resolution;
+    /** The constructor's viewHeight — unloadScene() restores it. */
+    private readonly baseViewHeight;
     private viewHeight;
     private sceneCamera;
     private renderSort;
     private sceneProjection;
     private lastTime;
     private runtimeBridge;
+    /** Host-registered scenes by name, resolved by loadSceneByName. Session-scoped. */
+    private sceneCatalog;
+    /** The live scene's name (its catalog key), or null with no scene loaded. */
+    private liveSceneName;
+    /** True for the whole extent of a runFrame() call, incl. its tail. */
+    private insideFrame;
+    /** A loadSceneByName() enqueued while insideFrame; applied at the next runFrame's start. */
+    private pendingSceneLoad;
     constructor(options: GameOptions);
     /** Creates a live entity in the scene. */
     spawn(name: string): Entity;
@@ -74,6 +101,35 @@ export declare class Game {
     spawnPrefab(prefab: string, options?: SpawnPrefabOptions): Entity | null;
     /** Finds an entity by name. */
     find(name: string): Entity | undefined;
+    /**
+     * Destroys the live scene — every entity (Entity.destroy(), so onDestroy
+     * cascades and GPU resources release) and its scene-scoped UI — and
+     * leaves the Game as newly constructed: no registry, no scene camera, no
+     * render sort or projection, viewHeight back to the constructor's.
+     * Session-scoped state (stats, paramOverrides, subscriptions, the scene
+     * catalog) is untouched. See ADR 0011. Public: the seam `loadScene` calls
+     * to replace a scene, and how a host leaves the Game with none loaded.
+     */
+    unloadScene(): void;
+    /** Registers the Project's scenes by name, resolved by loadSceneByName. */
+    registerSceneCatalog(catalog: SceneCatalog): void;
+    /** The live scene's name (its catalog key), or null with no scene loaded. */
+    get sceneName(): string | null;
+    /** Names registered via registerSceneCatalog, in registration order. */
+    get availableScenes(): string[];
+    /**
+     * Resolves `name` through the registered catalog and loads it, replacing
+     * the live scene. An unknown name warns and leaves the live scene
+     * untouched. Triggered mid-frame (e.g. from a SceneTransition's
+     * onCollide/onInteract) the swap is deferred to the very start of the
+     * next runFrame — dispatchCollisions finishes its double loop over the
+     * outgoing scene, and the incoming scene's entities are present only
+     * from the next frame. Called from outside a frame (boot, or the Runtime
+     * Bridge's `scene` control operation) it applies synchronously and wins
+     * over anything queued earlier this frame. A second mid-frame request
+     * loses to the first and says so. Returns whether the load took effect.
+     */
+    loadSceneByName(name: string): boolean;
     /** Loads persisted parameter overrides (waica.params.json). */
     loadParams(url: string): Promise<void>;
     /** Applies persisted overrides to a freshly added component. */
@@ -104,6 +160,7 @@ export declare class Game {
     private resumeRuntime;
     private tick;
     private runFrame;
+    private flushPendingSceneLoad;
     private unregisterRuntimeBridge;
     /** Under y-sort, re-derives every participant's z from layer band + entity Y. */
     private applyYSort;
@@ -111,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,9 +10,9 @@ 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 { registryEntry, spawnFromJson } from './scene.js';
+import { loadScene, registryEntry, spawnFromJson, } from './scene.js';
 import { Stats } from './stats.js';
 import { GameUi } from './ui.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 = {};
@@ -42,19 +45,39 @@ export class Game {
     updateFns = new Set();
     invalidUpdateCompositions = new WeakMap();
     resolution;
+    /** The constructor's viewHeight — unloadScene() restores it. */
+    baseViewHeight;
     viewHeight;
     sceneCamera = null;
     renderSort = null;
     sceneProjection = null;
     lastTime = 0;
     runtimeBridge = null;
+    /** Host-registered scenes by name, resolved by loadSceneByName. Session-scoped. */
+    sceneCatalog = null;
+    /** The live scene's name (its catalog key), or null with no scene loaded. */
+    liveSceneName = null;
+    /** True for the whole extent of a runFrame() call, incl. its tail. */
+    insideFrame = false;
+    /** A loadSceneByName() enqueued while insideFrame; applied at the next runFrame's start. */
+    pendingSceneLoad = null;
     constructor(options) {
         const { canvas, background = 0x1a1a2e, viewHeight = 10 } = options;
+        this.baseViewHeight = viewHeight;
         this.viewHeight = viewHeight;
         this.resolution = options.resolution ?? null;
         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);
@@ -97,6 +120,85 @@ export class Game {
     find(name) {
         return this.entities.find((e) => e.name === name);
     }
+    /**
+     * Destroys the live scene — every entity (Entity.destroy(), so onDestroy
+     * cascades and GPU resources release) and its scene-scoped UI — and
+     * leaves the Game as newly constructed: no registry, no scene camera, no
+     * render sort or projection, viewHeight back to the constructor's.
+     * Session-scoped state (stats, paramOverrides, subscriptions, the scene
+     * catalog) is untouched. See ADR 0011. Public: the seam `loadScene` calls
+     * to replace a scene, and how a host leaves the Game with none loaded.
+     */
+    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;
+        // Entity.destroy() splices itself out of `this.entities` in place — the
+        // Pointer holds that array by reference, so it must never be reassigned.
+        for (const entity of [...this.entities])
+            entity.destroy();
+        this.registry = null;
+        this.renderSort = null;
+        this.sceneProjection = null;
+        this.sceneCamera = null;
+        this.liveSceneName = null;
+        this.setViewHeight(this.baseViewHeight);
+    }
+    /** Registers the Project's scenes by name, resolved by loadSceneByName. */
+    registerSceneCatalog(catalog) {
+        this.sceneCatalog = catalog;
+    }
+    /** The live scene's name (its catalog key), or null with no scene loaded. */
+    get sceneName() {
+        return this.liveSceneName;
+    }
+    /** Names registered via registerSceneCatalog, in registration order. */
+    get availableScenes() {
+        return this.sceneCatalog ? Object.keys(this.sceneCatalog.scenes) : [];
+    }
+    /**
+     * Resolves `name` through the registered catalog and loads it, replacing
+     * the live scene. An unknown name warns and leaves the live scene
+     * untouched. Triggered mid-frame (e.g. from a SceneTransition's
+     * onCollide/onInteract) the swap is deferred to the very start of the
+     * next runFrame — dispatchCollisions finishes its double loop over the
+     * outgoing scene, and the incoming scene's entities are present only
+     * from the next frame. Called from outside a frame (boot, or the Runtime
+     * Bridge's `scene` control operation) it applies synchronously and wins
+     * over anything queued earlier this frame. A second mid-frame request
+     * loses to the first and says so. Returns whether the load took effect.
+     */
+    loadSceneByName(name) {
+        const catalog = this.sceneCatalog;
+        const json = catalog ? registryEntry(catalog.scenes, name) : undefined;
+        if (!catalog || !json) {
+            console.warn(`[waica] unknown scene: "${name}"`);
+            return false;
+        }
+        const apply = () => {
+            loadScene(this, json, catalog.registry);
+            this.liveSceneName = name;
+        };
+        if (!this.insideFrame) {
+            // Authoritative: dropping the queue is the point. A swap a transition
+            // enqueued earlier would otherwise flush on the next frame and silently
+            // undo this load, reporting success for a scene the caller never got.
+            this.pendingSceneLoad = null;
+            apply();
+            return true;
+        }
+        if (this.pendingSceneLoad) {
+            // Two transitions resolving in the same collision dispatch: the one the
+            // simulation reached first wins, and the loser is told. Last-write-wins
+            // would drop the player in the other door's destination with no signal.
+            console.warn(`[waica] a scene swap is already queued this frame; ignoring "${name}"`);
+            return false;
+        }
+        this.pendingSceneLoad = apply;
+        return true;
+    }
     /** Loads persisted parameter overrides (waica.params.json). */
     async loadParams(url) {
         try {
@@ -173,8 +275,11 @@ export class Game {
                     click: (x, y) => {
                         this.pointer.injectClick(x, y);
                     },
+                    loadScene: (name) => this.loadSceneByName(name),
+                    availableScenes: () => this.availableScenes,
                 });
                 activation.register(this.runtimeBridge);
+                this.audio.setSilenced(true);
                 window.addEventListener('pagehide', this.unregisterRuntimeBridge);
             }
             this.renderSurface();
@@ -211,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();
@@ -230,28 +336,51 @@ export class Game {
         this.runFrame(dt);
     }
     runFrame(dt) {
-        if (this.simulate) {
-            for (const entity of [...this.entities]) {
-                const schedule = this.componentUpdateSchedule(entity);
-                if (!schedule)
-                    continue;
-                for (const component of schedule)
-                    component.onUpdate?.(dt);
+        this.insideFrame = true;
+        try {
+            // Flushes a scene swap enqueued mid-frame last time (CA-7): applied
+            // before this frame's own simulation, so the incoming scene's
+            // entities are present only from this next frame onward.
+            this.flushPendingSceneLoad();
+            if (this.simulate) {
+                for (const entity of [...this.entities]) {
+                    const schedule = this.componentUpdateSchedule(entity);
+                    if (!schedule)
+                        continue;
+                    for (const component of schedule)
+                        component.onUpdate?.(dt);
+                }
+                this.dispatchCollisions();
+                this.updateSceneCamera(dt);
             }
-            this.dispatchCollisions();
-            this.updateSceneCamera(dt);
+            // 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();
+            this.renderSurface();
         }
-        // The UI must react to the pause itself (hide until resumed).
-        this.ui.setActive(this.simulate);
-        for (const fn of this.updateFns)
-            fn(dt);
-        this.input.endFrame();
-        this.renderSurface();
+        finally {
+            this.insideFrame = false;
+        }
+    }
+    flushPendingSceneLoad() {
+        const pending = this.pendingSceneLoad;
+        if (!pending)
+            return;
+        this.pendingSceneLoad = null;
+        pending();
     }
     unregisterRuntimeBridge = () => {
         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() {
@@ -348,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++) {