@woosh/meep-engine 2.138.19 → 2.139.0

package/src/engine/physics/island/union_find.js

@@ -0,0 +1,76 @@
+/**
+ * Disjoint-set-union (union-find) primitives on a flat `Uint32Array` parent
+ * table. Stateless helpers — callers own the buffer.
+ *
+ * Design choices:
+ *  - **Path halving** rather than full path compression. Halving rewires
+ *    `parent[x]` to `parent[parent[x]]` as it walks, which is `O(α(n))`
+ *    amortised (same as full compression) but has a simpler control flow and
+ *    is deterministic regardless of call order. Full compression's iterative
+ *    second pass would observe a different mutation pattern depending on
+ *    which subtree was queried first — fine for correctness, awkward for
+ *    bit-exact same-runtime determinism.
+ *  - **Union by min-index** rather than by rank or size. The smaller index
+ *    always becomes the root. This makes the canonical root of a component
+ *    a deterministic function of the bodies in it (the smallest body index
+ *    of any member), which gives us a natural stable ordering when sorting
+ *    islands at the end. Slightly worse worst-case tree height than
+ *    union-by-rank but path halving keeps the amortised cost the same in
+ *    practice for the body counts we care about (≤ millions).
+ *
+ * Used by {@link IslandBuilder} to partition awake bodies + contact pairs
+ * into connected components (islands) so the solver can iterate each
+ * independently and so whole islands can sleep atomically.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Initialise `parent` so every node `i ∈ [0, n)` is its own root.
+ * @param {Uint32Array} parent
+ * @param {number} n
+ */
+export function uf_init(parent, n) {
+    for (let i = 0; i < n; i++) parent[i] = i;
+}
+
+/**
+ * Find the root of `x` with path halving. Mutates `parent` to compress the
+ * walked path by one level per hop.
+ * @param {Uint32Array} parent
+ * @param {number} x
+ * @returns {number} root index
+ */
+export function uf_find(parent, x) {
+    let p = parent[x];
+    while (p !== x) {
+        // Path-halve: point x at its grandparent.
+        const gp = parent[p];
+        parent[x] = gp;
+        x = gp;
+        p = parent[x];
+    }
+    return x;
+}
+
+/**
+ * Union the components containing `x` and `y`. The smaller-indexed root wins,
+ * keeping the canonical root deterministic regardless of call order.
+ * @param {Uint32Array} parent
+ * @param {number} x
+ * @param {number} y
+ * @returns {number} the root of the unified component
+ */
+export function uf_union(parent, x, y) {
+    const rx = uf_find(parent, x);
+    const ry = uf_find(parent, y);
+    if (rx === ry) return rx;
+    if (rx < ry) {
+        parent[ry] = rx;
+        return rx;
+    } else {
+        parent[rx] = ry;
+        return ry;
+    }
+}

package/src/engine/physics/narrowphase/PosedShape.d.ts

@@ -0,0 +1,59 @@
+/**
+ * AbstractShape3D adapter that re-frames a shape's `support` (and bounding box)
+ * into world space under a rigid pose (position + unit quaternion). The
+ * underlying shape itself is never copied or transformed — we rotate the GJK
+ * query direction into body space, ask the shape, then rotate the support
+ * point back to world.
+ *
+ * Existing TransformedShape3D solves a more general case (arbitrary matrix
+ * including scale) and crucially does *not* rotate the query direction into
+ * body space before calling support — that path is correct for unscaled
+ * identity rotations but wrong for rotated bodies, which is what narrowphase
+ * needs.
+ *
+ * Reusable: physics narrowphase keeps two long-lived instances and calls
+ * {@link setup} each pair. No per-pair allocation.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PosedShape extends AbstractShape3D {
+    /** @type {AbstractShape3D|null} */
+    shape: AbstractShape3D | null;
+    px: number;
+    py: number;
+    pz: number;
+    qx: number;
+    qy: number;
+    qz: number;
+    qw: number;
+    /**
+     * Bind a shape and a world pose. Subsequent calls to {@link support} and
+     * {@link compute_bounding_box} return results in world space.
+     *
+     * @param {AbstractShape3D} shape
+     * @param {Vector3|{x:number,y:number,z:number}} position
+     * @param {Quaternion|{x:number,y:number,z:number,w:number}} rotation
+     */
+    setup(shape: AbstractShape3D, position: Vector3 | {
+        x: number;
+        y: number;
+        z: number;
+    }, rotation: Quaternion | {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    }): void;
+    /**
+     * @param {number[]|Float32Array|Float64Array} result
+     * @param {number} result_offset
+     * @param {number} dx world-space query direction x (unit)
+     * @param {number} dy world-space query direction y
+     * @param {number} dz world-space query direction z
+     */
+    support(result: number[] | Float32Array | Float64Array, result_offset: number, dx: number, dy: number, dz: number): void;
+    compute_bounding_box(result: any): void;
+}
+import { AbstractShape3D } from "../../../core/geom/3d/shape/AbstractShape3D.js";
+//# sourceMappingURL=PosedShape.d.ts.map

