@woosh/meep-engine 2.138.19 → 2.139.0

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/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"}

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

@@ -208,3 +208,15 @@ export class CapsuleShape3D extends AbstractShape3D {
         return ((a << 5) - a + b) | 0;
     }
 }
+
+/**
+ * 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}
+ */
+CapsuleShape3D.prototype.isCapsuleShape3D = true;

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

@@ -1,12 +1,40 @@
-export class UnitCubeShape3D extends AbstractShape3D {
+/**
+ * Unit cube centred at the origin, spanning `[-0.5, 0.5]` on every axis.
+ *
+ * @deprecated Use {@link BoxShape3D} instead — UnitCubeShape3D is now a thin
+ * subclass that just pins `half_extents` to `(0.5, 0.5, 0.5)`. All geometry
+ * (`support`, `signed_distance_at_point`, `volume`, `surface_area`,
+ * `nearest_point_on_surface`, ...) is inherited from {@link BoxShape3D}.
+ *
+ * Kept only for:
+ *   - the `UnitCubeShape3D.INSTANCE` shared singleton that scenes and tests
+ *     embed by reference
+ *   - the JSON `'cube'` type-tag round-trip in `shape_to_type` /
+ *     `type_adapters` (an `instanceof` check, which is why we still need a
+ *     distinct subclass rather than a constant `BoxShape3D` instance)
+ *
+ * For new code prefer:
+ *   - `new BoxShape3D()` — also defaults to half-extents `(0.5, 0.5, 0.5)`
+ *   - `BoxShape3D.from_size(w, h, d)` — express by full side lengths
+ *   - `BoxShape3D.from(hx, hy, hz)` — express by half-extents
+ */
+export class UnitCubeShape3D extends BoxShape3D {
+    /**
+     * Shared singleton. Many call sites — JSON deserialisation, tests,
+     * `TransformedShape3D.from_translation(UnitCubeShape3D.INSTANCE, ...)`
+     * — embed this by reference rather than allocating a fresh cube.
+     * @type {UnitCubeShape3D}
+     */
     static INSTANCE: UnitCubeShape3D;
-    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;
+    /**
+     * @deprecated Prefer dispatching on `isBoxShape3D`, which is `true` for both
+     * UnitCubeShape3D (inherited via prototype chain) and {@link BoxShape3D}.
+     * Retained so any older external code that already narrowed via this marker
+     * keeps working.
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isUnitCubeShape3D: boolean;
 }
-import { AbstractShape3D } from "./AbstractShape3D.js";
+import { BoxShape3D } from "./BoxShape3D.js";
 //# sourceMappingURL=UnitCubeShape3D.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"UnitCubeShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnitCubeShape3D.js"],"names":[],"mappings":"AAUA;IAsFI,iCAAwC;IA5ExC,wCAQC;IAED,4DAYC;IAED,qGAIC;IAED,mEAEC;IAED,6CAqBC;IAED,oCASC;IAED,kFAEC;CAOJ;gCA1F+B,sBAAsB"}
+{"version":3,"file":"UnitCubeShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnitCubeShape3D.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAKI;;;;;OAKG;IACH,iBAFU,eAAe,CAEe;IAG5C;;;;;;;OAOG;IACH,4BAFU,OAAO,CAE0B;CAV1C;2BAlC0B,iBAAiB"}

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

@@ -1,98 +1,45 @@
-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 { 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";
-
-export class UnitCubeShape3D extends AbstractShape3D {
-
-    get volume() {
-        return 1;
-    }
-
-    get surface_area() {
-        return 6;
-    }
-
-    compute_bounding_box(result) {
-        result[0] = -0.5;
-        result[1] = -0.5;
-        result[2] = -0.5;
-
-        result[3] = 0.5;
-        result[4] = 0.5;
-        result[5] = 0.5;
-    }
-
-    nearest_point_on_surface(result, reference) {
-        const r_x = reference[0];
-        const r_y = reference[1];
-        const r_z = reference[2];
-
-        aabb3_nearest_point_on_surface(
-            result,
-            -0.5, -0.5, -0.5,
-            0.5, 0.5, 0.5,
-            r_x, r_y, r_z
-        );
-
-    }
-
-    support(result, result_offset, direction_x, direction_y, direction_z) {
-        result[result_offset] = sign_not_zero(direction_x) * 0.5;
-        result[result_offset + 1] = sign_not_zero(direction_y) * 0.5;
-        result[result_offset + 2] = sign_not_zero(direction_z) * 0.5;
-    }
-
-    signed_distance_gradient_at_point(result, point) {
-        return compute_signed_distance_gradient_by_sampling(result, this, point);
-    }
-
-    signed_distance_at_point(point) {
-        /*
-        based on https://www.iquilezles.org/www/articles/distfunctions/distfunctions.htm
-        original shader code:
-            ------------
-            float sdBox( vec3 p, vec3 b )
-            {
-              vec3 q = abs(p) - b;
-              return length(max(q,0.0)) + min(max(q.x,max(q.y,q.z)),0.0);
-            }
-            ------------
-         */
-        const q_x = Math.abs(point[0]) - 0.5;
-        const q_y = Math.abs(point[1]) - 0.5;
-        const q_z = Math.abs(point[2]) - 0.5;
-
-        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 x = point[0];
-        const y = point[1];
-        const z = point[2];
-
-        return x > -0.5 && x < 0.5
-            && y > -0.5 && y < 0.5
-            && z > -0.5 && z < 0.5
-            ;
-    }
-
-    sample_random_point_in_volume(result, result_offset, random) {
-        randomPointInBox(random, result, result_offset);
-    }
-
-    hash() {
-        return 1;
-    }
-
-    static INSTANCE = new UnitCubeShape3D();
-}
+import { BoxShape3D } from "./BoxShape3D.js";
+
+/**
+ * Unit cube centred at the origin, spanning `[-0.5, 0.5]` on every axis.
+ *
+ * @deprecated Use {@link BoxShape3D} instead — UnitCubeShape3D is now a thin
+ * subclass that just pins `half_extents` to `(0.5, 0.5, 0.5)`. All geometry
+ * (`support`, `signed_distance_at_point`, `volume`, `surface_area`,
+ * `nearest_point_on_surface`, ...) is inherited from {@link BoxShape3D}.
+ *
+ * Kept only for:
+ *   - the `UnitCubeShape3D.INSTANCE` shared singleton that scenes and tests
+ *     embed by reference
+ *   - the JSON `'cube'` type-tag round-trip in `shape_to_type` /
+ *     `type_adapters` (an `instanceof` check, which is why we still need a
+ *     distinct subclass rather than a constant `BoxShape3D` instance)
+ *
+ * For new code prefer:
+ *   - `new BoxShape3D()` — also defaults to half-extents `(0.5, 0.5, 0.5)`
+ *   - `BoxShape3D.from_size(w, h, d)` — express by full side lengths
+ *   - `BoxShape3D.from(hx, hy, hz)` — express by half-extents
+ */
+export class UnitCubeShape3D extends BoxShape3D {
+    // No constructor / no method overrides on purpose. BoxShape3D's
+    // constructor already sets half_extents to (0.5, 0.5, 0.5), and every
+    // geometry method is correct for that case verbatim.
+
+    /**
+     * Shared singleton. Many call sites — JSON deserialisation, tests,
+     * `TransformedShape3D.from_translation(UnitCubeShape3D.INSTANCE, ...)`
+     * — embed this by reference rather than allocating a fresh cube.
+     * @type {UnitCubeShape3D}
+     */
+    static INSTANCE = new UnitCubeShape3D();
+}
+
+/**
+ * @deprecated Prefer dispatching on `isBoxShape3D`, which is `true` for both
+ * UnitCubeShape3D (inherited via prototype chain) and {@link BoxShape3D}.
+ * Retained so any older external code that already narrowed via this marker
+ * keeps working.
+ * @readonly
+ * @type {boolean}
+ */
+UnitCubeShape3D.prototype.isUnitCubeShape3D = true;

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

