@woosh/meep-engine 3.46.0 → 3.49.0

package/src/core/geom/3d/quaternion/quat3_look_rotation.js

@@ -0,0 +1,172 @@
+import { assert } from "../../../assert.js";
+
+/**
+ * @param {number} length
+ * @returns {number} what normalises a vector of that length: `1 / length`, or 1 for a zero vector, which
+ *   leaves it as it is
+ */
+function inverse_or_one(length) {
+    return length === 0 ? 1 : 1 / length;
+}
+
+/**
+ * The rotation that points local +Z along `forward`, with local +Y turned as close to `up` as it can be:
+ * the orientation of a camera, a turret or a walking body told where to face.
+ *
+ * Neither vector has to be unit length, within what their squares can hold: lanes from about 1e-154
+ * to 1e154. Below that a square is 0 and the vector reads as zero, above it Infinity. The frame is built
+ * from them the usual way — `right = up × forward` and `up' = forward × right`, each normalised — and the
+ * rotation is read off that matrix, so it maps +X to `right`, +Y to `up'` and +Z to `forward`.
+ *
+ * **When `up` is parallel to `forward` there is no frame to build**: their cross product is the zero
+ * vector, and any roll about `forward` would do. The forward direction is then nudged by 0.001 along X
+ * when `up` is ±Z, and along Z otherwise, and renormalised. For a unit `up` the answer is then a unit
+ * rotation within about a milliradian of `forward`, rolled however the nudge leaves it; do not rely on
+ * the roll there. The ±Z test reads `|uz| === 1`, so a longer `up` along Z is nudged along Z, stays
+ * parallel, and gets a rotation that is not unit length. Pass a unit `up` where it can be parallel.
+ *
+ * Sign convention: `(x, y, z, w)` — `w` last, matching {@link Quaternion} and the rest of the
+ * `core/geom/3d/quaternion/` family.
+ *
+ * Everything is worked in locals and only the result is written, so it allocates nothing, and a caller
+ * that hands its own parameters straight on boxes nothing either. {@link Quaternion#_lookRotation} and
+ * `t64_look_rotation` both answer through this.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset offset into `out`; receives 4 floats (x, y, z, w)
+ * @param {number} fx forward, any length
+ * @param {number} fy
+ * @param {number} fz
+ * @param {number} ux up, any length
+ * @param {number} uy
+ * @param {number} uz
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quat3_look_rotation(out, out_offset, fx, fy, fz, ux, uy, uz) {
+    assert.isFinite(fx, 'fx');
+    assert.isFinite(fy, 'fy');
+    assert.isFinite(fz, 'fz');
+    assert.isFinite(ux, 'ux');
+    assert.isFinite(uy, 'uy');
+    assert.isFinite(uz, 'uz');
+
+    /*
+     Forward, normalised; a zero vector is left as it is.
+
+     Every normalisation here scales unconditionally, by 1 for a zero vector, which leaves each lane as it
+     was bit for bit. Written as `if (length !== 0) { ax *= 1 / length; }` it merged a computed number
+     with the incoming argument, and V8 then held `ax` as a boxed number: 32 B a call.
+    */
+    let scale = inverse_or_one(Math.sqrt(fx * fx + fy * fy + fz * fz));
+
+    let ax = fx * scale;
+    let ay = fy * scale;
+    let az = fz * scale;
+
+    // right = up × forward
+    let cx = uy * az - uz * ay;
+    let cy = uz * ax - ux * az;
+    let cz = ux * ay - uy * ax;
+
+    if (cx * cx + cy * cy + cz * cz === 0) {
+        // up and forward are parallel; adjust forward slightly, as three.js does
+        // https://github.com/mrdoob/three.js/blob/88e8954b69377dad4ad1ceaf1a383f3536e88e5a/src/math/Matrix4.js#L304
+
+        if (Math.abs(uz) === 1) {
+            ax += 0.001;
+        } else {
+            az += 0.001;
+        }
+
+        scale = inverse_or_one(Math.sqrt(ax * ax + ay * ay + az * az));
+
+        ax *= scale;
+        ay *= scale;
+        az *= scale;
+
+        cx = uy * az - uz * ay;
+        cy = uz * ax - ux * az;
+        cz = ux * ay - uy * ax;
+    }
+
+    scale = inverse_or_one(Math.sqrt(cx * cx + cy * cy + cz * cz));
+
+    cx *= scale;
+    cy *= scale;
+    cz *= scale;
+
+    // up' = forward × right
+    const bx = ay * cz - az * cy;
+    const by = az * cx - ax * cz;
+    const bz = ax * cy - ay * cx;
+
+    // the rotation of the matrix whose columns are right, up' and forward
+    const m11 = cx, m12 = bx, m13 = ax;
+    const m21 = cy, m22 = by, m23 = ay;
+    const m31 = cz, m32 = bz, m33 = az;
+
+    const trace = m11 + m22 + m33;
+
+    let x, y, z, w, s;
+
+    if (trace > 0) {
+
+        s = Math.sqrt(trace + 1.0);
+
+        w = 0.5 * s;
+
+        s = 0.5 / s;
+
+        x = (m32 - m23) * s;
+        y = (m13 - m31) * s;
+        z = (m21 - m12) * s;
+
+    } else if (m11 > m22 && m11 > m33) {
+
+        s = Math.sqrt(1.0 + m11 - m22 - m33);
+
+        x = 0.5 * s;
+
+        s = 0.5 / s;
+
+        w = (m32 - m23) * s;
+        y = (m12 + m21) * s;
+        z = (m13 + m31) * s;
+
+    } else if (m22 > m33) {
+
+        s = Math.sqrt(1.0 + m22 - m11 - m33);
+
+        y = 0.5 * s;
+
+        s = 0.5 / s;
+
+        w = (m13 - m31) * s;
+        x = (m12 + m21) * s;
+        z = (m23 + m32) * s;
+
+    } else {
+
+        s = Math.sqrt(1.0 + m33 - m11 - m22);
+
+        z = 0.5 * s;
+
+        s = 0.5 / s;
+
+        w = (m21 - m12) * s;
+        x = (m13 + m31) * s;
+        y = (m23 + m32) * s;
+
+    }
+
+    // Finite inputs can still come out NaN, when a square or a cross product overflows. One check of one
+    // boolean, so a build keeping assertions boxes nothing for it.
+    assert.ok(x === x && y === y && z === z && w === w, 'look rotation is NaN: forward or up is too large for its square');
+
+    out[out_offset] = x;
+    out[out_offset + 1] = y;
+    out[out_offset + 2] = z;
+    out[out_offset + 3] = w;
+}

