@woosh/meep-engine 2.163.10 → 2.164.0

package/src/engine/sound/simulation/probe/ProbeFieldPathingSolution.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The per-frame pathing result over a probe-visibility graph: a single-source distance + exit field built
+ * FROM the listener's probe (via {@link csr_graph_build_distance_field}). One {@link computeExitField} pass
+ * per frame, then every source is served by direct index into the public {@link dist} / {@link next} /
+ * {@link exit} buffers.
+ *
+ * These are mutable, per-listener output buffers — they live here (reused across frames, allocation-free),
+ * not on the immutable baked field. The graph itself is NOT held: it is passed to {@link computeExitField}
+ * each call, so this object is just the sized scratch + result. Pure graph search; no WebAudio.
+ */
+export class ProbeFieldPathingSolution {
+    /**
+     * @param {number} n probe count — sizes the output buffers (the field's probe set must be final, and the
+     *        graph passed to {@link computeExitField} must have this many vertices)
+     */
+    constructor(n: number);
+    /**
+     * Shortest distance from each probe to the listener probe (`Infinity` = unreachable). Filled by
+     * {@link computeExitField}.
+     * @type {Float64Array}
+     */
+    dist: Float64Array;
+    /**
+     * Next hop from each probe toward the listener — the adjacent probe one step along its shortest path
+     * (`INVALID_NODE` = 0xFFFFFF at the listener probe / if unreachable). Walking it from a source probe
+     * enumerates the whole leaked polyline source→…→listener (each `(probe, next[probe])` pair is one traversed
+     * edge); the FIRST hop is the direction the source radiates into to begin the leak. Filled by
+     * {@link computeExitField}.
+     * @type {Uint32Array}
+     */
+    next: Uint32Array;
+    /**
+     * EXIT PROBE for each source probe — the probe adjacent to the listener on its shortest path, where the
+     * leaked sound emerges toward the listener (its apparent direction); `INVALID_NODE` (0xFFFFFF) if
+     * unreachable or already at the listener probe. Filled by {@link computeExitField}.
+     * @type {Uint32Array}
+     */
+    exit: Uint32Array;
+    /**
+     * Build the distance + exit field over `graph`, single-source FROM the listener's probe (delegates to
+     * {@link csr_graph_build_distance_field}), into {@link dist} / {@link next} / {@link exit}.
+     * PRECONDITION: `graph` has the vertex count passed to the constructor.
+     * @param {CSRGraph} graph the probe-visibility graph ({@link bakeVisibility})
+     * @param {number} listener_index probe nearest the listener
+     */
+    computeExitField(graph: CSRGraph, listener_index: number): void;
+}
+//# sourceMappingURL=ProbeFieldPathingSolution.d.ts.map

package/src/engine/sound/simulation/probe/ProbeFieldPathingSolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProbeFieldPathingSolution.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/ProbeFieldPathingSolution.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH;IA0BI;;;OAGG;IACH,eAHW,MAAM,EAShB;IAnCD;;;;OAIG;IACH,MAFU,YAAY,CAEjB;IAEL;;;;;;;OAOG;IACH,MAFU,WAAW,CAEhB;IAEL;;;;;OAKG;IACH,MAFU,WAAW,CAEhB;IAcL;;;;;;OAMG;IACH,kDAFW,MAAM,QAMhB;CACJ"}

package/src/engine/sound/simulation/probe/ProbeFieldPathingSolution.js