@@ -9,6 +9,16 @@ export class UnitSphereShape3D extends AbstractShape3D {
     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;
+    /**
+     * Fast type-check marker (mirrors {@link Transform.prototype.isTransform}). Lets
+     * downstream code dispatch on shape kind without instanceof / import coupling.
+     * Use case: physics narrowphase short-circuits sphere-sphere to a closed-form
+     * solution rather than running GJK+EPA on a smooth surface (which is the EPA
+     * degenerate case).
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isUnitSphereShape3D: boolean;
 }
 export namespace UnitSphereShape3D {
     let INSTANCE: UnitSphereShape3D;

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

@@ -1 +1 @@
-{"version":3,"file":"UnitSphereShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnitSphereShape3D.js"],"names":[],"mappings":"AAKA;;GAEG;AACH;IASI,qGAQC;IAED,wCAQC;IAED,4DAYC;IAED,mEAEC;IAED,6CAMC;IAED,oCAMC;IAED,kFAEC;CAKJ;;;;gCA5E+B,sBAAsB"}
+{"version":3,"file":"UnitSphereShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnitSphereShape3D.js"],"names":[],"mappings":"AAKA;;GAEG;AACH;IASI,qGAQC;IAED,wCAQC;IAED,4DAYC;IAED,mEAEC;IAED,6CAMC;IAED,oCAMC;IAED,kFAEC;IASL;;;;;;;;OAQG;IACH,8BAFU,OAAO,CAE8B;CAb9C;;;;gCA5E+B,sBAAsB"}

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

@@ -79,3 +79,14 @@ export class UnitSphereShape3D extends AbstractShape3D {
 }
 
 UnitSphereShape3D.INSTANCE = new UnitSphereShape3D();
+
+/**
+ * Fast type-check marker (mirrors {@link Transform.prototype.isTransform}). Lets
+ * downstream code dispatch on shape kind without instanceof / import coupling.
+ * Use case: physics narrowphase short-circuits sphere-sphere to a closed-form
+ * solution rather than running GJK+EPA on a smooth surface (which is the EPA
+ * degenerate case).
+ * @readonly
+ * @type {boolean}
+ */
+UnitSphereShape3D.prototype.isUnitSphereShape3D = true;

package/src/core/geom/3d/shape/util/shape3d_voxelize_to_grid.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Rasterize an {@link AbstractShape3D} into a cell-centered Uint8 grid mask.
+ *
+ * For each integer cell `(i, j, k)` in `[0, rx) × [0, ry) × [0, rz)`, the cell's
+ * center is recovered as the world-space point `grid_to_world * (i, j, k)`. If
+ * that point lies inside the shape — or close enough to its surface (see below)
+ * — the corresponding cell in `grid` is written as `1`.
+ *
+ * The grid is **not** cleared first. Cells outside the shape (and outside its
+ * proximity band) are left exactly as they were, which lets the caller compose
+ * multiple shapes into the same buffer by calling this function repeatedly. The
+ * caller is responsible for `grid.fill(0)` if a fresh mask is desired.
+ *
+ * **Proximity test.** A cell whose centre is outside the shape is still marked
+ * solid if `signed_distance_at_point(centre) < half_cell_diagonal`. This catches
+ * features that pass through a cell without containing its centre — e.g. a thin
+ * sheet bisecting a cubic cell at 45°. The threshold is the largest possible
+ * distance from a cell's centre to any point inside the cell, so any shape that
+ * intersects the cell at all is captured. Cheap fast path: `contains_point` is
+ * tested first (no sqrt for most shapes); the more expensive signed-distance
+ * call only runs for cells whose centre is outside.
+ *
+ * **Volume guard.** If the shape's total volume is less than half the volume of
+ * a single cell, the function returns immediately without writing anything. A
+ * shape that small can't be meaningfully represented as a unit-cell solid — the
+ * obstacle would end up perceptibly larger than the shape itself. Callers with
+ * sub-cell shapes should either refine the grid or use a different
+ * representation (e.g. a point-velocity effector).
+ *
+ * **Coord space.** `shape.contains_point` / `signed_distance_at_point` are
+ * called with **world** coordinates. For shapes that have their own local frame
+ * (e.g. `UnitSphereShape3D` centred at the origin), wrap them in a
+ * {@link TransformedShape3D} so they sit at the right world position before
+ * passing in. The voxelizer is otherwise agnostic to how the shape interprets
+ * its inputs.
+ *
+ * **Grid orientation.** `world_to_grid` and `grid_to_world` are full 4×4
+ * column-major affines, so the grid can be translated, scaled, or rotated in
+ * world space; the algorithm makes no axis-aligned assumption. Cell size per
+ * axis is recovered from the column lengths of `grid_to_world`, which is exact
+ * for orthogonal grids and an overestimate of cell volume for skewed ones — the
+ * latter only widens the volume-guard threshold, which is conservative.
+ *
+ * Designed to feed e.g. a fluid simulator's solid mask, but lives outside any
+ * specific package: anything that needs "rasterize a shape into a cell-centered
+ * boolean grid" can use it.
+ *
+ * @param {AbstractShape3D} shape  shape to voxelize; `contains_point` and
+ *     `signed_distance_at_point` are invoked with world-space points.
+ * @param {Float32Array|number[]} world_to_grid  column-major 4×4 affine;
+ *     world point → grid (cell-index) coords.
+ * @param {Float32Array|number[]} grid_to_world  column-major 4×4 affine;
+ *     grid (cell-index) coords → world cell center.
+ * @param {Uint8Array} grid  output mask, length must be ≥ `rx * ry * rz`.
+ *     Cells that don't pass the test are left untouched.
+ * @param {number} rx  positive integer.
+ * @param {number} ry  positive integer.
+ * @param {number} rz  positive integer.
+ */
+export function shape3d_voxelize_to_grid(shape: AbstractShape3D, world_to_grid: Float32Array | number[], grid_to_world: Float32Array | number[], grid: Uint8Array, rx: number, ry: number, rz: number): void;
+//# sourceMappingURL=shape3d_voxelize_to_grid.d.ts.map

package/src/core/geom/3d/shape/util/shape3d_voxelize_to_grid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape3d_voxelize_to_grid.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/util/shape3d_voxelize_to_grid.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,gFAVW,YAAY,GAAC,MAAM,EAAE,iBAErB,YAAY,GAAC,MAAM,EAAE,QAErB,UAAU,MAEV,MAAM,MACN,MAAM,MACN,MAAM,QA6EhB"}