package/src/core/geom/Quaternion.d.ts

@@ -125,6 +125,7 @@ export class Quaternion extends Float64Array implements Iterable<number> {
      * @param {number} uy up vector
      * @param {number} uz up vector
      * @returns {this}
+     * @see quat3_look_rotation the arithmetic, which this hands its arguments to unchanged
      */
     _lookRotation(fx: number, fy: number, fz: number, ux: number, uy: number, uz: number): this;
     /**

package/src/core/geom/Quaternion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Quaternion.d.ts","sourceRoot":"","sources":["../../../../src/core/geom/Quaternion.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"Quaternion.d.ts","sourceRoot":"","sources":["../../../../src/core/geom/Quaternion.js"],"names":[],"mappings":"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"}

package/src/core/geom/Quaternion.js

@@ -8,6 +8,7 @@ import { epsilonEquals } from "../math/epsilonEquals.js";
 import { lerp } from "../math/lerp.js";
 import { PI2 } from "../math/PI2.js";
 import { computeHashFloat } from "../primitives/numbers/computeHashFloat.js";
+import { quat3_look_rotation } from "./3d/quaternion/quat3_look_rotation.js";
 import { v3_dot } from "./vec3/v3_dot.js";
 import { v4_length } from "./vec4/v4_length.js";
 import Vector3 from "./Vector3.js";
@@ -17,8 +18,13 @@ import Vector3 from "./Vector3.js";
  */
 
 const scratch_v3_a = new Vector3();
-const scratch_v3_b = new Vector3();
-const scratch_v3_c = new Vector3();
+
+/**
+ * Where {@link Quaternion#_lookRotation} has its answer worked out before setting it.
+ *
+ * @type {Float64Array}
+ */
+const scratch_rotation = new Float64Array(4);
 
 const sin = Math.sin;
 const cos = Math.cos;
@@ -158,58 +164,16 @@ export class Quaternion extends Float64Array {
      * @param {number} uy up vector
      * @param {number} uz up vector
      * @returns {this}
+     * @see quat3_look_rotation the arithmetic, which this hands its arguments to unchanged
      */
     _lookRotation(
         fx, fy, fz,
         ux, uy, uz
     ) {
+        quat3_look_rotation(scratch_rotation, 0, fx, fy, fz, ux, uy, uz);
 
-        scratch_v3_a.set(fx, fy, fz);
-        scratch_v3_a.normalize();
-
-        scratch_v3_c._crossVectors(ux, uy, uz, scratch_v3_a.x, scratch_v3_a.y, scratch_v3_a.z);
-
-        if (scratch_v3_c.lengthSq() === 0) {
-            // up and forward are parallel
-
-            /*
-             adjust forward direction slightly
-             code take from : https://github.com/mrdoob/three.js/blob/88e8954b69377dad4ad1ceaf1a383f3536e88e5a/src/math/Matrix4.js#L304
-             */
-
-            if (Math.abs(uz) === 1) {
-                scratch_v3_a.x += 0.001;
-            } else {
-                scratch_v3_a.z += 0.001;
-            }
-
-            scratch_v3_a.normalize();
-            scratch_v3_c._crossVectors(ux, uy, uz, scratch_v3_a.x, scratch_v3_a.y, scratch_v3_a.z);
-
-        }
-
-        scratch_v3_c.normalize();
-
-        scratch_v3_b.crossVectors(scratch_v3_a, scratch_v3_c);
-
-        // construct partial transform matrix
-        const m00 = scratch_v3_c.x;
-        const m10 = scratch_v3_c.y;
-        const m20 = scratch_v3_c.z;
-
-        const m01 = scratch_v3_b.x;
-        const m11 = scratch_v3_b.y;
-        const m21 = scratch_v3_b.z;
-
-        const m02 = scratch_v3_a.x;
-        const m12 = scratch_v3_a.y;
-        const m22 = scratch_v3_a.z;
-
-        return this.__setFromRotationMatrix(
-            m00, m01, m02,
-            m10, m11, m12,
-            m20, m21, m22
-        );
+        // through set(), so the change is announced as any other write is
+        return this.set(scratch_rotation[0], scratch_rotation[1], scratch_rotation[2], scratch_rotation[3]);
     }
 
     /**

package/src/engine/Engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../../src/engine/Engine.js"],"names":[],"mappings":";6BAqCa,OAAO,8BAA8B,EAAE,cAAc;AAwClE;IA4FI;;;;;;;;;OASG;IACH,sBARW,cAAc;QAEU,aAAa,GAArC,aAAa;QACK,cAAc,GAAhC,OAAO;QACW,WAAW,GAA7B,OAAO;QACW,KAAK,GAAvB,OAAO;OAiPjB;IAtSD;;;OAGG;IACH,UAFU,cAAc,GAAC,IAAI,CAEb;IAEhB;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb,qBAA4B;IAE5B;;;;;;;;;OASG;IACH,0BAFU,uBAAuB,CAEe;IAEhD;;;OAGG;IACH,kBAFU,mBAAmB,CAEO;IAEpC;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,mBAFU,kBAAkB,CAEa;IAoBrC;;;OAGG;IACH,UAFU,cAAc,CAEA;IAKxB;;;OAGG;IACH,aAFU,gBAAgB,CAEe;IAGzC,yCAAkE;IAK9D,6BAAkC;IAMtC;;;OAGG;IACH,cAFU,aAAa,MAAM,CAAC,CAK5B;IAEF,8CAiCE;IAgCF;;;OAGG;IACH,SAFU,WAAW,CAEoB;IAEzC;;;OAGG;IACH,oCAA0C;IAE1C;;;OAGG;IACH,sCAFU,2BAA2B,CAE+B;IAEpE,yBAAoC;IAGpC;;OAEG;IACH,aAAkB;IAElB;;;OAGG;IACH,SAFU,OAAO,CAEwB;IAGzC,2BAAsC;IAuCtC;;;OAGG;IACH,KAFU,SAAS,CAEO;IAE1B;;;OAGG;IACH,uBAFU,YAAY,CAEqD;IAI3E;;;;;MAKC;IA8BD;;;OAGG;IACH,kBAFU,OAAO,CAEW;IAwIhC,wBAgCC;IApBG,oBAAwB;IAsB5B,2BA8CC;IAED,oBAiBC;IAED;;;OAGG;IACH,+CAUC;IAED,eAkDC;IAED;;;OAGG;IACH,sBA0GC;IAoBD;;OAEG;IACH,sBA+DC;IAED,aAEC;IAED;;OAEG;IACH,4BAOC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB;+BA94B8B,+BAA+B;wBAWtC,wBAAwB;0BArBtB,0CAA0C;wCAeN,iDAAiD;oCAG3E,iCAAiC;mBAElD,wBAAwB;+BAtBZ,gDAAgD;iCAO9C,+CAA+C;8BAGlD,wBAAwB;6BALzB,yBAAyB;uCAIf,6DAA6D;4BAUxE,0BAA0B;+BArBvB,iCAAiC;4CAapB,qDAAqD;AAgBjG;;GAEG;AAGH;IACI,gDAA2D;IAC3D,0BAAkC;IAClC,iCAAyC;CAC5C;6BAvC4B,sCAAsC;sBA4B7C,mBAAmB;yBAJhB,yBAAyB;8BALpB,kCAAkC;2BADrC,mCAAmC;8BAFhC,kCAAkC;8BAClC,kCAAkC;sBAb1C,+BAA+B;+BAKtB,qCAAqC;4BAPxC,kCAAkC;oBAH1C,yBAAyB"}
+{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../../src/engine/Engine.js"],"names":[],"mappings":";6BAqCa,OAAO,8BAA8B,EAAE,cAAc;AAwClE;IA4FI;;;;;;;;;OASG;IACH,sBARW,cAAc;QAEU,aAAa,GAArC,aAAa;QACK,cAAc,GAAhC,OAAO;QACW,WAAW,GAA7B,OAAO;QACW,KAAK,GAAvB,OAAO;OAiPjB;IAtSD;;;OAGG;IACH,UAFU,cAAc,GAAC,IAAI,CAEb;IAEhB;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb,qBAA4B;IAE5B;;;;;;;;;OASG;IACH,0BAFU,uBAAuB,CAEe;IAEhD;;;OAGG;IACH,kBAFU,mBAAmB,CAEO;IAEpC;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,mBAFU,kBAAkB,CAEa;IAoBrC;;;OAGG;IACH,UAFU,cAAc,CAEA;IAKxB;;;OAGG;IACH,aAFU,gBAAgB,CAEe;IAGzC,yCAAkE;IAK9D,6BAAkC;IAMtC;;;OAGG;IACH,cAFU,aAAa,MAAM,CAAC,CAK5B;IAEF,8CAiCE;IAgCF;;;OAGG;IACH,SAFU,WAAW,CAEoB;IAEzC;;;OAGG;IACH,oCAA0C;IAE1C;;;OAGG;IACH,sCAFU,2BAA2B,CAE+B;IAEpE,yBAAoC;IAGpC;;OAEG;IACH,aAAkB;IAElB;;;OAGG;IACH,SAFU,OAAO,CAEwB;IAGzC,2BAAsC;IAuCtC;;;OAGG;IACH,KAFU,SAAS,CAEO;IAE1B;;;OAGG;IACH,uBAFU,YAAY,CAEqD;IAI3E;;;;;MAKC;IA8BD;;;OAGG;IACH,kBAFU,OAAO,CAEW;IA6IhC,wBAgCC;IApBG,oBAAwB;IAsB5B,2BA8CC;IAED,oBAiBC;IAED;;;OAGG;IACH,+CAUC;IAED,eAkDC;IAED;;;OAGG;IACH,sBA0GC;IAoBD;;OAEG;IACH,sBA+DC;IAED,aAEC;IAED;;OAEG;IACH,4BAOC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB;+BAn5B8B,+BAA+B;wBAWtC,wBAAwB;0BArBtB,0CAA0C;wCAeN,iDAAiD;oCAG3E,iCAAiC;mBAElD,wBAAwB;+BAtBZ,gDAAgD;iCAO9C,+CAA+C;8BAGlD,wBAAwB;6BALzB,yBAAyB;uCAIf,6DAA6D;4BAUxE,0BAA0B;+BArBvB,iCAAiC;4CAapB,qDAAqD;AAgBjG;;GAEG;AAGH;IACI,gDAA2D;IAC3D,0BAAkC;IAClC,iCAAyC;CAC5C;6BAvC4B,sCAAsC;sBA4B7C,mBAAmB;yBAJhB,yBAAyB;8BALpB,kCAAkC;2BADrC,mCAAmC;8BAFhC,kCAAkC;8BAClC,kCAAkC;sBAb1C,+BAA+B;+BAKtB,qCAAqC;4BAPxC,kCAAkC;oBAH1C,yBAAyB"}

package/src/engine/Engine.js

@@ -477,10 +477,12 @@ class Engine {
     }
 
     /**
-     * @param {ShadeDeviceFailure} reason carries a message written to be shown to a person
+     * There is no usable device, so there will be no rendering at all.
+     *
+     * @param {ShadeDeviceFailure} failure carries a message written to be shown to a person
      */
-    #handle_context_failed(reason) {
-        logger.error(`Graphics context recovery abandoned (${reason}), no further rendering is possible`);
+    #handle_context_failed(failure) {
+        logger.error(`Graphics could not start (${failure}), no rendering is possible`);
 
         this.#clear_context_loss_pause_timer();
 
@@ -488,7 +490,10 @@ class Engine {
         // Application state is left intact, which keeps a save-on-failure handler viable.
         this.#pause_simulation_for_context_loss();
 
-        this.viewStack.addChild(new GraphicsContextFailureView());
+        this.viewStack.addChild(new GraphicsContextFailureView({
+            title: 'Graphics unavailable',
+            text: failure.message,
+        }));
     }
 
     #initialize_audio() {

package/src/engine/ecs/async/WORKER_SYSTEM_PLAN.md

@@ -189,18 +189,34 @@ and the sampling API are untouched. Two things the caller must do:
 it worker-owned between dispatch and the next join. Precisely:
 
 - Systems that touch fluid fields must run **earlier in the fixed pass** than
-  `WorkerFluidSystem`. Note this is *not* controlled by registration order:
-  `updateExecutionOrder` sorts by a score derived from `components_used`, and
-  registration order only breaks exact ties. `FluidObstacleSystem` does sort
-  first today, in both registration orders, and `WorkerFluidSystem.spec.js` pins
-  that as a standing assertion — because if the scheduler ever reorders the two,
-  the symptom is a silent data race rather than a visible failure.
+  `WorkerFluidSystem`. Note this is *not* controlled by registration order: the
+  order is derived from `components_used` (`orderSystemsByDeclaredAccess` — a
+  writer runs before a same-pass reader, and the score picks among free systems
+  and decides which member of a cycle runs first). Two systems touch the field
+  from outside the fluid step. Each is on a cycle with `WorkerFluidSystem`, so
+  the **score** puts it first, and a spec holds each there in both registration
+  orders as a standing assertion — because if the scheduler ever reorders them,
+  the symptom is a silent data race rather than a visible failure:
+  - `FluidObstacleSystem` writes solid masks. It and `WorkerFluidSystem` both read
+    and write `FluidComponent` (20 against 11 in a game-like composition);
+    `WorkerFluidSystem.spec.js` holds it first.
+  - Cloth (`ClothSystem`, `WorkerClothSystem`) reads the velocity field through
+    `ClothFluidWind`, once a tick in `ClothWorld#advance`, and declares that
+    read. It also writes the `Transform64` every fluid system reads, so the edges
+    run both ways (cloth 49 against `WorkerFluidSystem`'s 15);
+    `cloth_wind.spec.js` holds cloth first. Before the read was declared, the
+    `Transform64` edge alone ran it first: measured 2026-10-16 over all four
+    cloth × fluid pairs and a census of every `System` subclass, and declaring
+    it flipped no cloth–fluid pair. There, step `T − 1` has landed (the gate)
+    and step `T` is not yet dispatched, so cloth reads a complete field — under
+    either fluid system the one step `T − 1` left.
 - `update()`-phase and render-phase readers see a step in progress. **Today there
-  are no such readers** — the fluid package has no consumers anywhere else in the
-  codebase (verified) — so the exposure is zero, but it is a real constraint and is
-  documented on the class. The escape hatch, if a reader ever appears, is a
-  double-buffered publish slot (2× memory, one worker-side copy per step); not
-  built now because it would erase most of the zero-copy win for a hypothetical.
+  are no such readers** — cloth is the one consumer outside the fluid package, and
+  it reads inside the fixed pass, above — so the exposure is zero, but it is a real
+  constraint and is documented on the class. The escape hatch, if a reader ever
+  appears, is a double-buffered publish slot (2× memory, one worker-side copy per
+  step); not built now because it would erase most of the zero-copy win for a
+  hypothetical.
 
 ### Latency
 

package/src/engine/ecs/storage/populateEngineSerializationRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"populateEngineSerializationRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/storage/populateEngineSerializationRegistry.js"],"names":[],"mappings":"AAwLA;;;;;;;;GAQG;AACH,iGAiHC"}
+{"version":3,"file":"populateEngineSerializationRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/storage/populateEngineSerializationRegistry.js"],"names":[],"mappings":"AAsMA;;;;;;;;GAQG;AACH,iGAwHC"}

