@woosh/meep-engine 3.40.0 → 3.42.0

package/src/core/events/signal/SignalBinding.js

@@ -1,101 +1,101 @@
-/**
- * @typedef {import("./Signal.js").default} Signal
- */
-
-/**
- * Utility class for managing connection between listeners to signals
- */
-export class SignalBinding {
-    /**
-     * State flag
-     * @type {boolean}
-     */
-    #linked = false;
-
-    get linked() {
-        return this.#linked;
-    }
-
-    /**
-     *
-     * @param {Signal} signal
-     * @param {function} handler
-     * @param {*} [context] will be passed as thisArg to the handler
-     * @constructor
-     */
-    constructor(signal, handler, context) {
-        if (typeof handler !== "function") {
-            throw new TypeError(`handler must be a function, instead was '${typeof handler}'`);
-        }
-
-        if (typeof signal !== "object") {
-            throw new TypeError(`signal must be of an object, instead was '${typeof signal}'`)
-        }
-
-        if (typeof signal.add !== "function") {
-            throw new TypeError(`signal.add must be a function, instead was '${typeof signal.add}'`);
-        }
-
-        /**
-         * Binding signal
-         * @type {Signal}
-         */
-        this.signal = signal;
-
-        /**
-         * Signal handler to be attached to the signal
-         * @type {Function}
-         */
-        this.handler = handler;
-
-        /**
-         *
-         * @type {*}
-         */
-        this.context = context;
-
-    }
-
-    /**
-     * Attaches handler to the signal
-     * Idempotent
-     */
-    link() {
-        if (this.#linked) {
-            return;
-        }
-
-        this.#linked = true;
-        this.signal.add(this.handler, this.context);
-    }
-
-    /**
-     * Detaches handler from the signal
-     * Idempotent
-     */
-    unlink() {
-        if (!this.#linked) {
-            return;
-        }
-
-        this.#linked = false;
-        this.signal.remove(this.handler, this.context);
-    }
-
-    /**
-     * Creates a {@link SignalBinding} and links it immediately. Utility method
-     * @param {Signal} signal
-     * @param {function} handler
-     * @param {*} [context]
-     * @return {SignalBinding}
-     */
-    static bind(
-        signal, handler, context
-    ) {
-        const r = new SignalBinding(signal, handler, context);
-
-        r.link();
-
-        return r;
-    }
-}
+/**
+ * @typedef {import("./Signal.js").default} Signal
+ */
+
+/**
+ * Utility class for managing connection between listeners to signals
+ */
+export class SignalBinding {
+    /**
+     * State flag
+     * @type {boolean}
+     */
+    #linked = false;
+
+    get linked() {
+        return this.#linked;
+    }
+
+    /**
+     *
+     * @param {Signal} signal
+     * @param {function} handler
+     * @param {*} [context] will be passed as thisArg to the handler
+     * @constructor
+     */
+    constructor(signal, handler, context) {
+        if (typeof handler !== "function") {
+            throw new TypeError(`handler must be a function, instead was '${typeof handler}'`);
+        }
+
+        if (typeof signal !== "object") {
+            throw new TypeError(`signal must be of an object, instead was '${typeof signal}'`)
+        }
+
+        if (typeof signal.add !== "function") {
+            throw new TypeError(`signal.add must be a function, instead was '${typeof signal.add}'`);
+        }
+
+        /**
+         * Binding signal
+         * @type {Signal}
+         */
+        this.signal = signal;
+
+        /**
+         * Signal handler to be attached to the signal
+         * @type {Function}
+         */
+        this.handler = handler;
+
+        /**
+         *
+         * @type {*}
+         */
+        this.context = context;
+
+    }
+
+    /**
+     * Attaches handler to the signal
+     * Idempotent
+     */
+    link() {
+        if (this.#linked) {
+            return;
+        }
+
+        this.signal.add(this.handler, this.context);
+        this.#linked = true;
+    }
+
+    /**
+     * Detaches handler from the signal
+     * Idempotent
+     */
+    unlink() {
+        if (!this.#linked) {
+            return;
+        }
+
+        this.#linked = false;
+        this.signal.remove(this.handler, this.context);
+    }
+
+    /**
+     * Creates a {@link SignalBinding} and links it immediately. Utility method
+     * @param {Signal} signal
+     * @param {function} handler
+     * @param {*} [context]
+     * @return {SignalBinding}
+     */
+    static bind(
+        signal, handler, context
+    ) {
+        const r = new SignalBinding(signal, handler, context);
+
+        r.link();
+
+        return r;
+    }
+}

