@woosh/meep-engine 3.38.0 → 3.40.0

package/src/core/geom/3d/quaternion/quat3_shortest_arc.js

@@ -1,94 +1,155 @@
-/**
- * Shortest rotation taking one unit vector onto another: `out · a == b`.
- *
- * The construction is the standard half-way-vector one. `(a × b, 1 + a·b)` is
- * the quaternion of *twice* the required angle's axis-angle form before
- * normalisation; normalising halves it, and the result is the unique rotation
- * with no twist about `b` — which is what "shortest" means here and what makes
- * it the right primitive for orienting a bone from the direction it points in.
- *
- * **The antipodal case is real and has to be answered.** When `a` and `b` point
- * in opposite directions the cross product vanishes and `1 + a·b` is zero, so
- * the formula gives the zero quaternion — every axis perpendicular to `a` is an
- * equally valid 180° rotation and the expression cannot pick between them. This
- * picks one, by rotating about whichever coordinate axis `a` is least aligned
- * with. That is a discontinuity in `out` as `b` sweeps through `−a`, and it is
- * unavoidable: no continuous choice of axis exists on the whole sphere. It is
- * documented rather than hidden so a caller seeing a bone flip at exactly 180°
- * knows what it is looking at.
- *
- * Sign convention: `(x, y, z, w)` — `w` last, matching {@link Quaternion} and
- * the rest of the `core/geom/3d/quaternion/` family.
- *
- * **Precondition: `a` and `b` are unit length.** The half-way construction uses
- * `a·b` as a cosine and `|a × b|` as a sine; a non-unit input scales those two
- * differently and the normalisation cannot undo it, so the result is a rotation
- * of the wrong angle rather than a rotation of the wrong length.
- *
- * @param {number[]|Float32Array|Float64Array} out
- * @param {number} out_offset offset into `out`; receives 4 floats (x, y, z, w)
- * @param {number} ax unit vector, from
- * @param {number} ay
- * @param {number} az
- * @param {number} bx unit vector, to
- * @param {number} by
- * @param {number} bz
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export function quat3_shortest_arc(out, out_offset, ax, ay, az, bx, by, bz) {
-    const dot = ax * bx + ay * by + az * bz;
-
-    // The closed form survives far closer to opposition than it looks like it
-    // should. `w = 1 + a·b` shrinks as `δ` while `|a × b|` shrinks only as
-    // `√(2δ)`, so after normalisation `w` reads `cos(θ/2) = √(δ/2)` and stays
-    // accurate until `δ` itself stops resolving — which is at the `Float64`
-    // spacing near −1, around 2e-16. The threshold sits two orders above that,
-    // where the two vectors are 1.4e-7 radians apart and the arbitrary
-    // perpendicular chosen below is wrong by that much and no more.
-    //
-    // An earlier draft put it at 1e-6 in the *dot product*, which is 1.4e-3
-    // radians of angle — a tenth of a degree of silent error, and a spec here
-    // caught it.
-    if (dot < -1 + 1e-14) {
-        // The axis least aligned with `a` gives the cross product below the
-        // most magnitude to work with, which is the whole of the choice.
-        const abs_x = ax < 0 ? -ax : ax;
-        const abs_y = ay < 0 ? -ay : ay;
-        const abs_z = az < 0 ? -az : az;
-
-        let px, py, pz;
-
-        if (abs_x <= abs_y && abs_x <= abs_z) {
-            px = 0; py = -az; pz = ay;
-        } else if (abs_y <= abs_z) {
-            px = az; py = 0; pz = -ax;
-        } else {
-            px = -ay; py = ax; pz = 0;
-        }
-
-        const length = Math.sqrt(px * px + py * py + pz * pz);
-
-        // A 180° rotation is `(axis, 0)`.
-        out[out_offset] = px / length;
-        out[out_offset + 1] = py / length;
-        out[out_offset + 2] = pz / length;
-        out[out_offset + 3] = 0;
-
-        return;
-    }
-
-    const cx = ay * bz - az * by;
-    const cy = az * bx - ax * bz;
-    const cz = ax * by - ay * bx;
-
-    const w = 1 + dot;
-
-    const inverse = 1 / Math.sqrt(cx * cx + cy * cy + cz * cz + w * w);
-
-    out[out_offset] = cx * inverse;
-    out[out_offset + 1] = cy * inverse;
-    out[out_offset + 2] = cz * inverse;
-    out[out_offset + 3] = w * inverse;
-}
+/**
+ * Shortest rotation taking one unit vector onto another: `out · a == b`.
+ *
+ * The construction is the standard half-way-vector one. `(a × b, 1 + a·b)` is
+ * the quaternion of *twice* the required angle's axis-angle form before
+ * normalisation; normalising halves it, and the result is the unique rotation
+ * with no twist about `b` — which is what "shortest" means here and what makes
+ * it the right primitive for orienting a bone from the direction it points in.
+ *
+ * **The antipodal case is real and has to be answered.** When `a` and `b` point
+ * in opposite directions the cross product vanishes and `1 + a·b` is zero, so
+ * the formula gives the zero quaternion — every axis perpendicular to `a` is an
+ * equally valid 180° rotation and the expression cannot pick between them. This
+ * picks one, by rotating about whichever coordinate axis `a` is least aligned
+ * with. That is a discontinuity in `out` as `b` sweeps through `−a`, and it is
+ * unavoidable: no continuous choice of axis exists on the whole sphere. It is
+ * documented rather than hidden so a caller seeing a bone flip at exactly 180°
+ * knows what it is looking at.
+ *
+ * Sign convention: `(x, y, z, w)` — `w` last, matching {@link Quaternion} and
+ * the rest of the `core/geom/3d/quaternion/` family.
+ *
+ * **Precondition: `a` and `b` are unit length.** The half-way construction uses
+ * `a·b` as a cosine and `|a × b|` as a sine; a non-unit input scales those two
+ * differently and the normalisation cannot undo it, so the result is a rotation
+ * of the wrong angle rather than a rotation of the wrong length.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset offset into `out`; receives 4 floats (x, y, z, w)
+ * @param {number} ax unit vector, from
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx unit vector, to
+ * @param {number} by
+ * @param {number} bz
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quat3_shortest_arc(out, out_offset, ax, ay, az, bx, by, bz) {
+    const dot = ax * bx + ay * by + az * bz;
+
+    // The closed form survives far closer to opposition than it looks like it
+    // should. `w = 1 + a·b` shrinks as `δ` while `|a × b|` shrinks only as
+    // `√(2δ)`, so after normalisation `w` reads `cos(θ/2) = √(δ/2)` and stays
+    // accurate until `δ` itself stops resolving — which is at the `Float64`
+    // spacing near −1, around 2e-16. The threshold sits two orders above that,
+    // where the two vectors are 1.4e-7 radians apart and the arbitrary
+    // perpendicular chosen below is wrong by that much and no more.
+    //
+    // An earlier draft put it at 1e-6 in the *dot product*, which is 1.4e-3
+    // radians of angle — a tenth of a degree of silent error, and a spec here
+    // caught it.
+    if (dot < -1 + 1e-14) {
+        // The axis least aligned with `a` gives the cross product below the
+        // most magnitude to work with, which is the whole of the choice.
+        const abs_x = ax < 0 ? -ax : ax;
+        const abs_y = ay < 0 ? -ay : ay;
+        const abs_z = az < 0 ? -az : az;
+
+        let px, py, pz;
+
+        if (abs_x <= abs_y && abs_x <= abs_z) {
+            px = 0; py = -az; pz = ay;
+        } else if (abs_y <= abs_z) {
+            px = az; py = 0; pz = -ax;
+        } else {
+            px = -ay; py = ax; pz = 0;
+        }
+
+        const length = Math.sqrt(px * px + py * py + pz * pz);
+
+        // A 180° rotation is `(axis, 0)`.
+        out[out_offset] = px / length;
+        out[out_offset + 1] = py / length;
+        out[out_offset + 2] = pz / length;
+        out[out_offset + 3] = 0;
+
+        return;
+    }
+
+    const cx = ay * bz - az * by;
+    const cy = az * bx - ax * bz;
+    const cz = ax * by - ay * bx;
+
+    const w = 1 + dot;
+
+    const inverse = 1 / Math.sqrt(cx * cx + cy * cy + cz * cz + w * w);
+
+    out[out_offset] = cx * inverse;
+    out[out_offset + 1] = cy * inverse;
+    out[out_offset + 2] = cz * inverse;
+    out[out_offset + 3] = w * inverse;
+}
+
+/**
+ * {@link quat3_shortest_arc} with both vectors read from arrays. For a caller whose inlining budget
+ * is spent, or code V8 has not optimised yet: there a call to the scalar form is a real call, and a
+ * real call boxes each of its six numbers into a new heap object. The arithmetic is the scalar
+ * form's, written out again rather than called, for the same reason; the two must stay operation for
+ * operation the same.
+ *
+ * Both vectors are read before the first write, so `out` may overlap either.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset offset into `out`; receives 4 floats (x, y, z, w)
+ * @param {number[]|Float32Array|Float64Array} a unit vector `[x, y, z]`, from
+ * @param {number} a_offset
+ * @param {number[]|Float32Array|Float64Array} b unit vector `[x, y, z]`, to
+ * @param {number} b_offset
+ */
+export function quat3_shortest_arc_array(out, out_offset, a, a_offset, b, b_offset) {
+    const ax = a[a_offset], ay = a[a_offset + 1], az = a[a_offset + 2];
+    const bx = b[b_offset], by = b[b_offset + 1], bz = b[b_offset + 2];
+
+    const dot = ax * bx + ay * by + az * bz;
+
+    if (dot < -1 + 1e-14) {
+        const abs_x = ax < 0 ? -ax : ax;
+        const abs_y = ay < 0 ? -ay : ay;
+        const abs_z = az < 0 ? -az : az;
+
+        let px, py, pz;
+
+        if (abs_x <= abs_y && abs_x <= abs_z) {
+            px = 0; py = -az; pz = ay;
+        } else if (abs_y <= abs_z) {
+            px = az; py = 0; pz = -ax;
+        } else {
+            px = -ay; py = ax; pz = 0;
+        }
+
+        const length = Math.sqrt(px * px + py * py + pz * pz);
+
+        out[out_offset] = px / length;
+        out[out_offset + 1] = py / length;
+        out[out_offset + 2] = pz / length;
+        out[out_offset + 3] = 0;
+
+        return;
+    }
+
+    const cx = ay * bz - az * by;
+    const cy = az * bx - ax * bz;
+    const cz = ax * by - ay * bx;
+
+    const w = 1 + dot;
+
+    const inverse = 1 / Math.sqrt(cx * cx + cy * cy + cz * cz + w * w);
+
+    out[out_offset] = cx * inverse;
+    out[out_offset + 1] = cy * inverse;
+    out[out_offset + 2] = cz * inverse;
+    out[out_offset + 3] = w * inverse;
+}

