@woosh/meep-engine 3.1.0 → 3.3.0

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

@@ -1,196 +1,196 @@
-import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
-import { probe_edge_visible } from "./probe_edge_visible.js";
-
-// Interior sample points along each candidate pair (the throat is the narrowest of these).
-const EDGE_SAMPLES = 6;
-// Gather candidate partners within this × minSpacing. The cover places probes at the SPARSEST up to
-// `maxSpacing` (= sparsenessRatio·minSpacing, default 4) apart, so the two probes flanking an opening — placed
-// at their room interiors, away from the low-clearance throat — can be a full maxSpacing apart. The gather
-// must span that, or a wide room's doorway is never tested. (The constriction + aperture screens reject the
-// extra far/in-room pairs this admits.)
-const DEFAULT_NEIGHBOR_RADIUS_FACTOR = 4;
-// A throat counts as a portal only if it is at least this much narrower than the MORE-open of its two rooms —
-// a real dip, not a flat open line. Loose on purpose: the genuine selectivity is the APERTURE gate (bounded on
-// opposing sides), so this only has to reject lines that never squeeze. (A doorway in a low room barely dips —
-// e.g. a 0.7 m jamb throat vs a 1.1 m floor-limited room is ratio 0.64 — so the bar must sit above that.)
-const DEFAULT_CONSTRICTION_FACTOR = 0.8;
-// …and only if the throat is at least this fraction of `minSpacing` wide (an SDF/half-width floor) — a
-// passable opening, not a polygon crack the visibility ray happened to thread.
-const DEFAULT_PORTAL_FLOOR_RATIO = 0.1;
-// Two throats within this × minSpacing are the same opening — keep the widest (most central) crossing.
-const DEDUP_RADIUS_FACTOR = 1.0;
-// An opening up to this × minSpacing wide is bounded within reach — how far an aperture ray looks for the far
-// jamb / opposing wall.
-const APERTURE_REACH_FACTOR = 2;
-// module-static scratch for the aperture rays
-const APERTURE_RAY = new Ray3();
-
-/**
- * Detect acoustic PORTALS — the throats of openings (door frames, windows, arches) — over a probe field's
- * positions. A portal is where a clear line of sight between two probes threads a CONSTRICTION: the two probes
- * sit in open rooms (high clearance) but the line between them squeezes through a narrow gap that is bounded by
- * solid on opposing sides (a doorway's jambs, a window's frame).
- *
- * Candidates are every nearby MUTUALLY-VISIBLE probe pair (a BVH radius gather), NOT just the baked visibility
- * edges — so an opening is found whether or not the sparse cover happened to drop an edge across it. Each
- * candidate is screened three ways:
- *  - **constriction** — the throat (narrowest point, by the exact union SDF — the cover grid is far too coarse
- *    to resolve a doorway) is markedly narrower than the more-open room;
- *  - **aperture** — the throat is bounded by solid on BOTH sides of some axis perpendicular to the passage
- *    ({@link throatIsAperture}); this rejects a one-sided graze past a pillar and an open region boundary,
- *    which dip the SDF without being a coupling between two volumes;
- *  - **dedup** — collapse the many crossings of one opening to its single widest (most central) throat.
- *
- * The throats are fed back as PRE-SEEDED probes to a re-cover ({@link probe_place_sdf_cover} `predefined`) so
- * they carve the SDF and become first-class probes, and seed {@link probe_densify_portals}. Pure geometry;
- * offline (no WebAudio). Deterministic for a given field + scene.
- *
- * @param {import("./AcousticProbeField.js").AcousticProbeField} field the probe positions to detect over
- * @param {import("../core/AcousticOccluderIndex.js").AcousticOccluderIndex} index the acoustic scene
- * @param {number} minSpacing the probe spacing hint (scales the gather radius, opening-width floor, dedup)
- * @param {{constrictionFactor?: number, portalFloorRatio?: number, neighborRadiusFactor?: number}} [options]
- * @returns {number[]} flat throat positions `[x,y,z, …]`, one per detected opening (possibly empty)
- */
-export function probe_detect_portals(field, index, minSpacing, options = {}) {
-    const constrictionFactor = options.constrictionFactor ?? DEFAULT_CONSTRICTION_FACTOR;
-    const portalFloor = (options.portalFloorRatio ?? DEFAULT_PORTAL_FLOOR_RATIO) * minSpacing;
-    const radius = (options.neighborRadiusFactor ?? DEFAULT_NEIGHBOR_RADIUS_FACTOR) * minSpacing;
-    const maxDistance = minSpacing * 4; // SDF query cutoff (matches the cover's sparseness ceiling)
-
-    const n = field.size;
-
-    // candidate throats, then greedily deduped widest-first into one portal per opening
-    const candX = [];
-    const candY = [];
-    const candZ = [];
-    const candWidth = []; // the throat clearance (SDF) — wider = more central crossing
-
-    const hits = []; // probesWithinRadius scratch (auto-grows; valid length is the returned count)
-
-    for (let a = 0; a < n; a++) {
-        const ax = field.probeX(a), ay = field.probeY(a), az = field.probeZ(a);
-        const sdfA = index.signedDistanceAt(ax, ay, az, maxDistance);
-
-        const count = field.probesWithinRadius(hits, 0, ax, ay, az, radius);
-
-        for (let h = 0; h < count; h++) {
-            const b = hits[h];
-            if (b <= a) {
-                continue; // each unordered pair once
-            }
-
-            if (!probe_edge_visible(field, index, a, b)) {
-                continue; // a wall blocks it — the pair does not couple through an opening
-            }
-
-            const bx = field.probeX(b), by = field.probeY(b), bz = field.probeZ(b);
-            const sdfB = index.signedDistanceAt(bx, by, bz, maxDistance);
-
-            // the narrowest INTERIOR point of the segment = the throat
-            let minS = Infinity, mt = 0;
-            for (let s = 1; s <= EDGE_SAMPLES; s++) {
-                const t = s / (EDGE_SAMPLES + 1);
-                const sdfP = index.signedDistanceAt(
-                    ax + (bx - ax) * t, ay + (by - ay) * t, az + (bz - az) * t, maxDistance);
-                if (sdfP < minS) {
-                    minS = sdfP;
-                    mt = t;
-                }
-            }
-
-            // …narrower than the MORE-open of the two rooms. A doorway onto a low/tight room barely dips
-            // against THAT room's (often unrelated, e.g. floor-limited) clearance, so comparing against the
-            // less-open side would reject it; the aperture gate below is what rejects genuine non-openings.
-            const roomClearance = sdfA > sdfB ? sdfA : sdfB;
-            if (minS <= portalFloor || minS >= constrictionFactor * roomClearance) {
-                continue;
-            }
-
-            const tx = ax + (bx - ax) * mt, ty = ay + (by - ay) * mt, tz = az + (bz - az) * mt;
-
-            const ex = bx - ax, ey = by - ay, ez = bz - az;
-            const elen = Math.sqrt(ex * ex + ey * ey + ez * ez);
-            if (elen === 0 || !throatIsAperture(index, tx, ty, tz, ex / elen, ey / elen, ez / elen, minSpacing)) {
-                continue;
-            }
-
-            candX.push(tx);
-            candY.push(ty);
-            candZ.push(tz);
-            candWidth.push(minS);
-        }
-    }
-
-    return dedupeWidestFirst(candX, candY, candZ, candWidth, DEDUP_RADIUS_FACTOR * minSpacing);
-}
-
-/**
- * Collapse candidate throats that belong to the same opening (within `radius`) to one portal each, keeping the
- * WIDEST (most central) crossing of each cluster. Greedy: sort by width descending, accept a candidate only if
- * no already-accepted portal is within `radius`.
- * @returns {number[]} flat accepted positions `[x,y,z, …]`
- */
-function dedupeWidestFirst(candX, candY, candZ, candWidth, radius) {
-    const order = candWidth.map((_, i) => i).sort((a, b) => candWidth[b] - candWidth[a]);
-    const r2 = radius * radius;
-
-    const out = [];
-    for (let o = 0; o < order.length; o++) {
-        const i = order[o];
-        const x = candX[i], y = candY[i], z = candZ[i];
-
-        let merged = false;
-        for (let k = 0; k < out.length; k += 3) {
-            const dx = out[k] - x, dy = out[k + 1] - y, dz = out[k + 2] - z;
-            if (dx * dx + dy * dy + dz * dz <= r2) {
-                merged = true;
-                break;
-            }
-        }
-
-        if (!merged) {
-            out.push(x, y, z);
-        }
-    }
-
-    return out;
-}
-
-/**
- * Whether the throat `(tx,ty,tz)` is a genuine APERTURE: bounded by solid on BOTH sides of the HORIZONTAL axis
- * perpendicular to the passage `(ex,ey,ez)` — the doorway's jambs / the window's frame sides. A one-sided graze
- * past a pillar or wall stub is bounded on only ONE side of that axis; an open region boundary on neither —
- * both dip the SDF but are not couplings between two volumes, so they are rejected.
- *
- * Only the horizontal cross-axis discriminates: the vertical axis is trivially bounded by the floor and ceiling
- * in any enclosed room shorter than 2·reach, so testing it would rescue every indoor candidate (a graze past a
- * pillar would pass on the floor/ceiling alone). Sound sources and listeners are at comparable heights, so the
- * passage is near-horizontal and its jambs are the horizontal cross-axis.
- */
-function throatIsAperture(index, tx, ty, tz, ex, ey, ez, minSpacing) {
-    const reach = APERTURE_REACH_FACTOR * minSpacing;
-
-    // the horizontal axis perpendicular to the passage = ê × world-up (the jamb axis). For a near-vertical
-    // passage ê ∥ up, so swap the reference to keep the cross product well-conditioned (it stays horizontal).
-    let rx = 0, ry = 1, rz = 0;
-    if (Math.abs(ey) > 0.9) {
-        rx = 1; ry = 0; rz = 0;
-    }
-    let ux = ey * rz - ez * ry, uy = ez * rx - ex * rz, uz = ex * ry - ey * rx;
-    const ul = Math.sqrt(ux * ux + uy * uy + uz * uz);
-    ux /= ul; uy /= ul; uz /= ul;
-
-    return boundedBothSides(index, tx, ty, tz, ux, uy, uz, reach);
-}
-
-function boundedBothSides(index, ox, oy, oz, dx, dy, dz, reach) {
-    return solidWithin(index, ox, oy, oz, dx, dy, dz, reach)
-        && solidWithin(index, ox, oy, oz, -dx, -dy, -dz, reach);
-}
-
-function solidWithin(index, ox, oy, oz, dx, dy, dz, reach) {
-    APERTURE_RAY.setOrigin(ox, oy, oz);
-    APERTURE_RAY.setDirection(dx, dy, dz);
-    APERTURE_RAY.tMax = reach;
-    return index.anyHit(APERTURE_RAY);
-}
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { probe_edge_visible } from "./probe_edge_visible.js";
+
+// Interior sample points along each candidate pair (the throat is the narrowest of these).
+const EDGE_SAMPLES = 6;
+// Gather candidate partners within this × minSpacing. The cover places probes at the SPARSEST up to
+// `maxSpacing` (= sparsenessRatio·minSpacing, default 4) apart, so the two probes flanking an opening — placed
+// at their room interiors, away from the low-clearance throat — can be a full maxSpacing apart. The gather
+// must span that, or a wide room's doorway is never tested. (The constriction + aperture screens reject the
+// extra far/in-room pairs this admits.)
+const DEFAULT_NEIGHBOR_RADIUS_FACTOR = 4;
+// A throat counts as a portal only if it is at least this much narrower than the MORE-open of its two rooms —
+// a real dip, not a flat open line. Loose on purpose: the genuine selectivity is the APERTURE gate (bounded on
+// opposing sides), so this only has to reject lines that never squeeze. (A doorway in a low room barely dips —
+// e.g. a 0.7 m jamb throat vs a 1.1 m floor-limited room is ratio 0.64 — so the bar must sit above that.)
+const DEFAULT_CONSTRICTION_FACTOR = 0.8;
+// …and only if the throat is at least this fraction of `minSpacing` wide (an SDF/half-width floor) — a
+// passable opening, not a polygon crack the visibility ray happened to thread.
+const DEFAULT_PORTAL_FLOOR_RATIO = 0.1;
+// Two throats within this × minSpacing are the same opening — keep the widest (most central) crossing.
+const DEDUP_RADIUS_FACTOR = 1.0;
+// An opening up to this × minSpacing wide is bounded within reach — how far an aperture ray looks for the far
+// jamb / opposing wall.
+const APERTURE_REACH_FACTOR = 2;
+// module-static scratch for the aperture rays
+const APERTURE_RAY = new Ray3();
+
+/**
+ * Detect acoustic PORTALS — the throats of openings (door frames, windows, arches) — over a probe field's
+ * positions. A portal is where a clear line of sight between two probes threads a CONSTRICTION: the two probes
+ * sit in open rooms (high clearance) but the line between them squeezes through a narrow gap that is bounded by
+ * solid on opposing sides (a doorway's jambs, a window's frame).
+ *
+ * Candidates are every nearby MUTUALLY-VISIBLE probe pair (a BVH radius gather), NOT just the baked visibility
+ * edges — so an opening is found whether or not the sparse cover happened to drop an edge across it. Each
+ * candidate is screened three ways:
+ *  - **constriction** — the throat (narrowest point, by the exact union SDF — the cover grid is far too coarse
+ *    to resolve a doorway) is markedly narrower than the more-open room;
+ *  - **aperture** — the throat is bounded by solid on BOTH sides of some axis perpendicular to the passage
+ *    ({@link throatIsAperture}); this rejects a one-sided graze past a pillar and an open region boundary,
+ *    which dip the SDF without being a coupling between two volumes;
+ *  - **dedup** — collapse the many crossings of one opening to its single widest (most central) throat.
+ *
+ * The throats are fed back as PRE-SEEDED probes to a re-cover ({@link probe_place_sdf_cover} `predefined`) so
+ * they carve the SDF and become first-class probes, and seed {@link probe_densify_portals}. Pure geometry;
+ * offline (no WebAudio). Deterministic for a given field + scene.
+ *
+ * @param {import("./AcousticProbeField.js").AcousticProbeField} field the probe positions to detect over
+ * @param {import("../core/AcousticOccluderIndex.js").AcousticOccluderIndex} index the acoustic scene
+ * @param {number} minSpacing the probe spacing hint (scales the gather radius, opening-width floor, dedup)
+ * @param {{constrictionFactor?: number, portalFloorRatio?: number, neighborRadiusFactor?: number}} [options]
+ * @returns {number[]} flat throat positions `[x,y,z, …]`, one per detected opening (possibly empty)
+ */
+export function probe_detect_portals(field, index, minSpacing, options = {}) {
+    const constrictionFactor = options.constrictionFactor ?? DEFAULT_CONSTRICTION_FACTOR;
+    const portalFloor = (options.portalFloorRatio ?? DEFAULT_PORTAL_FLOOR_RATIO) * minSpacing;
+    const radius = (options.neighborRadiusFactor ?? DEFAULT_NEIGHBOR_RADIUS_FACTOR) * minSpacing;
+    const maxDistance = minSpacing * 4; // SDF query cutoff (matches the cover's sparseness ceiling)
+
+    const n = field.size;
+
+    // candidate throats, then greedily deduped widest-first into one portal per opening
+    const candX = [];
+    const candY = [];
+    const candZ = [];
+    const candWidth = []; // the throat clearance (SDF) — wider = more central crossing
+
+    const hits = []; // probesWithinRadius scratch (auto-grows; valid length is the returned count)
+
+    for (let a = 0; a < n; a++) {
+        const ax = field.probeX(a), ay = field.probeY(a), az = field.probeZ(a);
+        const sdfA = index.signedDistanceAt(ax, ay, az, maxDistance);
+
+        const count = field.probesWithinRadius(hits, 0, ax, ay, az, radius);
+
+        for (let h = 0; h < count; h++) {
+            const b = hits[h];
+            if (b <= a) {
+                continue; // each unordered pair once
+            }
+
+            if (!probe_edge_visible(field, index, a, b)) {
+                continue; // a wall blocks it — the pair does not couple through an opening
+            }
+
+            const bx = field.probeX(b), by = field.probeY(b), bz = field.probeZ(b);
+            const sdfB = index.signedDistanceAt(bx, by, bz, maxDistance);
+
+            // the narrowest INTERIOR point of the segment = the throat
+            let minS = Infinity, mt = 0;
+            for (let s = 1; s <= EDGE_SAMPLES; s++) {
+                const t = s / (EDGE_SAMPLES + 1);
+                const sdfP = index.signedDistanceAt(
+                    ax + (bx - ax) * t, ay + (by - ay) * t, az + (bz - az) * t, maxDistance);
+                if (sdfP < minS) {
+                    minS = sdfP;
+                    mt = t;
+                }
+            }
+
+            // …narrower than the MORE-open of the two rooms. A doorway onto a low/tight room barely dips
+            // against THAT room's (often unrelated, e.g. floor-limited) clearance, so comparing against the
+            // less-open side would reject it; the aperture gate below is what rejects genuine non-openings.
+            const roomClearance = sdfA > sdfB ? sdfA : sdfB;
+            if (minS <= portalFloor || minS >= constrictionFactor * roomClearance) {
+                continue;
+            }
+
+            const tx = ax + (bx - ax) * mt, ty = ay + (by - ay) * mt, tz = az + (bz - az) * mt;
+
+            const ex = bx - ax, ey = by - ay, ez = bz - az;
+            const elen = Math.sqrt(ex * ex + ey * ey + ez * ez);
+            if (elen === 0 || !throatIsAperture(index, tx, ty, tz, ex / elen, ey / elen, ez / elen, minSpacing)) {
+                continue;
+            }
+
+            candX.push(tx);
+            candY.push(ty);
+            candZ.push(tz);
+            candWidth.push(minS);
+        }
+    }
+
+    return dedupeWidestFirst(candX, candY, candZ, candWidth, DEDUP_RADIUS_FACTOR * minSpacing);
+}
+
+/**
+ * Collapse candidate throats that belong to the same opening (within `radius`) to one portal each, keeping the
+ * WIDEST (most central) crossing of each cluster. Greedy: sort by width descending, accept a candidate only if
+ * no already-accepted portal is within `radius`.
+ * @returns {number[]} flat accepted positions `[x,y,z, …]`
+ */
+function dedupeWidestFirst(candX, candY, candZ, candWidth, radius) {
+    const order = candWidth.map((_, i) => i).sort((a, b) => candWidth[b] - candWidth[a]);
+    const r2 = radius * radius;
+
+    const out = [];
+    for (let o = 0; o < order.length; o++) {
+        const i = order[o];
+        const x = candX[i], y = candY[i], z = candZ[i];
+
+        let merged = false;
+        for (let k = 0; k < out.length; k += 3) {
+            const dx = out[k] - x, dy = out[k + 1] - y, dz = out[k + 2] - z;
+            if (dx * dx + dy * dy + dz * dz <= r2) {
+                merged = true;
+                break;
+            }
+        }
+
+        if (!merged) {
+            out.push(x, y, z);
+        }
+    }
+
+    return out;
+}
+
+/**
+ * Whether the throat `(tx,ty,tz)` is a genuine APERTURE: bounded by solid on BOTH sides of the HORIZONTAL axis
+ * perpendicular to the passage `(ex,ey,ez)` — the doorway's jambs / the window's frame sides. A one-sided graze
+ * past a pillar or wall stub is bounded on only ONE side of that axis; an open region boundary on neither —
+ * both dip the SDF but are not couplings between two volumes, so they are rejected.
+ *
+ * Only the horizontal cross-axis discriminates: the vertical axis is trivially bounded by the floor and ceiling
+ * in any enclosed room shorter than 2·reach, so testing it would rescue every indoor candidate (a graze past a
+ * pillar would pass on the floor/ceiling alone). Sound sources and listeners are at comparable heights, so the
+ * passage is near-horizontal and its jambs are the horizontal cross-axis.
+ */
+function throatIsAperture(index, tx, ty, tz, ex, ey, ez, minSpacing) {
+    const reach = APERTURE_REACH_FACTOR * minSpacing;
+
+    // the horizontal axis perpendicular to the passage = ê × world-up (the jamb axis). For a near-vertical
+    // passage ê ∥ up, so swap the reference to keep the cross product well-conditioned (it stays horizontal).
+    let rx = 0, ry = 1, rz = 0;
+    if (Math.abs(ey) > 0.9) {
+        rx = 1; ry = 0; rz = 0;
+    }
+    let ux = ey * rz - ez * ry, uy = ez * rx - ex * rz, uz = ex * ry - ey * rx;
+    const ul = Math.sqrt(ux * ux + uy * uy + uz * uz);
+    ux /= ul; uy /= ul; uz /= ul;
+
+    return boundedBothSides(index, tx, ty, tz, ux, uy, uz, reach);
+}
+
+function boundedBothSides(index, ox, oy, oz, dx, dy, dz, reach) {
+    return solidWithin(index, ox, oy, oz, dx, dy, dz, reach)
+        && solidWithin(index, ox, oy, oz, -dx, -dy, -dz, reach);
+}
+
+function solidWithin(index, ox, oy, oz, dx, dy, dz, reach) {
+    APERTURE_RAY.setOrigin(ox, oy, oz);
+    APERTURE_RAY.setDirection(dx, dy, dz);
+    APERTURE_RAY.tMax = reach;
+    return index.anyHit(APERTURE_RAY);
+}

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

