@woosh/meep-engine 3.1.0 → 3.3.0

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

@@ -1,121 +1,121 @@
-# Topologically-aware probe-visibility graph
-
-## The cliff
-
-`bakeVisibility` connects every mutually-visible probe pair via an all-pairs `for i, for j<i` loop.
-With no occluders that is the **complete graph** — `n(n-1)/2` edges, O(n²) time *and* memory. A 128³ probe
-field (2,097,152 probes) would try to materialise **2.199e12 edges** → OOM. (Bench:
-`probe/bakeVisibility.bench.spec.js`.)
-
-Pruning a distance cutoff into that loop does **not** fix it — it still *enumerates* all pairs (O(n²) time),
-and the scheme is topologically blind. The fix is to never enumerate the complete graph: generate candidate
-edges from the **spatial topology** of the probe cloud, so we only ever touch O(n) of them.
-
-This is, in the literature, a **sparse geometric spanner** built like a **sparse roadmap spanner (SPARS2)**:
-a base graph + connectivity bridges + path-quality shortcuts. References that map 1:1 onto the three stages:
-SPARS/SPARS2 (Dobson & Bekris 2014 — names stage B a *"bridge"*, stage C a *"shortcut"*); the greedy
-geometric spanner (Bose et al. — stage C's length test `dist_G(u,v) > t·‖uv‖`); PRM* component-connection
-(stage B). Steam Audio, by contrast, keeps the all-pairs loop and just places **few** probes (5 m floor grid)
-— a placement lever we deliberately treat separately.
-
-## Decisions (locked)
-
-- **Base = Delaunay, no jitter.** `compute_delaunay_tetrahedral_mesh` on the probe positions. (Grid fields
-  have a clean dedicated tessellator, `tetrahedral_mesh_build_from_grid`, but wiring it by grid-structure is
-  part of the *placement* workstream — not conflated here.)
-- **Full A + B + C** in this change.
-- **Dense probe fields stay.** This is purely a graph-construction fix; placement is a separate workstream.
-- Caveat we are buying with B+C: **3D Delaunay is not a proven constant-stretch spanner** (2D is, ≤1.998;
-  3D has no such bound — Erickson, Xia). So the base graph *can* detour badly and *can* be fragmented by
-  walls; B repairs connectivity and C repairs path quality. They are mandatory, not optional.
-
-## Stage A — Delaunay base graph  (`probe_delaunay_edges.js`)
-
-1. Copy probe positions into a packed `[x,y,z]*n`; `compute_delaunay_tetrahedral_mesh(mesh, points, n)`.
-2. Extract the **unique undirected edges** of the live tets — 6 per tet (`getVertexIndex` pairs), deduped
-   (materialise the freed-tet skip set once; do **not** call `exists()` per tet — it is O(free)). The tet
-   mesh triangulates the convex hull, so this is a single connected graph of **≈6–7·n** edges.
-3. Drop edges that fail `probe_edge_visible(field, index, a, b)`; keep survivors weighted by distance.
-
-Result: a sparse, occlusion-respecting base graph. **O(n)** edges, **O(n)** shadow rays. (2.1M probes →
-~13M edges / rays vs 2.2e12 — ~150,000× fewer.) Dropping occluded edges is what fragments the graph into
-**islands** (rooms), which stage B repairs.
-
-## Stage B — bridge the islands  (`probe_visibility_bridge_components.js`)
-
-A door the Delaunay edge happened to miss leaves two acoustically-connected rooms as separate components.
-
-1. `uf_init` + `uf_union` over the surviving base edges → connected components (canonical root = min member).
-2. For each probe, **radius-query the probe BVH** (`bvh_query_user_data_intersects_sphere`, radius = k× the
-   median base-edge length) for nearby probes in a **different** component; among the **visible** ones keep
-   the **shortest** edge per unordered component-pair (the PRM/SPARS bridge heuristic).
-3. Add those bridges, re-`uf_union`, repeat until the component count stops dropping. Genuinely sealed
-   regions stay separate (correct — a closed vault should not leak).
-
-**O(n · |radius neighbours|)**, no all-pairs. Bridges are the only edges that can exceed the local Delaunay
-length, so they are also the place corner-leak pathing will most want.
-
-## Stage C — augment for path quality  (`probe_visibility_augment.js`)
-
-The Delaunay base routes only through local hops, so a graph path can detour or kink where a clear straight
-line exists. Add a **budgeted fraction** of extra edges (cap ≤ ~30% of base) on two criteria:
-
-- **C1 length (greedy spanner).** Candidate chords `(u,v)` from the 2-ring (a shared base neighbour `w`) and
-  short BVH-radius pairs. Add iff `(u,v)` is visible **and** `dist_G(u,v) > t·‖uv‖` — the current graph route
-  is ≥ t× the straight line. `dist_G` is evaluated with a **distance-bounded Dijkstra capped at `t·‖uv‖`**
-  (reuse the heap Dijkstra; stop early once the cap is exceeded), so it is cheap, not a full SSSP per pair.
-- **C2 directionality (diffraction-angle gate).** For a 2-ring kink `u–w–v`, with `d0 = ̂(u−w)`, `d1 = ̂(v−w)`,
-  add the chord iff visible **and** `dot(d0, −d1) < X` — the angle at `w` is acute, a sharp corner the sound
-  must wrap around. Acoustically a bend is a diffraction point whose HF loss grows with angle (UTD/Maekawa),
-  so straightening it is worth an edge even when it barely shortens the route. This is an acoustic heuristic,
-  **not** a spanner property — hence the budget cap, so it composes with C1 rather than overrunning it.
-
-**O(n · degree²)** candidates from the 2-ring; each gated test is local/bounded. Process shortest-first,
-stop at the budget.
-
-## Assembly — `bakeVisibility` rewrite
-
-`A (delaunay edges → visible) → B (bridge) → C (augment) → CSRGraph (both half-edges) → field.setVisibilityGraph`.
-The CSR build, the `EDGE_WEIGHT_BLOCKED` runtime recheck, and `findAcousticPath` are unchanged downstream —
-this only changes which edges exist, not their representation. Weights remain inter-probe distance so the
-recheck restores them identically.
-
-## New primitives that may be needed
-
-- Tet → unique-edge extraction with an O(tets) freed-skip (helper in `probe_delaunay_edges.js`).
-- A median base-edge-length helper to set the stage-B radius and the stage-C candidate radius.
-- (If 2-ring proves insufficient at scale) WSPD candidate pairs — deferred unless measured to be needed.
-
-## Test plan
-
-- `probe_delaunay_edges.spec.js`: a small grid tetrahedralises to the expected adjacency; coincident/degenerate
-  inputs; edge uniqueness.
-- `bakeVisibility.spec.js` (extend): empty scene is now **sparse** (≈O(n), assert ≪ n²) yet still **connected**
-  (one component) and every kept edge is visible; a wall fragments then B re-bridges through a gap; the
-  existing two-rooms-corridor integration test still passes (reachability + direction + per-band).
-- Re-point `bakeVisibility.bench.spec.js`: the complete-graph assertion becomes a **sparsity + connectivity**
-  assertion; the 128³ case should now *complete* (sweep added to confirm ~linear edges/time).
-- Stage C: a deliberate kink (L-shaped corridor with a clear diagonal) gains the shortcut; budget cap honoured.
-
-## Open knobs (defaults to pick during implementation, document in code)
-
-- stage-B radius multiplier `k` (× median edge length); stage-C stretch `t`; stage-C angle `X`; stage-C budget
-  fraction. All bake-time constants with JSDoc rationale (per the project's no-magic / uniform-flow style).
-
-## As-built notes (landed)
-
-- **Defaults chosen:** stage-B radius `2.5×` median edge length; stage-C stretch `1.3`, kink `dot < −0.5`
-  (~corners <60°), budget `0.2×` base edges.
-- **Coplanar degeneracy is handled, not avoided:** a valid 3D Delaunay 1-skeleton is connected, so
-  `probe_delaunay_edges` checks connectivity and falls back to the complete graph when the extraction is
-  disconnected (a near-coplanar/degenerate field — e.g. the y=0 test scenes). Dense 3D fields never hit it.
-- **Stage B is boundary-driven:** it searches only from the endpoints of dropped (occluded) edges (`sources`),
-  not all `n` probes — an interior probe with all-visible neighbours can't be a missed-door near side. An
-  empty scene drops nothing, so stage B is a no-op (measured: 10 s → 20 ms at 13.8k probes).
-- **Spatial sort:** `probe_delaunay_edges` Morton-sorts the points before the incremental tetrahedralisation
-  (the core's own TODO) and maps tet vertices back through the permutation. ~25% off the build.
-- **Result:** edges are O(n) (measured 6.7–8.0 per probe across 8³–32³, always 1 component); the old all-pairs
-  O(n²)/OOM is gone. The 128³ case no longer OOMs and completes.
-- **Remaining bottleneck = the core incremental Delaunay BUILD** (~98% of bake time, super-linear). Follow-ups
-  (out of scope here): wire `tetrahedral_mesh_build_from_grid` for grid fields (O(n) — the placement
-  workstream), and/or speed up core's Delaunay (BRIO/spatial-sort insertion is its standing TODO).
+# Topologically-aware probe-visibility graph
+
+## The cliff
+
+`bakeVisibility` connects every mutually-visible probe pair via an all-pairs `for i, for j<i` loop.
+With no occluders that is the **complete graph** — `n(n-1)/2` edges, O(n²) time *and* memory. A 128³ probe
+field (2,097,152 probes) would try to materialise **2.199e12 edges** → OOM. (Bench:
+`probe/bakeVisibility.bench.spec.js`.)
+
+Pruning a distance cutoff into that loop does **not** fix it — it still *enumerates* all pairs (O(n²) time),
+and the scheme is topologically blind. The fix is to never enumerate the complete graph: generate candidate
+edges from the **spatial topology** of the probe cloud, so we only ever touch O(n) of them.
+
+This is, in the literature, a **sparse geometric spanner** built like a **sparse roadmap spanner (SPARS2)**:
+a base graph + connectivity bridges + path-quality shortcuts. References that map 1:1 onto the three stages:
+SPARS/SPARS2 (Dobson & Bekris 2014 — names stage B a *"bridge"*, stage C a *"shortcut"*); the greedy
+geometric spanner (Bose et al. — stage C's length test `dist_G(u,v) > t·‖uv‖`); PRM* component-connection
+(stage B). Steam Audio, by contrast, keeps the all-pairs loop and just places **few** probes (5 m floor grid)
+— a placement lever we deliberately treat separately.
+
+## Decisions (locked)
+
+- **Base = Delaunay, no jitter.** `compute_delaunay_tetrahedral_mesh` on the probe positions. (Grid fields
+  have a clean dedicated tessellator, `tetrahedral_mesh_build_from_grid`, but wiring it by grid-structure is
+  part of the *placement* workstream — not conflated here.)
+- **Full A + B + C** in this change.
+- **Dense probe fields stay.** This is purely a graph-construction fix; placement is a separate workstream.
+- Caveat we are buying with B+C: **3D Delaunay is not a proven constant-stretch spanner** (2D is, ≤1.998;
+  3D has no such bound — Erickson, Xia). So the base graph *can* detour badly and *can* be fragmented by
+  walls; B repairs connectivity and C repairs path quality. They are mandatory, not optional.
+
+## Stage A — Delaunay base graph  (`probe_delaunay_edges.js`)
+
+1. Copy probe positions into a packed `[x,y,z]*n`; `compute_delaunay_tetrahedral_mesh(mesh, points, n)`.
+2. Extract the **unique undirected edges** of the live tets — 6 per tet (`getVertexIndex` pairs), deduped
+   (materialise the freed-tet skip set once; do **not** call `exists()` per tet — it is O(free)). The tet
+   mesh triangulates the convex hull, so this is a single connected graph of **≈6–7·n** edges.
+3. Drop edges that fail `probe_edge_visible(field, index, a, b)`; keep survivors weighted by distance.
+
+Result: a sparse, occlusion-respecting base graph. **O(n)** edges, **O(n)** shadow rays. (2.1M probes →
+~13M edges / rays vs 2.2e12 — ~150,000× fewer.) Dropping occluded edges is what fragments the graph into
+**islands** (rooms), which stage B repairs.
+
+## Stage B — bridge the islands  (`probe_visibility_bridge_components.js`)
+
+A door the Delaunay edge happened to miss leaves two acoustically-connected rooms as separate components.
+
+1. `uf_init` + `uf_union` over the surviving base edges → connected components (canonical root = min member).
+2. For each probe, **radius-query the probe BVH** (`bvh_query_user_data_intersects_sphere`, radius = k× the
+   median base-edge length) for nearby probes in a **different** component; among the **visible** ones keep
+   the **shortest** edge per unordered component-pair (the PRM/SPARS bridge heuristic).
+3. Add those bridges, re-`uf_union`, repeat until the component count stops dropping. Genuinely sealed
+   regions stay separate (correct — a closed vault should not leak).
+
+**O(n · |radius neighbours|)**, no all-pairs. Bridges are the only edges that can exceed the local Delaunay
+length, so they are also the place corner-leak pathing will most want.
+
+## Stage C — augment for path quality  (`probe_visibility_augment.js`)
+
+The Delaunay base routes only through local hops, so a graph path can detour or kink where a clear straight
+line exists. Add a **budgeted fraction** of extra edges (cap ≤ ~30% of base) on two criteria:
+
+- **C1 length (greedy spanner).** Candidate chords `(u,v)` from the 2-ring (a shared base neighbour `w`) and
+  short BVH-radius pairs. Add iff `(u,v)` is visible **and** `dist_G(u,v) > t·‖uv‖` — the current graph route
+  is ≥ t× the straight line. `dist_G` is evaluated with a **distance-bounded Dijkstra capped at `t·‖uv‖`**
+  (reuse the heap Dijkstra; stop early once the cap is exceeded), so it is cheap, not a full SSSP per pair.
+- **C2 directionality (diffraction-angle gate).** For a 2-ring kink `u–w–v`, with `d0 = ̂(u−w)`, `d1 = ̂(v−w)`,
+  add the chord iff visible **and** `dot(d0, −d1) < X` — the angle at `w` is acute, a sharp corner the sound
+  must wrap around. Acoustically a bend is a diffraction point whose HF loss grows with angle (UTD/Maekawa),
+  so straightening it is worth an edge even when it barely shortens the route. This is an acoustic heuristic,
+  **not** a spanner property — hence the budget cap, so it composes with C1 rather than overrunning it.
+
+**O(n · degree²)** candidates from the 2-ring; each gated test is local/bounded. Process shortest-first,
+stop at the budget.
+
+## Assembly — `bakeVisibility` rewrite
+
+`A (delaunay edges → visible) → B (bridge) → C (augment) → CSRGraph (both half-edges) → field.setVisibilityGraph`.
+The CSR build, the `EDGE_WEIGHT_BLOCKED` runtime recheck, and `findAcousticPath` are unchanged downstream —
+this only changes which edges exist, not their representation. Weights remain inter-probe distance so the
+recheck restores them identically.
+
+## New primitives that may be needed
+
+- Tet → unique-edge extraction with an O(tets) freed-skip (helper in `probe_delaunay_edges.js`).
+- A median base-edge-length helper to set the stage-B radius and the stage-C candidate radius.
+- (If 2-ring proves insufficient at scale) WSPD candidate pairs — deferred unless measured to be needed.
+
+## Test plan
+
+- `probe_delaunay_edges.spec.js`: a small grid tetrahedralises to the expected adjacency; coincident/degenerate
+  inputs; edge uniqueness.
+- `bakeVisibility.spec.js` (extend): empty scene is now **sparse** (≈O(n), assert ≪ n²) yet still **connected**
+  (one component) and every kept edge is visible; a wall fragments then B re-bridges through a gap; the
+  existing two-rooms-corridor integration test still passes (reachability + direction + per-band).
+- Re-point `bakeVisibility.bench.spec.js`: the complete-graph assertion becomes a **sparsity + connectivity**
+  assertion; the 128³ case should now *complete* (sweep added to confirm ~linear edges/time).
+- Stage C: a deliberate kink (L-shaped corridor with a clear diagonal) gains the shortcut; budget cap honoured.
+
+## Open knobs (defaults to pick during implementation, document in code)
+
+- stage-B radius multiplier `k` (× median edge length); stage-C stretch `t`; stage-C angle `X`; stage-C budget
+  fraction. All bake-time constants with JSDoc rationale (per the project's no-magic / uniform-flow style).
+
+## As-built notes (landed)
+
+- **Defaults chosen:** stage-B radius `2.5×` median edge length; stage-C stretch `1.3`, kink `dot < −0.5`
+  (~corners <60°), budget `0.2×` base edges.
+- **Coplanar degeneracy is handled, not avoided:** a valid 3D Delaunay 1-skeleton is connected, so
+  `probe_delaunay_edges` checks connectivity and falls back to the complete graph when the extraction is
+  disconnected (a near-coplanar/degenerate field — e.g. the y=0 test scenes). Dense 3D fields never hit it.
+- **Stage B is boundary-driven:** it searches only from the endpoints of dropped (occluded) edges (`sources`),
+  not all `n` probes — an interior probe with all-visible neighbours can't be a missed-door near side. An
+  empty scene drops nothing, so stage B is a no-op (measured: 10 s → 20 ms at 13.8k probes).
+- **Spatial sort:** `probe_delaunay_edges` Morton-sorts the points before the incremental tetrahedralisation
+  (the core's own TODO) and maps tet vertices back through the permutation. ~25% off the build.
+- **Result:** edges are O(n) (measured 6.7–8.0 per probe across 8³–32³, always 1 component); the old all-pairs
+  O(n²)/OOM is gone. The 128³ case no longer OOMs and completes.
+- **Remaining bottleneck = the core incremental Delaunay BUILD** (~98% of bake time, super-linear). Follow-ups
+  (out of scope here): wire `tetrahedral_mesh_build_from_grid` for grid fields (O(n) — the placement
+  workstream), and/or speed up core's Delaunay (BRIO/spatial-sort insertion is its standing TODO).

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

@@ -1,48 +1,48 @@
-import { AcousticSimulator } from "./AcousticSimulator.js";
-import { AcousticProbeFieldSystem } from "./ecs/AcousticProbeFieldSystem.js";
-import { AcousticSimulationSystem } from "./ecs/AcousticSimulationSystem.js";
-import { AcousticVolumeSystem } from "./ecs/AcousticVolumeSystem.js";
-
-/**
- * Wire the geometry-driven acoustic simulation into an {@link EngineConfiguration}.
- *
- * Builds (or reuses) the one shared {@link AcousticSimulator} and registers the ECS systems that feed it:
- *  - {@link AcousticSimulationSystem} — turns `AcousticBody` + `Collider` + `Transform` entities into the
- *    occluder index (reactive: link/unlink/move);
- *  - {@link AcousticVolumeSystem} — turns `AcousticVolume` + `Transform` entities into medium regions;
- *  - {@link AcousticProbeFieldSystem} — wires the baked `AcousticProbeField` (single field, v1) into the
- *    simulator for pathing + probe reverb.
- *
- * It then injects the simulator into the {@link AudioEmitterSystem}, whose per-frame `update()` drives
- * `simulator.apply(...)` over the bounded live-voice set. A source participates only when its
- * `AudioEmitter.acoustic` flag is set, so wiring this costs nothing for non-acoustic emitters.
- *
- * Returns the simulator so the caller can tune it (`rayCount`, `smoothing`, `random_seed`, `medium`), bake
- * against its `occluderIndex` (reverb / visibility), and enable corner-leakage (`pathing` + `setProbeField`).
- * For probe-baked reverb, pass a configured {@link ProbeReverbRenderer} as `options.probeReverb` (or assign
- * `audioEmitterSystem.probeReverb` yourself afterwards).
- *
- * Call once during engine configuration, after the `AudioEmitterSystem` is constructed (construct it
- * without an `acousticSim` argument — this injects it).
- *
- * @param {EngineConfiguration} configuration the config the acoustic systems are added to
- * @param {AudioEmitterSystem} audioEmitterSystem the system whose `update()` drives the simulation
- * @param {AcousticSimulator} [simulator] reuse this simulator instead of creating one (default: a fresh one)
- * @param {ProbeReverbRenderer} [probeReverb] optional probe-reverb renderer to wire (left untouched if omitted)
- * @returns {AcousticSimulator} the shared simulator (tune `random_seed` / `medium` on it directly)
- */
-export function configureAcousticSimulation(configuration, audioEmitterSystem, simulator = new AcousticSimulator(), probeReverb) {
-    configuration.addManySystems(
-        new AcousticSimulationSystem(simulator),
-        new AcousticVolumeSystem(simulator),
-        new AcousticProbeFieldSystem(simulator)
-    );
-
-    audioEmitterSystem.acousticSim = simulator;
-
-    if (probeReverb !== undefined) {
-        audioEmitterSystem.probeReverb = probeReverb;
-    }
-
-    return simulator;
-}
+import { AcousticSimulator } from "./AcousticSimulator.js";
+import { AcousticProbeFieldSystem } from "./ecs/AcousticProbeFieldSystem.js";
+import { AcousticSimulationSystem } from "./ecs/AcousticSimulationSystem.js";
+import { AcousticVolumeSystem } from "./ecs/AcousticVolumeSystem.js";
+
+/**
+ * Wire the geometry-driven acoustic simulation into an {@link EngineConfiguration}.
+ *
+ * Builds (or reuses) the one shared {@link AcousticSimulator} and registers the ECS systems that feed it:
+ *  - {@link AcousticSimulationSystem} — turns `AcousticBody` + `Collider` + `Transform` entities into the
+ *    occluder index (reactive: link/unlink/move);
+ *  - {@link AcousticVolumeSystem} — turns `AcousticVolume` + `Transform` entities into medium regions;
+ *  - {@link AcousticProbeFieldSystem} — wires the baked `AcousticProbeField` (single field, v1) into the
+ *    simulator for pathing + probe reverb.
+ *
+ * It then injects the simulator into the {@link AudioEmitterSystem}, whose per-frame `update()` drives
+ * `simulator.apply(...)` over the bounded live-voice set. A source participates only when its
+ * `AudioEmitter.acoustic` flag is set, so wiring this costs nothing for non-acoustic emitters.
+ *
+ * Returns the simulator so the caller can tune it (`rayCount`, `smoothing`, `random_seed`, `medium`), bake
+ * against its `occluderIndex` (reverb / visibility), and enable corner-leakage (`pathing` + `setProbeField`).
+ * For probe-baked reverb, pass a configured {@link ProbeReverbRenderer} as `options.probeReverb` (or assign
+ * `audioEmitterSystem.probeReverb` yourself afterwards).
+ *
+ * Call once during engine configuration, after the `AudioEmitterSystem` is constructed (construct it
+ * without an `acousticSim` argument — this injects it).
+ *
+ * @param {EngineConfiguration} configuration the config the acoustic systems are added to
+ * @param {AudioEmitterSystem} audioEmitterSystem the system whose `update()` drives the simulation
+ * @param {AcousticSimulator} [simulator] reuse this simulator instead of creating one (default: a fresh one)
+ * @param {ProbeReverbRenderer} [probeReverb] optional probe-reverb renderer to wire (left untouched if omitted)
+ * @returns {AcousticSimulator} the shared simulator (tune `random_seed` / `medium` on it directly)
+ */
+export function configureAcousticSimulation(configuration, audioEmitterSystem, simulator = new AcousticSimulator(), probeReverb) {
+    configuration.addManySystems(
+        new AcousticSimulationSystem(simulator),
+        new AcousticVolumeSystem(simulator),
+        new AcousticProbeFieldSystem(simulator)
+    );
+
+    audioEmitterSystem.acousticSim = simulator;
+
+    if (probeReverb !== undefined) {
+        audioEmitterSystem.probeReverb = probeReverb;
+    }
+
+    return simulator;
+}

package/src/engine/sound/simulation/core/AcousticMedium.js

@@ -1,113 +1,113 @@
-import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
-import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
-
-/**
- * Properties of the propagation MEDIUM at a point in space (air, fog, water, …). A pure value class,
- * carried by an `AcousticVolume` region and blended across overlapping regions by the {@link VolumeField}.
- *
- * v1 models only air absorption: a per-band (low/mid/high) high-frequency decay, in decibels per metre.
- * 0 = perfectly transparent. No WebAudio, no geometry.
- */
-export class AcousticMedium {
-    /**
-     * Air absorption per band (low/mid/high), in dB per metre. 0 = transparent.
-     * @type {Float32Array}
-     */
-    airAbsorption = new Float32Array([0, 0, 0]);
-
-    /**
-     * @param {number[]|Float32Array} [airAbsorption]
-     * @returns {AcousticMedium}
-     */
-    static from(airAbsorption) {
-        const m = new AcousticMedium();
-
-        if (airAbsorption !== undefined) {
-            m.airAbsorption[0] = airAbsorption[0];
-            m.airAbsorption[1] = airAbsorption[1];
-            m.airAbsorption[2] = airAbsorption[2];
-        }
-
-        return m;
-    }
-
-    /**
-     * Zero all properties — the accumulator state used by {@link VolumeField} blending.
-     */
-    setZero() {
-        this.airAbsorption[0] = 0;
-        this.airAbsorption[1] = 0;
-        this.airAbsorption[2] = 0;
-    }
-
-    /**
-     * @param {AcousticMedium} other
-     */
-    copy(other) {
-        this.airAbsorption[0] = other.airAbsorption[0];
-        this.airAbsorption[1] = other.airAbsorption[1];
-        this.airAbsorption[2] = other.airAbsorption[2];
-    }
-
-    /**
-     * Accumulate `other` scaled by `weight` into this (blending).
-     * @param {AcousticMedium} other
-     * @param {number} weight
-     */
-    addScaled(other, weight) {
-        this.airAbsorption[0] += other.airAbsorption[0] * weight;
-        this.airAbsorption[1] += other.airAbsorption[1] * weight;
-        this.airAbsorption[2] += other.airAbsorption[2] * weight;
-    }
-
-    /**
-     * @param {number} s
-     */
-    scale(s) {
-        this.airAbsorption[0] *= s;
-        this.airAbsorption[1] *= s;
-        this.airAbsorption[2] *= s;
-    }
-
-    /**
-     * @param {AcousticMedium} other
-     * @returns {boolean}
-     */
-    equals(other) {
-        return this.airAbsorption[0] === other.airAbsorption[0]
-            && this.airAbsorption[1] === other.airAbsorption[1]
-            && this.airAbsorption[2] === other.airAbsorption[2];
-    }
-
-    hash() {
-        return combine_hash(
-            computeHashFloat(this.airAbsorption[0]),
-            computeHashFloat(this.airAbsorption[1]),
-            computeHashFloat(this.airAbsorption[2])
-        );
-    }
-
-    /**
-     * @returns {AcousticMedium}
-     */
-    clone() {
-        return AcousticMedium.from(this.airAbsorption);
-    }
-
-    toJSON() {
-        return {
-            airAbsorption: [this.airAbsorption[0], this.airAbsorption[1], this.airAbsorption[2]]
-        };
-    }
-
-    /**
-     * @param {{airAbsorption:number[]}} json
-     */
-    fromJSON({ airAbsorption }) {
-        this.airAbsorption[0] = airAbsorption[0];
-        this.airAbsorption[1] = airAbsorption[1];
-        this.airAbsorption[2] = airAbsorption[2];
-    }
-}
-
-AcousticMedium.typeName = "AcousticMedium";
+import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
+import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
+
+/**
+ * Properties of the propagation MEDIUM at a point in space (air, fog, water, …). A pure value class,
+ * carried by an `AcousticVolume` region and blended across overlapping regions by the {@link VolumeField}.
+ *
+ * v1 models only air absorption: a per-band (low/mid/high) high-frequency decay, in decibels per metre.
+ * 0 = perfectly transparent. No WebAudio, no geometry.
+ */
+export class AcousticMedium {
+    /**
+     * Air absorption per band (low/mid/high), in dB per metre. 0 = transparent.
+     * @type {Float32Array}
+     */
+    airAbsorption = new Float32Array([0, 0, 0]);
+
+    /**
+     * @param {number[]|Float32Array} [airAbsorption]
+     * @returns {AcousticMedium}
+     */
+    static from(airAbsorption) {
+        const m = new AcousticMedium();
+
+        if (airAbsorption !== undefined) {
+            m.airAbsorption[0] = airAbsorption[0];
+            m.airAbsorption[1] = airAbsorption[1];
+            m.airAbsorption[2] = airAbsorption[2];
+        }
+
+        return m;
+    }
+
+    /**
+     * Zero all properties — the accumulator state used by {@link VolumeField} blending.
+     */
+    setZero() {
+        this.airAbsorption[0] = 0;
+        this.airAbsorption[1] = 0;
+        this.airAbsorption[2] = 0;
+    }
+
+    /**
+     * @param {AcousticMedium} other
+     */
+    copy(other) {
+        this.airAbsorption[0] = other.airAbsorption[0];
+        this.airAbsorption[1] = other.airAbsorption[1];
+        this.airAbsorption[2] = other.airAbsorption[2];
+    }
+
+    /**
+     * Accumulate `other` scaled by `weight` into this (blending).
+     * @param {AcousticMedium} other
+     * @param {number} weight
+     */
+    addScaled(other, weight) {
+        this.airAbsorption[0] += other.airAbsorption[0] * weight;
+        this.airAbsorption[1] += other.airAbsorption[1] * weight;
+        this.airAbsorption[2] += other.airAbsorption[2] * weight;
+    }
+
+    /**
+     * @param {number} s
+     */
+    scale(s) {
+        this.airAbsorption[0] *= s;
+        this.airAbsorption[1] *= s;
+        this.airAbsorption[2] *= s;
+    }
+
+    /**
+     * @param {AcousticMedium} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return this.airAbsorption[0] === other.airAbsorption[0]
+            && this.airAbsorption[1] === other.airAbsorption[1]
+            && this.airAbsorption[2] === other.airAbsorption[2];
+    }
+
+    hash() {
+        return combine_hash(
+            computeHashFloat(this.airAbsorption[0]),
+            computeHashFloat(this.airAbsorption[1]),
+            computeHashFloat(this.airAbsorption[2])
+        );
+    }
+
+    /**
+     * @returns {AcousticMedium}
+     */
+    clone() {
+        return AcousticMedium.from(this.airAbsorption);
+    }
+
+    toJSON() {
+        return {
+            airAbsorption: [this.airAbsorption[0], this.airAbsorption[1], this.airAbsorption[2]]
+        };
+    }
+
+    /**
+     * @param {{airAbsorption:number[]}} json
+     */
+    fromJSON({ airAbsorption }) {
+        this.airAbsorption[0] = airAbsorption[0];
+        this.airAbsorption[1] = airAbsorption[1];
+        this.airAbsorption[2] = airAbsorption[2];
+    }
+}
+
+AcousticMedium.typeName = "AcousticMedium";

package/src/engine/sound/simulation/core/AcousticMediumSerializationAdapter.js

@@ -1,27 +1,27 @@
-import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
-import { AcousticMedium } from "./AcousticMedium.js";
-
-/**
- * Binary (de)serialization for {@link AcousticMedium}: the per-band air-absorption (dB/metre). Mirrors the
- * class's `toJSON`/`fromJSON`. Used standalone and delegated to by {@link AcousticVolumeSerializationAdapter}.
- */
-export class AcousticMediumSerializationAdapter extends BinaryClassSerializationAdapter {
-    klass = AcousticMedium;
-    version = 0;
-
-    /**
-     * @param {BinaryBuffer} buffer
-     * @param {AcousticMedium} value
-     */
-    serialize(buffer, value) {
-        buffer.writeFloat32Array(value.airAbsorption, 0, 3);
-    }
-
-    /**
-     * @param {BinaryBuffer} buffer
-     * @param {AcousticMedium} value mutated in place
-     */
-    deserialize(buffer, value) {
-        buffer.readFloat32Array(value.airAbsorption, 0, 3);
-    }
-}
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { AcousticMedium } from "./AcousticMedium.js";
+
+/**
+ * Binary (de)serialization for {@link AcousticMedium}: the per-band air-absorption (dB/metre). Mirrors the
+ * class's `toJSON`/`fromJSON`. Used standalone and delegated to by {@link AcousticVolumeSerializationAdapter}.
+ */
+export class AcousticMediumSerializationAdapter extends BinaryClassSerializationAdapter {
+    klass = AcousticMedium;
+    version = 0;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {AcousticMedium} value
+     */
+    serialize(buffer, value) {
+        buffer.writeFloat32Array(value.airAbsorption, 0, 3);
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {AcousticMedium} value mutated in place
+     */
+    deserialize(buffer, value) {
+        buffer.readFloat32Array(value.airAbsorption, 0, 3);
+    }
+}