package/src/core/geom/3d/quaternion/quat3_to_matrix3.d.ts

@@ -51,4 +51,16 @@
  * @param {number} qw unit quaternion w (last)
  */
 export function quat3_to_matrix3(out: number[] | Float32Array | Float64Array, out_offset: number, qx: number, qy: number, qz: number, qw: number): void;
+/**
+ * {@link quat3_to_matrix3} with the quaternion read from an array. For a caller whose inlining budget
+ * is spent: there a call to the scalar form is a real call, and a real call boxes each of its four
+ * numbers into a new heap object. The arithmetic is the scalar form's, written out again rather than
+ * called, for the same reason; the two must stay operation for operation the same.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset
+ * @param {number[]|Float32Array|Float64Array} q unit quaternion `[x, y, z, w]`
+ * @param {number} q_offset
+ */
+export function quat3_to_matrix3_array(out: number[] | Float32Array | Float64Array, out_offset: number, q: number[] | Float32Array | Float64Array, q_offset: number): void;
 //# sourceMappingURL=quat3_to_matrix3.d.ts.map

package/src/core/geom/3d/quaternion/quat3_to_matrix3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"quat3_to_matrix3.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/quat3_to_matrix3.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,sCAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAkBhB"}
+{"version":3,"file":"quat3_to_matrix3.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/quat3_to_matrix3.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,sCAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAkBhB;AAED;;;;;;;;;;GAUG;AACH,4CALW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,KACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,YAClC,MAAM,QAoBhB"}

