@woosh/meep-engine 2.78.0 → 2.79.0

package/build/meep.module.js

@@ -1978,10 +1978,15 @@ function v3_length(x, y, z) {
  * @param {number} z1
  * @returns {number}
  */
-function v3_angle_between(x0, y0, z0, x1, y1, z1) {
+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);
+
 }
 
 /**
@@ -1992,9 +1997,13 @@ 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
  */
-function v3_angle_cos_between(x0, y0, z0, x1, y1, z1){
+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);
@@ -2004,10 +2013,12 @@ 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$1(d / l, -1, 1);
+
 }
 
 /**
@@ -4706,7 +4717,7 @@ let Quaternion$1 = 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) {
 
@@ -70583,10 +70594,19 @@ class Edge {
         return this.first === node || this.second === node;
     }
 
+    /**
+     *
+     * @param {N} source
+     * @param {N} target
+     * @returns {boolean} True  iff the edge contains both source and target and allows transition from source to target
+     */
     validateTransition(source, target) {
         const a = this.first;
         const b = this.second;
-        return (a === source && b === target && this.traversableForward()) || (b === source && a === target && this.traversableBackward());
+
+        return (a === source && b === target && this.traversableForward())
+            || (b === source && a === target && this.traversableBackward())
+            ;
     }
 
     /**
@@ -70634,16 +70654,6 @@ class Edge {
             || (this.second === node && this.direction === EdgeDirectionType.Backward)
     }
 
-    /**
-     * @deprecated
-     * @returns {number}
-     */
-    angle() {
-
-        const delta = this.second.clone().sub(this.first);
-        return Math.atan2(delta.y, delta.x);
-    }
-
     /**
      *
      * @returns {N[]}
@@ -70652,15 +70662,6 @@ class Edge {
         return [this.first, this.second];
     }
 
-
-    /**
-     * @deprecated
-     * @returns {number}
-     */
-    get length() {
-
-        return this.first.distanceTo(this.second);
-    }
 }
 
 /**
@@ -70691,6 +70692,7 @@ class NodeContainer {
     /**
      *
      * @type {Map<N,number>}
+     * Maps neighbour node to number of edges to that node from this one
      * @private
      */
     __neighbors = new Map();