package/src/engine/physics/narrowphase/PosedShape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PosedShape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/PosedShape.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAKQ,mCAAmC;IACnC,OADW,eAAe,GAAC,IAAI,CACd;IAEjB,WAAW;IAAE,WAAW;IAAE,WAAW;IACrC,WAAW;IAAE,WAAW;IAAE,WAAW;IAAE,WAAW;IAGtD;;;;;;;OAOG;IACH,aAJW,eAAe,YACf,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,YACpC,aAAW;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAM1D;IAED;;;;;;OAMG;IACH,gBANW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAyChB;IAED,wCASC;CACJ;gCA7G+B,gDAAgD"}

package/src/engine/physics/narrowphase/PosedShape.js

@@ -0,0 +1,110 @@
+import { AbstractShape3D } from "../../../core/geom/3d/shape/AbstractShape3D.js";
+import { aabb_transform_oriented } from "../broadphase/aabb_transform_oriented.js";
+
+const scratch_local = new Float64Array(3);
+const scratch_local_aabb = new Float64Array(6);
+
+/**
+ * AbstractShape3D adapter that re-frames a shape's `support` (and bounding box)
+ * into world space under a rigid pose (position + unit quaternion). The
+ * underlying shape itself is never copied or transformed — we rotate the GJK
+ * query direction into body space, ask the shape, then rotate the support
+ * point back to world.
+ *
+ * Existing TransformedShape3D solves a more general case (arbitrary matrix
+ * including scale) and crucially does *not* rotate the query direction into
+ * body space before calling support — that path is correct for unscaled
+ * identity rotations but wrong for rotated bodies, which is what narrowphase
+ * needs.
+ *
+ * Reusable: physics narrowphase keeps two long-lived instances and calls
+ * {@link setup} each pair. No per-pair allocation.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PosedShape extends AbstractShape3D {
+
+    constructor() {
+        super();
+
+        /** @type {AbstractShape3D|null} */
+        this.shape = null;
+
+        this.px = 0; this.py = 0; this.pz = 0;
+        this.qx = 0; this.qy = 0; this.qz = 0; this.qw = 1;
+    }
+
+    /**
+     * Bind a shape and a world pose. Subsequent calls to {@link support} and
+     * {@link compute_bounding_box} return results in world space.
+     *
+     * @param {AbstractShape3D} shape
+     * @param {Vector3|{x:number,y:number,z:number}} position
+     * @param {Quaternion|{x:number,y:number,z:number,w:number}} rotation
+     */
+    setup(shape, position, rotation) {
+        this.shape = shape;
+        this.px = position.x; this.py = position.y; this.pz = position.z;
+        this.qx = rotation.x; this.qy = rotation.y; this.qz = rotation.z; this.qw = rotation.w;
+    }
+
+    /**
+     * @param {number[]|Float32Array|Float64Array} result
+     * @param {number} result_offset
+     * @param {number} dx world-space query direction x (unit)
+     * @param {number} dy world-space query direction y
+     * @param {number} dz world-space query direction z
+     */
+    support(result, result_offset, dx, dy, dz) {
+        // Rotate world direction into body frame using the conjugate quaternion.
+        // Conjugate: (-qx, -qy, -qz, qw). v_local = q* · v_world · q
+        const qx = this.qx, qy = this.qy, qz = this.qz, qw = this.qw;
+
+        // Apply conjugate quaternion to dir: same formula as Vector3.applyQuaternion
+        // but with (qx,qy,qz) negated.
+        const cx = -qx, cy = -qy, cz = -qz;
+
+        // t = c · v
+        const tx = qw * dx + cy * dz - cz * dy;
+        const ty = qw * dy + cz * dx - cx * dz;
+        const tz = qw * dz + cx * dy - cy * dx;
+        const tw = -cx * dx - cy * dy - cz * dz;
+
+        // result_local = t · c^-1; conjugate of c is (-cx,-cy,-cz,qw) = (qx,qy,qz,qw) = original q
+        const ldx = tx * qw + tw * (-cx) + ty * (-cz) - tz * (-cy);
+        const ldy = ty * qw + tw * (-cy) + tz * (-cx) - tx * (-cz);
+        const ldz = tz * qw + tw * (-cz) + tx * (-cy) - ty * (-cx);
+
+        // Ask the local shape for its support point in body-local space.
+        this.shape.support(scratch_local, 0, ldx, ldy, ldz);
+
+        // Rotate result back to world frame using original quaternion.
+        const lsx = scratch_local[0], lsy = scratch_local[1], lsz = scratch_local[2];
+
+        // v_world = q · v_local · q*
+        const ix = qw * lsx + qy * lsz - qz * lsy;
+        const iy = qw * lsy + qz * lsx - qx * lsz;
+        const iz = qw * lsz + qx * lsy - qy * lsx;
+        const iw = -qx * lsx - qy * lsy - qz * lsz;
+
+        const wx = ix * qw + iw * (-qx) + iy * (-qz) - iz * (-qy);
+        const wy = iy * qw + iw * (-qy) + iz * (-qx) - ix * (-qz);
+        const wz = iz * qw + iw * (-qz) + ix * (-qy) - iy * (-qx);
+
+        result[result_offset] = wx + this.px;
+        result[result_offset + 1] = wy + this.py;
+        result[result_offset + 2] = wz + this.pz;
+    }
+
+    compute_bounding_box(result) {
+        this.shape.compute_bounding_box(scratch_local_aabb);
+        aabb_transform_oriented(
+            result, 0,
+            scratch_local_aabb[0], scratch_local_aabb[1], scratch_local_aabb[2],
+            scratch_local_aabb[3], scratch_local_aabb[4], scratch_local_aabb[5],
+            this.px, this.py, this.pz,
+            this.qx, this.qy, this.qz, this.qw
+        );
+    }
+}

