@woosh/meep-engine 2.163.11 → 2.165.0

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

@@ -0,0 +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).

package/src/engine/sound/simulation/configureAcousticSimulation.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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: EngineConfiguration, audioEmitterSystem: AudioEmitterSystem, simulator?: AcousticSimulator, probeReverb?: ProbeReverbRenderer): AcousticSimulator;
+import { AcousticSimulator } from "./AcousticSimulator.js";
+//# sourceMappingURL=configureAcousticSimulation.d.ts.map

package/src/engine/sound/simulation/configureAcousticSimulation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configureAcousticSimulation.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/simulation/configureAcousticSimulation.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,oIAJW,iBAAiB,sCAEf,iBAAiB,CAgB7B;kCA/CiC,wBAAwB"}

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

@@ -0,0 +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;
+}

package/src/engine/sound/simulation/core/AcousticMedium.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 {
+    /**
+     * @param {number[]|Float32Array} [airAbsorption]
+     * @returns {AcousticMedium}
+     */
+    static from(airAbsorption?: number[] | Float32Array): AcousticMedium;
+    /**
+     * Air absorption per band (low/mid/high), in dB per metre. 0 = transparent.
+     * @type {Float32Array}
+     */
+    airAbsorption: Float32Array;
+    /**
+     * Zero all properties — the accumulator state used by {@link VolumeField} blending.
+     */
+    setZero(): void;
+    /**
+     * @param {AcousticMedium} other
+     */
+    copy(other: AcousticMedium): void;
+    /**
+     * Accumulate `other` scaled by `weight` into this (blending).
+     * @param {AcousticMedium} other
+     * @param {number} weight
+     */
+    addScaled(other: AcousticMedium, weight: number): void;
+    /**
+     * @param {number} s
+     */
+    scale(s: number): void;
+    /**
+     * @param {AcousticMedium} other
+     * @returns {boolean}
+     */
+    equals(other: AcousticMedium): boolean;
+    hash(): number;
+    /**
+     * @returns {AcousticMedium}
+     */
+    clone(): AcousticMedium;
+    toJSON(): {
+        airAbsorption: number[];
+    };
+    /**
+     * @param {{airAbsorption:number[]}} json
+     */
+    fromJSON({ airAbsorption }: {
+        airAbsorption: number[];
+    }): void;
+}
+export namespace AcousticMedium {
+    let typeName: string;
+}
+//# sourceMappingURL=AcousticMedium.d.ts.map

package/src/engine/sound/simulation/core/AcousticMedium.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcousticMedium.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/core/AcousticMedium.js"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH;IAOI;;;OAGG;IACH,4BAHW,MAAM,EAAE,GAAC,YAAY,GACnB,cAAc,CAY1B;IApBD;;;OAGG;IACH,eAFU,YAAY,CAEsB;IAkB5C;;OAEG;IACH,gBAIC;IAED;;OAEG;IACH,YAFW,cAAc,QAMxB;IAED;;;;OAIG;IACH,iBAHW,cAAc,UACd,MAAM,QAMhB;IAED;;OAEG;IACH,SAFW,MAAM,QAMhB;IAED;;;OAGG;IACH,cAHW,cAAc,GACZ,OAAO,CAMnB;IAED,eAMC;IAED;;OAEG;IACH,SAFa,cAAc,CAI1B;IAED;;MAIC;IAED;;OAEG;IACH,4BAFW;QAAC,aAAa,EAAC,MAAM,EAAE,CAAA;KAAC,QAMlC;CACJ"}

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

@@ -0,0 +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";

package/src/engine/sound/simulation/core/AcousticMediumSerializationAdapter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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<any> {
+    constructor();
+    klass: typeof AcousticMedium;
+    version: number;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {AcousticMedium} value
+     */
+    serialize(buffer: BinaryBuffer, value: AcousticMedium): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {AcousticMedium} value mutated in place
+     */
+    deserialize(buffer: BinaryBuffer, value: AcousticMedium): void;
+}
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { AcousticMedium } from "./AcousticMedium.js";
+//# sourceMappingURL=AcousticMediumSerializationAdapter.d.ts.map

package/src/engine/sound/simulation/core/AcousticMediumSerializationAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcousticMediumSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/core/AcousticMediumSerializationAdapter.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH;;IACI,6BAAuB;IACvB,gBAAY;IAEZ;;;OAGG;IACH,uCAFW,cAAc,QAIxB;IAED;;;OAGG;IACH,yCAFW,cAAc,QAIxB;CACJ;gDA1B+C,gEAAgE;+BACjF,qBAAqB"}

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

@@ -0,0 +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);
+    }
+}

