@woosh/meep-engine 2.143.0 → 2.145.0

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.143.0",
+  "version": "2.145.0",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/bvh2/bvh3/BVH.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BVH.d.ts","sourceRoot":"","sources":["../../../../../src/core/bvh2/bvh3/BVH.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"BVH.d.ts","sourceRoot":"","sources":["../../../../../src/core/bvh2/bvh3/BVH.js"],"names":[],"mappings":"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"}

package/src/core/bvh2/bvh3/BVH.js

@@ -800,7 +800,14 @@ export class BVH {
         const uint32 = this.__data_uint32;
 
         while (index !== NULL_NODE) {
-            index = this.balance(index);
+            // SAH-reducing rotation (Box2D v3 style) — keeps query cost near the
+            // SAH optimum. {@link balance_height} (pure height-AVL) is kept as
+            // the alternative. The tree shape this produces differs from the
+            // height-balanced one, which (because the contact solver's order
+            // follows broadphase traversal order) shifts Gauss-Seidel
+            // convergence on near-aligned stacks — see the BVH balance note in
+            // engine/physics/PLAN.md.
+            index = this.balance_rotate(index);
 
             const node_address = index * ELEMENT_WORD_COUNT;
 
@@ -875,13 +882,18 @@ export class BVH {
     }
 
     /**
-     * Perform a left or right rotation if node A is imbalanced.
-     * Returns the new root index.
+     * **Height-balancing** rotation (Box2D v2 `b2DynamicTree::Balance`): if the
+     * two subtrees of node A differ in height by more than one, rotate the
+     * taller grandchild up. Keeps the tree height ≤ O(log N) but is chosen
+     * purely on *height* — it does not consider surface area, so the result is
+     * height-balanced yet not SAH-balanced (query cost can stay 1.3–2× above an
+     * SAH-optimal tree). See {@link balance_rotate} for the SAH-driven variant.
+     * Returns the (possibly new) subtree-root index.
      * @param {number} iA
      * @returns {number}
      * @private
      */
-    balance(iA) {
+    balance_height(iA) {
         assert.notEqual(iA, NULL_NODE, 'input is a null node');
 
         //b2TreeNode* A = m_nodes + iA;
@@ -1079,6 +1091,148 @@ export class BVH {
         return iA;
     }
 
+    /**
+     * **SAH-reducing** rotation (Kensler 2008 / Box2D v3 `b2RotateNodes`). For
+     * node A with children B, C, consider the four ways to swap a child of A
+     * with a grandchild (a child of the other child); each rotation re-forms
+     * exactly one internal node and changes the tree's total surface-area
+     * (SAH) cost by `area(old child) − area(new child)`. Apply the swap with
+     * the largest positive reduction, or none if no swap helps.
+     *
+     * Unlike {@link balance_height} the subtree root A never moves (so the
+     * return value is always `iA`), and the criterion is *surface area*, not
+     * height — keeping query cost near the SAH optimum. Height is not an
+     * explicit invariant here, but SAH-good trees stay well-shaped for
+     * spatially-distributed data (this is what modern Box2D ships).
+     *
+     * Deterministic: a pure function of the current tree state.
+     *
+     * @param {number} iA
+     * @returns {number} always `iA` (the subtree root is unchanged)
+     * @private
+     */
+    balance_rotate(iA) {
+        assert.notEqual(iA, NULL_NODE, 'input is a null node');
+
+        const uint32 = this.__data_uint32;
+        const a_addr = iA * ELEMENT_WORD_COUNT;
+
+        if (this.node_is_leaf(iA) || uint32[a_addr + COLUMN_HEIGHT] < 2) {
+            return iA;
+        }
+
+        const iB = uint32[a_addr + COLUMN_CHILD_1];
+        const iC = uint32[a_addr + COLUMN_CHILD_2];
+
+        const b_leaf = this.node_is_leaf(iB);
+        const c_leaf = this.node_is_leaf(iC);
+
+        // Largest beneficial SAH reduction found so far. Strictly positive, so a
+        // zero-improvement (or worse) configuration leaves the tree untouched —
+        // no churn, and deterministic.
+        let best_improvement = 0;
+        let best_rotation = 0; // 1..4, 0 = keep as-is
+
+        let iD = NULL_NODE, iE = NULL_NODE, iF = NULL_NODE, iG = NULL_NODE;
+
+        if (!b_leaf) {
+            // B is internal with children D, E. Moving C down into B (and a
+            // grandchild D/E up to A) re-forms B; the only changed area is B's.
+            const area_b = this.node_get_surface_area(iB);
+            iD = uint32[iB * ELEMENT_WORD_COUNT + COLUMN_CHILD_1];
+            iE = uint32[iB * ELEMENT_WORD_COUNT + COLUMN_CHILD_2];
+
+            // Rotation 1 — swap C and D → B = (C, E), A = (B, D).
+            const imp1 = area_b - this.node_get_combined_surface_area(iC, iE);
+            if (imp1 > best_improvement) { best_improvement = imp1; best_rotation = 1; }
+
+            // Rotation 2 — swap C and E → B = (D, C), A = (B, E).
+            const imp2 = area_b - this.node_get_combined_surface_area(iD, iC);
+            if (imp2 > best_improvement) { best_improvement = imp2; best_rotation = 2; }
+        }
+
+        if (!c_leaf) {
+            // C is internal with children F, G. Symmetric: re-forms C.
+            const area_c = this.node_get_surface_area(iC);
+            iF = uint32[iC * ELEMENT_WORD_COUNT + COLUMN_CHILD_1];
+            iG = uint32[iC * ELEMENT_WORD_COUNT + COLUMN_CHILD_2];
+
+            // Rotation 3 — swap B and F → C = (B, G), A = (F, C).
+            const imp3 = area_c - this.node_get_combined_surface_area(iB, iG);
+            if (imp3 > best_improvement) { best_improvement = imp3; best_rotation = 3; }
+
+            // Rotation 4 — swap B and G → C = (F, B), A = (G, C).
+            const imp4 = area_c - this.node_get_combined_surface_area(iF, iB);
+            if (imp4 > best_improvement) { best_improvement = imp4; best_rotation = 4; }
+        }
+
+        if (best_rotation === 0) {
+            return iA; // no beneficial rotation
+        }
+
+        // Apply the chosen rotation: re-wire one child↔grandchild pair, then
+        // refresh the re-formed internal node's AABB + height. A's AABB / height
+        // are recomputed by the caller (bubble_up_update) after we return, but
+        // we also set A's height here so the subtree is self-consistent.
+        switch (best_rotation) {
+            case 1: { // swap C and D: B = (C, E), A = (B, D)
+                uint32[a_addr + COLUMN_CHILD_2] = iD;
+                uint32[iB * ELEMENT_WORD_COUNT + COLUMN_CHILD_1] = iC;
+                uint32[iD * ELEMENT_WORD_COUNT + COLUMN_PARENT] = iA;
+                uint32[iC * ELEMENT_WORD_COUNT + COLUMN_PARENT] = iB;
+                this.node_set_combined_aabb(iB, iC, iE);
+                uint32[iB * ELEMENT_WORD_COUNT + COLUMN_HEIGHT] = 1 + max2(
+                    uint32[iC * ELEMENT_WORD_COUNT + COLUMN_HEIGHT],
+                    uint32[iE * ELEMENT_WORD_COUNT + COLUMN_HEIGHT]
+                );
+                break;
+            }
+            case 2: { // swap C and E: B = (D, C), A = (B, E)
+                uint32[a_addr + COLUMN_CHILD_2] = iE;
+                uint32[iB * ELEMENT_WORD_COUNT + COLUMN_CHILD_2] = iC;
+                uint32[iE * ELEMENT_WORD_COUNT + COLUMN_PARENT] = iA;
+                uint32[iC * ELEMENT_WORD_COUNT + COLUMN_PARENT] = iB;
+                this.node_set_combined_aabb(iB, iD, iC);
+                uint32[iB * ELEMENT_WORD_COUNT + COLUMN_HEIGHT] = 1 + max2(
+                    uint32[iD * ELEMENT_WORD_COUNT + COLUMN_HEIGHT],
+                    uint32[iC * ELEMENT_WORD_COUNT + COLUMN_HEIGHT]
+                );
+                break;
+            }
+            case 3: { // swap B and F: C = (B, G), A = (F, C)
+                uint32[a_addr + COLUMN_CHILD_1] = iF;
+                uint32[iC * ELEMENT_WORD_COUNT + COLUMN_CHILD_1] = iB;
+                uint32[iF * ELEMENT_WORD_COUNT + COLUMN_PARENT] = iA;
+                uint32[iB * ELEMENT_WORD_COUNT + COLUMN_PARENT] = iC;
+                this.node_set_combined_aabb(iC, iB, iG);
+                uint32[iC * ELEMENT_WORD_COUNT + COLUMN_HEIGHT] = 1 + max2(
+                    uint32[iB * ELEMENT_WORD_COUNT + COLUMN_HEIGHT],
+                    uint32[iG * ELEMENT_WORD_COUNT + COLUMN_HEIGHT]
+                );
+                break;
+            }
+            case 4: { // swap B and G: C = (F, B), A = (G, C)
+                uint32[a_addr + COLUMN_CHILD_1] = iG;
+                uint32[iC * ELEMENT_WORD_COUNT + COLUMN_CHILD_2] = iB;
+                uint32[iG * ELEMENT_WORD_COUNT + COLUMN_PARENT] = iA;
+                uint32[iB * ELEMENT_WORD_COUNT + COLUMN_PARENT] = iC;
+                this.node_set_combined_aabb(iC, iF, iB);
+                uint32[iC * ELEMENT_WORD_COUNT + COLUMN_HEIGHT] = 1 + max2(
+                    uint32[iF * ELEMENT_WORD_COUNT + COLUMN_HEIGHT],
+                    uint32[iB * ELEMENT_WORD_COUNT + COLUMN_HEIGHT]
+                );
+                break;
+            }
+        }
+
+        uint32[a_addr + COLUMN_HEIGHT] = 1 + max2(
+            uint32[uint32[a_addr + COLUMN_CHILD_1] * ELEMENT_WORD_COUNT + COLUMN_HEIGHT],
+            uint32[uint32[a_addr + COLUMN_CHILD_2] * ELEMENT_WORD_COUNT + COLUMN_HEIGHT]
+        );
+
+        return iA;
+    }
+
     /**
      * Utility method for assigning both children at once
      * Children must be valid nodes (non-null)

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

@@ -0,0 +1,56 @@
+/**
+ * A solid right circular cylinder aligned with the Y axis, centred at the local
+ * origin. A disk of {@link radius} extruded along Y for {@link height}, so it
+ * spans `y ∈ [-height/2, +height/2]` with **flat** circular caps (the capsule's
+ * flat-cap sibling — same radius/height parametrisation, hemispherical caps
+ * replaced by disks).
+ *
+ * Convex, so the physics narrowphase handles it through the GJK + EPA fallback
+ * via {@link support} — there is no closed-form cylinder-vs-X contact path yet
+ * (a future refinement; the curved side is the usual smooth-support EPA case).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class CylinderShape3D extends AbstractShape3D {
+    /**
+     * @param {number} radius
+     * @param {number} height
+     * @returns {CylinderShape3D}
+     */
+    static from(radius: number, height: number): CylinderShape3D;
+    /**
+     * Radius of the circular cross-section.
+     * @type {number}
+     */
+    radius: number;
+    /**
+     * Full height along the Y axis (total extent — the cylinder spans
+     * `[-height/2, +height/2]`).
+     * @type {number}
+     */
+    height: number;
+    compute_bounding_box(result: any): void;
+    support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    signed_distance_at_point(point: any): number;
+    signed_distance_gradient_at_point(result: any, point: any): number;
+    contains_point(point: any): boolean;
+    nearest_point_on_surface(result: any, reference: any): void;
+    sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
+    /**
+     * @param {CylinderShape3D} other
+     * @returns {boolean}
+     */
+    equals(other: CylinderShape3D): boolean;
+    /**
+     * Fast type-check marker, mirroring `isSphereShape3D` / `isBoxShape3D` /
+     * `isCapsuleShape3D`. Reserved for a future closed-form cylinder narrowphase
+     * dispatch; until then the cylinder routes through GJK + EPA like any other
+     * convex shape (no marker check needed for that path).
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isCylinderShape3D: boolean;
+}
+import { AbstractShape3D } from "./AbstractShape3D.js";
+//# sourceMappingURL=CylinderShape3D.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CylinderShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/CylinderShape3D.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;GAaG;AACH;IAkBI;;;;OAIG;IACH,oBAJW,MAAM,UACN,MAAM,GACJ,eAAe,CAa3B;IA9BG;;;OAGG;IACH,QAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,QAFU,MAAM,CAED;IAgCnB,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;gCA/M+B,sBAAsB"}

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

@@ -0,0 +1,223 @@
+import { assert } from "../../../assert.js";
+import { clamp } from "../../../math/clamp.js";
+import { sign_not_zero } from "../../../math/sign_not_zero.js";
+import { computeHashFloat } from "../../../primitives/numbers/computeHashFloat.js";
+import { randomPointInCircle } from "../../random/randomPointInCircle.js";
+import { AbstractShape3D } from "./AbstractShape3D.js";
+import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
+
+const scratch_v3 = [0, 0, 0];
+
+/**
+ * A solid right circular cylinder aligned with the Y axis, centred at the local
+ * origin. A disk of {@link radius} extruded along Y for {@link height}, so it
+ * spans `y ∈ [-height/2, +height/2]` with **flat** circular caps (the capsule's
+ * flat-cap sibling — same radius/height parametrisation, hemispherical caps
+ * replaced by disks).
+ *
+ * Convex, so the physics narrowphase handles it through the GJK + EPA fallback
+ * via {@link support} — there is no closed-form cylinder-vs-X contact path yet
+ * (a future refinement; the curved side is the usual smooth-support EPA case).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class CylinderShape3D extends AbstractShape3D {
+    constructor() {
+        super();
+
+        /**
+         * Radius of the circular cross-section.
+         * @type {number}
+         */
+        this.radius = 0.5;
+
+        /**
+         * Full height along the Y axis (total extent — the cylinder spans
+         * `[-height/2, +height/2]`).
+         * @type {number}
+         */
+        this.height = 1;
+    }
+
+    /**
+     * @param {number} radius
+     * @param {number} height
+     * @returns {CylinderShape3D}
+     */
+    static from(radius, height) {
+        assert.isNumber(radius, 'radius');
+        assert.isNumber(height, 'height');
+        assert.greaterThanOrEqual(radius, 0, 'radius');
+        assert.greaterThanOrEqual(height, 0, 'height');
+
+        const r = new CylinderShape3D();
+        r.radius = radius;
+        r.height = height;
+
+        return r;
+    }
+
+    get volume() {
+        const r = this.radius;
+        return Math.PI * r * r * this.height;
+    }
+
+    get surface_area() {
+        const r = this.radius;
+        // two circular caps + the lateral (side) surface
+        return 2 * Math.PI * r * r + 2 * Math.PI * r * this.height;
+    }
+
+    compute_bounding_box(result) {
+        const r = this.radius;
+        const half_h = this.height / 2;
+
+        result[0] = -r;
+        result[1] = -half_h;
+        result[2] = -r;
+        result[3] = r;
+        result[4] = half_h;
+        result[5] = r;
+    }
+
+    support(result, result_offset, direction_x, direction_y, direction_z) {
+        const r = this.radius;
+        const half_h = this.height / 2;
+
+        // Radial: farthest point on the cross-section disk along (dx, dz). For a
+        // purely axial query (rl ≈ 0) any point on the cap face is extremal —
+        // the cap centre (0,0) is on the (flat) surface, so it's a valid support.
+        const rl = Math.sqrt(direction_x * direction_x + direction_z * direction_z);
+        let sx = 0, sz = 0;
+        if (rl > 0) {
+            const inv = r / rl;
+            sx = direction_x * inv;
+            sz = direction_z * inv;
+        }
+
+        // Axial: the cap on the +direction.y side.
+        const sy = sign_not_zero(direction_y) * half_h;
+
+        result[result_offset] = sx;
+        result[result_offset + 1] = sy;
+        result[result_offset + 2] = sz;
+    }
+
+    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;
+    }
+
+    signed_distance_gradient_at_point(result, point) {
+        return compute_signed_distance_gradient_by_sampling(result, this, point);
+    }
+
+    contains_point(point) {
+        const px = point[0];
+        const py = point[1];
+        const pz = point[2];
+
+        const half_h = this.height / 2;
+        const r = this.radius;
+
+        return (px * px + pz * pz) < r * r && (py < half_h) && (py > -half_h);
+    }
+
+    nearest_point_on_surface(result, reference) {
+        const rx = reference[0];
+        const ry = reference[1];
+        const rz = reference[2];
+
+        const r = this.radius;
+        const half_h = this.height / 2;
+
+        const rho = Math.sqrt(rx * rx + rz * rz);
+        let dirx, dirz;
+        if (rho > 0) {
+            dirx = rx / rho;
+            dirz = rz / rho;
+        } else {
+            // On the axis — radial direction is undefined; pick +X.
+            dirx = 1;
+            dirz = 0;
+        }
+
+        // Three candidate projections; the nearest to the reference is the
+        // closest surface point (correct for points inside and outside).
+        //   1. side    — radial clamped to r, y clamped to the band
+        //   2. top cap — y = +half_h, radial clamped to r
+        //   3. bot cap — y = -half_h, radial clamped to r
+        const cy = clamp(ry, -half_h, half_h);
+        const s1x = r * dirx, s1y = cy, s1z = r * dirz;
+
+        const rc = rho < r ? rho : r;
+        const s2x = rc * dirx, s2y = half_h, s2z = rc * dirz;
+        const s3x = rc * dirx, s3y = -half_h, s3z = rc * dirz;
+
+        const d1 = (s1x - rx) * (s1x - rx) + (s1y - ry) * (s1y - ry) + (s1z - rz) * (s1z - rz);
+        const d2 = (s2x - rx) * (s2x - rx) + (s2y - ry) * (s2y - ry) + (s2z - rz) * (s2z - rz);
+        const d3 = (s3x - rx) * (s3x - rx) + (s3y - ry) * (s3y - ry) + (s3z - rz) * (s3z - rz);
+
+        if (d1 <= d2 && d1 <= d3) {
+            result[0] = s1x; result[1] = s1y; result[2] = s1z;
+        } else if (d2 <= d3) {
+            result[0] = s2x; result[1] = s2y; result[2] = s2z;
+        } else {
+            result[0] = s3x; result[1] = s3y; result[2] = s3z;
+        }
+    }
+
+    sample_random_point_in_volume(result, result_offset, random) {
+        // Uniform in the disk (sqrt-weighted radius) × uniform in y.
+        randomPointInCircle(random, scratch_v3, 0);
+
+        result[result_offset] = scratch_v3[0] * this.radius;
+        result[result_offset + 1] = (random() - 0.5) * this.height;
+        result[result_offset + 2] = scratch_v3[1] * this.radius;
+    }
+
+    /**
+     * @param {CylinderShape3D} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return super.equals(other)
+            && this.radius === other.radius
+            && this.height === other.height;
+    }
+
+    hash() {
+        const a = computeHashFloat(this.radius);
+        const b = computeHashFloat(this.height);
+
+        return ((a << 5) - a + b) | 0;
+    }
+}
+
+/**
+ * Fast type-check marker, mirroring `isSphereShape3D` / `isBoxShape3D` /
+ * `isCapsuleShape3D`. Reserved for a future closed-form cylinder narrowphase
+ * dispatch; until then the cylinder routes through GJK + EPA like any other
+ * convex shape (no marker check needed for that path).
+ * @readonly
+ * @type {boolean}
+ */
+CylinderShape3D.prototype.isCylinderShape3D = true;

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

@@ -9,6 +9,7 @@ export class PointShape3D extends AbstractShape3D {
     nearest_point_on_surface(result: any, reference: any): void;
     sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
     support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    equals(other: any): boolean;
 }
 import { AbstractShape3D } from "./AbstractShape3D.js";
 //# sourceMappingURL=PointShape3D.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"PointShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PointShape3D.js"],"names":[],"mappings":"AAGA;;GAEG;AACH;IA4CI,8BAAqC;IAnCrC,wCAOC;IAED,6CAEC;IAED,oCAEC;IAED,4DAIC;IAED,kFAIC;IAED,qGAIC;CAGJ;gCAlD+B,sBAAsB"}
+{"version":3,"file":"PointShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PointShape3D.js"],"names":[],"mappings":"AAGA;;GAEG;AACH;IAuDI,8BAAqC;IA9CrC,wCAOC;IAED,6CAEC;IAED,oCAEC;IAED,4DAIC;IAED,kFAIC;IAED,qGAIC;IAED,4BAGC;CASJ;gCA7D+B,sBAAsB"}

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

@@ -48,5 +48,16 @@ export class PointShape3D extends AbstractShape3D {
         result[result_offset + 2] = 0;
     }
 
+    equals(other) {
+        // Parameterless: identity is the type alone (a point has no fields).
+        return super.equals(other);
+    }
+
+    hash() {
+        // Constant — every PointShape3D is identical. Distinct from the
+        // base-class 0 so it doesn't collide with a hypothetical default shape.
+        return 0x504f494e; // "POIN"
+    }
+
     static INSTANCE = new PointShape3D();
 }

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