package/src/core/geom/3d/quaternion/quat3_to_matrix3.js

@@ -67,3 +67,34 @@ export function quat3_to_matrix3(out, out_offset, qx, qy, qz, qw) {
     out[out_offset + 7] = 2 * (yz - wx);
     out[out_offset + 8] = 1 - 2 * (xx + yy);
 }
+
+/**
+ * {@link quat3_to_matrix3} with the quaternion read from an array. For a caller whose inlining budget
+ * is spent: there a call to the scalar form is a real call, and a real call boxes each of its four
+ * numbers into a new heap object. The arithmetic is the scalar form's, written out again rather than
+ * called, for the same reason; the two must stay operation for operation the same.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset
+ * @param {number[]|Float32Array|Float64Array} q unit quaternion `[x, y, z, w]`
+ * @param {number} q_offset
+ */
+export function quat3_to_matrix3_array(out, out_offset, q, q_offset) {
+    const qx = q[q_offset], qy = q[q_offset + 1], qz = q[q_offset + 2], qw = q[q_offset + 3];
+
+    const xx = qx * qx, yy = qy * qy, zz = qz * qz;
+    const xy = qx * qy, xz = qx * qz, yz = qy * qz;
+    const wx = qw * qx, wy = qw * qy, wz = qw * qz;
+
+    out[out_offset]     = 1 - 2 * (yy + zz);
+    out[out_offset + 1] = 2 * (xy + wz);
+    out[out_offset + 2] = 2 * (xz - wy);
+
+    out[out_offset + 3] = 2 * (xy - wz);
+    out[out_offset + 4] = 1 - 2 * (xx + zz);
+    out[out_offset + 5] = 2 * (yz + wx);
+
+    out[out_offset + 6] = 2 * (xz + wy);
+    out[out_offset + 7] = 2 * (yz - wx);
+    out[out_offset + 8] = 1 - 2 * (xx + yy);
+}