@@ -71084,6 +71086,7 @@ class Graph {
     /**
      *
      * @param {N} node
+     * @returns {boolean}
      */
     removeNode(node) {
 
@@ -71157,7 +71160,7 @@ class Graph {
     }
 
     /**
-     *
+     * Node degree is the number of attached edges
      * @param {N} node
      * @return {number}
      */
@@ -71199,13 +71202,18 @@ class Graph {
      *
      * @param {N} source
      * @param {N} target
-     * @param {EdgeDirectionType} [type] Undirected by default
+     * @param {EdgeDirectionType} [direction] Undirected by default
      * @returns {Edge<N>}
      */
-    createEdge(source, target, type = EdgeDirectionType.Undirected) {
+    createEdge(
+        source,
+        target,
+        direction = EdgeDirectionType.Undirected
+    ) {
+
         const edge = new Edge(source, target);
 
-        edge.direction = type;
+        edge.direction = direction;
 
         this.addEdge(edge);
 
@@ -71213,9 +71221,10 @@ class Graph {
     }
 
     /**
-     *
+     * Both nodes that the edge is attached to must be present
      * @param {Edge<N>} edge
-     * @returns {boolean}
+     * @returns {boolean} true if edge was added, false if edge was already present
+     * @throws if one or both nodes are not contained in the graph
      */
     addEdge(edge) {
         if (this.hasEdge(edge)) {
@@ -71417,10 +71426,10 @@ class Graph {
     }
 
     /**
-     *
+     * Find a path through the graph
      * @param {N} start
      * @param {N} goal
-     * @returns {null|N[]}
+     * @returns {null|N[]} null if no path exists
      */
     findPath(start, goal) {
         const start_node_container = this.__nodes.get(start);
@@ -71460,6 +71469,7 @@ class Graph {
                 const b = edge.second;
 
                 let other = null;
+
                 if (a === current_node && (edge.direction === EdgeDirectionType.Forward || edge.direction === EdgeDirectionType.Undirected)) {
                     other = b;
                 } else if (b === current_node && (edge.direction === EdgeDirectionType.Backward || edge.direction === EdgeDirectionType.Undirected)) {
@@ -71488,6 +71498,9 @@ class Graph {
         return null;
     }
 
+    /**
+     * Remove all data from the graph, resetting it to empty state
+     */
     clear() {
         this.__nodes.clear();
         this.__edges.clear();
@@ -72956,6 +72969,7 @@ class TransformAttachment {
 
     /**
      * transform relative to the attachment target
+     * Think of it as "local transform"
      * @type {Transform}
      */
     transform = new Transform();
@@ -73569,7 +73583,10 @@ class UpdateContext {
     }
 
     update() {
-        this.transform.multiplyTransforms(this.parent_transform, this.attachment.transform);
+        this.transform.multiplyTransforms(
+            this.parent_transform,
+            this.attachment.transform
+        );
     }
 
     /**
@@ -73592,51 +73609,51 @@ class UpdateContext {
     link() {
         const t_parent = this.parent_transform;
 
-        t_parent.position.onChanged.add(this.update, this);
-        t_parent.rotation.onChanged.add(this.update, this);
-        t_parent.scale.onChanged.add(this.update, this);
+        t_parent.subscribe(this.update, this);
 
         const t_attachment = this.attachment.transform;
-        t_attachment.position.onChanged.add(this.update,this);
-        t_attachment.rotation.onChanged.add(this.update,this);
-        t_attachment.scale.onChanged.add(this.update,this);
+
+        t_attachment.subscribe(this.update, this);
     }
 
     unlink() {
         const transform = this.parent_transform;
 
-        transform.position.onChanged.remove(this.update, this);
-        transform.rotation.onChanged.remove(this.update, this);
-        transform.scale.onChanged.remove(this.update, this);
+        transform.unsubscribe(this.update, this);
 
         const t_attachment = this.attachment.transform;
-        t_attachment.position.onChanged.remove(this.update,this);
-        t_attachment.rotation.onChanged.remove(this.update,this);
-        t_attachment.scale.onChanged.remove(this.update,this);
+
+        t_attachment.unsubscribe(this.update, this);
     }
 }
 
 class TransformAttachmentSystem extends System {
+
+    /**
+     *
+     * @type {UpdateContext[]}
+     * @private
+     */
+    __contexts = [];
+
+    /**
+     *
+     * @type {UpdateContext[]}
+     * @private
+     */
+    __queue = [];
+    __queue_size = 0;
+    __queue_cursor = 0;
+
     constructor() {
         super();
 
         this.dependencies = [TransformAttachment, Transform];
 
-        /**
-         *
-         * @type {UpdateContext[]}
-         * @private
-         */
-        this.__contexts = [];
-
-        /**
-         *
-         * @type {UpdateContext[]}
-         * @private
-         */
-        this.__queue = [];
-        this.__queue_size = 0;
-        this.__queue_cursor = 0;
+        this.components_used = [
+            ResourceAccessSpecification.from(TransformAttachment, ResourceAccessKind.Read),
+            ResourceAccessSpecification.from(Transform, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ];
     }
 
     /**
@@ -73664,6 +73681,12 @@ class TransformAttachmentSystem extends System {
         this.__queue[this.__queue_size++] = ctx;
     }
 
+    /**
+     *
+     * @param {number} entity
+     * @returns {boolean}
+     * @private
+     */
     __dequeue_entity(entity) {
         for (let i = 0; i < this.__queue_size; i++) {
             const ctx = this.__queue[i];
@@ -73692,9 +73715,7 @@ class TransformAttachmentSystem extends System {
         ctx.entity = entity;
 
 
-        const ecd = this.entityManager.dataset;
-
-        ctx.ecd = ecd;
+        ctx.ecd = this.entityManager.dataset;
 
         if (ctx.bind_parent()) {
             this.__finalize_link(ctx);
@@ -73729,12 +73750,14 @@ class TransformAttachmentSystem extends System {
 
     update(timeDelta) {
         const step_count = min2(this.__queue_size, QUEUE_ITERATION_COUNT);
+
         for (let i = 0; i < step_count; i++) {
             const index = this.__queue_cursor % this.__queue_size;
 
             const ctx = this.__queue[index];
 
             if (ctx.bind_parent()) {
+                // parent obtained
                 this.__finalize_link(ctx);
 
                 this.__queue.splice(index, 1);
@@ -73744,6 +73767,7 @@ class TransformAttachmentSystem extends System {
                 this.__queue_cursor++;
             }
         }
+
     }
 }
 

package/package.json

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

package/src/core/{graph → geom/3d/topology}/build_face_graph_from_mesh.js

@@ -1,8 +1,8 @@
-import { Graph } from "./v2/Graph.js";
-import { MultiNode } from "./MultiNode.js";
-import { compute_face_connection_weight } from "../geom/3d/topology/util/compute_face_connection_weight.js";
-import { WeightedEdge } from "./WeightedEdge.js";
-import { graph_compute_disconnected_clusters } from "./graph_compute_disconnected_clusters.js";
+import { graph_compute_disconnected_clusters } from "../../../graph/graph_compute_disconnected_clusters.js";
+import { MultiNode } from "../../../graph/MultiNode.js";
+import { Graph } from "../../../graph/v2/Graph.js";
+import { WeightedEdge } from "../../../graph/WeightedEdge.js";
+import { compute_face_connection_weight } from "./util/compute_face_connection_weight.js";
 
 
 /**

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/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/Edge.js

@@ -55,10 +55,19 @@ export class Edge {
         return this.first === node || this.second === node;
     }
 
+    /**
+     *
+     * @param {N} source
+     * @param {N} target
+     * @returns {boolean} True  iff the edge contains both source and target and allows transition from source to target
+     */
     validateTransition(source, target) {
         const a = this.first;
         const b = this.second;
-        return (a === source && b === target && this.traversableForward()) || (b === source && a === target && this.traversableBackward());
+
+        return (a === source && b === target && this.traversableForward())
+            || (b === source && a === target && this.traversableBackward())
+            ;
     }
 
     /**
@@ -106,17 +115,6 @@ export class Edge {
             || (this.second === node && this.direction === EdgeDirectionType.Backward)
     }
 
-    /**
-     * @deprecated
-     * @returns {number}
-     */
-    angle() {
-        console.error('method is deprecated, do not use');
-
-        const delta = this.second.clone().sub(this.first);
-        return Math.atan2(delta.y, delta.x);
-    }
-
     /**
      *
      * @returns {N[]}
@@ -125,16 +123,6 @@ export class Edge {
         return [this.first, this.second];
     }
 
-
-    /**
-     * @deprecated
-     * @returns {number}
-     */
-    get length() {
-        console.error('method is deprecated, do not use');
-
-        return this.first.distanceTo(this.second);
-    }
 }
 
 /**

package/src/core/graph/Edge.spec.js

@@ -48,3 +48,38 @@ test('other', () => {
     expect(edge.other(3)).toBe(7);
     expect(edge.other(7)).toBe(3);
 });
+
+
+test("isDirectedTowards", () => {
+    const e = new Edge(1, 3);
+
+    e.direction = EdgeDirectionType.Forward;
+
+    expect(e.isDirectedTowards(3)).toBe(true);
+    expect(e.isDirectedTowards(1)).toBe(false);
+
+    e.direction = EdgeDirectionType.Backward;
+
+    expect(e.isDirectedTowards(3)).toBe(false);
+    expect(e.isDirectedTowards(1)).toBe(true);
+});
+
+test("isDirectedAwayFrom", () => {
+    const e = new Edge(1, 3);
+
+    e.direction = EdgeDirectionType.Forward;
+
+    expect(e.isDirectedAwayFrom(3)).toBe(false);
+    expect(e.isDirectedAwayFrom(1)).toBe(true);
+
+    e.direction = EdgeDirectionType.Backward;
+
+    expect(e.isDirectedAwayFrom(3)).toBe(true);
+    expect(e.isDirectedAwayFrom(1)).toBe(false);
+});
+
+test("nodes accessor", () => {
+    const e = new Edge(1, 3);
+
+    expect(e.nodes).toEqual([1, 3]);
+});

package/src/core/graph/MultiNode.js

@@ -1,14 +1,13 @@
 /**
+ * A grouping node, intended mainly for meta-graphs, or hierarchical graphs
  * @template T
  */
 export class MultiNode {
-    constructor() {
-        /**
-         *
-         * @type {T[]}
-         */
-        this.source_nodes = [];
-    }
+    /**
+     *
+     * @type {T[]}
+     */
+    source_nodes = [];
 
     /**
      *

package/src/core/graph/v2/Graph.js

@@ -92,6 +92,7 @@ export class Graph {
     /**
      *
      * @param {N} node
+     * @returns {boolean}
      */
     removeNode(node) {
 
@@ -165,7 +166,7 @@ export class Graph {
     }
 
     /**
-     *
+     * Node degree is the number of attached edges
      * @param {N} node
      * @return {number}
      */
@@ -207,13 +208,19 @@ export class Graph {
      *
      * @param {N} source
      * @param {N} target
-     * @param {EdgeDirectionType} [type] Undirected by default
+     * @param {EdgeDirectionType} [direction] Undirected by default
      * @returns {Edge<N>}
      */
-    createEdge(source, target, type = EdgeDirectionType.Undirected) {
+    createEdge(
+        source,
+        target,
+        direction = EdgeDirectionType.Undirected
+    ) {
+        assert.enum(direction, EdgeDirectionType, 'direction');
+
         const edge = new Edge(source, target);
 
-        edge.direction = type;
+        edge.direction = direction;
 
         this.addEdge(edge);
 
@@ -221,9 +228,10 @@ export class Graph {
     }
 
     /**
-     *
+     * Both nodes that the edge is attached to must be present
      * @param {Edge<N>} edge
-     * @returns {boolean}
+     * @returns {boolean} true if edge was added, false if edge was already present
+     * @throws if one or both nodes are not contained in the graph
      */
     addEdge(edge) {
         if (this.hasEdge(edge)) {
@@ -431,10 +439,10 @@ export class Graph {
     }
 
     /**
-     *
+     * Find a path through the graph
      * @param {N} start
      * @param {N} goal
-     * @returns {null|N[]}
+     * @returns {null|N[]} null if no path exists
      */
     findPath(start, goal) {
         const start_node_container = this.__nodes.get(start);
@@ -474,6 +482,7 @@ export class Graph {
                 const b = edge.second;
 
                 let other = null;
+
                 if (a === current_node && (edge.direction === EdgeDirectionType.Forward || edge.direction === EdgeDirectionType.Undirected)) {
                     other = b;
                 } else if (b === current_node && (edge.direction === EdgeDirectionType.Backward || edge.direction === EdgeDirectionType.Undirected)) {
@@ -502,6 +511,9 @@ export class Graph {
         return null;
     }
 
+    /**
+     * Remove all data from the graph, resetting it to empty state
+     */
     clear() {
         this.__nodes.clear();
         this.__edges.clear();

package/src/core/graph/v2/NodeContainer.js

@@ -22,6 +22,7 @@ export class NodeContainer {
     /**
      *
      * @type {Map<N,number>}
+     * Maps neighbour node to number of edges to that node from this one
      * @private
      */
     __neighbors = new Map();

package/src/engine/ecs/ik/OneBoneSurfaceAlignmentSolver.js

@@ -1,6 +1,6 @@
 import { SurfacePoint3 } from "../../../core/geom/3d/SurfacePoint3.js";
 import Quaternion from "../../../core/geom/Quaternion.js";
-import { v3_computeOffsetVector } from "../../../core/geom/vec3/v3_computeOffsetVector.js";
+import { v3_displace_in_direction } from "../../../core/geom/vec3/v3_displace_in_direction.js";
 import { v3_dot } from "../../../core/geom/vec3/v3_dot.js";
 import { v3_length } from "../../../core/geom/vec3/v3_length.js";
 import Vector3 from "../../../core/geom/Vector3.js";
@@ -116,7 +116,7 @@ export class OneBoneSurfaceAlignmentSolver extends IKSolver {
 
         const targetOffsetDistance = constraint.offset * bone_scale;
 
-        v3_computeOffsetVector(
+        v3_displace_in_direction(
             targetPosition,
             targetOffsetDistance,
             contactPosition.x, contactPosition.y, contactPosition.z,