@woosh/meep-engine 2.138.20 → 2.140.0

package/src/core/geom/3d/aabb/aabb3_transform_oriented.js

@@ -0,0 +1,93 @@
+/**
+ * Compute the world-space axis-aligned bounding box of a local AABB after a
+ * rigid transform (position + orientation).
+ *
+ * Math: an AABB transformed by a rotation `R` is bounded by another AABB whose
+ * centre is `R · c_local + t` and whose half-extent along each world axis `i`
+ * is `Σ_j |R_ij| · half_extent_local_j`. The element-wise-abs trick avoids
+ * rotating all 8 corners and projecting.
+ *
+ * Output layout matches existing AABB conventions: `[x0, y0, z0, x1, y1, z1]`
+ * with `(x0,y0,z0)` as the min corner.
+ *
+ * @param {number[]|Float32Array|Float64Array} result
+ * @param {number} result_offset
+ * @param {number} lx0 local min x
+ * @param {number} ly0 local min y
+ * @param {number} lz0 local min z
+ * @param {number} lx1 local max x
+ * @param {number} ly1 local max y
+ * @param {number} lz1 local max z
+ * @param {number} px  translation x
+ * @param {number} py  translation y
+ * @param {number} pz  translation z
+ * @param {number} qx  quaternion x (unit)
+ * @param {number} qy  quaternion y
+ * @param {number} qz  quaternion z
+ * @param {number} qw  quaternion w
+ */
+export function aabb3_transform_oriented(
+    result, result_offset,
+    lx0, ly0, lz0, lx1, ly1, lz1,
+    px, py, pz,
+    qx, qy, qz, qw
+) {
+    // local centre and half-extent
+    const cx = (lx0 + lx1) * 0.5;
+    const cy = (ly0 + ly1) * 0.5;
+    const cz = (lz0 + lz1) * 0.5;
+
+    const ex = (lx1 - lx0) * 0.5;
+    const ey = (ly1 - ly0) * 0.5;
+    const ez = (lz1 - lz0) * 0.5;
+
+    // Rotation matrix from unit quaternion.
+    const xx = qx * qx;
+    const yy = qy * qy;
+    const zz = qz * qz;
+    const xy = qx * qy;
+    const xz = qx * qz;
+    const yz = qy * qz;
+    const wx = qw * qx;
+    const wy = qw * qy;
+    const wz = qw * qz;
+
+    const r00 = 1 - 2 * (yy + zz);
+    const r01 = 2 * (xy - wz);
+    const r02 = 2 * (xz + wy);
+
+    const r10 = 2 * (xy + wz);
+    const r11 = 1 - 2 * (xx + zz);
+    const r12 = 2 * (yz - wx);
+
+    const r20 = 2 * (xz - wy);
+    const r21 = 2 * (yz + wx);
+    const r22 = 1 - 2 * (xx + yy);
+
+    // World centre = R · c + t
+    const wcx = r00 * cx + r01 * cy + r02 * cz + px;
+    const wcy = r10 * cx + r11 * cy + r12 * cz + py;
+    const wcz = r20 * cx + r21 * cy + r22 * cz + pz;
+
+    // World half-extent = |R| · e
+    const ar00 = r00 < 0 ? -r00 : r00;
+    const ar01 = r01 < 0 ? -r01 : r01;
+    const ar02 = r02 < 0 ? -r02 : r02;
+    const ar10 = r10 < 0 ? -r10 : r10;
+    const ar11 = r11 < 0 ? -r11 : r11;
+    const ar12 = r12 < 0 ? -r12 : r12;
+    const ar20 = r20 < 0 ? -r20 : r20;
+    const ar21 = r21 < 0 ? -r21 : r21;
+    const ar22 = r22 < 0 ? -r22 : r22;
+
+    const wex = ar00 * ex + ar01 * ey + ar02 * ez;
+    const wey = ar10 * ex + ar11 * ey + ar12 * ez;
+    const wez = ar20 * ex + ar21 * ey + ar22 * ez;
+
+    result[result_offset] = wcx - wex;
+    result[result_offset + 1] = wcy - wey;
+    result[result_offset + 2] = wcz - wez;
+    result[result_offset + 3] = wcx + wex;
+    result[result_offset + 4] = wcy + wey;
+    result[result_offset + 5] = wcz + wez;
+}