@@ -1,38 +1,38 @@
-/**
- * Canonical (order-independent) integer key for an undirected pair of probe indices: `min·probe_count + max`.
- *
- * WHY this exists: the probe bake keys undirected pairs in four different modules (visibility augmentation's
- * dedup set, portal densification's dedup set, component bridging's per-component-pair best-candidate map, and
- * the runtime {@link ProbeVisibilityRecheck} dirty queue). The packing carries TWO invariants that are easy to
- * break independently — the pair must be canonicalised (so `(a,b)` and `(b,a)` collide deliberately) and the
- * radix must be the PROBE COUNT (so distinct pairs never collide). Re-deriving it per module meant a change of
- * packing — say to bit-shifts once a field exceeds 2^26 probes and the product loses exact integer precision —
- * would have to be found in four places. Encode and decode live together here so they cannot drift apart.
- *
- * PRECONDITION: `a` and `b` are in `[0, probe_count)` and `probe_count² ≤ Number.MAX_SAFE_INTEGER`.
- *
- * @param {number} a probe index
- * @param {number} b probe index
- * @param {number} probe_count number of probes in the field — the packing radix
- * @returns {number} canonical key, equal for `(a,b)` and `(b,a)`
- */
-export function probe_edge_key(a, b, probe_count) {
-    return a < b
-        ? a * probe_count + b
-        : b * probe_count + a;
-}
-
-/**
- * Unpack a {@link probe_edge_key} back into its two probe indices, written into `result` as
- * `[low, high]`. The inverse of {@link probe_edge_key} — kept beside it so the radix convention has a
- * single owner.
- *
- * @param {number[]|Uint32Array} result receives 2 elements: the lower then the higher probe index
- * @param {number} result_offset
- * @param {number} key a key produced by {@link probe_edge_key} with the same `probe_count`
- * @param {number} probe_count the packing radix the key was built with
- */
-export function probe_edge_key_decode(result, result_offset, key, probe_count) {
-    result[result_offset] = (key / probe_count) | 0;
-    result[result_offset + 1] = key % probe_count;
-}
+/**
+ * Canonical (order-independent) integer key for an undirected pair of probe indices: `min·probe_count + max`.
+ *
+ * WHY this exists: the probe bake keys undirected pairs in four different modules (visibility augmentation's
+ * dedup set, portal densification's dedup set, component bridging's per-component-pair best-candidate map, and
+ * the runtime {@link ProbeVisibilityRecheck} dirty queue). The packing carries TWO invariants that are easy to
+ * break independently — the pair must be canonicalised (so `(a,b)` and `(b,a)` collide deliberately) and the
+ * radix must be the PROBE COUNT (so distinct pairs never collide). Re-deriving it per module meant a change of
+ * packing — say to bit-shifts once a field exceeds 2^26 probes and the product loses exact integer precision —
+ * would have to be found in four places. Encode and decode live together here so they cannot drift apart.
+ *
+ * PRECONDITION: `a` and `b` are in `[0, probe_count)` and `probe_count² ≤ Number.MAX_SAFE_INTEGER`.
+ *
+ * @param {number} a probe index
+ * @param {number} b probe index
+ * @param {number} probe_count number of probes in the field — the packing radix
+ * @returns {number} canonical key, equal for `(a,b)` and `(b,a)`
+ */
+export function probe_edge_key(a, b, probe_count) {
+    return a < b
+        ? a * probe_count + b
+        : b * probe_count + a;
+}
+
+/**
+ * Unpack a {@link probe_edge_key} back into its two probe indices, written into `result` as
+ * `[low, high]`. The inverse of {@link probe_edge_key} — kept beside it so the radix convention has a
+ * single owner.
+ *
+ * @param {number[]|Uint32Array} result receives 2 elements: the lower then the higher probe index
+ * @param {number} result_offset
+ * @param {number} key a key produced by {@link probe_edge_key} with the same `probe_count`
+ * @param {number} probe_count the packing radix the key was built with
+ */
+export function probe_edge_key_decode(result, result_offset, key, probe_count) {
+    result[result_offset] = (key / probe_count) | 0;
+    result[result_offset + 1] = key % probe_count;
+}

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