@@ -0,0 +1,64 @@
+import { assert } from "../../../../core/assert.js";
+import { csr_graph_build_distance_field } from "../../../../core/graph/csr/csr_graph_build_distance_field.js";
+
+/**
+ * The per-frame pathing result over a probe-visibility graph: a single-source distance + exit field built
+ * FROM the listener's probe (via {@link csr_graph_build_distance_field}). One {@link computeExitField} pass
+ * per frame, then every source is served by direct index into the public {@link dist} / {@link next} /
+ * {@link exit} buffers.
+ *
+ * These are mutable, per-listener output buffers — they live here (reused across frames, allocation-free),
+ * not on the immutable baked field. The graph itself is NOT held: it is passed to {@link computeExitField}
+ * each call, so this object is just the sized scratch + result. Pure graph search; no WebAudio.
+ */
+export class ProbeFieldPathingSolution {
+    /**
+     * Shortest distance from each probe to the listener probe (`Infinity` = unreachable). Filled by
+     * {@link computeExitField}.
+     * @type {Float64Array}
+     */
+    dist;
+
+    /**
+     * Next hop from each probe toward the listener — the adjacent probe one step along its shortest path
+     * (`INVALID_NODE` = 0xFFFFFF at the listener probe / if unreachable). Walking it from a source probe
+     * enumerates the whole leaked polyline source→…→listener (each `(probe, next[probe])` pair is one traversed
+     * edge); the FIRST hop is the direction the source radiates into to begin the leak. Filled by
+     * {@link computeExitField}.
+     * @type {Uint32Array}
+     */
+    next;
+
+    /**
+     * EXIT PROBE for each source probe — the probe adjacent to the listener on its shortest path, where the
+     * leaked sound emerges toward the listener (its apparent direction); `INVALID_NODE` (0xFFFFFF) if
+     * unreachable or already at the listener probe. Filled by {@link computeExitField}.
+     * @type {Uint32Array}
+     */
+    exit;
+
+    /**
+     * @param {number} n probe count — sizes the output buffers (the field's probe set must be final, and the
+     *        graph passed to {@link computeExitField} must have this many vertices)
+     */
+    constructor(n) {
+        assert.isNonNegativeInteger(n, 'n');
+
+        this.dist = new Float64Array(n);
+        this.next = new Uint32Array(n);
+        this.exit = new Uint32Array(n);
+    }
+
+    /**
+     * Build the distance + exit field over `graph`, single-source FROM the listener's probe (delegates to
+     * {@link csr_graph_build_distance_field}), into {@link dist} / {@link next} / {@link exit}.
+     * PRECONDITION: `graph` has the vertex count passed to the constructor.
+     * @param {CSRGraph} graph the probe-visibility graph ({@link bakeVisibility})
+     * @param {number} listener_index probe nearest the listener
+     */
+    computeExitField(graph, listener_index) {
+        assert.isNonNegativeInteger(listener_index, 'listener_index');
+
+        csr_graph_build_distance_field(this.dist, this.next, this.exit, graph, listener_index);
+    }
+}

package/src/engine/sound/simulation/probe/ProbeVisibilityRecheck.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Float32 max — a finite, in-range sentinel weight that makes a baked visibility edge **effectively
+ * untraversable** without a topology change. Dijkstra still sees the edge, but its astronomically large
+ * weight pushes any path through it past every source's audible range, so the leak silences (its falloff
+ * curve is 0 long before this). Restoring the real inter-probe distance re-opens it. `Number.MAX_VALUE`
+ * would overflow Float32 to `Infinity` when stored — this is the largest value the `edge_weights`
+ * `Float32Array` holds exactly.
+ * @type {number}
+ */
+export const EDGE_WEIGHT_BLOCKED: number;
+/**
+ * Budgeted incremental recheck of the probe-visibility graph against LIVE geometry — the cheap dynamic-geometry
+ * policy for corner-leakage. The baked graph ({@link bakeVisibility}) encodes bake-time topology, so a door
+ * that closes afterwards still has its edge; this re-verifies the edges leaks actually traverse and, when one
+ * is now blocked, sets its weight to {@link EDGE_WEIGHT_BLOCKED} (both half-edges) — disabling it without a
+ * structural change — or restores the inter-probe distance when it re-opens.
+ *
+ * Work is bounded: the simulator {@link markEdge}s the edges each leak uses, and {@link update} re-verifies up
+ * to `budget` of them per call from a FIFO dirty queue (deduped), round-robining so no edge starves. One
+ * `anyHit` ray per rechecked edge. No bake, no full O(probes²) sweep. No WebAudio.
+ */
+export class ProbeVisibilityRecheck {
+    /**
+     * @param {AcousticProbeField} field the baked probe field whose visibility graph is rechecked + mutated
+     * @param {AcousticOccluderIndex} index the live acoustic scene
+     */
+    constructor(field: AcousticProbeField, index: AcousticOccluderIndex);
+    /**
+     * Number of edges currently awaiting recheck.
+     * @returns {number}
+     */
+    get pending(): number;
+    /**
+     * Mark the edge `(a, b)` — traversed by a leak this frame — as needing a visibility recheck. Cheap: just
+     * enqueues (deduped); the ray is cast later in {@link update}. PRECONDITION: `(a, b)` is a real edge of
+     * the field's visibility graph (it came from the path walk).
+     * @param {number} a probe index
+     * @param {number} b probe index
+     */
+    markEdge(a: number, b: number): void;
+    /**
+     * Re-verify up to `budget` dirty edges (FIFO), updating each weight: a now-blocked edge →
+     * {@link EDGE_WEIGHT_BLOCKED}, a clear edge → its inter-probe distance (the baked weight). One `anyHit`
+     * ray per edge. Edges beyond the budget stay queued for the next call.
+     * @param {number} budget max edges to recheck this call
+     * @returns {number} edges actually rechecked
+     */
+    update(budget: number): number;
+    #private;
+}
+//# sourceMappingURL=ProbeVisibilityRecheck.d.ts.map

