@woosh/meep-engine 2.135.0 → 2.138.0

package/src/core/geom/Vector3.js

@@ -23,12 +23,14 @@ import { v3_slerp } from "./vec3/v3_slerp.js";
  *
  * Iterating through a Vector3 instance will yield its components `(x, y, z)` in the corresponding order.
  *
+ * Backed by a `Float64Array` of length 3, so instances are usable directly as typed-array views and indexed access `v[0]`, `v[1]`, `v[2]` aliases `v.x`, `v.y`, `v.z`.
+ *
  * @implements Iterable<number>
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2025
  */
-export class Vector3 {
+export class Vector3 extends Float64Array {
     /**
      *
      * @param {number} [x=0]
@@ -45,26 +47,11 @@ export class Vector3 {
         assert.isNumber(z, 'z');
         assert.notNaN(z, 'z');
 
-        /**
-         * Do not assign directly, use {@link set} method instead
-         * @readonly
-         * @type {number}
-         */
-        this.x = x;
-
-        /**
-         * Do not assign directly, use {@link set} method instead
-         * @readonly
-         * @type {number}
-         */
-        this.y = y;
+        super(3);
 
-        /**
-         * Do not assign directly, use {@link set} method instead
-         * @readonly
-         * @type {number}
-         */
-        this.z = z;
+        this[0] = x;
+        this[1] = y;
+        this[2] = z;
 
         /**
          * Dispatches ( x, y, z, old_x, old_y, old_z )
@@ -75,63 +62,60 @@ export class Vector3 {
     }
 
     /**
-     *
-     * @return {number}
+     * Ensure that built-in `TypedArray` methods (`map`, `slice`, `subarray`, ...) do not
+     * try to construct a `Vector3` via the buffer-form constructor.
+     * @returns {Float64ArrayConstructor}
      */
-    get 0() {
-        return this.x;
+    static get [Symbol.species]() {
+        return Float64Array;
     }
 
     /**
      *
-     * @return {number}
+     * @returns {number}
      */
-    get 1() {
-        return this.y;
+    get x() {
+        return this[0];
     }
 
     /**
      *
-     * @return {number}
+     * @param {number} v
      */
-    get 2() {
-        return this.z;
+    set x(v) {
+        this[0] = v;
     }
 
     /**
      *
-     * @param {number} v
+     * @returns {number}
      */
-    set 0(v) {
-        this.x = v;
+    get y() {
+        return this[1];
     }
 
     /**
      *
      * @param {number} v
      */
-    set 1(v) {
-        this.y = v;
+    set y(v) {
+        this[1] = v;
     }
 
     /**
      *
-     * @param {number} v
+     * @returns {number}
      */
-    set 2(v) {
-        this.z = v;
+    get z() {
+        return this[2];
     }
 
     /**
      *
-     * @return {Generator<number>}
+     * @param {number} v
      */
-    * [Symbol.iterator]() {
-
-        yield this.x;
-        yield this.y;
-        yield this.z;
-
+    set z(v) {
+        this[2] = v;
     }
 
     /**
@@ -159,9 +143,9 @@ export class Vector3 {
     toArray(array = [], offset = 0) {
         assert.isNonNegativeInteger(offset, "offset");
 
-        array[offset] = this.x;
-        array[offset + 1] = this.y;
-        array[offset + 2] = this.z;
+        array[offset] = this[0];
+        array[offset + 1] = this[1];
+        array[offset + 2] = this[2];
 
         return array;
     }
@@ -182,16 +166,16 @@ export class Vector3 {
         assert.notNaN(y, "y");
         assert.notNaN(z, "z");
 
-        const oldX = this.x;
-        const oldY = this.y;
-        const oldZ = this.z;
+        const oldX = this[0];
+        const oldY = this[1];
+        const oldZ = this[2];
 
         if (x !== oldX || y !== oldY || z !== oldZ) {
             // change has occurred
 
-            this.x = x;
-            this.y = y;
-            this.z = z;
+            this[0] = x;
+            this[1] = y;
+            this[2] = z;
 
             if (this.onChanged.hasHandlers()) {
                 this.onChanged.send6(
@@ -220,7 +204,7 @@ export class Vector3 {
      * @returns {this}
      */
     setX(v) {
-        return this.set(v, this.y, this.z);
+        return this.set(v, this[1], this[2]);
     }
 
     /**
@@ -229,7 +213,7 @@ export class Vector3 {
      * @returns {this}
      */
     setY(v) {
-        return this.set(this.x, v, this.z);
+        return this.set(this[0], v, this[2]);
     }
 
     /**
@@ -238,7 +222,7 @@ export class Vector3 {
      * @returns {this}
      */
     setZ(v) {
-        return this.set(this.x, this.y, v);
+        return this.set(this[0], this[1], v);
     }
 
     /**
@@ -248,7 +232,7 @@ export class Vector3 {
      * @returns {this}
      */
     setXY(x, y) {
-        return this.set(x, y, this.z);
+        return this.set(x, y, this[2]);
     }
 
     /**
@@ -258,7 +242,7 @@ export class Vector3 {
      * @returns {this}
      */
     setXZ(x, z) {
-        return this.set(x, this.y, z);
+        return this.set(x, this[1], z);
     }
 
     /**
@@ -268,7 +252,7 @@ export class Vector3 {
      * @returns {this}
      */
     setYZ(y, z) {
-        return this.set(this.x, y, z);
+        return this.set(this[0], y, z);
     }
 
     /**
@@ -302,7 +286,7 @@ export class Vector3 {
      * @returns {this}
      */
     _add(x, y, z) {
-        return this.set(this.x + x, this.y + y, this.z + z);
+        return this.set(this[0] + x, this[1] + y, this[2] + z);
     }
 
 
@@ -337,9 +321,9 @@ export class Vector3 {
      * @returns {this}
      */
     _sub(x, y, z) {
-        const _x = this.x - x;
-        const _y = this.y - y;
-        const _z = this.z - z;
+        const _x = this[0] - x;
+        const _y = this[1] - y;
+        const _z = this[2] - z;
 
         return this.set(_x, _y, _z);
     }
@@ -352,7 +336,7 @@ export class Vector3 {
      * @returns {this}
      */
     _multiply(x, y, z) {
-        return this.set(this.x * x, this.y * y, this.z * z);
+        return this.set(this[0] * x, this[1] * y, this[2] * z);
     }
 
     /**
@@ -387,9 +371,9 @@ export class Vector3 {
      */
     _divide(x, y, z) {
         return this.set(
-            this.x / x,
-            this.y / y,
-            this.z / z,
+            this[0] / x,
+            this[1] / y,
+            this[2] / z,
         )
     }
 
@@ -423,7 +407,7 @@ export class Vector3 {
      * @returns {this}
      */
     addScalar(val) {
-        return this.set(this.x + val, this.y + val, this.z + val);
+        return this.set(this[0] + val, this[1] + val, this[2] + val);
     }
 
     /**
@@ -440,7 +424,7 @@ export class Vector3 {
      * @returns {Vector3}
      */
     clone() {
-        return new Vector3(this.x, this.y, this.z);
+        return new Vector3(this[0], this[1], this[2]);
     }
 
     /**
@@ -452,7 +436,7 @@ export class Vector3 {
         assert.isNumber(val, "val");
         assert.notNaN(val, "val");
 
-        return this.set(this.x * val, this.y * val, this.z * val);
+        return this.set(this[0] * val, this[1] * val, this[2] * val);
     }
 
     /**
@@ -460,9 +444,9 @@ export class Vector3 {
      * @returns {boolean}
      */
     isZero() {
-        return this.x === 0
-            && this.y === 0
-            && this.z === 0
+        return this[0] === 0
+            && this[1] === 0
+            && this[2] === 0
             ;
     }
 
@@ -516,9 +500,9 @@ export class Vector3 {
      */
     abs() {
         return this.set(
-            Math.abs(this.x),
-            Math.abs(this.y),
-            Math.abs(this.z)
+            Math.abs(this[0]),
+            Math.abs(this[1]),
+            Math.abs(this[2])
         );
     }
 
@@ -536,7 +520,7 @@ export class Vector3 {
      * @returns {number}
      */
     length() {
-        return v3_length(this.x, this.y, this.z);
+        return v3_length(this[0], this[1], this[2]);
     }
 
     /**
@@ -545,7 +529,7 @@ export class Vector3 {
      * @returns {number}
      */
     lengthSqr() {
-        return v3_length_sqr(this.x, this.y, this.z);
+        return v3_length_sqr(this[0], this[1], this[2]);
     }
 
     /**
@@ -553,7 +537,12 @@ export class Vector3 {
      * @returns {this}
      */
     normalize() {
-        const l = this.length();
+        // NOTE: call v3_length directly rather than via `this.length()`.
+        // Float64Array exposes `length` as an exotic instance property that V8 inlines
+        // through a fast path which bypasses the prototype chain; once an optimized
+        // function caller has been specialized for Float64Array shape, `this.length`
+        // is read as the array length (a number) rather than our prototype method.
+        const l = v3_length(this[0], this[1], this[2]);
 
         if (l === 0) {
             //special case, can't normalize 0 length vector
@@ -591,9 +580,9 @@ export class Vector3 {
      */
     negate() {
         return this.set(
-            -this.x,
-            -this.y,
-            -this.z
+            -this[0],
+            -this[1],
+            -this[2]
         );
     }
 
@@ -615,7 +604,7 @@ export class Vector3 {
      */
     _distanceTo(x, y, z) {
         return v3_distance(
-            this.x, this.y, this.z,
+            this[0], this[1], this[2],
             x, y, z
         );
     }
@@ -640,9 +629,9 @@ export class Vector3 {
      */
     _distanceSqrTo(x, y, z) {
         return v3_length_sqr(
-            this.x - x,
-            this.y - y,
-            this.z - z
+            this[0] - x,
+            this[1] - y,
+            this[2] - z
         );
     }
 
@@ -653,7 +642,7 @@ export class Vector3 {
      */
     angleTo(other) {
         return v3_angle_between(
-            this.x, this.y, this.z,
+            this[0], this[1], this[2],
             other.x, other.y, other.z
         );
     }
@@ -668,9 +657,9 @@ export class Vector3 {
 
         //transform point into quaternion
 
-        const x = this.x;
-        const y = this.y;
-        const z = this.z;
+        const x = this[0];
+        const y = this[1];
+        const z = this[2];
 
         const qx = q.x;
         const qy = q.y;
@@ -700,9 +689,9 @@ export class Vector3 {
      */
     sign() {
         return this.set(
-            sign(this.x),
-            sign(this.y),
-            sign(this.z)
+            sign(this[0]),
+            sign(this[1]),
+            sign(this[2])
         );
     }
 
@@ -758,9 +747,9 @@ export class Vector3 {
      * @returns {this}
      */
     applyMatrix4(m4) {
-        const x = this.x;
-        const y = this.y;
-        const z = this.z;
+        const x = this[0];
+        const y = this[1];
+        const z = this[2];
 
         const w = 1 / (m4[3] * x + m4[7] * y + m4[11] * z + m4[15]);
 
@@ -778,9 +767,9 @@ export class Vector3 {
      * @returns {this}
      */
     applyDirectionMatrix4(m4) {
-        const x = this.x;
-        const y = this.y;
-        const z = this.z;
+        const x = this[0];
+        const y = this[1];
+        const z = this[2];
 
         // This is just 3x3 matrix multiplication
         const _x = m4[0] * x + m4[4] * y + m4[8] * z;
@@ -803,9 +792,9 @@ export class Vector3 {
      * @returns {this}
      */
     applyMatrix3(mat) {
-        const x = this.x;
-        const y = this.y;
-        const z = this.z;
+        const x = this[0];
+        const y = this[1];
+        const z = this[2];
 
         const _x = mat[0] * x + mat[3] * y + mat[6] * z;
         const _y = mat[1] * x + mat[4] * y + mat[7] * z;
@@ -846,7 +835,7 @@ export class Vector3 {
      * @return {boolean}
      */
     _equals(x, y, z) {
-        return this.x === x && this.y === y && this.z === z;
+        return this[0] === x && this[1] === y && this[2] === z;
     }
 
     /**
@@ -868,9 +857,9 @@ export class Vector3 {
      * @return {boolean}
      */
     _roughlyEquals(x, y, z, tolerance = EPSILON) {
-        return epsilonEquals(this.x, x, tolerance)
-            && epsilonEquals(this.y, y, tolerance)
-            && epsilonEquals(this.z, z, tolerance);
+        return epsilonEquals(this[0], x, tolerance)
+            && epsilonEquals(this[1], y, tolerance)
+            && epsilonEquals(this[2], z, tolerance);
     }
 
     /**
@@ -879,9 +868,9 @@ export class Vector3 {
      */
     round() {
         return this.set(
-            Math.round(this.x),
-            Math.round(this.y),
-            Math.round(this.z),
+            Math.round(this[0]),
+            Math.round(this[1]),
+            Math.round(this[2]),
         );
     }
 
@@ -890,9 +879,9 @@ export class Vector3 {
      * @returns {this}
      */
     floor() {
-        const x = Math.floor(this.x);
-        const y = Math.floor(this.y);
-        const z = Math.floor(this.z);
+        const x = Math.floor(this[0]);
+        const y = Math.floor(this[1]);
+        const z = Math.floor(this[2]);
 
         return this.set(x, y, z);
     }
@@ -903,9 +892,9 @@ export class Vector3 {
      */
     ceil() {
         return this.set(
-            Math.ceil(this.x),
-            Math.ceil(this.y),
-            Math.ceil(this.z),
+            Math.ceil(this[0]),
+            Math.ceil(this[1]),
+            Math.ceil(this[2]),
         );
     }
 
@@ -915,9 +904,9 @@ export class Vector3 {
      * @returns {this}
      */
     projectOntoVector3(other) {
-        const x0 = this.x;
-        const y0 = this.y;
-        const z0 = this.z;
+        const x0 = this[0];
+        const y0 = this[1];
+        const z0 = this[2];
 
         const x1 = other.x;
         const y1 = other.y;
@@ -995,7 +984,7 @@ export class Vector3 {
      */
     process(processor, thisArg) {
 
-        processor.call(thisArg, this.x, this.y, this.z);
+        processor.call(thisArg, this[0], this[1], this[2]);
 
         this.onChanged.add(processor, thisArg);
 
@@ -1004,9 +993,9 @@ export class Vector3 {
 
     toJSON() {
         return {
-            x: this.x,
-            y: this.y,
-            z: this.z
+            x: this[0],
+            y: this[1],
+            z: this[2]
         };
     }
 
@@ -1024,7 +1013,7 @@ export class Vector3 {
     }
 
     toString() {
-        return `Vector3{ x:${this.x}, y:${this.y}, z:${this.z} }`;
+        return `Vector3{ x:${this[0]}, y:${this[1]}, z:${this[2]} }`;
     }
 
     /**
@@ -1033,9 +1022,9 @@ export class Vector3 {
      * @deprecated
      */
     toBinaryBuffer(buffer) {
-        buffer.writeFloat64(this.x);
-        buffer.writeFloat64(this.y);
-        buffer.writeFloat64(this.z);
+        buffer.writeFloat64(this[0]);
+        buffer.writeFloat64(this[1]);
+        buffer.writeFloat64(this[2]);
     }
 
     /**
@@ -1057,9 +1046,9 @@ export class Vector3 {
      * @deprecated
      */
     toBinaryBufferFloat32(buffer) {
-        buffer.writeFloat32(this.x);
-        buffer.writeFloat32(this.y);
-        buffer.writeFloat32(this.z);
+        buffer.writeFloat32(this[0]);
+        buffer.writeFloat32(this[1]);
+        buffer.writeFloat32(this[2]);
     }
 
     /**
@@ -1076,9 +1065,9 @@ export class Vector3 {
     }
 
     hash() {
-        const x = computeHashFloat(this.x);
-        const y = computeHashFloat(this.y);
-        const z = computeHashFloat(this.z);
+        const x = computeHashFloat(this[0]);
+        const y = computeHashFloat(this[1]);
+        const z = computeHashFloat(this[2]);
 
         return x ^ (y << 1) ^ (z << 2);
     }
@@ -1153,57 +1142,57 @@ Vector3.prototype.asArray = Vector3.prototype.toArray;
  * @readonly
  * @type {Vector3}
  */
-Vector3.zero = Object.freeze(new Vector3(0, 0, 0));
+Vector3.zero = new Vector3(0, 0, 0);
 
 /**
  * Useful for setting scale
  * @readonly
  * @type {Vector3}
  */
-Vector3.one = Object.freeze(new Vector3(1, 1, 1));
+Vector3.one = new Vector3(1, 1, 1);
 
 /**
  * Useful for setting scale
  * @readonly
  * @type {Vector3}
  */
-Vector3.minus_one = Object.freeze(new Vector3(-1, -1, -1));
+Vector3.minus_one = new Vector3(-1, -1, -1);
 
 /**
  * @readonly
  * @type {Vector3}
  */
-Vector3.up = Object.freeze(new Vector3(0, 1, 0));
+Vector3.up = new Vector3(0, 1, 0);
 
 /**
  * @readonly
  * @type {Vector3}
  */
-Vector3.down = Object.freeze(new Vector3(0, -1, 0));
+Vector3.down = new Vector3(0, -1, 0);
 
 /**
  * @readonly
  * @type {Vector3}
  */
-Vector3.left = Object.freeze(new Vector3(-1, 0, 0));
+Vector3.left = new Vector3(-1, 0, 0);
 
 /**
  * @readonly
  * @type {Vector3}
  */
-Vector3.right = Object.freeze(new Vector3(1, 0, 0));
+Vector3.right = new Vector3(1, 0, 0);
 
 /**
  * @readonly
  * @type {Vector3}
  */
-Vector3.forward = Object.freeze(new Vector3(0, 0, 1));
+Vector3.forward = new Vector3(0, 0, 1);
 
 /**
  * @readonly
  * @type {Vector3}
  */
-Vector3.back = Object.freeze(new Vector3(0, 0, -1));
+Vector3.back = new Vector3(0, 0, -1);
 
 /**
  * @readonly