package/src/core/geom/3d/line/line3_closest_points_segment_segment.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Closest-point pair on two 3D line segments. Writes parameters `s` and `t`
+ * (each in `[0, 1]`) into `out[0]` and `out[1]` such that:
+ *
+ *     closest_point_on_S1 = P1 + s * (Q1 - P1)
+ *     closest_point_on_S2 = P2 + t * (Q2 - P2)
+ *
+ * Source: Ericson, *Real-Time Collision Detection*, §5.1.9. Robust to
+ * degenerate inputs (point-like segments, parallel segments) — both
+ * cases fall back to the clamped point-on-line projection.
+ *
+ * @param {number[]|Float64Array} out length >= 2; receives [s, t]
+ * @param {number} p1x  segment-A start x
+ * @param {number} p1y
+ * @param {number} p1z
+ * @param {number} q1x  segment-A end x
+ * @param {number} q1y
+ * @param {number} q1z
+ * @param {number} p2x  segment-B start x
+ * @param {number} p2y
+ * @param {number} p2z
+ * @param {number} q2x  segment-B end x
+ * @param {number} q2y
+ * @param {number} q2z
+ */
+export function line3_closest_points_segment_segment(out: number[] | Float64Array, p1x: number, p1y: number, p1z: number, q1x: number, q1y: number, q1z: number, p2x: number, p2y: number, p2z: number, q2x: number, q2y: number, q2z: number): void;
+//# sourceMappingURL=line3_closest_points_segment_segment.d.ts.map

package/src/core/geom/3d/line/line3_closest_points_segment_segment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"line3_closest_points_segment_segment.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/line/line3_closest_points_segment_segment.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,0DAdW,MAAM,EAAE,GAAC,YAAY,OACrB,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,QAuDhB"}

package/src/core/geom/3d/line/line3_closest_points_segment_segment.js

