@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -1,16 +1,12 @@
 import { hash_mix3 } from "../../../math/hash/hash_mix3.js";
 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 { random_point_in_box } from "../../random/random_point_in_box.js";
-import { v3_length } from "../../vec3/v3_length.js";
 import { aabb3_closest_point_on_surface } from "../aabb/aabb3_closest_point_on_surface.js";
 import { box3_raycast } from "../box/box3_raycast.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
-import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
+import { sdf3_box, sdf3_box_gradient } from "./sdf/sdf3_box.js";
 
 /**
  * Axis-aligned box of arbitrary half-extents, expressed in the body's local
@@ -107,22 +103,15 @@ export class BoxShape3D extends AbstractShape3D {
     }
 
     signed_distance_gradient_at_point(result, point) {
-        return compute_signed_distance_gradient_by_sampling(result, this, point);
+        const h = this.half_extents;
+
+        return sdf3_box_gradient(result, 0, point[0], point[1], point[2], h.x, h.y, h.z);
     }
 
     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);
+
+        return sdf3_box(point[0], point[1], point[2], h.x, h.y, h.z);
     }
 
     contains_point(point) {

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,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;gCAxN+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,qGAUC;IAED,kFA+BC;IAED;;;OAGG;IACH,cAHW,cAAc,GACZ,OAAO,CAMnB;IAUL;;;;;;;;;OASG;IACH,2BAFU,OAAO,CAEwB;CAZxC;gCA7M+B,sBAAsB"}

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

@@ -8,7 +8,7 @@ import { random_point_in_sphere } from "../../random/random_point_in_sphere.js";
 import { v3_length } from "../../vec3/v3_length.js";
 import { capsule_raycast } from "../capsule/capsule_raycast.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
-import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
+import { sdf3_capsule, sdf3_capsule_gradient } from "./sdf/sdf3_capsule.js";
 
 const scratch_v3 = [0, 0, 0];
 
@@ -95,22 +95,11 @@ export class CapsuleShape3D extends AbstractShape3D {
     }
 
     signed_distance_at_point(point) {
-        const px = point[0];
-        const py = point[1];
-        const pz = point[2];
-
-        const half_h = this.height / 2;
-
-        // collapse Y onto the central segment
-        const y_seg = clamp(py, -half_h, half_h);
-
-        const dy = py - y_seg;
-
-        return v3_length(px, dy, pz) - this.radius;
+        return sdf3_capsule(point[0], point[1], point[2], this.radius, this.height);
     }
 
     signed_distance_gradient_at_point(result, point) {
-        return compute_signed_distance_gradient_by_sampling(result, this, point);
+        return sdf3_capsule_gradient(result, 0, point[0], point[1], point[2], this.radius, this.height);
     }
 
     contains_point(point) {

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

@@ -89,16 +89,14 @@ export class ConvexHullShape3D extends AbstractShape3D {
      * caller outside the class (the physics narrowphase's ray refinement) needs them, and re-deriving
      * them per query would repeat the O(F) pass this already cached.
      *
-     * @readonly
      * @returns {Float64Array}
      */
-    readonly get face_planes(): Float64Array;
+    get face_planes(): Float64Array;
     /**
      * Number of face half-spaces in {@link face_planes}.
-     * @readonly
      * @returns {number}
      */