package/src/engine/ecs/storage/populateEngineSerializationRegistry.js

@@ -6,6 +6,10 @@ import {
 import { Tag } from "../components/Tag.js";
 import { TagSerializationAdapter } from "../components/TagSerializationAdapter.js";
 import { TagSerializationUpgrader_0_1 } from "../components/TagSerializationUpgrader_0_1.js";
+import { ParticipatingMedia } from "../../graphics3/ParticipatingMedia.js";
+import {
+    ParticipatingMediaSerializationUpgrader_0_1
+} from "../../graphics3/ParticipatingMediaSerializationUpgrader_0_1.js";
 import { FogOfWar } from "../fow/FogOfWar.js";
 import {
     FogOfWarRevealerSerializationAdapter
@@ -44,9 +48,13 @@ import {
 } from "../../graphics3/VolumetricLightMapSerializationAdapter.js";
 import { Transform } from "../transform/Transform.js";
 import { Transform64SerializationAdapter } from "../transform/Transform64SerializationAdapter.js";
+import { ParticleEffect } from "../../graphics/ecs/particles/ParticleEffect.js";
 import {
     ParticleEffectSerializationAdapter
 } from "../../graphics/ecs/particles/ParticleEffectSerializationAdapter.js";
+import {
+    ParticleEffectSerializationUpgrader_1_2
+} from "../../graphics/ecs/particles/ParticleEffectSerializationUpgrader_1_2.js";
 import { TransformSerializationAdapter } from "../transform/TransformSerializationAdapter.js";
 import { TransformSerializationUpgrader_0_1 } from "../transform/TransformSerializationUpgrader_0_1.js";
 import {
@@ -172,6 +180,12 @@ import {
 import { SoundControllerSerializationAdapter } from "../../sound/sopra/legacy/SoundController.js";
 import { SoundListenerSerializationAdapter } from "../../sound/ecs/SoundListener.js";
 import { AudioEmitterSerializationAdapter } from "../../sound/ecs/audio/AudioEmitterSerializationAdapter.js";
+import { AudioEmitterSerializationUpgrader_0_1 } from "../../sound/ecs/audio/AudioEmitterSerializationUpgrader_0_1.js";
+import { AudioEmitter } from "../../sound/ecs/audio/AudioEmitter.js";
+import {
+    AudioEventTriggerSerializationUpgrader_0_1
+} from "../../sound/ecs/trigger/AudioEventTriggerSerializationUpgrader_0_1.js";
+import { AudioEventTrigger } from "../../sound/ecs/trigger/AudioEventTrigger.js";
 import {
     AudioEventTriggerSerializationAdapter
 } from "../../sound/ecs/trigger/AudioEventTriggerSerializationAdapter.js";
@@ -271,6 +285,7 @@ export function populateEngineSerializationRegistry(registry) {
     registry.registerUpgrader(GridPosition.typeName, new GridPositionSerializationUpdater_0_1());
     registry.registerUpgrader(Transform.typeName, new TransformSerializationUpgrader_0_1());
     registry.registerUpgrader(Tag.typeName, new TagSerializationUpgrader_0_1());
+    registry.registerUpgrader(ParticipatingMedia.typeName, new ParticipatingMediaSerializationUpgrader_0_1());
     registry.registerUpgrader(Decal.typeName, new DecalSerializationUpgrader_0_1());
 
     registry.registerUpgrader(FogOfWar.typeName, new FogOfWarSerializationUpdater_0_1());
@@ -282,6 +297,8 @@ export function populateEngineSerializationRegistry(registry) {
     registry.registerUpgrader(Path.typeName, new PathSerializationUpgrader_1_2());
     registry.registerUpgrader(Path.typeName, new PathSerializationUpgrader_2_3());
 
+    registry.registerUpgrader(ParticleEffect.typeName, new ParticleEffectSerializationUpgrader_1_2());
+
     registry.registerUpgrader(PathFollower.typeName, new PathFollowerSerializationUpgrader_0_1());
     registry.registerUpgrader(PathFollower.typeName, new PathFollowerSerializationUpgrader_1_2());
     registry.registerUpgrader(PathFollower.typeName, new PathFollowerSerializationUpgrader_2_3());
@@ -300,6 +317,10 @@ export function populateEngineSerializationRegistry(registry) {
     registry.registerUpgrader(SoundEmitter.typeName, new SoundEmitterSerializationUpgrader_0_1());
     registry.registerUpgrader(SoundEmitter.typeName, new SoundEmitterSerializationUpgrader_1_2());
 
+    // both embed an EventDescription record, so they take a registry to read its clip tree
+    registry.registerUpgrader(AudioEmitter.typeName, new AudioEmitterSerializationUpgrader_0_1(registry));
+    registry.registerUpgrader(AudioEventTrigger.typeName, new AudioEventTriggerSerializationUpgrader_0_1(registry));
+
     registry.registerUpgrader(TopDownCameraController.typeName, new TopDownCameraControllerSerializationUpgrader_0_1());
 
     registry.registerUpgrader(ClingToTerrain.typeName, new ClingToTerrainSerializationUpgrader_0_1());

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

@@ -1,10 +1,10 @@
 /**
  * Orient a {@link Transform64} so its local +Z axis points along `(fx, fy, fz)`.
  *
- * The {@link Transform64} counterpart of `Quaternion._lookRotation`, and it defers to exactly that
- * — the interesting part of the computation is the case where `up` and the forward direction are
- * parallel, and there is no reason for a second copy of it to exist. `Quaternion` is itself f64, so
- * routing through one costs no precision.
+ * The {@link Transform64} counterpart of `Quaternion._lookRotation`; both are
+ * {@link quat3_look_rotation}, which also says what happens when `up` and the forward direction are
+ * parallel. This writes the rotation lanes in place and hands its arguments on unchanged, so it
+ * allocates nothing — it runs once per body per frame in a game that faces a crowd where it walks.
  *
  * Nothing here is normalized on the way in, and nothing touches `t64`'s matrix on the way out —
  * call {@link Transform64.updateMatrix} once you are done setting components.

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

@@ -1 +1 @@
-{"version":3,"file":"t64_look_rotation.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/t64_look_rotation.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wDAPW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAWhB"}
+{"version":3,"file":"t64_look_rotation.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/t64_look_rotation.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wDAPW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAIhB"}

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

@@ -1,17 +1,13 @@
-import { Quaternion } from "../../../core/geom/Quaternion.js";
-
-/**
- * @type {Quaternion}
- */
-const SCRATCH_ROTATION = new Quaternion();
+import { quat3_look_rotation } from "../../../core/geom/3d/quaternion/quat3_look_rotation.js";
+import { TRANSFORM64_ROTATION_OFFSET } from "./Transform64.js";
 
 /**
  * Orient a {@link Transform64} so its local +Z axis points along `(fx, fy, fz)`.
  *
- * The {@link Transform64} counterpart of `Quaternion._lookRotation`, and it defers to exactly that
- * — the interesting part of the computation is the case where `up` and the forward direction are
- * parallel, and there is no reason for a second copy of it to exist. `Quaternion` is itself f64, so
- * routing through one costs no precision.
+ * The {@link Transform64} counterpart of `Quaternion._lookRotation`; both are
+ * {@link quat3_look_rotation}, which also says what happens when `up` and the forward direction are
+ * parallel. This writes the rotation lanes in place and hands its arguments on unchanged, so it
+ * allocates nothing — it runs once per body per frame in a game that faces a crowd where it walks.
  *
  * Nothing here is normalized on the way in, and nothing touches `t64`'s matrix on the way out —
  * call {@link Transform64.updateMatrix} once you are done setting components.
@@ -25,12 +21,5 @@ const SCRATCH_ROTATION = new Quaternion();
  * @param {number} uz up
  */
 export function t64_look_rotation(t64, fx, fy, fz, ux, uy, uz) {
-    SCRATCH_ROTATION._lookRotation(fx, fy, fz, ux, uy, uz);
-
-    t64.setRotation(
-        SCRATCH_ROTATION[0],
-        SCRATCH_ROTATION[1],
-        SCRATCH_ROTATION[2],
-        SCRATCH_ROTATION[3]
-    );
+    quat3_look_rotation(t64, TRANSFORM64_ROTATION_OFFSET, fx, fy, fz, ux, uy, uz);
 }

package/src/engine/graphics/ecs/camera/topdown/TopDownCameraControllerSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TopDownCameraControllerSystem.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/camera/topdown/TopDownCameraControllerSystem.js"],"names":[],"mappings":"AAwDA;;;;GAIG;AACH,iDAHW,uBAAuB,UACvB,WAAW,QA0BrB;AAED;;;;;GAKG;AACH,4DAJW,WAAW,cACX,uBAAuB,aACvB,MAAM,QAahB;;oCA/F+D,8BAA8B;4BAHlE,0CAA0C;AAWtE;;IACI,gCAAkC;IAClC,iDAAyC;IACzC,mEAEE;IAEF;;;;;OAKG;IACH,8BAQC;IAED,6BAaC;CACJ;uBAjDsB,2BAA2B;0BAHxB,4CAA4C;4CAE1B,0DAA0D"}
+{"version":3,"file":"TopDownCameraControllerSystem.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/camera/topdown/TopDownCameraControllerSystem.js"],"names":[],"mappings":"AAqFA;;;;GAIG;AACH,iDAHW,uBAAuB,UACvB,WAAW,QA0BrB;AAED;;;;;GAKG;AACH,4DAJW,WAAW,cACX,uBAAuB,aACvB,MAAM,QAahB;;oCA1H+D,8BAA8B;4BAHlE,0CAA0C;AAoBtE;;IACI,gCAAkC;IAClC,iDAAyC;IACzC,mEAEE;IAEF;;;;;OAKG;IACH,8BA0BC;IAED,6BAaC;CACJ;uBA9EsB,2BAA2B;0BAHxB,4CAA4C;4CAE1B,0DAA0D"}

package/src/engine/graphics/ecs/camera/topdown/TopDownCameraControllerSystem.js

@@ -4,6 +4,8 @@ import ObservedValue from "../../../../../core/model/ObservedValue.js";
 import { ResourceAccessKind } from "../../../../../core/model/ResourceAccessKind.js";
 import { ResourceAccessSpecification } from "../../../../../core/model/ResourceAccessSpecification.js";
 import { System } from '../../../../ecs/System.js';
+import { t64_announce_change } from "../../../../ecs/transform/t64_announce_change.js";
+import { t64_read_pose_array } from "../../../../ecs/transform/t64_read_pose_array.js";
 import { Transform64 } from '../../../../ecs/transform/Transform64.js';
 
 
@@ -15,6 +17,15 @@ import { v3_quaternion_apply } from "../../../../../core/geom/vec3/v3_quaternion
 const v3_scratch = new Vector3();
 const q_scratch = new Quaternion();
 
+/**
+ * A camera's translation and rotation before and after its controller rewrites them, to tell a move from
+ * a rewrite of the same pose.
+ * @type {Float64Array}
+ */
+const POSE_BEFORE = new Float64Array(7);
+/** @type {Float64Array} */
+const POSE_AFTER = new Float64Array(7);
+
 class TopDownCameraControllerSystem extends System {
     enabled = new ObservedValue(true);
     dependencies = [TopDownCameraController];
@@ -29,13 +40,31 @@ class TopDownCameraControllerSystem extends System {
      * @private
      */
     __visit_camera_entity(ctrl, entity){
-        const transform = this.entityManager.dataset.getComponent(entity,Transform64);
+        const dataset = this.entityManager.dataset;
+
+        const transform = dataset.getComponent(entity,Transform64);
 
         if(transform === undefined){
             return;
         }
 
+        t64_read_pose_array(POSE_BEFORE, 0, transform);
+
         computeTopDownTransform(ctrl,transform);
+
+        t64_read_pose_array(POSE_AFTER, 0, transform);
+
+        // A Transform64 cannot say it was written, so the writer does: this is what moves the sound
+        // listener, and everything else that follows the camera by its transform. The pose is rewritten
+        // every frame whether the controller moved or not, so it is announced only when it changed: a
+        // still camera wakes none of them.
+        for (let i = 0; i < 7; i++) {
+            if (POSE_BEFORE[i] !== POSE_AFTER[i]) {
+                t64_announce_change(dataset, entity);
+
+                return;
+            }
+        }
     }
 
     update(timeDelta) {

package/src/engine/graphics/ecs/particles/ParticleEffect.d.ts

@@ -188,8 +188,8 @@ export class ParticleEffect {
     render_size: number;
     /** @type {number} record word offset of rgba colour */
     render_color: number;
-    /** @type {number} record word offset of roll angle, radians */
-    render_rotation: number;
+    /** @type {number} record word offset of the orientation, a quaternion (x, y, z, w) turning the sprite inside its projection mode's frame */
+    render_orientation: number;
     /** @type {number} record word offset of flipbook frame index */
     render_frame: number;
     /** @type {number} record word offset of velocity, read by the STRETCHED projection */

package/src/engine/graphics/ecs/particles/ParticleEffect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleEffect.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/particles/ParticleEffect.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH;IAoRI;;;;;;;;;;;;;;;;;;OAkBG;IACH;QAZ2G,MAAM,GAAtG,OAAO,+DAA+D,EAAE,cAAc;QACS,OAAO,GAAtG,OAAO,6DAA6D,EAAE,eAAe;QAChE,OAAO,GAA5B,MAAM,GAAC,IAAI;QACK,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACW,QAAQ,GAAzB,OAAO;QACS,OAAO,GAAvB,MAAM;QACU,KAAK,GAArB,MAAM;QACyB,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACO,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACf,cAAc,CA8C1B;IAjVD;;;;;;;;;OASG;IACH,QAFU,OAAO,+DAA+D,EAAE,cAAc,GAAC,IAAI,CAEvF;IAEd;;;;;OAKG;IACH,SAFU,OAAO,6DAA6D,EAAE,eAAe,GAAC,IAAI,CAErF;IAEf;;;;;;;;;OASG;IACH,SAFU,MAAM,GAAC,IAAI,CAEN;IAEf;;;;;;;;OAQG;IACH,MAFU,MAAM,CAEP;IAET;;;;;OAKG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;OAUG;IACH,UAFU,OAAO,CAED;IAEhB;;;;;;;;;;;;;OAaG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;OAKG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;OAKG;IACH,UAFU,YAAY,CAEc;IAEpC,+FAA+F;IAC/F,iBADW,MAAM,CAC0B;IAC3C,gDAAgD;IAChD,aADW,MAAM,CACsB;IACvC,uDAAuD;IACvD,cADW,MAAM,CACuB;IACxC,+DAA+D;IAC/D,iBADW,MAAM,CAC0B;IAC3C,gEAAgE;IAChE,cADW,MAAM,CACuB;IACxC,sFAAsF;IACtF,iBADW,MAAM,CAC0B;IAE3C;;;;;OAKG;IACH,mCAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH;YAJkB,MAAM,GAAC,MAAM;QAElB,cAAc,CAuC1B;IAED;;;;;;;;;OASG;IACH,cAHW,cAAc,GACZ,OAAO,CAsBnB;IAED;;;;OAIG;IACH,QAFa,MAAM,CAuBlB;IAED;;;;;;;;;OASG;IACH,YAHW,cAAc,GACZ,cAAc,CAuB1B;IAED;;OAEG;IACH,SAFa,cAAc,CAI1B;IAgFL;;;;;OAKG;IACH,2BAFU,OAAO,CAEwB;CApBxC;;kBAUS,MAAM"}
+{"version":3,"file":"ParticleEffect.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/particles/ParticleEffect.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH;IAoRI;;;;;;;;;;;;;;;;;;OAkBG;IACH;QAZ2G,MAAM,GAAtG,OAAO,+DAA+D,EAAE,cAAc;QACS,OAAO,GAAtG,OAAO,6DAA6D,EAAE,eAAe;QAChE,OAAO,GAA5B,MAAM,GAAC,IAAI;QACK,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACW,QAAQ,GAAzB,OAAO;QACS,OAAO,GAAvB,MAAM;QACU,KAAK,GAArB,MAAM;QACyB,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACO,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACf,cAAc,CA8C1B;IAjVD;;;;;;;;;OASG;IACH,QAFU,OAAO,+DAA+D,EAAE,cAAc,GAAC,IAAI,CAEvF;IAEd;;;;;OAKG;IACH,SAFU,OAAO,6DAA6D,EAAE,eAAe,GAAC,IAAI,CAErF;IAEf;;;;;;;;;OASG;IACH,SAFU,MAAM,GAAC,IAAI,CAEN;IAEf;;;;;;;;OAQG;IACH,MAFU,MAAM,CAEP;IAET;;;;;OAKG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;OAUG;IACH,UAFU,OAAO,CAED;IAEhB;;;;;;;;;;;;;OAaG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;OAKG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;OAKG;IACH,UAFU,YAAY,CAEc;IAEpC,+FAA+F;IAC/F,iBADW,MAAM,CAC0B;IAC3C,gDAAgD;IAChD,aADW,MAAM,CACsB;IACvC,uDAAuD;IACvD,cADW,MAAM,CACuB;IACxC,4IAA4I;IAC5I,oBADW,MAAM,CAC6B;IAC9C,gEAAgE;IAChE,cADW,MAAM,CACuB;IACxC,sFAAsF;IACtF,iBADW,MAAM,CAC0B;IAE3C;;;;;OAKG;IACH,mCAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH;YAJkB,MAAM,GAAC,MAAM;QAElB,cAAc,CAuC1B;IAED;;;;;;;;;OASG;IACH,cAHW,cAAc,GACZ,OAAO,CAsBnB;IAED;;;;OAIG;IACH,QAFa,MAAM,CAuBlB;IAED;;;;;;;;;OASG;IACH,YAHW,cAAc,GACZ,cAAc,CAuB1B;IAED;;OAEG;IACH,SAFa,cAAc,CAI1B;IAgFL;;;;;OAKG;IACH,2BAFU,OAAO,CAEwB;CApBxC;;kBAUS,MAAM"}

package/src/engine/graphics/ecs/particles/ParticleEffect.js

@@ -180,8 +180,8 @@ export class ParticleEffect {
     render_size = EMITTER_ATTRIBUTE_ABSENT;
     /** @type {number} record word offset of rgba colour */
     render_color = EMITTER_ATTRIBUTE_ABSENT;
-    /** @type {number} record word offset of roll angle, radians */
-    render_rotation = EMITTER_ATTRIBUTE_ABSENT;
+    /** @type {number} record word offset of the orientation, a quaternion (x, y, z, w) turning the sprite inside its projection mode's frame */
+    render_orientation = EMITTER_ATTRIBUTE_ABSENT;
     /** @type {number} record word offset of flipbook frame index */
     render_frame = EMITTER_ATTRIBUTE_ABSENT;
     /** @type {number} record word offset of velocity, read by the STRETCHED projection */
@@ -233,8 +233,8 @@ export class ParticleEffect {
                 case "color":
                     this.render_color = offset;
                     break;
-                case "rotation":
-                    this.render_rotation = offset;
+                case "orientation":
+                    this.render_orientation = offset;
                     break;
                 case "frame":
                     this.render_frame = offset;
@@ -276,7 +276,7 @@ export class ParticleEffect {
             && this.render_position === other.render_position
             && this.render_size === other.render_size
             && this.render_color === other.render_color
-            && this.render_rotation === other.render_rotation
+            && this.render_orientation === other.render_orientation
             && this.render_frame === other.render_frame
             && this.render_velocity === other.render_velocity
             && is_typed_array_equals(this.flipbook, other.flipbook)
@@ -292,7 +292,7 @@ export class ParticleEffect {
     hash() {
         const bindings = hash_mix3(
             hash_mix3(this.render_position, this.render_size, this.render_color),
-            hash_mix3(this.render_rotation, this.render_frame, this.render_velocity),
+            hash_mix3(this.render_orientation, this.render_frame, this.render_velocity),
             this.flags
         );
 
@@ -338,7 +338,7 @@ export class ParticleEffect {
         this.render_position = other.render_position;
         this.render_size = other.render_size;
         this.render_color = other.render_color;
-        this.render_rotation = other.render_rotation;
+        this.render_orientation = other.render_orientation;
         this.render_frame = other.render_frame;
         this.render_velocity = other.render_velocity;