@woosh/meep-engine 2.163.11 → 2.164.0

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

@@ -0,0 +1,637 @@
+import { BinaryElementPool } from "../../../core/geom/3d/topology/struct/binary/BinaryElementPool.js";
+import { Vector3 } from "../../../core/geom/Vector3.js";
+import { seededRandom } from "../../../core/math/random/seededRandom.js";
+import { INVALID_NODE } from "../../../core/graph/csr/csr_graph_build_distance_field.js";
+import { line3_compute_segment_closest_point_t } from "../../../core/geom/3d/line/line3_compute_segment_closest_point_t.js";
+import { AcousticMedium } from "./core/AcousticMedium.js";
+import { AcousticOccluderIndex } from "./core/AcousticOccluderIndex.js";
+import { AcousticRegionIndex } from "./core/AcousticRegionIndex.js";
+import { AcousticSolution } from "./core/AcousticSolution.js";
+import { ACOUSTIC_SOURCE_STATE_FLOATS, AcousticSourceState } from "./core/AcousticSourceState.js";
+import { OcclusionSolver } from "./core/OcclusionSolver.js";
+import { VolumeField } from "./core/VolumeField.js";
+import { ProbeFieldPathingSolution } from "./probe/ProbeFieldPathingSolution.js";
+import { ProbeVisibilityRecheck } from "./probe/ProbeVisibilityRecheck.js";
+
+// module-static scratch solution reused across every instance in apply()
+const SOLUTION = new AcousticSolution();
+
+// module-static scratch for the source's world-space forward vector during directivity
+const FORWARD = new Vector3();
+
+/**
+ * Default ambient atmospheric absorption (dB per metre, per band low/mid/high) for space outside every
+ * authored `AcousticVolume`. Anchored at the low band (lows carry any distance), rising toward the highs so
+ * distant sources progressively lose their top end. A modest, tunable default — pass your own
+ * `defaultMedium` to dial the air thicker/thinner (or zero it for vacuum-clean falloff).
+ * @type {number[]}
+ */
+const DEFAULT_AIR_ABSORPTION = [0, 0.03, 0.1];
+
+// default RNG seed for deterministic ray jitter (override via the `random_seed` field)
+const DEFAULT_RANDOM_SEED = 1;
+
+// module-static scratch for one leg's air absorption while integrating along the leaked polyline
+const PATH_AIRLOSS_LEG = new Float32Array(3);
+
+// scratch — per-band directional transfer at a probe (the corner-leak turn gate)
+const TURN_TRANSFER = new Float32Array(3);
+// below this squared leg length an attachment/edge direction is undefined → no directional gate
+const TURN_EPS = 1e-12;
+
+/**
+ * The acoustic simulation engine: owns the occluder index, the medium volume regions, the solvers, and
+ * the per-instance temporal state, and turns a source position into an {@link AcousticSolution} the
+ * render seam consumes. ECS-agnostic and WebAudio-agnostic — the ECS systems feed its geometry and the
+ * `AudioEmitterSystem` drives {@link apply}; both inject real objects, so it is unit-testable on bare
+ * geometry.
+ *
+ * Tunables are plain settable fields (not an opaque config bag): construct with no arguments, then set
+ * `rayCount`, `smoothing`, `random_seed`, `medium`, `pathing`, … after construction to taste.
+ */
+export class AcousticSimulator {
+    /**
+     * Rays cast per source per tick. Lower + temporal smoothing = cheaper, integrated over frames.
+     * @type {number}
+     */
+    rayCount = 16;
+
+    /**
+     * EMA factor for temporal smoothing, (0, 1]. Smaller = smoother / slower to react.
+     * @type {number}
+     */
+    smoothing = 0.4;
+
+    /**
+     * Engine-wide corner-leakage toggle. Off (default) = zero cost (no path branch, no graph search).
+     * On = occluded sources route a leaked send spatialized from their propagation exit point. Requires
+     * a probe field with a baked visibility graph ({@link setProbeField}).
+     * @type {boolean}
+     */
+    pathing = false;
+
+    /**
+     * Re-verify the visibility edges leaks traverse against LIVE geometry (dynamic-geometry policy — a door
+     * that closes after the bake re-blocks the leak). Off (default) = the baked graph is trusted as-is.
+     * Requires {@link pathing}. The recheck is budgeted ({@link recheckBudget}); a blocked edge is disabled
+     * by weight (no topology change), restored when it re-opens.
+     * @type {boolean}
+     */
+    pathingRecheck = false;
+
+    /**
+     * Max visibility edges re-verified per tick when {@link pathingRecheck} is on (one `anyHit` ray each).
+     * Bounds the recheck cost; leftover dirty edges round-robin to later ticks.
+     * @type {number}
+     */
+    recheckBudget = 8;
+
+    /**
+     * @type {AcousticOccluderIndex}
+     */
+    #occluder_index = new AcousticOccluderIndex();
+
+    /**
+     * Medium regions behind a BVH — blend queries resolve in O(log n) (re-fit each frame for moving volumes).
+     * @type {AcousticRegionIndex}
+     */
+    #region_index = new AcousticRegionIndex();
+
+    /**
+     * Ambient medium field — its default medium (settable via {@link medium}) fills space outside every
+     * authored region.
+     * @type {VolumeField}
+     */
+    #volumeField = new VolumeField(AcousticMedium.from(DEFAULT_AIR_ABSORPTION));
+
+    /**
+     * @type {OcclusionSolver}
+     */
+    #occlusionSolver = new OcclusionSolver();
+
+    /**
+     * Live-instance → its temporal-state record id in {@link #statePool}. The state DATA lives in the
+     * pool (flat floats); this map only holds the id relation. Audio events are highly transient (a
+     * burst of one-shots), so pooling the records avoids per-source object churn — freed slots are
+     * recycled, not GC'd.
+     * @type {Map<EventInstance, number>}
+     */
+    #stateIds = new Map();
+
+    /**
+     * Backing store for per-source {@link AcousticSourceState} records (one record =
+     * {@link ACOUSTIC_SOURCE_STATE_FLOATS} float32s).
+     * @type {BinaryElementPool}
+     */
+    #statePool = new BinaryElementPool(ACOUSTIC_SOURCE_STATE_FLOATS * Float32Array.BYTES_PER_ELEMENT);
+
+    /**
+     * One reusable cursor, re-pointed at each live instance's pool record per tick (zero-alloc).
+     * @type {AcousticSourceState}
+     */
+    #stateCursor = new AcousticSourceState();
+
+    /**
+     * Seeded RNG for deterministic ray jitter. Re-created when {@link random_seed} is set.
+     * @type {function():number}
+     */
+    #random = seededRandom(DEFAULT_RANDOM_SEED);
+
+    /**
+     * The current RNG seed (backs {@link random_seed}).
+     * @type {number}
+     */
+    #randomSeed = DEFAULT_RANDOM_SEED;
+
+    /**
+     * Reused scratch set for pruning ended-instance state in {@link apply} (allocation-free).
+     * @type {Set<EventInstance>}
+     */
+    #liveScratch = new Set();
+
+    /**
+     * Baked probe field whose visibility graph drives pathing (corner-leakage). Null until
+     * {@link setProbeField}.
+     * @type {AcousticProbeField|null}
+     */
+    #probeField = null;
+
+    /**
+     * Budgeted incremental visibility recheck over the probe-visibility graph (dynamic geometry — a door
+     * that closes after the bake). Null unless {@link pathingRecheck} is on and a field is set; created
+     * alongside the pathing solution. Edges traversed by leaks are marked here and re-verified within budget.
+     * @type {ProbeVisibilityRecheck|null}
+     */
+    #visibilityRecheck = null;
+
+    /**
+     * Per-frame exit-field solver over {@link #probeField}'s visibility graph (corner-leakage). Lazily
+     * (re)created the first time pathing runs against the current field, then reused across frames.
+     * @type {ProbeFieldPathingSolution|null}
+     */
+    #pathingSolution = null;
+
+    /**
+     * RNG seed for deterministic ray jitter. Setting it re-seeds the generator (resets the jitter stream).
+     * Default {@link DEFAULT_RANDOM_SEED}.
+     * @returns {number}
+     */
+    get random_seed() {
+        return this.#randomSeed;
+    }
+
+    set random_seed(seed) {
+        this.#randomSeed = seed;
+        this.#random = seededRandom(seed);
+    }
+
+    /**
+     * The default medium for space outside every authored `AcousticVolume` region (ambient air). Default: a
+     * modest atmospheric absorption ({@link DEFAULT_AIR_ABSORPTION}); set it to dial the air thicker/thinner
+     * (or zero it for vacuum-clean falloff).
+     * @returns {AcousticMedium}
+     */
+    get medium() {
+        return this.#volumeField.defaultMedium;
+    }
+
+    set medium(medium) {
+        this.#volumeField.defaultMedium = medium;
+    }
+
+    /**
+     * The occluder index, for offline baking (reverb / visibility) against the same scene geometry the
+     * runtime occludes with.
+     * @returns {AcousticOccluderIndex}
+     */
+    get occluderIndex() {
+        return this.#occluder_index;
+    }
+
+    /**
+     * Register an occluder shape, placed by `matrix` (its canonical frame is local; the matrix is the
+     * world transform).
+     * @param {AbstractShape3D} shape
+     * @param {AcousticMaterial} material
+     * @param {Float32Array|number[]} [matrix]
+     * @returns {number} occluder handle
+     */
+    addOccluder(shape, material, matrix) {
+        return this.#occluder_index.addBody(shape, material, matrix);
+    }
+
+    /**
+     * @param {number} handle
+     * @param {Float32Array|number[]} matrix
+     */
+    setOccluderTransform(handle, matrix) {
+        this.#occluder_index.setTransform(handle, matrix);
+    }
+
+    /**
+     * @param {number} handle
+     */
+    removeOccluder(handle) {
+        this.#occluder_index.removeBody(handle);
+    }
+
+    /**
+     * @param {AcousticVolumeRegion} region
+     * @returns {AcousticVolumeRegion} the same region (for handle-keeping)
+     */
+    addRegion(region) {
+        return this.#region_index.add(region);
+    }
+
+    /**
+     * @param {AcousticVolumeRegion} region
+     */
+    removeRegion(region) {
+        this.#region_index.remove(region);
+    }
+
+    /**
+     * The baked probe field currently wired in (for pathing + probe reverb), or null if none. Paired with the
+     * {@link occluderIndex} it is what an offline re-bake (e.g. after deserialization) runs against.
+     * @returns {AcousticProbeField|null}
+     */
+    get probeField() {
+        return this.#probeField;
+    }
+
+    /**
+     * Provide the baked probe field (with a visibility graph) that pathing routes through, or `null` to
+     * clear it. Required before {@link pathing} has any effect. The exit-field solver is dropped and lazily
+     * rebuilt for the new field.
+     * @param {AcousticProbeField|null} field a field with a baked visibility graph ({@link bakeVisibility})
+     */
+    setProbeField(field) {
+        this.#probeField = field;
+        this.#pathingSolution = null;
+        this.#visibilityRecheck = null; // rebuilt against the new field (and its graph) on the next tick
+    }
+
+    /**
+     * Compute the full acoustic solution for a source at `source`, given `listener`, into `out`.
+     * @param {Vector3} listener
+     * @param {Vector3} source
+     * @param {number} sourceRadius apparent radius of the source (per-source; 0 = point source). For
+     *        volumetric (fractional) occlusion.
+     * @param {AcousticSourceState} state per-source temporal accumulation (mutated)
+     * @param {AcousticSolution} out
+     */
+    solveFor(listener, source, sourceRadius, state, out) {
+        out.reset();
+
+        // air absorption integrated over the actual source→listener path (distance-dependent, per band)
+        this.#volumeField.integrateAbsorption(
+            this.#region_index,
+            source.x, source.y, source.z,
+            listener.x, listener.y, listener.z,
+            out.airLoss
+        );
+
+        this.#occlusionSolver.solve(
+            listener, source, sourceRadius,
+            this.#occluder_index, this.rayCount, this.smoothing, this.#random,
+            state, out
+        );
+    }
+
+    /**
+     * Solve + push the result to every live instance. Each instance must expose a `position` (Vector3)
+     * and `setAcoustic(solution)`. Called once per frame by the `AudioEmitterSystem`, between the live-set
+     * refresh and the sopra tick.
+     * @param {EventInstance[]} liveInstances bounded set (≤ voice budget)
+     * @param {Vector3} listener
+     */
+    apply(liveInstances, listener) {
+        const live = this.#liveScratch;
+        live.clear();
+
+        // re-fit moving volumes' BVH leaves once per frame (regions track Transform.position by reference),
+        // so this frame's blend queries see current positions.
+        this.#region_index.refit();
+
+        // pathing (corner-leakage): one single-source pass from the listener serves every source's exit
+        const pathing = this.pathing && this.#probeField !== null && this.#probeField.hasVisibility;
+        // The exit field is usable only once the listener has snapped to a VISIBLE probe + solved this frame;
+        // if the listener can see no probe, pathing is off for every source this frame (no stale field).
+        let exitFieldReady = false;
+        if (pathing) {
+            if (this.#pathingSolution === null) {
+                this.#pathingSolution = new ProbeFieldPathingSolution(this.#probeField.size);
+            }
+            if (this.pathingRecheck && this.#visibilityRecheck === null) {
+                this.#visibilityRecheck = new ProbeVisibilityRecheck(this.#probeField, this.#occluder_index);
+            }
+            // Snap to the nearest probe the listener can SEE — never one occluded by a wall/floor (a different
+            // acoustic region), which would route a spurious cross-occluder detour or none at all.
+            const listenerProbe = this.#probeField.nearestVisibleIndex(listener.x, listener.y, listener.z, this.#occluder_index);
+            if (listenerProbe >= 0) {
+                this.#pathingSolution.computeExitField(this.#probeField.visibilityGraph, listenerProbe);
+                exitFieldReady = true;
+            }
+        }
+
+        const pool = this.#statePool;
+        const cursor = this.#stateCursor;
+
+        for (let i = 0; i < liveInstances.length; i++) {
+            const instance = liveInstances[i];
+
+            live.add(instance);
+
+            let id = this.#stateIds.get(instance);
+
+            if (id === undefined) {
+                id = pool.allocate();
+                this.#stateIds.set(instance, id);
+                // the pool view may have grown during allocate — bind the current one, then clear the
+                // (possibly recycled) record to its cold state before the first solve.
+                cursor.rebind(pool.data_float32, pool.element_word(id));
+                cursor.reset();
+            } else {
+                cursor.rebind(pool.data_float32, pool.element_word(id));
+            }
+
+            this.solveFor(listener, instance.position, instance.sourceRadius, cursor, SOLUTION);
+
+            if (exitFieldReady) {
+                this.#applyPath(SOLUTION, instance, listener);
+            }
+
+            // source radiation directivity (skipped for omni sources — the common case, zero cost)
+            const directivity = instance.directivity;
+            if (directivity && !directivity.isOmni) {
+                this.#applyDirectivity(SOLUTION, instance, listener);
+            }
+
+            instance.setAcoustic(SOLUTION);
+        }
+
+        // release pool records for instances no longer live (ended / demoted) — keeps the live set
+        // bounded without per-instance lifecycle wiring; freed ids are recycled by the next allocate.
+        if (this.#stateIds.size > live.size) {
+            for (const instance of this.#stateIds.keys()) {
+                if (!live.has(instance)) {
+                    pool.release(this.#stateIds.get(instance));
+                    this.#stateIds.delete(instance);
+                }
+            }
+        }
+
+        // dynamic-geometry policy: re-verify (within budget) the visibility edges the leaks just traversed,
+        // disabling/restoring them against live geometry. The updated weights take effect next frame's solve.
+        // Gated on the LIVE flag (not just the object), so toggling pathingRecheck off stops marking + rechecking
+        // immediately; the object persists for cheap re-enable.
+        if (this.pathingRecheck && this.#visibilityRecheck !== null) {
+            this.#visibilityRecheck.update(this.recheckBudget);
+        }
+
+        live.clear();
+    }
+
+    /**
+     * Fill the path (corner-leakage) fields of `solution` for a source, using the exit field computed this
+     * frame. The leaked level grows with occlusion (more blocked → more of the sound arrives via the path) and
+     * falls with routed length; no path → fields left cleared.
+     *
+     * The source and listener are not graph vertices: each is VIRTUALIZED onto its adjacent corridor edge (the
+     * nearest point via line3 closest-point), so the attachment legs are the true geometry rather than a dart to
+     * the probe centre — a probe sitting just past an endpoint no longer folds a there-and-back bend into the
+     * route, and a standoff/oblique endpoint attenuates instead of under-counting. The distance falloff is the
+     * SOURCE's own authored attenuation curve evaluated at the routed length = source-leg + corridor span +
+     * listener-leg (the corridor span is the graph distance, less the partial first/last edges the virtual
+     * points cut off). The curve — with its `distanceMax` — is where a source's audible range legitimately
+     * lives; the simulator carries no presumptuous global scale of its own.
+     *
+     * Once the leak is known audible, a single walk of the polyline (source-probe → … → listener-probe, via
+     * `nextProbe`) integrates AIR ABSORPTION per leg (the longer route darkens more than the direct line) and
+     * marks each traversed edge for the budgeted visibility recheck — an out-of-range leak returns BEFORE the
+     * walk, so it spends no recheck budget. DIRECTIVITY-on-leak scales the gain by the source's radiation toward
+     * the first hop (the corner it leaks through), not the blocked listener.
+     * @param {AcousticSolution} solution (occlusion already solved)
+     * @param {EventInstance} instance the source (position + attenuation + orientation + directivity)
+     * @param {Vector3} listener the listener world position (the leak's far endpoint)
+     */
+    #applyPath(solution, instance, listener) {
+        const field = this.#probeField;
+        const pathingSolution = this.#pathingSolution;
+        const source = instance.position;
+
+        const sourceProbe = field.nearestVisibleIndex(source.x, source.y, source.z, this.#occluder_index);
+
+        if (sourceProbe < 0) {
+            return;
+        }
+
+        const exit = pathingSolution.exit[sourceProbe];
+
+        if (exit === INVALID_NODE) {
+            return;
+        }
+
+        // The corridor endpoints, derivable WITHOUT walking: `firstHop` is the source-probe's first hop toward
+        // the listener; the gateway `exit` is the probe adjacent to the listener's probe (the last hop); and the
+        // listener's probe — the exit-field root — is one hop past the gateway. All valid here: exit and next go
+        // INVALID together (both only at the root / an unreachable source) and exit===INVALID already returned,
+        // and `exit` is a NEIGHBOUR of the root, so next[exit] IS the root.
+        const firstHop = pathingSolution.next[sourceProbe];
+        const listenerProbe = pathingSolution.next[exit];
+
+        const spx = field.probeX(sourceProbe), spy = field.probeY(sourceProbe), spz = field.probeZ(sourceProbe);
+        const fhx = field.probeX(firstHop), fhy = field.probeY(firstHop), fhz = field.probeZ(firstHop);
+        const lhx = field.probeX(exit), lhy = field.probeY(exit), lhz = field.probeZ(exit);
+        const lpx = field.probeX(listenerProbe), lpy = field.probeY(listenerProbe), lpz = field.probeZ(listenerProbe);
+
+        // Virtualize the dynamic endpoints onto their adjacent edges (line3 closest point) rather than darting
+        // to the probe vertex: (a) avoids the spurious there-and-back bend a probe sitting just past the
+        // endpoint would fold into the route (the transfer gate would wrongly refuse it), and (b) lets the
+        // attachment legs count toward the routed distance, so a standoff / oblique endpoint attenuates.
+        const tS = line3_compute_segment_closest_point_t(spx, spy, spz, fhx, fhy, fhz, source.x, source.y, source.z);
+        const sX = spx + (fhx - spx) * tS, sY = spy + (fhy - spy) * tS, sZ = spz + (fhz - spz) * tS;
+        const sourceLeg = Math.hypot(source.x - sX, source.y - sY, source.z - sZ);
+        const firstEdgeLen = Math.hypot(fhx - spx, fhy - spy, fhz - spz);
+
+        const tL = line3_compute_segment_closest_point_t(lhx, lhy, lhz, lpx, lpy, lpz, listener.x, listener.y, listener.z);
+        const lX = lhx + (lpx - lhx) * tL, lY = lhy + (lpy - lhy) * tL, lZ = lhz + (lpz - lhz) * tL;
+        const listenerLeg = Math.hypot(listener.x - lX, listener.y - lY, listener.z - lZ);
+        const lastEdgeLen = Math.hypot(lpx - lhx, lpy - lhy, lpz - lhz);
+
+        // Corridor span between the two virtual attach points. A SINGLE-edge route (firstHop IS the listener's
+        // probe) projects both endpoints onto that ONE edge, so the span is just their |arc| gap. The
+        // graph-distance subtraction (the general case) assumes DISTINCT first/last edges — for one shared edge
+        // it would mis-sign a tS>tL crossing; for distinct edges it is exactly (1−tS)·first + middle + tL·last,
+        // which is ≥ 0 by construction (the partial edges sum to ≤ dist).
+        const corridor = firstHop === listenerProbe
+            ? Math.abs(tL - tS) * firstEdgeLen
+            : pathingSolution.dist[sourceProbe] - tS * firstEdgeLen - (1 - tL) * lastEdgeLen;
+
+        const falloff = Math.max(0, instance.description.attenuation.evaluate(sourceLeg + corridor + listenerLeg));
+
+        if (falloff <= 0) {
+            return; // out of audible range — bail BEFORE the walk, so an inaudible leak spends no recheck budget
+        }
+
+        // pathGain is the BROADBAND geometric leak strength (occlusion × distance falloff × directivity × turn
+        // gates). The per-band material split — (1 − transmission[b]), the energy that did NOT transmit through a
+        // band leaks AROUND it (vs THROUGH it on the direct send) — is applied per band at the render seam, so
+        // direct + leak stay energy-consistent for a band-selective wall.
+        let pathGain = solution.occlusion * falloff;
+
+        // directivity-on-leak: the source radiates toward the FIRST hop (the corner it leaks through), not the
+        // listener it cannot reach directly
+        const directivity = instance.directivity;
+        if (directivity && !directivity.isOmni) {
+            pathGain *= this.#directivityGainToward(instance, fhx, fhy, fhz);
+        }
+
+        // Directional TRANSFER gate (only with baked reflector lobes — otherwise behaves exactly as before).
+        // With the endpoints virtualized, each endpoint bend is the attachment leg vs the corridor edge: an
+        // endpoint ON the corridor passes straight through (degenerate leg → gain 1), one off to the side or
+        // behind it bends and attenuates. (Interior turns: Phase 0b.)
+        if (field.hasTransfer) {
+            pathGain *= this.#turnGain(sourceProbe, sX - source.x, sY - source.y, sZ - source.z, fhx - spx, fhy - spy, fhz - spz);
+            pathGain *= this.#turnGain(listenerProbe, lpx - lhx, lpy - lhy, lpz - lhz, listener.x - lX, listener.y - lY, listener.z - lZ);
+        }
+
+        // Walk the leaked polyline (source-probe → … → listener-probe) once, now that the leak is audible:
+        // integrate air per leg + mark each edge for the budgeted recheck.
+        const leg = PATH_AIRLOSS_LEG;
+        let airLow = 0;
+        let airMid = 0;
+        let airHigh = 0;
+        let prevCur = -1; // the probe before `cur`; gates the INTERIOR turn at `cur`
+        let cur = sourceProbe;
+        let next = firstHop;
+        while (next !== INVALID_NODE) {
+            this.#volumeField.integrateAbsorption(
+                this.#region_index,
+                field.probeX(cur), field.probeY(cur), field.probeZ(cur),
+                field.probeX(next), field.probeY(next), field.probeZ(next),
+                leg
+            );
+            airLow += leg[0];
+            airMid += leg[1];
+            airHigh += leg[2];
+
+            if (this.pathingRecheck && this.#visibilityRecheck !== null) {
+                this.#visibilityRecheck.markEdge(cur, next);
+            }
+
+            // INTERIOR turn gate: charge the bend from the incoming edge to the outgoing edge through every
+            // corridor probe BETWEEN the endpoints, so a leak that diffracts around several corners pays
+            // per-corner loss, not just distance (a far-side wrap-around dies off). The source/listener ENDPOINT
+            // bends are gated above; this gates the interior ones. Only when reflector lobes are baked (else
+            // unchanged). The route is still the DISTANCE-shortest path — turn-AWARE routing (an edge-based
+            // Dijkstra that picks the max-energy route) is the further refinement; this charges the route taken.
+            if (field.hasTransfer && prevCur >= 0) {
+                pathGain *= this.#turnGain(cur,
+                    field.probeX(cur) - field.probeX(prevCur), field.probeY(cur) - field.probeY(prevCur), field.probeZ(cur) - field.probeZ(prevCur),
+                    field.probeX(next) - field.probeX(cur), field.probeY(next) - field.probeY(cur), field.probeZ(next) - field.probeZ(cur));
+            }
+
+            prevCur = cur;
+            cur = next;
+            next = pathingSolution.next[cur];
+        }
+
+        solution.hasPath = true;
+        solution.exit[0] = lhx; // leak emerges from the gateway probe (the last corner before the listener)
+        solution.exit[1] = lhy;
+        solution.exit[2] = lhz;
+        solution.pathGain = pathGain;
+        solution.pathAirLoss[0] = airLow;
+        solution.pathAirLoss[1] = airMid;
+        solution.pathAirLoss[2] = airHigh;
+    }
+
+    /**
+     * Directional-transfer gain at probe `p` for a routed BEND with incoming propagation direction
+     * (inx,iny,inz) and outgoing (outx,outy,outz) — neither need be unit. The band-mean of the probe's
+     * transfer T(in, out): a turn the probe's local reflectors cannot support → ~0; straight-through → 1; a
+     * degenerate (zero-length) direction → 1 (no gate). See {@link AcousticProbeField#probeTransfer} /
+     * PROBE_TRANSFER_RESEARCH.md §3.
+     * @param {number} p probe index
+     * @returns {number} gain in [0, 1]
+     */
+    #turnGain(p, inx, iny, inz, outx, outy, outz) {
+        const il2 = inx * inx + iny * iny + inz * inz;
+        const ol2 = outx * outx + outy * outy + outz * outz;
+
+        if (il2 < TURN_EPS || ol2 < TURN_EPS) {
+            return 1; // a coincident endpoint leaves the bend undefined — don't gate
+        }
+
+        const ii = 1 / Math.sqrt(il2);
+        const oi = 1 / Math.sqrt(ol2);
+
+        this.#probeField.probeTransfer(
+            TURN_TRANSFER, p,
+            inx * ii, iny * ii, inz * ii,
+            outx * oi, outy * oi, outz * oi
+        );
+
+        return (TURN_TRANSFER[0] + TURN_TRANSFER[1] + TURN_TRANSFER[2]) / 3;
+    }
+
+    /**
+     * The source's radiation gain toward a target point `(tx, ty, tz)`: the {@link AcousticDirectivity}
+     * pattern at the angle between the source's world forward (local {@link Vector3.forward} rotated by its
+     * orientation) and the source→target direction. A coincident source/target leaves the direction
+     * undefined → gain 1 (no attenuation).
+     * PRECONDITION: only called for a non-omni `instance.directivity`, which (being authored on the source)
+     * always travels with the source's `orientation`.
+     * @param {EventInstance} instance the source — position + orientation + directivity
+     * @param {number} tx @param {number} ty @param {number} tz target point
+     * @returns {number} radiation gain ≥ 0
+     */
+    #directivityGainToward(instance, tx, ty, tz) {
+        const source = instance.position;
+
+        let dx = tx - source.x;
+        let dy = ty - source.y;
+        let dz = tz - source.z;
+
+        const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+        if (len === 0) {
+            return 1; // target at the source — radiation direction undefined
+        }
+
+        const inv = 1 / len;
+        dx *= inv;
+        dy *= inv;
+        dz *= inv;
+
+        // source forward in world space = local forward rotated by the source's orientation
+        FORWARD.copy(Vector3.forward);
+        FORWARD.applyQuaternion(instance.orientation);
+
+        return instance.directivity.gain(FORWARD.x * dx + FORWARD.y * dy + FORWARD.z * dz);
+    }
+
+    /**
+     * Fill `solution.directivityGain` — the source's radiation toward the LISTENER (the direct path).
+     * @param {AcousticSolution} solution (occlusion already solved; `directivityGain` written)
+     * @param {EventInstance} instance the source — position + orientation + directivity
+     * @param {Vector3} listener
+     */
+    #applyDirectivity(solution, instance, listener) {
+        solution.directivityGain = this.#directivityGainToward(instance, listener.x, listener.y, listener.z);
+    }
+
+    /**
+     * Drop a live instance's accumulated state (call when the instance ends).
+     * @param {EventInstance} instance
+     */
+    forget(instance) {
+        const id = this.#stateIds.get(instance);
+
+        if (id !== undefined) {
+            this.#statePool.release(id);
+            this.#stateIds.delete(instance);
+        }
+    }
+}