package/src/engine/sound/simulation/probe/ProbeVisibilityRecheck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProbeVisibilityRecheck.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/ProbeVisibilityRecheck.js"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,kCAFU,MAAM,CAEyC;AAEzD;;;;;;;;;;GAUG;AACH;IAuBI;;;OAGG;IACH,qEAGC;IAED;;;OAGG;IACH,sBAEC;IAaD;;;;;;OAMG;IACH,YAHW,MAAM,KACN,MAAM,QAShB;IAED;;;;;;OAMG;IACH,eAHW,MAAM,GACJ,MAAM,CAsClB;;CACJ"}

package/src/engine/sound/simulation/probe/ProbeVisibilityRecheck.js

@@ -0,0 +1,137 @@
+import { csr_graph_find_edge } from "../../../../core/graph/csr/csr_graph_find_edge.js";
+import { probe_edge_visible } from "./probe_edge_visible.js";
+
+/**
+ * Float32 max — a finite, in-range sentinel weight that makes a baked visibility edge **effectively
+ * untraversable** without a topology change. Dijkstra still sees the edge, but its astronomically large
+ * weight pushes any path through it past every source's audible range, so the leak silences (its falloff
+ * curve is 0 long before this). Restoring the real inter-probe distance re-opens it. `Number.MAX_VALUE`
+ * would overflow Float32 to `Infinity` when stored — this is the largest value the `edge_weights`
+ * `Float32Array` holds exactly.
+ * @type {number}
+ */
+export const EDGE_WEIGHT_BLOCKED = 3.4028234663852886e38;
+
+/**
+ * Budgeted incremental recheck of the probe-visibility graph against LIVE geometry — the cheap dynamic-geometry
+ * policy for corner-leakage. The baked graph ({@link bakeVisibility}) encodes bake-time topology, so a door
+ * that closes afterwards still has its edge; this re-verifies the edges leaks actually traverse and, when one
+ * is now blocked, sets its weight to {@link EDGE_WEIGHT_BLOCKED} (both half-edges) — disabling it without a
+ * structural change — or restores the inter-probe distance when it re-opens.
+ *
+ * Work is bounded: the simulator {@link markEdge}s the edges each leak uses, and {@link update} re-verifies up
+ * to `budget` of them per call from a FIFO dirty queue (deduped), round-robining so no edge starves. One
+ * `anyHit` ray per rechecked edge. No bake, no full O(probes²) sweep. No WebAudio.
+ */
+export class ProbeVisibilityRecheck {
+    /**
+     * @type {AcousticProbeField}
+     */
+    #field;
+
+    /**
+     * @type {AcousticOccluderIndex}
+     */
+    #index;
+
+    /**
+     * FIFO of dirty edges (canonical ids) awaiting recheck — drained up to `budget` per {@link update}.
+     * @type {number[]}
+     */
+    #queue = [];
+
+    /**
+     * Membership of {@link #queue} (dedup) keyed by canonical edge id.
+     * @type {Set<number>}
+     */
+    #queued = new Set();
+
+    /**
+     * @param {AcousticProbeField} field the baked probe field whose visibility graph is rechecked + mutated
+     * @param {AcousticOccluderIndex} index the live acoustic scene
+     */
+    constructor(field, index) {
+        this.#field = field;
+        this.#index = index;
+    }
+
+    /**
+     * Number of edges currently awaiting recheck.
+     * @returns {number}
+     */
+    get pending() {
+        return this.#queue.length;
+    }
+
+    /**
+     * Canonical undirected edge id (order-independent), `min·size + max`.
+     * @param {number} a
+     * @param {number} b
+     * @returns {number}
+     */
+    #edgeId(a, b) {
+        const size = this.#field.size;
+        return a < b ? a * size + b : b * size + a;
+    }
+
+    /**
+     * Mark the edge `(a, b)` — traversed by a leak this frame — as needing a visibility recheck. Cheap: just
+     * enqueues (deduped); the ray is cast later in {@link update}. PRECONDITION: `(a, b)` is a real edge of
+     * the field's visibility graph (it came from the path walk).
+     * @param {number} a probe index
+     * @param {number} b probe index
+     */
+    markEdge(a, b) {
+        const id = this.#edgeId(a, b);
+
+        if (!this.#queued.has(id)) {
+            this.#queued.add(id);
+            this.#queue.push(id);
+        }
+    }
+
+    /**
+     * Re-verify up to `budget` dirty edges (FIFO), updating each weight: a now-blocked edge →
+     * {@link EDGE_WEIGHT_BLOCKED}, a clear edge → its inter-probe distance (the baked weight). One `anyHit`
+     * ray per edge. Edges beyond the budget stay queued for the next call.
+     * @param {number} budget max edges to recheck this call
+     * @returns {number} edges actually rechecked
+     */
+    update(budget) {
+        const field = this.#field;
+        const size = field.size;
+        const graph = field.visibilityGraph;
+        const weights = graph.edge_weights;
+
+        let processed = 0;
+
+        while (processed < budget && this.#queue.length > 0) {
+            const id = this.#queue.shift();
+            this.#queued.delete(id);
+
+            const a = (id / size) | 0;
+            const b = id % size;
+
+            const ka = csr_graph_find_edge(graph, a, b);
+            const kb = csr_graph_find_edge(graph, b, a);
+
+            let weight;
+            if (probe_edge_visible(field, this.#index, a, b)) {
+                // re-open: restore the baked weight = the inter-probe distance
+                const dx = field.probeX(b) - field.probeX(a);
+                const dy = field.probeY(b) - field.probeY(a);
+                const dz = field.probeZ(b) - field.probeZ(a);
+                weight = Math.sqrt(dx * dx + dy * dy + dz * dz);
+            } else {
+                weight = EDGE_WEIGHT_BLOCKED;
+            }
+
+            weights[ka] = weight;
+            weights[kb] = weight;
+
+            processed++;
+        }
+
+        return processed;
+    }
+}