package/src/core/geom/3d/shape/AbstractShape3D.d.ts

@@ -58,16 +58,30 @@ export class AbstractShape3D {
      */
     compute_bounding_box(result: number[] | ArrayLike<number> | Float32Array | Float64Array): void;
     /**
-     * Support function, given a direction vector, return point on the shape that's furthest in that direction
-     * Assumes direction is a unit vector
+     * Support function: writes into `result[result_offset .. +2]` the point of the shape furthest along the
+     * direction held in `direction[direction_offset .. +2]`, in the shape's own frame.
+     *
+     * The contract, which every implementation and every caller keeps:
+     *  - The direction is unit length. It is not normalised here.
+     *  - It travels in an array, never as three numbers. Support is called through sites V8 sees many
+     *    shapes at (GJK, MPR, the wrappers below) and so never inlines, and each double handed across
+     *    such a call is boxed into a fresh heap number. There is no scalar form and no overload.
+     *  - An implementation reads all three components before it writes anything, `result` included, and
+     *    before it calls any other support. So `direction` may be the same memory as `result`, and a
+     *    wrapper that turns the direction ({@link PosedShape3D}, {@link TransformedShape3D}) writes the
+     *    turned one into its own module scratch and passes that down, even when what it wraps is another
+     *    wrapper of its class.
+     *  - That nesting is the one way a call can change `direction` under its caller: the inner wrapper
+     *    reuses the scratch it was handed once it has read it. A caller that asks several shapes along
+     *    one direction ({@link UnionShape3D}) keeps it in locals and writes it out afresh before each.
+     *
      * @param {number[]|Float32Array|Float64Array} result
      * @param {number} result_offset
-     * @param {number} direction_x
-     * @param {number} direction_y
-     * @param {number} direction_z
+     * @param {number[]|Float32Array|Float64Array} direction unit direction, at `direction_offset`
+     * @param {number} direction_offset
      * @returns {void}
      */
-    support(result: number[] | Float32Array | Float64Array, result_offset: number, direction_x: number, direction_y: number, direction_z: number): void;
+    support(result: number[] | Float32Array | Float64Array, result_offset: number, direction: number[] | Float32Array | Float64Array, direction_offset: number): void;
     /**
      * Ray ↔ shape intersection in the shape's LOCAL frame (the shape sits at the origin in its canonical
      * pose). On a hit, writes the surface point and unit surface normal into `hit` as

package/src/core/geom/3d/shape/AbstractShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/AbstractShape3D.js"],"names":[],"mappings":"AAaA;IACI;;;;OAIG;IACH,gCAHW,MAAM,EAAE,GACN,MAAM,CAIlB;IAED;;;;;OAKG;IACH,0CAJW,MAAM,EAAE,SACR,MAAM,EAAE,GACN,MAAM,CAIlB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,EAAE,aACR,MAAM,EAAE,GACN,IAAI,CAIhB;IAED;;;;;;;;;;;;;;;OAeG;IACH,sCALW,MAAM,EAAE,iBACR,MAAM,qBAEJ,IAAI,CA6BhB;IAED;;;;OAIG;IACH,sBAHW,MAAM,EAAE,GACN,OAAO,CAInB;IAED;;;OAGG;IACH,qBAEC;IAED;;OAEG;IACH,2BAEC;IAED;;;;OAIG;IACH,6BAHW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,YAAY,GAAC,YAAY,GAClD,IAAI,CAIhB;IAED;;;;;;;;;OASG;IACH,gBAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,GACJ,IAAI,CAIhB;IAED;;;;;;;;;;;OAWG;IACH,aAJW,YAAY,GAAC,MAAM,EAAE,OACrB,IAAI,GACF,OAAO,CAInB;IAED;;;;;;;;;;;OAWG;IACH,cAHW,eAAe,GACb,OAAO,CAInB;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAGL;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,oBAFU,OAAO,CAEkB;CAvBlC;mBA7KY,OAAO,gBAAgB,EAAE,IAAI"}
+{"version":3,"file":"AbstractShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/AbstractShape3D.js"],"names":[],"mappings":"AAaA;IACI;;;;OAIG;IACH,gCAHW,MAAM,EAAE,GACN,MAAM,CAIlB;IAED;;;;;OAKG;IACH,0CAJW,MAAM,EAAE,SACR,MAAM,EAAE,GACN,MAAM,CAIlB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,EAAE,aACR,MAAM,EAAE,GACN,IAAI,CAIhB;IAED;;;;;;;;;;;;;;;OAeG;IACH,sCALW,MAAM,EAAE,iBACR,MAAM,qBAEJ,IAAI,CA6BhB;IAED;;;;OAIG;IACH,sBAHW,MAAM,EAAE,GACN,OAAO,CAInB;IAED;;;OAGG;IACH,qBAEC;IAED;;OAEG;IACH,2BAEC;IAED;;;;OAIG;IACH,6BAHW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,YAAY,GAAC,YAAY,GAClD,IAAI,CAIhB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,gBANW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,aACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,oBAClC,MAAM,GACJ,IAAI,CAIhB;IAED;;;;;;;;;;;OAWG;IACH,aAJW,YAAY,GAAC,MAAM,EAAE,OACrB,IAAI,GACF,OAAO,CAInB;IAED;;;;;;;;;;;OAWG;IACH,cAHW,eAAe,GACb,OAAO,CAInB;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAGL;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,oBAFU,OAAO,CAEkB;CAvBlC;mBA3LY,OAAO,gBAAgB,EAAE,IAAI"}

package/src/core/geom/3d/shape/AbstractShape3D.js

@@ -120,16 +120,30 @@ export class AbstractShape3D {
     }
 
     /**
-     * Support function, given a direction vector, return point on the shape that's furthest in that direction
-     * Assumes direction is a unit vector
+     * Support function: writes into `result[result_offset .. +2]` the point of the shape furthest along the
+     * direction held in `direction[direction_offset .. +2]`, in the shape's own frame.
+     *
+     * The contract, which every implementation and every caller keeps:
+     *  - The direction is unit length. It is not normalised here.
+     *  - It travels in an array, never as three numbers. Support is called through sites V8 sees many
+     *    shapes at (GJK, MPR, the wrappers below) and so never inlines, and each double handed across
+     *    such a call is boxed into a fresh heap number. There is no scalar form and no overload.
+     *  - An implementation reads all three components before it writes anything, `result` included, and
+     *    before it calls any other support. So `direction` may be the same memory as `result`, and a
+     *    wrapper that turns the direction ({@link PosedShape3D}, {@link TransformedShape3D}) writes the
+     *    turned one into its own module scratch and passes that down, even when what it wraps is another
+     *    wrapper of its class.
+     *  - That nesting is the one way a call can change `direction` under its caller: the inner wrapper
+     *    reuses the scratch it was handed once it has read it. A caller that asks several shapes along
+     *    one direction ({@link UnionShape3D}) keeps it in locals and writes it out afresh before each.
+     *
      * @param {number[]|Float32Array|Float64Array} result
      * @param {number} result_offset
-     * @param {number} direction_x
-     * @param {number} direction_y
-     * @param {number} direction_z
+     * @param {number[]|Float32Array|Float64Array} direction unit direction, at `direction_offset`
+     * @param {number} direction_offset
      * @returns {void}
      */
-    support(result, result_offset, direction_x, direction_y, direction_z) {
+    support(result, result_offset, direction, direction_offset) {
         throw new Error("Not Implemented");
     }
 

package/src/core/geom/3d/shape/BoxShape3D.d.ts

@@ -37,7 +37,7 @@ export class BoxShape3D extends AbstractShape3D {
     readonly half_extents: Vector3;
     compute_bounding_box(result: any): void;
     nearest_point_on_surface(result: any, reference: any): void;
-    support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    support(result: any, result_offset: any, direction: any, direction_offset: any): void;
     raycast(hit: any, ray: any): boolean;
     signed_distance_gradient_at_point(result: any, point: any): number;
     signed_distance_at_point(point: any): number;

package/src/core/geom/3d/shape/BoxShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BoxShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/BoxShape3D.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;GAYG;AACH;IAQI;;;;;;OAMG;IACH,gBALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,UAAU,CAMtB;IAED;;;;;;;OAOG;IACH,wBALW,MAAM,UACN,MAAM,SACN,MAAM,GACJ,UAAU,CAItB;IA9BD;;;;OAIG;IACH,uBAFU,OAAO,CAEyB;IAqC1C,wCAIC;IAED,4DAQC;IAED,qGAKC;IAED,qCAaC;IAED,mEAIC;IAED,6CAIC;IAED,oCAQC;IAED,kFAOC;IAED;;;OAGG;IACH,cAHW,UAAU,GACR,OAAO,CAInB;IAWL;;;;;;OAMG;IACH,uBAFU,OAAO,CAEgB;CAThC;gCA/I+B,sBAAsB;oBANlC,kBAAkB"}
+{"version":3,"file":"BoxShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/BoxShape3D.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;GAYG;AACH;IAQI;;;;;;OAMG;IACH,gBALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,UAAU,CAMtB;IAED;;;;;;;OAOG;IACH,wBALW,MAAM,UACN,MAAM,SACN,MAAM,GACJ,UAAU,CAItB;IA9BD;;;;OAIG;IACH,uBAFU,OAAO,CAEyB;IAqC1C,wCAIC;IAED,4DAQC;IAED,sFASC;IAED,qCAaC;IAED,mEAIC;IAED,6CAIC;IAED,oCAQC;IAED,kFAOC;IAED;;;OAGG;IACH,cAHW,UAAU,GACR,OAAO,CAInB;IAWL;;;;;;OAMG;IACH,uBAFU,OAAO,CAEgB;CAThC;gCAnJ+B,sBAAsB;oBANlC,kBAAkB"}

package/src/core/geom/3d/shape/BoxShape3D.js

@@ -80,7 +80,11 @@ export class BoxShape3D extends AbstractShape3D {
         );
     }
 
-    support(result, result_offset, direction_x, direction_y, direction_z) {
+    support(result, result_offset, direction, direction_offset) {
+        const direction_x = direction[direction_offset];
+        const direction_y = direction[direction_offset + 1];
+        const direction_z = direction[direction_offset + 2];
+
         const h = this.half_extents;
         result[result_offset]     = sign_not_zero(direction_x) * h.x;
         result[result_offset + 1] = sign_not_zero(direction_y) * h.y;

package/src/core/geom/3d/shape/CapsuleShape3D.d.ts

@@ -26,7 +26,7 @@ export class CapsuleShape3D extends AbstractShape3D {
     signed_distance_gradient_at_point(result: any, point: any): number;
     contains_point(point: any): boolean;
     nearest_point_on_surface(result: any, reference: any): void;
-    support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    support(result: any, result_offset: any, direction: any, direction_offset: any): void;
     sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
     /**
      * @param {CapsuleShape3D} other

package/src/core/geom/3d/shape/CapsuleShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CapsuleShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/CapsuleShape3D.js"],"names":[],"mappings":"AAcA;;;;GAIG;AACH;IAaI;;;;OAIG;IACH,oBAJW,MAAM,UACN,MAAM,GACJ,cAAc,CAa1B;IA5BD;;;OAGG;IACH,QAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,QAFU,MAAM,CAEL;IAoCX,wCAUC;IAED,qCAgBC;IAED,6CAEC;IAED,mEAEC;IAED,oCAcC;IAED,4DA+BC;IAED,qGAUC;IAED,kFA+BC;IAED;;;OAGG;IACH,cAHW,cAAc,GACZ,OAAO,CAMnB;IAUL;;;;;;;;;OASG;IACH,2BAFU,OAAO,CAEwB;CAZxC;gCA7M+B,sBAAsB"}
+{"version":3,"file":"CapsuleShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/CapsuleShape3D.js"],"names":[],"mappings":"AAcA;;;;GAIG;AACH;IAaI;;;;OAIG;IACH,oBAJW,MAAM,UACN,MAAM,GACJ,cAAc,CAa1B;IA5BD;;;OAGG;IACH,QAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,QAFU,MAAM,CAEL;IAoCX,wCAUC;IAED,qCAgBC;IAED,6CAEC;IAED,mEAEC;IAED,oCAcC;IAED,4DA+BC;IAED,sFAcC;IAED,kFA+BC;IAED;;;OAGG;IACH,cAHW,cAAc,GACZ,OAAO,CAMnB;IAUL;;;;;;;;;OASG;IACH,2BAFU,OAAO,CAEwB;CAZxC;gCAjN+B,sBAAsB"}

package/src/core/geom/3d/shape/CapsuleShape3D.js

@@ -151,7 +151,11 @@ export class CapsuleShape3D extends AbstractShape3D {
         result[2] = dz * scale;
     }
 
-    support(result, result_offset, direction_x, direction_y, direction_z) {
+    support(result, result_offset, direction, direction_offset) {
+        const direction_x = direction[direction_offset];
+        const direction_y = direction[direction_offset + 1];
+        const direction_z = direction[direction_offset + 2];
+
         const half_h = this.height / 2;
         const r = this.radius;
 

package/src/core/geom/3d/shape/ConvexHullShape3D.d.ts

@@ -1,20 +1,24 @@
 /**
  * Convex polyhedron collider.
  *
- * Holds a convex triangle surface (`vertices` + outward-CCW `indices`) and the
- * derived face half-spaces. Because it is convex (`is_convex === true`, the
- * default), it routes straight through the narrowphase's GJK + EPA path via
- * {@link support} — no tetrahedralisation, no per-triangle decomposition, no
- * BVH. This is the right shape for authored convex geometry (props, crates,
- * gems, low-poly rocks, an icosphere) and is far cheaper to construct than
- * {@link MeshShape3D}, which tetrahedralises its interior.
+ * Holds a convex triangle surface (`vertices` + outward-CCW `indices`) and what
+ * is derived from it: the per-triangle half-spaces, and the polygon faces (one
+ * per flat side) with their planes. Because it is convex (`is_convex === true`,
+ * the default), the narrowphase collides it through {@link support} (GJK + EPA)
+ * and its polygon faces (face clipping) — no tetrahedralisation, no per-triangle
+ * decomposition, no BVH. This is the right shape for authored convex geometry
+ * (props, crates, gems, low-poly rocks, an icosphere) and is far cheaper to
+ * construct than {@link MeshShape3D}, which tetrahedralises its interior.
  *
  * Contract:
  *   - `support` is exact for any convex point set (deepest vertex along the
  *     direction) — the precondition GJK relies on.
  *   - `contains_point` is the convex half-space test (behind every face plane).
  *   - `signed_distance` / `nearest_point_on_surface` scan the surface triangles
- *     (O(F)); these are query-path helpers, not on the collision hot path.
+ *     (O(F)). `nearest_point_on_surface` is on the collision path: the
+ *     hull/sphere contact calls it for a sphere outside the hull whose centre
+ *     is not over the face it is furthest in front of (near an edge or a
+ *     corner), so such a pair costs O(F) triangle tests.
  *
  * The input is assumed convex with outward-facing CCW winding — build it via
  * {@link ConvexHullShape3D.from}. A genuine non-convex mesh belongs in
@@ -49,13 +53,23 @@ export class ConvexHullShape3D extends AbstractShape3D {
     /**
      * Polygon-face representation for the contact clipper (CSR): face `f`'s
      * vertex loop is `face_loops[face_offsets[f] .. face_offsets[f+1]]`,
-     * ordered CCW (outward). Currently one triangle per face; a coplanar-merge
-     * pass will collapse coplanar triangles into larger polygon faces.
+     * ordered CCW (outward), indexing {@link vertices}. Derived in
+     * {@link recompute}: each side of the hull is ONE convex polygon however
+     * many coplanar triangles {@link indices} spends on it (a box has six
+     * quads), so a face-on-face contact clips to the whole patch.
      * @type {Uint32Array}
      */
     face_offsets: Uint32Array;
     /** @type {Uint32Array} */
     face_loops: Uint32Array;
+    /**
+     * The plane of each polygon face of {@link face_loops}, four doubles per face `(nx, ny, nz, d)`
+     * with unit outward normal and `d = n · v`; all zero for a face with no area. Derived in
+     * {@link recompute}, alongside the loops, so contact code that looks for the face facing a
+     * direction reads one plane per side rather than re-deriving each loop's normal per query.
+     * @type {Float64Array}
+     */
+    face_loop_planes: Float64Array;
     /**
      * Face half-spaces, four doubles per face `(nx, ny, nz, d)` with unit
      * outward normal and `d = n · v` — point is inside iff `n · p − d ≤ 0`
@@ -82,7 +96,7 @@ export class ConvexHullShape3D extends AbstractShape3D {
      * vertex counts of authored hulls; a hill-climb over vertex adjacency is
      * the acceleration for very large hulls.
      */
-    support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    support(result: any, result_offset: any, direction: any, direction_offset: any): void;
     /**
      * The hull's face half-spaces, four doubles per face `(nx, ny, nz, d)` with unit OUTWARD normal —
      * the derived form of `vertices` / `indices` that every half-space query reads. Exposed because a

package/src/core/geom/3d/shape/ConvexHullShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConvexHullShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/ConvexHullShape3D.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA8CI;;;;;;;OAOG;IACH,sBAJW,YAAY,WACZ,WAAW,GACT,iBAAiB,CAQ7B;IA1DD;;;;OAIG;IACH,UAFU,YAAY,CAES;IAE/B;;;;OAIG;IACH,SAFU,WAAW,CAEQ;IAE7B;;;;;;OAMG;IACH,cAFU,WAAW,CAEa;IAElC,0BAA0B;IAC1B,YADW,WAAW,CACU;IAEhC;;;;;;OAMG;IACH,iBAA+B;IAE/B,oCAAoC;IACpC,eAA6B;IAE7B,8BAA8B;IAC9B,iBAAa;IAEb,8BAA8B;IAC9B,uBAAmB;IAkBnB;;;OAGG;IACH,kBAkFC;IAUD,wCAQC;IAED;;;;;OAKG;IACH,qGAwCC;IAED;;;;;;;OAOG;IACH,gCAEC;IAED;;;OAGG;IACH,+BAEC;IAED,qCAkBC;IAED;;;OAGG;IACH,oCAgBC;IAED;;;OAGG;IACH,6CAiBC;IAED,mEAEC;IAED,4DAwBC;IAGD;;;OAGG;IACH,cAHW,iBAAiB,GACf,OAAO,CAanB;IAcL;;;;OAIG;IACH,8BAFU,OAAO,CAE8B;CAP9C;gCApY+B,sBAAsB"}
+{"version":3,"file":"ConvexHullShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/ConvexHullShape3D.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAyDI;;;;;;;OAOG;IACH,sBAJW,YAAY,WACZ,WAAW,GACT,iBAAiB,CAQ7B;IArED;;;;OAIG;IACH,UAFU,YAAY,CAES;IAE/B;;;;OAIG;IACH,SAFU,WAAW,CAEQ;IAE7B;;;;;;;;OAQG;IACH,cAFU,WAAW,CAEa;IAElC,0BAA0B;IAC1B,YADW,WAAW,CACU;IAEhC;;;;;;OAMG;IACH,kBAFU,YAAY,CAEiB;IAEvC;;;;;;OAMG;IACH,iBAA+B;IAE/B,oCAAoC;IACpC,eAA6B;IAE7B,8BAA8B;IAC9B,iBAAa;IAEb,8BAA8B;IAC9B,uBAAmB;IAkBnB;;;OAGG;IACH,kBA8EC;IAUD,wCAQC;IAED;;;;;OAKG;IACH,sFAsCC;IAED;;;;;;;OAOG;IACH,gCAEC;IAED;;;OAGG;IACH,+BAEC;IAED,qCAkBC;IAED;;;OAGG;IACH,oCAgBC;IAED;;;OAGG;IACH,6CAiBC;IAED,mEAEC;IAED,4DAwBC;IAGD;;;OAGG;IACH,cAHW,iBAAiB,GACf,OAAO,CAanB;IAcL;;;;OAIG;IACH,8BAFU,OAAO,CAE8B;CAP9C;gCA7Y+B,sBAAsB"}