@woosh/meep-engine 2.163.11 → 2.164.0

package/src/engine/sound/simulation/prototypeAcousticSolver.js

@@ -0,0 +1,1534 @@
+import {
+    BoxGeometry,
+    BufferGeometry,
+    Float32BufferAttribute,
+    LineBasicMaterial,
+    MeshStandardMaterial,
+    SphereGeometry
+} from "three";
+import { AABB3 } from "../../../core/geom/3d/aabb/AABB3.js";
+import { Ray3 } from "../../../core/geom/3d/ray/Ray3.js";
+import { BoxShape3D } from "../../../core/geom/3d/shape/BoxShape3D.js";
+import { CapsuleShape3D } from "../../../core/geom/3d/shape/CapsuleShape3D.js";
+import { TransformedShape3D } from "../../../core/geom/3d/shape/TransformedShape3D.js";
+import { Quaternion } from "../../../core/geom/Quaternion.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { interpolate_irradiance_smith } from "../../../core/math/physics/irradiance/interpolate_irradiance_smith.js";
+import { seededRandom } from "../../../core/math/random/seededRandom.js";
+import { FirstPersonPlayerController } from "../../control/first-person/FirstPersonPlayerController.js";
+import { FirstPersonPlayerControllerSystem } from "../../control/first-person/FirstPersonPlayerControllerSystem.js";
+import { FirstPersonSensorsSystem } from "../../control/first-person/sensors/FirstPersonSensorsSystem.js";
+import { SerializationMetadata } from "../../ecs/components/SerializationMetadata.js";
+import { Tag } from "../../ecs/components/Tag.js";
+import Entity from "../../ecs/Entity.js";
+import { System } from "../../ecs/System.js";
+import { Transform } from "../../ecs/transform/Transform.js";
+import { EngineHarness } from "../../EngineHarness.js";
+import { CameraSystem } from "../../graphics/ecs/camera/CameraSystem.js";
+import { Light } from "../../graphics/ecs/light/Light.js";
+import { DrawMode } from "../../graphics/ecs/mesh-v2/DrawMode.js";
+import { ShadedGeometry } from "../../graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { ShadedGeometryFlags } from "../../graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
+import { ShadedGeometrySystem } from "../../graphics/ecs/mesh-v2/ShadedGeometrySystem.js";
+import {
+    AmbientOcclusionPostProcessEffect
+} from "../../graphics/render/buffer/simple-fx/ao/AmbientOcclusionPostProcessEffect.js";
+import { MaterialTransformer, ProbeResolutionStage } from "../../graphics/sh3/gi/material/MaterialTransformer.js";
+import { LightProbeVolume } from "../../graphics/sh3/lpv/LightProbeVolume.js";
+import { LightProbeVolumeBaker } from "../../graphics/sh3/lpv/LightProbeVolumeBaker.js";
+import { setup_environment_sky_from_ecd } from "../../graphics/sh3/sky/hosek/setup_environment_sky_from_ecd.js";
+import {
+    sampler2d_sample_equirectangular_direction
+} from "../../graphics/texture/sampler/sampler2d_sample_equirectangular_direction.js";
+import InputController from "../../input/ecs/components/InputController.js";
+import InputControllerSystem from "../../input/ecs/systems/InputControllerSystem.js";
+import { BodyKind } from "../../physics/ecs/BodyKind.js";
+import { Collider } from "../../physics/ecs/Collider.js";
+import { ColliderObserverSystem } from "../../physics/ecs/ColliderObserverSystem.js";
+import { PhysicsSystem } from "../../physics/ecs/PhysicsSystem.js";
+import { RigidBody } from "../../physics/ecs/RigidBody.js";
+import { PhysicsSurfacePoint } from "../../physics/queries/PhysicsSurfacePoint.js";
+import { AudioEmitter } from "../ecs/audio/AudioEmitter.js";
+import { AudioEmitterSystem } from "../ecs/audio/AudioEmitterSystem.js";
+import SoundListener from "../ecs/SoundListener.js";
+import SoundListenerSystem from "../ecs/SoundListenerSystem.js";
+import { SampleAudioClip } from "../sopra/definition/clip/SampleAudioClip.js";
+import { EventDescription } from "../sopra/definition/EventDescription.js";
+import { buildAttenuationCurve } from "../sopra/util/buildAttenuationCurve.js";
+import { configureAcousticSimulation } from "./configureAcousticSimulation.js";
+import { AcousticMaterial } from "./definition/AcousticMaterial.js";
+import { AcousticBody } from "./ecs/AcousticBody.js";
+import { bakeProbeField } from "./probe/bakeProbeField.js";
+import { FoaProbeReverbRenderer } from "./render/FoaProbeReverbRenderer.js";
+
+/**
+ * Prototype harness for the geometry-driven acoustic solver — a first-person walkaround under a Hosek sky.
+ *
+ * A platform holding TWO sealed sources with deliberately different acoustics:
+ *   - a small HOUSE (orchestral loop) — a tight, dead room; leaks from its south DOOR + north WINDOW, with a
+ *     hard REFLECTOR wall set back from the window that bounces its leak back at you;
+ *   - a much larger CATHEDRAL (main-menu loop) west across a gap — a tall, hard stone hall with a wide main
+ *     entrance, side windows, and a TOWER shaft (open to the nave) that gives a long, coupled-volume tail.
+ * Every surface is an {@link AcousticBody} occluder, so each source only escapes through its openings — the
+ * baked probe-field pathing routes it around corners and out, and the baked per-probe reverb colours the tail.
+ *
+ * What to listen for, as you walk: the house leak from its door/window (brighter near the reflector); the
+ * cathedral's long reverb through its entrance/windows; plain occlusion behind a solid wall or barrier. A
+ * RAMP on the house's east side walks you up onto its roof.
+ *
+ * Controls (same as the first-person gym):
+ *   - Click the canvas to capture the mouse (pointer lock); ESC to release. The first click also resumes
+ *     the (autoplay-policy-suspended) audio context, so sound starts on that click.
+ *   - WASD  — move          Mouse — look          Space — jump
+ *   - P (or the top-right button) — toggle the probe + visibility-edge overlay
+ *
+ * The probe field is baked ONCE at startup against the live occluder geometry (a brief synchronous
+ * freeze — watch the console for the probe count + bake time). Tune the BAKE_* / scene constants below.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+// -- Scene layout (metres; the platform is centred on the origin) --------
+const SPAWN_X = 0;
+const SPAWN_Z = 10;                 // player starts south of the house, facing it
+
+const SRC = new Vector3(0, 1.2, 0); // the orchestral source, inside the house
+const SRC_DIST_MIN = 3;   // full volume within this radius (m)
+const SRC_DIST_MAX = 30;  // rolled off to silence by here (m)
+
+const HOUSE_HALF = 4;               // footprint half-extent (x,z ∈ [-4, 4])
+const WALL_H = 3;                   // wall height
+const WALL_T = 0.3;                 // wall thickness
+const WALL_MID_Y = WALL_H / 2;
+
+const DOOR_HALF_W = 0.7;            // south wall opening: 1.4 m wide, to 2.2 m tall
+const DOOR_H = 2.2;
+const WIN_HALF_W = 0.9;             // north wall opening: 1.8 m wide, sill 1.0 → head 2.2
+const WIN_SILL = 1.0;
+const WIN_HEAD = 2.2;
+
+// -- Cathedral (a much larger, taller, more reverberant space + a tower) west of the house, across a gap.
+// The small house is a tight, dead room; the cathedral is a big stone hall whose tall nave + a tower shaft
+// (open to the nave through a hole in the roof) give a long, coupled-volume reverb tail — a deliberately
+// different "echo character", à la Šibenik.
+const CATH_X1 = -10;                  // east face (x=-10) is the entrance, facing the house across the gap
+const CATH_X0 = -38;                  // back (west) wall — 28 m deep, ≈2× the width, a proper long nave
+const CATH_Z0 = -9, CATH_Z1 = 9;      // 28 × 18 footprint
+const CATH_H = 8;                     // nave wall height (very tall ceiling)
+const CATH_T = 0.4;                   // wall thickness
+const CATH_ENTRY_HALF_W = 1.75;       // main entrance on the east wall: 3.5 m wide, 4.5 m tall
+const CATH_ENTRY_H = 4.5;
+const CATH_WIN_HALF_W = 1.25;         // side windows: 2.5 m wide, sill 3.5 → head 5.5
+const CATH_WIN_SILL = 3.5, CATH_WIN_HEAD = 5.5;
+const CATH_WIN_XS = [-15, -21, -27, -33]; // four windows per long side, spread along the longer nave
+const TOWER_X0 = -37, TOWER_X1 = -31; // a 6 × 6 shaft centred at the BACK of the nave (z=0), rising to y=20
+const TOWER_Z0 = -3, TOWER_Z1 = 3;
+const TOWER_BOTTOM = CATH_H - 1;      // tower walls drop 1 m below the roof so the roof seam is buried (no z-fight)
+const TOWER_TOP = 20;
+const JUMP_HOLE_X = -22, JUMP_HOLE_Z = 0, JUMP_HOLE_HALF = 1.0; // a 2×2 m hole in the roof to drop through
+
+const CATH_SRC = new Vector3(-28, 1.5, 0); // the MainMenu source, deep in the longer nave
+const CATH_SRC_DIST_MIN = 4;
+const CATH_SRC_DIST_MAX = 46;              // the long hall carries further than the house source
+
+// -- A free-standing wall opposite the house's WINDOW (north face, z=-4), set back far enough to walk between
+// it and the window — a hard REFLECTOR that bounces the window's leaked sound back (a baked early-reflection).
+const REFLECTOR_Z = -12;              // 8 m north of the window
+const REFLECTOR_HALF_W = 6;           // 12 m wide, x ∈ [-6, 6]
+const REFLECTOR_H = 4;
+
+// -- Ramps: ground → house roof (east), and house roof → cathedral roof (over the gap). The prototype's
+// ground resolver snaps the player to whatever surface is underfoot, so any angle is walkable.
+const ROOF_TOP = WALL_H + WALL_T;     // the house roof's walking surface (y)
+
+// -- Bake (offline probe field, for corner-leak pathing) -----------------
+// bakeProbeField derives its region from the scene (the occluder hull + a margin) — no bounds to configure.
+// minSpacing dominates the one-off startup bake: this big scene is ~400 probes (≈60 s) at spacing 3 but ~200
+// (≈10 s) at spacing 4, because the visibility/portal/lobe passes scale super-linearly in probe count (the
+// reverb ray count barely moves it). 4 keeps the bake tolerable; drop to 3 for finer pathing if you'll wait.
+const BAKE_MIN_SPACING = 2;   // probe density hint (m)
+const BAKE_REVERB_RAYS = 1024; // rays/probe for the per-band reverb (cheap at this probe count — keep it high)
+
+// Fully-blocking, mildly absorptive surfaces — so the door/window leak is the ONLY exit and the pathing
+// is unambiguous (a tiny transmission would muddy "is this leak or through-wall?").
+const WALL_MATERIAL = AcousticMaterial.from({
+    absorption: [0.1, 0.15, 0.25],
+    scattering: 0.3,
+    transmission: [0.1, 0.02, 0],
+});
+
+// The ground platform is an acoustic occluder too — this is load-bearing for the probe bake. WITHOUT a
+// floor in the occluder index the SDF cover treats the y=0 voxel layer as open air and drops ~half the
+// probes onto the ground; visibility rays between two ground probes then graze UNDER the walls (whose
+// bottoms sit at y=0), so inside connects to outside and occlusion is lost. With the floor, probes lift
+// into the wall band and the leak is forced through the door/window. (See demo_scene_probe_placement.spec.js
+// — no-floor: inside→behind-the-east-wall is a near-straight 9 m leak; with-floor: a 19 m detour.) Ground-
+// like absorption (a touch deader + more scattering than the walls).
+const GROUND_MATERIAL = AcousticMaterial.from({
+    absorption: [0.3, 0.35, 0.4],
+    scattering: 0.7,
+    transmission: [0, 0, 0],
+});
+
+// Hard, lightly-absorptive STONE for the cathedral — a much longer reverberation tail than the deader house
+// walls (low absorption = little energy lost per bounce → high RT60 in the big tall volume).
+const CATHEDRAL_MATERIAL = AcousticMaterial.from({
+    absorption: [0.04, 0.06, 0.1],
+    scattering: 0.25,
+    transmission: [0.1, 0, 0],
+});
+
+// A near-rigid REFLECTOR — almost nothing absorbed, almost no scatter → a clean specular bounce of the window's
+// leaked sound back toward the listener.
+const REFLECTOR_MATERIAL = AcousticMaterial.from({
+    absorption: [0.02, 0.03, 0.05],
+    scattering: 0.1,
+    transmission: [0, 0, 0],
+});
+
+// -- A small 3×3 reverb-chamber shack in the open SE: a door (west face) and NO windows. A low, hard little
+// box → a bright, ringy small-room tail, isolated from the rest for an A/B against the big stone cathedral.
+const SHACK_X = 13, SHACK_Z = -13;    // clear of the barrier (13,5), the SE block (8,-10) and the reflector
+const SHACK_HALF = 1.5;               // 3 × 3 footprint
+const SHACK_H = 2.6, SHACK_T = 0.25;
+const SHACK_DOOR_HALF = 0.5, SHACK_DOOR_H = 2.0; // a 1 m doorway on the west wall (faces the scene)
+
+// -- Operable sliding doors (house south DOOR + cathedral east ENTRANCE). They START open (slab slid down into
+// the ground, opening clear); pressing E within range slides it back UP to fill the opening (closed) and down
+// again (open). The slab is a KinematicPosition body AND an AcousticBody, so its occlusion follows it live (the
+// occluder index re-syncs on transform change) — closed it seals the opening, open it clears it.
+const DOOR_T = 0.2;                   // door slab thickness (sits within the opening)
+const DOOR_SLIDE_SPEED = 3.0;         // m/s vertical travel
+
+// -- Orbiting external source (WorldMode layer), circling the scene from outside ------------------------
+const ORBIT_CLIP = "data/sounds/music/matsmusic/d1/Fiverr Alexgoldring WorldMode LAYER 1.ogg";
+const ORBIT_CX = -12, ORBIT_CZ = 0;   // scene centre (between the cathedral and the east edge)
+const ORBIT_RADIUS = 40;              // well outside the platform (x∈[-44,16], z∈[-16,16])
+const ORBIT_HEIGHT = 5;               // a touch above the walls, so line-of-sight is wall-gated
+const ORBIT_SPEED = 0.18;             // rad/s (~35 s per lap)
+const ORBIT_DIST_MIN = 12, ORBIT_DIST_MAX = 90; // carries far — clearly audible from the centre with LoS
+
+// -- Light probe volume (baked diffuse GI). Baked once at startup by path-tracing each grid probe, so the probe
+// COUNT is the bake-cost knob. After the bake the IBL is switched off (scene.environment = null) so the LPV is
+// the only indirect light — the sky stays only as the backdrop.
+//
+// The volume must ENCLOSE every rendered surface with margin: a surface sitting exactly on the hull boundary
+// makes the per-fragment tetrahedral-mesh lookup flip in/out across neighbouring pixels (salt-and-pepper noise
+// with the tet grid showing through). In particular the bottom is BELOW the platform (y0 = -4, platform top is
+// y=0) so the floor is INTERIOR; ny=5 over y∈[-4,12] lands a probe LAYER exactly on the floor (y = -4,0,4,8,12),
+// where it captures the floor's incident sky/sun light. The x/z bounds overhang the platform for the same reason.
+const LPV_BOUNDS = [-46, -4, -18, 18, 16, 18]; // x0,y0,z0, x1,y1,z1 — overhangs the platform; floor y=0 is interior
+const LPV_RESOLUTION = new Vector3(30, 10, 20);  // counts/axis; ny=5 over y∈[-4,12] → a layer at y=0
+
+// -- Point lights co-located with each emissive source marker (a warm/cool glow in its room) -----------
+const SOURCE_LIGHT_INTENSITY = 6, SOURCE_LIGHT_DISTANCE = 12;
+
+// Wired in the configuration callback (needs the EngineConfiguration); baked against in main().
+let acousticSim = null;
+
+// Set in setupLightProbes() once the graphics MaterialManager exists. Lit scene materials are obtained THROUGH
+// it (see litMaterial) so the LPV MaterialTransformer compile-step actually patches them — a bare
+// `new MeshStandardMaterial(...)` never passes through the transform chain, so it would get NO probe GI.
+let materialManager = null;
+
+/**
+ * A managed lit material: routed through the {@link MaterialManager} so every registered compile-step (notably
+ * the LPV {@link MaterialTransformer}) patches it. Use this for every lit surface instead of a bare
+ * `new MeshStandardMaterial` — that is what makes the baked probe lighting visible.
+ *
+ * @param {object} params MeshStandardMaterial parameters (color, roughness, emissive, …)
+ * @returns {MeshStandardMaterial} the managed (compiled) material to hand to {@link ShadedGeometry.from}
+ */
+function litMaterial(params) {
+    const mat = new MeshStandardMaterial(params);
+    return materialManager === null ? mat : materialManager.obtain(mat).getValue();
+}
+
+const eh = new EngineHarness();
+
+/**
+ * Wire the sound + acoustic systems into the engine config. Runs inside {@link EngineHarness.initialize}
+ * (which owns the `EngineConfiguration` and `engine.sound` / `engine.assetManager`), before the world is
+ * built in {@link main}. `configureAcousticSimulation` needs the config, so it lives here rather than in
+ * main()'s `em.addSystem` flow.
+ *
+ * @param {EngineConfiguration} config
+ * @param {Engine} engine
+ */
+function setupSound(config, engine) {
+    // Native sopra-backed emitter system. acousticSim is injected by configureAcousticSimulation below,
+    // so it is constructed WITHOUT the 4th arg.
+    const audioEmitterSystem = new AudioEmitterSystem(engine.assetManager, engine.sound);
+    config.addSystem(audioEmitterSystem);
+
+    // Registers AcousticSimulationSystem (occluders) + AcousticVolumeSystem (media) +
+    // AcousticProbeFieldSystem (the baked field), all sharing one simulator, and sets
+    // audioEmitterSystem.acousticSim = simulator.
+    acousticSim = configureAcousticSimulation(config, audioEmitterSystem);
+    acousticSim.rayCount = 32;   // a touch crisper occlusion than the default 16
+    acousticSim.pathing = false;  // corner-leak through the door/window (needs the baked field, set in main)
+
+    // Poses the WebAudio listener from a SoundListener+Transform entity (the player, built in main).
+    config.addSystem(new SoundListenerSystem(engine.sound.context));
+}
+
+/**
+ * Create the light probe volume + its material compile-step. MUST run before any scene geometry compiles — the
+ * transformer injects the irradiance-sampling shader chunk into lit materials AT compile time — so it is called
+ * at the very top of {@link main}. The bake itself runs later, once the geometry exists ({@link bakeLightProbes}).
+ *
+ * @param {Engine} engine
+ * @returns {{volume:LightProbeVolume, transformer:MaterialTransformer}}
+ */
+function setupLightProbes(engine) {
+    materialManager = engine.graphics.getMaterialManager();
+    const volume = new LightProbeVolume();
+    // Fragment (per-pixel) sampling: this scene is big flat boxes, so vertex sampling (only the 4 face corners)
+    // would barely read; fragment is costlier but shows the baked GI gradient across a wall/floor.
+    const transformer = new MaterialTransformer({ volume, stage: ProbeResolutionStage.Fragment });
+    materialManager.addCompileStep(transformer);
+    return { volume, transformer };
+}
+
+const _skyScratch = new Float32Array(4);
+
+/**
+ * A path-tracer background sampler over the Hosek sky equirectangular texture, by ray direction (+Y up). The LPV
+ * baker's path tracer otherwise has a BLACK background ({@link PathTracedScene} default), so without this the
+ * bake captures only the sun bouncing off surfaces — no sky-dome fill. It samples the SAME sharp sky texture the
+ * renderer applies, so the baked GI matches the visible sky.
+ *
+ * @param {THREE.DataTexture} skyTexture equirectangular Float32 RGBA sky (the return of setup_environment_sky_from_ecd)
+ * @returns {function(out:number[], out_offset:number, direction:number[], direction_offset:number): void}
+ */
+function makeSkyBackgroundSampler(skyTexture) {
+    const sampler = {
+        width: skyTexture.image.width,
+        height: skyTexture.image.height,
+        itemSize: 4, // RGBA Float32
+        data: skyTexture.image.data,
+    };
+
+    return (out, out_offset, direction, direction_offset) => {
+        sampler2d_sample_equirectangular_direction(
+            sampler,
+            direction[direction_offset], direction[direction_offset + 1], direction[direction_offset + 2],
+            _skyScratch, 0);
+        out[out_offset] = _skyScratch[0];
+        out[out_offset + 1] = _skyScratch[1];
+        out[out_offset + 2] = _skyScratch[2];
+    };
+}
+
+/**
+ * Bake the LPV against the now-populated scene (path-traces each grid probe — {@link LPV_RESOLUTION} drives the
+ * cost), giving the path tracer the Hosek SKY as its background radiance (its default is black) so the bake picks
+ * up sky-dome fill, not just the sun. Then switch the IBL OFF (`scene.environment = null`) so the baked diffuse
+ * GI is the only indirect light; the sky stays as the visible backdrop (`scene.background`). Finally push the
+ * baked irradiance into the already-compiled materials.
+ *
+ * @param {Engine} engine
+ * @param {EntityComponentDataset} ecd
+ * @param {{volume:LightProbeVolume, transformer:MaterialTransformer}} lpv
+ * @param {THREE.DataTexture} skyTexture the equirectangular sky to sample as the bake's background radiance
+ */
+async function bakeLightProbes(engine, ecd, lpv, skyTexture) {
+    const b = LPV_BOUNDS;
+    // build_grid populates the probe positions AND the (grid) tetrahedral mesh the bake/interp need.
+    lpv.volume.build_grid(new AABB3(b[0], b[1], b[2], b[3], b[4], b[5]), LPV_RESOLUTION);
+
+    const baker = new LightProbeVolumeBaker();
+    // Give the path tracer the sky (its background defaults to black) — otherwise escaped rays return no
+    // radiance and the bake is sun-bounce only, so surfaces in shadow / facing away go dark.
+    baker._ren.scene.__background_sampler = makeSkyBackgroundSampler(skyTexture);
+
+    // Path-trace each probe (via the executor's task group) and wait for the whole bake to finish.
+    const task = baker.bake(lpv.volume, ecd);
+    engine.executor.runGroup(task);
+    await task.promise();
+
+    engine.graphics.scene.environment = null; // IBL off — only the LPV contributes indirect light now
+    lpv.transformer.update();
+}
+
+async function main(engine) {
+    const em = engine.entityManager;
+    const ecd = em.dataset;
+
+    // Light probe volume — create the volume + its material compile-step BEFORE any geometry compiles (the
+    // transformer injects the irradiance-sampling shader chunk at material-compile time). Baked + the IBL
+    // switched off later, once the scene exists (see bakeLightProbes, after the acoustic bake).
+    const lpv = setupLightProbes(engine);
+
+    // -- Systems ---------------------------------------------------------
+    EngineHarness.addFpsCounter(engine);
+
+    await EngineHarness.buildLights({
+        engine,
+        sunIntensity: 1.0,
+        ambientIntensity: 0.0,
+        shadowmapResolution: 2048,
+        sunShadowDistance: 60,
+    });
+
+    // Hosek-Wilkie sky + image-based lighting, sun direction taken from the directional light built above.
+    // A clear-ish daytime sky (low turbidity) lit by a touch of ground bounce so the stone reads warmer.
+    const skyTexture = setup_environment_sky_from_ecd(engine.graphics, ecd, { turbidity: 2.5, albedo: [0.12, 0.11, 0.1] });
+
+    engine.plugins.acquire(AmbientOcclusionPostProcessEffect);
+
+    if (em.getSystem(CameraSystem) === null) {
+        await em.addSystem(new CameraSystem(engine.graphics));
+    }
+    if (em.getSystem(InputControllerSystem) === null) {
+        await em.addSystem(new InputControllerSystem(engine.devices));
+    }
+    if (em.getSystem(ShadedGeometrySystem) === null) {
+        await em.addSystem(new ShadedGeometrySystem(engine));
+    }
+
+    // Physics — owns the static occluder/floor bodies, the kinematic player capsule, and serves the
+    // first-person ground resolver's downward raycasts (added before the controller so its sensors and
+    // mover find it).
+    const physicsSystem = new PhysicsSystem();
+    await em.addSystem(physicsSystem);
+    await em.addSystem(new ColliderObserverSystem(physicsSystem));
+
+    // Per-frame mover for the orbiting source + the sliding doors, plus the centred "Press E" cue it shows when
+    // the player is in a door's trigger zone. (motion.playerEntity is set below, once the player is built.)
+    const motion = new PrototypeMotionSystem({ physics: physicsSystem, cue: makeInteractionCue() });
+    await em.addSystem(motion);
+
+    const fpsSystem = new FirstPersonPlayerControllerSystem();
+    // The platform is a physics body, not a flat y=0 baseline — let the physics-backed resolver below be
+    // the sole ground source (so the house roof / barriers are stood-on correctly).
+    fpsSystem.useBuiltInFlatGround = false;
+    await em.addSystem(fpsSystem);
+    await em.addSystem(new FirstPersonSensorsSystem());
+
+    // -- World -----------------------------------------------------------
+    buildPlatform(ecd);
+    buildHouse(ecd);
+    buildCathedral(ecd);
+    buildReflectorWall(ecd);
+    buildRoofRamp(ecd);
+    buildScatteredOccluders(ecd);
+    buildSmallShack(ecd);
+    buildSlidingDoors(ecd); // house door + cathedral entrance, built OPEN (so the bake sees the openings clear)
+    // The audio sources are spawned on the FIRST click (setupInteraction), once the context has resumed —
+    // the engine starts ticking inside EngineHarness.initialize, so a source built here would be promoted
+    // and play on the still-suspended context (the autoplay-policy warning). Deferring the spawn to the
+    // gesture means its first playEvent always lands on a running context.
+
+    // -- Player ----------------------------------------------------------
+    const player = buildPlayerEntity(ecd);
+    fpsSystem.groundResolver = makePhysicsGroundResolver(physicsSystem, player.entity);
+    motion.playerEntity = player.entity; // door-proximity overlap tests against the player capsule
+    buildInputBindings(ecd, player, motion);
+    setupInteraction(engine, ecd);
+
+    // -- Bake the probe field against the now-populated occluder index ----
+    // The acoustic entities above linked into acousticSim.occluderIndex on build; bake the visibility
+    // graph + per-band reverb over it, then hand the field to the simulator for pathing.
+    console.log("%c[acoustic] baking probe field…", "color:#88ddff;font-weight:bold");
+    console.time("[acoustic] bake");
+    const field = bakeProbeField(
+        acousticSim.occluderIndex,
+        BAKE_MIN_SPACING,
+        BAKE_REVERB_RAYS,
+        seededRandom(1),
+    );
+    console.timeEnd("[acoustic] bake");
+    acousticSim.setProbeField(field);
+    console.log(`%c[acoustic] ${field.size} probes and ${field.visibilityGraph.adjacency_length} edges baked — pathing ${acousticSim.pathing ? "ON" : "off"}`,
+        "color:#88ddff;font-weight:bold");
+
+    // Probe-baked reverb: a listener-centric (FOA directional) reverb send tapped off the master bus, driven
+    // from the listener's nearest probe each frame — the SAME baked field carries the per-band RT60 + arrival
+    // direction. Inside the house's enclosed probes it gives a room tail that leans toward the openings; outside
+    // (open probes, ~0 RT60) it crossfades dry. Wired AFTER the bake (the renderer needs the field) and fed a
+    // copy of the dry mix; its own output goes to the master destination.
+    const reverb = new FoaProbeReverbRenderer(engine.sound.context, engine.sound.destination);
+    reverb.setProbeField(field);
+    engine.sound.sopra.masterBusOutput.connect(reverb.input);
+    em.getSystem(AudioEmitterSystem).probeReverb = reverb;
+
+    // Toggleable probe + visibility-edge overlay (top-right button, or press P). Starts hidden.
+    setupProbeVizToggle(makeProbeVisualization(ecd, field));
+
+    logHelp();
+
+    // -- Light probe volume: bake the diffuse GI against the populated scene, then switch the IBL off so the LPV
+    // is the only indirect light. Done LAST (after the audio path is fully wired) — it path-traces ≈240 probes,
+    // a few seconds; the scene renders IBL-lit until it finishes, then switches to the baked GI. --------------
+    console.log("%c[lpv] baking light probes…", "color:#ffcc66;font-weight:bold");
+    console.time("[lpv] bake");
+    await bakeLightProbes(engine, ecd, lpv, skyTexture);
+    console.timeEnd("[lpv] bake");
+}
+
+/**
+ * Downward-raycast ground resolver backed by {@link PhysicsSystem.raycast}, filtered to exclude the
+ * player's own capsule. Identical in spirit to the first-person gym's — from just above the feet, cast
+ * straight down, return the surface y or null. (Copied from the gym prototype.)
+ *
+ * @param {PhysicsSystem} physicsSystem
+ * @param {number} playerEntity
+ * @returns {(x:number, y:number, z:number) => number|null}
+ */
+function makePhysicsGroundResolver(physicsSystem, playerEntity) {
+    const PROBE_LIFT = 0.1;
+    const PROBE_DOWN = 50;
+    const filter = (entity) => entity !== playerEntity;
+    const ray = Ray3.from(0, 0, 0, 0, -1, 0, PROBE_DOWN);
+    const hit = new PhysicsSurfacePoint();
+    return function physicsGroundResolver(x, y, z) {
+        ray.setOrigin(x, y + PROBE_LIFT, z);
+        if (!physicsSystem.raycast(ray, hit, filter)) return null;
+        return (y + PROBE_LIFT) - hit.t;
+    };
+}
+
+// =====================================================================
+// World construction
+// =====================================================================
+
+/**
+ * The flat box platform everyone stands on — visible + a static physics body, top face at y=0. Also an
+ * acoustic occluder (a real floor): this is what keeps the probe bake from dropping probes onto y=0 and
+ * leaking sound under the walls — see {@link GROUND_MATERIAL}.
+ */
+function buildPlatform(ecd) {
+    // Sized to hold the cathedral (west, x≈-24..-10), the house (origin), the reflector (north, z=-12) and the
+    // roof ramp (east, x≈10) with room to roam — the floor's extent IS the bake's horizontal extent, so it is
+    // kept only as large as the scene needs. Centred on x=-7 (between house and cathedral).
+    const THICK = 1.0;
+    spawnBox(ecd, {
+        center: new Vector3(-14, -THICK / 2, 0),
+        size: new Vector3(60, THICK, 32), // x ∈ [-44, 16], z ∈ [-16, 16]
+        color: 0x5a6b52,
+        roughness: 0.97,
+        material: GROUND_MATERIAL,
+    });
+}
+
+/**
+ * The house: four 3 m walls + a roof around an 8×8 m room, every surface an acoustic occluder. South wall
+ * carries a DOOR (opening to the floor, walk-through); north wall a WINDOW (mid-height opening); east /
+ * west walls + roof are solid. Each opening is framed by wall segments so the gap is a real hole in the
+ * geometry the solver routes through.
+ */
+function buildHouse(ecd) {
+    const color = 0xc9b79a;
+
+    // -- South wall (z = +HOUSE_HALF) — DOOR, centred on x, open to the floor -----------------
+    // left + right jambs (full height), and a lintel above the opening.
+    acousticWall(ecd, segCenter(-HOUSE_HALF, -DOOR_HALF_W), WALL_MID_Y, HOUSE_HALF,
+        segWidth(-HOUSE_HALF, -DOOR_HALF_W), WALL_H, WALL_T, color);
+    acousticWall(ecd, segCenter(DOOR_HALF_W, HOUSE_HALF), WALL_MID_Y, HOUSE_HALF,
+        segWidth(DOOR_HALF_W, HOUSE_HALF), WALL_H, WALL_T, color);
+    acousticWall(ecd, 0, (DOOR_H + WALL_H) / 2, HOUSE_HALF,
+        DOOR_HALF_W * 2, WALL_H - DOOR_H, WALL_T, color); // lintel
+
+    // -- North wall (z = -HOUSE_HALF) — WINDOW, framed sill + lintel -------------------------
+    acousticWall(ecd, segCenter(-HOUSE_HALF, -WIN_HALF_W), WALL_MID_Y, -HOUSE_HALF,
+        segWidth(-HOUSE_HALF, -WIN_HALF_W), WALL_H, WALL_T, color);
+    acousticWall(ecd, segCenter(WIN_HALF_W, HOUSE_HALF), WALL_MID_Y, -HOUSE_HALF,
+        segWidth(WIN_HALF_W, HOUSE_HALF), WALL_H, WALL_T, color);
+    acousticWall(ecd, 0, WIN_SILL / 2, -HOUSE_HALF,
+        WIN_HALF_W * 2, WIN_SILL, WALL_T, color); // sill (below window)
+    acousticWall(ecd, 0, (WIN_HEAD + WALL_H) / 2, -HOUSE_HALF,
+        WIN_HALF_W * 2, WALL_H - WIN_HEAD, WALL_T, color); // lintel (above window)
+
+    // -- East / west walls (solid), inset along z to butt against the N/S walls' inner faces --
+    const sideLen = HOUSE_HALF * 2 - WALL_T;
+    acousticWall(ecd, HOUSE_HALF, WALL_MID_Y, 0, WALL_T, WALL_H, sideLen, color);
+    acousticWall(ecd, -HOUSE_HALF, WALL_MID_Y, 0, WALL_T, WALL_H, sideLen, color);
+
+    // -- Roof — caps the room so the source is genuinely sealed -------------------------------
+    acousticWall(ecd, 0, WALL_H + WALL_T / 2, 0,
+        HOUSE_HALF * 2 + 0.6, WALL_T, HOUSE_HALF * 2 + 0.6, 0x8a5a3a);
+}
+
+/** Centre of the wall segment spanning [a, b] along one axis. */
+function segCenter(a, b) {
+    return (a + b) / 2;
+}
+
+/** Width of the wall segment spanning [a, b] along one axis. */
+function segWidth(a, b) {
+    return b - a;
+}
+
+/** A house wall slab: a visual + physics + acoustic box from a centre + full extents. */
+function acousticWall(ecd, cx, cy, cz, sx, sy, sz, color) {
+    spawnBox(ecd, {
+        center: new Vector3(cx, cy, cz),
+        size: new Vector3(sx, sy, sz),
+        color,
+        roughness: 0.85,
+        material: WALL_MATERIAL,
+    });
+}
+
+/**
+ * Free-standing occluders dotted around the platform, away from the house — direct-path occlusion test
+ * pieces (duck behind one and the music dampens, no opening involved).
+ */
+function buildScatteredOccluders(ecd) {
+    const color = 0x8a8a8a;
+
+    // A long barrier wall east of the house.
+    spawnBox(ecd, { center: new Vector3(13, 1.5, 5), size: new Vector3(WALL_T, 3, 7), color, roughness: 0.8, material: WALL_MATERIAL });
+    // A chunky block in the open south-east (clear of the cathedral, the reflector corridor, and the ramp).
+    spawnBox(ecd, { center: new Vector3(8, 1.5, -10), size: new Vector3(3, 3, 3), color, roughness: 0.8, material: WALL_MATERIAL });
+    // A couple of pillars for parallax + narrow shadows.
+    spawnBox(ecd, { center: new Vector3(7, 2, 13), size: new Vector3(1, 4, 1), color, roughness: 0.8, material: WALL_MATERIAL });
+    spawnBox(ecd, { center: new Vector3(-7, 2, -14), size: new Vector3(1, 4, 1), color, roughness: 0.8, material: WALL_MATERIAL });
+}
+
+/**
+ * A tiny 3×3 m enclosed shack in the open south-east: four hard walls (one with a 1 m doorway, NO windows) and a
+ * roof, all {@link CATHEDRAL_MATERIAL}. A deliberately small, hard cavity — a "reverb chamber" test site whose
+ * baked tail (short but bright/ringy) contrasts the big stone cathedral and the dead little house. No source
+ * inside: walk in with the orbiting source audible, or A/B the room tone against the open platform.
+ */
+function buildSmallShack(ecd) {
+    const color = 0xb0a48c;
+    const x0 = SHACK_X - SHACK_HALF, x1 = SHACK_X + SHACK_HALF;
+    const z0 = SHACK_Z - SHACK_HALF, z1 = SHACK_Z + SHACK_HALF;
+
+    // West wall (x=x0, faces the scene) — a doorway to the floor, centred on z
+    buildWall(ecd, {
+        fixedAxis: "x", fixed: x0, from: z0, to: z1, height: SHACK_H, thickness: SHACK_T,
+        openings: [{ a: SHACK_Z - SHACK_DOOR_HALF, b: SHACK_Z + SHACK_DOOR_HALF, y0: 0, y1: SHACK_DOOR_H }],
+        material: CATHEDRAL_MATERIAL, color,
+    });
+    // East wall (x=x1) — solid
+    buildWall(ecd, {
+        fixedAxis: "x", fixed: x1, from: z0, to: z1, height: SHACK_H, thickness: SHACK_T,
+        material: CATHEDRAL_MATERIAL, color,
+    });
+    // North + south walls (z=z0/z1) — solid
+    for (const z of [z0, z1]) {
+        buildWall(ecd, {
+            fixedAxis: "z", fixed: z, from: x0, to: x1, height: SHACK_H, thickness: SHACK_T,
+            material: CATHEDRAL_MATERIAL, color,
+        });
+    }
+    roofSlab(ecd, x0, x1, z0, z1, SHACK_H, SHACK_T, color);
+}
+
+/**
+ * The cathedral, west of the house across a ~6 m gap: a big, tall, hard-walled stone hall — a much larger,
+ * more reverberant space than the dead little house. A wide MAIN ENTRANCE faces the gap (east wall), a couple
+ * of WINDOWS line each long side, and a TOWER shaft rises from the centre of the nave roof's back (open to the nave
+ * through a roof hole) — a tall coupled volume that lengthens + colours the tail near it (à la Šibenik). Every
+ * surface is a {@link CATHEDRAL_MATERIAL} occluder, so the source within only escapes through the openings.
+ */
+function buildCathedral(ecd) {
+    const color = 0xb8b0a0;
+
+    // -- East wall (x=CATH_X1, faces the house) — the MAIN ENTRANCE, centred, open to the floor -------------
+    buildWall(ecd, {
+        fixedAxis: "x", fixed: CATH_X1, from: CATH_Z0, to: CATH_Z1, height: CATH_H, thickness: CATH_T,
+        openings: [{ a: -CATH_ENTRY_HALF_W, b: CATH_ENTRY_HALF_W, y0: 0, y1: CATH_ENTRY_H }],
+        material: CATHEDRAL_MATERIAL, color,
+    });
+
+    // -- West wall (x=CATH_X0) — solid --------------------------------------------------------------------
+    buildWall(ecd, {
+        fixedAxis: "x", fixed: CATH_X0, from: CATH_Z0, to: CATH_Z1, height: CATH_H, thickness: CATH_T,
+        material: CATHEDRAL_MATERIAL, color,
+    });
+
+    // -- North + south long walls (z=CATH_Z0 / CATH_Z1) — four windows each, along the nave -----------------
+    const sideWindows = CATH_WIN_XS.map((x) => (
+        { a: x - CATH_WIN_HALF_W, b: x + CATH_WIN_HALF_W, y0: CATH_WIN_SILL, y1: CATH_WIN_HEAD }
+    ));
+    for (const z of [CATH_Z0, CATH_Z1]) {
+        buildWall(ecd, {
+            fixedAxis: "z", fixed: z, from: CATH_X0, to: CATH_X1, height: CATH_H, thickness: CATH_T,
+            openings: sideWindows, material: CATHEDRAL_MATERIAL, color,
+        });
+    }
+
+    // -- Roof at y=CATH_H, tiled around two holes: the tower shaft (back centre) and a 2×2 m drop-through -----
+    buildRoofWithHoles(ecd, CATH_X0, CATH_X1, CATH_Z0, CATH_Z1, CATH_H, CATH_T, [
+        { x0: TOWER_X0, x1: TOWER_X1, z0: TOWER_Z0, z1: TOWER_Z1 },
+        { x0: JUMP_HOLE_X - JUMP_HOLE_HALF, x1: JUMP_HOLE_X + JUMP_HOLE_HALF, z0: JUMP_HOLE_Z - JUMP_HOLE_HALF, z1: JUMP_HOLE_Z + JUMP_HOLE_HALF },
+    ], 0x6b5a48);
+
+    // -- Tower: four walls around the tower roof hole, from TOWER_BOTTOM (1 m below the roof, so the roof
+    //    seam is buried — no z-fighting) up to TOWER_TOP, capped — open to the nave below -------------------
+    const towerMidY = (TOWER_BOTTOM + TOWER_TOP) / 2, towerHeight = TOWER_TOP - TOWER_BOTTOM;
+    const towerCz = (TOWER_Z0 + TOWER_Z1) / 2, towerDz = TOWER_Z1 - TOWER_Z0;
+    const towerCx = (TOWER_X0 + TOWER_X1) / 2, towerDx = TOWER_X1 - TOWER_X0;
+    const tower = (center, size) => spawnBox(ecd, { center, size, color, roughness: 0.8, material: CATHEDRAL_MATERIAL });
+    tower(new Vector3(TOWER_X0, towerMidY, towerCz), new Vector3(CATH_T, towerHeight, towerDz));
+    tower(new Vector3(TOWER_X1, towerMidY, towerCz), new Vector3(CATH_T, towerHeight, towerDz));
+    tower(new Vector3(towerCx, towerMidY, TOWER_Z0), new Vector3(towerDx, towerHeight, CATH_T));
+    tower(new Vector3(towerCx, towerMidY, TOWER_Z1), new Vector3(towerDx, towerHeight, CATH_T));
+    tower(new Vector3(towerCx, TOWER_TOP + CATH_T / 2, towerCz), new Vector3(towerDx, CATH_T, towerDz)); // cap
+}
+
+/**
+ * A vertical wall (a slab of `thickness` at `fixed` on `fixedAxis` — 'x' or 'z' — spanning [from,to] on the
+ * other horizontal axis, y∈[0,height]) with rectangular `openings` cut out of it. Each opening is `{a, b, y0,
+ * y1}` (a,b on the span axis, y0..y1 vertical); the gaps between openings become full-height pillars, and each
+ * opening gets a sill below + a lintel above. The same recipe the house door/window are framed with.
+ */
+function buildWall(ecd, { fixedAxis, fixed, from, to, height, thickness, openings = [], material, color }) {
+    const ops = openings.slice().sort((p, q) => p.a - q.a);
+
+    // full-height pillars in the gaps between openings (and at the two ends)
+    let cursor = from;
+    for (const op of ops) {
+        if (op.a > cursor) {
+            wallSlab(ecd, fixedAxis, fixed, cursor, op.a, 0, height, thickness, material, color);
+        }
+        cursor = Math.max(cursor, op.b);
+    }
+    if (to > cursor) {
+        wallSlab(ecd, fixedAxis, fixed, cursor, to, 0, height, thickness, material, color);
+    }
+
+    // sill below + lintel above each opening
+    for (const op of ops) {
+        if (op.y0 > 0) {
+            wallSlab(ecd, fixedAxis, fixed, op.a, op.b, 0, op.y0, thickness, material, color);
+        }
+        if (op.y1 < height) {
+            wallSlab(ecd, fixedAxis, fixed, op.a, op.b, op.y1, height, thickness, material, color);
+        }
+    }
+}
+
+/** One box of a {@link buildWall}: spans [s0,s1] on the span axis, [y0,y1] vertical, `thickness` at `fixed`. */
+function wallSlab(ecd, fixedAxis, fixed, s0, s1, y0, y1, thickness, material, color) {
+    const sc = (s0 + s1) / 2, sw = s1 - s0;
+    const yc = (y0 + y1) / 2, yh = y1 - y0;
+    const center = fixedAxis === "x" ? new Vector3(fixed, yc, sc) : new Vector3(sc, yc, fixed);
+    const size = fixedAxis === "x" ? new Vector3(thickness, yh, sw) : new Vector3(sw, yh, thickness);
+    spawnBox(ecd, { center, size, color, roughness: 0.8, material });
+}
+
+/** A horizontal roof slab over the x/z rectangle, its bottom face at `y`. */
+function roofSlab(ecd, x0, x1, z0, z1, y, thickness, color) {
+    spawnBox(ecd, {
+        center: new Vector3((x0 + x1) / 2, y + thickness / 2, (z0 + z1) / 2),
+        size: new Vector3(x1 - x0, thickness, z1 - z0),
+        color, roughness: 0.8, material: CATHEDRAL_MATERIAL,
+    });
+}
+
+/**
+ * A flat roof over [x0,x1]×[z0,z1] (bottom face at `y`) with rectangular `holes` ({x0,x1,z0,z1}) cut out. Tiled
+ * as z-strips split at the holes' z-edges; within each strip the x-span is split around any hole that spans it
+ * (so non-overlapping holes at different z are all handled).
+ */
+function buildRoofWithHoles(ecd, x0, x1, z0, z1, y, thickness, holes, color) {
+    const zEdges = [z0, z1];
+    for (const h of holes) {
+        zEdges.push(h.z0, h.z1);
+    }
+    const bands = Array.from(new Set(zEdges)).sort((a, b) => a - b);
+
+    for (let i = 0; i < bands.length - 1; i++) {
+        const za = bands[i], zb = bands[i + 1];
+        // holes spanning this whole z-band → their x-ranges are cut from this strip
+        const cuts = holes
+            .filter((h) => h.z0 <= za + 1e-6 && h.z1 >= zb - 1e-6)
+            .map((h) => ({ a: h.x0, b: h.x1 }))
+            .sort((p, q) => p.a - q.a);
+
+        let cursor = x0;
+        for (const cut of cuts) {
+            if (cut.a > cursor) {
+                roofSlab(ecd, cursor, cut.a, za, zb, y, thickness, color);
+            }
+            cursor = Math.max(cursor, cut.b);
+        }
+        if (x1 > cursor) {
+            roofSlab(ecd, cursor, x1, za, zb, y, thickness, color);
+        }
+    }
+}
+
+/**
+ * A free-standing hard wall opposite the house's WINDOW (north face), set back so you can walk between them —
+ * a {@link REFLECTOR_MATERIAL} reflector that bounces the window's leaked sound back at a listener in the gap
+ * (the bounce shows up as a baked early reflection / a brighter local reverb between window and wall).
+ */
+function buildReflectorWall(ecd) {
+    spawnBox(ecd, {
+        center: new Vector3(0, REFLECTOR_H / 2, REFLECTOR_Z),
+        size: new Vector3(REFLECTOR_HALF_W * 2, REFLECTOR_H, 0.4),
+        color: 0x9aa0a8,
+        roughness: 0.6,
+        material: REFLECTOR_MATERIAL,
+    });
+}
+
+/**
+ * Two ramps: from the platform up onto the HOUSE roof (east side), and from the house roof across the gap up
+ * onto the (taller) CATHEDRAL roof. Walkable static bodies (the ground resolver snaps the player to whatever's
+ * underfoot), and acoustic occluders too — the tilted slabs cast their own (rotated-box) shadow, e.g. the
+ * gap-spanning ramp shades the gap below it.
+ */
+function buildRoofRamp(ecd) {
+    const ROOF_EDGE = HOUSE_HALF + 0.3;   // the house roof overhangs its walls to ±(HOUSE_HALF+0.3)
+    const CATH_ROOF_TOP = CATH_H + CATH_T; // the cathedral roof's walking surface
+    buildRamp(ecd, 10, 0.05, ROOF_EDGE, ROOF_TOP, 0, 2.6, 0x7a6f5e);              // platform → house roof
+    buildRamp(ecd, -ROOF_EDGE, ROOF_TOP, CATH_X1, CATH_ROOF_TOP, 0, 3.0, 0x7a6f5e); // house roof → cathedral roof
+}
+
+/**
+ * A ramp whose top face runs from the lower surface point (bx,by) up to the upper one (tx,ty) in the x–y plane
+ * at z=`z`, `width` wide: a thin box rotated so its length runs bottom→top. The top end lands EXACTLY on
+ * (tx,ty) (so it never pokes through the roof it meets); a short overhang is added only at the BOTTOM to seat
+ * it in the lower surface. An acoustic occluder (`WALL_MATERIAL`) — the rotated box is honoured by the occluder
+ * index exactly as by the collider.
+ */
+function buildRamp(ecd, bx, by, tx, ty, z, width, color) {
+    const dx = tx - bx, dy = ty - by;
+    const span = Math.hypot(dx, dy);
+    const angle = Math.atan2(dy, dx);
+    const overhang = 0.6;
+    const ux = dx / span, uy = dy / span; // unit bottom→top
+    spawnBox(ecd, {
+        // centre shifted half the overhang toward the bottom, so the +x (top) end is exactly (tx,ty)
+        center: new Vector3((bx + tx) / 2 - ux * overhang / 2, (by + ty) / 2 - uy * overhang / 2, z),
+        size: new Vector3(span + overhang, 0.3, width),
+        color,
+        roughness: 0.9,
+        rotation: Quaternion.fromAxisAngle(new Vector3(0, 0, 1), angle),
+        material: WALL_MATERIAL,
+    });
+}
+
+// =====================================================================
+// Operable sliding doors + the per-frame mover (orbiter + doors + proximity cue)
+// =====================================================================
+
+const IDENTITY_QUATERNION = Quaternion.fromAxisAngle(new Vector3(0, 1, 0), 0); // axis-aligned overlap queries
+
+/**
+ * Build one operable sliding door: a slab filling an opening (centre `center`, full extents `size`), a
+ * KinematicPosition body so it can be driven, an {@link AcousticBody} occluder so it seals/clears the opening
+ * LIVE as it slides (the occluder index re-syncs on transform change), and a {@link PrototypeMover} (kind
+ * "door") so {@link PrototypeMotionSystem} slides it down (open) / up (closed) on E and tracks player proximity
+ * to `zoneCenter ± zoneHalf`.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {{center:Vector3, size:Vector3, zoneCenter:Vector3, zoneHalf:Vector3, label:string}} p
+ */
+function spawnSlidingDoor(ecd, { center, size, zoneCenter, zoneHalf, label }) {
+    const geom = new BoxGeometry(size.x, size.y, size.z);
+    const mat = litMaterial({ color: 0x5a4632, roughness: 0.7 });
+    const sg = ShadedGeometry.from(geom, mat);
+    sg.setFlag(ShadedGeometryFlags.CastShadow);
+    sg.setFlag(ShadedGeometryFlags.ReceiveShadow);
+    sg.setFlag(ShadedGeometryFlags.Visible);
+
+    const rigidBody = new RigidBody();
+    rigidBody.kind = BodyKind.KinematicPosition; // scripted vertical motion; solid + occluding while raised
+
+    const collider = new Collider();
+    collider.shape = BoxShape3D.from_size(size.x, size.y, size.z);
+
+    const openY = center.y - size.y; // slid fully below the floor → the opening is clear
+
+    // START open (slid down): the doors begin open AND, since the acoustic bake runs after the world is built,
+    // it sees the openings clear rather than sealed. E closes them.
+    const transform = new Transform();
+    transform.position.set(center.x, openY, center.z);
+
+    const mover = new PrototypeMover();
+    mover.kind = "door";
+    mover.closedY = center.y;
+    mover.openY = openY;
+    mover.open = true;
+    mover.label = label;
+    mover.zoneShape = BoxShape3D.from(zoneHalf.x, zoneHalf.y, zoneHalf.z);
+    mover.zoneCenter = zoneCenter;
+
+    new Entity()
+        .add(sg)
+        .add(rigidBody)
+        .add(collider)
+        .add(AcousticBody.from(WALL_MATERIAL))
+        .add(mover)
+        .add(Tag.fromJSON(["AcousticDemo", "Door"]))
+        .add(SerializationMetadata.Transient)
+        .add(transform)
+        .build(ecd);
+}
+
+/** The two operable doors: the house's south DOOR and the cathedral's east ENTRANCE (built OPEN; E closes them). */
+function buildSlidingDoors(ecd) {
+    // House south door — fills the 1.4 m × 2.2 m opening at z = +HOUSE_HALF
+    spawnSlidingDoor(ecd, {
+        center: new Vector3(0, DOOR_H / 2, HOUSE_HALF),
+        size: new Vector3(DOOR_HALF_W * 2, DOOR_H, DOOR_T),
+        zoneCenter: new Vector3(0, 1.5, HOUSE_HALF),
+        zoneHalf: new Vector3(2.5, 2.0, 2.5),
+        label: "house door",
+    });
+    // Cathedral main entrance — fills the 3.5 m × 4.5 m opening at x = CATH_X1
+    spawnSlidingDoor(ecd, {
+        center: new Vector3(CATH_X1, CATH_ENTRY_H / 2, 0),
+        size: new Vector3(DOOR_T, CATH_ENTRY_H, CATH_ENTRY_HALF_W * 2),
+        zoneCenter: new Vector3(CATH_X1, 2.2, 0),
+        zoneHalf: new Vector3(3.5, 2.5, 3.5),
+        label: "cathedral entrance",
+    });
+}
+
+/** A centred "Press E" hint, shown by the motion system whenever the player is in a door's trigger zone. */
+function makeInteractionCue() {
+    const el = document.createElement("div");
+    Object.assign(el.style, {
+        position: "absolute", left: "50%", top: "60%", transform: "translate(-50%, -50%)",
+        zIndex: "1000", padding: "6px 14px", font: "16px sans-serif", color: "#eaf4ff",
+        background: "rgba(18,26,34,0.82)", border: "1px solid #3a6ea5", borderRadius: "4px",
+        pointerEvents: "none", display: "none", letterSpacing: "0.5px",
+    });
+    el.textContent = 'Press "E"';
+    document.body.appendChild(el);
+    return el;
+}
+
+/**
+ * Per-entity motion record, attached alongside a {@link Transform} and observed by {@link PrototypeMotionSystem}.
+ * A tagged record: either an ORBITING source (`kind` "orbit" — circles (cx,cz) at `radius`/`height`, advancing
+ * `angle` by `speed`) or a SLIDING door (`kind` "door" — slides between `closedY`/`openY`, `open` toggled by E;
+ * `zoneShape`/`zoneCenter` is its proximity trigger). A plain data component; never serialized (the prototype
+ * entities are {@link SerializationMetadata.Transient}).
+ */
+class PrototypeMover {
+    kind = "orbit";
+    // kind "orbit"
+    cx = 0;
+    cz = 0;
+    radius = 0;
+    height = 0;
+    speed = 0;
+    angle = 0;
+    // kind "door"
+    closedY = 0;
+    openY = 0;
+    open = false;
+    label = "";
+    zoneShape = null;
+    zoneCenter = null;
+}
+
+PrototypeMover.typeName = "PrototypeMover";
+
+/**
+ * One per-frame mover for the prototype's dynamic pieces (added via {@link EntityManager.addSystem}). It observes
+ * ({@link PrototypeMover}, {@link Transform}) — link/unlink keep a working list — and each tick:
+ *  - ORBIT movers — advance around their circle (the entity's Transform.position is set every frame);
+ *  - DOOR movers — slide toward the target (open = down into the ground, closed = up), and the physics is
+ *    queried for the player capsule overlapping a door's trigger zone. The nearest in-range door becomes
+ *    {@link activeDoor} (E toggles it) and the "Press E" cue is shown. Proximity is a real collider overlap
+ *    ({@link PhysicsSystem.overlap} of the zone box vs the player), not a distance test.
+ *
+ * (A system must declare ≥1 dependency — the engine drives it as an entity observer — so the movers are a real
+ * component rather than a side list.)
+ */
+class PrototypeMotionSystem extends System {
+    #scratch = new Uint32Array(8);
+
+    constructor({ physics, cue }) {
+        super();
+        this.dependencies = [PrototypeMover, Transform];
+        this.physics = physics;
+        this.cue = cue;
+        this.playerEntity = -1;    // set once the player is built
+        this.movers = [];          // { mover: PrototypeMover, transform: Transform, entity: number }
+        this.activeDoor = null;    // the door mover the player is next to, or null
+    }
+
+    /** EntityObserver callbacks — argument order matches `dependencies`, entity last, `this` = the system. */
+    link(mover, transform, entity) {
+        this.movers.push({ mover, transform, entity });
+    }
+
+    unlink(mover, transform, entity) {
+        const i = this.movers.findIndex((m) => m.entity === entity);
+        if (i !== -1) {
+            this.movers.splice(i, 1);
+        }
+    }
+
+    /** E handler — flip the door the player is standing next to (if any). */
+    toggleActiveDoor() {
+        if (this.activeDoor !== null) {
+            this.activeDoor.open = !this.activeDoor.open;
+        }
+    }
+
+    update(timeDelta) {
+        const ecd = this.entityManager === null ? null : this.entityManager.dataset;
+        if (ecd === null) {
+            return;
+        }
+
+        let active = null;
+        for (let i = 0; i < this.movers.length; i++) {
+            const mover = this.movers[i].mover;
+            const transform = this.movers[i].transform;
+
+            if (mover.kind === "orbit") {
+                mover.angle += mover.speed * timeDelta;
+                transform.position.set(
+                    mover.cx + Math.cos(mover.angle) * mover.radius, mover.height,
+                    mover.cz + Math.sin(mover.angle) * mover.radius);
+                continue;
+            }
+
+            // kind "door": proximity (collider overlap vs the player) + slide toward target
+            if (this.playerEntity !== -1 && active === null) {
+                const n = this.physics.overlap(
+                    mover.zoneShape, mover.zoneCenter, IDENTITY_QUATERNION, this.#scratch, 0,
+                    (entity) => entity === this.playerEntity);
+                if (n > 0) {
+                    active = mover;
+                }
+            }
+
+            const targetY = mover.open ? mover.openY : mover.closedY;
+            const p = transform.position;
+            const dy = targetY - p.y;
+            if (dy !== 0) {
+                const step = Math.sign(dy) * Math.min(Math.abs(dy), DOOR_SLIDE_SPEED * timeDelta);
+                p.set(p.x, p.y + step, p.z); // onChanged → the kinematic body + acoustic occluder follow
+            }
+        }
+
+        this.activeDoor = active;
+        this.cue.style.display = active === null ? "none" : "block";
+    }
+}
+
+// The MainMenu loop, shared by the house, cathedral and shack sources (same clip, different rooms/acoustics).
+const MAIN_MENU_CLIP = "data/sounds/music/matsmusic/d1/Fiverr Alexgoldring MainMenu.ogg";
+
+/** Sources spawned on the first click. House, cathedral and the little SHACK all play the SAME MainMenu loop (so
+ * the difference you hear is purely the room acoustics); a fourth source orbits the scene from outside. (The
+ * paths have spaces — the browser percent-encodes them on fetch, and the dev server serves it straight from
+ * `app/`.) */
+function buildSources(ecd) {
+    spawnAudioSource(ecd, {
+        id: "house-mainmenu",
+        clipPath: MAIN_MENU_CLIP,
+        position: SRC,
+        distanceMin: SRC_DIST_MIN,
+        distanceMax: SRC_DIST_MAX,
+        markerColor: 0xffcc66,
+        markerEmissive: 0xff8800,
+        lightDistance: SOURCE_LIGHT_DISTANCE / 2, // a tighter orange glow in the small dead room
+    });
+    spawnAudioSource(ecd, {
+        id: "cathedral-mainmenu",
+        clipPath: MAIN_MENU_CLIP,
+        position: CATH_SRC,
+        distanceMin: CATH_SRC_DIST_MIN,
+        distanceMax: CATH_SRC_DIST_MAX,
+        markerColor: 0x99ccff,
+        markerEmissive: 0x3388ff,
+    });
+    spawnAudioSource(ecd, {
+        id: "shack-mainmenu",
+        clipPath: MAIN_MENU_CLIP,
+        position: new Vector3(SHACK_X, 1.2, SHACK_Z),
+        distanceMin: SRC_DIST_MIN,
+        distanceMax: SRC_DIST_MAX,
+        markerColor: 0xcc99ff,
+        markerEmissive: 0x8844cc,
+    });
+
+    // A third source ORBITS the whole scene from outside (a WorldMode layer). Acoustic + a long max distance,
+    // so from the centre you hear it swing in and out as buildings break the line of sight. The
+    // PrototypeMotionSystem drives its position each frame around (ORBIT_CX, ORBIT_CZ).
+    const orbiter = spawnAudioSource(ecd, {
+        id: "orbit-worldmode",
+        clipPath: ORBIT_CLIP,
+        position: new Vector3(ORBIT_CX + ORBIT_RADIUS, ORBIT_HEIGHT, ORBIT_CZ),
+        distanceMin: ORBIT_DIST_MIN,
+        distanceMax: ORBIT_DIST_MAX,
+        markerColor: 0x99ff99,
+        markerEmissive: 0x33cc55,
+        lightIntensity: 9,
+        lightDistance: 15, // ~30% smaller than the other markers' default reach
+    });
+    const mover = new PrototypeMover();
+    mover.kind = "orbit";
+    mover.cx = ORBIT_CX;
+    mover.cz = ORBIT_CZ;
+    mover.radius = ORBIT_RADIUS;
+    mover.height = ORBIT_HEIGHT;
+    mover.speed = ORBIT_SPEED;
+    ecd.addComponentToEntity(orbiter.entity, mover); // PrototypeMotionSystem links it via (PrototypeMover, Transform)
+}
+
+/**
+ * Spawn one 3D looping {@link AudioEmitter} (acoustic on) with a small emissive marker sphere so it's visible.
+ * Looping + 3D + autoplay → the emitter is "managed": it sounds once the listener (player) exists and is
+ * within `distanceMax`, after the context resumes on the first click.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {{id:string, clipPath:string, position:Vector3, distanceMin:number, distanceMax:number,
+ *          markerColor:number, markerEmissive:number, lightIntensity?:number, lightDistance?:number}} p
+ * @returns {{entity:number, transform:Transform}} the spawned entity + its transform (so a mover can drive it)
+ */
+function spawnAudioSource(ecd, { id, clipPath, position, distanceMin, distanceMax, markerColor, markerEmissive,
+                                 lightIntensity = SOURCE_LIGHT_INTENSITY, lightDistance = SOURCE_LIGHT_DISTANCE }) {
+    const event = EventDescription.from(
+        id,
+        SampleAudioClip.from(clipPath, { loop: true }),
+        {
+            is3D: true,
+            distanceMin,
+            distanceMax,
+            // Physically-based (sound-pressure-fitted) rolloff, sampled across [min, max] in metres: full
+            // volume within distanceMin, a natural log-ish falloff to silence at distanceMax. Reuses the
+            // engine's own falloff + curve builder rather than a hand-rolled line.
+            attenuation: buildAttenuationCurve(distanceMin, distanceMax, interpolate_irradiance_smith),
+        },
+    );
+
+    const emitter = new AudioEmitter();
+    emitter.event = event;
+    emitter.acoustic = true;   // occlusion / transmission / pathing
+    emitter.sourceRadius = 0.3; // a little volume so occlusion fades in/out rather than popping
+    emitter.autoplay = true;
+    emitter.volume.set(1);
+
+    const markerGeom = new SphereGeometry(0.3, 16, 16);
+    const markerMat = litMaterial({
+        color: markerColor,
+        emissive: markerEmissive,
+        emissiveIntensity: 1.4,
+        roughness: 0.4,
+    });
+    const sg = ShadedGeometry.from(markerGeom, markerMat);
+    sg.setFlag(ShadedGeometryFlags.Visible);
+    sg.setFlag(ShadedGeometryFlags.CastShadow);
+
+    // A point light co-located with the marker — the markers were already emissive, this lets each one cast a
+    // coloured glow into its room (the light colour is taken from the marker's emissive tint).
+    const light = new Light();
+    light.type.set(Light.Type.POINT);
+    light.color.setRGBUint8((markerEmissive >> 16) & 0xff, (markerEmissive >> 8) & 0xff, markerEmissive & 0xff);
+    light.intensity.set(lightIntensity);
+    light.distance.set(lightDistance);
+
+    const transform = new Transform();
+    transform.position.copy(position);
+
+    const eb = new Entity()
+        .add(emitter)
+        .add(sg)
+        .add(light)
+        .add(Tag.fromJSON(["AudioSource"]))
+        .add(SerializationMetadata.Transient)
+        .add(transform);
+    eb.build(ecd);
+
+    return { entity: eb.id, transform };
+}
+
+/**
+ * Add a box to the world: visual ({@link ShadedGeometry}) + a static physics body ({@link RigidBody} +
+ * {@link Collider}). If an {@link AcousticMaterial} is given, it also becomes an {@link AcousticBody}
+ * occluder (the same Collider shape is the occluding geometry). Position is the box centre; Transform is
+ * added LAST so the (RigidBody, Transform) and (AcousticBody, Collider, Transform) tuples complete on it.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {object} p
+ * @param {Vector3} p.center
+ * @param {Vector3} p.size                 full w, h, d
+ * @param {number} p.color
+ * @param {number} [p.roughness]
+ * @param {AcousticMaterial} [p.material]  present → also an acoustic occluder
+ * @param {Quaternion} [p.rotation]        present → the box is oriented (e.g. a ramp); physics + acoustics use it
+ */
+function spawnBox(ecd, { center, size, color, roughness = 0.8, material, rotation }) {
+    const geom = new BoxGeometry(size.x, size.y, size.z);
+    const mat = litMaterial({ color, roughness });
+    const sg = ShadedGeometry.from(geom, mat);
+    sg.setFlag(ShadedGeometryFlags.CastShadow);
+    sg.setFlag(ShadedGeometryFlags.ReceiveShadow);
+    sg.setFlag(ShadedGeometryFlags.Visible);
+
+    const rigidBody = new RigidBody();
+    rigidBody.kind = BodyKind.Static;
+
+    const collider = new Collider();
+    // Explicit half/full-extent box → the closed-form box narrowphase, not GJK+EPA.
+    collider.shape = BoxShape3D.from_size(size.x, size.y, size.z);
+
+    const transform = new Transform();
+    transform.position.copy(center);
+    if (rotation !== undefined) {
+        transform.rotation.copy(rotation); // a tilted box — the renderer, the collider, and the occluder all honour it
+    }
+
+    const eb = new Entity()
+        .add(sg)
+        .add(rigidBody)
+        .add(collider)
+        .add(Tag.fromJSON(["AcousticDemo"]))
+        .add(SerializationMetadata.Transient);
+
+    if (material !== undefined) {
+        eb.add(AcousticBody.from(material));
+    }
+
+    eb.add(transform).build(ecd);
+}
+
+// =====================================================================
+// Player + input (mirrors the first-person gym, minus the parkour abilities)
+// =====================================================================
+
+/**
+ * @param {EntityComponentDataset} ecd
+ * @returns {{entity:number, controller:FirstPersonPlayerController}}
+ */
+function buildPlayerEntity(ecd) {
+    const transform = new Transform();
+    transform.position.set(SPAWN_X, 0, SPAWN_Z);
+
+    // Plain walk / look / jump — no parkour abilities for this acoustic walkaround.
+    const controller = new FirstPersonPlayerController();
+
+    const bodyCfg = controller.config.body;
+    const radius = bodyCfg.radius;
+    const totalHeight = bodyCfg.height;
+    const cylinderHeight = Math.max(0, totalHeight - 2 * radius);
+
+    const rigidBody = new RigidBody();
+    rigidBody.kind = BodyKind.KinematicPosition;
+    rigidBody.mass = bodyCfg.mass;
+
+    const collider = new Collider();
+    // Capsule bottom at the feet (Transform.position), top at the head — see the gym prototype.
+    collider.shape = TransformedShape3D.from_translation(
+        CapsuleShape3D.from(radius, cylinderHeight),
+        [0, totalHeight / 2, 0],
+    );
+
+    const eb = new Entity()
+        .add(controller)
+        .add(rigidBody)
+        .add(collider)
+        .add(Tag.fromJSON(["Player"]))
+        .add(SerializationMetadata.Transient)
+        .add(transform);
+
+    eb.build(ecd);
+
+    // The acoustic listener rides the CAMERA (eye height), not the feet. Building the player linked the
+    // first-person controller, whose link() created an eye entity — a Camera + a Transform driven to eye
+    // height and look direction every frame — so attaching the SoundListener there makes occlusion / pathing
+    // (and the WebAudio listener pose) test from the EARS. At feet height (Transform.position) a window sill
+    // or a low wall occludes a source the player plainly sees through it; the modelled ears were below the
+    // geometry the eye is above. (Component-add linking is synchronous, so controller.eyeEntity is valid here.)
+    ecd.addComponentToEntity(controller.eyeEntity, new SoundListener());
+
+    return { entity: eb.id, controller };
+}
+
+/**
+ * Keyboard + mouse → the controller's intent surface (WASD move, mouse look, space jump).
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {{entity:number, controller:FirstPersonPlayerController}} player
+ * @param {PrototypeMotionSystem} motion drives the doors; E operates the one the player is next to
+ */
+function buildInputBindings(ecd, player, motion) {
+    const ic = new InputController();
+    const intent = player.controller.intent;
+
+    const SENSITIVITY = (Math.PI * 2) / 1200;
+
+    const held = { w: false, a: false, s: false, d: false };
+
+    function recomputeMove() {
+        let mx = 0, my = 0;
+        if (held.d) mx += 1;
+        if (held.a) mx -= 1;
+        if (held.w) my += 1;
+        if (held.s) my -= 1;
+        intent.move.set(mx, my);
+    }
+
+    function bindMoveKey(key, prop) {
+        ic.bind(`keyboard/keys/${key}/down`, () => { held[prop] = true; recomputeMove(); });
+        ic.bind(`keyboard/keys/${key}/up`, () => { held[prop] = false; recomputeMove(); });
+    }
+
+    bindMoveKey("w", "w");
+    bindMoveKey("a", "a");
+    bindMoveKey("s", "s");
+    bindMoveKey("d", "d");
+
+    ic.bind("keyboard/keys/space/down", () => { intent.jump = true; });
+    ic.bind("keyboard/keys/space/up", () => { intent.jump = false; });
+
+    // Sprint — hold Shift while moving (the controller reads intent.sprint; see prototype_first_person_controller).
+    ic.bind("keyboard/keys/shift/down", () => { intent.sprint = true; });
+    ic.bind("keyboard/keys/shift/up", () => { intent.sprint = false; });
+
+    // E — operate the door the player is standing next to (the motion system tracks which one is in range).
+    ic.bind("keyboard/keys/e/down", () => { motion.toggleActiveDoor(); });
+
+    ic.bind("pointer/on/move", (position, event, delta) => {
+        if (document.pointerLockElement === null) return;
+        intent.look._add(delta.x * SENSITIVITY, delta.y * SENSITIVITY);
+    });
+
+    ic.on.unlinked.add(() => {
+        intent.move.set(0, 0);
+        intent.look.set(0, 0);
+        intent.jump = false;
+        intent.sprint = false;
+    });
+
+    new Entity()
+        .add(ic)
+        .add(Tag.fromJSON(["FirstPersonInputBindings"]))
+        .add(SerializationMetadata.Transient)
+        .build(ecd);
+}
+
+/**
+ * Wire the canvas click to (a) start audio and (b) capture the mouse.
+ *
+ * The autoplay policy requires a user gesture before audio: the engine creates the context suspended and
+ * starts ticking immediately, so we must not let the source play before the first click. On that click we
+ * resume the context and — only once `resume()` has actually resolved — spawn the source, so its first
+ * `playEvent` lands on a running context (no autoplay warning). Pointer lock is (re)requested every click;
+ * ESC (browser default) releases it.
+ *
+ * @param {Engine} engine
+ * @param {EntityComponentDataset} ecd
+ */
+function setupInteraction(engine, ecd) {
+    const el = engine.graphics.domElement;
+    const captureEl = engine.viewStack.el;
+
+    let audioStarted = false;
+
+    captureEl.addEventListener("click", () => {
+        if (!audioStarted) {
+            audioStarted = true;
+            // resume() returns the context.resume() promise — spawn the sources only after it resolves, so the
+            // first playEvent lands on a running context.
+            engine.sound.resumeContext().then(() => buildSources(ecd));
+        }
+
+        if (document.pointerLockElement === el || !el.requestPointerLock) return;
+        let p;
+        try {
+            p = el.requestPointerLock({ unadjustedMovement: true });
+        } catch (e) {
+            el.requestPointerLock();
+            return;
+        }
+        if (p && typeof p.catch === "function") {
+            p.catch(() => { el.requestPointerLock(); });
+        }
+    });
+
+    captureEl.addEventListener("contextmenu", (e) => e.preventDefault());
+}
+
+function logHelp() {
+    /* eslint-disable no-console */
+    console.log("%cAcoustic solver — first-person walkaround",
+        "color:#88ddff;font-weight:bold;font-size:14px");
+    console.log("Click the canvas to capture the mouse (and start audio). ESC to release.");
+    console.log("WASD = move | Shift = sprint | Mouse = look | Space = jump | E = operate a door | P = probe overlay");
+    console.log("");
+    console.log("%cThree sources + a tiny chamber — listen as you move:", "font-weight:bold");
+    console.log("  • HOUSE (main-menu) — a tight, dead room; leaks from its DOOR (south) + WINDOW (north); a");
+    console.log("    REFLECTOR wall north of the window bounces the window leak back at you");
+    console.log("  • CATHEDRAL (main-menu, west across the gap) — a tall stone hall: long reverb + a coupled");
+    console.log("    TOWER tail. SAME loop as the house, so the difference you hear is purely the room");
+    console.log("  • ORBITER (WorldMode) — circles the scene from outside; fades in/out as buildings break LoS");
+    console.log("  • SHACK (south-east) — a tiny hard reverb chamber; step in for a bright, ringy room tone");
+    console.log("  • DOORS — walk up to the house door / cathedral entrance and press E to lower/raise it");
+    console.log("  • RAMPS up onto the house roof + across to the cathedral roof; duck behind a barrier to occlude");
+}
+
+// =====================================================================
+// Probe visualization (toggleable debug overlay)
+// =====================================================================
+
+/**
+ * Toggleable debug overlay for the baked field: the probe positions (small 3-axis crosses) and the
+ * visibility-graph edges (line segments between mutually-visible probes). Mimics
+ * {@link visualize_tetrahedral_mesh} / {@link lpv_visualize_probes} — built as {@link DrawMode.LineSegments}
+ * {@link ShadedGeometry}, and ADDED/REMOVED on toggle (so there is zero cost while hidden, and no reliance
+ * on live flag mutation).
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {AcousticProbeField} field
+ * @returns {{toggle: function(): void, shown: boolean}}
+ */
+function makeProbeVisualization(ecd, field) {
+    let ids = null; // [edgesEntity, probesEntity] while shown; null while hidden
+
+    function show() {
+        // Magenta edges read clearly against the blue sky (cyan washed out); probe crosses stay amber.
+        const edges = lineSegmentsEntity(buildVisibilityEdgesGeometry(field), 0xff00ff, 0.7);
+        const probes = lineSegmentsEntity(buildProbeMarkersGeometry(field, 0.18), 0xffdd33, 1.0);
+        edges.build(ecd);
+        probes.build(ecd);
+        ids = [edges.id, probes.id];
+    }
+
+    function hide() {
+        for (const id of ids) {
+            ecd.removeEntity(id);
+        }
+        ids = null;
+    }
+
+    return {
+        toggle() {
+            if (ids === null) {
+                show();
+            } else {
+                hide();
+            }
+        },
+        get shown() {
+            return ids !== null;
+        },
+    };
+}
+
+/**
+ * A LineSegments {@link ShadedGeometry} entity over `geometry` — the unlit, shadowless, no-depth-write
+ * debug-draw recipe from {@link visualize_tetrahedral_mesh}. Geometry positions are absolute world coords,
+ * so the entity carries an identity {@link Transform}.
+ */
+function lineSegmentsEntity(geometry, color, opacity) {
+    const material = new LineBasicMaterial({ color, transparent: true, opacity, depthWrite: false });
+    const sg = ShadedGeometry.from(geometry, material, DrawMode.LineSegments);
+    sg.clearFlag(ShadedGeometryFlags.CastShadow);
+    sg.clearFlag(ShadedGeometryFlags.ReceiveShadow);
+
+    return new Entity()
+        .add(sg)
+        .add(Tag.fromJSON(["ProbeViz"]))
+        .add(SerializationMetadata.Transient)
+        .add(new Transform());
+}
+
+/** LineSegments geometry: one segment per visibility-graph edge (each undirected edge emitted once). */
+function buildVisibilityEdgesGeometry(field) {
+    const positions = [];
+    const graph = field.visibilityGraph;
+
+    if (graph !== null) {
+        const addresses = graph.edge_addresses;
+        const adjacency = graph.adjacency;
+
+        for (let v = 0; v < graph.vertex_count; v++) {
+            const end = addresses[v + 1];
+            for (let k = addresses[v]; k < end; k++) {
+                const u = adjacency[k];
+                if (v < u) { // CSR is symmetric — emit each undirected edge once
+                    positions.push(field.probeX(v), field.probeY(v), field.probeZ(v));
+                    positions.push(field.probeX(u), field.probeY(u), field.probeZ(u));
+                }
+            }
+        }
+    }
+
+    return lineGeometry(positions);
+}
+
+/** LineSegments geometry: a small 3-axis cross (3 segments) at each probe position. */
+function buildProbeMarkersGeometry(field, r) {
+    const positions = [];
+
+    for (let i = 0; i < field.size; i++) {
+        const x = field.probeX(i);
+        const y = field.probeY(i);
+        const z = field.probeZ(i);
+
+        positions.push(x - r, y, z, x + r, y, z);
+        positions.push(x, y - r, z, x, y + r, z);
+        positions.push(x, y, z - r, x, y, z + r);
+    }
+
+    return lineGeometry(positions);
+}
+
+/** A BufferGeometry with a single position attribute (3 floats/vertex). */
+function lineGeometry(positions) {
+    const geometry = new BufferGeometry();
+    geometry.setAttribute("position", new Float32BufferAttribute(positions, 3));
+    return geometry;
+}
+
+/**
+ * On-screen toggle for the probe overlay: a top-right button plus the P key. (The button can't be clicked
+ * while the pointer is locked — the OS hides the cursor — so the key is the in-play toggle; ESC unlocks to
+ * reach the button.)
+ *
+ * @param {{toggle: function(): void, shown: boolean}} viz
+ */
+function setupProbeVizToggle(viz) {
+    const button = document.createElement("button");
+    Object.assign(button.style, {
+        position: "absolute",
+        top: "10px",
+        right: "10px",
+        zIndex: "1000",
+        padding: "8px 12px",
+        font: "13px sans-serif",
+        color: "#cfe6ff",
+        background: "rgba(18,26,34,0.85)",
+        border: "1px solid #3a6ea5",
+        borderRadius: "4px",
+        cursor: "pointer",
+    });
+
+    function sync() {
+        button.textContent = `Probes: ${viz.shown ? "ON" : "off"} (P)`;
+    }
+
+    sync();
+
+    button.addEventListener("click", (e) => {
+        e.stopPropagation(); // don't let the canvas capture-click also fire (pointer lock)
+        viz.toggle();
+        sync();
+    });
+
+    document.body.appendChild(button);
+
+    window.addEventListener("keydown", (e) => {
+        if (e.code === "KeyP") {
+            viz.toggle();
+            sync();
+        }
+    });
+}
+
+async function init() {
+    await eh.initialize({ configuration: setupSound });
+    await main(eh.engine);
+}
+
+init();