package/src/engine/sound/simulation/probe/acoustic_probe_transfer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Forward / passthrough transfer for a bend whose in·out cosine is `c` (1 = perfectly straight). 1 on the
+ * plateau, exponential decay past it. Band-independent (geometry, not material).
+ * @param {number} c ω_in·ω_out
+ * @returns {number} forward transfer in [0, 1]
+ */
+export function forward_plateau(c: number): number;
+/**
+ * Per-band transfer T(ω_in, ω_out) at a probe, written into `out[0..2]` (low/mid/high) — clamped to [0, 1].
+ * `out_b = min(1, max(forward, max over lobes of ρ_b · SG(ĥ·n; λ)))`, the dominant of the forward
+ * passthrough and the best reflection lobe (the leak picks the best mechanism; `max` keeps it ≤ 1, i.e. a
+ * probe never amplifies, and makes straight-through full regardless of nearby reflectors). Reflection lobes
+ * are weighted by the bend `(1−ω_in·ω_out)/2` so the ĥ-undefined straight region is the forward term's alone.
+ *
+ * Directions are unit PROPAGATION directions (the way the wave travels). Reciprocal:
+ * `T(ω_in,ω_out) = T(−ω_out,−ω_in)`.
+ *
+ * @param {Float32Array|number[]} out length ≥ 3 — per-band result
+ * @param {Float32Array} lobes flat lobe array (LOBE_STRIDE floats each)
+ * @param {number} lobeOffset start index of this probe's lobes in `lobes`
+ * @param {number} lobeCount number of lobes for this probe
+ * @param {number} inx @param {number} iny @param {number} inz   ω_in (unit)
+ * @param {number} outx @param {number} outy @param {number} outz ω_out (unit)
+ */
+export function acoustic_probe_transfer(out: Float32Array | number[], lobes: Float32Array, lobeOffset: number, lobeCount: number, inx: number, iny: number, inz: number, outx: number, outy: number, outz: number): void;
+export const LOBE_STRIDE: 7;
+export const FORWARD_PLATEAU_COS: 0.766;
+export const FORWARD_FALLOFF: 4;
+//# sourceMappingURL=acoustic_probe_transfer.d.ts.map

package/src/engine/sound/simulation/probe/acoustic_probe_transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acoustic_probe_transfer.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/acoustic_probe_transfer.js"],"names":[],"mappings":"AAgCA;;;;;GAKG;AACH,mCAHW,MAAM,GACJ,MAAM,CAOlB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,6CAPW,YAAY,GAAC,MAAM,EAAE,SACrB,YAAY,cACZ,MAAM,aACN,MAAM,OACN,MAAM,OAAc,MAAM,OAAc,MAAM,QAC9C,MAAM,QAAe,MAAM,QAAe,MAAM,QAsC1D;AAlFD,4BAA6B;AAU7B,wCAAyC;AACzC,gCAAiC"}

package/src/engine/sound/simulation/probe/acoustic_probe_transfer.js

