@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -18,28 +18,32 @@ import { t64_look_rotation } from "./t64_look_rotation.js";
 export const TRANSFORM64_MATRIX_OFFSET = 0;
 
 /**
- * Index of the first element of the translation (x, y, z) inside a {@link Transform64}
+ * Index of the first element of the translation (x, y, z) inside a {@link Transform64}.
+ *
+ * It is 12, which is inside the matrix: for a column-major affine matrix elements 12..14 are the
+ * translation column, and neither rotation nor scale ever touch it, so the transform keeps a single
+ * copy and the translation is that column. See {@link Transform64#translation} for what that implies.
  * @type {number}
  */
-export const TRANSFORM64_TRANSLATION_OFFSET = 16;
+export const TRANSFORM64_TRANSLATION_OFFSET = 12;
 
 /**
  * Index of the first element of the rotation quaternion (x, y, z, w) inside a {@link Transform64}
  * @type {number}
  */
-export const TRANSFORM64_ROTATION_OFFSET = 19;
+export const TRANSFORM64_ROTATION_OFFSET = 16;
 
 /**
  * Index of the first element of the scale (x, y, z) inside a {@link Transform64}
  * @type {number}
  */
-export const TRANSFORM64_SCALE_OFFSET = 23;
+export const TRANSFORM64_SCALE_OFFSET = 20;
 
 /**
  * Number of elements in a {@link Transform64}
  * @type {number}
  */
-export const TRANSFORM64_SIZE = 26;
+export const TRANSFORM64_SIZE = 23;
 
 /**
  * World up, the direction orientation is resolved against when nothing else says otherwise.
@@ -53,7 +57,7 @@ const WORLD_UP = new Float64Array([0, 1, 0]);
  * packed into a single `Float64Array`.
  *
  * This is the passive counterpart of {@link Transform}. There are no signals, no flags and no change
- * detection: setting the translation, rotation or scale does **not** refresh {@link matrix}, you call
+ * detection: setting the rotation or scale does **not** refresh {@link matrix}, you call
  * {@link updateMatrix} yourself once you are done mutating. What you get for that is one allocation of one
  * contiguous buffer per transform, plain array stores instead of setter dispatch, and double precision
  * throughout.
@@ -62,18 +66,29 @@ const WORLD_UP = new Float64Array([0, 1, 0]);
  * write the buffer without going through the accessors:
  * ```
  * [ 0..15] matrix, column-major
- * [16..18] translation  x, y, z
- * [19..22] rotation     x, y, z, w
- * [23..25] scale        x, y, z
+ * [12..14] translation  x, y, z   (aliased into the matrix)
+ * [16..19] rotation     x, y, z, w
+ * [20..22] scale        x, y, z
  * ```
  *
+ * The translation is not stored twice: it *is* the matrix's translation column, elements 12..14. Which
+ * gives the staleness rule its exact shape - {@link matrix} is correct as long as the rotation and scale
+ * have not changed since the last {@link updateMatrix}. A translation-only change needs no
+ * {@link updateMatrix}, it lands in the matrix as it is written.
+ *
+ * NOTE: the flip side of that is a matrix that can describe a state that never existed. Change the
+ * translation *and* the rotation without an {@link updateMatrix} in between, and the matrix now carries
+ * the new translation under the old orientation, rather than lagging wholesale as it did when the
+ * translation had its own copy. Nothing reads such a matrix on your behalf, but if you hand it out
+ * between the two writes, that is what the receiver sees.
+ *
  * @example
  *  const t = new Transform64();
  *
  *  t.setTranslation(1, 2, 3);
  *  t.setScale(2, 2, 2);
  *
- *  // nothing has touched the matrix up to this point
+ *  // the translation is already in the matrix, the scale is not
  *  t.updateMatrix();
  *
  * @example
@@ -105,7 +120,14 @@ export class Transform64 extends Float64Array {
      * Affine transform matrix, column-major.
      *
      * Unlike {@link Transform}, this is not maintained for you - it holds whatever {@link updateMatrix},
-     * {@link fromMatrix} or {@link multiply} last wrote, and goes stale the moment you set a component.
+     * {@link fromMatrix} or {@link multiply} last wrote, and goes stale the moment you set the rotation
+     * or the scale.
+     *
+     * The translation column, elements 12..14, is shared with {@link translation} - the two are views over
+     * the same three numbers. Writing `matrix[12]` moves the transform, and setting the translation edits
+     * the matrix, so a translation-only change never leaves the matrix stale. Note the trap in the other
+     * direction: after poking the matrix directly, {@link translation} tracks it, while {@link rotation}
+     * and {@link scale} still lag until {@link updateComponents}.
      *
      * NOTE: the returned array is a live view over the transform's own buffer, but a freshly allocated
      * view on every access. Hold on to it rather than reading this property in a loop, or index the
@@ -118,6 +140,11 @@ export class Transform64 extends Float64Array {
 
     /**
      * Position in 3D space.
+     *
+     * This is the translation column of {@link matrix}, elements 12..14, not a separate copy: writing
+     * `translation[0]` edits the matrix, and writing `matrix[12]` shows up here. See {@link matrix} for
+     * the trap that comes with that.
+     *
      * NOTE: live view over the transform's own buffer, freshly allocated on every access
      * @returns {Float64Array}
      */