@@ -0,0 +1,88 @@
+import { clamp01 } from "../../../math/clamp01.js";
+
+/**
+ * Lengths-squared below this threshold are treated as "this segment is a
+ * point" so the algorithm degrades gracefully to point-segment closest.
+ * @type {number}
+ */
+const SEGMENT_EPS = 1e-12;
+
+/**
+ * Closest-point pair on two 3D line segments. Writes parameters `s` and `t`
+ * (each in `[0, 1]`) into `out[0]` and `out[1]` such that:
+ *
+ *     closest_point_on_S1 = P1 + s * (Q1 - P1)
+ *     closest_point_on_S2 = P2 + t * (Q2 - P2)
+ *
+ * Source: Ericson, *Real-Time Collision Detection*, §5.1.9. Robust to
+ * degenerate inputs (point-like segments, parallel segments) — both
+ * cases fall back to the clamped point-on-line projection.
+ *
+ * @param {number[]|Float64Array} out length >= 2; receives [s, t]
+ * @param {number} p1x  segment-A start x
+ * @param {number} p1y
+ * @param {number} p1z
+ * @param {number} q1x  segment-A end x
+ * @param {number} q1y
+ * @param {number} q1z
+ * @param {number} p2x  segment-B start x
+ * @param {number} p2y
+ * @param {number} p2z
+ * @param {number} q2x  segment-B end x
+ * @param {number} q2y
+ * @param {number} q2z
+ */
+export function line3_closest_points_segment_segment(
+    out,
+    p1x, p1y, p1z, q1x, q1y, q1z,
+    p2x, p2y, p2z, q2x, q2y, q2z
+) {
+    const d1x = q1x - p1x, d1y = q1y - p1y, d1z = q1z - p1z;
+    const d2x = q2x - p2x, d2y = q2y - p2y, d2z = q2z - p2z;
+    const rx  = p1x - p2x, ry  = p1y - p2y, rz  = p1z - p2z;
+
+    const a = d1x * d1x + d1y * d1y + d1z * d1z; // |d1|²
+    const e = d2x * d2x + d2y * d2y + d2z * d2z; // |d2|²
+    const f = d2x * rx + d2y * ry + d2z * rz;    // d2·r
+
+    let s, t;
+
+    if (a <= SEGMENT_EPS && e <= SEGMENT_EPS) {
+        // Both degenerate to points.
+        s = 0; t = 0;
+    } else if (a <= SEGMENT_EPS) {
+        // S1 is a point.
+        s = 0;
+        t = clamp01(f / e);
+    } else {
+        const c = d1x * rx + d1y * ry + d1z * rz; // d1·r
+        if (e <= SEGMENT_EPS) {
+            // S2 is a point.
+            t = 0;
+            s = clamp01(-c / a);
+        } else {
+            const b = d1x * d2x + d1y * d2y + d1z * d2z; // d1·d2
+            const denom = a * e - b * b; // always >= 0
+
+            if (denom !== 0) {
+                s = clamp01((b * f - c * e) / denom);
+            } else {
+                // Segments are parallel — any s is fine; pick 0.
+                s = 0;
+            }
+
+            t = (b * s + f) / e;
+
+            if (t < 0) {
+                t = 0;
+                s = clamp01(-c / a);
+            } else if (t > 1) {
+                t = 1;
+                s = clamp01((b - c) / a);
+            }
+        }
+    }
+
+    out[0] = s;
+    out[1] = t;
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Convert a unit quaternion to a 3×3 matrix laid out as
+ * "rows-are-world-coords-of-the-local-axes".
+ *
+ * Writes 9 floats starting at `out[out_offset]`:
+ *
+ *   row 0 (offsets 0..2) — image of body-local +X in world space
+ *   row 1 (offsets 3..5) — image of body-local +Y in world space
+ *   row 2 (offsets 6..8) — image of body-local +Z in world space
+ *
+ * This is the **transpose** of the standard linear-algebra rotation
+ * matrix `R(q)` (which is "columns-are-world-coords-of-local-axes" or
+ * equivalently rows-are-local-coords-of-world-axes). The layout here
+ * matches the existing `quat_to_axes` helpers in
+ * `box_box_manifold.js` / `box_triangle_contact.js` — for SAT
+ * projection a row dot product against a candidate axis directly
+ * yields "extent of the box's local axis i along that direction":
+ *
+ *   project_onto(v) = out[off+0..2] · v        // ← local-X extent
+ *
+ * Computing M(q) once and reusing across many vectors is cheaper
+ * than calling {@link v3_quat3_apply} per vector when the same
+ * orientation rotates ≥ 4 vectors (box-vs-box SAT projects 8
+ * corners; box-vs-triangle clips an incident face). For one-shot
+ * rotation use {@link v3_quat3_apply} directly.
+ *
+ * To rotate a world-space vector `v` into the local frame via the
+ * matrix form, the standard `R · v` (rotate local → world) requires
+ * a **column-major** read of this storage:
+ *
+ *   (R · v)[i] = out[off + 0 + i] * v[0]
+ *              + out[off + 3 + i] * v[1]
+ *              + out[off + 6 + i] * v[2]
+ *
+ * — equivalent to {@link v3_quat3_apply}(v, q).
+ *
+ * Sign convention: `(qx, qy, qz, qw)` — `w` last, matching
+ * {@link Quaternion} and the rest of the `core/geom/3d/quaternion/`
+ * family.
+ *
+ * Formula (yields R^T of the standard linear-algebra rotation matrix):
+ *   out[0]=1-2(yy+zz)   out[1]=2(xy+wz)     out[2]=2(xz-wy)
+ *   out[3]=2(xy-wz)     out[4]=1-2(xx+zz)   out[5]=2(yz+wx)
+ *   out[6]=2(xz+wy)     out[7]=2(yz-wx)     out[8]=1-2(xx+yy)
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset offset into `out`; receives 9 floats
+ * @param {number} qx unit quaternion x
+ * @param {number} qy
+ * @param {number} qz
+ * @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;
+//# sourceMappingURL=quat3_to_matrix3.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,69 @@
+/**
+ * Convert a unit quaternion to a 3×3 matrix laid out as
+ * "rows-are-world-coords-of-the-local-axes".
+ *
+ * Writes 9 floats starting at `out[out_offset]`:
+ *
+ *   row 0 (offsets 0..2) — image of body-local +X in world space
+ *   row 1 (offsets 3..5) — image of body-local +Y in world space
+ *   row 2 (offsets 6..8) — image of body-local +Z in world space
+ *
+ * This is the **transpose** of the standard linear-algebra rotation
+ * matrix `R(q)` (which is "columns-are-world-coords-of-local-axes" or
+ * equivalently rows-are-local-coords-of-world-axes). The layout here
+ * matches the existing `quat_to_axes` helpers in
+ * `box_box_manifold.js` / `box_triangle_contact.js` — for SAT
+ * projection a row dot product against a candidate axis directly
+ * yields "extent of the box's local axis i along that direction":
+ *
+ *   project_onto(v) = out[off+0..2] · v        // ← local-X extent
+ *
+ * Computing M(q) once and reusing across many vectors is cheaper
+ * than calling {@link v3_quat3_apply} per vector when the same
+ * orientation rotates ≥ 4 vectors (box-vs-box SAT projects 8
+ * corners; box-vs-triangle clips an incident face). For one-shot
+ * rotation use {@link v3_quat3_apply} directly.
+ *
+ * To rotate a world-space vector `v` into the local frame via the
+ * matrix form, the standard `R · v` (rotate local → world) requires
+ * a **column-major** read of this storage:
+ *
+ *   (R · v)[i] = out[off + 0 + i] * v[0]
+ *              + out[off + 3 + i] * v[1]
+ *              + out[off + 6 + i] * v[2]
+ *
+ * — equivalent to {@link v3_quat3_apply}(v, q).
+ *
+ * Sign convention: `(qx, qy, qz, qw)` — `w` last, matching
+ * {@link Quaternion} and the rest of the `core/geom/3d/quaternion/`
+ * family.
+ *
+ * Formula (yields R^T of the standard linear-algebra rotation matrix):
+ *   out[0]=1-2(yy+zz)   out[1]=2(xy+wz)     out[2]=2(xz-wy)
+ *   out[3]=2(xy-wz)     out[4]=1-2(xx+zz)   out[5]=2(yz+wx)
+ *   out[6]=2(xz+wy)     out[7]=2(yz-wx)     out[8]=1-2(xx+yy)
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset offset into `out`; receives 9 floats
+ * @param {number} qx unit quaternion x
+ * @param {number} qy
+ * @param {number} qz
+ * @param {number} qw unit quaternion w (last)
+ */
+export function quat3_to_matrix3(out, out_offset, qx, qy, qz, qw) {
+    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

@@ -51,14 +51,14 @@ 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
-     * @param {number[]|Float32Array} result
+     * @param {number[]|Float32Array|Float64Array} result
      * @param {number} result_offset
      * @param {number} direction_x
      * @param {number} direction_y
      * @param {number} direction_z
      * @returns {void}
      */
-    support(result: number[] | Float32Array, result_offset: number, direction_x: number, direction_y: number, direction_z: number): void;
+    support(result: number[] | Float32Array | Float64Array, result_offset: number, direction_x: number, direction_y: number, direction_z: number): void;
     /**
      * @template {AbstractShape3D} T
      * @param {T} other
@@ -70,5 +70,27 @@ export class AbstractShape3D {
      * @returns {number}
      */
     hash(): number;
+    /**
+     * Whether this shape is convex.
+     *
+     * Convex shapes can be fed directly into GJK/EPA via their {@link support}
+     * function — the Minkowski difference of two convex sets is itself convex,
+     * which is the precondition GJK relies on. Non-convex shapes (heightmaps,
+     * arbitrary meshes, unions of convex shapes) violate that precondition: the
+     * support operator is still definable as `argmax (p · d)`, but feeding it to
+     * GJK will produce false negatives where the algorithm walks into a
+     * concavity and reports "no overlap" between intersecting bodies.
+     *
+     * The narrowphase reads this flag to gate Minkowski-based pair dispatch.
+     * When `false`, a dedicated path is required (grid traversal for heightmaps,
+     * per-triangle GJK for meshes, per-child decomposition for unions).
+     *
+     * Default is `true` — convex is the common case across primitives. Each
+     * non-convex subclass overrides this on its own prototype.
+     *
+     * @readonly
+     * @type {boolean}
+     */
+    readonly is_convex: boolean;
 }
 //# sourceMappingURL=AbstractShape3D.d.ts.map

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;;;;;;OAMG;IACH,sCALW,MAAM,EAAE,iBACR,MAAM,qBAEJ,IAAI,CAIhB;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,iBACrB,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,GACJ,IAAI,CAIhB;IAED;;;;OAIG;IACH,6CAFa,OAAO,CAInB;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;CACJ"}
+{"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;;;;;;OAMG;IACH,sCALW,MAAM,EAAE,iBACR,MAAM,qBAEJ,IAAI,CAIhB;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;;;;OAIG;IACH,6CAFa,OAAO,CAInB;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAGL;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,oBAFU,OAAO,CAEkB;CAvBlC"}

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

@@ -75,7 +75,7 @@ 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
-     * @param {number[]|Float32Array} result
+     * @param {number[]|Float32Array|Float64Array} result
      * @param {number} result_offset
      * @param {number} direction_x
      * @param {number} direction_y
@@ -103,3 +103,26 @@ export class AbstractShape3D {
         return 0;
     }
 }
