@woosh/meep-engine 2.163.10 → 2.164.0

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

@@ -0,0 +1,574 @@
+import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
+import {
+    bvh_query_user_data_nearest_to_point
+} from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_nearest_to_point.js";
+import {
+    bvh_query_user_data_intersects_sphere
+} from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_sphere.js";
+import {
+    bvh_query_user_data_nearest_to_point_filtered
+} from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_nearest_to_point_filtered.js";
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { csr_graph_find_shortest_path } from "../../../../core/graph/csr/csr_graph_find_shortest_path.js";
+import { acoustic_probe_transfer, LOBE_STRIDE } from "./acoustic_probe_transfer.js";
+
+// Probe layout in #data: STRIDE float32s per probe — position, per-band reverb RT60, per-band arrival dir.
+const STRIDE = 15;
+const OFFSET_X = 0;
+const OFFSET_Y = 1;
+const OFFSET_Z = 2;
+const OFFSET_REVERB = 3;    // per-band RT60 (seconds): band b at OFFSET_REVERB + b              — 3 floats
+const OFFSET_DIRECTION = 6; // per-band arrival direction (xyz): band b at OFFSET_DIRECTION + b*3 — 9 floats
+
+// passed as the lobe store for a probe with no lobes baked — never indexed (count 0), but keeps a real array
+// off the transfer call rather than null
+const EMPTY_LOBES = new Float32Array(0);
+
+// initial probe capacity of a fresh field's backing array
+const DEFAULT_CAPACITY = 8;
+
+// module scratch for a point-leaf AABB during BVH build
+const LEAF_BOUNDS = new Float32Array(6);
+
+// module scratch — the query→probe line-of-sight ray for nearestVisibleIndex
+const VISIBILITY_RAY = new Ray3();
+
+/**
+ * The baked probe volume: the set of acoustic probes covering a scene, plus the connectivity between them.
+ * Carries everything an offline bake produces about the field and everything the runtime reads back from
+ * it — per-band reverb, BVH nearest-probe lookup, and (optionally) the probe-visibility graph that sound
+ * routes through. Serializable (the bake is offline; the field loads as an asset). Pure data + graph
+ * search; no WebAudio.
+ *
+ * Probe data lives in a flat {@link Float32Array} ({@link STRIDE} floats per probe: x, y, z, per-band
+ * reverbDecay, per-band arrival direction) indexed by `i*STRIDE` — no per-probe object, no table
+ * indirection. The per-band arrival direction is the FOA / first-order anisotropy vector a directional
+ * reverb renderer steers the wet field by. Nearest-probe lookup is
+ * BVH-accelerated: a {@link BVH} over the probe points (leaf user-data = probe index) is built lazily and
+ * queried with {@link bvh_query_user_data_nearest_to_point}, so a per-frame listener query is O(log n)
+ * rather than a full scan.
+ *
+ * Connectivity is an inherent property of the field: once `bakeVisibility` has connected the probes with
+ * mutual line-of-sight ({@link setVisibilityGraph}), {@link shortestPath} routes sound around obstacles —
+ * through doorways and around corners — independent of walkability (air-visibility, not a navmesh). The
+ * mutable, per-listener exit-field solve lives in a separate {@link ProbeFieldPathingSolution} — this baked
+ * field stays immutable data + the graph it owns.
+ */
+export class AcousticProbeField {
+    /**
+     * Flat probe storage, {@link STRIDE} float32s per probe:
+     * `[x, y, z, reverbLow, reverbMid, reverbHigh, dirLowXYZ, dirMidXYZ, dirHighXYZ]`.
+     * Probe `i` occupies `[i*STRIDE … i*STRIDE + STRIDE)`. Backing length is the capacity, not the size.
+     * @type {Float32Array}
+     */
+    #data = new Float32Array(DEFAULT_CAPACITY * STRIDE);
+
+    /**
+     * Number of probes (distinct from the backing array's length).
+     * @type {number}
+     */
+    #size = 0;
+
+    /**
+     * Nearest-lookup acceleration over the probe points; rebuilt lazily after the field changes.
+     * @type {BVH}
+     */
+    #bvh = new BVH();
+
+    /**
+     * Whether {@link #bvh} reflects the current probes (false after a position change).
+     * @type {boolean}
+     */
+    #bvhValid = false;
+
+    /**
+     * Probe-visibility adjacency for pathing: vertex v = probe v, edge = mutual line-of-sight, edge weight =
+     * inter-probe distance. Baked by `bakeVisibility` and attached via {@link setVisibilityGraph}; null
+     * until then — a field without connectivity still serves reverb and nearest lookup.
+     * @type {CSRGraph|null}
+     */
+    #graph = null;
+
+    /**
+     * Per-probe reflector lobes for the directional TRANSFER (corner-leak gating), in CSR form:
+     * {@link #lobeOffsets}`[v]…[v+1]` is probe v's lobe range in {@link #lobeData} (LOBE_STRIDE floats each).
+     * Baked by `bakeProbeReflectors` and attached via {@link setLobes}; both null until then (a field without
+     * transfer routes with the forward/passthrough term only). Like the visibility graph, a bake product —
+     * NOT serialized; re-bake after load.
+     * @type {Uint32Array|null}
+     */
+    #lobeOffsets = null;
+
+    /**
+     * Flat lobe storage (LOBE_STRIDE floats per lobe), indexed via {@link #lobeOffsets}. Null until baked.
+     * @type {Float32Array|null}
+     */
+    #lobeData = null;
+
+    /**
+     * @returns {number} number of probes
+     */
+    get size() {
+        return this.#size;
+    }
+
+    /**
+     * Whether a visibility graph has been baked into this field (i.e. pathing is available).
+     * @returns {boolean}
+     */
+    get hasVisibility() {
+        return this.#graph !== null;
+    }
+
+    /**
+     * The baked probe-visibility graph, or null if none has been baked. The substrate that
+     * {@link shortestPath} and a {@link ProbeFieldPathingSolution} search.
+     * @returns {CSRGraph|null}
+     */
+    get visibilityGraph() {
+        return this.#graph;
+    }
+
+    /**
+     * Whether reflector lobes (the directional transfer) have been baked into this field.
+     * @returns {boolean}
+     */
+    get hasTransfer() {
+        return this.#lobeOffsets !== null;
+    }
+
+    /**
+     * Number of reflector lobes baked for probe `i` (0 if no transfer is baked, or an open-air probe).
+     * @param {number} i probe index
+     * @returns {number}
+     */
+    probeLobeCount(i) {
+        return this.#lobeOffsets === null ? 0 : this.#lobeOffsets[i + 1] - this.#lobeOffsets[i];
+    }
+
+    /**
+     * Grow {@link #data} so it can hold at least `probeCount` probes, preserving existing contents (the new
+     * tail is zero-initialised). Geometric growth keeps incremental appends amortized O(1).
+     * @param {number} probeCount
+     */
+    #ensureCapacity(probeCount) {
+        const needed = probeCount * STRIDE;
+
+        if (needed <= this.#data.length) {
+            return;
+        }
+
+        let capacity = this.#data.length;
+        do {
+            capacity = Math.max(capacity * 2, DEFAULT_CAPACITY * STRIDE);
+        } while (capacity < needed);
+
+        const grown = new Float32Array(capacity);
+        grown.set(this.#data);
+        this.#data = grown;
+    }
+
+    /**
+     * Set probe `index`'s position. When `index === size` this APPENDS a new probe (zero reverb + zero
+     * direction) — so a field is built by writing indices 0, 1, 2, … in order; when `index < size` it moves
+     * an existing probe. Either way the nearest-lookup BVH is invalidated (positions changed).
+     * PRECONDITION: 0 ≤ index ≤ size.
+     * @param {number} index
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    setProbePosition(index, x, y, z) {
+        if (index === this.#size) {
+            this.#ensureCapacity(this.#size + 1);
+            this.#size++;
+
+            // a freshly appended probe starts with zero reverb + zero direction (the appended-row contract)
+            const base = index * STRIDE;
+            for (let k = OFFSET_REVERB; k < STRIDE; k++) {
+                this.#data[base + k] = 0;
+            }
+        }
+
+        const base = index * STRIDE;
+        const data = this.#data;
+
+        data[base + OFFSET_X] = x;
+        data[base + OFFSET_Y] = y;
+        data[base + OFFSET_Z] = z;
+
+        this.#bvhValid = false;
+    }
+
+    /**
+     * Set probe `index`'s per-band reverb decay (seconds). Does not move the probe, so the BVH is
+     * untouched.
+     * PRECONDITION: 0 ≤ index < size.
+     * @param {number} index
+     * @param {number} low
+     * @param {number} mid
+     * @param {number} high
+     */
+    setProbeReverbDecay(index, low, mid, high) {
+        const base = index * STRIDE + OFFSET_REVERB;
+        const data = this.#data;
+
+        data[base] = low;
+        data[base + 1] = mid;
+        data[base + 2] = high;
+    }
+
+    /**
+     * Set probe `index`'s per-band arrival direction (the FOA anisotropy vectors, band-major xyz, length 9:
+     * `[lowX,lowY,lowZ, midX,midY,midZ, highX,highY,highZ]`). Each band's magnitude is 0…1 (0 = diffuse,
+     * →1 = strongly directional). Does not move the probe, so the BVH is untouched.
+     * PRECONDITION: 0 ≤ index < size.
+     * @param {number} index
+     * @param {Float32Array|number[]} directions band-major xyz, length 9
+     */
+    setProbeReverbDirections(index, directions) {
+        const base = index * STRIDE + OFFSET_DIRECTION;
+        const data = this.#data;
+
+        for (let k = 0; k < 9; k++) {
+            data[base + k] = directions[k];
+        }
+    }
+
+    /**
+     * @param {number} i probe index
+     * @returns {number}
+     */
+    probeX(i) {
+        return this.#data[i * STRIDE + OFFSET_X];
+    }
+
+    /**
+     * @param {number} i probe index
+     * @returns {number}
+     */
+    probeY(i) {
+        return this.#data[i * STRIDE + OFFSET_Y];
+    }
+
+    /**
+     * @param {number} i probe index
+     * @returns {number}
+     */
+    probeZ(i) {
+        return this.#data[i * STRIDE + OFFSET_Z];
+    }
+
+    /**
+     * Per-band baked RT60 (seconds) of probe `i`.
+     * @param {number} i probe index
+     * @param {number} band 0 = low, 1 = mid, 2 = high
+     * @returns {number}
+     */
+    reverbBand(i, band) {
+        return this.#data[i * STRIDE + OFFSET_REVERB + band];
+    }
+
+    /**
+     * Per-band arrival direction of probe `i` (xyz) written into `out`. Magnitude 0…1 (0 = diffuse, →1 =
+     * the reverb arrives predominantly from this direction).
+     * @param {number} i probe index
+     * @param {number} band 0 = low, 1 = mid, 2 = high
+     * @param {Float32Array|number[]} out at least length 3
+     */
+    reverbDirection(i, band, out) {
+        const base = i * STRIDE + OFFSET_DIRECTION + band * 3;
+        const data = this.#data;
+
+        out[0] = data[base];
+        out[1] = data[base + 1];
+        out[2] = data[base + 2];
+    }
+
+    /**
+     * Broadband baked RT60 (seconds) of probe `i` — the mean of its three bands (the scalar render path).
+     * @param {number} i probe index
+     * @returns {number}
+     */
+    reverbDecay(i) {
+        return (this.reverbBand(i, 0) + this.reverbBand(i, 1) + this.reverbBand(i, 2)) / 3;
+    }
+
+    /**
+     * Index of the nearest probe to a world point, or -1 if the field is empty.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {number}
+     */
+    nearestIndex(x, y, z) {
+        this.#ensureBVH();
+        return bvh_query_user_data_nearest_to_point(this.#bvh, x, y, z);
+    }
+
+    /**
+     * Index of the nearest probe a world point can SEE — line-of-sight unobstructed by `occluderIndex` — or
+     * -1 if the field is empty or NO probe is visible. Unlike {@link nearestIndex} this never snaps to a
+     * probe behind a wall or below a floor (a different acoustic region), which would make a runtime
+     * listener/source route a spurious cross-occluder detour through the visibility graph (or find none). The
+     * runtime pathing snaps with this. Cost: the branch-and-bound nearest search with one visibility raycast
+     * per leaf nearer than the current best — typically one or two, since the nearest probe is usually
+     * visible.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {AcousticOccluderIndex} occluderIndex the scene line-of-sight is tested against
+     * @returns {number} nearest visible probe index, or -1
+     */
+    nearestVisibleIndex(x, y, z, occluderIndex) {
+        this.#ensureBVH();
+
+        const data = this.#data;
+
+        return bvh_query_user_data_nearest_to_point_filtered(this.#bvh, x, y, z, (probeIndex) => {
+            const base = probeIndex * STRIDE;
+            const dx = data[base + OFFSET_X] - x;
+            const dy = data[base + OFFSET_Y] - y;
+            const dz = data[base + OFFSET_Z] - z;
+
+            const d = Math.sqrt(dx * dx + dy * dy + dz * dz);
+            if (d === 0) {
+                return true; // the query point coincides with the probe — trivially visible
+            }
+
+            const inv = 1 / d;
+            VISIBILITY_RAY.setOrigin(x, y, z);
+            VISIBILITY_RAY.setDirection(dx * inv, dy * inv, dz * inv);
+            VISIBILITY_RAY.tMax = d;
+
+            return !occluderIndex.anyHit(VISIBILITY_RAY);
+        });
+    }
+
+    /**
+     * Indices of all probes within `radius` of a world point, written into `result` starting at
+     * `result_offset`; returns how many were written. Built on the same nearest-lookup BVH — used by the
+     * visibility-graph bake to find spatially-local candidate pairs (island bridging, shortcut augmentation)
+     * without an all-pairs scan. The probe leaves are points, so a hit means centre-within-radius (the BVH
+     * may return a few extra near the boundary; re-test the exact distance if you need a hard cutoff).
+     * PRECONDITION: `result` has room for the local probe count near the query (size it to the field's
+     * densest neighbourhood).
+     * @param {number[]|Uint32Array} result
+     * @param {number} result_offset
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} radius
+     * @returns {number} number of probe indices written
+     */
+    probesWithinRadius(result, result_offset, x, y, z, radius) {
+        this.#ensureBVH();
+        return bvh_query_user_data_intersects_sphere(result, result_offset, this.#bvh, x, y, z, radius);
+    }
+
+    /**
+     * Broadband reverb decay (seconds) at a world point — the nearest probe's mean RT60, or 0 if no
+     * probes.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {number}
+     */
+    reverbDecayAt(x, y, z) {
+        const i = this.nearestIndex(x, y, z);
+        return i === -1 ? 0 : this.reverbDecay(i);
+    }
+
+    /**
+     * Per-band reverb decay (seconds) at a world point — the nearest probe's `[low, mid, high]` RT60s
+     * written into `out`, or all-zero if no probes.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {Float32Array|number[]} out at least length 3
+     */
+    reverbBandsAt(x, y, z, out) {
+        const i = this.nearestIndex(x, y, z);
+
+        if (i === -1) {
+            out[0] = 0;
+            out[1] = 0;
+            out[2] = 0;
+            return;
+        }
+
+        out[0] = this.reverbBand(i, 0);
+        out[1] = this.reverbBand(i, 1);
+        out[2] = this.reverbBand(i, 2);
+    }
+
+    /**
+     * Per-band arrival directions at a world point — the nearest probe's 9 floats (band-major xyz) written
+     * into `out`, or all-zero if no probes.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {Float32Array|number[]} out at least length 9
+     */
+    reverbDirectionsAt(x, y, z, out) {
+        const i = this.nearestIndex(x, y, z);
+
+        if (i === -1) {
+            for (let k = 0; k < 9; k++) {
+                out[k] = 0;
+            }
+            return;
+        }
+
+        const base = i * STRIDE + OFFSET_DIRECTION;
+        const data = this.#data;
+
+        for (let k = 0; k < 9; k++) {
+            out[k] = data[base + k];
+        }
+    }
+
+    /**
+     * (Re)build the nearest-lookup BVH from the probes — each probe a point leaf carrying its index as user
+     * data. Lazy: the runtime pays once after a bake/load, not per query.
+     */
+    #ensureBVH() {
+        if (this.#bvhValid) {
+            return;
+        }
+
+        const bvh = new BVH();
+        const data = this.#data;
+        const n = this.#size;
+
+        for (let i = 0; i < n; i++) {
+            const base = i * STRIDE;
+            const x = data[base + OFFSET_X];
+            const y = data[base + OFFSET_Y];
+            const z = data[base + OFFSET_Z];
+
+            LEAF_BOUNDS[0] = LEAF_BOUNDS[3] = x;
+            LEAF_BOUNDS[1] = LEAF_BOUNDS[4] = y;
+            LEAF_BOUNDS[2] = LEAF_BOUNDS[5] = z;
+
+            const node = bvh.allocate_node();
+            bvh.node_set_aabb(node, LEAF_BOUNDS);
+            bvh.node_set_user_data(node, i);
+            bvh.insert_leaf(node);
+        }
+
+        this.#bvh = bvh;
+        this.#bvhValid = true;
+    }
+
+    /**
+     * Attach the baked probe-visibility graph (from `bakeVisibility`), enabling {@link shortestPath} and
+     * {@link ProbeFieldPathingSolution}.
+     * PRECONDITION: the graph's vertex set is this field's probes (vertex v = probe v); bake it AFTER the
+     * field's probes are final.
+     * @param {CSRGraph} graph visibility adjacency over this field's probes
+     */
+    setVisibilityGraph(graph) {
+        this.#graph = graph;
+    }
+
+    /**
+     * Attach the baked reflector lobes (from `bakeProbeReflectors`), enabling {@link probeTransfer}.
+     * PRECONDITION: `offsets` has length `size + 1` (probe v's lobes are `offsets[v]…offsets[v+1]`) and `data`
+     * holds `offsets[size]` lobes (LOBE_STRIDE floats each). Bake AFTER the probes are final.
+     * @param {Uint32Array} offsets per-probe lobe-range offsets (length size+1)
+     * @param {Float32Array} data flat lobe array
+     */
+    setLobes(offsets, data) {
+        this.#lobeOffsets = offsets;
+        this.#lobeData = data;
+    }
+
+    /**
+     * The directional transfer T(ω_in, ω_out) at probe `i`, per band, written into `out[0..2]` (see
+     * {@link acoustic_probe_transfer}). With no lobes baked (or an open-air probe) it is the forward /
+     * passthrough term alone. Directions are unit PROPAGATION directions.
+     * @param {Float32Array|number[]} out length ≥ 3
+     * @param {number} i probe index
+     * @param {number} inx @param {number} iny @param {number} inz   ω_in
+     * @param {number} outx @param {number} outy @param {number} outz ω_out
+     */
+    probeTransfer(out, i, inx, iny, inz, outx, outy, outz) {
+        const offsets = this.#lobeOffsets;
+        const start = offsets === null ? 0 : offsets[i];
+        const count = offsets === null ? 0 : offsets[i + 1] - start;
+
+        acoustic_probe_transfer(out, this.#lobeData ?? EMPTY_LOBES, start * LOBE_STRIDE, count, inx, iny, inz, outx, outy, outz);
+    }
+
+    /**
+     * Shortest path (Dijkstra) from probe `from` to probe `to`, as a list of probe indices (inclusive of
+     * both ends), or null if they are not connected.
+     * PRECONDITION: a visibility graph is attached ({@link hasVisibility}).
+     * @param {number} from
+     * @param {number} to
+     * @returns {number[]|null}
+     */
+    shortestPath(from, to) {
+        const path = [];
+
+        const count = csr_graph_find_shortest_path(path, 0, this.#graph, from, to);
+
+        return count === -1 ? null : path;
+    }
+
+    toJSON() {
+        const data = this.#data;
+        const probes = [];
+
+        for (let i = 0; i < this.#size; i++) {
+            const base = i * STRIDE;
+
+            const reverbDirection = [];
+            for (let k = 0; k < 9; k++) {
+                reverbDirection.push(data[base + OFFSET_DIRECTION + k]);
+            }
+
+            probes.push({
+                x: data[base + OFFSET_X],
+                y: data[base + OFFSET_Y],
+                z: data[base + OFFSET_Z],
+                reverbDecay: [
+                    data[base + OFFSET_REVERB],
+                    data[base + OFFSET_REVERB + 1],
+                    data[base + OFFSET_REVERB + 2]
+                ],
+                reverbDirection
+            });
+        }
+
+        return { probes };
+    }
+
+    /**
+     * Replace this field's probes from serialized form. The visibility graph is NOT serialized (re-bake it
+     * with `bakeVisibility` after loading), so any prior graph is dropped.
+     * @param {{probes:{x:number,y:number,z:number,reverbDecay:number[],reverbDirection:number[]}[]}} json
+     */
+    fromJSON(json) {
+        const probes = json.probes;
+        const n = probes.length;
+
+        this.#data = new Float32Array(Math.max(n, DEFAULT_CAPACITY) * STRIDE);
+        this.#size = 0;
+        this.#bvhValid = false;
+        this.#graph = null;
+        this.#lobeOffsets = null;
+        this.#lobeData = null;
+
+        for (let i = 0; i < n; i++) {
+            const p = probes[i];
+            const r = p.reverbDecay;
+            this.setProbePosition(i, p.x, p.y, p.z);
+            this.setProbeReverbDecay(i, r[0], r[1], r[2]);
+            this.setProbeReverbDirections(i, p.reverbDirection);
+        }
+    }
+}
+
+AcousticProbeField.typeName = "AcousticProbeField";

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

@@ -0,0 +1,24 @@
+/**
+ * Binary (de)serialization for the baked {@link AcousticProbeField} component: the probe count, then each
+ * probe's position, per-band reverb RT60, and per-band arrival direction (the same data its `toJSON`
+ * persists). The visibility graph is NOT serialized — re-bake it with `bakeVisibility` after loading
+ * (matching `fromJSON`). Deserialization assumes a freshly-constructed value (probes appended in order).
+ */
+export class AcousticProbeFieldSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof AcousticProbeField;
+    version: number;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {AcousticProbeField} value
+     */
+    serialize(buffer: BinaryBuffer, value: AcousticProbeField): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {AcousticProbeField} value mutated in place (assumed freshly constructed)
+     */
+    deserialize(buffer: BinaryBuffer, value: AcousticProbeField): void;
+}
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { AcousticProbeField } from "./AcousticProbeField.js";
+//# sourceMappingURL=AcousticProbeFieldSerializationAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AcousticProbeFieldSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/AcousticProbeFieldSerializationAdapter.js"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH;;IACI,iCAA2B;IAC3B,gBAAY;IAEZ;;;OAGG;IACH,uCAFW,kBAAkB,QAsB5B;IAED;;;OAGG;IACH,yCAFW,kBAAkB,QAc5B;CACJ;gDA3D+C,gEAAgE;mCAC7E,yBAAyB"}

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

@@ -0,0 +1,60 @@
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { AcousticProbeField } from "./AcousticProbeField.js";
+
+// module scratch — one probe's per-band arrival directions (band-major xyz) during (de)serialization
+const DIRECTIONS = new Float32Array(9);
+
+/**
+ * Binary (de)serialization for the baked {@link AcousticProbeField} component: the probe count, then each
+ * probe's position, per-band reverb RT60, and per-band arrival direction (the same data its `toJSON`
+ * persists). The visibility graph is NOT serialized — re-bake it with `bakeVisibility` after loading
+ * (matching `fromJSON`). Deserialization assumes a freshly-constructed value (probes appended in order).
+ */
+export class AcousticProbeFieldSerializationAdapter extends BinaryClassSerializationAdapter {
+    klass = AcousticProbeField;
+    version = 0;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {AcousticProbeField} value
+     */
+    serialize(buffer, value) {
+        const size = value.size;
+        buffer.writeUintVar(size);
+
+        for (let i = 0; i < size; i++) {
+            buffer.writeFloat32(value.probeX(i));
+            buffer.writeFloat32(value.probeY(i));
+            buffer.writeFloat32(value.probeZ(i));
+
+            buffer.writeFloat32(value.reverbBand(i, 0));
+            buffer.writeFloat32(value.reverbBand(i, 1));
+            buffer.writeFloat32(value.reverbBand(i, 2));
+
+            for (let band = 0; band < 3; band++) {
+                value.reverbDirection(i, band, DIRECTIONS);
+                buffer.writeFloat32(DIRECTIONS[0]);
+                buffer.writeFloat32(DIRECTIONS[1]);
+                buffer.writeFloat32(DIRECTIONS[2]);
+            }
+        }
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {AcousticProbeField} value mutated in place (assumed freshly constructed)
+     */
+    deserialize(buffer, value) {
+        const size = buffer.readUintVar();
+
+        for (let i = 0; i < size; i++) {
+            value.setProbePosition(i, buffer.readFloat32(), buffer.readFloat32(), buffer.readFloat32());
+            value.setProbeReverbDecay(i, buffer.readFloat32(), buffer.readFloat32(), buffer.readFloat32());
+
+            for (let k = 0; k < 9; k++) {
+                DIRECTIONS[k] = buffer.readFloat32();
+            }
+            value.setProbeReverbDirections(i, DIRECTIONS);
+        }
+    }
+}