@@ -0,0 +1,99 @@
+// Per-probe directional transfer T(ω_in, ω_out): the fraction of energy, per band, that — arriving at a
+// probe's neighbourhood travelling propagation direction ω_in — leaves travelling ω_out. It is a property
+// of the MEDIUM around the probe (source/listener-agnostic), composed of:
+//   • a FORWARD / passthrough term — straight-through energy (ω_out ≈ ω_in), always present (free air);
+//   • zero or more REFLECTOR LOBES — each a spherical Gaussian on the HALF-VECTOR ĥ = normalize(ω_out − ω_in)
+//     about a reflector's air-side normal n (peaks when the pair is specular about n), scaled by per-band
+//     reflectivity ρ.
+//
+// The half-vector is the reciprocal variable: ĥ(−ω_out, −ω_in) = ĥ(ω_in, ω_out), and ω_in·ω_out is likewise
+// swap-invariant, so T(ω_in,ω_out) = T(−ω_out,−ω_in) BY CONSTRUCTION (acoustic reciprocity, medium at rest).
+// And ĥ·n only reaches +1 when ω_in·n < 0 (the in-ray enters the surface's FRONT face), so a lobe cannot
+// fire for a ray hitting the back — the front-face/reachability gate is intrinsic, no separate test needed.
+//
+// See PROBE_TRANSFER_RESEARCH.md §3. Pure math; no allocation; no WebAudio.
+
+// Lobe layout in a flat Float32Array: STRIDE floats per lobe.
+export const LOBE_STRIDE = 7;
+const LOBE_NX = 0, LOBE_NY = 1, LOBE_NZ = 2; // air-side normal (the SG axis, unit)
+const LOBE_LAMBDA = 3;                        // SG sharpness (large = flat mirror; small = rough/curved)
+const LOBE_RHO = 4;                           // per-band reflectivity ρ[low,mid,high] at LOBE_RHO + band
+
+// FORWARD / passthrough plateau. Φ(c), c = ω_in·ω_out (1 = straight). It is a PLATEAU (≡1 up to the graph's
+// typical edge-to-edge angle, then falls off) — NOT a sharp Gaussian — so a straight corridor sampled by a
+// jittered probe graph accrues NO per-hop loss (a sharp term would bleed loss at every probe and a long
+// straight run would spuriously attenuate). These are DISCRETIZATION knobs (probe spacing/jitter), not
+// physics: PLATEAU_COS = cos(angle below which a bend is "straight enough"), FALLOFF = decay steepness past it.
+export const FORWARD_PLATEAU_COS = 0.766; // cos 40° — bends ≤ 40° pass free
+export const FORWARD_FALLOFF = 4;         // e.g. a 90° open-air bend → Φ ≈ 0.05 (−13 dB), 135° → ≈ −25 dB
+
+// Below this half-vector length the pair is ~straight (ĥ ill-defined): reflections vanish, forward owns it.
+const STRAIGHT_EPSILON = 1e-9;
+
+/**
+ * Forward / passthrough transfer for a bend whose in·out cosine is `c` (1 = perfectly straight). 1 on the
+ * plateau, exponential decay past it. Band-independent (geometry, not material).
+ * @param {number} c ω_in·ω_out
+ * @returns {number} forward transfer in [0, 1]
+ */
+export function forward_plateau(c) {
+    if (c >= FORWARD_PLATEAU_COS) {
+        return 1;
+    }
+    return Math.exp(FORWARD_FALLOFF * (c - FORWARD_PLATEAU_COS));
+}
+
+/**
+ * Per-band transfer T(ω_in, ω_out) at a probe, written into `out[0..2]` (low/mid/high) — clamped to [0, 1].
+ * `out_b = min(1, max(forward, max over lobes of ρ_b · SG(ĥ·n; λ)))`, the dominant of the forward
+ * passthrough and the best reflection lobe (the leak picks the best mechanism; `max` keeps it ≤ 1, i.e. a
+ * probe never amplifies, and makes straight-through full regardless of nearby reflectors). Reflection lobes
+ * are weighted by the bend `(1−ω_in·ω_out)/2` so the ĥ-undefined straight region is the forward term's alone.
+ *
+ * Directions are unit PROPAGATION directions (the way the wave travels). Reciprocal:
+ * `T(ω_in,ω_out) = T(−ω_out,−ω_in)`.
+ *
+ * @param {Float32Array|number[]} out length ≥ 3 — per-band result
+ * @param {Float32Array} lobes flat lobe array (LOBE_STRIDE floats each)
+ * @param {number} lobeOffset start index of this probe's lobes in `lobes`
+ * @param {number} lobeCount number of lobes for this probe
+ * @param {number} inx @param {number} iny @param {number} inz   ω_in (unit)
+ * @param {number} outx @param {number} outy @param {number} outz ω_out (unit)
+ */
+export function acoustic_probe_transfer(out, lobes, lobeOffset, lobeCount, inx, iny, inz, outx, outy, outz) {
+    const c = inx * outx + iny * outy + inz * outz; // ω_in·ω_out
+
+    // forward seeds every band (the floor every reflection competes with)
+    const fwd = forward_plateau(c);
+    let b0 = fwd, b1 = fwd, b2 = fwd;
+
+    // half-vector ĥ = normalize(ω_out − ω_in); the reciprocal reflection variable
+    let hx = outx - inx, hy = outy - iny, hz = outz - inz;
+    const hlen2 = hx * hx + hy * hy + hz * hz;
+
+    if (hlen2 > STRAIGHT_EPSILON && lobeCount > 0) {
+        const hinv = 1 / Math.sqrt(hlen2);
+        hx *= hinv; hy *= hinv; hz *= hinv;
+
+        // a "reflection" with no direction change is not one — fade lobes in with the bend
+        const bend = (1 - c) * 0.5; // 0 at straight, → 1 at reversal
+
+        for (let k = 0; k < lobeCount; k++) {
+            const base = lobeOffset + k * LOBE_STRIDE;
+            const hdotn = hx * lobes[base + LOBE_NX] + hy * lobes[base + LOBE_NY] + hz * lobes[base + LOBE_NZ];
+            const g = bend * Math.exp(lobes[base + LOBE_LAMBDA] * (hdotn - 1)); // SG at the half-vector
+
+            const r0 = lobes[base + LOBE_RHO] * g;
+            const r1 = lobes[base + LOBE_RHO + 1] * g;
+            const r2 = lobes[base + LOBE_RHO + 2] * g;
+
+            if (r0 > b0) b0 = r0;
+            if (r1 > b1) b1 = r1;
+            if (r2 > b2) b2 = r2;
+        }
+    }
+
+    out[0] = b0 > 1 ? 1 : b0;
+    out[1] = b1 > 1 ? 1 : b1;
+    out[2] = b2 > 1 ? 1 : b2;
+}