+
+/**
+ * Whether this shape is convex.
+ *
+ * Convex shapes can be fed directly into GJK/EPA via their {@link support}
+ * function — the Minkowski difference of two convex sets is itself convex,
+ * which is the precondition GJK relies on. Non-convex shapes (heightmaps,
+ * arbitrary meshes, unions of convex shapes) violate that precondition: the
+ * support operator is still definable as `argmax (p · d)`, but feeding it to
+ * GJK will produce false negatives where the algorithm walks into a
+ * concavity and reports "no overlap" between intersecting bodies.
+ *
+ * The narrowphase reads this flag to gate Minkowski-based pair dispatch.
+ * When `false`, a dedicated path is required (grid traversal for heightmaps,
+ * per-triangle GJK for meshes, per-child decomposition for unions).
+ *
+ * Default is `true` — convex is the common case across primitives. Each
+ * non-convex subclass overrides this on its own prototype.
+ *
+ * @readonly
+ * @type {boolean}
+ */
+AbstractShape3D.prototype.is_convex = true;

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

@@ -0,0 +1,61 @@
+/**
+ * Axis-aligned box of arbitrary half-extents, expressed in the body's local
+ * frame. The shape spans `[-half_extents.x, +half_extents.x]` along X and
+ * symmetrically on Y / Z.
+ *
+ * This is the generalisation of {@link UnitCubeShape3D} (which is fixed to
+ * `0.5` per axis). The physics narrowphase recognises both via the shared
+ * `isBoxShape3D` prototype marker and reads `half_extents.x / y / z` to feed
+ * the closed-form sphere-box and box-box paths.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BoxShape3D extends AbstractShape3D {
+    /**
+     * Convenience constructor.
+     * @param {number} hx
+     * @param {number} hy
+     * @param {number} hz
+     * @returns {BoxShape3D}
+     */
+    static from(hx: number, hy: number, hz: number): BoxShape3D;
+    /**
+     * Convenience constructor for boxes specified by full side lengths
+     * rather than half-extents.
+     * @param {number} width
+     * @param {number} height
+     * @param {number} depth
+     * @returns {BoxShape3D}
+     */
+    static from_size(width: number, height: number, depth: number): BoxShape3D;
+    /**
+     * Half-width / half-height / half-depth in the body's local frame.
+     * @readonly
+     * @type {Vector3}
+     */
+    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;
+    signed_distance_gradient_at_point(result: any, point: any): number;
+    signed_distance_at_point(point: any): number;
+    contains_point(point: any): boolean;
+    sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
+    /**
+     * @param {BoxShape3D} other
+     * @returns {boolean}
+     */
+    equals(other: BoxShape3D): boolean;
+    /**
+     * Fast type-check marker. Lets the physics narrowphase dispatch sphere-box
+     * and box-box pairs against arbitrary-half-extent boxes without an instanceof
+     * import or chain check. Read together with `shape.half_extents.x/y/z`.
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isBoxShape3D: boolean;
+}
+import { AbstractShape3D } from "./AbstractShape3D.js";
+import Vector3 from "../../Vector3.js";
+//# sourceMappingURL=BoxShape3D.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BoxShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/BoxShape3D.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;GAYG;AACH;IAYI;;;;;;OAMG;IACH,gBALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,UAAU,CAMtB;IAED;;;;;;;OAOG;IACH,wBALW,MAAM,UACN,MAAM,SACN,MAAM,GACJ,UAAU,CAItB;IA/BG;;;;OAIG;IACH,uBAFU,OAAO,CAE6B;IAsClD,wCAIC;IAED,4DAQC;IAED,qGAKC;IAED,mEAEC;IAED,6CAaC;IAED,oCAQC;IAED,kFAOC;IAED;;;OAGG;IACH,cAHW,UAAU,GACR,OAAO,CAInB;IAWL;;;;;;OAMG;IACH,uBAFU,OAAO,CAEgB;CAThC;gCA3I+B,sBAAsB;oBATlC,kBAAkB"}

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

@@ -0,0 +1,158 @@
+import Vector3 from "../../Vector3.js";
+import { max2 } from "../../../math/max2.js";
+import { max3 } from "../../../math/max3.js";
+import { min2 } from "../../../math/min2.js";
+import { sign_not_zero } from "../../../math/sign_not_zero.js";
+import { computeHashFloat } from "../../../primitives/numbers/computeHashFloat.js";
+import { randomPointInBox } from "../../random/randomPointInBox.js";
+import { v3_length } from "../../vec3/v3_length.js";
+import { aabb3_nearest_point_on_surface } from "../aabb/aabb3_nearest_point_on_surface.js";
+import { AbstractShape3D } from "./AbstractShape3D.js";
+import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
+
+/**
+ * Axis-aligned box of arbitrary half-extents, expressed in the body's local
+ * frame. The shape spans `[-half_extents.x, +half_extents.x]` along X and
+ * symmetrically on Y / Z.
+ *
+ * This is the generalisation of {@link UnitCubeShape3D} (which is fixed to
+ * `0.5` per axis). The physics narrowphase recognises both via the shared
+ * `isBoxShape3D` prototype marker and reads `half_extents.x / y / z` to feed
+ * the closed-form sphere-box and box-box paths.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BoxShape3D extends AbstractShape3D {
+    constructor() {
+        super();
+
+        /**
+         * Half-width / half-height / half-depth in the body's local frame.
+         * @readonly
+         * @type {Vector3}
+         */
+        this.half_extents = new Vector3(0.5, 0.5, 0.5);
+    }
+
+    /**
+     * Convenience constructor.
+     * @param {number} hx
+     * @param {number} hy
+     * @param {number} hz
+     * @returns {BoxShape3D}
+     */
+    static from(hx, hy, hz) {
+        const b = new BoxShape3D();
+        b.half_extents.set(hx, hy, hz);
+        return b;
+    }
+
+    /**
+     * Convenience constructor for boxes specified by full side lengths
+     * rather than half-extents.
+     * @param {number} width
+     * @param {number} height
+     * @param {number} depth
+     * @returns {BoxShape3D}
+     */
+    static from_size(width, height, depth) {
+        return BoxShape3D.from(width * 0.5, height * 0.5, depth * 0.5);
+    }
+
+    get volume() {
+        const h = this.half_extents;
+        return 8 * h.x * h.y * h.z;
+    }
+
+    get surface_area() {
+        const h = this.half_extents;
+        return 8 * (h.x * h.y + h.y * h.z + h.z * h.x);
+    }
+
+    compute_bounding_box(result) {
+        const h = this.half_extents;
+        result[0] = -h.x; result[1] = -h.y; result[2] = -h.z;
+        result[3] =  h.x; result[4] =  h.y; result[5] =  h.z;
+    }
+
+    nearest_point_on_surface(result, reference) {
+        const h = this.half_extents;
+        aabb3_nearest_point_on_surface(
+            result,
+            -h.x, -h.y, -h.z,
+             h.x,  h.y,  h.z,
+            reference[0], reference[1], reference[2]
+        );
+    }
+
+    support(result, result_offset, direction_x, direction_y, direction_z) {
+        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;
+        result[result_offset + 2] = sign_not_zero(direction_z) * h.z;
+    }
+
+    signed_distance_gradient_at_point(result, point) {
+        return compute_signed_distance_gradient_by_sampling(result, this, point);
+    }
+
+    signed_distance_at_point(point) {
+        // SDF of an axis-aligned box centred at origin. Same closed form as
+        // UnitCubeShape3D but parametrised by half_extents.
+        const h = this.half_extents;
+        const q_x = Math.abs(point[0]) - h.x;
+        const q_y = Math.abs(point[1]) - h.y;
+        const q_z = Math.abs(point[2]) - h.z;
+
+        return v3_length(
+            max2(q_x, 0),
+            max2(q_y, 0),
+            max2(q_z, 0)
+        ) + min2(max3(q_x, q_y, q_z), 0);
+    }
+
+    contains_point(point) {
+        const h = this.half_extents;
+        const x = point[0];
+        const y = point[1];
+        const z = point[2];
+        return x > -h.x && x < h.x
+            && y > -h.y && y < h.y
+            && z > -h.z && z < h.z;
+    }
+
+    sample_random_point_in_volume(result, result_offset, random) {
+        randomPointInBox(random, result, result_offset);
+        const h = this.half_extents;
+        // randomPointInBox samples a unit cube — rescale to our half-extents.
+        result[result_offset]     *= h.x * 2;
+        result[result_offset + 1] *= h.y * 2;
+        result[result_offset + 2] *= h.z * 2;
+    }
+
+    /**
+     * @param {BoxShape3D} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return super.equals(other) && this.half_extents.equals(other.half_extents);
+    }
+
+    hash() {
+        const h = this.half_extents;
+        const a = computeHashFloat(h.x);
+        const b = computeHashFloat(h.y);
+        const c = computeHashFloat(h.z);
+        return ((a * 31 + b) * 31 + c) | 0;
+    }
+}
+
+/**
+ * Fast type-check marker. Lets the physics narrowphase dispatch sphere-box
+ * and box-box pairs against arbitrary-half-extent boxes without an instanceof
+ * import or chain check. Read together with `shape.half_extents.x/y/z`.
+ * @readonly
+ * @type {boolean}
+ */
+BoxShape3D.prototype.isBoxShape3D = true;

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

