@woosh/meep-engine 3.46.0 → 3.47.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/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":"AA8LA;;;;;;;;GAQG;AACH,iGAqHC"}

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

@@ -172,6 +172,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";
@@ -300,6 +306,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/graphics3/GPUParticleEmitterSystem.d.ts

@@ -11,6 +11,12 @@
  * to. Layout and program are shared by reference, never copied — two entities of one effect belong
  * on one program id in the heap.
  *
+ * Every field is compared by name, and that is load-bearing rather than style. Through a shared
+ * `assign(target, field, value)` the one `target[field]` access saw all thirteen names, went
+ * megamorphic, and read numbers back boxed, while the call boxed the value it was handed: 228 B and
+ * ~120 ns per emitter per call, against nothing and ~9 ns written out like this
+ * (`GPUParticleEmitterSystem.allocation.spec.js`). This runs for every live emitter twice a frame.
+ *
  * @param {ParticleEmitter} emitter
  * @param {ParticleEffect} effect
  * @returns {boolean} whether the emitter differs from what it held before

package/src/engine/graphics3/GPUParticleEmitterSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUParticleEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GPUParticleEmitterSystem.js"],"names":[],"mappings":"AAszBA;;;;;;;;;;;;;;;;GAgBG;AACH,+CAJW,eAAe,UACf,cAAc,GACZ,OAAO,CA4BnB;AAv0BD;;;;GAIG;AAEH;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH;IAoDI;;;;;OAKG;IACH,sBALW,OAAO,qBAAqB,EAAE,cAAc,SAC5C,OAAO,qCAAqC,EAAE,KAAK,gEAgB7D;IArED,6DAA6C;IAE7C;;;OAGG;IACH,OAFU,YAAY,CAEO;IAiE7B;;;;;;OAMG;IACH,iEAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;;;;;;OAUG;IACH,mBAJW,MAAM,GACJ,eAAe,GAAC,IAAI,CAWhC;IAED;;;;;;;;;;;OAWG;IACH,cAHW,MAAM,SACN,MAAM,QA4BhB;IA6BD,+BAA+B;IAC/B,YADc,QAAQ,IAAI,CAAC,CAyB1B;IAED;;;;OAIG;IACH,aAJW,cAAc,aACd,WAAW,UACX,MAAM,QAqChB;IAED;;;;OAIG;IACH,eAJW,cAAc,aACd,WAAW,UACX,MAAM,QAIhB;IAED;;;;;;;OAOG;IACH,4BAHW,MAAM,GACJ,IAAI,CAgBhB;IAoCD;;;;;;;;;;;;OAYG;IACH,eAHW,OAAO,gDAAgD,EAAE,YAAY,GACnE,IAAI,CAqChB;;CAiWJ;;;;;gBAxxBa,MAAM;;;;WACN,OAAO,yCAAyC,EAAE,UAAU,GAAC,IAAI;;;YAKjE,MAAM;;;;YACN,cAAc;;;;eACd,WAAW;;;;aACX,eAAe,GAAC,IAAI;;;;;aACpB,OAAO,+CAA+C,EAAE,eAAe,GAAC,IAAI;gCAGjE,IAAI;;;;SACf,MAAM,GAAC,IAAI;;;;aACX,oBAAoB,GAAC,IAAI;;gCAvCP,2DAA2D;+BAS5D,6CAA6C;uBAPrD,kBAAkB;4BAEb,iCAAiC;6BAMhC,2CAA2C"}
+{"version":3,"file":"GPUParticleEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GPUParticleEmitterSystem.js"],"names":[],"mappings":"AAszBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,+CAJW,eAAe,UACf,cAAc,GACZ,OAAO,CAiFnB;AAl4BD;;;;GAIG;AAEH;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH;IAoDI;;;;;OAKG;IACH,sBALW,OAAO,qBAAqB,EAAE,cAAc,SAC5C,OAAO,qCAAqC,EAAE,KAAK,gEAgB7D;IArED,6DAA6C;IAE7C;;;OAGG;IACH,OAFU,YAAY,CAEO;IAiE7B;;;;;;OAMG;IACH,iEAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;;;;;;OAUG;IACH,mBAJW,MAAM,GACJ,eAAe,GAAC,IAAI,CAWhC;IAED;;;;;;;;;;;OAWG;IACH,cAHW,MAAM,SACN,MAAM,QA4BhB;IA6BD,+BAA+B;IAC/B,YADc,QAAQ,IAAI,CAAC,CAyB1B;IAED;;;;OAIG;IACH,aAJW,cAAc,aACd,WAAW,UACX,MAAM,QAqChB;IAED;;;;OAIG;IACH,eAJW,cAAc,aACd,WAAW,UACX,MAAM,QAIhB;IAED;;;;;;;OAOG;IACH,4BAHW,MAAM,GACJ,IAAI,CAgBhB;IAoCD;;;;;;;;;;;;OAYG;IACH,eAHW,OAAO,gDAAgD,EAAE,YAAY,GACnE,IAAI,CAqChB;;CAiWJ;;;;;gBAxxBa,MAAM;;;;WACN,OAAO,yCAAyC,EAAE,UAAU,GAAC,IAAI;;;YAKjE,MAAM;;;;YACN,cAAc;;;;eACd,WAAW;;;;aACX,eAAe,GAAC,IAAI;;;;;aACpB,OAAO,+CAA+C,EAAE,eAAe,GAAC,IAAI;gCAGjE,IAAI;;;;SACf,MAAM,GAAC,IAAI;;;;aACX,oBAAoB,GAAC,IAAI;;gCAvCP,2DAA2D;+BAS5D,6CAA6C;uBAPrD,kBAAkB;4BAEb,iCAAiC;6BAMhC,2CAA2C"}