@@ -32,6 +32,7 @@ export class SphereShape3D 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;
+    equals(other: any): boolean;
     /**
      * Fast type-check marker. Lets the physics narrowphase short-circuit
      * sphere-involved pairs to closed-form solvers (reading `radius`) rather than

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

@@ -1 +1 @@
-{"version":3,"file":"SphereShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/SphereShape3D.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AACH;IAUI;;;;OAIG;IACH,oBAHW,MAAM,GACJ,aAAa,CAMzB;IAhBG;;;OAGG;IACH,QAFU,MAAM,CAED;IAwBnB,qGAQC;IAED,wCAQC;IAED,4DAaC;IAED,mEAEC;IAED,6CAEC;IAED,oCAOC;IAED,kFAMC;IAOL;;;;;;;;OAQG;IACH,0BAFU,OAAO,CAEsB;CAXtC;gCAhH+B,sBAAsB"}
+{"version":3,"file":"SphereShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/SphereShape3D.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AACH;IAUI;;;;OAIG;IACH,oBAHW,MAAM,GACJ,aAAa,CAMzB;IAhBG;;;OAGG;IACH,QAFU,MAAM,CAED;IAwBnB,qGAQC;IAED,wCAQC;IAED,4DAaC;IAED,mEAEC;IAED,6CAEC;IAED,oCAOC;IAED,kFAMC;IAED,4BAEC;IAOL;;;;;;;;OAQG;IACH,0BAFU,OAAO,CAEsB;CAXtC;gCApH+B,sBAAsB"}

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

@@ -110,6 +110,10 @@ export class SphereShape3D extends AbstractShape3D {
         result[result_offset + 2] *= r;
     }
 
+    equals(other) {
+        return super.equals(other) && this.radius === other.radius;
+    }
+
     hash() {
         return computeHashFloat(this.radius);
     }

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":"AAMA;;;;GAIG;AACH,uDAFa,MAAM,CAkBlB"}
+{"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"}

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

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

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

@@ -30,6 +30,20 @@ export namespace type_adapters {
             height: number;
         };
     }
+    namespace cylinder {
+        function read({ radius, height }: {
+            radius: any;
+            height: any;
+        }): CylinderShape3D;
+        /**
+         *
+         * @param {CylinderShape3D} object
+         */
+        function write(object: CylinderShape3D): {
+            radius: number;
+            height: number;
+        };
+    }
     namespace transform {
         function read({ transform, subject }: {
             transform: any;
@@ -60,6 +74,7 @@ export namespace type_adapters {
 import { UnitCubeShape3D } from "../UnitCubeShape3D.js";
 import { SphereShape3D } from "../SphereShape3D.js";
 import { CapsuleShape3D } from "../CapsuleShape3D.js";
+import { CylinderShape3D } from "../CylinderShape3D.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":";;QAWQ,iCAEC;QACD,qBAEC;;;QAGD;;0BAQC;QACD;;WAEG;QACH;;;;UAIC;;;QAGD;;;2BAEC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;;+BAIC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;yBAIC;QACD;;;WAGG;QACH;;UAIC;;;gCA/EuB,uBAAuB;8BAHzB,qBAAqB;+BADpB,sBAAsB;mCAElB,0BAA0B;6BAChC,oBAAoB"}
+{"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"}

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

@@ -1,4 +1,5 @@
 import { CapsuleShape3D } from "../CapsuleShape3D.js";
+import { CylinderShape3D } from "../CylinderShape3D.js";
 import { SphereShape3D } from "../SphereShape3D.js";
 import { TransformedShape3D } from "../TransformedShape3D.js";
 import { UnionShape3D } from "../UnionShape3D.js";
@@ -50,6 +51,21 @@ export const type_adapters = {
             };
         }
     },
+    'cylinder': {
+        read({ radius, height }) {
+            return CylinderShape3D.from(radius, height);
+        },
+        /**
+         *
+         * @param {CylinderShape3D} object
+         */
+        write(object) {
+            return {
+                radius: object.radius,
+                height: object.height
+            };
+        }
+    },
     'transform': {
         read({ transform, subject }) {
             const subject_shape = shape_from_json(subject);