@woosh/meep-engine 3.1.0 → 3.2.0

package/src/engine/sound/simulation/README.md

@@ -1,277 +1,277 @@
-# Acoustic Simulation
-
-Geometry-driven acoustics for meep — occlusion, transmission, propagation medium, geometry-derived
-reverb, and pathing — that **feeds the [sopra](../sopra/README.md) sound engine**. This layer is the
-meep equivalent of what Steam Audio is to FMOD/Wwise: it *simulates* how sound interacts with the world,
-and sopra *renders* the result through WebAudio.
-
-> One rule above all: **this layer computes, sopra renders.** `simulation/core`, `simulation/ecs`, and
-> `simulation/probe` import **no WebAudio**. They turn scene geometry into an `AcousticSolution` (a few
-> numbers per source) and baked data (reverb probes, a visibility graph). Only the thin `simulation/render`
-> folder and the `EventInstance.setAcoustic` seam touch WebAudio. Because of that the whole simulation is
-> unit-testable on bare geometry with no audio mock.
-
----
-
-## The idea: simulator vs. renderer
-
-```
-  SIMULATION (this folder — geometry, JS, no WebAudio)            RENDER (sopra — WebAudio)
-  ─────────────────────────────────────────────────────          ─────────────────────────
-  AcousticBody   (occluder shapes + material) ─┐
-  AcousticVolume (medium regions)              ├─► AcousticSolution ─► EventInstance.setAcoustic()
-  ray queries (BVH over shapes) + fibonacci ───┘    {occlusion,           (gain + lowpass + transmission)
-                                                     transmission[3],
-  AcousticProbeField (baked per-band reverb) ──────────────► medium,      ─► ProbeReverbRenderer (convolver)
-   + probe-visibility graph (pathing) ─────────────►  exit, path} ─► exit-point send (EventInstance)
-```
-
-WebAudio is a **renderer, not a simulator** — it has no geometry/ray/scene API. So every acoustic
-feature is "compute a factor / IR / path against meep geometry, then drive native nodes with it." The
-render primitives (`GainNode`, `BiquadFilterNode`, `ConvolverNode`) already exist; this layer supplies
-their *inputs*.
-
-A source **opts in** with one flag (`AudioEmitter.acoustic = true`). Medium and occlusion are properties
-of the **world** (`AcousticVolume` / `AcousticBody` components), never of the event.
-
----
-
-## Directory map
-
-```
-simulation/
-  AcousticSimulator.js          the engine: owns the occluder index + medium regions + solvers; solveFor / apply
-  configureAcousticSimulation.js one-call ECS wiring (build the simulator, add the systems, inject the emitter)
-  definition/                   authored value types (serializable)
-    AcousticMaterial.js           3-band absorption / scattering / transmission of a surface
-    AcousticDirectivity.js        source radiation pattern (monopole→dipole) — how a source "points" its sound
-  core/                         ECS-agnostic AND WebAudio-agnostic — the testable heart
-    AcousticOccluderIndex.js      dynamic ray index — a TLAS BVH over OccluderBody shapes (exact shape.raycast)
-    OccluderBody.js               one occluder: shape + material + world transform (+ cached inverse / AABB)
-    RayHit.js                     reusable closest-hit result (caller-allocated): point + normal + t + material
-    OcclusionSolver.js            volumetric occlusion + transmission for one source (temporally smoothed)
-    VolumeField.js                blends AcousticVolume regions into a medium at a point + integrates air
-                                  absorption along the source→listener path (distance-dependent, per band)
-    AcousticVolumeRegion.js       a shape + medium + transition band (boundary blend)
-    AcousticMedium.js             propagation medium (air absorption per band, dB/metre)
-    AcousticSolution.js           the per-source result the render seam consumes
-    AcousticSourceState.js        transient per-source temporal accumulation (pool-backed cursor)
-  ecs/                          thin ECS binding (real-component tested)
-    AcousticBody.js / AcousticSimulationSystem.js     occluders (pair with Collider + Transform)
-    AcousticVolume.js / AcousticVolumeSystem.js       medium regions (pair with Transform)
-  probe/                        the baked substrate (offline; no WebAudio)
-    bakeProbeField.js             place a grid of probes (density knob) and bake each
-    AcousticProbeField.js                 the baked probe volume — flat Float32Array storage (per-band RT60 +
-                                  per-band arrival direction) + BVH nearest-probe lookup + visibility graph
-    acoustic_trace_energy.js      one ray's multi-bounce per-band energy deposit into a time-binned echogram,
-                                  + the energy-weighted launch direction (FOA arrival vector) per band
-    echogram_band_rt60.js         reduce one band's echogram to RT60 (Schroeder + ISO-3382 T30 slope)
-    bakeReverbBands.js            N rays → echogram → per-band RT60 + per-band arrival direction for a probe
-    bakeVisibility.js             connect probes by line-of-sight into the field's graph + findAcousticPath
-    probe_edge_visible.js         the one shadow-ray edge test shared by the bake and the runtime recheck
-    ProbeFieldPathingSolution.js  per-frame, per-listener exit-field solve (public dist/next/exit buffers)
-    ProbeVisibilityRecheck.js     budgeted dynamic-geometry recheck — disables/restores edges vs live geometry
-  serialization/                binary save/load adapters (registered via populateAcousticSerializationRegistry)
-  render/                       the ONLY WebAudio code in this layer
-    ProbeReverbRenderer.js        scalar acoustic-owned reverb bus (double-buffered convolver crossfade)
-    reverbImpulseResponse.js      per-band decaying-noise IR from [low, mid, high] RT60 (band-split, seeded)
-    FoaProbeReverbRenderer.js     directional (FOA / B-format) reverb bus — rotate-the-decoder stereo decode
-    foaReverbImpulseResponse.js   per-band W,X,Y,Z B-format IR steered by the baked arrival direction
-  bench/                        perf calibration
-```
-
-The render seam (`EventInstance.setAcoustic` + the inserted nodes, the `AudioEmitter.acoustic` flag, the
-`AudioEmitterSystem` driving) lives in **sopra / the ECS audio layer**, not here.
-
----
-
-## Quick start
-
-### 1. Wire it into the engine
-
-`configureAcousticSimulation` does the whole runtime wiring in one call — it builds (or reuses) the
-shared simulator, registers the two ECS systems against it, and injects the simulator into the
-`AudioEmitterSystem` whose per-frame `update()` drives it:
-
-```js
-import { configureAcousticSimulation } from "./configureAcousticSimulation.js";
-
-// `audioEmitterSystem` is constructed without an acousticSim; this injects it.
-// args: (configuration, audioEmitterSystem, simulator?, probeReverb?)
-const sim = configureAcousticSimulation(configuration, audioEmitterSystem, undefined, probeReverb);
-
-sim.random_seed = 1;   // optional — deterministic ray jitter (default 1)
-sim.rayCount = 16;     // rays per source per tick (amortized over frames)
-sim.smoothing = 0.4;   // temporal EMA
-```
-
-Under the hood that adds `AcousticSimulationSystem` (`AcousticBody` + `Collider` + `Transform` →
-occluders) and `AcousticVolumeSystem` (`AcousticVolume` + `Transform` → medium regions), both feeding the
-one returned simulator.
-
-Tag scene geometry as an occluder by adding an `AcousticBody` (with an `AcousticMaterial`) to an entity
-that already has a `Collider` + `Transform`. Add an `AcousticVolume` (a shape + `AcousticMedium`) to mark
-a region of different air.
-
-### 2. Opt sources in
-
-```js
-emitter.acoustic = true;     // 3D events with this set get occlusion / transmission / medium
-emitter.sourceRadius = 0.5;  // apparent source size, for volumetric (fractional) occlusion
-
-// optional: source DIRECTIVITY — radiate more toward where the entity faces (its Transform rotation).
-emitter.directivity.dipoleWeight = 0.5;  // 0 = omni (default), 0.5 = cardioid, 1 = dipole / figure-8
-emitter.directivity.dipolePower = 1;     // sharpen the lobe (> 1 narrows it)
-```
-
-Each frame the `AudioEmitterSystem` solves occlusion + transmission (ray-traced against the
-`AcousticBody` geometry), the medium (blended `AcousticVolume`s), and — for a non-omni source — the
-radiation **directivity** (the angle between where the source faces and the listener) for every live
-acoustic 3D instance, and pushes the result to `EventInstance.setAcoustic`, which drives an occlusion gain
-(scaled by directivity) + lowpass + transmission filter inserted in that instance's chain. All
-off-by-default: a non-acoustic event renders exactly as before, and an omni source pays nothing for
-directivity.
-
-### 3. Bake + wire reverb (offline once, render at runtime)
-
-```js
-import { bakeProbeField } from "./probe/bakeProbeField.js";
-import { ProbeReverbRenderer } from "./render/ProbeReverbRenderer.js";
-import { seededRandom } from "../../../core/math/random/seededRandom.js";
-
-// OFFLINE: place probes over the scene (the bake region is derived from the occluder hull) and bake each
-// probe's per-band RT60. minSpacing is the density knob (smaller = denser).
-const probes = bakeProbeField(sim.occluderIndex, /*minSpacing*/ 8, /*rayCount*/ 256, seededRandom(1));
-const json = probes.toJSON();   // serialize, ship as an asset
-
-// RUNTIME: an acoustic-owned reverb bus driven by the listener's nearest probe
-const reverb = new ProbeReverbRenderer(audioContext, masterDestination);
-reverb.setProbeField(probes);
-sopraBusOutput.connect(reverb.input);   // send a copy of the dry signal in
-// pass `reverb` as options.probeReverb to configureAcousticSimulation, or assign it directly:
-audioSystem.probeReverb = reverb;       // driven once per frame from the listener
-```
-
-(`sim.occluderIndex` exposes the live occluder geometry so the bake runs against the same scene the
-runtime occludes with.)
-
-For **directional** reverb, drop in `FoaProbeReverbRenderer` instead — same bake, same wiring, but it
-renders the probe's per-band **arrival direction** (baked alongside the RT60) as a first-order ambisonic
-(B-format) field decoded to stereo, and steered by the listener's orientation so the reverb leans toward
-the open door / off the near wall and stays world-anchored as the head turns. It is driven the same way;
-`AudioEmitterSystem` passes the listener rotation to `update()` (the scalar renderer ignores it):
-
-```js
-import { FoaProbeReverbRenderer } from "./render/FoaProbeReverbRenderer.js";
-
-const reverb = new FoaProbeReverbRenderer(audioContext, masterDestination);
-reverb.setProbeField(probes);           // the SAME baked field — directions ride along
-sopraBusOutput.connect(reverb.input);
-audioSystem.probeReverb = reverb;        // driven from the listener pose (position + orientation)
-```
-
-The stereo decode is isolated so a binaural/HRTF (SOFA) decoder can replace it later without touching the
-encode/rotate path.
-
-### 4. Pathing (corner-leakage), optional
-
-```js
-import { bakeVisibility } from "./probe/bakeVisibility.js";
-
-bakeVisibility(probes, sim.occluderIndex); // bake the inter-probe visibility graph into the field
-sim.setProbeField(probes);                 // the field whose visibility graph pathing routes through
-sim.pathing = true;                        // engine-wide toggle (off by default)
-
-sim.pathingRecheck = true;                 // optional: re-verify traversed edges against LIVE geometry
-sim.recheckBudget = 8;                     //   (a closing door re-blocks the leak; budgeted, off by default)
-```
-
-The leak send carries the same acoustics as the direct path, but along the *routed* polyline: it is scaled
-by the source's **directivity toward the corner it leaks through** (not the blocked listener) and darkened by
-**air absorption over the longer leaked distance**. With `pathingRecheck`, the edges leaks traverse are
-re-tested each tick (within `recheckBudget`); an edge a mover has since blocked is disabled by weight
-(`EDGE_WEIGHT_BLOCKED`, no topology change) and restored when it re-opens — the cheap real-time half of the
-real-time-direct / baked-indirect split.
-
----
-
-## The simulation, in one paragraph each
-
-**Occlusion + transmission.** For each live source, `OcclusionSolver` shoots `rayCount` rays from the
-listener toward points spread over the source's sphere (Fibonacci distribution, randomly re-oriented per
-tick). The fraction blocked is the occlusion; the blocked rays' material `transmission` (3 bands) is what
-leaks through. The result is folded into a temporal EMA, so a low ray count integrates over frames and
-the output never flickers. Rendered as a broadband gain (occluded → quieter, floored by transmission)
-plus a lowpass (occluded → muffled).
-
-**Medium / air absorption.** `AcousticVolume` regions carry an `AcousticMedium` whose `airAbsorption` is in
-**dB per metre**, per band. `VolumeField.integrateAbsorption` line-integrates it along the source→listener
-path (`∫ α ds`, blending regions + ambient air at each step) into `AcousticSolution.airLoss` — the per-band
-total dB lost over the path. So highs, which absorb faster, die over distance while the low end carries
-(distance-dependent atmospheric absorption); a thicker painted region adds extra loss where the path crosses
-it. Open air uses a small default atmosphere (tunable via the simulator's `defaultMedium`).
-
-It is rendered as a **low-anchored spectral tilt**: only the high‑vs‑low *excess* loss
-(`airLoss[high] − airLoss[low]`) drops the lowpass cutoff, so a uniform loss — which the authored distance
-**attenuation curve** already owns as broadband loudness — causes no darkening. The air filter is a separate
-series node from the attenuation gain, so the two compose (multiply) rather than fight: the curve owns *how
-loud*, air absorption owns *how bright*.
-
-**Reverb.** Offline, `bakeProbeField` bakes each probe's **per-band** reverberation. For a probe,
-`acoustic_trace_energy` shoots rays that bounce multiply through the scene ("source at the listener"),
-depositing per-band energy into a time-binned echogram; `echogram_band_rt60` reduces each band's decay to
-an RT60 (Schroeder backward integration + the ISO-3382 T30 slope). The bake is validated against the
-analytic **Sabine** reverberation time of a closed box. At runtime the listener's nearest probe sets the
-per-band RT60, which `reverbImpulseResponse` turns into a band-split decaying-noise convolution IR (so a
-bright room's tail rings longer in the highs), crossfaded by `ProbeReverbRenderer` as you cross probe
-cells.
-
-**Pathing (corner-leakage).** Offline, `bakeVisibility` connects probes with mutual line-of-sight into
-the `AcousticProbeField`'s visibility graph (a `CSRGraph` adjacency — connectivity is an inherent property of the
-field). At runtime, when the engine-wide `AcousticSimulator.pathing` toggle is on, one single-source
-Dijkstra from the listener (`ProbeFieldPathingSolution.computeExitField`, a per-frame solver the simulator
-owns) gives every probe its **exit point** — the probe adjacent to the listener on its
-path. Each occluded source then routes a second, exit-spatialized send, so a sound blocked by a wall is
-heard coming from the *doorway it leaks through*, not through the wall. Engine-wide toggle, **off by
-default (zero cost when off)** — no per-source flag.
-
----
-
-## Performance
-
-Per-frame cost is bounded by the **live voice budget** (≤ 64), not the world size — the sim only touches
-promoted instances. Each source costs `rayCount` rays; a top-level BVH (TLAS) over the occluder bodies
-means a ray pays only for the few occluders near it, not every registered body. Tune `rayCount` down +
-lean on the temporal smoothing to amortize. The reverb/visibility bakes are offline (no frame budget).
-See `bench/occlusion.bench.spec.js` (remove `.skip` on the sweep to read µs/ray for your scene).
-
----
-
-## Testing
-
-Everything except `render/` is WebAudio-free, so tests use real geometry and real ECS components — no
-audio mock. The render seam + reverb renderer use sopra's `MockAudioContext`.
-
-```
-npx jest --config jest.conf.json engine/sound/simulation     # from the repo root H:/git/moh
-```
-
----
-
-## Status
-
-**Built + tested:** the whole simulation engine (P0–P6) + the **ray-traced per-band reflection-IR reverb**
-(the keystone: multi-bounce energy trace → per-band RT60, Sabine-validated → band-split IR render) + the
-occlusion / transmission / medium render seam + the corner-leakage (pathing) render. All wired into sopra
-+ `AudioEmitterSystem` (one call via `configureAcousticSimulation`), additive and off-by-default.
-
-**Not yet wired (gated on the sopra strangler migration, all outside this folder):** production
-registration in `makeMirEngineConfig` (the legacy `SoundEmitter` path is still the live one) + save/load
-**binary serialization adapters** for `AcousticBody`/`AcousticVolume` — deliberately deferred to match
-`AudioEmitter`, which has none either (the components carry JSON `toJSON`/`fromJSON` for when it lands).
-
-**Optional / on-demand (not v1):** NEE-to-source early reflections, pathing live-recheck + door variants,
-FOA ambisonics, SOFA HRTF, source directivity.
-
-See [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md) and [REFLECTION_IR_PLAN.md](./REFLECTION_IR_PLAN.md)
-for the full phase-by-phase record and decisions.
+# Acoustic Simulation
+
+Geometry-driven acoustics for meep — occlusion, transmission, propagation medium, geometry-derived
+reverb, and pathing — that **feeds the [sopra](../sopra/README.md) sound engine**. This layer is the
+meep equivalent of what Steam Audio is to FMOD/Wwise: it *simulates* how sound interacts with the world,
+and sopra *renders* the result through WebAudio.
+
+> One rule above all: **this layer computes, sopra renders.** `simulation/core`, `simulation/ecs`, and
+> `simulation/probe` import **no WebAudio**. They turn scene geometry into an `AcousticSolution` (a few
+> numbers per source) and baked data (reverb probes, a visibility graph). Only the thin `simulation/render`
+> folder and the `EventInstance.setAcoustic` seam touch WebAudio. Because of that the whole simulation is
+> unit-testable on bare geometry with no audio mock.
+
+---
+
+## The idea: simulator vs. renderer
+
+```
+  SIMULATION (this folder — geometry, JS, no WebAudio)            RENDER (sopra — WebAudio)
+  ─────────────────────────────────────────────────────          ─────────────────────────
+  AcousticBody   (occluder shapes + material) ─┐
+  AcousticVolume (medium regions)              ├─► AcousticSolution ─► EventInstance.setAcoustic()
+  ray queries (BVH over shapes) + fibonacci ───┘    {occlusion,           (gain + lowpass + transmission)
+                                                     transmission[3],
+  AcousticProbeField (baked per-band reverb) ──────────────► medium,      ─► ProbeReverbRenderer (convolver)
+   + probe-visibility graph (pathing) ─────────────►  exit, path} ─► exit-point send (EventInstance)
+```
+
+WebAudio is a **renderer, not a simulator** — it has no geometry/ray/scene API. So every acoustic
+feature is "compute a factor / IR / path against meep geometry, then drive native nodes with it." The
+render primitives (`GainNode`, `BiquadFilterNode`, `ConvolverNode`) already exist; this layer supplies
+their *inputs*.
+
+A source **opts in** with one flag (`AudioEmitter.acoustic = true`). Medium and occlusion are properties
+of the **world** (`AcousticVolume` / `AcousticBody` components), never of the event.
+
+---
+
+## Directory map
+
+```
+simulation/
+  AcousticSimulator.js          the engine: owns the occluder index + medium regions + solvers; solveFor / apply
+  configureAcousticSimulation.js one-call ECS wiring (build the simulator, add the systems, inject the emitter)
+  definition/                   authored value types (serializable)
+    AcousticMaterial.js           3-band absorption / scattering / transmission of a surface
+    AcousticDirectivity.js        source radiation pattern (monopole→dipole) — how a source "points" its sound
+  core/                         ECS-agnostic AND WebAudio-agnostic — the testable heart
+    AcousticOccluderIndex.js      dynamic ray index — a TLAS BVH over OccluderBody shapes (exact shape.raycast)
+    OccluderBody.js               one occluder: shape + material + world transform (+ cached inverse / AABB)
+    RayHit.js                     reusable closest-hit result (caller-allocated): point + normal + t + material
+    OcclusionSolver.js            volumetric occlusion + transmission for one source (temporally smoothed)
+    VolumeField.js                blends AcousticVolume regions into a medium at a point + integrates air
+                                  absorption along the source→listener path (distance-dependent, per band)
+    AcousticVolumeRegion.js       a shape + medium + transition band (boundary blend)
+    AcousticMedium.js             propagation medium (air absorption per band, dB/metre)
+    AcousticSolution.js           the per-source result the render seam consumes
+    AcousticSourceState.js        transient per-source temporal accumulation (pool-backed cursor)
+  ecs/                          thin ECS binding (real-component tested)
+    AcousticBody.js / AcousticSimulationSystem.js     occluders (pair with Collider + Transform)
+    AcousticVolume.js / AcousticVolumeSystem.js       medium regions (pair with Transform)
+  probe/                        the baked substrate (offline; no WebAudio)
+    bakeProbeField.js             place a grid of probes (density knob) and bake each
+    AcousticProbeField.js                 the baked probe volume — flat Float32Array storage (per-band RT60 +
+                                  per-band arrival direction) + BVH nearest-probe lookup + visibility graph
+    acoustic_trace_energy.js      one ray's multi-bounce per-band energy deposit into a time-binned echogram,
+                                  + the energy-weighted launch direction (FOA arrival vector) per band
+    echogram_band_rt60.js         reduce one band's echogram to RT60 (Schroeder + ISO-3382 T30 slope)
+    bakeReverbBands.js            N rays → echogram → per-band RT60 + per-band arrival direction for a probe
+    bakeVisibility.js             connect probes by line-of-sight into the field's graph + findAcousticPath
+    probe_edge_visible.js         the one shadow-ray edge test shared by the bake and the runtime recheck
+    ProbeFieldPathingSolution.js  per-frame, per-listener exit-field solve (public dist/next/exit buffers)
+    ProbeVisibilityRecheck.js     budgeted dynamic-geometry recheck — disables/restores edges vs live geometry
+  serialization/                binary save/load adapters (registered via populateAcousticSerializationRegistry)
+  render/                       the ONLY WebAudio code in this layer
+    ProbeReverbRenderer.js        scalar acoustic-owned reverb bus (double-buffered convolver crossfade)
+    reverbImpulseResponse.js      per-band decaying-noise IR from [low, mid, high] RT60 (band-split, seeded)
+    FoaProbeReverbRenderer.js     directional (FOA / B-format) reverb bus — rotate-the-decoder stereo decode
+    foaReverbImpulseResponse.js   per-band W,X,Y,Z B-format IR steered by the baked arrival direction
+  bench/                        perf calibration
+```
+
+The render seam (`EventInstance.setAcoustic` + the inserted nodes, the `AudioEmitter.acoustic` flag, the
+`AudioEmitterSystem` driving) lives in **sopra / the ECS audio layer**, not here.
+
+---
+
+## Quick start
+
+### 1. Wire it into the engine
+
+`configureAcousticSimulation` does the whole runtime wiring in one call — it builds (or reuses) the
+shared simulator, registers the two ECS systems against it, and injects the simulator into the
+`AudioEmitterSystem` whose per-frame `update()` drives it:
+
+```js
+import { configureAcousticSimulation } from "./configureAcousticSimulation.js";
+
+// `audioEmitterSystem` is constructed without an acousticSim; this injects it.
+// args: (configuration, audioEmitterSystem, simulator?, probeReverb?)
+const sim = configureAcousticSimulation(configuration, audioEmitterSystem, undefined, probeReverb);
+
+sim.random_seed = 1;   // optional — deterministic ray jitter (default 1)
+sim.rayCount = 16;     // rays per source per tick (amortized over frames)
+sim.smoothing = 0.4;   // temporal EMA
+```
+
+Under the hood that adds `AcousticSimulationSystem` (`AcousticBody` + `Collider` + `Transform` →
+occluders) and `AcousticVolumeSystem` (`AcousticVolume` + `Transform` → medium regions), both feeding the
+one returned simulator.
+
+Tag scene geometry as an occluder by adding an `AcousticBody` (with an `AcousticMaterial`) to an entity
+that already has a `Collider` + `Transform`. Add an `AcousticVolume` (a shape + `AcousticMedium`) to mark
+a region of different air.
+
+### 2. Opt sources in
+
+```js
+emitter.acoustic = true;     // 3D events with this set get occlusion / transmission / medium
+emitter.sourceRadius = 0.5;  // apparent source size, for volumetric (fractional) occlusion
+
+// optional: source DIRECTIVITY — radiate more toward where the entity faces (its Transform rotation).
+emitter.directivity.dipoleWeight = 0.5;  // 0 = omni (default), 0.5 = cardioid, 1 = dipole / figure-8
+emitter.directivity.dipolePower = 1;     // sharpen the lobe (> 1 narrows it)
+```
+
+Each frame the `AudioEmitterSystem` solves occlusion + transmission (ray-traced against the
+`AcousticBody` geometry), the medium (blended `AcousticVolume`s), and — for a non-omni source — the
+radiation **directivity** (the angle between where the source faces and the listener) for every live
+acoustic 3D instance, and pushes the result to `EventInstance.setAcoustic`, which drives an occlusion gain
+(scaled by directivity) + lowpass + transmission filter inserted in that instance's chain. All
+off-by-default: a non-acoustic event renders exactly as before, and an omni source pays nothing for
+directivity.
+
+### 3. Bake + wire reverb (offline once, render at runtime)
+
+```js
+import { bakeProbeField } from "./probe/bakeProbeField.js";
+import { ProbeReverbRenderer } from "./render/ProbeReverbRenderer.js";
+import { seededRandom } from "../../../core/math/random/seededRandom.js";
+
+// OFFLINE: place probes over the scene (the bake region is derived from the occluder hull) and bake each
+// probe's per-band RT60. minSpacing is the density knob (smaller = denser).
+const probes = bakeProbeField(sim.occluderIndex, /*minSpacing*/ 8, /*rayCount*/ 256, seededRandom(1));
+const json = probes.toJSON();   // serialize, ship as an asset
+
+// RUNTIME: an acoustic-owned reverb bus driven by the listener's nearest probe
+const reverb = new ProbeReverbRenderer(audioContext, masterDestination);
+reverb.setProbeField(probes);
+sopraBusOutput.connect(reverb.input);   // send a copy of the dry signal in
+// pass `reverb` as options.probeReverb to configureAcousticSimulation, or assign it directly:
+audioSystem.probeReverb = reverb;       // driven once per frame from the listener
+```
+
+(`sim.occluderIndex` exposes the live occluder geometry so the bake runs against the same scene the
+runtime occludes with.)
+
+For **directional** reverb, drop in `FoaProbeReverbRenderer` instead — same bake, same wiring, but it
+renders the probe's per-band **arrival direction** (baked alongside the RT60) as a first-order ambisonic
+(B-format) field decoded to stereo, and steered by the listener's orientation so the reverb leans toward
+the open door / off the near wall and stays world-anchored as the head turns. It is driven the same way;
+`AudioEmitterSystem` passes the listener rotation to `update()` (the scalar renderer ignores it):
+
+```js
+import { FoaProbeReverbRenderer } from "./render/FoaProbeReverbRenderer.js";
+
+const reverb = new FoaProbeReverbRenderer(audioContext, masterDestination);
+reverb.setProbeField(probes);           // the SAME baked field — directions ride along
+sopraBusOutput.connect(reverb.input);
+audioSystem.probeReverb = reverb;        // driven from the listener pose (position + orientation)
+```
+
+The stereo decode is isolated so a binaural/HRTF (SOFA) decoder can replace it later without touching the
+encode/rotate path.
+
+### 4. Pathing (corner-leakage), optional
+
+```js
+import { bakeVisibility } from "./probe/bakeVisibility.js";
+
+bakeVisibility(probes, sim.occluderIndex); // bake the inter-probe visibility graph into the field
+sim.setProbeField(probes);                 // the field whose visibility graph pathing routes through
+sim.pathing = true;                        // engine-wide toggle (off by default)
+
+sim.pathingRecheck = true;                 // optional: re-verify traversed edges against LIVE geometry
+sim.recheckBudget = 8;                     //   (a closing door re-blocks the leak; budgeted, off by default)
+```
+
+The leak send carries the same acoustics as the direct path, but along the *routed* polyline: it is scaled
+by the source's **directivity toward the corner it leaks through** (not the blocked listener) and darkened by
+**air absorption over the longer leaked distance**. With `pathingRecheck`, the edges leaks traverse are
+re-tested each tick (within `recheckBudget`); an edge a mover has since blocked is disabled by weight
+(`EDGE_WEIGHT_BLOCKED`, no topology change) and restored when it re-opens — the cheap real-time half of the
+real-time-direct / baked-indirect split.
+
+---
+
+## The simulation, in one paragraph each
+
+**Occlusion + transmission.** For each live source, `OcclusionSolver` shoots `rayCount` rays from the
+listener toward points spread over the source's sphere (Fibonacci distribution, randomly re-oriented per
+tick). The fraction blocked is the occlusion; the blocked rays' material `transmission` (3 bands) is what
+leaks through. The result is folded into a temporal EMA, so a low ray count integrates over frames and
+the output never flickers. Rendered as a broadband gain (occluded → quieter, floored by transmission)
+plus a lowpass (occluded → muffled).
+
+**Medium / air absorption.** `AcousticVolume` regions carry an `AcousticMedium` whose `airAbsorption` is in
+**dB per metre**, per band. `VolumeField.integrateAbsorption` line-integrates it along the source→listener
+path (`∫ α ds`, blending regions + ambient air at each step) into `AcousticSolution.airLoss` — the per-band
+total dB lost over the path. So highs, which absorb faster, die over distance while the low end carries
+(distance-dependent atmospheric absorption); a thicker painted region adds extra loss where the path crosses
+it. Open air uses a small default atmosphere (tunable via the simulator's `defaultMedium`).
+
+It is rendered as a **low-anchored spectral tilt**: only the high‑vs‑low *excess* loss
+(`airLoss[high] − airLoss[low]`) drops the lowpass cutoff, so a uniform loss — which the authored distance
+**attenuation curve** already owns as broadband loudness — causes no darkening. The air filter is a separate
+series node from the attenuation gain, so the two compose (multiply) rather than fight: the curve owns *how
+loud*, air absorption owns *how bright*.
+
+**Reverb.** Offline, `bakeProbeField` bakes each probe's **per-band** reverberation. For a probe,
+`acoustic_trace_energy` shoots rays that bounce multiply through the scene ("source at the listener"),
+depositing per-band energy into a time-binned echogram; `echogram_band_rt60` reduces each band's decay to
+an RT60 (Schroeder backward integration + the ISO-3382 T30 slope). The bake is validated against the
+analytic **Sabine** reverberation time of a closed box. At runtime the listener's nearest probe sets the
+per-band RT60, which `reverbImpulseResponse` turns into a band-split decaying-noise convolution IR (so a
+bright room's tail rings longer in the highs), crossfaded by `ProbeReverbRenderer` as you cross probe
+cells.
+
+**Pathing (corner-leakage).** Offline, `bakeVisibility` connects probes with mutual line-of-sight into
+the `AcousticProbeField`'s visibility graph (a `CSRGraph` adjacency — connectivity is an inherent property of the
+field). At runtime, when the engine-wide `AcousticSimulator.pathing` toggle is on, one single-source
+Dijkstra from the listener (`ProbeFieldPathingSolution.computeExitField`, a per-frame solver the simulator
+owns) gives every probe its **exit point** — the probe adjacent to the listener on its
+path. Each occluded source then routes a second, exit-spatialized send, so a sound blocked by a wall is
+heard coming from the *doorway it leaks through*, not through the wall. Engine-wide toggle, **off by
+default (zero cost when off)** — no per-source flag.
+
+---
+
+## Performance
+
+Per-frame cost is bounded by the **live voice budget** (≤ 64), not the world size — the sim only touches
+promoted instances. Each source costs `rayCount` rays; a top-level BVH (TLAS) over the occluder bodies
+means a ray pays only for the few occluders near it, not every registered body. Tune `rayCount` down +
+lean on the temporal smoothing to amortize. The reverb/visibility bakes are offline (no frame budget).
+See `bench/occlusion.bench.spec.js` (remove `.skip` on the sweep to read µs/ray for your scene).
+
+---
+
+## Testing
+
+Everything except `render/` is WebAudio-free, so tests use real geometry and real ECS components — no
+audio mock. The render seam + reverb renderer use sopra's `MockAudioContext`.
+
+```
+npx jest --config jest.conf.json engine/sound/simulation     # from the repo root H:/git/moh
+```
+
+---
+
+## Status
+
+**Built + tested:** the whole simulation engine (P0–P6) + the **ray-traced per-band reflection-IR reverb**
+(the keystone: multi-bounce energy trace → per-band RT60, Sabine-validated → band-split IR render) + the
+occlusion / transmission / medium render seam + the corner-leakage (pathing) render. All wired into sopra
++ `AudioEmitterSystem` (one call via `configureAcousticSimulation`), additive and off-by-default.
+
+**Not yet wired (gated on the sopra strangler migration, all outside this folder):** production
+registration in `makeMirEngineConfig` (the legacy `SoundEmitter` path is still the live one) + save/load
+**binary serialization adapters** for `AcousticBody`/`AcousticVolume` — deliberately deferred to match
+`AudioEmitter`, which has none either (the components carry JSON `toJSON`/`fromJSON` for when it lands).
+
+**Optional / on-demand (not v1):** NEE-to-source early reflections, pathing live-recheck + door variants,
+FOA ambisonics, SOFA HRTF, source directivity.
+
+See [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md) and [REFLECTION_IR_PLAN.md](./REFLECTION_IR_PLAN.md)
+for the full phase-by-phase record and decisions.