package/src/core/function/extractFunctionBody.js

@@ -1,13 +1,13 @@
-/**
- *
- * @param {function} f
- * @returns {string}
- */
-export function extractFunctionBody(f) {
-
-    const entire = f.toString();
-
-    const body = entire.slice(entire.indexOf("{") + 1, entire.lastIndexOf("}")).trim();
-
-    return body;
-}
+/**
+ *
+ * @param {function} f
+ * @returns {string}
+ */
+export function extractFunctionBody(f) {
+
+    const entire = f.toString();
+
+    const body = entire.slice(entire.indexOf("{") + 1, entire.lastIndexOf("}")).trim();
+
+    return body;
+}

package/src/core/function/objectsEqual.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"objectsEqual.d.ts","sourceRoot":"","sources":["../../../../src/core/function/objectsEqual.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,8CAFa,OAAO,CAUnB"}
+{"version":3,"file":"objectsEqual.d.ts","sourceRoot":"","sources":["../../../../src/core/function/objectsEqual.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,8CAFa,OAAO,CAWnB"}

package/src/core/function/objectsEqual.js

@@ -1,15 +1,16 @@
-/**
- *
- * @param {Object} a
- * @param {Object} b
- * @returns {boolean}
- */
-export function objectsEqual(a, b) {
-    return a === b
-        || (
-            typeof a === "object" // guard against undefined values
-            && a !== null // typeof null === "object", so null must be excluded explicitly
-            && typeof a.equals === "function" // check for equals method
-            && a.equals(b)
-        );
+/**
+ *
+ * @param {Object} a
+ * @param {Object} b
+ * @returns {boolean}
+ */
+export function objectsEqual(a, b) {
+    return a === b
+        || (
+            typeof a === "object" // guard against undefined values
+            && a !== null // typeof null === "object", so null must be excluded explicitly
+            && b !== null && b !== undefined
+            && typeof a.equals === "function" // check for equals method
+            && a.equals(b)
+        );
 }

package/src/core/geom/3d/frustum/frustum3_compute_closest_point.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frustum3_compute_closest_point.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/frustum/frustum3_compute_closest_point.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;GAeG;AACH,uDAPW,OAAO,UACP,SAAS,YACT,MAAM,YACN,MAAM,YACN,MAAM,GACJ,OAAO,CA8HnB;oBA1KmB,kBAAkB"}
+{"version":3,"file":"frustum3_compute_closest_point.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/frustum/frustum3_compute_closest_point.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;GAeG;AACH,uDAPW,OAAO,UACP,SAAS,YACT,MAAM,YACN,MAAM,YACN,MAAM,GACJ,OAAO,CAyKnB;oBA7MmB,kBAAkB"}

package/src/core/geom/3d/frustum/frustum3_compute_closest_point.js

@@ -1,172 +1,207 @@
-import { v3_distance_above_plane } from "../../vec3/v3_distance_above_plane.js";
-import Vector3 from "../../Vector3.js";
-import { plane3_compute_3_plane_intersection } from "../plane/plane3_compute_3_plane_intersection.js";
-import { plane3_compute_intersection } from "../plane/plane3_compute_intersection.js";
-import { plane3_project_point } from "../plane/plane3_project_point.js";
-import { ray3_compute_closest_point } from "../ray/ray3_compute_closest_point.js";
-
-/**
- * Indices into the caller's plane list, for the planes the target lies outside of.
- * @type {number[]}
- */
-const scratch_outer_planes = [];
-
-const scratch_v3_0 = new Vector3();
-
-const scratch_v3_1 = new Vector3();
-
-/**
- *
- * @type {number[]}
- */
-const scratch_v3_array = [];
-
-/**
- * How many projection rounds the four-or-more-planes fallback takes before it settles for where it
- * has got to. Bounded rather than convergent: the loop must not be able to spin on a degenerate
- * frustum.
- * @type {number}
- */
-const CLAMP_ITERATION_LIMIT = 32;
-
-/**
- * The point inside a convex frustum nearest to a target point, and whether the target was already
- * inside it.
- *
- * **A plane is a `Vector4`**: `x, y, z` its normal and `w` its constant, inside where
- * `dot(normal, p) + w` is non-negative. That is the same four numbers every frustum query in the
- * tree reads and what `camera_active_frustum` publishes; it used to be a three `Plane`, whose
- * `normal`/`constant` pair is the same thing wearing an object (X15d).
- *
- * @param {Vector3} result
- * @param {Vector4[]} planes
- * @param {number} target_x
- * @param {number} target_y
- * @param {number} target_z
- * @returns {boolean} if point is inside the frustum - true, false otherwise
- */
-export function frustum3_compute_closest_point(result, planes, target_x, target_y, target_z) {
-    let j;
-
-    let outside_plane_count = 0;
-
-    const plane_count = planes.length;
-
-    for (j = 0; j < plane_count; j++) {
-
-        const plane = planes[j];
-
-        const distance = v3_distance_above_plane(
-            target_x, target_y, target_z,
-            plane.x, plane.y, plane.z, plane.w
-        );
-
-        if (distance < 0) {
-
-            scratch_outer_planes[outside_plane_count] = j;
-
-            outside_plane_count++;
-
-        }
-
-    }
-
-    if (outside_plane_count === 0) {
-        result.set(target_x, target_y, target_z);
-
-        return true;
-    }
-
-    // point is outside the frustum
-
-    if (outside_plane_count === 1) {
-        const plane_0 = planes[scratch_outer_planes[0]];
-
-        // point lies outside exactly one plane
-        plane3_project_point(result, target_x, target_y, target_z, plane_0.x, plane_0.y, plane_0.z, plane_0.w);
-    } else if (outside_plane_count === 2) {
-        // outside two planes, nearest point lies on the intersection line of two planes
-
-        const plane_0 = planes[scratch_outer_planes[0]];
-        const plane_1 = planes[scratch_outer_planes[1]];
-
-        const intersection_exists = plane3_compute_intersection(
-            scratch_v3_0, scratch_v3_1,
-            plane_0.x, plane_0.y, plane_0.z, plane_0.w,
-            plane_1.x, plane_1.y, plane_1.z, plane_1.w
-        );
-
-        if (!intersection_exists) {
-            throw new Error('Planes are parallel and do not intersect, likely an invalid frustum');
-        }
-
-        ray3_compute_closest_point(result,
-            scratch_v3_0.x, scratch_v3_0.y, scratch_v3_0.z,
-            scratch_v3_1.x, scratch_v3_1.y, scratch_v3_1.z,
-            target_x, target_y, target_z
-        );
-    } else if (outside_plane_count === 3) {
-        // outside 3 planes, nearest point is intersect of 3 planes
-        const plane_0 = planes[scratch_outer_planes[0]];
-        const plane_1 = planes[scratch_outer_planes[1]];
-        const plane_2 = planes[scratch_outer_planes[2]];
-
-        plane3_compute_3_plane_intersection(
-            scratch_v3_array, 0,
-            plane_0.x, plane_0.y, plane_0.z, plane_0.w,
-            plane_1.x, plane_1.y, plane_1.z, plane_1.w,
-            plane_2.x, plane_2.y, plane_2.z, plane_2.w
-        );
-
-        result.fromArray(scratch_v3_array, 0)
-    } else {
-        // Four or more violated planes has no closed form here, and a perspective frustum reaches
-        // that easily: its side planes all pass through the apex, so any point behind the camera is
-        // outside near, left, right, top and bottom at once. Falling out of the chain left `result`
-        // holding whatever the caller's vector had — with a reused scratch, the *previous* query's
-        // answer, which reads as a plausibly placed point rather than as a failure.
-        //
-        // Walk the point back in by repeatedly projecting it onto whichever plane it violates
-        // most. For a convex body that converges into the intersection; it is not guaranteed to be
-        // the exact nearest point, but it is inside, and it is written.
-        let px = target_x;
-        let py = target_y;
-        let pz = target_z;
-
-        for (let iteration = 0; iteration < CLAMP_ITERATION_LIMIT; iteration++) {
-            let worst_plane = -1;
-            let worst_distance = 0;
-
-            for (j = 0; j < plane_count; j++) {
-                const plane = planes[j];
-
-                const distance = v3_distance_above_plane(
-                    px, py, pz,
-                    plane.x, plane.y, plane.z, plane.w
-                );
-
-                if (distance < worst_distance) {
-                    worst_distance = distance;
-                    worst_plane = j;
-                }
-            }
-
-            if (worst_plane === -1) {
-                // inside every plane
-                break;
-            }
-
-            const plane = planes[worst_plane];
-
-            plane3_project_point(scratch_v3_0, px, py, pz, plane.x, plane.y, plane.z, plane.w);
-
-            px = scratch_v3_0.x;
-            py = scratch_v3_0.y;
-            pz = scratch_v3_0.z;
-        }
-
-        result.set(px, py, pz);
-    }
-
-    return false;
-}
+import { v3_distance_above_plane } from "../../vec3/v3_distance_above_plane.js";
+import Vector3 from "../../Vector3.js";
+import { plane3_compute_intersection } from "../plane/plane3_compute_intersection.js";
+import { plane3_project_point } from "../plane/plane3_project_point.js";
+
+/**
+ * Indices into the caller's plane list, for the planes the target lies outside of.
+ * @type {number[]}
+ */
+const scratch_outer_planes = [];
+
+const scratch_v3_0 = new Vector3();
+
+const scratch_v3_1 = new Vector3();
+
+/**
+ * How many projection rounds the degenerate-edge fallback takes before it settles for where it
+ * has got to. Bounded rather than convergent: the loop must not be able to spin on a degenerate
+ * frustum.
+ * @type {number}
+ */
+const CLAMP_ITERATION_LIMIT = 32;
+
+/**
+ * The point inside a convex frustum nearest to a target point, and whether the target was already
+ * inside it.
+ *
+ * **A plane is a `Vector4`**: `x, y, z` its normal and `w` its constant, inside where
+ * `dot(normal, p) + w` is non-negative. That is the same four numbers every frustum query in the
+ * tree reads and what `camera_active_frustum` publishes; it used to be a three `Plane`, whose
+ * `normal`/`constant` pair is the same thing wearing an object (X15d).
+ *
+ * @param {Vector3} result
+ * @param {Vector4[]} planes
+ * @param {number} target_x
+ * @param {number} target_y
+ * @param {number} target_z
+ * @returns {boolean} if point is inside the frustum - true, false otherwise
+ */
+export function frustum3_compute_closest_point(result, planes, target_x, target_y, target_z) {
+    let j;
+
+    let outside_plane_count = 0;
+
+    const plane_count = planes.length;
+
+    for (j = 0; j < plane_count; j++) {
+
+        const plane = planes[j];
+
+        const distance = v3_distance_above_plane(
+            target_x, target_y, target_z,
+            plane.x, plane.y, plane.z, plane.w
+        );
+
+        if (distance < 0) {
+
+            scratch_outer_planes[outside_plane_count] = j;
+
+            outside_plane_count++;
+
+        }
+
+    }
+
+    if (outside_plane_count === 0) {
+        result.set(target_x, target_y, target_z);
+
+        return true;
+    }
+
+    // point is outside the frustum
+
+    // Several violated planes need not all meet at the nearest point. A feasible face projection
+    // attains that halfspace's distance lower bound, so it is also nearest to the whole frustum.
+    for (let candidate = 0; candidate < outside_plane_count; candidate++) {
+        const face = planes[scratch_outer_planes[candidate]];
+        // Stored Float32 normals are only approximately unit length.
+        const normal_length_squared = face.x * face.x + face.y * face.y + face.z * face.z;
+        const offset = -v3_distance_above_plane(target_x, target_y, target_z, face.x, face.y, face.z, face.w)
+            / normal_length_squared;
+        scratch_v3_0.set(target_x + face.x * offset, target_y + face.y * offset, target_z + face.z * offset);
+
+        let inside = true;
+        for (j = 0; j < plane_count; j++) {
+            if (j === scratch_outer_planes[candidate]) {
+                // The projection lies on this face; recomputing it can produce roundoff below zero.
+                continue;
+            }
+            const plane = planes[j];
+            if (v3_distance_above_plane(
+                scratch_v3_0.x, scratch_v3_0.y, scratch_v3_0.z,
+                plane.x, plane.y, plane.z, plane.w
+            ) < 0) {
+                inside = false;
+                break;
+            }
+        }
+
+        if (inside) {
+            result.copy(scratch_v3_0);
+            return false;
+        }
+    }
+
+    // If no face projection is feasible, the closest point is on an edge or corner.
+    // At least one active plane was initially violated; clip its intersection lines to the frustum.
+    let best_distance_squared = Infinity;
+    let best_x = 0, best_y = 0, best_z = 0;
+    for (let candidate = 0; candidate < outside_plane_count; candidate++) {
+        const face_index = scratch_outer_planes[candidate];
+        const face = planes[face_index];
+        for (let edge_index = 0; edge_index < plane_count; edge_index++) {
+            if (edge_index === face_index) continue;
+            const edge_plane = planes[edge_index];
+            if (edge_index < face_index && v3_distance_above_plane(
+                target_x, target_y, target_z,
+                edge_plane.x, edge_plane.y, edge_plane.z, edge_plane.w
+            ) < 0) continue;
+            if (!plane3_compute_intersection(
+                scratch_v3_0, scratch_v3_1,
+                face.x, face.y, face.z, face.w,
+                edge_plane.x, edge_plane.y, edge_plane.z, edge_plane.w
+            )) continue;
+
+            const ox = scratch_v3_0.x, oy = scratch_v3_0.y, oz = scratch_v3_0.z;
+            const dx = scratch_v3_1.x, dy = scratch_v3_1.y, dz = scratch_v3_1.z;
+            let lower = -Infinity;
+            let upper = Infinity;
+            for (j = 0; j < plane_count; j++) {
+                if (j === face_index || j === edge_index) continue;
+                const plane = planes[j];
+                const along = plane.x * dx + plane.y * dy + plane.z * dz;
+                const at_origin = v3_distance_above_plane(ox, oy, oz, plane.x, plane.y, plane.z, plane.w);
+                if (along > 0) {
+                    lower = Math.max(lower, -at_origin / along);
+                } else if (along < 0) {
+                    upper = Math.min(upper, -at_origin / along);
+                } else if (at_origin < 0) {
+                    lower = Infinity;
+                    upper = -Infinity;
+                    break;
+                }
+            }
+            if (lower > upper) continue;
+
+            const direction_length_squared = dx * dx + dy * dy + dz * dz;
+            const target_parameter = ((target_x - ox) * dx + (target_y - oy) * dy + (target_z - oz) * dz)
+                / direction_length_squared;
+            const parameter = Math.max(lower, Math.min(upper, target_parameter));
+            const px = ox + dx * parameter, py = oy + dy * parameter, pz = oz + dz * parameter;
+            const tx = px - target_x, ty = py - target_y, tz = pz - target_z;
+            const distance_squared = tx * tx + ty * ty + tz * tz;
+            if (distance_squared < best_distance_squared) {
+                best_distance_squared = distance_squared;
+                best_x = px;
+                best_y = py;
+                best_z = pz;
+            }
+        }
+    }
+    if (best_distance_squared < Infinity) {
+        result.set(best_x, best_y, best_z);
+        return false;
+    }
+
+    // Retain the bounded projection fallback if no usable clipped edge was obtained.
+    let px = target_x;
+    let py = target_y;
+    let pz = target_z;
+
+    for (let iteration = 0; iteration < CLAMP_ITERATION_LIMIT; iteration++) {
+        let worst_plane = -1;
+        let worst_distance = 0;
+
+        for (j = 0; j < plane_count; j++) {
+            const plane = planes[j];
+
+            const distance = v3_distance_above_plane(
+                px, py, pz,
+                plane.x, plane.y, plane.z, plane.w
+            );
+
+            if (distance < worst_distance) {
+                worst_distance = distance;
+                worst_plane = j;
+            }
+        }
+
+        if (worst_plane === -1) {
+            // inside every plane
+            break;
+        }
+
+        const plane = planes[worst_plane];
+
+        plane3_project_point(scratch_v3_0, px, py, pz, plane.x, plane.y, plane.z, plane.w);
+
+        px = scratch_v3_0.x;
+        py = scratch_v3_0.y;
+        pz = scratch_v3_0.z;
+    }
+
+    result.set(px, py, pz);
+
+    return false;
+}