package/src/engine/sound/simulation/core/AcousticOccluderIndex.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Dynamic spatial index of acoustic occluders, providing closest-hit / any-hit ray queries for the
+ * occlusion / transmission simulation. NOT a user-facing "scene" — it is an internal acceleration
+ * structure populated from `AcousticBody` components by the `AcousticSimulationSystem`.
+ *
+ * Each occluder is an {@link OccluderBody}: an {@link AbstractShape3D} + world transform. The shape is
+ * raycast EXACTLY in its own local frame — closed-form for sphere/box/capsule, an internal BLAS for
+ * meshes (`AbstractShape3D.raycast`) — so primitives need no triangulation.
+ *
+ * A top-level {@link BVH} over the bodies' world AABBs (leaf user-data = handle) makes a query
+ * O(log n + hits): the ray segment descends the tree, visiting only the bodies whose bounds it crosses,
+ * instead of scanning every registered occluder. The BVH is fully dynamic — adding, moving
+ * ({@link setTransform}, O(log n) leaf refit) and removing a body all update it in place. For each
+ * candidate the ray is localised into the body's frame, `shape.raycast` run, and the hit point + normal
+ * mapped back to world.
+ *
+ * WebAudio-agnostic and ECS-agnostic. PRECONDITION: body transforms are rigid (no scale).
+ */
+export class AcousticOccluderIndex {
+    /**
+     * Add an occluder shape, placed by `matrix` (identity = at the world origin).
+     * @param {AbstractShape3D} shape geometry in its canonical local frame
+     * @param {AcousticMaterial} material acoustic properties of the surface
+     * @param {Float32Array|number[]} [matrix] world transform (rigid)
+     * @returns {number} a stable handle
+     */
+    addBody(shape: AbstractShape3D, material: AcousticMaterial, matrix?: Float32Array | number[]): number;
+    /**
+     * Re-place a body's world transform — refits its BVH leaf in place (O(log n), no rebuild).
+     * @param {number} handle
+     * @param {Float32Array|number[]} matrix world transform (rigid)
+     */
+    setTransform(handle: number, matrix: Float32Array | number[]): void;
+    /**
+     * Remove a body. Its leaf is unlinked from the BVH and its handle retired (queries skip it).
+     * @param {number} handle
+     */
+    removeBody(handle: number): void;
+    /**
+     * Nearest occluder hit by `ray` within `ray.tMax`, written into `out` (world hit point + normal +
+     * distance + material). Returns whether anything hit.
+     * @param {Ray3} ray world-space ray (tMax bounds the search)
+     * @param {RayHit} out result container (reset by this call)
+     * @returns {boolean}
+     */
+    closestHit(ray: Ray3, out: RayHit): boolean;
+    /**
+     * Whether `ray` is blocked by ANY occluder within `ray.tMax`. Cheaper than {@link closestHit} —
+     * early-outs on the first body hit, no result detail.
+     * @param {Ray3} ray
+     * @returns {boolean}
+     */
+    anyHit(ray: Ray3): boolean;
+    /**
+     * Signed distance from a world point to the nearest occluder surface: NEGATIVE inside solid, POSITIVE in
+     * open air, magnitude = distance to the nearest surface. This is the union SDF — `min` over bodies of
+     * each shape's own signed distance (a point inside ANY occluder is inside the union → negative).
+     *
+     * Bounded by `maxDistance`: only bodies whose world AABB lies within that radius are considered (the BVH
+     * sphere query — the AABB bounds the shape, so this never misses a surface within range), so the result
+     * is EXACT when the nearest surface is ≤ `maxDistance` and CLAMPED to `+maxDistance` when nothing is
+     * nearer. Inside-ness is always detected (a containing body's AABB contains the point) and its depth is
+     * returned unclamped. O(log n + nearby bodies); allocation-free. The index is otherwise ray-only — this
+     * is the placement baker's clearance / air / inside query.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} [maxDistance] search-radius cap (smaller = cheaper; the value beyond which "very open"
+     *        is good enough). Default unbounded (considers every body — pass a cap for per-voxel sweeps).
+     * @returns {number} signed distance (negative = inside an occluder; `maxDistance` if nothing is nearer)
+     */
+    signedDistanceAt(x: number, y: number, z: number, maxDistance?: number): number;
+    /**
+     * Combined world AABB of all live occluders, written into `out` as `[x0,y0,z0, x1,y1,z1]`. Returns the
+     * number of bodies unioned — 0 means the index is empty and `out` is left untouched. The probe bake
+     * derives its region from this (the occluder hull + a margin), so the region need not be configured.
+     * @param {Float32Array|number[]} out length ≥ 6
+     * @returns {number} number of live bodies
+     */
+    computeWorldBounds(out: Float32Array | number[]): number;
+    #private;
+}
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+//# sourceMappingURL=AcousticOccluderIndex.d.ts.map

package/src/engine/sound/simulation/core/AcousticOccluderIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcousticOccluderIndex.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/core/AcousticOccluderIndex.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;GAiBG;AACH;IA0BI;;;;;;OAMG;IACH,qEAHW,YAAY,GAAC,MAAM,EAAE,GACnB,MAAM,CAelB;IAED;;;;OAIG;IACH,qBAHW,MAAM,UACN,YAAY,GAAC,MAAM,EAAE,QAO/B;IAgBD;;;OAGG;IACH,mBAFW,MAAM,QAMhB;IAED;;;;;;OAMG;IACH,gBAJW,IAAI,gBAEF,OAAO,CA6CnB;IAED;;;;;OAKG;IACH,YAHW,IAAI,GACF,OAAO,CAgBnB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,oBAPW,MAAM,KACN,MAAM,KACN,MAAM,gBACN,MAAM,GAEJ,MAAM,CA4BlB;IAED;;;;;;OAMG;IACH,wBAHW,YAAY,GAAC,MAAM,EAAE,GACnB,MAAM,CA6BlB;;CAmCJ;qBAlToB,sCAAsC"}