package/src/engine/graphics3/GPUParticleEmitterSystem.js

@@ -833,6 +833,12 @@ export class GPUParticleEmitterSystem extends System {
  * to. Layout and program are shared by reference, never copied — two entities of one effect belong
  * on one program id in the heap.
  *
+ * Every field is compared by name, and that is load-bearing rather than style. Through a shared
+ * `assign(target, field, value)` the one `target[field]` access saw all thirteen names, went
+ * megamorphic, and read numbers back boxed, while the call boxed the value it was handed: 228 B and
+ * ~120 ns per emitter per call, against nothing and ~9 ns written out like this
+ * (`GPUParticleEmitterSystem.allocation.spec.js`). This runs for every live emitter twice a frame.
+ *
  * @param {ParticleEmitter} emitter
  * @param {ParticleEffect} effect
  * @returns {boolean} whether the emitter differs from what it held before
@@ -840,45 +846,82 @@ export class GPUParticleEmitterSystem extends System {
 export function apply_particle_effect(emitter, effect) {
     let changed = false;
 
-    changed = assign(emitter, "layout", effect.layout) || changed;
-    changed = assign(emitter, "program", effect.program) || changed;
-    changed = assign(emitter, "texture", effect.texture) || changed;
-    changed = assign(emitter, "seed", effect.seed) || changed;
-    changed = assign(emitter, "spawn_rate", effect.effective_spawn_rate) || changed;
-    changed = assign(emitter, "prewarm", effect.prewarm) || changed;
-    changed = assign(emitter, "flags", effect.flags) || changed;
-    changed = assign(emitter, "render_position", effect.render_position) || changed;
-    changed = assign(emitter, "render_size", effect.render_size) || changed;
-    changed = assign(emitter, "render_color", effect.render_color) || changed;
-    changed = assign(emitter, "render_rotation", effect.render_rotation) || changed;
-    changed = assign(emitter, "render_frame", effect.render_frame) || changed;
-    changed = assign(emitter, "render_velocity", effect.render_velocity) || changed;
+    if (emitter.layout !== effect.layout) {
+        emitter.layout = effect.layout;
+        changed = true;
+    }
 
-    const flipbook = emitter.flipbook;
+    if (emitter.program !== effect.program) {
+        emitter.program = effect.program;
+        changed = true;
+    }
 
-    if (flipbook[0] !== effect.flipbook[0] || flipbook[1] !== effect.flipbook[1]) {
-        flipbook.set(effect.flipbook);
+    if (emitter.texture !== effect.texture) {
+        emitter.texture = effect.texture;
+        changed = true;
+    }
 
+    if (emitter.seed !== effect.seed) {
+        emitter.seed = effect.seed;
         changed = true;
     }
 
-    return changed;
-}
+    const spawn_rate = effect.effective_spawn_rate;
 
-/**
- * @param {object} target
- * @param {string} field
- * @param {*} value
- * @returns {boolean} whether the field held something else
- */
-function assign(target, field, value) {
-    if (target[field] === value) {
-        return false;
+    if (emitter.spawn_rate !== spawn_rate) {
+        emitter.spawn_rate = spawn_rate;
+        changed = true;
+    }
+
+    if (emitter.prewarm !== effect.prewarm) {
+        emitter.prewarm = effect.prewarm;
+        changed = true;
     }
 
-    target[field] = value;
+    if (emitter.flags !== effect.flags) {
+        emitter.flags = effect.flags;
+        changed = true;
+    }
+
+    if (emitter.render_position !== effect.render_position) {
+        emitter.render_position = effect.render_position;
+        changed = true;
+    }
 
-    return true;
+    if (emitter.render_size !== effect.render_size) {
+        emitter.render_size = effect.render_size;
+        changed = true;
+    }
+
+    if (emitter.render_color !== effect.render_color) {
+        emitter.render_color = effect.render_color;
+        changed = true;
+    }
+
+    if (emitter.render_rotation !== effect.render_rotation) {
+        emitter.render_rotation = effect.render_rotation;
+        changed = true;
+    }
+
+    if (emitter.render_frame !== effect.render_frame) {
+        emitter.render_frame = effect.render_frame;
+        changed = true;
+    }
+
+    if (emitter.render_velocity !== effect.render_velocity) {
+        emitter.render_velocity = effect.render_velocity;
+        changed = true;
+    }
+
+    const flipbook = emitter.flipbook;
+
+    if (flipbook[0] !== effect.flipbook[0] || flipbook[1] !== effect.flipbook[1]) {
+        flipbook.set(effect.flipbook);
+
+        changed = true;
+    }
+
+    return changed;
 }
 
 class GPUParticleAtlasExtension extends RenderExtension {

package/src/engine/input/devices/KeyboardDevice.d.ts

@@ -6,6 +6,7 @@ export default KeyboardDevice;
  * the key remains pressed and the eventual physical release is picked up at the window level.
  * NOTE: when the window itself loses focus (e.g. switching to another application), key releases can no longer
  * be observed at all, so any "pressed" keys are forcibly released with the appropriate signal.
+ * A key still held when focus returns is pressed again by its next automatic repetition.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026

package/src/engine/input/devices/KeyboardDevice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KeyboardDevice.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/KeyboardDevice.js"],"names":[],"mappings":";AAYA;;;;;;;;;;GAUG;AACH;IA4BI;;;OAGG;IACH,wBAHW,WAAW,GAAC,OAAO,EAgC7B;IA3DD;;OAEG;IACH;QACI;;;WAGG;;QAEH;;;WAGG;;MAEL;IAEF;;;;;;;OAOG;IACH,mBAAU;IAkBN;;;OAGG;IACH,YAFU,WAAW,CAEO;IA2HhC;;;OAGG;IACH,SAFa,IAAI,CAWhB;IAED;;;OAGG;IACH,QAFa,IAAI,CAUhB;;CAEJ"}
+{"version":3,"file":"KeyboardDevice.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/KeyboardDevice.js"],"names":[],"mappings":";AAYA;;;;;;;;;;;GAWG;AACH;IA4BI;;;OAGG;IACH,wBAHW,WAAW,GAAC,OAAO,EAgC7B;IA3DD;;OAEG;IACH;QACI;;;WAGG;;QAEH;;;WAGG;;MAEL;IAEF;;;;;;;OAOG;IACH,mBAAU;IAkBN;;;OAGG;IACH,YAFU,WAAW,CAEO;IA2HhC;;;OAGG;IACH,SAFa,IAAI,CAWhB;IAED;;;OAGG;IACH,QAFa,IAAI,CAUhB;;CAEJ"}