@woosh/meep-engine 2.61.0 → 2.63.0

package/package.json

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

package/src/core/binary/EncodingBinaryBuffer.js

@@ -1,58 +1,22 @@
+import { BiMap } from "../collection/map/BiMap.js";
 import { BinaryBuffer } from "./BinaryBuffer.js";
 
-class Dictionary {
-    constructor() {
-        this.forward = new Map();
-        this.backward = new Map();
-    }
-
-    /**
-     *
-     * @param {*} value
-     * @param {number} address
-     */
-    add(value, address) {
-        this.forward.set(address, value);
-        this.backward.set(value, address);
-    }
-
-    /**
-     *
-     * @param {*} value
-     * @returns {number|undefined}
-     */
-    getAddress(value) {
-        return this.backward.get(value);
-    }
-
-    /**
-     *
-     * @param {number} address
-     * @returns {*}
-     */
-    getValue(address) {
-        return this.forward.get(address);
-    }
-}
+export class EncodingBinaryBuffer extends BinaryBuffer {
 
+    __dictionary = new BiMap();
 
-export class EncodingBinaryBuffer extends BinaryBuffer {
-    constructor() {
-        super();
-        this.__dictionary = new Dictionary();
-    }
 
     writeUTF8String(value) {
-        const address = this.__dictionary.getAddress(value);
+        const address = this.__dictionary.getKeyByValue(value);
 
         if (address === undefined) {
             this.writeUint8(0); //mark as complete value
 
-            const address1 = this.position;
+            const current_address = this.position;
 
             super.writeUTF8String(value);
 
-            this.__dictionary.add(value, address1);
+            this.__dictionary.add(value, current_address);
         } else {
             //write as reference
             this.writeUint32LE(1 | (address << 1));
@@ -72,7 +36,7 @@ export class EncodingBinaryBuffer extends BinaryBuffer {
 
             const address = header >> 1;
 
-            let value = this.__dictionary.getValue(address);
+            let value = this.__dictionary.getValueByKey(address);
 
             if (value === undefined) {
                 //remember position

package/src/core/binary/EncodingBinaryBuffer.spec.js

@@ -0,0 +1,16 @@
+import { EncodingBinaryBuffer } from "./EncodingBinaryBuffer.js";
+
+test("read/write strings", () => {
+
+    const buffer = new EncodingBinaryBuffer();
+
+    buffer.writeUTF8String("hello world");
+    buffer.writeUTF8String("cat");
+    buffer.writeUTF8String("hello world");
+
+    buffer.position = 0;
+
+    expect(buffer.readUTF8String()).toEqual("hello world");
+    expect(buffer.readUTF8String()).toEqual("cat");
+    expect(buffer.readUTF8String()).toEqual("hello world");
+});

package/src/core/bvh2/BinaryNode.js

@@ -3,19 +3,19 @@
  */
 
 
-import { assert } from "../assert.js";
-import { arrayQuickSort } from "../collection/array/arrayQuickSort.js";
-import { max2 } from "../math/max2.js";
-import { min2 } from "../math/min2.js";
-import { computeSampleStandardDeviation } from "../math/statistics/computeSampleStandardDeviation.js";
-import { isLeaf, LeafNode } from "./LeafNode.js";
-import { Node } from "./Node.js";
-import { surfaceAreaHeuristic } from "./sah/surfaceAreaHeuristic.js";
-import { BVHVisitor } from "./traversal/BVHVisitor.js";
-import { traverseBinaryNodeUsingVisitor } from "./traversal/traverseBinaryNodeUsingVisitor.js";
-import { aabb3_intersects_aabb3 } from "../geom/3d/aabb/aabb3_intersects_aabb3.js";
-import { aabb3_box_surface_area_2 } from "../geom/3d/aabb/aabb3_box_surface_area_2.js";
-import { aabb3_combined_surface_area } from "../geom/3d/aabb/aabb3_combined_surface_area.js";
+import {assert} from "../assert.js";
+import {arrayQuickSort} from "../collection/array/arrayQuickSort.js";
+import {aabb3_box_surface_area_2} from "../geom/3d/aabb/aabb3_box_surface_area_2.js";
+import {aabb3_combined_surface_area} from "../geom/3d/aabb/aabb3_combined_surface_area.js";
+import {aabb3_intersects_aabb3} from "../geom/3d/aabb/aabb3_intersects_aabb3.js";
+import {max2} from "../math/max2.js";
+import {min2} from "../math/min2.js";
+import {computeSampleStandardDeviation} from "../math/statistics/computeSampleStandardDeviation.js";
+import {isLeaf, LeafNode} from "./LeafNode.js";
+import {Node} from "./Node.js";
+import {surfaceAreaHeuristic} from "./sah/surfaceAreaHeuristic.js";
+import {BVHVisitor} from "./traversal/BVHVisitor.js";
+import {traverseBinaryNodeUsingVisitor} from "./traversal/traverseBinaryNodeUsingVisitor.js";
 
 
 /**
@@ -36,6 +36,9 @@ let stackPointer = 0;
  */
 const stack = [];
 
+/**
+ * @deprecated use {@link ExplicitBinaryBoundingVolumeHierarchy} instead
+ */
 export class BinaryNode extends Node {
     constructor() {
         super();

package/src/core/bvh2/LeafNode.js

@@ -1,9 +1,9 @@
 /**
  * Created by Alex on 17/11/2014.
  */
-import { Node } from "./Node.js";
-import { serializeAABB3 } from "../geom/3d/aabb/serializeAABB3.js";
-import { deserializeAABB3 } from "../geom/3d/aabb/deserializeAABB3.js";
+import {deserializeAABB3} from "../geom/3d/aabb/deserializeAABB3.js";
+import {serializeAABB3} from "../geom/3d/aabb/serializeAABB3.js";
+import {Node} from "./Node.js";
 
 
 /**
@@ -15,6 +15,9 @@ function isLeaf(node) {
     return node.isLeafNode;
 }
 
+/**
+ * @deprecated use {@link ExplicitBinaryBoundingVolumeHierarchy} and {@link EBBVHLeafProxy} respectively
+ */
 export class LeafNode extends Node {
     /**
      *

package/src/core/bvh2/bvh3/EBBVHLeafProxy.js

@@ -50,8 +50,10 @@ export class EBBVHLeafProxy {
     unlink() {
         assert.equal(this.is_linked, true, 'not linked');
 
-        this.#tree.remove_leaf(this.#node_id);
-        this.#tree.release_node(this.#node_id);
+        const node_id = this.#node_id;
+
+        this.#tree.remove_leaf(node_id);
+        this.#tree.release_node(node_id);
 
         this.#node_id = -1;
         this.#tree = null;

package/src/core/bvh2/bvh3/query/bvh_query_user_data_overlaps_sphere.js

@@ -0,0 +1,81 @@
+import {SCRATCH_UINT32_TRAVERSAL_STACK} from "../../../collection/SCRATCH_UINT32_TRAVERSAL_STACK.js";
+import {aabb3_array_intersects_sphere_array} from "../../../geom/3d/aabb/aabb3_array_intersects_sphere_array.js";
+import {NULL_NODE} from "../ExplicitBinaryBoundingVolumeHierarchy.js";
+import {bvh_collect_user_data} from "./bvh_collect_user_data.js";
+
+const stack = SCRATCH_UINT32_TRAVERSAL_STACK;
+
+const scratch_aabb = new Float32Array(6);
+
+/**
+ *
+ * @param {number[]} result
+ * @param {number} result_offset
+ * @param {ExplicitBinaryBoundingVolumeHierarchy} bvh
+ * @param {number[]|Float32Array} sphere
+ */
+export function bvh_query_user_data_overlaps_sphere(
+    result,
+    result_offset,
+    bvh,
+    sphere
+) {
+    const root = bvh.root;
+
+    if (root === NULL_NODE) {
+        return 0;
+    }
+
+    /**
+     *
+     * @type {number}
+     */
+    const stack_top = stack.pointer++;
+
+    stack[stack_top] = root;
+
+    let result_cursor = result_offset;
+
+    while (stack.pointer > stack_top) {
+        stack.pointer--;
+
+        /**
+         *
+         * @type {number}
+         */
+        const node = stack[stack.pointer];
+
+        // test node against the ray
+        bvh.node_get_aabb(node, scratch_aabb);
+        const intersection = aabb3_array_intersects_sphere_array(scratch_aabb, sphere);
+
+        if (intersection === 0) {
+            // fully outside
+            continue;
+        }
+
+        const node_is_leaf = bvh.node_is_leaf(node);
+
+        if (node_is_leaf) {
+            // leaf node
+            result[result_cursor++] = bvh.node_get_user_data(node);
+
+        } else if (intersection === 2) {
+            // fully inside, fast collection path
+            result_cursor += bvh_collect_user_data(result, result_cursor, bvh, node);
+        } else {
+            // partially inside
+            // read in-order
+            const child1 = bvh.node_get_child1(node);
+            const child2 = bvh.node_get_child2(node);
+
+            // write to stack in reverse order, so that fist child ends up being visited first
+            stack[stack.pointer++] = child1;
+            stack[stack.pointer++] = child2;
+        }
+    }
+
+    // drop stack frame
+
+    return result_cursor - result_offset;
+}

package/src/core/cache/LoadingCache.js

@@ -1,7 +1,8 @@
 //
 
-import { Cache } from "./Cache.js";
+import { assert } from "../assert.js";
 import { current_time_in_seconds } from "../time/current_time_in_seconds.js";
+import { Cache } from "./Cache.js";
 
 /**
  * @template R
@@ -79,6 +80,8 @@ export class LoadingCache {
                     retryFailed = true
                 }) {
 
+        assert.isFunction(load, 'load');
+
         this.#internal = new Cache({
             maxWeight,
             keyWeigher,

package/src/core/collection/map/BiMap.js

@@ -0,0 +1,49 @@
+/**
+ * Bi-directional map
+ * @template K,V
+ */
+export class BiMap {
+
+    /**
+     *
+     * @type {Map<K, V>}
+     */
+    forward = new Map();
+    /**
+     *
+     * @type {Map<V, K>}
+     */
+    backward = new Map();
+
+
+    /**
+     *
+     * @param {K} key
+     * @param {V} value
+     */
+    add(key, value) {
+        this.forward.set(value, key);
+        this.backward.set(key, value);
+    }
+
+    /**
+     *
+     * @param {V} value
+     * @returns {K|undefined}
+     */
+    getKeyByValue(value) {
+        return this.backward.get(value);
+    }
+
+    /**
+     *
+     * @param {K} address
+     * @returns {V|undefined}
+     */
+    getValueByKey(address) {
+        return this.forward.get(address);
+    }
+}
+
+BiMap.prototype.get = BiMap.prototype.getValueByKey;
+BiMap.prototype.set = BiMap.prototype.add;

package/src/core/geom/3d/aabb/AABB3.js

@@ -3,22 +3,24 @@
  */
 
 
-import { aabb3_compute_distance_above_plane_max } from "./aabb3_compute_distance_above_plane_max.js";
-import { aabb3_compute_plane_side } from "./aabb3_compute_plane_side.js";
+import {assert} from "../../../assert.js";
 import computeMortonCode from "../morton/Morton.js";
-import { aabb3_build_corners } from "./aabb3_build_corners.js";
-import { assert } from "../../../assert.js";
-import { aabb3_intersects_frustum_degree } from "./aabb3_intersects_frustum_degree.js";
-import { aabb3_intersects_line_segment } from "./aabb3_intersects_line_segment.js";
-import { aabb3_intersects_ray } from "./aabb3_intersects_ray.js";
-import { aabb3_compute_surface_area } from "./aabb3_compute_surface_area.js";
-import { aabb3_intersects_frustum_array } from "./aabb3_intersects_frustum_array.js";
-import { aabb3_matrix4_project } from "./aabb3_matrix4_project.js";
-import { aabb3_signed_distance_sqr_to_point } from "./aabb3_signed_distance_sqr_to_point.js";
-import { aabb3_array_intersects_point } from "./aabb3_array_intersects_point.js";
+import {aabb3_array_intersects_point} from "./aabb3_array_intersects_point.js";
+import {aabb3_build_corners} from "./aabb3_build_corners.js";
+import {aabb3_compute_distance_above_plane_max} from "./aabb3_compute_distance_above_plane_max.js";
+import {aabb3_compute_plane_side} from "./aabb3_compute_plane_side.js";
+import {aabb3_compute_surface_area} from "./aabb3_compute_surface_area.js";
+import {aabb3_intersects_frustum_array} from "./aabb3_intersects_frustum_array.js";
+import {aabb3_intersects_frustum_degree} from "./aabb3_intersects_frustum_degree.js";
+import {aabb3_intersects_line_segment} from "./aabb3_intersects_line_segment.js";
+import {aabb3_intersects_ray} from "./aabb3_intersects_ray.js";
+import {aabb3_matrix4_project} from "./aabb3_matrix4_project.js";
+import {aabb3_signed_distance_sqr_to_point} from "./aabb3_signed_distance_sqr_to_point.js";
+import {aabb3_signed_distance_to_aabb3} from "./aabb3_signed_distance_to_aabb3.js";
 
 /**
  * Axis-Aligned bounding box in 3D
+ * NOTE: In cases where all you want is raw performance - prefer to use typed arrays instead along with `aabb3_` functions
  */
 export class AABB3 {
     /**
@@ -238,7 +240,12 @@ export class AABB3 {
      * @returns {boolean}
      */
     _equals(x0, y0, z0, x1, y1, z1) {
-        return this.x0 === x0 && this.y0 === y0 && this.z0 === z0 && this.x1 === x1 && this.y1 === y1 && this.z1 === z1;
+        return this.x0 === x0
+            && this.y0 === y0
+            && this.z0 === z0
+            && this.x1 === x1
+            && this.y1 === y1
+            && this.z1 === z1;
     }
 
     /**
@@ -332,28 +339,10 @@ export class AABB3 {
         const _y1 = this.y1;
         const _z1 = this.z1;
 
-        //do projection
-        const xp0 = _x0 - x1;
-        const xp1 = x0 - _x1;
-        const yp0 = _y0 - y1;
-        const yp1 = y0 - _y1;
-        const zp0 = _z0 - z1;
-        const zp1 = z0 - _z1;
-
-        //calculate separation in each axis
-        const dx = Math.max(xp0, xp1);
-        const dy = Math.max(yp0, yp1);
-        const dz = Math.max(zp0, zp1);
-
-        //straight-line distance
-        let distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
-
-        if (dx < 0 && dy < 0 && dz < 0) {
-            //penetration
-            return -distance;
-        } else {
-            return distance;
-        }
+        return aabb3_signed_distance_to_aabb3(
+            _x0, _y0, _z0, _x1, _y1, _z1,
+            x0, y0, z0, x1, y1, z1
+        );
     }
 
     /**
@@ -778,7 +767,6 @@ export class AABB3 {
     }
 
     /**
-     *
      * @param {Plane[]} clippingPlanes
      * @returns {boolean}
      */

package/src/core/geom/3d/aabb/aabb3_array_compute_from_sphere.js

@@ -0,0 +1,22 @@
+/**
+ *
+ * @param {number[]} output
+ * @param {number} output_offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ */
+export function aabb3_array_compute_from_sphere(
+    output, output_offset,
+    x, y, z, radius
+) {
+
+    output[output_offset] = x - radius;
+    output[output_offset + 1] = y - radius;
+    output[output_offset + 2] = z - radius;
+    output[output_offset + 3] = x + radius;
+    output[output_offset + 4] = y + radius;
+    output[output_offset + 5] = z + radius;
+
+}

package/src/core/geom/3d/aabb/aabb3_array_intersects_sphere.js

@@ -0,0 +1,22 @@
+import {aabb3_signed_distance_sqr_to_point} from "./aabb3_signed_distance_sqr_to_point.js";
+
+/**
+ *
+ * @param {number[]} aabb
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ * @returns {boolean}
+ */
+export function aabb3_array_intersects_sphere(aabb, x, y, z, radius) {
+    const distance_sqr = aabb3_signed_distance_sqr_to_point(
+        aabb[0], aabb[1], aabb[2],
+        aabb[3], aabb[4], aabb[5],
+        x, y, z
+    );
+
+    const radius2 = radius * radius;
+
+    return distance_sqr <= radius2;
+}

package/src/core/geom/3d/aabb/aabb3_array_intersects_sphere_array.js

@@ -0,0 +1,11 @@
+import {aabb3_array_intersects_sphere} from "./aabb3_array_intersects_sphere.js";
+
+/**
+ *
+ * @param {number[]|Float32Array} aabb
+ * @param {number[]|Float32Array} sphere [x,y,z, radius]
+ * @returns {boolean}
+ */
+export function aabb3_array_intersects_sphere_array(aabb, sphere) {
+    return aabb3_array_intersects_sphere(aabb, sphere[0], sphere[1], sphere[2], sphere[3]);
+}

package/src/core/geom/3d/aabb/aabb3_signed_distance_to_aabb3.js

@@ -0,0 +1,28 @@
+export function aabb3_signed_distance_to_aabb3(
+    ax0,ay0,az0,ax1,ay1,az1,
+    bx0,by0,bz0, bx1,by1,bz1
+){
+
+    //do projection
+    const xp0 = bx0 - ax1;
+    const xp1 = ax0 - bx1;
+    const yp0 = by0 - ay1;
+    const yp1 = ay0 - by1;
+    const zp0 = bz0 - az1;
+    const zp1 = az0 - bz1;
+
+    //calculate separation in each axis
+    const dx = Math.max(xp0, xp1);
+    const dy = Math.max(yp0, yp1);
+    const dz = Math.max(zp0, zp1);
+
+    //straight-line distance
+    let distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+    if (dx < 0 && dy < 0 && dz < 0) {
+        //penetration
+        return -distance;
+    } else {
+        return distance;
+    }
+}

package/src/core/geom/3d/aabb/serializeAABB3Quantized16Uint.js

@@ -9,20 +9,29 @@
  * @param {number} y1
  * @param {number} z1
  */
-export function serializeAABB3Quantized16Uint(buffer, box, x0, y0, z0, x1, y1, z1) {
+export function serializeAABB3Quantized16Uint(
+    buffer, box,
+    x0, y0, z0, x1, y1, z1
+) {
+
     //compute value ranges
-    const xD = x1 - x0;
-    const yD = y1 - y0;
-    const zD = z1 - z0;
+    const dx = x1 - x0;
+    const dy = y1 - y0;
+    const dz = z1 - z0;
+
+    // scale delta to Uin16 range, and avoid division by 0
+    const mx = dx > 0 ? 65535 / dx : 0;
+    const my = dy > 0 ? 65535 / dy : 0;
+    const mz = dz > 0 ? 65535 / dz : 0;
 
     //quantize all values
-    const _x0 = (((box.x0 - x0) / xD) * 65535) | 0;
-    const _y0 = (((box.y0 - y0) / yD) * 65535) | 0;
-    const _z0 = (((box.z0 - z0) / zD) * 65535) | 0;
+    const _x0 = Math.floor((box.x0 - x0) * mx);
+    const _y0 = Math.floor((box.y0 - y0) * my);
+    const _z0 = Math.floor((box.z0 - z0) * mz);
 
-    const _x1 = (((box.x1 - x0) / xD) * 65535) | 0;
-    const _y1 = (((box.y1 - y0) / yD) * 65535) | 0;
-    const _z1 = (((box.z1 - z0) / zD) * 65535) | 0;
+    const _x1 = Math.ceil((box.x1 - x0) * mx);
+    const _y1 = Math.ceil((box.y1 - y0) * my);
+    const _z1 = Math.ceil((box.z1 - z0) * mz);
 
     buffer.writeUint16(_x0);
     buffer.writeUint16(_y0);

package/src/core/geom/3d/tetrahedra/delaunay/Cavity.js

@@ -1,5 +1,8 @@
 import { assert } from "../../../../assert.js";
 
+/**
+ * Represents cavity or "ball" formed when carving out "triangles" to accommodate inserted point
+ */
 export class Cavity {
     constructor() {
         /**
@@ -52,10 +55,6 @@ export class Cavity {
         this.__boundary_size++;
     }
 
-    update() {
-        // compute in/out state for each side of each tetra
-    }
-
     /**
      *
      * @param {number} i

package/src/engine/ecs/components/Tag.d.ts

@@ -17,6 +17,8 @@ export class Tag {
 
     containsOneOf(values: string[]): boolean
 
+    hash(): number
+
     equals(other: Tag): boolean
 
     static find(tags: string[], ecd: EntityComponentDataset): number[]

package/src/engine/ecs/components/Tag.js

@@ -3,8 +3,9 @@
  */
 
 
-import { computeStringHash } from "../../../core/primitives/strings/computeStringHash.js";
 import { assert } from "../../../core/assert.js";
+import { isArrayEqualStrict } from "../../../core/collection/array/isArrayEqualStrict.js";
+import { computeStringHash } from "../../../core/primitives/strings/computeStringHash.js";
 
 /**
  * Stores textual tags, useful for marking entities
@@ -12,7 +13,7 @@ import { assert } from "../../../core/assert.js";
 export class Tag {
     /**
      * @private
-     * @type {String[]}
+     * @type {string[]}
      */
     values = [];
 
@@ -194,41 +195,31 @@ export class Tag {
      * @return {boolean}
      */
     equals(other) {
-
-        const s0 = this.values;
-
-        const s1 = other.values;
-
-        const n0 = s0.length;
-        const n1 = s1.length;
-
-        if (n0 !== n1) {
-            //wrong length
-            return false;
-        }
-
-        for (let i = 0; i < n0; i++) {
-            const v0 = s0[i];
-            const v1 = s1[i];
-
-            if (v0 !== v1) {
-                return false;
-            }
-        }
-
-        return true;
+        return isArrayEqualStrict(this.values, other.values);
     }
 
     toJSON() {
         return this.values;
     }
 
+    /**
+     *
+     * @param {string[]|string} json
+     */
     fromJSON(json) {
+
+        this.clear();
+
         if (typeof json === "string") {
-            this.clear();
             this.add(json);
-        } else if (Array.isArray(json)) {
-            this.values = json;
+        } else {
+            assert.isArray(json, 'json');
+
+            const n = json.length;
+
+            for (let i = 0; i < n; i++) {
+                this.add(json[i]);
+            }
         }
     }