@@ -126,7 +153,8 @@ export class Transform64 extends Float64Array {
     }
 
     /**
-     * Reads 3 elements, does not update {@link matrix}
+     * Reads 3 elements. Lands in {@link matrix} directly, since the translation is a column of it - no
+     * {@link updateMatrix} is needed for a translation-only change.
      * @param {number[]|Float32Array|Float64Array} v
      */
     set translation(v) {
@@ -146,7 +174,8 @@ export class Transform64 extends Float64Array {
     }
 
     /**
-     * Does not update {@link matrix}
+     * Lands in {@link matrix} directly, since the translation is a column of it - no {@link updateMatrix}
+     * is needed for a translation-only change.
      * @param {number} x
      * @param {number} y
      * @param {number} z
@@ -482,7 +511,11 @@ export class Transform64 extends Float64Array {
 
     /**
      * Write {@link matrix} from the current {@link translation}, {@link rotation} and {@link scale}.
-     * Nothing calls this for you, and until you do, the matrix is whatever it was before.
+     * Nothing calls this for you, and until you do, the rotation and scale part of the matrix is whatever
+     * it was before. The translation column needs no help - it is the translation, see {@link matrix}.
+     *
+     * The translation is passed in as three scalars, read before the first store, so writing it back
+     * over its own column is safe.
      */
     updateMatrix() {
         m4_from_rotation_translation_scale_scalar(
@@ -508,6 +541,9 @@ export class Transform64 extends Float64Array {
      *
      * A matrix carrying shear cannot be described by a translation, a rotation and a scale, so shear is
      * dropped from the components. It survives in {@link matrix} until the next {@link updateMatrix}.
+     *
+     * The matrix itself is left bit-identical: the decompose reads every element before its first store,
+     * and the translation it writes is the matrix's own column copied onto itself.
      */
     updateComponents() {
         m4_decompose_array(
@@ -530,6 +566,8 @@ export class Transform64 extends Float64Array {
 
         array_copy(m4, 0, this, TRANSFORM64_MATRIX_OFFSET, 16);
 
+        // the copy above already put the translation where it lives; the decompose writes those three
+        // elements onto themselves, which is harmless and keeps this a straight copy-then-decompose
         this.updateComponents();
 
         return this;
@@ -591,7 +629,8 @@ export class Transform64 extends Float64Array {
 
     /**
      * Whether the translation is exactly [0,0,0], the rotation exactly [0,0,0,1] and the scale exactly
-     * [1,1,1]. Says nothing about {@link matrix}, which only agrees after an {@link updateMatrix}.
+     * [1,1,1]. Says nothing about the rotation and scale part of {@link matrix}, which only agrees after
+     * an {@link updateMatrix}; the translation column is the translation, so that much is covered.
      * @returns {boolean}
      */
     isIdentity() {

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

@@ -0,0 +1,37 @@
+/**
+ * Binary serialization for {@link Transform64}.
+ *
+ * Writes the same bytes in the same order as {@link TransformSerializationAdapter}: translation as
+ * three `Float64`s, rotation packed into a single `Uint32`, scale equality-encoded. A save written by
+ * either adapter can be read by the other, which is what lets the engine move onto {@link Transform64}
+ * without a save-format break.
+ *
+ * The matrix is not written. It is derived, and {@link Transform64#updateMatrix} rebuilds it on load
+ * from the three components that were - storing it would cost 128 bytes per transform to persist a
+ * value that is a pure function of the rest.
+ *
+ * The decode helpers take an array and an offset, and a `Transform64` *is* that array, so rotation and
+ * scale are decoded straight into the transform at their own offsets with no intermediate.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Transform64SerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof Transform64;
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Transform64} value
+     */
+    serialize(buffer: BinaryBuffer, value: Transform64): void;
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Transform64} value
+     */
+    deserialize(buffer: BinaryBuffer, value: Transform64): void;
+}
+import { BinaryClassSerializationAdapter } from "../storage/binary/BinaryClassSerializationAdapter.js";
+import { Transform64 } from "./Transform64.js";
+//# sourceMappingURL=Transform64SerializationAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Transform64SerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/Transform64SerializationAdapter.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;GAiBG;AACH;;IAEI,0BAAoB;IAGpB;;;;OAIG;IACH,uCAFW,WAAW,QAiBrB;IAED;;;;OAIG;IACH,yCAFW,WAAW,QAkBrB;CACJ;gDAtE+C,sDAAsD;4BACnB,kBAAkB"}

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

@@ -0,0 +1,75 @@
+import { quat3_decode_from_uint32 } from "../../../core/geom/3d/quaternion/quat3_decode_from_uint32.js";
+import { quat3_encode_to_uint32 } from "../../../core/geom/3d/quaternion/quat3_encode_to_uint32.js";
+import { v3_binary_equality_decode } from "../../../core/geom/vec3/serialization/v3_binary_equality_decode.js";
+import { v3_binary_equality_encode } from "../../../core/geom/vec3/serialization/v3_binary_equality_encode.js";
+import { BinaryClassSerializationAdapter } from "../storage/binary/BinaryClassSerializationAdapter.js";
+import { Transform64, TRANSFORM64_ROTATION_OFFSET, TRANSFORM64_SCALE_OFFSET } from "./Transform64.js";
+
+/**
+ * Binary serialization for {@link Transform64}.
+ *
+ * Writes the same bytes in the same order as {@link TransformSerializationAdapter}: translation as
+ * three `Float64`s, rotation packed into a single `Uint32`, scale equality-encoded. A save written by
+ * either adapter can be read by the other, which is what lets the engine move onto {@link Transform64}
+ * without a save-format break.
+ *
+ * The matrix is not written. It is derived, and {@link Transform64#updateMatrix} rebuilds it on load
+ * from the three components that were - storing it would cost 128 bytes per transform to persist a
+ * value that is a pure function of the rest.
+ *
+ * The decode helpers take an array and an offset, and a `Transform64` *is* that array, so rotation and
+ * scale are decoded straight into the transform at their own offsets with no intermediate.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Transform64SerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = Transform64;
+    version = 1;
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Transform64} value
+     */
+    serialize(buffer, value) {
+        buffer.writeFloat64(value.translation_x);
+        buffer.writeFloat64(value.translation_y);
+        buffer.writeFloat64(value.translation_z);
+
+        const encoded_rotation = quat3_encode_to_uint32(
+            value.rotation_x,
+            value.rotation_y,
+            value.rotation_z,
+            value.rotation_w
+        );
+
+        buffer.writeUint32(encoded_rotation);
+
+        v3_binary_equality_encode(buffer, value.scale_x, value.scale_y, value.scale_z);
+    }
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Transform64} value
+     */
+    deserialize(buffer, value) {
+        const translation_x = buffer.readFloat64();
+        const translation_y = buffer.readFloat64();
+        const translation_z = buffer.readFloat64();
+
+        const encoded_rotation = buffer.readUint32();
+
+        v3_binary_equality_decode(buffer, value, TRANSFORM64_SCALE_OFFSET);
+
+        quat3_decode_from_uint32(value, TRANSFORM64_ROTATION_OFFSET, encoded_rotation);
+
+        value.setTranslation(translation_x, translation_y, translation_z);
+
+        // rotation and scale were both written, so the matrix owes an update. The translation does
+        // not, being the matrix's own column, but updateMatrix writes it back regardless.
+        value.updateMatrix();
+    }
+}

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

@@ -0,0 +1,4 @@
+/** @param {Transform64} t */
+export function probe(t: Transform64): any[];
+import { Transform64 } from "./Transform64.js";
+//# sourceMappingURL=__probe.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"__probe.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/__probe.js"],"names":[],"mappings":"AAEA,6BAA6B;AAC7B,yBADY,WAAW,SAMtB;4BAP2B,kBAAkB"}

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

@@ -0,0 +1,31 @@
+/**
+ * Counts how many `Float64Array` views a piece of code causes {@link Transform64} to allocate.
+ *
+ * `t.translation`, `t.rotation` and `t.scale` each build a fresh view over the transform's buffer on
+ * every read. That is the right behaviour for a type that holds no state of its own - caching a view
+ * would mean a field, and being free of fields is the whole point - but it makes those three
+ * accessors the wrong way to read a transform in a loop that runs per entity per frame. The scalar
+ * accessors (`translation_x`, `rotation_w`, ...) and the exported offset constants read the same
+ * numbers without allocating.
+ *
+ * The counting is installed on the prototype for the duration of the call and removed afterwards, so
+ * {@link Transform64} itself carries no instrumentation and ships exactly as written. Nothing here
+ * runs unless a test calls it.
+ *
+ * @example
+ *  const allocations = t64_count_view_allocations(() => {
+ *      for (const t of transforms) {
+ *          total += t.translation_x;      // no view
+ *      }
+ *  });
+ *
+ *  expect(allocations).toBe(0);
+ *
+ * @param {function(): void} fn code to measure
+ * @returns {number} number of views allocated while `fn` ran
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function t64_count_view_allocations(fn: () => void): number;
+//# sourceMappingURL=t64_allocation_probe.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"t64_allocation_probe.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/t64_allocation_probe.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qDANuB,IAAI,GACd,MAAM,CA6ClB"}

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

@@ -0,0 +1,78 @@
+import { Transform64 } from "./Transform64.js";
+
+/**
+ * The three accessors that hand out a view over a transform's buffer.
+ * @type {string[]}
+ */
+const VIEW_ACCESSORS = ["translation", "rotation", "scale"];
+
+/**
+ * Counts how many `Float64Array` views a piece of code causes {@link Transform64} to allocate.
+ *
+ * `t.translation`, `t.rotation` and `t.scale` each build a fresh view over the transform's buffer on
+ * every read. That is the right behaviour for a type that holds no state of its own - caching a view
+ * would mean a field, and being free of fields is the whole point - but it makes those three
+ * accessors the wrong way to read a transform in a loop that runs per entity per frame. The scalar
+ * accessors (`translation_x`, `rotation_w`, ...) and the exported offset constants read the same
+ * numbers without allocating.
+ *
+ * The counting is installed on the prototype for the duration of the call and removed afterwards, so
+ * {@link Transform64} itself carries no instrumentation and ships exactly as written. Nothing here
+ * runs unless a test calls it.
+ *
+ * @example
+ *  const allocations = t64_count_view_allocations(() => {
+ *      for (const t of transforms) {
+ *          total += t.translation_x;      // no view
+ *      }
+ *  });
+ *
+ *  expect(allocations).toBe(0);
+ *
+ * @param {function(): void} fn code to measure
+ * @returns {number} number of views allocated while `fn` ran
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function t64_count_view_allocations(fn) {
+    const prototype = Transform64.prototype;
+
+    /**
+     * @type {Map<string, PropertyDescriptor>}
+     */
+    const originals = new Map();
+
+    let count = 0;
+
+    for (const name of VIEW_ACCESSORS) {
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+
+        if (descriptor === undefined || typeof descriptor.get !== "function") {
+            throw new Error(`Transform64.prototype.${name} is not an accessor; the probe is out of date`);
+        }
+
+        originals.set(name, descriptor);
+
+        const original_get = descriptor.get;
+
+        Object.defineProperty(prototype, name, {
+            ...descriptor,
+            get() {
+                count++;
+
+                return original_get.call(this);
+            }
+        });
+    }
+
+    try {
+        fn();
+    } finally {
+        for (const [name, descriptor] of originals) {
+            Object.defineProperty(prototype, name, descriptor);
+        }
+    }
+
+    return count;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Tell the dataset that an entity's {@link Transform64} was mutated in place.
+ *
+ * A {@link Transform64} carries no signals - that is the point of it - so a write is invisible until
+ * someone says so, and saying so is the writer's job. Every consumer that used to wake on
+ * `position.onChanged` wakes on {@link EventType.ComponentChanged} instead: the render placement,
+ * the parent/child sync, fog-of-war, the grid mirror, the spatial audio refit.
+ *
+ * The announcement is deliberately coarse - it names the component, not what changed inside it - so
+ * a consumer that only tracks translation still wakes on a scale write. That is redundant work, not
+ * wrong work, and it is what lets one call stand in for the three signals it replaces.
+ *
+ * Call it once per group of writes, after the last of them and after any
+ * {@link Transform64#updateMatrix} the group owes:
+ *
+ * ```
+ * transform.setRotation(x, y, z, w);
+ * transform.updateMatrix();
+ *
+ * t64_announce_change(ecd, entity, transform);
+ * ```
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {number} entity
+ * @param {Transform64} transform the instance that was written, handed to listeners as `instance`
+ * @returns {void}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function t64_announce_change(ecd: EntityComponentDataset, entity: number, transform: Transform64): void;
+import { Transform64 } from "./Transform64.js";
+//# sourceMappingURL=t64_announce_change.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"t64_announce_change.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/t64_announce_change.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,yEAPW,MAAM,aACN,WAAW,GACT,IAAI,CAUhB;4BArC2B,kBAAkB"}

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

@@ -0,0 +1,39 @@
+import { EventType } from "../EventType.js";
+import { Transform64 } from "./Transform64.js";
+
+/**
+ * Tell the dataset that an entity's {@link Transform64} was mutated in place.
+ *
+ * A {@link Transform64} carries no signals - that is the point of it - so a write is invisible until
+ * someone says so, and saying so is the writer's job. Every consumer that used to wake on
+ * `position.onChanged` wakes on {@link EventType.ComponentChanged} instead: the render placement,
+ * the parent/child sync, fog-of-war, the grid mirror, the spatial audio refit.
+ *
+ * The announcement is deliberately coarse - it names the component, not what changed inside it - so
+ * a consumer that only tracks translation still wakes on a scale write. That is redundant work, not
+ * wrong work, and it is what lets one call stand in for the three signals it replaces.
+ *
+ * Call it once per group of writes, after the last of them and after any
+ * {@link Transform64#updateMatrix} the group owes:
+ *
+ * ```
+ * transform.setRotation(x, y, z, w);
+ * transform.updateMatrix();
+ *
+ * t64_announce_change(ecd, entity, transform);
+ * ```
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {number} entity
+ * @param {Transform64} transform the instance that was written, handed to listeners as `instance`
+ * @returns {void}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function t64_announce_change(ecd, entity, transform) {
+    ecd.sendEvent(entity, EventType.ComponentChanged, {
+        klass: Transform64,
+        instance: transform
+    });
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Whether two {@link Transform64}s hold the same translation, rotation and scale.
+ *
+ * The counterpart of {@link t64_equals_transform} for two transforms of the same type, and it exists
+ * for the same reason: a system that places on a poll rather than on a signal has to be able to tell
+ * that there is nothing to place. The cost of not asking is not the copy - it is that
+ * `Node3D.updateMatrices` bumps a version whether or not anything moved, and downstream a bumped
+ * version means a scene-database row uploaded and, for a mesh, a whole-tree rebuild of the top-level
+ * acceleration structure.
+ *
+ * **Not {@link Transform64#equals}.** That one compares all 23 elements, the matrix included, and so
+ * reports two transforms as different when only one of them has a stale matrix - which is a state
+ * this type invites, since a rotation or scale write does not refresh the matrix until
+ * {@link Transform64#updateMatrix} is called. Using it as a placement guard would answer "have the
+ * buffers diverged" when the question is "has anything moved", and would let the rebuild it is meant
+ * to prevent back in.
+ *
+ * Exact equality rather than a tolerance, for the same reason {@link t64_equals_transform} uses it:
+ * the question is whether a write would change anything, and a write of a value that differs by any
+ * amount does.
+ *
+ * @param {Transform64} a
+ * @param {Transform64} b
+ * @returns {boolean}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function t64_equals_components(a: Transform64, b: Transform64): boolean;
+//# sourceMappingURL=t64_equals_components.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"t64_equals_components.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/t64_equals_components.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,uEALa,OAAO,CA4BnB"}

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

@@ -0,0 +1,59 @@
+import { assert } from "../../../core/assert.js";
+import {
+    TRANSFORM64_ROTATION_OFFSET,
+    TRANSFORM64_SCALE_OFFSET,
+    TRANSFORM64_TRANSLATION_OFFSET
+} from "./Transform64.js";
+
+/**
+ * Whether two {@link Transform64}s hold the same translation, rotation and scale.
+ *
+ * The counterpart of {@link t64_equals_transform} for two transforms of the same type, and it exists
+ * for the same reason: a system that places on a poll rather than on a signal has to be able to tell
+ * that there is nothing to place. The cost of not asking is not the copy - it is that
+ * `Node3D.updateMatrices` bumps a version whether or not anything moved, and downstream a bumped
+ * version means a scene-database row uploaded and, for a mesh, a whole-tree rebuild of the top-level
+ * acceleration structure.
+ *
+ * **Not {@link Transform64#equals}.** That one compares all 23 elements, the matrix included, and so
+ * reports two transforms as different when only one of them has a stale matrix - which is a state
+ * this type invites, since a rotation or scale write does not refresh the matrix until
+ * {@link Transform64#updateMatrix} is called. Using it as a placement guard would answer "have the
+ * buffers diverged" when the question is "has anything moved", and would let the rebuild it is meant
+ * to prevent back in.
+ *
+ * Exact equality rather than a tolerance, for the same reason {@link t64_equals_transform} uses it:
+ * the question is whether a write would change anything, and a write of a value that differs by any
+ * amount does.
+ *
+ * @param {Transform64} a
+ * @param {Transform64} b
+ * @returns {boolean}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function t64_equals_components(a, b) {
+    assert.equal(a.isTransform64, true, 'a.isTransform64 !== true');
+    assert.equal(b.isTransform64, true, 'b.isTransform64 !== true');
+
+    for (let i = 0; i < 3; i++) {
+        if (a[TRANSFORM64_TRANSLATION_OFFSET + i] !== b[TRANSFORM64_TRANSLATION_OFFSET + i]) {
+            return false;
+        }
+    }
+
+    for (let i = 0; i < 4; i++) {
+        if (a[TRANSFORM64_ROTATION_OFFSET + i] !== b[TRANSFORM64_ROTATION_OFFSET + i]) {
+            return false;
+        }
+    }
+
+    for (let i = 0; i < 3; i++) {
+        if (a[TRANSFORM64_SCALE_OFFSET + i] !== b[TRANSFORM64_SCALE_OFFSET + i]) {
+            return false;
+        }
+    }
+
+    return true;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Read a transform's rotation out into a quaternion.
+ *
+ * The companion of {@link t64_read_translation}, and there for the same reason: quaternion math -
+ * inverses, slerps, angles between two rotations - lives on {@link Quaternion}, and a
+ * {@link Transform64} is an array holding none of it.
+ *
+ * @param {Quaternion} out
+ * @param {Transform64} transform
+ * @returns {Quaternion} out
+ */
+export function t64_read_rotation(out: Quaternion, transform: Transform64): Quaternion;
+//# sourceMappingURL=t64_read_rotation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"t64_read_rotation.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/t64_read_rotation.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,uFAIC"}

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

@@ -0,0 +1,16 @@
+/**
+ * Read a transform's rotation out into a quaternion.
+ *
+ * The companion of {@link t64_read_translation}, and there for the same reason: quaternion math -
+ * inverses, slerps, angles between two rotations - lives on {@link Quaternion}, and a
+ * {@link Transform64} is an array holding none of it.
+ *
+ * @param {Quaternion} out
+ * @param {Transform64} transform
+ * @returns {Quaternion} out
+ */
+export function t64_read_rotation(out, transform) {
+    out.set(transform.rotation_x, transform.rotation_y, transform.rotation_z, transform.rotation_w);
+
+    return out;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Read a transform's translation out into a vector.
+ *
+ * A {@link Transform64} keeps its components as numbers inside its own array, which is the whole
+ * point of it; code that needs vector math on one of them - a distance, a cross product, a
+ * direction to rotate - reads it out into a scratch here instead of taking a view, which would
+ * allocate on every call.
+ *
+ * @param {Vector3} out
+ * @param {Transform64} transform
+ * @returns {Vector3} out
+ */
+export function t64_read_translation(out: Vector3, transform: Transform64): Vector3;
+//# sourceMappingURL=t64_read_translation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"t64_read_translation.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/t64_read_translation.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,oFAIC"}

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

@@ -0,0 +1,17 @@
+/**
+ * Read a transform's translation out into a vector.
+ *
+ * A {@link Transform64} keeps its components as numbers inside its own array, which is the whole
+ * point of it; code that needs vector math on one of them - a distance, a cross product, a
+ * direction to rotate - reads it out into a scratch here instead of taking a view, which would
+ * allocate on every call.
+ *
+ * @param {Vector3} out
+ * @param {Transform64} transform
+ * @returns {Vector3} out
+ */
+export function t64_read_translation(out, transform) {
+    out.set(transform.translation_x, transform.translation_y, transform.translation_z);
+
+    return out;
+}