@woosh/meep-engine 3.22.0 → 3.23.0

package/package.json

@@ -6,7 +6,7 @@
   "description": "Advanced 3D game engine",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.22.0",
+  "version": "3.23.0",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

package/src/core/geom/3d/hash-grid/PointHashGrid3.d.ts

@@ -0,0 +1,118 @@
+/**
+ * # A uniform hash grid over points, rebuilt whole
+ *
+ * Bucket every point by the cell of a uniform grid it falls in, so that "what is
+ * near this point" is a walk over a handful of buckets instead of a scan over
+ * everything. The classic particle broadphase, and the structure a cloth's
+ * self-collision needs (§9, §14.2).
+ *
+ * ## What it takes from `SpatialHashGrid`, and where it deliberately differs
+ *
+ * §14.2 asks for this "modelled on `core/geom/2d/hash-grid/SpatialHashGrid.js`",
+ * and it takes the idea — uniform cells, hashed into a fixed bucket table — and
+ * not the structure, because the two answer different questions.
+ *
+ * `SpatialHashGrid` is a **persistent index of boxes**: an element carries an
+ * AABB, spans several cells, is allocated and freed individually, and lives in a
+ * singly-linked list per cell so that moving one element touches only that
+ * element. That is right for a world index whose contents change a few at a time
+ * and wrong for this: a cloth's particles *all* move every step, so every link
+ * would be relinked, and the pointer chase through a linked list is the worst
+ * possible access pattern for a loop that is going to visit every bucket anyway.
+ *
+ * This is instead a **counting sort, rebuilt whole**: two passes over the points
+ * to count and scatter, and a bucket is then a contiguous run of point indices.
+ * Rebuilding is O(n) with no allocation after the first sizing, and the walk is
+ * sequential. A point is a point rather than a box, so it lands in exactly one
+ * cell and nothing is emitted twice.
+ *
+ * ## Hash collisions are the caller's problem, and that is the trade
+ *
+ * The bucket table is a power of two and cell coordinates are hashed into it, so
+ * two distant cells can share a bucket and a query can hand back a point that is
+ * nowhere near. **Every caller has to check the actual distance**, which is not a
+ * cost because every caller was going to: a broadphase answers "maybe", and the
+ * narrow phase is a subtraction and a dot product.
+ *
+ * What the hash buys is that the grid needs no extent. A dense grid over a
+ * garment's bounds would have to be resized whenever the garment moved or grew,
+ * and a garment that teleports a kilometre would size it into the gigabytes.
+ *
+ * What a caller does **not** have to handle is a point arriving twice.
+ * `SpatialHashGrid` documents duplicate emission as the caller's problem because
+ * its elements are boxes and a box genuinely occupies several cells; here a point
+ * occupies one, and the only way it could be emitted twice is the 27-cell walk
+ * visiting one bucket more than once because two of those cells collided into it.
+ * {@link forEachNear} skips a bucket it has already visited, which is a scan over
+ * at most 27 numbers and removes the whole class.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PointHashGrid3 {
+    /**
+     * Side of one cell. Points closer than this are in the same cell or an
+     * adjacent one, which is what makes {@link forEachNear}'s 27-cell walk the
+     * whole of the broadphase.
+     * @type {number}
+     */
+    cell_size: number;
+    /**
+     * Points in the grid.
+     * @type {number}
+     */
+    count: number;
+    /**
+     * Start of each bucket in {@link point}, `bucket_count + 1` entries. Bucket
+     * `b` is `point[offset[b] .. offset[b + 1])`.
+     *
+     * Public because the inner loop that motivated this class walks buckets
+     * directly rather than through {@link forEachNear}, and a private field with
+     * an accessor in front of it would put a call in that loop.
+     * @type {Int32Array}
+     */
+    offset: Int32Array;
+    /**
+     * Point indices, bucket-major.
+     * @type {Int32Array}
+     */
+    point: Int32Array;
+    /**
+     * How many buckets the table has. A power of two, so hashing is a mask.
+     * @returns {number}
+     */
+    get bucketCount(): number;
+    /**
+     * Rebuild the grid from a flat position array.
+     *
+     * @param {Float32Array|Float64Array} position 3 per point
+     * @param {number} count points
+     * @param {number} cell_size metres
+     * @returns {void}
+     */
+    build(position: Float32Array | Float64Array, count: number, cell_size: number): void;
+    /**
+     * Call `visit(index)` for every point in the 27 cells around `(x, y, z)`.
+     *
+     * Points from other cells may be handed back — see the class docblock on
+     * hash collisions — and the visitor is expected to check the distance.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {function(number): void} visit
+     * @returns {void}
+     */
+    forEachNear(x: number, y: number, z: number, visit: (arg0: number) => void): void;
+    /**
+     * The bucket a cell falls in. For a caller walking buckets itself.
+     *
+     * @param {number} cx cell coordinate
+     * @param {number} cy
+     * @param {number} cz
+     * @returns {number}
+     */
+    bucketOf(cx: number, cy: number, cz: number): number;
+    #private;
+}
+//# sourceMappingURL=PointHashGrid3.d.ts.map