package/src/engine/sound/simulation/probe/acoustic_trace_energy.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Trace ONE ray's multi-bounce energy through the scene, depositing per-band energy into a time-binned
+ * echogram. "Reverb = reflections with the source at the listener": the ray starts at the probe carrying
+ * unit per-band energy `[low, mid, high]`; at each surface hit it deposits its surviving energy into the
+ * bin for the cumulative arrival time (`pathLength / speedOfSound`), then loses `material.absorption[band]`
+ * and scatters — diffuse (cosine lobe about the normal) with probability `material.scattering`, else
+ * specular (reflect about the normal). A ray stops when it escapes, reaches the echogram window, decays
+ * below `energyThreshold`, or hits `maxBounce`.
+ *
+ * Termination is by ENERGY THRESHOLD, not Russian roulette. RR with a fixed survival probability is the
+ * wrong estimator for acoustic reflectance: a survivor at bounce `n` carries energy `(1−α)^n` yet is
+ * scaled by `2^n`, so for a live room (`1−α > ½`) the survivor weight grows as `(2(1−α))^n` and the rare
+ * deep survivors dominate the late bins with enormous weights — exactly the part of the curve the RT60
+ * slope is fitted to. Decaying each ray deterministically until it falls below the fit floor (then
+ * dropping it, no survivor scaling) is unbiased for the fit window and far lower variance.
+ *
+ * DIRECTIONAL (FOA) encode: by acoustic reciprocity the reverberant energy this "source-at-the-listener"
+ * ray represents ARRIVES at the listener from the ray's initial LAUNCH direction (reverse the path — its
+ * last segment toward the listener is the launch segment reversed). So every deposit this ray makes is
+ * attributed to that one launch direction: `directionAccum` accumulates, per band, the energy-weighted
+ * launch direction (the first-order / B-format `XYZ` arrival vector; the echogram is the `W` omni term).
+ * Summed over a sphere of rays and normalised by total energy, it gives the room's per-band arrival
+ * anisotropy at the probe (≈0 = diffuse, →1 = one strong direction).
+ *
+ * Leak-free (the scale-aware self-occlusion offset). Allocation-free (module scratch); deterministic for a
+ * given `random`. No WebAudio.
+ *
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {Ray3} ray origin (= probe) + initial UNIT direction; CONSUMED (mutated as it bounces)
+ * @param {Float32Array} echogram per-band time bins, band-major `[band * binCount + bin]`, ACCUMULATED into
+ * @param {Float32Array} directionAccum per-band energy-weighted launch direction, band-major `[band*3 + xyz]`
+ *        (length 9), ACCUMULATED into
+ * @param {number} binCount number of time bins per band
+ * @param {number} binSeconds seconds per bin
+ * @param {number} speedOfSound metres/second (e.g. {@link SPEED_OF_SOUND_MPS})
+ * @param {number} maxBounce hard bounce cap (safety net for a near-lossless scene)
+ * @param {number} energyThreshold stop once every band's energy is below this (set below the RT60 fit floor)
+ * @param {function():number} random seeded RNG
+ */
+export function acoustic_trace_energy(index: AcousticOccluderIndex, ray: Ray3, echogram: Float32Array, directionAccum: Float32Array, binCount: number, binSeconds: number, speedOfSound: number, maxBounce: number, energyThreshold: number, random: () => number): void;
+/**
+ * Speed of sound in air (m/s, ~20 °C). Converts a ray's path length to arrival time.
+ * @type {number}
+ */
+export const SPEED_OF_SOUND_MPS: number;
+//# sourceMappingURL=acoustic_trace_energy.d.ts.map

