@woosh/meep-engine 2.78.1 → 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) {
 
@@ -72958,6 +72969,7 @@ class TransformAttachment {
 
     /**
      * transform relative to the attachment target
+     * Think of it as "local transform"
      * @type {Transform}
      */
     transform = new Transform();
@@ -73571,7 +73583,10 @@ class UpdateContext {
     }
 
     update() {
-        this.transform.multiplyTransforms(this.parent_transform, this.attachment.transform);
+        this.transform.multiplyTransforms(
+            this.parent_transform,
+            this.attachment.transform
+        );
     }
 
     /**
@@ -73594,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),
+        ];
     }
 
     /**
@@ -73666,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];
@@ -73694,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);
@@ -73731,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);
@@ -73746,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.1",
+  "version": "2.79.0",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

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/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,

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

@@ -1,7 +1,7 @@
 import { assert } from "../../../core/assert.js";
 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";
@@ -255,7 +255,7 @@ export class TwoBoneInverseKinematicsSolver extends IKSolver {
 
         const targetOffsetDistance = constraint.offset * limbLength;
 
-        v3_computeOffsetVector(
+        v3_displace_in_direction(
             targetPosition,
             targetOffsetDistance,
             contactPosition.x, contactPosition.y, contactPosition.z,

package/src/engine/ecs/transform-attachment/TransformAttachment.js

@@ -1,5 +1,5 @@
-import { Transform } from "../transform/Transform.js";
 import { assert } from "../../../core/assert.js";
+import { Transform } from "../transform/Transform.js";
 
 export const TransformAttachmentFlags = {
     /**
@@ -15,6 +15,7 @@ export class TransformAttachment {
 
     /**
      * transform relative to the attachment target
+     * Think of it as "local transform"
      * @type {Transform}
      */
     transform = new Transform();

package/src/engine/ecs/transform-attachment/TransformAttachmentSystem.js

@@ -1,7 +1,9 @@
+import { min2 } from "../../../core/math/min2.js";
+import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
 import { System } from "../System.js";
-import { TransformAttachment, TransformAttachmentFlags } from "./TransformAttachment.js";
 import { Transform } from "../transform/Transform.js";
-import { min2 } from "../../../core/math/min2.js";
+import { TransformAttachment, TransformAttachmentFlags } from "./TransformAttachment.js";
 
 /**
  * @readonly
@@ -47,7 +49,10 @@ class UpdateContext {
     }
 
     update() {
-        this.transform.multiplyTransforms(this.parent_transform, this.attachment.transform);
+        this.transform.multiplyTransforms(
+            this.parent_transform,
+            this.attachment.transform
+        );
     }
 
     /**
@@ -70,51 +75,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);
     }
 }
 
 export 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),
+        ];
     }
 
     /**
@@ -142,6 +147,12 @@ export 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];
@@ -170,9 +181,7 @@ export 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);
@@ -207,12 +216,14 @@ export 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);
@@ -222,5 +233,6 @@ export class TransformAttachmentSystem extends System {
                 this.__queue_cursor++;
             }
         }
+
     }
 }