@woosh/meep-engine 2.163.11 → 2.165.0

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

@@ -0,0 +1,90 @@
+/**
+ * The per-source result of one simulation tick — what the render seam (`EventInstance.setAcoustic`)
+ * consumes. A reusable container: the system holds one per live instance and the solvers write into it.
+ *
+ * Pure data; no WebAudio. `occlusion` + `transmission` come from the {@link OcclusionSolver}; `airLoss`
+ * comes from the {@link VolumeField} (integrated over the source→listener path).
+ */
+export class AcousticSolution {
+    /**
+     * Fraction of the source occluded by geometry, [0, 1]. 0 = clear line of sight, 1 = fully blocked.
+     * @type {number}
+     */
+    occlusion = 0;
+
+    /**
+     * Per-band (low/mid/high) fraction of energy that LEAKS through the occluder(s), [0, 1]. Only
+     * meaningful when `occlusion > 0`. 1 = transparent.
+     * @type {Float32Array}
+     */
+    transmission = new Float32Array([1, 1, 1]);
+
+    /**
+     * Per-band (low/mid/high) air absorption integrated over the source→listener path, in **total dB** of
+     * attenuation (0 = transparent). Highs accumulate faster than lows, so distant sources lose their top
+     * end while the low end carries. Rendered as a low-anchored spectral tilt (the high-vs-low excess), so
+     * it composes with — rather than competes with — the authored distance attenuation curve.
+     * @type {Float32Array}
+     */
+    airLoss = new Float32Array([0, 0, 0]);
+
+    /**
+     * Whether a propagation path to the listener exists (corner-leakage). Only set when engine-wide
+     * pathing is on; when true, the leaked sound is spatialized from the exit point below.
+     * @type {boolean}
+     */
+    hasPath = false;
+
+    /**
+     * Exit-point world position `[x, y, z]` — where the leaked sound emerges toward the listener (the
+     * path's last probe before the listener). Only meaningful when `hasPath`.
+     * @type {Float32Array}
+     */
+    exit = new Float32Array(3);
+
+    /**
+     * Linear gain of the leaked (path) signal, [0, 1]. Grows with occlusion (the more the direct path is
+     * blocked, the more the sound arrives via the path) and falls with path length. Already folded with the
+     * source's radiation toward the leak's first hop (directivity-on-leak). Only meaningful when `hasPath`.
+     * @type {number}
+     */
+    pathGain = 0;
+
+    /**
+     * Per-band air absorption integrated over the LEAKED route (source→…→exit→listener), in total dB — the
+     * leak travels a longer path than the direct line, so it darkens more. Rendered as a low-anchored tilt on
+     * the leak send. Only meaningful when `hasPath`.
+     * @type {Float32Array}
+     */
+    pathAirLoss = new Float32Array([0, 0, 0]);
+
+    /**
+     * Source-radiation directivity gain on the DIRECT path, ≥ 0 (1 = omnidirectional / no directivity).
+     * How much the source radiates toward the listener given where it faces (the {@link AcousticDirectivity}
+     * pattern). Multiplies the direct-path gain at the render seam.
+     * @type {number}
+     */
+    directivityGain = 1;
+
+    /**
+     * Reset to the "no effect" state (clear, transparent, vacuum, no path, omni radiation).
+     */
+    reset() {
+        this.occlusion = 0;
+        this.transmission[0] = 1;
+        this.transmission[1] = 1;
+        this.transmission[2] = 1;
+        this.airLoss[0] = 0;
+        this.airLoss[1] = 0;
+        this.airLoss[2] = 0;
+        this.hasPath = false;
+        this.exit[0] = 0;
+        this.exit[1] = 0;
+        this.exit[2] = 0;
+        this.pathGain = 0;
+        this.pathAirLoss[0] = 0;
+        this.pathAirLoss[1] = 0;
+        this.pathAirLoss[2] = 0;
+        this.directivityGain = 1;
+    }
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Number of float32 words in one per-source state record: `[occlusion, transmission_low,
+ * transmission_mid, transmission_high, initialized]`. Exported so a pool can be sized for it.
+ * @type {number}
+ */
+export const ACOUSTIC_SOURCE_STATE_FLOATS: number;
+/**
+ * Transient per-source accumulation for the {@link OcclusionSolver}. Holds the temporally-smoothed
+ * occlusion + transmission so that (a) a low per-tick ray count integrates over frames, and (b) the
+ * result does not flicker as the (jittered) ray set changes frame-to-frame.
+ *
+ * A **flyweight**: the record is just {@link ACOUSTIC_SOURCE_STATE_FLOATS} floats, and an instance is a
+ * cursor over a backing float view. By default it owns a tiny standalone buffer (handy for direct use
+ * and tests); {@link rebind} re-points it at a record inside a shared pool so ONE reusable cursor can
+ * serve many sources with no per-source object allocation — which matters when audio events are highly
+ * transient (e.g. automatic fire spraying shot + impact one-shots).
+ *
+ * Runtime-only, never serialized.
+ */
+export class AcousticSourceState {
+    /**
+     * Re-point this cursor at a record inside a shared float view. The pool may reallocate its buffer on
+     * growth, so callers pass the CURRENT view each time.
+     * @param {Float32Array} data backing float view (e.g. `BinaryElementPool.data_float32`)
+     * @param {number} word float-word offset of the record
+     */
+    rebind(data: Float32Array, word: number): void;
+    /**
+     * Smoothed occlusion, [0, 1].
+     * @returns {number}
+     */
+    get occlusion(): number;
+    /**
+     * Fold an instantaneous measurement into the smoothed record with an exponential moving average. The
+     * FIRST measurement snaps (no ramp from cold) so a source that appears already behind a wall is
+     * occluded immediately rather than fading in.
+     *
+     * @param {number} occlusion instantaneous occlusion this tick
+     * @param {Float32Array|Float64Array|number[]} transmission instantaneous per-band transmission this tick
+     * @param {number} alpha EMA factor in (0, 1] — 1 = no smoothing, smaller = smoother/slower
+     */
+    integrate(occlusion: number, transmission: Float32Array | Float64Array | number[], alpha: number): void;
+    /**
+     * Copy the smoothed accumulator into an {@link AcousticSolution}.
+     * @param {AcousticSolution} out
+     */
+    writeTo(out: AcousticSolution): void;
+    /**
+     * Clear the bound record to the cold state (uninitialised → the next {@link integrate} snaps). Must be
+     * called on a freshly-allocated pool record, whose bytes may be stale from a prior occupant.
+     */
+    reset(): void;
+    #private;
+}
+//# sourceMappingURL=AcousticSourceState.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AcousticSourceState.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/core/AcousticSourceState.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,2CAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;GAYG;AACH;IAaI;;;;;OAKG;IACH,aAHW,YAAY,QACZ,MAAM,QAKhB;IAED;;;OAGG;IACH,wBAEC;IAED;;;;;;;;OAQG;IACH,qBAJW,MAAM,gBACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,SAClC,MAAM,QAmBhB;IAED;;;OAGG;IACH,qCAQC;IAED;;;OAGG;IACH,cASC;;CACJ"}

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

@@ -0,0 +1,109 @@
+/**
+ * Number of float32 words in one per-source state record: `[occlusion, transmission_low,
+ * transmission_mid, transmission_high, initialized]`. Exported so a pool can be sized for it.
+ * @type {number}
+ */
+export const ACOUSTIC_SOURCE_STATE_FLOATS = 5;
+
+/**
+ * Transient per-source accumulation for the {@link OcclusionSolver}. Holds the temporally-smoothed
+ * occlusion + transmission so that (a) a low per-tick ray count integrates over frames, and (b) the
+ * result does not flicker as the (jittered) ray set changes frame-to-frame.
+ *
+ * A **flyweight**: the record is just {@link ACOUSTIC_SOURCE_STATE_FLOATS} floats, and an instance is a
+ * cursor over a backing float view. By default it owns a tiny standalone buffer (handy for direct use
+ * and tests); {@link rebind} re-points it at a record inside a shared pool so ONE reusable cursor can
+ * serve many sources with no per-source object allocation — which matters when audio events are highly
+ * transient (e.g. automatic fire spraying shot + impact one-shots).
+ *
+ * Runtime-only, never serialized.
+ */
+export class AcousticSourceState {
+    /**
+     * Backing float view. Standalone by default; a pool's `data_float32` after {@link rebind}.
+     * @type {Float32Array}
+     */
+    #data= new Float32Array(ACOUSTIC_SOURCE_STATE_FLOATS);
+
+    /**
+     * Float-word offset of this cursor's record within {@link #data}.
+     * @type {number}
+     */
+    #word = 0;
+
+    /**
+     * Re-point this cursor at a record inside a shared float view. The pool may reallocate its buffer on
+     * growth, so callers pass the CURRENT view each time.
+     * @param {Float32Array} data backing float view (e.g. `BinaryElementPool.data_float32`)
+     * @param {number} word float-word offset of the record
+     */
+    rebind(data, word) {
+        this.#data = data;
+        this.#word = word;
+    }
+
+    /**
+     * Smoothed occlusion, [0, 1].
+     * @returns {number}
+     */
+    get occlusion() {
+        return this.#data[this.#word];
+    }
+
+    /**
+     * Fold an instantaneous measurement into the smoothed record with an exponential moving average. The
+     * FIRST measurement snaps (no ramp from cold) so a source that appears already behind a wall is
+     * occluded immediately rather than fading in.
+     *
+     * @param {number} occlusion instantaneous occlusion this tick
+     * @param {Float32Array|Float64Array|number[]} transmission instantaneous per-band transmission this tick
+     * @param {number} alpha EMA factor in (0, 1] — 1 = no smoothing, smaller = smoother/slower
+     */
+    integrate(occlusion, transmission, alpha) {
+        const d = this.#data;
+        const w = this.#word;
+
+        if (d[w + 4] === 0) {
+            d[w] = occlusion;
+            d[w + 1] = transmission[0];
+            d[w + 2] = transmission[1];
+            d[w + 3] = transmission[2];
+            d[w + 4] = 1;
+            return;
+        }
+
+        d[w] += (occlusion - d[w]) * alpha;
+        d[w + 1] += (transmission[0] - d[w + 1]) * alpha;
+        d[w + 2] += (transmission[1] - d[w + 2]) * alpha;
+        d[w + 3] += (transmission[2] - d[w + 3]) * alpha;
+    }
+
+    /**
+     * Copy the smoothed accumulator into an {@link AcousticSolution}.
+     * @param {AcousticSolution} out
+     */
+    writeTo(out) {
+        const d = this.#data;
+        const w = this.#word;
+
+        out.occlusion = d[w];
+        out.transmission[0] = d[w + 1];
+        out.transmission[1] = d[w + 2];
+        out.transmission[2] = d[w + 3];
+    }
+
+    /**
+     * Clear the bound record to the cold state (uninitialised → the next {@link integrate} snaps). Must be
+     * called on a freshly-allocated pool record, whose bytes may be stale from a prior occupant.
+     */
+    reset() {
+        const d = this.#data;
+        const w = this.#word;
+
+        d[w] = 0;
+        d[w + 1] = 0;
+        d[w + 2] = 0;
+        d[w + 3] = 0;
+        d[w + 4] = 0;
+    }
+}

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

@@ -0,0 +1,45 @@
+/**
+ * One medium region for the {@link VolumeField}: a shape placed at a world position, carrying an
+ * {@link AcousticMedium}, with a `transition` band over which its influence fades at the boundary.
+ *
+ * ECS-agnostic — the `AcousticVolume` component (ECS) produces one of these from its shape + the
+ * entity's `Transform`. Pure geometry: no WebAudio.
+ *
+ * PRECONDITION: the shape is centred at its local origin and the region is axis-aligned (position only,
+ * no rotation in v1); rotated regions are a later refinement via a posed shape.
+ */
+export class AcousticVolumeRegion {
+    /**
+     * @param {AbstractShape3D} shape centred at the local origin (sphere, box, …)
+     * @param {Vector3} position world centre
+     * @param {number} transition boundary blend band, in metres (>= 0)
+     * @param {AcousticMedium} medium
+     */
+    constructor(shape: AbstractShape3D, position: Vector3, transition: number, medium: AcousticMedium);
+    /**
+     * @type {AbstractShape3D}
+     */
+    shape: AbstractShape3D;
+    /**
+     * @type {Vector3}
+     */
+    position: Vector3;
+    /**
+     * @type {number}
+     */
+    transition: number;
+    /**
+     * @type {AcousticMedium}
+     */
+    medium: AcousticMedium;
+    /**
+     * Blend weight of this region at a world point: 1 deep inside, 0 outside, smoothstep across the
+     * `transition` band just inside the surface.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {number} weight in [0, 1]
+     */
+    weightAt(x: number, y: number, z: number): number;
+}
+//# sourceMappingURL=AcousticVolumeRegion.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AcousticVolumeRegion.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/core/AcousticVolumeRegion.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH;IACI;;;;;OAKG;IACH,mEAHW,MAAM,0BAuBhB;IAnBG;;OAEG;IACH,uBAAkB;IAElB;;OAEG;IACH,kBAAwB;IAExB;;OAEG;IACH,YAFU,MAAM,CAEY;IAE5B;;OAEG;IACH,uBAAoB;IAGxB;;;;;;;OAOG;IACH,YALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAqBlB;CACJ"}

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

@@ -0,0 +1,73 @@
+import { smoothStep } from "../../../../core/math/smoothStep.js";
+
+// module-static scratch — the query point in the region's local frame. Reused; weightAt is synchronous.
+const LOCAL_POINT = [0, 0, 0];
+
+/**
+ * One medium region for the {@link VolumeField}: a shape placed at a world position, carrying an
+ * {@link AcousticMedium}, with a `transition` band over which its influence fades at the boundary.
+ *
+ * ECS-agnostic — the `AcousticVolume` component (ECS) produces one of these from its shape + the
+ * entity's `Transform`. Pure geometry: no WebAudio.
+ *
+ * PRECONDITION: the shape is centred at its local origin and the region is axis-aligned (position only,
+ * no rotation in v1); rotated regions are a later refinement via a posed shape.
+ */
+export class AcousticVolumeRegion {
+    /**
+     * @param {AbstractShape3D} shape centred at the local origin (sphere, box, …)
+     * @param {Vector3} position world centre
+     * @param {number} transition boundary blend band, in metres (>= 0)
+     * @param {AcousticMedium} medium
+     */
+    constructor(shape, position, transition, medium) {
+        /**
+         * @type {AbstractShape3D}
+         */
+        this.shape = shape;
+
+        /**
+         * @type {Vector3}
+         */
+        this.position = position;
+
+        /**
+         * @type {number}
+         */
+        this.transition = transition;
+
+        /**
+         * @type {AcousticMedium}
+         */
+        this.medium = medium;
+    }
+
+    /**
+     * Blend weight of this region at a world point: 1 deep inside, 0 outside, smoothstep across the
+     * `transition` band just inside the surface.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {number} weight in [0, 1]
+     */
+    weightAt(x, y, z) {
+        LOCAL_POINT[0] = x - this.position.x;
+        LOCAL_POINT[1] = y - this.position.y;
+        LOCAL_POINT[2] = z - this.position.z;
+
+        const sd = this.shape.signed_distance_at_point(LOCAL_POINT);
+
+        if (sd >= 0) {
+            return 0;
+        }
+
+        const transition = this.transition;
+
+        if (transition <= 0 || sd <= -transition) {
+            return 1;
+        }
+
+        // smoothstep across the band: 0 at the surface, 1 at the inner edge (transition metres in)
+        return smoothStep(0, transition, -sd);
+    }
+}

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

@@ -0,0 +1,57 @@
+/**
+ * One acoustic occluder in the {@link AcousticOccluderIndex}: an {@link AbstractShape3D} placed by a
+ * world transform, with an acoustic material. The shape owns its OWN exact raycast (closed-form for
+ * primitives, an internal BLAS for meshes); this record carries only the world placement (the forward
+ * matrix + its cached inverse, used to localise the query ray) and the world AABB (for the index's
+ * broadphase).
+ *
+ * The transform is **mandatory** — there is no "untransformed" special case; an occluder placed at the
+ * world origin simply carries an identity matrix. (Uniform control flow: every body localises the ray
+ * the same way.)
+ *
+ * PRECONDITION: the transform is rigid (rotation + translation, no scale), so a hit distance in the
+ * body's local frame equals the distance in world space, and rotating the local normal yields the world
+ * normal.
+ */
+export class OccluderBody {
+    /**
+     * @param {AbstractShape3D} shape geometry, in its canonical local frame
+     * @param {AcousticMaterial} material acoustic properties of the surface
+     * @param {Float32Array|number[]} matrix world transform (rigid)
+     */
+    constructor(shape: AbstractShape3D, material: AcousticMaterial, matrix: Float32Array | number[]);
+    /**
+     * @type {AbstractShape3D}
+     */
+    shape: AbstractShape3D;
+    /**
+     * @type {AcousticMaterial}
+     */
+    material: AcousticMaterial;
+    /**
+     * Forward world transform (column-major). Used to map a local hit point + normal back to world.
+     * @type {Float32Array}
+     */
+    matrix: Float32Array;
+    /**
+     * Cached inverse of {@link matrix} — localises the world query ray into the shape's frame.
+     * @type {Float32Array}
+     */
+    inverse: Float32Array;
+    /**
+     * Shape bounds in the local frame.
+     * @type {number[]}
+     */
+    localAABB: number[];
+    /**
+     * Local bounds transformed to world — the index's broadphase volume.
+     * @type {number[]}
+     */
+    worldAABB: number[];
+    /**
+     * Re-place the body. O(1) — recomputes the inverse + world bounds; the shape is untouched.
+     * @param {Float32Array|number[]} matrix world transform (rigid)
+     */
+    setTransform(matrix: Float32Array | number[]): void;
+}
+//# sourceMappingURL=OccluderBody.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"OccluderBody.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/core/OccluderBody.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH;IACI;;;;OAIG;IACH,wEAFW,YAAY,GAAC,MAAM,EAAE,EAuC/B;IApCG;;OAEG;IACH,uBAAkB;IAElB;;OAEG;IACH,2BAAwB;IAExB;;;OAGG;IACH,QAFU,YAAY,CAEY;IAElC;;;OAGG;IACH,SAFU,YAAY,CAEa;IAEnC;;;OAGG;IACH,WAFU,MAAM,EAAE,CAEiB;IAEnC;;;OAGG;IACH,WAFU,MAAM,EAAE,CAEiB;IAMvC;;;OAGG;IACH,qBAFW,YAAY,GAAC,MAAM,EAAE,QAO/B;CACJ"}

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

@@ -0,0 +1,74 @@
+import { aabb3_matrix4_project } from "../../../../core/geom/3d/aabb/aabb3_matrix4_project.js";
+import { m4_invert } from "../../../../core/geom/3d/mat4/m4_invert.js";
+
+/**
+ * One acoustic occluder in the {@link AcousticOccluderIndex}: an {@link AbstractShape3D} placed by a
+ * world transform, with an acoustic material. The shape owns its OWN exact raycast (closed-form for
+ * primitives, an internal BLAS for meshes); this record carries only the world placement (the forward
+ * matrix + its cached inverse, used to localise the query ray) and the world AABB (for the index's
+ * broadphase).
+ *
+ * The transform is **mandatory** — there is no "untransformed" special case; an occluder placed at the
+ * world origin simply carries an identity matrix. (Uniform control flow: every body localises the ray
+ * the same way.)
+ *
+ * PRECONDITION: the transform is rigid (rotation + translation, no scale), so a hit distance in the
+ * body's local frame equals the distance in world space, and rotating the local normal yields the world
+ * normal.
+ */
+export class OccluderBody {
+    /**
+     * @param {AbstractShape3D} shape geometry, in its canonical local frame
+     * @param {AcousticMaterial} material acoustic properties of the surface
+     * @param {Float32Array|number[]} matrix world transform (rigid)
+     */
+    constructor(shape, material, matrix) {
+        /**
+         * @type {AbstractShape3D}
+         */
+        this.shape = shape;
+
+        /**
+         * @type {AcousticMaterial}
+         */
+        this.material = material;
+
+        /**
+         * Forward world transform (column-major). Used to map a local hit point + normal back to world.
+         * @type {Float32Array}
+         */
+        this.matrix = new Float32Array(16);
+
+        /**
+         * Cached inverse of {@link matrix} — localises the world query ray into the shape's frame.
+         * @type {Float32Array}
+         */
+        this.inverse = new Float32Array(16);
+
+        /**
+         * Shape bounds in the local frame.
+         * @type {number[]}
+         */
+        this.localAABB = [0, 0, 0, 0, 0, 0];
+
+        /**
+         * Local bounds transformed to world — the index's broadphase volume.
+         * @type {number[]}
+         */
+        this.worldAABB = [0, 0, 0, 0, 0, 0];
+
+        shape.compute_bounding_box(this.localAABB);
+        this.setTransform(matrix);
+    }
+
+    /**
+     * Re-place the body. O(1) — recomputes the inverse + world bounds; the shape is untouched.
+     * @param {Float32Array|number[]} matrix world transform (rigid)
+     */
+    setTransform(matrix) {
+        this.matrix.set(matrix);
+        m4_invert(this.inverse, matrix);
+        // Arvo's O(1) AABB transform (worldAABB and localAABB are distinct arrays, as it requires).
+        aabb3_matrix4_project(this.worldAABB, this.localAABB, this.matrix);
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Computes per-source occlusion + transmission by shooting rays from the listener toward points spread
+ * over the source's sphere and counting how many are blocked by the {@link AcousticOccluderIndex}.
+ *
+ * - Volumetric (not boolean): occlusion is the FRACTION of blocked rays, so partially-hidden sources
+ *   attenuate smoothly instead of popping on/off.
+ * - Transmission: blocked rays accumulate their occluder's per-band transmission; the average is the
+ *   energy that leaks through.
+ * - Temporal: the fibonacci sample set is randomly re-oriented each tick (seeded), and the result is
+ *   folded into an {@link AcousticSourceState} via EMA — so a low per-tick ray count integrates over
+ *   frames and the output stays frame-stable.
+ *
+ * Pure: geometry in, numbers out. No WebAudio, no ECS, no allocation.
+ */
+export class OcclusionSolver {
+    /**
+     * @param {Vector3} listener listener world position
+     * @param {Vector3} source source world position
+     * @param {number} sourceRadius apparent radius of the source (0 = point source → boolean occlusion)
+     * @param {AcousticOccluderIndex} index
+     * @param {number} rayCount rays shot this tick (≥ 1)
+     * @param {number} smoothing EMA factor in (0, 1] — 1 = no smoothing
+     * @param {function():number} random seeded RNG; decorrelates the sample set per call
+     * @param {AcousticSourceState} state per-source temporal accumulation (mutated)
+     * @param {AcousticSolution} out occlusion + transmission written here (medium untouched)
+     */
+    solve(listener: Vector3, source: Vector3, sourceRadius: number, index: AcousticOccluderIndex, rayCount: number, smoothing: number, random: () => number, state: AcousticSourceState, out: AcousticSolution): void;
+}
+//# sourceMappingURL=OcclusionSolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"OcclusionSolver.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/core/OcclusionSolver.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;GAaG;AACH;IACI;;;;;;;;;;OAUG;IACH,wDARW,MAAM,0CAEN,MAAM,aACN,MAAM,gBACK,MAAM,2DAgF3B;CACJ"}

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

@@ -0,0 +1,119 @@
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { sphere_fibonacci_point } from "../../../../core/geom/3d/sphere/sphere_fibonacci_point.js";
+import { v3_matrix3_rotate } from "../../../../core/geom/vec3/v3_matrix3_rotate.js";
+import { v3_orthonormal_matrix_from_normal } from "../../../../core/geom/vec3/v3_orthonormal_matrix_from_normal.js";
+import { RayHit } from "./RayHit.js";
+
+// module-static scratch — reused across calls so a solve allocates nothing. Typed throughout (the
+// vectors carry direction cosines / band ratios, so Float64 native precision is free here).
+const RAY = new Ray3();
+const HIT = new RayHit();
+const FIBONACCI = new Float64Array(3);
+const DIRECTION = new Float64Array(3);
+const ROTATION = new Float64Array(9);
+const TRANSMISSION = new Float64Array(3);
+
+/**
+ * Computes per-source occlusion + transmission by shooting rays from the listener toward points spread
+ * over the source's sphere and counting how many are blocked by the {@link AcousticOccluderIndex}.
+ *
+ * - Volumetric (not boolean): occlusion is the FRACTION of blocked rays, so partially-hidden sources
+ *   attenuate smoothly instead of popping on/off.
+ * - Transmission: blocked rays accumulate their occluder's per-band transmission; the average is the
+ *   energy that leaks through.
+ * - Temporal: the fibonacci sample set is randomly re-oriented each tick (seeded), and the result is
+ *   folded into an {@link AcousticSourceState} via EMA — so a low per-tick ray count integrates over
+ *   frames and the output stays frame-stable.
+ *
+ * Pure: geometry in, numbers out. No WebAudio, no ECS, no allocation.
+ */
+export class OcclusionSolver {
+    /**
+     * @param {Vector3} listener listener world position
+     * @param {Vector3} source source world position
+     * @param {number} sourceRadius apparent radius of the source (0 = point source → boolean occlusion)
+     * @param {AcousticOccluderIndex} index
+     * @param {number} rayCount rays shot this tick (≥ 1)
+     * @param {number} smoothing EMA factor in (0, 1] — 1 = no smoothing
+     * @param {function():number} random seeded RNG; decorrelates the sample set per call
+     * @param {AcousticSourceState} state per-source temporal accumulation (mutated)
+     * @param {AcousticSolution} out occlusion + transmission written here (medium untouched)
+     */
+    solve(listener, source, sourceRadius, index, rayCount, smoothing, random, state, out) {
+        // a per-tick random orientation for the fibonacci set (decorrelation over frames)
+        const z = 2 * random() - 1;
+        const azimuth = 2 * Math.PI * random();
+        const ring = Math.sqrt(Math.max(0, 1 - z * z));
+
+        v3_orthonormal_matrix_from_normal(
+            ROTATION, 0,
+            ring * Math.cos(azimuth), ring * Math.sin(azimuth), z
+        );
+
+        const lx = listener.x;
+        const ly = listener.y;
+        const lz = listener.z;
+
+        const sx = source.x;
+        const sy = source.y;
+        const sz = source.z;
+
+        let blocked = 0;
+        let t0 = 0;
+        let t1 = 0;
+        let t2 = 0;
+
+        for (let i = 0; i < rayCount; i++) {
+            sphere_fibonacci_point(FIBONACCI, 0, i, rayCount);
+            v3_matrix3_rotate(DIRECTION, 0, FIBONACCI[0], FIBONACCI[1], FIBONACCI[2], ROTATION);
+
+            // a sample point spread over the source's sphere
+            const px = sx + DIRECTION[0] * sourceRadius;
+            const py = sy + DIRECTION[1] * sourceRadius;
+            const pz = sz + DIRECTION[2] * sourceRadius;
+
+            const dx = px - lx;
+            const dy = py - ly;
+            const dz = pz - lz;
+
+            const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+            if (distance <= 1e-6) {
+                // listener sitting on the source — treat as unoccluded for this ray
+                continue;
+            }
+
+            const inv = 1 / distance;
+
+            RAY.setOrigin(lx, ly, lz);
+            RAY.setDirection(dx * inv, dy * inv, dz * inv);
+            RAY.tMax = distance;
+
+            if (index.closestHit(RAY, HIT)) {
+                blocked++;
+
+                const transmission = HIT.material.transmission;
+                t0 += transmission[0];
+                t1 += transmission[1];
+                t2 += transmission[2];
+            }
+        }
+
+        const occlusion = blocked / rayCount;
+
+        // instantaneous transmission = average blocker transmission; transparent when nothing blocked
+        if (blocked > 0) {
+            const inv = 1 / blocked;
+            TRANSMISSION[0] = t0 * inv;
+            TRANSMISSION[1] = t1 * inv;
+            TRANSMISSION[2] = t2 * inv;
+        } else {
+            TRANSMISSION[0] = 1;
+            TRANSMISSION[1] = 1;
+            TRANSMISSION[2] = 1;
+        }
+
+        state.integrate(occlusion, TRANSMISSION, smoothing);
+        state.writeTo(out);
+    }
+}