@@ -32,6 +32,17 @@ export class CapsuleShape3D extends AbstractShape3D {
      * @returns {boolean}
      */
     equals(other: CapsuleShape3D): boolean;
+    /**
+     * Fast type-check marker, mirroring `UnitSphereShape3D.prototype.isUnitSphereShape3D`
+     * and `BoxShape3D.prototype.isBoxShape3D`. Lets the physics narrowphase
+     * dispatch capsule-sphere / capsule-capsule / capsule-box pairs to
+     * closed-form helpers (capsule = Minkowski sum of segment + sphere; all
+     * three reduce to point-or-segment distance queries that GJK+EPA struggles
+     * with on a smooth surface).
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isCapsuleShape3D: boolean;
 }
 import { AbstractShape3D } from "./AbstractShape3D.js";
 //# sourceMappingURL=CapsuleShape3D.d.ts.map

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":"AAYA;;;;GAIG;AACH;IAiBI;;;;OAIG;IACH,oBAJW,MAAM,UACN,MAAM,GACJ,cAAc,CAa1B;IA7BG;;;OAGG;IACH,QAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,QAFU,MAAM,CAED;IAqCnB,wCAUC;IAED,6CAaC;IAED,mEAEC;IAED,oCAcC;IAED,4DA+BC;IAED,qGAUC;IAED,kFA+BC;IAED;;;OAGG;IACH,cAHW,cAAc,GACZ,OAAO,CAMnB;CAQJ;gCA1M+B,sBAAsB"}
+{"version":3,"file":"CapsuleShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/CapsuleShape3D.js"],"names":[],"mappings":"AAYA;;;;GAIG;AACH;IAiBI;;;;OAIG;IACH,oBAJW,MAAM,UACN,MAAM,GACJ,cAAc,CAa1B;IA7BG;;;OAGG;IACH,QAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,QAFU,MAAM,CAED;IAqCnB,wCAUC;IAED,6CAaC;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;gCA1M+B,sBAAsB"}