@woosh/meep-engine 2.78.1 → 2.80.0

package/package.json

@@ -5,7 +5,7 @@
   "description": "Fully featured ECS game engine written in JavaScript",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.78.1",
+  "version": "2.80.0",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/geom/2d/aabb/AABB2.js

@@ -9,11 +9,11 @@ import { clamp } from "../../../math/clamp.js";
 import { max2 } from "../../../math/max2.js";
 import { min2 } from "../../../math/min2.js";
 import Vector2 from "../../Vector2.js";
-import { aabb2_compute_overlap } from "./aabb2_compute_overlap.js";
-import { aabb2_overlap_exists } from "./aabb2_overlap_exists.js";
 import {
     line_segment_compute_line_segment_intersection_2d
 } from "../line/line_segment_compute_line_segment_intersection_2d.js";
+import { aabb2_compute_overlap } from "./aabb2_compute_overlap.js";
+import { aabb2_overlap_exists } from "./aabb2_overlap_exists.js";
 
 /**
  *
@@ -146,7 +146,7 @@ class AABB2 {
     /**
      *
      * @param {AABB2} other
-     * @returns {number}
+     * @returns {boolean}
      */
     overlapExists(other) {
         const ax0 = this.x0;
@@ -173,6 +173,7 @@ class AABB2 {
     _expandToFit(x0, y0, x1, y1) {
         this.x0 = min2(this.x0, x0);
         this.y0 = min2(this.y0, y0);
+
         this.x1 = max2(this.x1, x1);
         this.y1 = max2(this.y1, y1);
     }
@@ -183,21 +184,8 @@ class AABB2 {
      * @param {number} y
      */
     _expandToFitPoint(x, y) {
-        if (x < this.x0) {
-            this.x0 = x;
-        }
-
-        if (x > this.x1) {
-            this.x1 = x;
-        }
-
-        if (y < this.y0) {
-            this.y0 = y;
-        }
-
-        if (y > this.y1) {
-            this.y1 = y;
-        }
+        // shortcut, use a 0-size box
+        this._expandToFit(x, y, x, y);
     }
 
     /**

package/src/core/geom/3d/SurfacePoint3.spec.js

@@ -1,5 +1,5 @@
+import { MATRIX_4_IDENTITY } from "./mat4/MATRIX_4_IDENTITY.js";
 import { SurfacePoint3 } from "./SurfacePoint3.js";
-import { MATRIX_4_IDENTITY } from "./matrix/MATRIX_4_IDENTITY.js";
 
 
 test("equals", () => {

package/src/core/geom/3d/{matrix → mat4}/m4_multiply.spec.js

@@ -1,7 +1,6 @@
-import {MATRIX_4_IDENTITY} from "./MATRIX_4_IDENTITY.js";
-import {m4_multiply} from "./m4_multiply.js";
-import {m4_multiply_alphatensor} from "./m4_multiply_alphatensor.js";
-import {number_pretty_print} from "../../../primitives/numbers/number_pretty_print.js";
+import { number_pretty_print } from "../../../primitives/numbers/number_pretty_print.js";
+import { m4_multiply } from "./m4_multiply.js";
+import { MATRIX_4_IDENTITY } from "./MATRIX_4_IDENTITY.js";
 
 test("identity multiplication", () => {
 

package/src/core/geom/3d/{matrix → mat4}/m4_multiply_alphatensor.spec.js

@@ -1,6 +1,6 @@
-import {m4_multiply_alphatensor} from "./m4_multiply_alphatensor.js";
-import {MATRIX_4_IDENTITY} from "./MATRIX_4_IDENTITY.js";
-import {number_pretty_print} from "../../../primitives/numbers/number_pretty_print.js";
+import { number_pretty_print } from "../../../primitives/numbers/number_pretty_print.js";
+import { m4_multiply_alphatensor } from "./m4_multiply_alphatensor.js";
+import { MATRIX_4_IDENTITY } from "./MATRIX_4_IDENTITY.js";
 
 test("identity multiplication", () => {
 

package/src/core/geom/3d/morton/v3_morton_encode_transformed.spec.js

@@ -1,5 +1,5 @@
+import { MATRIX_4_IDENTITY } from "../mat4/MATRIX_4_IDENTITY.js";
 import { v3_morton_encode_transformed } from "./v3_morton_encode_transformed.js";
-import { MATRIX_4_IDENTITY } from "../matrix/MATRIX_4_IDENTITY.js";
 
 test("valid number with identity transform", () => {
     const v = v3_morton_encode_transformed(0, 0, 0, MATRIX_4_IDENTITY);

package/src/core/geom/3d/sphere/sphere_radius_sqr_from_v3_array_transformed.spec.js

@@ -1,5 +1,5 @@
+import { MATRIX_4_IDENTITY } from "../mat4/MATRIX_4_IDENTITY.js";
 import { sphere_radius_sqr_from_v3_array_transformed } from "./sphere_radius_sqr_from_v3_array_transformed.js";
-import { MATRIX_4_IDENTITY } from "../matrix/MATRIX_4_IDENTITY.js";
 
 test("base case", () => {
     expect(sphere_radius_sqr_from_v3_array_transformed([0, 0, 0], 3, MATRIX_4_IDENTITY)).toBe(0);

package/src/core/geom/Quaternion.js

@@ -1546,7 +1546,7 @@ class Quaternion {
      * @param {Quaternion} result
      * @param {Quaternion} from
      * @param {Quaternion} to
-     * @param {number} max_delta
+     * @param {number} max_delta in radians
      */
     static rotateTowards(result, from, to, max_delta) {
         assert.isNumber(max_delta, 'max_delta');

package/src/core/geom/Vector3.js

@@ -37,7 +37,7 @@ class Vector3 {
 
     /**
      *
-     * @param {number[]} array
+     * @param {number[]|Float32Array} array
      * @param {number} offset
      */
     readFromArray(array, offset = 0) {
@@ -50,7 +50,7 @@ class Vector3 {
 
     /**
      *
-     * @param {number[]} array
+     * @param {number[]|Float32Array} array
      * @param {number} offset
      */
     writeToArray(array, offset = 0) {

package/src/core/geom/Vector3.spec.js

@@ -1,5 +1,5 @@
-import {MATRIX_4_IDENTITY} from "./3d/matrix/MATRIX_4_IDENTITY.js";
-import {v3_slerp} from "./vec3/v3_slerp.js";
+import { MATRIX_4_IDENTITY } from "./3d/mat4/MATRIX_4_IDENTITY.js";
+import { v3_slerp } from "./vec3/v3_slerp.js";
 import Vector3 from "./Vector3.js";
 
 test('slerp', () => {

package/src/core/geom/packing/max-rect/{MaxRectangles.js → MaxRectanglesPacker.js}

@@ -1,15 +1,19 @@
-import BinaryHeap from "../../../collection/heap/FastBinaryHeap.js";
 import { assert } from "../../../assert.js";
+import BinaryHeap from "../../../collection/heap/FastBinaryHeap.js";
+import AABB2 from "../../2d/aabb/AABB2.js";
 import { QuadTreeDatum } from "../../2d/quad-tree/QuadTreeDatum.js";
 import { QuadTreeNode } from "../../2d/quad-tree/QuadTreeNode.js";
-import AABB2 from "../../2d/aabb/AABB2.js";
 import Vector2 from "../../Vector2.js";
-import { removeRedundantBoxes } from "./removeRedundantBoxes.js";
 import { costByRemainingArea } from "./cost/costByRemainingArea.js";
 import { findBestContainer } from "./findBestContainer.js";
 import { packOneBox } from "./packOneBox.js";
+import { removeRedundantBoxes } from "./removeRedundantBoxes.js";
 
-
+/**
+ * Packs rectangles into a finite area, packer is incremental and supports both insertions and removals of rectangles
+ * Implementation of "max rectangles" packing algorithm.
+ * Useful for packing texture atlases
+ */
 export class MaxRectanglesPacker {
     /**
      *
@@ -24,6 +28,8 @@ export class MaxRectanglesPacker {
          * @type {QuadTreeNode}
          */
         this.free = new QuadTreeNode(0, 0, width, height);
+
+        // initialize a with a free space occupying the entire area
         this.free.add(null, 0, 0, width, height);
 
         /**
@@ -98,7 +104,8 @@ export class MaxRectanglesPacker {
     }
 
     /**
-     *
+     * Tests whether a rectangle of given dimensions can be packed into remaining space
+     * Essentially, if this method succeeds - insertion will succeed as well, and if it fails - insertion will fail too
      * @param {number} w
      * @param {number} h
      * @return {boolean}
@@ -184,9 +191,10 @@ export class MaxRectanglesPacker {
     }
 
     /**
-     * Resize the packer canvas
+     * Resize the packer canvas, may trigger repacking if new dimensions are smaller than the existing ones
      * @param {number} width
      * @param {number} height
+     * @returns {boolean} false if packing fails after resize, true otherwise
      */
     resize(width, height) {
 
@@ -199,18 +207,20 @@ export class MaxRectanglesPacker {
 
         if (oldWidth > width || oldHeight > height) {
             //canvas was made smaller in at least one dimension, re-pack is required
-            this.repack();
-        } else {
-            //canvas was enlarged, we can simply add new free areas
-            if (width > oldWidth) {
-                this.free.insertDatum(new QuadTreeDatum(oldWidth, 0, width, height));
-            }
-            if (height > oldHeight) {
-                this.free.insertDatum(new QuadTreeDatum(0, oldHeight, width, height))
-            }
+            return this.repack();
+        }
+
+        //canvas was enlarged, we can simply add new free areas
+        if (width > oldWidth) {
+            this.free.insertDatum(new QuadTreeDatum(oldWidth, 0, width, height));
+        }
+        if (height > oldHeight) {
+            this.free.insertDatum(new QuadTreeDatum(0, oldHeight, width, height))
         }
 
         // assert.ok(this.validate());
+
+        return true;
     }
 
     validate() {
@@ -239,20 +249,3 @@ export class MaxRectanglesPacker {
 }
 
 
-/**
- * Packs {@link AABB2} boxes into defined bounds
- *
- * Based on paper "A Thousand Ways to Pack the Bin - A Practical Approach to Two-Dimensional Rectangle Bin Packing" 2010 Jukka Jylänki
- * Method presented called Maximal Rectangles
- *
- * @param {number} width
- * @param {number} height
- * @param {AABB2[]} boxes
- * @returns {boolean} true if packing was successful, false otherwise
- */
-export function packMaxRectangles(width, height, boxes) {
-
-    const packer = new MaxRectanglesPacker(width, height);
-
-    return packer.addMany(boxes);
-}

package/src/core/geom/packing/max-rect/MaxRectanglesPacker.spec.js

@@ -0,0 +1,60 @@
+import AABB2 from "../../2d/aabb/AABB2.js";
+import { MaxRectanglesPacker } from "./MaxRectanglesPacker.js";
+
+test("constructor does not throw", () => {
+    new MaxRectanglesPacker(1, 1)
+});
+
+test("pack 1 box that takes up entire available area", () => {
+    const packer = new MaxRectanglesPacker(1, 1);
+
+    const box = new AABB2(3, 5, 4, 6);
+
+    expect(packer.add(box)).toBe(true);
+
+    expect(box.x0).toBe(0);
+    expect(box.y0).toBe(0);
+});
+
+test("packing a box larger than available area", () => {
+
+    const packer = new MaxRectanglesPacker(1, 1);
+
+    const box = new AABB2(0, 0, 2, 1);
+
+    expect(packer.add(box)).toBe(false);
+
+    box.set(0, 0, 1, 2);
+
+    expect(packer.add(box)).toBe(false);
+
+    box.set(0, 0, 2, 2)
+
+    expect(packer.add(box)).toBe(false);
+});
+
+test("pack 4 squares that fit exactly", () => {
+
+    const packer = new MaxRectanglesPacker(2, 2);
+
+    const boxes = [
+        new AABB2(0, 0, 1, 1),
+        new AABB2(0, 0, 1, 1),
+        new AABB2(0, 0, 1, 1),
+        new AABB2(0, 0, 1, 1)
+    ];
+
+    for (let i = 0; i < boxes.length; i++) {
+        expect(packer.add(boxes[i])).toBe(true);
+    }
+
+    // validate overlap constraints
+    for (let i = 0; i < boxes.length; i++) {
+        const box_0 = boxes[i];
+        for (let j = i + 1; j < boxes.length; j++) {
+            const box_1 = boxes[j];
+
+            expect(box_0.overlapExists(box_1)).toBe(false);
+        }
+    }
+});

package/src/core/geom/packing/max-rect/packMaxRectangles.js

@@ -0,0 +1,19 @@
+import { MaxRectanglesPacker } from "./MaxRectanglesPacker.js";
+
+/**
+ * Packs {@link AABB2} boxes into defined bounds
+ *
+ * Based on paper "A Thousand Ways to Pack the Bin - A Practical Approach to Two-Dimensional Rectangle Bin Packing" 2010 Jukka Jylänki
+ * Method presented called Maximal Rectangles
+ *
+ * @param {number} width
+ * @param {number} height
+ * @param {AABB2[]} boxes
+ * @returns {boolean} true if packing was successful, false otherwise
+ */
+export function packMaxRectangles(width, height, boxes) {
+
+    const packer = new MaxRectanglesPacker(width, height);
+
+    return packer.addMany(boxes);
+}

package/src/core/geom/vec3/v3_angle_between.js

@@ -1,6 +1,6 @@
+import { clamp } from "../../math/clamp.js";
 import { v3_dot } from "./v3_dot.js";
 import { v3_length } from "./v3_length.js";
-import { clamp } from "../../math/clamp.js";
 
 /**
  *
@@ -12,10 +12,15 @@ import { clamp } from "../../math/clamp.js";
  * @param {number} z1
  * @returns {number}
  */
-export function v3_angle_between(x0, y0, z0, x1, y1, z1) {
+export function v3_angle_between(
+    x0, y0, z0,
+    x1, y1, z1
+) {
+
     const theta = v3_angle_cos_between(x0, y0, z0, x1, y1, z1);
 
     return Math.acos(theta);
+
 }
 
 /**
@@ -26,9 +31,13 @@ export function v3_angle_between(x0, y0, z0, x1, y1, z1) {
  * @param {number} x1
  * @param {number} y1
  * @param {number} z1
- * @returns {number}
+ * @returns {number} value between -1 and 1, cosine of the angle between vectors
  */
-export function v3_angle_cos_between(x0, y0, z0, x1, y1, z1){
+export function v3_angle_cos_between(
+    x0, y0, z0,
+    x1, y1, z1
+) {
+
     const d = v3_dot(x0, y0, z0, x1, y1, z1);
 
     const magnitude_0 = v3_length(x0, y0, z0);
@@ -38,10 +47,12 @@ export function v3_angle_cos_between(x0, y0, z0, x1, y1, z1){
 
     if (l === 0) {
         // collective magnitude is 0, provide arbitrary angle
+        // avoid division by 0
         return 0;
     }
 
     return clamp(d / l, -1, 1);
+
 }
 
 /**

package/src/core/geom/vec3/{v3_computeOffsetVector.js → v3_displace_in_direction.js}

@@ -8,8 +8,9 @@
  * @param {number} directionX
  * @param {number} directionY
  * @param {number} directionZ
+ * @returns {boolean} true if displaced successfully, false if direction had 0 magnitude
  */
-export function v3_computeOffsetVector(
+export function v3_displace_in_direction(
     result,
     distance,
     sourceX, sourceY, sourceZ,
@@ -17,13 +18,19 @@ export function v3_computeOffsetVector(
 ) {
     if (distance === 0) {
         result.set(sourceX, sourceY, sourceZ);
-        return;
+        return true;
     }
 
     //scale direction to have length equal to distance
 
     const directionLength = Math.sqrt(directionX * directionX + directionY * directionY + directionZ * directionZ);
 
+    if(directionLength === 0){
+        // direction vector is zero length, avoid division by zero, clamp to source instead
+        result.set(sourceX, sourceY, sourceZ);
+        return false;
+    }
+
     const m = distance / directionLength;
 
     const x = sourceX + directionX * m;
@@ -31,4 +38,6 @@ export function v3_computeOffsetVector(
     const z = sourceZ + directionZ * m;
 
     result.set(x, y, z);
+
+    return true;
 }

package/src/core/graph/cluster_mesh_metis.js

@@ -12,12 +12,12 @@ const MAX_STEPS = 50;
  * @param {Uint32Array} result
  * @param {number} node_count
  * @param {Uint32Array} edge_addresses
- * @param {Uint32Array} adjecency_uint32
+ * @param {Uint32Array} adjacency_uint32
  * @param {Uint32Array} edge_weights_uint32
  * @param {number} patch_size
  * @returns {Promise<number>}
  */
-export async function metis_cluster_bs(result, node_count, edge_addresses, adjecency_uint32, edge_weights_uint32, patch_size) {
+export async function metis_cluster_bs(result, node_count, edge_addresses, adjacency_uint32, edge_weights_uint32, patch_size) {
 
     const metis = Metis.INSTANCE;
 
@@ -46,7 +46,7 @@ export async function metis_cluster_bs(result, node_count, edge_addresses, adjec
             node_count,
             partition_count,
             edge_addresses,
-            adjecency_uint32,
+            adjacency_uint32,
             edge_weights_uint32,
             metisOptions
         );

package/src/core/graph/metis/metis.js

@@ -1,5 +1,5 @@
-import WorkerBuilder from "../../process/worker/WorkerBuilder.js";
 import { OnDemandWorkerManager } from "../../process/worker/OnDemandWorkerManager.js";
+import WorkerBuilder from "../../process/worker/WorkerBuilder.js";
 
 
 export class Metis {
@@ -13,6 +13,16 @@ export class Metis {
         this.service = manager;
     }
 
+    /**
+     *
+     * @param {number} n_vertices
+     * @param {number} n_parts
+     * @param {Uint32Array} edge_addresses
+     * @param {Uint32Array} adjacency
+     * @param {Uint32Array} edge_weights
+     * @param {metis_options} options
+     * @returns {Promise<T>}
+     */
     partition(
         n_vertices,
         n_parts,
@@ -32,4 +42,9 @@ export class Metis {
     }
 }
 
+/**
+ * Singleton instance
+ * @readonly
+ * @type {Metis}
+ */
 Metis.INSTANCE = new Metis();

package/src/core/graph/metis/metis_options.js

@@ -1,33 +1,36 @@
+
+/**
+ * See metis.h for more details
+ * -1 is the used to signal absence of value, in which case a default will be used
+ */
 export class metis_options {
+    ptype = -1;
+    objtype = -1;
     /**
-     * See metis.h for more details
-     * -1 is the used to signal absence of value, in which case a default will be used
+     * Coarsening scheme
+     * 0 - METIS_CTYPE_RM
+     * 1 - METIS_CTYPE_SHEM
+     * @type {number}
      */
-    constructor() {
-        this.ptype = -1;
-        this.objtype = -1;
-        /**
-         * Coarsening scheme
-         * 0 - METIS_CTYPE_RM
-         * 1 - METIS_CTYPE_SHEM
-         * @type {number}
-         */
-        this.ctype = -1;
-        this.iptype = -1;
-        this.rtype = -1;
-        this.dbglvl = -1;
-        this.niter = -1;
-        this.ncuts = -1;
-        this.seed = -1;
-        this.no2hop = -1;
-        this.minconn = -1;
-        this.contig = -1;
-        this.compress - 1;
-        this.ccorder = -1;
-        this.pfactor = -1;
-        this.nseps = -1;
-        this.ufactor = -1;
-        this.numbering = -1;
-
-    }
+    ctype = -1;
+    iptype = -1;
+    rtype = -1;
+    dbglvl = -1;
+    niter = -1;
+    ncuts = -1;
+    /**
+     * Random seed
+     * Integer
+     * @type {number}
+     */
+    seed = -1;
+    no2hop = -1;
+    minconn = -1;
+    contig = -1;
+    ccorder = -1;
+    pfactor = -1;
+    nseps = -1;
+    ufactor = -1;
+    numbering = -1;
+    compress = - 1;
 }

package/src/core/math/interval/overlap1D.js

@@ -12,8 +12,15 @@ import { assert } from "../../assert.js";
 export function overlap1D(a0, a1, b0, b1) {
     assert.isNumber(a0, "a0");
     assert.isNumber(a1, "a1");
+
     assert.isNumber(b0, "b0");
     assert.isNumber(b1, "b1");
 
+    assert.notNaN(a0, 'a0');
+    assert.notNaN(a1, 'a1');
+
+    assert.notNaN(b0, 'b0');
+    assert.notNaN(b1, 'b1');
+
     return a1 > b0 && b1 > a0;
 }

package/src/core/math/noise/create_simplex_noise_2d.js

@@ -73,6 +73,10 @@ export function create_simplex_noise_2d(random = Math.random) {
         permMod12[i] = (perm[i] % 12) * 2;
     }
 
+    /**
+     * @param {number} x
+     * @param {number} y
+     */
     return function noise2D(x, y) {
         // if(!isFinite(x) || !isFinite(y)) return 0;
         let n0 = 0; // Noise contributions from the three corners

package/src/core/math/spline/computeCatmullRomSplineUniformDistance.js

@@ -30,9 +30,9 @@ const p2 = [];
 const p3 = [];
 
 /**
- * Takes distances between points into account and samples at equal intervals along linear distance along the point sequence. Computationally slightly more expensive, but produces very predictable and sable results
- * @param {number[]} result
- * @param {number[]} input
+ * Takes distances between points into account and samples at equal intervals along linear distance along the point sequence. Computationally slightly more expensive, but produces very predictable and stable results
+ * @param {number[]|Float32Array} result
+ * @param {number[]|Float32Array} input
  * @param {number} input_length number of points in the input
  * @param {number} dimensions number of dimensions per vertex
  * @param {number} sample_count number of discrete points to be generated

package/src/core/math/spline/v3_computeCatmullRomSplineUniformDistance.js

@@ -0,0 +1,42 @@
+import Vector3 from "../../geom/Vector3.js";
+import { computeCatmullRomSplineUniformDistance } from "./computeCatmullRomSplineUniformDistance.js";
+
+/**
+ *
+ * @param {Vector3[]} inputs
+ * @param {number} samples
+ * @returns {Vector3[]}
+ */
+export function v3_computeCatmullRomSplineUniformDistance(
+    inputs, samples
+) {
+
+    const input_count = inputs.length;
+
+    const inputs_array = new Float32Array(3 * input_count);
+    const result_array = new Float32Array(3 * samples);
+
+    for (let i = 0; i < input_count; i++) {
+        const v3 = inputs[i];
+
+        v3.writeToArray(inputs_array, i * 3);
+    }
+
+    computeCatmullRomSplineUniformDistance(
+        result_array, inputs_array, input_count, 3, samples
+    );
+
+    // convert numeric result to array of Vector3 objects
+    const result = [];
+
+    for (let i = 0; i < samples; i++) {
+        const v3 = new Vector3();
+
+        v3.readFromArray(result_array, i * 3);
+
+        result[i] = v3;
+
+    }
+
+    return result;
+}