@woosh/meep-engine 3.17.0 → 3.17.1

package/README.md

@@ -8,11 +8,11 @@
 npm install @woosh/meep-engine
 ```
 
-**Start here:** [`samples/engine/README.md`](samples/engine/README.md) — the first thirty minutes,
-with the Vite stanza you need, why your scene should be authored in metres, photometric reference
-values, and how input reaches the engine. The worked example beside it,
-[`samples/engine/first-scene`](samples/engine/first-scene), boots the engine, lights a scene and
-reads the keyboard in about eighty lines.
+**Start here:** the package ships a guide to the first thirty minutes at
+`samples/engine/README.md` - the Vite stanza you need, why your scene should be authored in
+metres, photometric reference values, and how input reaches the engine. The worked example beside
+it, `samples/engine/first-scene`, boots the engine, lights a scene and reads the keyboard in about
+eighty lines.
 
 **Proprietary and source-available.** You get all ~6,200 fine-grained ES modules, unobfuscated,
 under a licence that lets you ship. Need a lerp function? Import the module that holds it and pay
@@ -32,10 +32,9 @@ on paper and still not have them working together - and every plugin is another
 tune, per scene and per device.
 
 **Shadows, ambient occlusion, indirect lighting, auto-exposure, anti-aliasing and transparency are
-all on by default, and there is nothing to configure to get a correct-looking frame.** No quality
-tiers to author, no per-device profiles, no exposure value to pick, no shadow cascade splits to
-hand-tune. You put a scene together, it looks right, and it holds its frame rate across a wide
-range of hardware without you doing anything about it.
+all on by default, with nothing to configure.** No quality tiers to author, no per-device profiles,
+no exposure value to pick, no shadow cascade splits to hand-tune. You put a scene together and it
+holds its frame rate across a wide range of hardware without you doing anything about it.
 
 In development since 2013, shipped in a commercial Steam release, and held to **~15,000 tests** -
 determinism, adversarial and shader-emulation suites among them.
@@ -74,39 +73,6 @@ occlusion culling, the frame graph - they are in **the renderer contract**, whic
 package at `src/shade/RENDERER_CONTRACT.md`. It also covers how to put a model on the screen and
 how to add your own work to the frame.
 
-## How the features interact
-
-What a feature list cannot tell you is whether the features work together once they are in the same
-scene. This can.
-
-| | Lit by scene lights | Shadows | Stable when it moves | Indirect light |
-|---|---|---|---|---|
-| Static meshes | ✅ | casts + receives | ✅ | ✅ |
-| **Skinned characters** | ✅ | casts + receives | ✅ **per-vertex** | ✅ |
-| Terrain | ✅ | casts + receives | ✅ | ✅ |
-| Decals | ✅ | receives | ✅ follows the surface | ✅ |
-| Transparent surfaces | ✅ | receives | ❌ | ✅ |
-| Volumetric fog | ✅ | shadowed by them | ✅ | n/a |
-| Water, particles, trails, overlays | ❌ | ❌ | ❌ | ❌ |
-
-Those top six are not six systems that were each taught about lighting. They read the same lighting,
-the same shadows and the same motion data, because there is only one of each. Three consequences:
-
-* **Animated characters are not a special case.** A skinned character goes down the same path as a
-  static one: same culling, same shadows, same lighting. It also produces motion data per vertex
-  rather than per object, so a swinging arm resolves cleanly under anti-aliasing instead of
-  smearing - which is the usual failure of bolt-on temporal AA.
-* **A decal is lit like the surface it lands on.** Decals modify the surface itself rather than
-  painting over the finished image, so a scorch mark is lit, shadowed and bounced exactly like the
-  wall under it, and ambient occlusion and reflections see it too.
-* **Ordering is declared, not accidental.** Systems state what they must come after, by name, and
-  the renderer resolves the order. Decals declare that they follow terrain, so scorch marks land on
-  textured ground - rather than depending on which system happened to register first.
-
-Water, particles, trails and screen overlays are drawn after lighting, so they are not lit or
-shadowed and contribute no motion data. They read the scene's depth, so they are correctly hidden
-behind things in front of them.
-
 ## Scaling across hardware
 
 **One build covers a wide hardware range, and you don't author the tiers.** When frames start
@@ -165,36 +131,6 @@ skinned objects sample as they move through it. It bakes in-engine, from a live
 so the precompute is a call you make rather than a tool you leave the engine for. Opaque and
 transparent surfaces both use it, so turning it on does not leave them lit differently.
 
-## WebGPU only
-
-WebGPU is not a better WebGL - it is a different machine. Compute shaders, storage buffers and
-indirect draw are what let visibility be decided on the GPU and a whole scene be submitted in a
-couple of draw calls. None of that has an equivalent in WebGL, so supporting both would mean either
-a second renderer to maintain or holding this one down to what the older API can express. meep
-targets WebGPU, and everything above follows from that.
-
-The floor is fixed and checked before anything is created: WebGPU plus a small set of capabilities
-that mainstream desktop GPUs have had for years. Hardware that does not clear it gets a clear
-failure message written to be shown to a person, rather than a degraded picture. The exact features
-and limits are in §2 of `src/shade/RENDERER_CONTRACT.md`.
-
-To see what a given browser and GPU actually report, open
-**[webgpu.report](https://webgpu.report/)** on the machine in question - it lists the adapter's
-features and limits, which is what the floor is checked against.
-
-## Numbers
-
-There is no published benchmark for the renderer yet. What the pipeline does differently is
-checkable in the source without running anything - draw count independent of object count, one
-lighting pass independent of light count, material cost independent of overdraw - and the tools to
-measure the rest ship with it.
-
-The renderer records `.sgpt` GPU profile captures - per-pass timings, and at higher capture levels
-the frame-graph structure, dispatch and draw counts. Assign a
-`GPUProfileSession({ level: GPUProfileLevel.WORKLOAD })` to `renderer.profile_session`, call
-`start()`, run frames, and `stop()` returns an `ArrayBuffer` to write out. The recorder and the
-format specification (`src/shade/device/timing/profile/SGPT_FORMAT.md`) both ship in this package.
-
 ---
 
 ## Everything else

package/package.json

@@ -6,7 +6,7 @@
   "description": "Advanced 3D game engine",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.17.0",
+  "version": "3.17.1",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

package/src/engine/ecs/transform/t64_set_rotation_axis_angle.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Set a {@link Transform64}'s rotation to `angle` radians about the axis `(ax, ay, az)`, right-handed.
+ *
+ * The {@link Transform64} counterpart of `Quaternion.fromAxisAngle`, and it defers to
+ * `Quaternion._fromAxisAngle` for the same reason {@link t64_look_rotation} defers to
+ * `_lookRotation` — one copy of the arithmetic, and `Quaternion` is itself f64, so routing through
+ * one costs no precision.
+ *
+ * The axis must be unit length. Unlike {@link t64_look_rotation}, which takes a direction whose
+ * length means nothing, here it means something and is not recovered by normalizing the result: for
+ * an axis of length `k` the quaternion `(axis·sin(angle/2), cos(angle/2))` normalizes to a rotation
+ * about the same axis by `2·atan(k·tan(angle/2))`, which is `angle` only for `k = 1`. So a longer
+ * axis does not fail, it quietly turns further — hence the assert, which the consumer strips.
+ *
+ * Nothing here touches `t64`'s matrix — call {@link Transform64#updateMatrix} once you are done
+ * setting components.
+ *
+ * @param {Transform64} t64
+ * @param {number} ax axis, unit length
+ * @param {number} ay axis, unit length
+ * @param {number} az axis, unit length
+ * @param {number} angle radians
+ */
+export function t64_set_rotation_axis_angle(t64: Transform64, ax: number, ay: number, az: number, angle: number): void;
+//# sourceMappingURL=t64_set_rotation_axis_angle.d.ts.map

package/src/engine/ecs/transform/t64_set_rotation_axis_angle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"t64_set_rotation_axis_angle.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/t64_set_rotation_axis_angle.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,kEALW,MAAM,MACN,MAAM,MACN,MAAM,SACN,MAAM,QAehB"}

package/src/engine/ecs/transform/t64_set_rotation_axis_angle.js

@@ -0,0 +1,45 @@
+import { assert } from "../../../core/assert.js";
+import { Quaternion } from "../../../core/geom/Quaternion.js";
+
+/**
+ * @type {Quaternion}
+ */
+const SCRATCH_ROTATION = new Quaternion();
+
+/**
+ * Set a {@link Transform64}'s rotation to `angle` radians about the axis `(ax, ay, az)`, right-handed.
+ *
+ * The {@link Transform64} counterpart of `Quaternion.fromAxisAngle`, and it defers to
+ * `Quaternion._fromAxisAngle` for the same reason {@link t64_look_rotation} defers to
+ * `_lookRotation` — one copy of the arithmetic, and `Quaternion` is itself f64, so routing through
+ * one costs no precision.
+ *
+ * The axis must be unit length. Unlike {@link t64_look_rotation}, which takes a direction whose
+ * length means nothing, here it means something and is not recovered by normalizing the result: for
+ * an axis of length `k` the quaternion `(axis·sin(angle/2), cos(angle/2))` normalizes to a rotation
+ * about the same axis by `2·atan(k·tan(angle/2))`, which is `angle` only for `k = 1`. So a longer
+ * axis does not fail, it quietly turns further — hence the assert, which the consumer strips.
+ *
+ * Nothing here touches `t64`'s matrix — call {@link Transform64#updateMatrix} once you are done
+ * setting components.
+ *
+ * @param {Transform64} t64
+ * @param {number} ax axis, unit length
+ * @param {number} ay axis, unit length
+ * @param {number} az axis, unit length
+ * @param {number} angle radians
+ */
+export function t64_set_rotation_axis_angle(t64, ax, ay, az, angle) {
+    // a constant message on purpose - a template literal would build a string on every call, and
+    // this is vocabulary the migration puts in hot paths
+    assert.ok(Math.abs(ax * ax + ay * ay + az * az - 1) < 1e-6, 'axis must be unit length');
+
+    SCRATCH_ROTATION._fromAxisAngle(ax, ay, az, angle);
+
+    t64.setRotation(
+        SCRATCH_ROTATION[0],
+        SCRATCH_ROTATION[1],
+        SCRATCH_ROTATION[2],
+        SCRATCH_ROTATION[3]
+    );
+}

package/src/engine/sound/simulation/AcousticSimulator.d.ts

@@ -103,22 +103,26 @@ export class AcousticSimulator {
     setProbeField(field: AcousticProbeField | null): void;
     /**
      * 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
+     *
+     * Both positions are read BY INDEX rather than through `.x/.y/.z`: they are live views over
+     * {@link Transform64} buffers (plain `Float64Array`s, no component accessors). A {@link Vector3}
+     * is a `Float64Array` subclass whose `[0..2]` alias `x/y/z`, so indexing reads both shapes.
+     * @param {number[]|Float32Array|Float64Array} listener listener world position, 3 elements
+     * @param {number[]|Float32Array|Float64Array} source source world position, 3 elements
+     * @param {number} source_radius 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: Vector3, source: Vector3, sourceRadius: number, state: AcousticSourceState, out: AcousticSolution): void;
+    solveFor(listener: number[] | Float32Array | Float64Array, source: number[] | Float32Array | Float64Array, source_radius: number, state: AcousticSourceState, out: AcousticSolution): void;
     /**
      * 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
+     * @param {EventInstance[]} live_instances bounded set (≤ voice budget)
+     * @param {number[]|Float32Array|Float64Array} listener listener world position, 3 elements
      */
-    apply(liveInstances: EventInstance[], listener: Vector3): void;
+    apply(live_instances: EventInstance[], listener: number[] | Float32Array | Float64Array): void;
     /**
      * Drop a live instance's accumulated state (call when the instance ends).
      * @param {EventInstance} instance
@@ -128,7 +132,6 @@ export class AcousticSimulator {
 }
 import { AcousticMedium } from "./core/AcousticMedium.js";
 import { AcousticOccluderIndex } from "./core/AcousticOccluderIndex.js";
-import { Vector3 } from "../../../core/geom/Vector3.js";
 import { AcousticSourceState } from "./core/AcousticSourceState.js";
 import { AcousticSolution } from "./core/AcousticSolution.js";
 //# sourceMappingURL=AcousticSimulator.d.ts.map

package/src/engine/sound/simulation/AcousticSimulator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AcousticSimulator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/simulation/AcousticSimulator.js"],"names":[],"mappings":"AA0CA;;;;;;;;;GASG;AACH;IACI;;;OAGG;IACH,UAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,WAFU,MAAM,CAEA;IAEhB;;;;;OAKG;IACH,SAFU,OAAO,CAED;IAEhB;;;;;;OAMG;IACH,gBAFU,OAAO,CAEM;IAEvB;;;;OAIG;IACH,eAFU,MAAM,CAEE;IAgGlB,6BAGC;IAZD;;;;OAIG;IACH,0BAEC;IAiBD,gCAEC;IAZD;;;;;OAKG;IACH,6BAEC;IAMD;;;;OAIG;IACH,2CAEC;IAED;;;;;;;OAOG;IACH,yEAHW,YAAY,GAAC,MAAM,EAAE,GACnB,MAAM,CAIlB;IAED;;;OAGG;IACH,6BAHW,MAAM,UACN,YAAY,GAAC,MAAM,EAAE,QAI/B;IAED;;OAEG;IACH,uBAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,8DAEC;IAED;;OAEG;IACH,iDAEC;IAED;;;;OAIG;IACH,sBAEC;IAED;;;;;OAKG;IACH,qBAFW,qBAAmB,IAAI,QAMjC;IAED;;;;;;;;OAQG;IACH,mBAPW,OAAO,UACP,OAAO,gBACP,MAAM,SAEN,mBAAmB,OACnB,gBAAgB,QAkB1B;IAED;;;;;;OAMG;IACH,qBAHW,eAAe,YACf,OAAO,QAuFjB;IAgPD;;;OAGG;IACH,sCAOC;;CACJ;+BA/nB8B,0BAA0B;sCACnB,iCAAiC;wBAN/C,+BAA+B;oCASW,+BAA+B;iCADhE,4BAA4B"}
+{"version":3,"file":"AcousticSimulator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/simulation/AcousticSimulator.js"],"names":[],"mappings":"AA6CA;;;;;;;;;GASG;AACH;IACI;;;OAGG;IACH,UAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,WAFU,MAAM,CAEA;IAEhB;;;;;OAKG;IACH,SAFU,OAAO,CAED;IAEhB;;;;;;OAMG;IACH,gBAFU,OAAO,CAEM;IAEvB;;;;OAIG;IACH,eAFU,MAAM,CAEE;IA2FlB,6BAGC;IAZD;;;;OAIG;IACH,0BAEC;IAiBD,gCAEC;IAZD;;;;;OAKG;IACH,6BAEC;IAMD;;;;OAIG;IACH,2CAEC;IAED;;;;;;;OAOG;IACH,yEAHW,YAAY,GAAC,MAAM,EAAE,GACnB,MAAM,CAIlB;IAED;;;OAGG;IACH,6BAHW,MAAM,UACN,YAAY,GAAC,MAAM,EAAE,QAI/B;IAED;;OAEG;IACH,uBAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,8DAEC;IAED;;OAEG;IACH,iDAEC;IAED;;;;OAIG;IACH,sBAEC;IAED;;;;;OAKG;IACH,qBAFW,qBAAmB,IAAI,QAMjC;IAED;;;;;;;;;;;;OAYG;IACH,mBAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,UAClC,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,SAEN,mBAAmB,OACnB,gBAAgB,QAkB1B;IAED;;;;;;OAMG;IACH,sBAHW,eAAe,YACf,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,QAyF5C;IAqPD;;;OAGG;IACH,sCAOC;;CACJ;+BAroB8B,0BAA0B;sCACnB,iCAAiC;oCAGL,+BAA+B;iCADhE,4BAA4B"}

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

@@ -1,15 +1,18 @@
+import { assert } from "../../../core/assert.js";
+import {
+    line3_compute_segment_closest_point_t
+} from "../../../core/geom/3d/line/line3_compute_segment_closest_point_t.js";
 import { BinaryElementPool } from "../../../core/geom/3d/topology/struct/binary/BinaryElementPool.js";
+import { v3_length } from "../../../core/geom/vec3/v3_length.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 { v3_length } from "../../../core/geom/vec3/v3_length.js";
+import { seededRandom } from "../../../core/math/random/seededRandom.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 { acoustic_occlusion_solve } from "./core/acoustic_occlusion_solve.js";
 import { VolumeField } from "./core/VolumeField.js";
 import { ProbeFieldPathingSolution } from "./probe/ProbeFieldPathingSolution.js";
 import { ProbeVisibilityRecheck } from "./probe/ProbeVisibilityRecheck.js";
@@ -105,11 +108,6 @@ export class AcousticSimulator {
      */
     #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
@@ -274,26 +272,30 @@ export class AcousticSimulator {
 
     /**
      * 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
+     *
+     * Both positions are read BY INDEX rather than through `.x/.y/.z`: they are live views over
+     * {@link Transform64} buffers (plain `Float64Array`s, no component accessors). A {@link Vector3}
+     * is a `Float64Array` subclass whose `[0..2]` alias `x/y/z`, so indexing reads both shapes.
+     * @param {number[]|Float32Array|Float64Array} listener listener world position, 3 elements
+     * @param {number[]|Float32Array|Float64Array} source source world position, 3 elements
+     * @param {number} source_radius 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) {
+    solveFor(listener, source, source_radius, 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,
+            source[0], source[1], source[2],
+            listener[0], listener[1], listener[2],
             out.airLoss
         );
 
-        this.#occlusionSolver.solve(
-            listener, source, sourceRadius,
+        acoustic_occlusion_solve(
+            listener, source, source_radius,
             this.#occluder_index, this.rayCount, this.smoothing, this.#random,
             state, out
         );
@@ -303,10 +305,12 @@ export class AcousticSimulator {
      * 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
+     * @param {EventInstance[]} live_instances bounded set (≤ voice budget)
+     * @param {number[]|Float32Array|Float64Array} listener listener world position, 3 elements
      */
-    apply(liveInstances, listener) {
+    apply(live_instances, listener) {
+        assert.defined(listener, 'listener');
+
         const live = this.#liveScratch;
         live.clear();
 
@@ -328,7 +332,7 @@ export class AcousticSimulator {
             }
             // 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);
+            const listenerProbe = this.#probeField.nearestVisibleIndex(listener[0], listener[1], listener[2], this.#occluder_index);
             if (listenerProbe >= 0) {
                 this.#pathingSolution.computeExitField(this.#probeField.visibilityGraph, listenerProbe);
                 exitFieldReady = true;
@@ -338,8 +342,8 @@ export class AcousticSimulator {
         const pool = this.#statePool;
         const cursor = this.#stateCursor;
 
-        for (let i = 0; i < liveInstances.length; i++) {
-            const instance = liveInstances[i];
+        for (let i = 0; i < live_instances.length; i++) {
+            const instance = live_instances[i];
 
             live.add(instance);
 
@@ -414,14 +418,18 @@ export class AcousticSimulator {
      * 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)
+     * @param {number[]|Float32Array|Float64Array} 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);
+        // both endpoints are live Transform64 translation views (bare Float64Arrays) — read by index
+        const source_x = source[0], source_y = source[1], source_z = source[2];
+        const listener_x = listener[0], listener_y = listener[1], listener_z = listener[2];
+
+        const sourceProbe = field.nearestVisibleIndex(source_x, source_y, source_z, this.#occluder_index);
 
         if (sourceProbe < 0) {
             return;
@@ -450,14 +458,14 @@ export class AcousticSimulator {
         // 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 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 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 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 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
@@ -493,8 +501,8 @@ export class AcousticSimulator {
         // 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);
+            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:
@@ -599,9 +607,10 @@ export class AcousticSimulator {
     #directivityGainToward(instance, tx, ty, tz) {
         const source = instance.position;
 
-        let dx = tx - source.x;
-        let dy = ty - source.y;
-        let dz = tz - source.z;
+        // a live Transform64 translation view (a bare Float64Array) — read by index
+        let dx = tx - source[0];
+        let dy = ty - source[1];
+        let dz = tz - source[2];
 
         const len = v3_length(dx, dy, dz);
 
@@ -625,10 +634,10 @@ export class AcousticSimulator {
      * 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
+     * @param {number[]|Float32Array|Float64Array} listener listener world position, 3 elements
      */
     #applyDirectivity(solution, instance, listener) {
-        solution.directivityGain = this.#directivityGainToward(instance, listener.x, listener.y, listener.z);
+        solution.directivityGain = this.#directivityGainToward(instance, listener[0], listener[1], listener[2]);
     }
 
     /**

package/src/engine/sound/simulation/README.md

@@ -49,7 +49,7 @@ simulation/
     AcousticOccluderIndex.js      dynamic ray index — a TLAS BVH over OccluderBody shapes (exact shape.raycast)
     OccluderBody.js               one occluder: shape + material + world transform (+ cached inverse / AABB)
     RayHit.js                     reusable closest-hit result (caller-allocated): point + normal + t + material
-    OcclusionSolver.js            volumetric occlusion + transmission for one source (temporally smoothed)
+    acoustic_occlusion_solve.js   volumetric occlusion + transmission for one source (temporally smoothed)
     VolumeField.js                blends AcousticVolume regions into a medium at a point + integrates air
                                   absorption along the source→listener path (distance-dependent, per band)
     AcousticVolumeRegion.js       a shape + medium + transition band (boundary blend)
@@ -197,7 +197,7 @@ real-time-direct / baked-indirect split.
 
 ## The simulation, in one paragraph each
 
-**Occlusion + transmission.** For each live source, `OcclusionSolver` shoots `rayCount` rays from the
+**Occlusion + transmission.** For each live source, `acoustic_occlusion_solve` shoots `rayCount` rays from the
 listener toward points spread over the source's sphere (Fibonacci distribution, randomly re-oriented per
 tick). The fraction blocked is the occlusion; the blocked rays' material `transmission` (3 bands) is what
 leaks through. The result is folded into a temporal EMA, so a low ray count integrates over frames and

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

@@ -1 +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,2DAyE3B;CACJ"}
+{"version":3,"file":"OcclusionSolver.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/core/OcclusionSolver.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;GAaG;AACH;IACI;;;;;;;;;;OAUG;IACH,wDARW,MAAM,0CAEN,MAAM,aACN,MAAM,gBACK,MAAM,2DA4F3B;CACJ"}

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

@@ -32,8 +32,8 @@ export class VolumeField {
      */
     sample(regionIndex: AcousticRegionIndex, x: number, y: number, z: number, out: AcousticMedium): void;
     /**
-     * Integrate per-band air absorption along the segment from the source `(sx, sy, sz)` to the listener
-     * `(lx, ly, lz)`, through the blended media, into `outLoss` (per-band **total dB** attenuation over the
+     * Integrate per-band air absorption along the segment from the source `(source_x, source_y, source_z)` to the listener
+     * `(listener_x, listener_y, listener_z)`, through the blended media, into `outLoss` (per-band **total dB** attenuation over the
      * path). Each `AcousticMedium.airAbsorption` is in dB per metre, so the line integral `∫ α ds` gives the
      * total dB lost per band — i.e. distance-dependent atmospheric absorption (highs accumulate loss faster,
      * so they die over distance while lows carry), plus extra loss along whatever painted region the path
@@ -44,15 +44,15 @@ export class VolumeField {
      * midpoints, blending the medium at each via {@link sample}. Allocation-free (module scratch).
      *
      * @param {AcousticRegionIndex} regionIndex
-     * @param {number} sx source position x
-     * @param {number} sy source position y
-     * @param {number} sz source position z
-     * @param {number} lx listener position x
-     * @param {number} ly listener position y
-     * @param {number} lz listener position z
+     * @param {number} source_x source position x
+     * @param {number} source_y source position y
+     * @param {number} source_z source position z
+     * @param {number} listener_x listener position x
+     * @param {number} listener_y listener position y
+     * @param {number} listener_z listener position z
      * @param {Float32Array} outLoss `[low, mid, high]` total dB attenuation over the path
      */
-    integrateAbsorption(regionIndex: AcousticRegionIndex, sx: number, sy: number, sz: number, lx: number, ly: number, lz: number, outLoss: Float32Array): void;
+    integrateAbsorption(regionIndex: AcousticRegionIndex, source_x: number, source_y: number, source_z: number, listener_x: number, listener_y: number, listener_z: number, outLoss: Float32Array): void;
     #private;
 }
 import { AcousticMedium } from "./AcousticMedium.js";

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

@@ -1 +1 @@
-{"version":3,"file":"VolumeField.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/core/VolumeField.js"],"names":[],"mappings":"AAaA;;;;;GAKG;AACH;IAMI;;OAEG;IACH,4BAFW,cAAc,EAIxB;IASD;;OAEG;IACH,uCAEC;IAZD;;OAEG;IACH,oCAEC;IASD;;;;;;;;;;;;OAYG;IACH,4CALW,MAAM,KACN,MAAM,KACN,MAAM,OACN,cAAc,QA0BxB;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,0DARW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,WACN,YAAY,QA2CtB;;CACJ;+BApJ8B,qBAAqB"}
+{"version":3,"file":"VolumeField.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/core/VolumeField.js"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH;IAMI;;OAEG;IACH,4BAFW,cAAc,EAIxB;IASD;;OAEG;IACH,uCAEC;IAZD;;OAEG;IACH,oCAEC;IASD;;;;;;;;;;;;OAYG;IACH,4CALW,MAAM,KACN,MAAM,KACN,MAAM,OACN,cAAc,QA0BxB;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gEARW,MAAM,YACN,MAAM,YACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,WACN,YAAY,QA0DtB;;CACJ;+BAnK8B,qBAAqB"}

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

@@ -1,3 +1,4 @@
+import { assert } from "../../../../core/assert.js";
 import { AcousticMedium } from "./AcousticMedium.js";
 
 // Samples along a source→listener segment for the air-absorption line integral (midpoint rule). The
@@ -84,8 +85,8 @@ export class VolumeField {
     }
 
     /**
-     * Integrate per-band air absorption along the segment from the source `(sx, sy, sz)` to the listener
-     * `(lx, ly, lz)`, through the blended media, into `outLoss` (per-band **total dB** attenuation over the
+     * Integrate per-band air absorption along the segment from the source `(source_x, source_y, source_z)` to the listener
+     * `(listener_x, listener_y, listener_z)`, through the blended media, into `outLoss` (per-band **total dB** attenuation over the
      * path). Each `AcousticMedium.airAbsorption` is in dB per metre, so the line integral `∫ α ds` gives the
      * total dB lost per band — i.e. distance-dependent atmospheric absorption (highs accumulate loss faster,
      * so they die over distance while lows carry), plus extra loss along whatever painted region the path
@@ -96,18 +97,33 @@ export class VolumeField {
      * midpoints, blending the medium at each via {@link sample}. Allocation-free (module scratch).
      *
      * @param {AcousticRegionIndex} regionIndex
-     * @param {number} sx source position x
-     * @param {number} sy source position y
-     * @param {number} sz source position z
-     * @param {number} lx listener position x
-     * @param {number} ly listener position y
-     * @param {number} lz listener position z
+     * @param {number} source_x source position x
+     * @param {number} source_y source position y
+     * @param {number} source_z source position z
+     * @param {number} listener_x listener position x
+     * @param {number} listener_y listener position y
+     * @param {number} listener_z listener position z
      * @param {Float32Array} outLoss `[low, mid, high]` total dB attenuation over the path
      */
-    integrateAbsorption(regionIndex, sx, sy, sz, lx, ly, lz, outLoss) {
-        const dx = lx - sx;
-        const dy = ly - sy;
-        const dz = lz - sz;
+    integrateAbsorption(
+        regionIndex,
+        source_x, source_y, source_z,
+        listener_x, listener_y, listener_z,
+        outLoss
+    ) {
+
+        assert.isNumber(source_x, 'source_x');
+        assert.isNumber(source_y, 'source_y');
+        assert.isNumber(source_z, 'source_z');
+
+        assert.isNumber(listener_x, 'listener_x');
+        assert.isNumber(listener_y, 'listener_y');
+        assert.isNumber(listener_z, 'listener_z');
+
+        const dx = listener_x - source_x;
+        const dy = listener_y - source_y;
+        const dz = listener_z - source_z;
+
         const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
 
         if (distance === 0) {
@@ -134,7 +150,7 @@ export class VolumeField {
 
         for (let i = 0; i < AIR_INTEGRAL_SAMPLES; i++) {
             const t = (i + 0.5) / AIR_INTEGRAL_SAMPLES;
-            this.sample(regionIndex, sx + dx * t, sy + dy * t, sz + dz * t, STEP_MEDIUM);
+            this.sample(regionIndex, source_x + dx * t, source_y + dy * t, source_z + dz * t, STEP_MEDIUM);
 
             const air = STEP_MEDIUM.airAbsorption;
             low += air[0];

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

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ *
+ * Both positions are read BY INDEX, never as `.x/.y/.z`: production hands us live views over
+ * {@link Transform64} buffers (plain `Float64Array`s, which carry no component accessors), while a
+ * {@link Vector3} is itself a `Float64Array` subclass whose `[0..2]` alias `x/y/z`. Indexing is the one
+ * form that reads both.
+ *
+ * Pure: geometry in, numbers out. No WebAudio, no ECS, no allocation.
+ *
+ * @param {number[]|Float32Array|Float64Array} listener listener world position, 3 elements
+ * @param {number[]|Float32Array|Float64Array} source source world position, 3 elements
+ * @param {number} source_radius apparent radius of the source (0 = point source → boolean occlusion)
+ * @param {AcousticOccluderIndex} index
+ * @param {number} ray_count 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)
+ */
+export function acoustic_occlusion_solve(listener: number[] | Float32Array | Float64Array, source: number[] | Float32Array | Float64Array, source_radius: number, index: AcousticOccluderIndex, ray_count: number, smoothing: number, random: () => number, state: AcousticSourceState, out: AcousticSolution): void;
+//# sourceMappingURL=acoustic_occlusion_solve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"acoustic_occlusion_solve.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/core/acoustic_occlusion_solve.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,mDAVW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,UAClC,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,2CAEN,MAAM,aACN,MAAM,gBACK,MAAM,2DA4F3B"}

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

@@ -0,0 +1,134 @@
+import { assert } from "../../../../core/assert.js";
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { sphere_fibonacci_point } from "../../../../core/geom/3d/sphere/sphere_fibonacci_point.js";
+import { random_orthonormal_basis } from "../../../../core/geom/random/random_orthonormal_basis.js";
+import { v3_matrix3_rotate } from "../../../../core/geom/vec3/v3_matrix3_rotate.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.
+ *
+ * Both positions are read BY INDEX, never as `.x/.y/.z`: production hands us live views over
+ * {@link Transform64} buffers (plain `Float64Array`s, which carry no component accessors), while a
+ * {@link Vector3} is itself a `Float64Array` subclass whose `[0..2]` alias `x/y/z`. Indexing is the one
+ * form that reads both.
+ *
+ * Pure: geometry in, numbers out. No WebAudio, no ECS, no allocation.
+ *
+ * @param {number[]|Float32Array|Float64Array} listener listener world position, 3 elements
+ * @param {number[]|Float32Array|Float64Array} source source world position, 3 elements
+ * @param {number} source_radius apparent radius of the source (0 = point source → boolean occlusion)
+ * @param {AcousticOccluderIndex} index
+ * @param {number} ray_count 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)
+ */
+export function acoustic_occlusion_solve(
+    listener,
+    source,
+    source_radius,
+    index,
+    ray_count,
+    smoothing,
+    random,
+    state,
+    out
+) {
+
+    // a per-tick random orientation for the fibonacci set (decorrelation over frames)
+    random_orthonormal_basis(ROTATION, 0, random);
+
+    const listener_x = listener[0];
+    const listener_y = listener[1];
+    const listener_z = listener[2];
+
+    assert.isNumber(listener_x, 'listener_x');
+    assert.isNumber(listener_y, 'listener_y');
+    assert.isNumber(listener_z, 'listener_z');
+
+    const source_x = source[0];
+    const source_y = source[1];
+    const source_z = source[2];
+
+    assert.isNumber(source_x, 'source_x');
+    assert.isNumber(source_y, 'source_y');
+    assert.isNumber(source_z, 'source_z');
+
+    let blocked = 0;
+    let t0 = 0;
+    let t1 = 0;
+    let t2 = 0;
+
+    for (let i = 0; i < ray_count; i++) {
+        sphere_fibonacci_point(FIBONACCI, 0, i, ray_count);
+        v3_matrix3_rotate(DIRECTION, 0, FIBONACCI[0], FIBONACCI[1], FIBONACCI[2], ROTATION);
+
+        // a sample point spread over the source's sphere
+        const px = source_x + DIRECTION[0] * source_radius;
+        const py = source_y + DIRECTION[1] * source_radius;
+        const pz = source_z + DIRECTION[2] * source_radius;
+
+        const dx = px - listener_x;
+        const dy = py - listener_y;
+        const dz = pz - listener_z;
+
+        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(listener_x, listener_y, listener_z);
+        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 / ray_count;
+
+    // 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);
+}

package/src/shade/playground/volumetrics_froxel/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/volumetrics_froxel/main.js"],"names":[],"mappings":"AA8ZA,uCAsfC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/volumetrics_froxel/main.js"],"names":[],"mappings":"AAmaA,uCAsfC"}

package/src/shade/playground/volumetrics_froxel/main.js

@@ -3,6 +3,7 @@ import Quaternion from "../../../core/geom/Quaternion.js";
 import Vector3 from "../../../core/geom/Vector3.js";
 import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
 import { MIE_PARTICLES_STANDARD_PRECOMPUTED } from "../../../core/math/physics/mie/MIE_PARTICLES_STANDARD_PRECOMPUTED.js";
+import { t64_set_rotation_axis_angle } from "../../../engine/ecs/transform/t64_set_rotation_axis_angle.js";
 import { GPUProfileLevel } from "../../device/timing/profile/GPUProfileLevel.js";
 import { GPUProfileSession } from "../../device/timing/profile/GPUProfileSession.js";
 import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
@@ -209,9 +210,13 @@ function add_participating_media(scene) {
         v.transform.setScale(...scale);
 
         if (yaw_degrees !== 0) {
-            v.transform.rotation.fromAxisAngle(Vector3.up, yaw_degrees * DEG_TO_RAD);
+            t64_set_rotation_axis_angle(v.transform, 0, 1, 0, yaw_degrees * DEG_TO_RAD);
         }
 
+        // the GPU is handed `transform.matrix`, and a Transform64 does not maintain one - the
+        // scale and the yaw above are components and nothing more until this call folds them in
+        v.transform.updateMatrix();
+
         v.fade_distance = fade;
         v.particle_spec = VolumetricsParticleSpec.fromMeep(particle);
         v.target_extinction = extinction;

package/src/shade/renderer/volumetrics/ParticipatingMediaVolume.d.ts

@@ -98,6 +98,13 @@ export class ParticipatingMediaVolume {
     /**
      * Defines actual scale, orientation and world position of the volume.
      * The base size of the volume is 1, centered at 0,0,0
+     *
+     * What reaches the GPU is the *matrix*, and its inverse - `GPUSceneVolumetrics` reads nothing
+     * else. A `Transform64` does not maintain one, so a volume posed by writing components owes an
+     * {@link Transform64#updateMatrix} before it is drawn; one posed by writing the matrix, as
+     * `ParticipatingMediaSystem` does through `fromMatrix`, owes nothing. Skip it and the volume is
+     * a unit cube at the right place, which reads as a volume that is simply not there.
+     *
      * @type {Transform64}
      */
     transform: Transform64;

package/src/shade/renderer/volumetrics/ParticipatingMediaVolume.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticipatingMediaVolume.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/ParticipatingMediaVolume.js"],"names":[],"mappings":"AAKA;IA6EI;;;;OAIG;IACH,+BAHW;QAAC,wBAAwB,CAAC;QAAC,wBAAwB,CAAC;QAAC,MAAM,CAAC;QAAC,CAAC,CAAA;KAAC,GAC9D,uBAAuB,CAalC;IAED,oDAIC;IAlGD;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX,UAAQ;IAER,iCAIC;IAED;;;OAGG;IACH,YAFW,uBAAuB,QAOjC;IAED;;;;;aA0BC;IAED;;;OAGG;IACH,cAHW,uBAAuB,GACrB,OAAO,CAOnB;CAyBJ;AAED,6EAKI;AAIJ;IAII,iBAEC;IAED;;;OAGG;IACH,aAFU,MAAM,EAAE,CAEM;IACxB,0BAA4B;IAC5B,uBAAyB;IAEzB;;;OAGG;IACH,gBAFU,MAAM,EAAE,CAES;IAE3B;;;OAGG;IACH,uBAFU,MAAM,EAAE,CAEgB;IAElC;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;OAGG;IACH,gBAAc;IAEd;;;;;;;;;OASG;IACH,mCAEC;IAED,uCAA+E;IAE/E;;;;;;OAMG;IACH,eAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,WAFU,WAAW,CAES;;CAEjC;4BAzL2B,8CAA8C"}
+{"version":3,"file":"ParticipatingMediaVolume.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/ParticipatingMediaVolume.js"],"names":[],"mappings":"AAKA;IA6EI;;;;OAIG;IACH,+BAHW;QAAC,wBAAwB,CAAC;QAAC,wBAAwB,CAAC;QAAC,MAAM,CAAC;QAAC,CAAC,CAAA;KAAC,GAC9D,uBAAuB,CAalC;IAED,oDAIC;IAlGD;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX,UAAQ;IAER,iCAIC;IAED;;;OAGG;IACH,YAFW,uBAAuB,QAOjC;IAED;;;;;aA0BC;IAED;;;OAGG;IACH,cAHW,uBAAuB,GACrB,OAAO,CAOnB;CAyBJ;AAED,6EAKI;AAIJ;IAII,iBAEC;IAED;;;OAGG;IACH,aAFU,MAAM,EAAE,CAEM;IACxB,0BAA4B;IAC5B,uBAAyB;IAEzB;;;OAGG;IACH,gBAFU,MAAM,EAAE,CAES;IAE3B;;;OAGG;IACH,uBAFU,MAAM,EAAE,CAEgB;IAElC;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;OAGG;IACH,gBAAc;IAEd;;;;;;;;;OASG;IACH,mCAEC;IAED,uCAA+E;IAE/E;;;;;;OAMG;IACH,eAFU,MAAM,CAEI;IAEpB;;;;;;;;;;;OAWG;IACH,WAFU,WAAW,CAES;;CAEjC;4BAhM2B,8CAA8C"}

package/src/shade/renderer/volumetrics/ParticipatingMediaVolume.js

@@ -182,6 +182,13 @@ export class ParticipatingMediaVolume {
     /**
      * Defines actual scale, orientation and world position of the volume.
      * The base size of the volume is 1, centered at 0,0,0
+     *
+     * What reaches the GPU is the *matrix*, and its inverse - `GPUSceneVolumetrics` reads nothing
+     * else. A `Transform64` does not maintain one, so a volume posed by writing components owes an
+     * {@link Transform64#updateMatrix} before it is drawn; one posed by writing the matrix, as
+     * `ParticipatingMediaSystem` does through `fromMatrix`, owes nothing. Skip it and the volume is
+     * a unit cube at the right place, which reads as a volume that is simply not there.
+     *
      * @type {Transform64}
      */
     transform = new Transform64();

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

@@ -1,112 +0,0 @@
-import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
-import { sphere_fibonacci_point } from "../../../../core/geom/3d/sphere/sphere_fibonacci_point.js";
-import { random_orthonormal_basis } from "../../../../core/geom/random/random_orthonormal_basis.js";
-import { v3_matrix3_rotate } from "../../../../core/geom/vec3/v3_matrix3_rotate.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)
-        random_orthonormal_basis(ROTATION, 0, random);
-
-        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);
-    }
-}

package/src/shade/renderer/particles/runtime/ProgramArena.d.ts

@@ -1,115 +0,0 @@
-/**
- * Packs many compiled {@link ../isa/ParticleProgram.js} programs into one shared buffer — a header,
- * every program's constant pool, then every program's instruction words — and hands back the
- * offsets each emitter records.
- *
- * Data before code, behind a four-word header whose first word says where the code starts: the VM
- * reads both sections through one binding (a storage buffer per stage is not free, and code and
- * constants are read together), and an emitter's constant pool sits next to the pools of the
- * programs it shares a wave with.
- *
- * Because VM instructions carry no absolute code addresses (control flow is branchless) and
- * constant references are program-local (the VM adds the emitter's `constant_offset`), programs
- * can be concatenated at any offset. INIT and UPDATE sections are laid out back-to-back per program.
- */
-export class ProgramArena {
-    /**
-     * Flat instruction words, every program's INIT and UPDATE sections concatenated.
-     * @type {number[]}
-     */
-    instruction_words: number[];
-    /**
-     * Flat constant words (f32 bit patterns), every program's pool concatenated.
-     * @type {number[]}
-     */
-    constant_words: number[];
-    /**
-     * Running instruction index — INIT/UPDATE offsets are in these units.
-     * @type {number}
-     */
-    instruction_count: number;
-    /**
-     * Running constant word index — the pool is addressed by word, so a scalar literal costs one
-     * rather than the four a `vec4` entry used to.
-     * @type {number}
-     */
-    constant_word_count: number;
-    /**
-     * Slots the hungriest program in the arena needs — the maximum of every added program's
-     * `register_count`.
-     *
-     * This is the number that picks an interpreter. It is a property of the SET, not of a program:
-     * one program past {@link ../ParticleConstants.js PARTICLE_VM_FAST_REGISTER_SLOTS} moves every
-     * pass in the system onto the wide register file, including the emitters whose programs would
-     * have fit. Per-program dispatch would be the other design, and a much larger one — two pipelines
-     * live at once, the coherence pass's buckets split along a second axis, and two indirect
-     * commands to size. This is a fallback for a case that should not arise, so it is the whole
-     * system or none of it.
-     *
-     * @type {number}
-     */
-    register_high_water: number;
-    /**
-     * Whether the arena holds a program the fast interpreter's register file cannot hold, and the
-     * system must therefore run on {@link ../vm/chunk_particle_vm_registers_wide.js}.
-     *
-     * Monotonic in practice: removing an emitter does not remove its program from the arena (ids are
-     * dense and buckets are keyed on them), so once the set has seen a wide program it stays wide
-     * until the arena itself is rebuilt.
-     *
-     * @returns {boolean}
-     */
-    get requires_wide_registers(): boolean;
-    /**
-     * Content key -> the placement the first identical program got.
-     * @type {Map<string, {init_offset: number, init_count: number, update_offset: number, update_count: number, constant_offset: number, program_id: number}>}
-     */
-    programs: Map<string, {
-        init_offset: number;
-        init_count: number;
-        update_offset: number;
-        update_count: number;
-        constant_offset: number;
-        program_id: number;
-    }>;
-    /**
-     * Number of distinct programs in the arena — and therefore the number of buckets the
-     * simulation-order pass histograms into. Program ids are dense in `[0, program_count)`.
-     * @returns {number}
-     */
-    get program_count(): number;
-    /**
-     * Append a program, or hand back the placement an identical one already has.
-     *
-     * Deduplication is by CONTENT, not object identity: two emitters that authored the same graph
-     * separately compile to distinct {@link ParticleProgram} objects holding the same bytecode, and
-     * they should still land in one simulation bucket. Emitters are few and long-lived, so hashing
-     * the words is not a cost worth avoiding.
-     *
-     * The `program_id` it returns is what the emitter record carries and what the coherence pass
-     * buckets on. Keying on the emitter index instead would be simpler but strictly worse: N
-     * emitters running one shared effect would become N buckets, each padded to a whole workgroup,
-     * which both wastes lanes and splits a run that was already program-coherent.
-     *
-     * @param {import("../isa/ParticleProgram.js").ParticleProgram} program
-     * @returns {{init_offset: number, init_count: number, update_offset: number, update_count: number, constant_offset: number, program_id: number}}
-     */
-    add(program: import("../isa/ParticleProgram.js").ParticleProgram): {
-        init_offset: number;
-        init_count: number;
-        update_offset: number;
-        update_count: number;
-        constant_offset: number;
-        program_id: number;
-    };
-    /**
-     * The packed buffer: `[header][constants][code]`. Word {@link PARTICLE_PROGRAM_CODE_BASE_WORD} of
-     * the header is the word index the code starts at, which moves every time a program's constants
-     * are appended — the emitter records never carry it, they carry offsets into each section.
-     *
-     * @returns {Uint32Array}
-     */
-    build_program_buffer(): Uint32Array;
-    #private;
-}
-//# sourceMappingURL=ProgramArena.d.ts.map

package/src/shade/renderer/particles/runtime/ProgramArena.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ProgramArena.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ProgramArena.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;GAaG;AACH;IAEI;;;OAGG;IACH,mBAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,gBAFU,MAAM,EAAE,CAEE;IAEpB;;;OAGG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;;;;;;;;;;;OAaG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;;;;;;;OASG;IACH,uCAEC;IAED;;;OAGG;IACH,UAFU,IAAI,MAAM,EAAE;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAErI;IAErB;;;;OAIG;IACH,4BAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,aAHW,OAAO,2BAA2B,EAAE,eAAe;qBACnC,MAAM;oBAAc,MAAM;uBAAiB,MAAM;sBAAgB,MAAM;yBAAmB,MAAM;oBAAc,MAAM;MAkC9I;IAUD;;;;;;OAMG;IACH,wBAFa,WAAW,CAcvB;;CACJ"}