package/src/core/geom/3d/hash-grid/PointHashGrid3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PointHashGrid3.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/hash-grid/PointHashGrid3.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH;IAEI;;;;;OAKG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;;;OAQG;IACH,QAFU,UAAU,CAEO;IAE3B;;;OAGG;IACH,OAFU,UAAU,CAEM;IAQ1B;;;OAGG;IACH,0BAEC;IAED;;;;;;;OAOG;IACH,gBALW,YAAY,GAAC,YAAY,SACzB,MAAM,aACN,MAAM,GACJ,IAAI,CA0EhB;IAED;;;;;;;;;;;OAWG;IACH,eANW,MAAM,KACN,MAAM,KACN,MAAM,gBACG,MAAM,KAAG,IAAI,GACpB,IAAI,CAiDhB;IAED;;;;;;;OAOG;IACH,aALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAIlB;;CACJ"}

package/src/core/geom/3d/hash-grid/PointHashGrid3.js

@@ -0,0 +1,283 @@
+import { assert } from "../../../assert.js";
+
+/**
+ * # A uniform hash grid over points, rebuilt whole
+ *
+ * Bucket every point by the cell of a uniform grid it falls in, so that "what is
+ * near this point" is a walk over a handful of buckets instead of a scan over
+ * everything. The classic particle broadphase, and the structure a cloth's
+ * self-collision needs (§9, §14.2).
+ *
+ * ## What it takes from `SpatialHashGrid`, and where it deliberately differs
+ *
+ * §14.2 asks for this "modelled on `core/geom/2d/hash-grid/SpatialHashGrid.js`",
+ * and it takes the idea — uniform cells, hashed into a fixed bucket table — and
+ * not the structure, because the two answer different questions.
+ *
+ * `SpatialHashGrid` is a **persistent index of boxes**: an element carries an
+ * AABB, spans several cells, is allocated and freed individually, and lives in a
+ * singly-linked list per cell so that moving one element touches only that
+ * element. That is right for a world index whose contents change a few at a time
+ * and wrong for this: a cloth's particles *all* move every step, so every link
+ * would be relinked, and the pointer chase through a linked list is the worst
+ * possible access pattern for a loop that is going to visit every bucket anyway.
+ *
+ * This is instead a **counting sort, rebuilt whole**: two passes over the points
+ * to count and scatter, and a bucket is then a contiguous run of point indices.
+ * Rebuilding is O(n) with no allocation after the first sizing, and the walk is
+ * sequential. A point is a point rather than a box, so it lands in exactly one
+ * cell and nothing is emitted twice.
+ *
+ * ## Hash collisions are the caller's problem, and that is the trade
+ *
+ * The bucket table is a power of two and cell coordinates are hashed into it, so
+ * two distant cells can share a bucket and a query can hand back a point that is
+ * nowhere near. **Every caller has to check the actual distance**, which is not a
+ * cost because every caller was going to: a broadphase answers "maybe", and the
+ * narrow phase is a subtraction and a dot product.
+ *
+ * What the hash buys is that the grid needs no extent. A dense grid over a
+ * garment's bounds would have to be resized whenever the garment moved or grew,
+ * and a garment that teleports a kilometre would size it into the gigabytes.
+ *
+ * What a caller does **not** have to handle is a point arriving twice.
+ * `SpatialHashGrid` documents duplicate emission as the caller's problem because
+ * its elements are boxes and a box genuinely occupies several cells; here a point
+ * occupies one, and the only way it could be emitted twice is the 27-cell walk
+ * visiting one bucket more than once because two of those cells collided into it.
+ * {@link forEachNear} skips a bucket it has already visited, which is a scan over
+ * at most 27 numbers and removes the whole class.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PointHashGrid3 {
+
+    /**
+     * Side of one cell. Points closer than this are in the same cell or an
+     * adjacent one, which is what makes {@link forEachNear}'s 27-cell walk the
+     * whole of the broadphase.
+     * @type {number}
+     */
+    cell_size = 1;
+
+    /**
+     * Points in the grid.
+     * @type {number}
+     */
+    count = 0;
+
+    /**
+     * Start of each bucket in {@link point}, `bucket_count + 1` entries. Bucket
+     * `b` is `point[offset[b] .. offset[b + 1])`.
+     *
+     * Public because the inner loop that motivated this class walks buckets
+     * directly rather than through {@link forEachNear}, and a private field with
+     * an accessor in front of it would put a call in that loop.
+     * @type {Int32Array}
+     */
+    offset = new Int32Array(1);
+
+    /**
+     * Point indices, bucket-major.
+     * @type {Int32Array}
+     */
+    point = new Int32Array(0);
+
+    /**
+     * @type {number}
+     * @private
+     */
+    #bucket_count = 0;
+
+    /**
+     * How many buckets the table has. A power of two, so hashing is a mask.
+     * @returns {number}
+     */
+    get bucketCount() {
+        return this.#bucket_count;
+    }
+
+    /**
+     * Rebuild the grid from a flat position array.
+     *
+     * @param {Float32Array|Float64Array} position 3 per point
+     * @param {number} count points
+     * @param {number} cell_size metres
+     * @returns {void}
+     */
+    build(position, count, cell_size) {
+        assert.isFinite(cell_size, 'cell_size');
+        assert.greaterThan(cell_size, 0, 'cell_size');
+
+        this.cell_size = cell_size;
+        this.count = count;
+
+        // One bucket per point, rounded up to a power of two, so the mean
+        // occupancy is about one and the table is never a rounding error next to
+        // the points it indexes.
+        let buckets = 16;
+
+        while (buckets < count) {
+            buckets *= 2;
+        }
+
+        if (buckets !== this.#bucket_count) {
+            this.#bucket_count = buckets;
+            this.offset = new Int32Array(buckets + 1);
+        } else {
+            this.offset.fill(0);
+        }
+
+        if (this.point.length < count) {
+            this.point = new Int32Array(count);
+        }
+
+        const offset = this.offset;
+        const mask = buckets - 1;
+
+        const inverse = 1 / cell_size;
+
+        for (let i = 0; i < count; i++) {
+            const p = i * 3;
+
+            const bucket = hash(
+                Math.floor(position[p] * inverse),
+                Math.floor(position[p + 1] * inverse),
+                Math.floor(position[p + 2] * inverse)
+            ) & mask;
+
+            offset[bucket + 1]++;
+        }
+
+        for (let b = 0; b < buckets; b++) {
+            offset[b + 1] += offset[b];
+        }
+
+        // The scatter needs a moving cursor per bucket, and the offsets are the
+        // starting cursors — so the pass below consumes them and the loop after
+        // it puts them back rather than keeping a second array of the same size.
+        const point = this.point;
+
+        for (let i = 0; i < count; i++) {
+            const p = i * 3;
+
+            const bucket = hash(
+                Math.floor(position[p] * inverse),
+                Math.floor(position[p + 1] * inverse),
+                Math.floor(position[p + 2] * inverse)
+            ) & mask;
+
+            point[offset[bucket]++] = i;
+        }
+
+        // Undo the cursor advance: `offset[b]` ran up to `offset[b + 1]`, so
+        // shifting the array back down by one restores the starts.
+        for (let b = buckets; b > 0; b--) {
+            offset[b] = offset[b - 1];
+        }
+
+        offset[0] = 0;
+    }
+
+    /**
+     * Call `visit(index)` for every point in the 27 cells around `(x, y, z)`.
+     *
+     * Points from other cells may be handed back — see the class docblock on
+     * hash collisions — and the visitor is expected to check the distance.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {function(number): void} visit
+     * @returns {void}
+     */
+    forEachNear(x, y, z, visit) {
+        const inverse = 1 / this.cell_size;
+
+        const cx = Math.floor(x * inverse);
+        const cy = Math.floor(y * inverse);
+        const cz = Math.floor(z * inverse);
+
+        const mask = this.#bucket_count - 1;
+
+        const offset = this.offset;
+        const point = this.point;
+
+        let visited = 0;
+
+        for (let dz = -1; dz <= 1; dz++) {
+            for (let dy = -1; dy <= 1; dy++) {
+                for (let dx = -1; dx <= 1; dx++) {
+                    const bucket = hash(cx + dx, cy + dy, cz + dz) & mask;
+
+                    // Two of the 27 cells can hash to one bucket — most easily on
+                    // a small table, where there are fewer buckets than cells in
+                    // the neighbourhood — and visiting it twice would hand every
+                    // point in it back twice.
+                    let seen = false;
+
+                    for (let i = 0; i < visited; i++) {
+                        if (VISITED[i] === bucket) {
+                            seen = true;
+
+                            break;
+                        }
+                    }
+
+                    if (seen) {
+                        continue;
+                    }
+
+                    VISITED[visited++] = bucket;
+
+                    const end = offset[bucket + 1];
+
+                    for (let at = offset[bucket]; at < end; at++) {
+                        visit(point[at]);
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * The bucket a cell falls in. For a caller walking buckets itself.
+     *
+     * @param {number} cx cell coordinate
+     * @param {number} cy
+     * @param {number} cz
+     * @returns {number}
+     */
+    bucketOf(cx, cy, cz) {
+        return hash(cx, cy, cz) & (this.#bucket_count - 1);
+    }
+}
+
+/**
+ * The buckets one {@link PointHashGrid3#forEachNear} has already visited — at
+ * most 27, so a linear scan is the whole of the de-duplication. Module scratch
+ * because a query allocates nothing, and safe because a query does not nest: the
+ * visitor is called with a point index and has no reason to start another walk.
+ * @type {Int32Array}
+ * @private
+ */
+const VISITED = new Int32Array(27);
+
+/**
+ * Teschner's spatial hash — three large primes, one exclusive-or, which is the
+ * one every particle system in the literature uses because it is cheap and its
+ * collisions are uncorrelated with the lattice.
+ *
+ * `Math.imul` rather than `*` because the products overflow 32 bits and JavaScript
+ * would carry them into doubles, losing the low bits that are the hash.
+ *
+ * @param {number} x cell coordinate, integer
+ * @param {number} y
+ * @param {number} z
+ * @returns {number} a non-negative int32
+ * @private
+ */
+function hash(x, y, z) {
+    return (Math.imul(x, 73856093) ^ Math.imul(y, 19349663) ^ Math.imul(z, 83492791)) >>> 0;
+}

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":"AAcA;;;;;;;;;;;;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,mEAEC;IAED,6CAaC;IAED,oCAQC;IAED,kFAOC;IAED;;;OAGG;IACH,cAHW,UAAU,GACR,OAAO,CAInB;IAWL;;;;;;OAMG;IACH,uBAFU,OAAO,CAEgB;CAThC;gCAtJ+B,sBAAsB;oBAVlC,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,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"}

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