-    readonly get face_plane_count(): number;
+    get face_plane_count(): number;
     raycast(hit: any, ray: any): boolean;
     /**
      * Convex half-space test: inside iff the point is behind (or on) every face

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;;;;;;;;OAQG;IACH,yCAEC;IAED;;;;OAIG;IACH,wCAEC;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;gCAtY+B,sBAAsB"}
+{"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"}

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

@@ -254,7 +254,6 @@ export class ConvexHullShape3D extends AbstractShape3D {
      * caller outside the class (the physics narrowphase's ray refinement) needs them, and re-deriving
      * them per query would repeat the O(F) pass this already cached.
      *
-     * @readonly
      * @returns {Float64Array}
      */
     get face_planes() {
@@ -263,7 +262,6 @@ export class ConvexHullShape3D extends AbstractShape3D {
 
     /**
      * Number of face half-spaces in {@link face_planes}.
-     * @readonly
      * @returns {number}
      */
     get face_plane_count() {

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

@@ -1 +1 @@
-{"version":3,"file":"CylinderShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/CylinderShape3D.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;GAaG;AACH;IAcI;;;;OAIG;IACH,oBAJW,MAAM,UACN,MAAM,GACJ,eAAe,CAa3B;IA7BD;;;OAGG;IACH,QAFU,MAAM,CAEH;IAEb;;;;OAIG;IACH,QAFU,MAAM,CAEL;IA+BX,qCAkBC;IAED,wCAUC;IAED,qGAqBC;IAED,6CAoBC;IAED,mEAEC;IAED,oCASC;IAED,4DA0CC;IAED,kFAOC;IAED;;;OAGG;IACH,cAHW,eAAe,GACb,OAAO,CAMnB;IAUL;;;;;;;OAOG;IACH,4BAFU,OAAO,CAE0B;CAV1C;gCAhO+B,sBAAsB"}
+{"version":3,"file":"CylinderShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/CylinderShape3D.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;GAaG;AACH;IAcI;;;;OAIG;IACH,oBAJW,MAAM,UACN,MAAM,GACJ,eAAe,CAa3B;IA7BD;;;OAGG;IACH,QAFU,MAAM,CAEH;IAEb;;;;OAIG;IACH,QAFU,MAAM,CAEL;IA+BX,qCAkBC;IAED,wCAUC;IAED,qGAqBC;IAED,6CAEC;IAED,mEAEC;IAED,oCASC;IAED,4DA0CC;IAED,kFAOC;IAED;;;OAGG;IACH,cAHW,eAAe,GACb,OAAO,CAMnB;IAUL;;;;;;;OAOG;IACH,4BAFU,OAAO,CAE0B;CAV1C;gCA9M+B,sBAAsB"}

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

@@ -6,7 +6,7 @@ import { computeHashFloat } from "../../../primitives/numbers/computeHashFloat.j
 import { random_point_in_circle } from "../../random/random_point_in_circle.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
 import { cylinder3_raycast } from "../cylinder/cylinder3_raycast.js";
-import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
+import { sdf3_cylinder, sdf3_cylinder_gradient } from "./sdf/sdf3_cylinder.js";
 
 const scratch_v3 = [0, 0, 0];
 
@@ -123,29 +123,11 @@ export class CylinderShape3D extends AbstractShape3D {
     }
 
     signed_distance_at_point(point) {
-        const px = point[0];
-        const py = point[1];
-        const pz = point[2];
-
-        const half_h = this.height / 2;
-
-        // Inigo Quilez capped-cylinder SDF, axis = Y. `d_radial` / `d_axial` are
-        // the signed distances outside the infinite cylinder and the slab.
-        const d_radial = Math.sqrt(px * px + pz * pz) - this.radius;
-        const d_axial = Math.abs(py) - half_h;
-
-        const ext_r = d_radial > 0 ? d_radial : 0;
-        const ext_a = d_axial > 0 ? d_axial : 0;
-        const outside = Math.sqrt(ext_r * ext_r + ext_a * ext_a);
-
-        const m = d_radial > d_axial ? d_radial : d_axial;
-        const inside = m < 0 ? m : 0;
-
-        return outside + inside;
+        return sdf3_cylinder(point[0], point[1], point[2], this.radius, this.height);
     }
 
     signed_distance_gradient_at_point(result, point) {
-        return compute_signed_distance_gradient_by_sampling(result, this, point);
+        return sdf3_cylinder_gradient(result, 0, point[0], point[1], point[2], this.radius, this.height);
     }
 
     contains_point(point) {

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

@@ -0,0 +1,105 @@
+/**
+ * # An infinite half-space
+ *
+ * The solid is `{ p : n·p − offset ≤ 0 }` — everything on the far side of the
+ * boundary plane from the direction {@link normal} points in. So `normal` is
+ * the **outward** surface normal, exactly as it is for every other shape's
+ * signed-distance gradient, and `offset` is how far along it the boundary sits
+ * from the body's local origin.
+ *
+ * A ground plane is `normal = (0, 1, 0), offset = 0`: solid below, open above.
+ *
+ * ## Why a shape rather than a very large box
+ *
+ * A box standing in for a ground plane has to be large enough that nothing ever
+ * reaches its edge and thin enough that nothing tunnels through it, and those
+ * two requirements pull against each other in `Float32`. It also costs a
+ * six-face field evaluation where the honest answer is one dot product, and its
+ * gradient has creases that the thing it is standing in for does not.
+ *
+ * ## What it deliberately does not implement, and why that is the honest answer
+ *
+ * A half-space is convex and **unbounded**, and three of
+ * {@link AbstractShape3D}'s methods are only meaningful on a bounded set:
+ *
+ * - {@link support} — GJK's operand. `argmax(p·d)` over a half-space is at
+ *   infinity for all but one direction, so a plane is not a GJK operand and
+ *   pretending otherwise with a large finite point would silently produce wrong
+ *   contact manifolds rather than a loud failure. Left unimplemented, which
+ *   makes the base class's `Not Implemented` the answer.
+ * - {@link sample_random_point_in_volume} — the base class's rejection sampler
+ *   needs a finite bounding box. There is no uniform distribution on an
+ *   infinite volume.
+ * - {@link volume} and {@link surface_area} — both `Infinity`, stated rather
+ *   than thrown, because a caller summing volumes gets an answer that is true.
+ *
+ * {@link compute_bounding_box} **does** answer, with `±Infinity` on the
+ * unbounded axes. That is what the set is. A consumer that cannot hold an
+ * infinite AABB — a BVH leaf, a broadphase grid — must not be handed a plane,
+ * and the cloth collider index that motivated this shape derives a plane's
+ * bounds from its normal rather than by projecting this box (`aabb3_matrix4_project`
+ * would multiply an infinity by a zero matrix element and get `NaN`).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PlaneShape3D extends AbstractShape3D {
+    /**
+     * @param {number} normal_x
+     * @param {number} normal_y
+     * @param {number} normal_z
+     * @param {number} [offset]
+     * @returns {PlaneShape3D}
+     */
+    static from(normal_x: number, normal_y: number, normal_z: number, offset?: number): PlaneShape3D;
+    /**
+     * Outward unit normal, x.
+     * @type {number}
+     */
+    normal_x: number;
+    /**
+     * Outward unit normal, y.
+     * @type {number}
+     */
+    normal_y: number;
+    /**
+     * Outward unit normal, z.
+     * @type {number}
+     */
+    normal_z: number;
+    /**
+     * Distance from the local origin to the boundary plane, along
+     * {@link normal_x}/{@link normal_y}/{@link normal_z}.
+     * @type {number}
+     */
+    offset: number;
+    signed_distance_at_point(point: any): number;
+    signed_distance_gradient_at_point(result: any, point: any): number;
+    nearest_point_on_surface(result: any, reference: any): void;
+    contains_point(point: any): boolean;
+    /**
+     * Ray ↔ half-space, in the shape's local frame. A ray that starts inside
+     * the solid is already in contact and reports a hit at `t = 0` with the
+     * boundary normal, which is the convention every other shape here follows
+     * for an origin inside it.
+     *
+     * @param {Float32Array|number[]} hit
+     * @param {Ray3} ray
+     * @returns {boolean}
+     */
+    raycast(hit: Float32Array | number[], ray: Ray3): boolean;
+    equals(other: any): boolean;
+    /**
+     * Fast type-check marker, following {@link SphereShape3D#isSphereShape3D}. A
+     * consumer that cannot hold an unbounded shape tests this rather than reaching
+     * for `instanceof` across a module boundary.
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isPlaneShape3D: boolean;
+}
+export namespace PlaneShape3D {
+    let GROUND: PlaneShape3D;
+}
+import { AbstractShape3D } from "./AbstractShape3D.js";
+//# sourceMappingURL=PlaneShape3D.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PlaneShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PlaneShape3D.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH;IA2BI;;;;;;OAMG;IACH,sBANW,MAAM,YACN,MAAM,YACN,MAAM,WACN,MAAM,GACJ,YAAY,CAyBxB;IAvDD;;;OAGG;IACH,UAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,UAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,UAFU,MAAM,CAEH;IAEb;;;;OAIG;IACH,QAFU,MAAM,CAEL;IA0CX,6CAKC;IAED,mEAMC;IAED,4DAMC;IAED,oCAEC;IA4BD;;;;;;;;;OASG;IACH,aAJW,YAAY,GAAC,MAAM,EAAE,cAEnB,OAAO,CAkCnB;IAED,4BAMC;IAcL;;;;;;OAMG;IACH,yBAFU,OAAO,CAEoB;CATpC;;gBAcS,YAAY;;gCApPU,sBAAsB"}

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

@@ -0,0 +1,251 @@
+import { assert } from "../../../assert.js";
+import { hash_mix2 } from "../../../math/hash/hash_mix2.js";
+import { hash_mix3 } from "../../../math/hash/hash_mix3.js";
+import { computeHashFloat } from "../../../primitives/numbers/computeHashFloat.js";
+import { AbstractShape3D } from "./AbstractShape3D.js";
+import { sdf3_plane, sdf3_plane_gradient } from "./sdf/sdf3_plane.js";
+
+/**
+ * # An infinite half-space
+ *
+ * The solid is `{ p : n·p − offset ≤ 0 }` — everything on the far side of the
+ * boundary plane from the direction {@link normal} points in. So `normal` is
+ * the **outward** surface normal, exactly as it is for every other shape's
+ * signed-distance gradient, and `offset` is how far along it the boundary sits
+ * from the body's local origin.
+ *
+ * A ground plane is `normal = (0, 1, 0), offset = 0`: solid below, open above.
+ *
+ * ## Why a shape rather than a very large box
+ *
+ * A box standing in for a ground plane has to be large enough that nothing ever
+ * reaches its edge and thin enough that nothing tunnels through it, and those
+ * two requirements pull against each other in `Float32`. It also costs a
+ * six-face field evaluation where the honest answer is one dot product, and its
+ * gradient has creases that the thing it is standing in for does not.
+ *
+ * ## What it deliberately does not implement, and why that is the honest answer
+ *
+ * A half-space is convex and **unbounded**, and three of
+ * {@link AbstractShape3D}'s methods are only meaningful on a bounded set:
+ *
+ * - {@link support} — GJK's operand. `argmax(p·d)` over a half-space is at
+ *   infinity for all but one direction, so a plane is not a GJK operand and
+ *   pretending otherwise with a large finite point would silently produce wrong
+ *   contact manifolds rather than a loud failure. Left unimplemented, which
+ *   makes the base class's `Not Implemented` the answer.
+ * - {@link sample_random_point_in_volume} — the base class's rejection sampler
+ *   needs a finite bounding box. There is no uniform distribution on an
+ *   infinite volume.
+ * - {@link volume} and {@link surface_area} — both `Infinity`, stated rather
+ *   than thrown, because a caller summing volumes gets an answer that is true.
+ *
+ * {@link compute_bounding_box} **does** answer, with `±Infinity` on the
+ * unbounded axes. That is what the set is. A consumer that cannot hold an
+ * infinite AABB — a BVH leaf, a broadphase grid — must not be handed a plane,
+ * and the cloth collider index that motivated this shape derives a plane's
+ * bounds from its normal rather than by projecting this box (`aabb3_matrix4_project`
+ * would multiply an infinity by a zero matrix element and get `NaN`).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PlaneShape3D extends AbstractShape3D {
+
+    /**
+     * Outward unit normal, x.
+     * @type {number}
+     */
+    normal_x = 0;
+
+    /**
+     * Outward unit normal, y.
+     * @type {number}
+     */
+    normal_y = 1;
+
+    /**
+     * Outward unit normal, z.
+     * @type {number}
+     */
+    normal_z = 0;
+
+    /**
+     * Distance from the local origin to the boundary plane, along
+     * {@link normal_x}/{@link normal_y}/{@link normal_z}.
+     * @type {number}
+     */
+    offset = 0;
+
+    /**
+     * @param {number} normal_x
+     * @param {number} normal_y
+     * @param {number} normal_z
+     * @param {number} [offset]
+     * @returns {PlaneShape3D}
+     */
+    static from(normal_x, normal_y, normal_z, offset = 0) {
+        assert.isNumber(normal_x, 'normal_x');
+        assert.isNumber(normal_y, 'normal_y');
+        assert.isNumber(normal_z, 'normal_z');
+        assert.isNumber(offset, 'offset');
+
+        const length = Math.sqrt(normal_x * normal_x + normal_y * normal_y + normal_z * normal_z);
+
+        assert.greaterThan(length, 0, 'plane normal length');
+
+        const r = new PlaneShape3D();
+
+        // Normalised on construction rather than trusted, because every method
+        // below reads the field as a *distance* field and an unnormalised
+        // normal makes all of them wrong by a scale rather than imprecise.
+        const inverse = 1 / length;
+
+        r.normal_x = normal_x * inverse;
+        r.normal_y = normal_y * inverse;
+        r.normal_z = normal_z * inverse;
+        r.offset = offset;
+
+        return r;
+    }
+
+    get volume() {
+        return Infinity;
+    }
+
+    get surface_area() {
+        return Infinity;
+    }
+
+    signed_distance_at_point(point) {
+        return sdf3_plane(
+            point[0], point[1], point[2],
+            this.normal_x, this.normal_y, this.normal_z, this.offset
+        );
+    }
+
+    signed_distance_gradient_at_point(result, point) {
+        return sdf3_plane_gradient(
+            result, 0,
+            point[0], point[1], point[2],
+            this.normal_x, this.normal_y, this.normal_z, this.offset
+        );
+    }
+
+    nearest_point_on_surface(result, reference) {
+        const distance = this.signed_distance_at_point(reference);
+
+        result[0] = reference[0] - this.normal_x * distance;
+        result[1] = reference[1] - this.normal_y * distance;
+        result[2] = reference[2] - this.normal_z * distance;
+    }
+
+    contains_point(point) {
+        return this.signed_distance_at_point(point) < 0;
+    }
+
+    /**
+     * The half-space's own bounds: finite on the one axis the normal is aligned
+     * with when it is axis-aligned, infinite everywhere else. See the class
+     * docblock for what a consumer is expected to do with that.
+     *
+     * @param {number[]|ArrayLike<number>|Float32Array|Float64Array} result
+     */
+    compute_bounding_box(result) {
+        result[0] = -Infinity;
+        result[1] = -Infinity;
+        result[2] = -Infinity;
+        result[3] = Infinity;
+        result[4] = Infinity;
+        result[5] = Infinity;
+
+        // A general normal makes every axis unbounded. An axis-aligned one — the
+        // overwhelmingly common case, and every ground plane — bounds exactly
+        // one of them, and saying so is what lets a caller cull against a floor.
+        if (this.normal_x === 1) { result[3] = this.offset; }
+        else if (this.normal_x === -1) { result[0] = -this.offset; }
+        else if (this.normal_y === 1) { result[4] = this.offset; }
+        else if (this.normal_y === -1) { result[1] = -this.offset; }
+        else if (this.normal_z === 1) { result[5] = this.offset; }
+        else if (this.normal_z === -1) { result[2] = -this.offset; }
+    }
+
+    /**
+     * Ray ↔ half-space, in the shape's local frame. A ray that starts inside
+     * the solid is already in contact and reports a hit at `t = 0` with the
+     * boundary normal, which is the convention every other shape here follows
+     * for an origin inside it.
+     *
+     * @param {Float32Array|number[]} hit
+     * @param {Ray3} ray
+     * @returns {boolean}
+     */
+    raycast(hit, ray) {
+        const nx = this.normal_x;
+        const ny = this.normal_y;
+        const nz = this.normal_z;
+
+        const distance = ray[0] * nx + ray[1] * ny + ray[2] * nz - this.offset;
+
+        const along = ray[3] * nx + ray[4] * ny + ray[5] * nz;
+
+        let t;
+
+        if (distance <= 0) {
+            t = 0;
+        } else if (along >= 0) {
+            // Outside and travelling away from — or exactly along — the plane.
+            return false;
+        } else {
+            t = -distance / along;
+
+            if (t > ray[6]) {
+                return false;
+            }
+        }
+
+        hit[0] = ray[0] + ray[3] * t;
+        hit[1] = ray[1] + ray[4] * t;
+        hit[2] = ray[2] + ray[5] * t;
+        hit[3] = nx;
+        hit[4] = ny;
+        hit[5] = nz;
+
+        return true;
+    }
+
+    equals(other) {
+        return super.equals(other)
+            && this.normal_x === other.normal_x
+            && this.normal_y === other.normal_y
+            && this.normal_z === other.normal_z
+            && this.offset === other.offset;
+    }
+
+    hash() {
+        return hash_mix2(
+            hash_mix3(
+                computeHashFloat(this.normal_x),
+                computeHashFloat(this.normal_y),
+                computeHashFloat(this.normal_z)
+            ),
+            computeHashFloat(this.offset)
+        );
+    }
+}
+
+/**
+ * Fast type-check marker, following {@link SphereShape3D#isSphereShape3D}. A
+ * consumer that cannot hold an unbounded shape tests this rather than reaching
+ * for `instanceof` across a module boundary.
+ * @readonly
+ * @type {boolean}
+ */
+PlaneShape3D.prototype.isPlaneShape3D = true;
+
+/**
+ * The ground: solid below `y = 0`, open above it. Shared and immutable, in the
+ * same spirit as {@link UnitSphereShape3D}`.INSTANCE`.
+ * @type {PlaneShape3D}
+ */
+PlaneShape3D.GROUND = PlaneShape3D.from(0, 1, 0, 0);

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

@@ -3,7 +3,7 @@ import { random_point_in_sphere } from "../../random/random_point_in_sphere.js";
 import { sphere_raycast } from "../sphere/sphere_raycast.js";
 import { v3_length } from "../../vec3/v3_length.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
-import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
+import { sdf3_sphere, sdf3_sphere_gradient } from "./sdf/sdf3_sphere.js";
 
 /**
  * Sphere of arbitrary `radius`, centred at the body's local origin.
@@ -98,11 +98,11 @@ export class SphereShape3D extends AbstractShape3D {
     }
 
     signed_distance_gradient_at_point(result, point) {
-        return compute_signed_distance_gradient_by_sampling(result, this, point);
+        return sdf3_sphere_gradient(result, 0, point[0], point[1], point[2], this.radius);
     }
 
     signed_distance_at_point(point) {
-        return v3_length(point[0], point[1], point[2]) - this.radius;
+        return sdf3_sphere(point[0], point[1], point[2], this.radius);
     }
 
     contains_point(point) {

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

@@ -61,10 +61,9 @@ export class TransformedShape3D extends AbstractShape3D {
      * physics narrowphase — need it, and re-inverting a 4x4 per query to recover something already
      * stored is pure waste.
      *
-     * @readonly
      * @returns {Float32Array|mat4}
      */
-    readonly get inverse_transform(): any;
+    get inverse_transform(): any;
     compute_bounding_box(result: any): void;
     signed_distance_gradient_at_point(result: any, point: any): number;
     signed_distance_at_point(point: any): number;

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

@@ -1 +1 @@
-{"version":3,"file":"TransformedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/TransformedShape3D.js"],"names":[],"mappings":"AAwBA;IAwCI;;;;;OAKG;IACH,wBAHW,eAAe,MADf,MAAM,EAAE,GAAC,YAAY,OAAK,GAExB,kBAAkB,CAS9B;IAED;;;;;OAKG;IACH,uCAJW,eAAe,eACf,MAAM,EAAE,SACR,MAAM,EAAE,sBAiBlB;IAED;;;;OAIG;IACH,iCAHW,eAAe,eACf,MAAM,EAAE,sBAIlB;IAED;;;;;OAKG;IACH,2BAHW,eAAe,SACf,MAAM,EAAE,GAAC,YAAY,OAAK,GAFxB,kBAAkB,CAM9B;IA9FD;;;;OAIG;IACH,iBAAgC;IAEhC;;;;OAIG;IACH,yBAAwC;IAExC;;;;OAIG;IACH,kBAAiB;IAEjB;;;OAGG;IACH,+BAEC;IAqED;;;OAGG;IACH,0CAIC;IAED,yCAEC;IAED;;;;;;;;OAQG;IACH,sCAEC;IAUD,wCAKC;IAED,mEAyDC;IAED,6CAEC;IAED,oCAKC;IAED,kFAIC;IAED,qGAwCC;IAED;;;;OAIG;IACH,cAHW,kBAAkB,GAChB,OAAO,CAOnB;IAQL;;;;;OAKG;IACH,+BAFU,OAAO,CAEgC;CARhD;gCA/R+B,sBAAsB"}
+{"version":3,"file":"TransformedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/TransformedShape3D.js"],"names":[],"mappings":"AAwBA;IAwCI;;;;;OAKG;IACH,wBAHW,eAAe,MADf,MAAM,EAAE,GAAC,YAAY,OAAK,GAExB,kBAAkB,CAS9B;IAED;;;;;OAKG;IACH,uCAJW,eAAe,eACf,MAAM,EAAE,SACR,MAAM,EAAE,sBAiBlB;IAED;;;;OAIG;IACH,iCAHW,eAAe,eACf,MAAM,EAAE,sBAIlB;IAED;;;;;OAKG;IACH,2BAHW,eAAe,SACf,MAAM,EAAE,GAAC,YAAY,OAAK,GAFxB,kBAAkB,CAM9B;IA9FD;;;;OAIG;IACH,iBAAgC;IAEhC;;;;OAIG;IACH,yBAAwC;IAExC;;;;OAIG;IACH,kBAAiB;IAEjB;;;OAGG;IACH,+BAEC;IAqED;;;OAGG;IACH,0CAIC;IAED,yCAEC;IAED;;;;;;;OAOG;IACH,6BAEC;IAUD,wCAKC;IAED,mEAyDC;IAED,6CAEC;IAED,oCAKC;IAED,kFAIC;IAED,qGAwCC;IAED;;;;OAIG;IACH,cAHW,kBAAkB,GAChB,OAAO,CAOnB;IAQL;;;;;OAKG;IACH,+BAFU,OAAO,CAEgC;CARhD;gCA9R+B,sBAAsB"}

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

@@ -139,7 +139,6 @@ export class TransformedShape3D extends AbstractShape3D {
      * physics narrowphase — need it, and re-inverting a 4x4 per query to recover something already
      * stored is pure waste.
      *
-     * @readonly
      * @returns {Float32Array|mat4}
      */
     get inverse_transform() {

package/src/core/geom/3d/shape/json/shape_to_type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shape_to_type.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/json/shape_to_type.js"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,uDAFa,MAAM,CAoBlB"}
+{"version":3,"file":"shape_to_type.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/json/shape_to_type.js"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,uDAFa,MAAM,CAsBlB"}

package/src/core/geom/3d/shape/json/shape_to_type.js

@@ -1,5 +1,6 @@
 import { CapsuleShape3D } from "../CapsuleShape3D.js";
 import { CylinderShape3D } from "../CylinderShape3D.js";
+import { PlaneShape3D } from "../PlaneShape3D.js";
 import { SphereShape3D } from "../SphereShape3D.js";
 import { TransformedShape3D } from "../TransformedShape3D.js";
 import { UnionShape3D } from "../UnionShape3D.js";
@@ -25,6 +26,8 @@ export function shape_to_type(shape) {
         return 'capsule';
     } else if (shape instanceof CylinderShape3D) {
         return 'cylinder';
+    } else if (shape instanceof PlaneShape3D) {
+        return 'plane';
     } else {
         throw new Error('Unsupported shape');
     }

package/src/core/geom/3d/shape/json/type_adapters.d.ts

@@ -44,6 +44,19 @@ export namespace type_adapters {
             height: number;
         };
     }
+    namespace plane {
+        function read({ normal, offset }: {
+            normal: any;
+            offset: any;
+        }): PlaneShape3D;
+        /**
+         * @param {PlaneShape3D} object
+         */
+        function write(object: PlaneShape3D): {
+            normal: number[];
+            offset: number;
+        };
+    }
     namespace transform {
         function read({ transform, subject }: {
             transform: any;
@@ -75,6 +88,7 @@ import { UnitCubeShape3D } from "../UnitCubeShape3D.js";
 import { SphereShape3D } from "../SphereShape3D.js";
 import { CapsuleShape3D } from "../CapsuleShape3D.js";
 import { CylinderShape3D } from "../CylinderShape3D.js";
+import { PlaneShape3D } from "../PlaneShape3D.js";
 import { TransformedShape3D } from "../TransformedShape3D.js";
 import { UnionShape3D } from "../UnionShape3D.js";
 //# sourceMappingURL=type_adapters.d.ts.map

package/src/core/geom/3d/shape/json/type_adapters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type_adapters.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/json/type_adapters.js"],"names":[],"mappings":";;QAYQ,iCAEC;QACD,qBAEC;;;QAGD;;0BAQC;QACD;;WAEG;QACH;;;;UAIC;;;QAGD;;;2BAEC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;;4BAEC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;;+BAIC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;yBAIC;QACD;;;WAGG;QACH;;UAIC;;;gCA9FuB,uBAAuB;8BAHzB,qBAAqB;+BAFpB,sBAAsB;gCACrB,uBAAuB;mCAEpB,0BAA0B;6BAChC,oBAAoB"}
+{"version":3,"file":"type_adapters.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/json/type_adapters.js"],"names":[],"mappings":";;QAaQ,iCAEC;QACD,qBAEC;;;QAGD;;0BAQC;QACD;;WAEG;QACH;;;;UAIC;;;QAGD;;;2BAEC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;;4BAEC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;;yBAEC;QACD;;WAEG;QACH;;;UAKC;;;QAGD;;;+BAIC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;yBAIC;QACD;;;WAGG;QACH;;UAIC;;;gCA5GuB,uBAAuB;8BAHzB,qBAAqB;+BAHpB,sBAAsB;gCACrB,uBAAuB;6BAC1B,oBAAoB;mCAEd,0BAA0B;6BAChC,oBAAoB"}