package/src/engine/physics/narrowphase/box_box_manifold.d.ts

@@ -0,0 +1,32 @@
+/**
+ *
+ * @param {number[]|Float64Array} out length >= BOX_BOX_OUT_LENGTH
+ * @param {number} ax centre x of A
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} aqx A rotation quaternion x
+ * @param {number} aqy
+ * @param {number} aqz
+ * @param {number} aqw
+ * @param {number} ahx A half-extent x in body frame
+ * @param {number} ahy
+ * @param {number} ahz
+ * @param {number} bx centre x of B
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} bqx
+ * @param {number} bqy
+ * @param {number} bqz
+ * @param {number} bqw
+ * @param {number} bhx
+ * @param {number} bhy
+ * @param {number} bhz
+ * @returns {boolean} true if overlap
+ */
+export function box_box_manifold(out: number[] | Float64Array, ax: number, ay: number, az: number, aqx: number, aqy: number, aqz: number, aqw: number, ahx: number, ahy: number, ahz: number, bx: number, by: number, bz: number, bqx: number, bqy: number, bqz: number, bqw: number, bhx: number, bhy: number, bhz: number): boolean;
+/**
+ * Length of `out` required by {@link box_box_manifold}.
+ * @type {number}
+ */
+export const BOX_BOX_OUT_LENGTH: number;
+//# sourceMappingURL=box_box_manifold.d.ts.map

package/src/engine/physics/narrowphase/box_box_manifold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"box_box_manifold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/box_box_manifold.js"],"names":[],"mappings":"AAiIA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,sCAvBW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CAwUnB;AA1bD;;;GAGG;AACH,iCAFU,MAAM,CAEoD"}