@@ -1,41 +1,41 @@
-import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
-
-// module-static scratch — the shadow ray between two probes (allocation-free)
-const RAY = new Ray3();
-
-/**
- * Whether probes `a` and `b` have clear line of sight in the current `index` — a single shadow ray along the
- * segment between them, true if no occluder blocks it. This is the one visibility test shared by the offline
- * bake ({@link bakeVisibility}) and the runtime {@link ProbeVisibilityRecheck}, so they agree exactly.
- * Coincident probes are trivially "visible" (a zero-length segment blocks nothing). Allocation-free; no
- * WebAudio.
- *
- * @param {AcousticProbeField} probeField
- * @param {AcousticOccluderIndex} index the acoustic scene (live geometry — a door that has since closed will
- *        block the ray even though the baked graph still has the edge)
- * @param {number} a probe index
- * @param {number} b probe index
- * @returns {boolean}
- */
-export function probe_edge_visible(probeField, index, a, b) {
-    const ax = probeField.probeX(a);
-    const ay = probeField.probeY(a);
-    const az = probeField.probeZ(a);
-
-    const dx = probeField.probeX(b) - ax;
-    const dy = probeField.probeY(b) - ay;
-    const dz = probeField.probeZ(b) - az;
-
-    const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
-
-    if (distance === 0) {
-        return true;
-    }
-
-    const inv = 1 / distance;
-    RAY.setOrigin(ax, ay, az);
-    RAY.setDirection(dx * inv, dy * inv, dz * inv);
-    RAY.tMax = distance;
-
-    return !index.anyHit(RAY);
-}
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+
+// module-static scratch — the shadow ray between two probes (allocation-free)
+const RAY = new Ray3();
+
+/**
+ * Whether probes `a` and `b` have clear line of sight in the current `index` — a single shadow ray along the
+ * segment between them, true if no occluder blocks it. This is the one visibility test shared by the offline
+ * bake ({@link bakeVisibility}) and the runtime {@link ProbeVisibilityRecheck}, so they agree exactly.
+ * Coincident probes are trivially "visible" (a zero-length segment blocks nothing). Allocation-free; no
+ * WebAudio.
+ *
+ * @param {AcousticProbeField} probeField
+ * @param {AcousticOccluderIndex} index the acoustic scene (live geometry — a door that has since closed will
+ *        block the ray even though the baked graph still has the edge)
+ * @param {number} a probe index
+ * @param {number} b probe index
+ * @returns {boolean}
+ */
+export function probe_edge_visible(probeField, index, a, b) {
+    const ax = probeField.probeX(a);
+    const ay = probeField.probeY(a);
+    const az = probeField.probeZ(a);
+
+    const dx = probeField.probeX(b) - ax;
+    const dy = probeField.probeY(b) - ay;
+    const dz = probeField.probeZ(b) - az;
+
+    const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+    if (distance === 0) {
+        return true;
+    }
+
+    const inv = 1 / distance;
+    RAY.setOrigin(ax, ay, az);
+    RAY.setDirection(dx * inv, dy * inv, dz * inv);
+    RAY.tMax = distance;
+
+    return !index.anyHit(RAY);
+}