package/src/engine/sound/simulation/probe/acoustic_trace_energy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acoustic_trace_energy.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/acoustic_trace_energy.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,yFAVW,YAAY,kBACZ,YAAY,YAEZ,MAAM,cACN,MAAM,gBACN,MAAM,aACN,MAAM,mBACN,MAAM,gBACK,MAAM,QA6E3B;AAnID;;;GAGG;AACH,iCAFU,MAAM,CAEsB"}

package/src/engine/sound/simulation/probe/acoustic_trace_energy.js

@@ -0,0 +1,136 @@
+import { getBiasedNormalSample } from "../../../graphics/sh3/path_tracer/sampling/getBiasedNormalSample.js";
+import { v3_reflect } from "../../../../core/geom/vec3/v3_reflect.js";
+import { RayHit } from "../core/RayHit.js";
+
+/**
+ * Speed of sound in air (m/s, ~20 °C). Converts a ray's path length to arrival time.
+ * @type {number}
+ */
+export const SPEED_OF_SOUND_MPS = 343;
+
+// module-static scratch — the bake is offline but stays allocation-free across rays/probes.
+const HIT = new RayHit();
+const SCATTER_DIR = [0, 0, 0];
+
+/**
+ * Base self-occlusion offset; scaled by coordinate magnitude so it stays above the Float32 ULP at large
+ * world scales (a fixed epsilon silently leaks energy through walls far from the origin).
+ * @type {number}
+ */
+const SELF_OCCLUSION_OFFSET = 0.00001;
+
+/**
+ * Trace ONE ray's multi-bounce energy through the scene, depositing per-band energy into a time-binned
+ * echogram. "Reverb = reflections with the source at the listener": the ray starts at the probe carrying
+ * unit per-band energy `[low, mid, high]`; at each surface hit it deposits its surviving energy into the
+ * bin for the cumulative arrival time (`pathLength / speedOfSound`), then loses `material.absorption[band]`
+ * and scatters — diffuse (cosine lobe about the normal) with probability `material.scattering`, else
+ * specular (reflect about the normal). A ray stops when it escapes, reaches the echogram window, decays
+ * below `energyThreshold`, or hits `maxBounce`.
+ *
+ * Termination is by ENERGY THRESHOLD, not Russian roulette. RR with a fixed survival probability is the
+ * wrong estimator for acoustic reflectance: a survivor at bounce `n` carries energy `(1−α)^n` yet is
+ * scaled by `2^n`, so for a live room (`1−α > ½`) the survivor weight grows as `(2(1−α))^n` and the rare
+ * deep survivors dominate the late bins with enormous weights — exactly the part of the curve the RT60
+ * slope is fitted to. Decaying each ray deterministically until it falls below the fit floor (then
+ * dropping it, no survivor scaling) is unbiased for the fit window and far lower variance.
+ *
+ * DIRECTIONAL (FOA) encode: by acoustic reciprocity the reverberant energy this "source-at-the-listener"
+ * ray represents ARRIVES at the listener from the ray's initial LAUNCH direction (reverse the path — its
+ * last segment toward the listener is the launch segment reversed). So every deposit this ray makes is
+ * attributed to that one launch direction: `directionAccum` accumulates, per band, the energy-weighted
+ * launch direction (the first-order / B-format `XYZ` arrival vector; the echogram is the `W` omni term).
+ * Summed over a sphere of rays and normalised by total energy, it gives the room's per-band arrival
+ * anisotropy at the probe (≈0 = diffuse, →1 = one strong direction).
+ *
+ * Leak-free (the scale-aware self-occlusion offset). Allocation-free (module scratch); deterministic for a
+ * given `random`. No WebAudio.
+ *
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {Ray3} ray origin (= probe) + initial UNIT direction; CONSUMED (mutated as it bounces)
+ * @param {Float32Array} echogram per-band time bins, band-major `[band * binCount + bin]`, ACCUMULATED into
+ * @param {Float32Array} directionAccum per-band energy-weighted launch direction, band-major `[band*3 + xyz]`
+ *        (length 9), ACCUMULATED into
+ * @param {number} binCount number of time bins per band
+ * @param {number} binSeconds seconds per bin
+ * @param {number} speedOfSound metres/second (e.g. {@link SPEED_OF_SOUND_MPS})
+ * @param {number} maxBounce hard bounce cap (safety net for a near-lossless scene)
+ * @param {number} energyThreshold stop once every band's energy is below this (set below the RT60 fit floor)
+ * @param {function():number} random seeded RNG
+ */
+export function acoustic_trace_energy(
+    index, ray, echogram, directionAccum, binCount, binSeconds, speedOfSound, maxBounce, energyThreshold, random
+) {
+    let energyLow = 1;
+    let energyMid = 1;
+    let energyHigh = 1;
+
+    // the launch direction (read before the bounce loop mutates ray[3..5]) — every deposit this ray makes
+    // is attributed to it as the arrival direction (reciprocity, see above)
+    const launchX = ray[3];
+    const launchY = ray[4];
+    const launchZ = ray[5];
+
+    let pathLength = 0;
+
+    const irMetres = binCount * binSeconds * speedOfSound; // path length at which the echogram window ends
+
+    for (let bounce = 0; bounce < maxBounce; bounce++) {
+        // never trace past the echogram window — a hit beyond it could not be deposited anyway
+        ray.tMax = irMetres - pathLength;
+
+        if (ray.tMax <= 0 || !index.closestHit(ray, HIT)) {
+            return; // escaped, or no more geometry within the remaining window
+        }
+
+        pathLength += HIT.t;
+
+        const bin = Math.floor((pathLength / speedOfSound) / binSeconds);
+
+        if (bin >= binCount) {
+            return; // arrived past the last bin
+        }
+
+        echogram[bin] += energyLow;
+        echogram[binCount + bin] += energyMid;
+        echogram[2 * binCount + bin] += energyHigh;
+
+        // FOA arrival vector: this deposit's energy arrives from the launch direction (reciprocity)
+        directionAccum[0] += energyLow * launchX;
+        directionAccum[1] += energyLow * launchY;
+        directionAccum[2] += energyLow * launchZ;
+        directionAccum[3] += energyMid * launchX;
+        directionAccum[4] += energyMid * launchY;
+        directionAccum[5] += energyMid * launchZ;
+        directionAccum[6] += energyHigh * launchX;
+        directionAccum[7] += energyHigh * launchY;
+        directionAccum[8] += energyHigh * launchZ;
+
+        // fold in this surface's absorption (the energy that continues past the reflection)
+        const absorption = HIT.material.absorption;
+        energyLow *= 1 - absorption[0];
+        energyMid *= 1 - absorption[1];
+        energyHigh *= 1 - absorption[2];
+
+        // drop the ray once even its loudest band has decayed below the fit floor
+        if (energyLow < energyThreshold && energyMid < energyThreshold && energyHigh < energyThreshold) {
+            return;
+        }
+
+        // bounce from the hit point: diffuse (cosine lobe) with prob `scattering`, else specular.
+        // v3_reflect must read the INCOMING direction (ray[3..5]) before we overwrite it.
+        if (random() < HIT.material.scattering) {
+            getBiasedNormalSample(SCATTER_DIR, 0, HIT.normal, 0, 1, random);
+        } else {
+            v3_reflect(SCATTER_DIR, 0, ray[3], ray[4], ray[5], HIT.normal[0], HIT.normal[1], HIT.normal[2]);
+        }
+
+        ray.setOrigin(HIT.position[0], HIT.position[1], HIT.position[2]);
+        ray.setDirection(SCATTER_DIR[0], SCATTER_DIR[1], SCATTER_DIR[2]);
+
+        // step off the surface so the next query doesn't immediately re-hit it; scale with coordinate
+        // magnitude so the nudge stays above the Float32 ULP far from the origin.
+        const magnitude = Math.max(Math.abs(ray[0]), Math.abs(ray[1]), Math.abs(ray[2]));
+        ray.shiftForward(SELF_OCCLUSION_OFFSET * Math.max(1, magnitude));
+    }
+}