@woosh/meep-engine 2.144.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.144.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":"AASA,8BAA+B;AAC/B,+BAAgC;AAChC,+BAAgC;AAChC,8BAA+B;AAE/B;;;;;GAKG;AACH,+BAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,wBAFU,MAAM,CAEoB;AAcpC;;;;;GAKG;AACH,iCAFU,MAAM,CAEqB;AAiBrC;;;;;;;;GAQG;AACH;IAEI;;;;OAIG;IACH,sBAAuE;IAYvE;;;;;OAKG;IACH,kCAUC;IA1BD;;;;;OAKG;IACH,+BAEC;IAoBD;;;;OAIG;IACH,uBAAsD;IAUtD;;;;OAIG;IACH,sBAAoD;IAsEpD;;;OAGG;IACH,+BAMC;IAlBD;;;OAGG;IACH,4BAEC;IAjFD;;;OAGG;IACH,iCAEC;IASD;;;;OAIG;IACH,mBAA8B;IAE9B;;;;OAIG;IACH,eAAW;IAEX;;;;OAIG;IACH,eAAY;IAEZ;;;;OAIG;IACH,uBAAmB;IAEnB;;;;OAIG;IACH,eAAmB;IAUnB;;;OAGG;IACH,sBAEC;IAdD;;;OAGG;IACH,mBAEC;IAUD;;;;OAIG;IACH,mBAEC;IAsBD,wBAgBC;IAED;;;;OAIG;IACH,uBA6BC;IAED;;OAEG;IACH,aAIC;IAED;;;;;;;OAOG;IACH,4BAFW,MAAM,QAQhB;IAED;;;OAGG;IACH,iBAFa,MAAM,CAqDlB;IAED;;;;OAIG;IACH,iBAFW,MAAM,QAMhB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,OAAO,CAOnB;IAED;;;;OAIG;IACH,uBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;;OAIG;IACH,uBAHW,MAAM,SACN,MAAM,QAOhB;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;;OAIG;IACH,sBAHW,MAAM,UACN,MAAM,QAIhB;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;;OAIG;IACH,sBAHW,MAAM,UACN,MAAM,QAIhB;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;;OAIG;IACH,sBAHW,MAAM,UACN,MAAM,QAIhB;IAGD;;;;OAIG;IACH,oBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;;OAIG;IACH,oBAHW,MAAM,UACN,MAAM,QAKhB;IAED;;;;OAIG;IACH,kBAHW,MAAM,UACN,MAAM,EAAE,GAAC,YAAY,QAe/B;IAED;;;;OAIG;IACH,kBAHW,MAAM,QACN,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,QAAM,QAsB1C;IAED;;;;OAIG;IACH,mBAHW,MAAM,QACN,MAAM,EAAE,QAWlB;IAED;;;;;;;;;OASG;IACH,4BARW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAmBhB;IAED;;;;OAIG;IACH,0BAHW,MAAM,GACJ,MAAM,CAoBlB;IAED;;;;;OAKG;IACH,wCAJW,MAAM,WACN,MAAM,GACJ,MAAM,CAoClB;IAED;;;;;OAKG;IACH,oCAJW,MAAM,WACN,MAAM,WACN,MAAM,QAgBhB;IAED;;;;OAIG;IACH,kBAHW,MAAM,GACJ,IAAI,CA0GhB;IAED;;;;;OAKG;IACH,wBAqBC;IAED;;;;OAIG;IACH,yBA4BC;IAED;;;;OAIG;IACH,kBAHW,MAAM,GACJ,IAAI,CA6ChB;IAED;;;;;;OAMG;IACH,gBAoMC;IAED;;;;;;OAMG;IACH,6BAJW,MAAM,WACN,MAAM,WACN,MAAM,QAWhB;IAED;;;;;;;OAOG;IACH,kCAJW,MAAM,WACN,MAAM,WACN,MAAM,QAmBhB;IAED;;;OAGG;IACH,oBAIC;IAED;;;;OAIG;IACH,yCA8BC;IAED;;;;;OAKG;IACH,+BAJW,MAAM,EAAE,sBACR,MAAM,GACJ,MAAM,CAWlB;IAED;;;;;OAKG;IACH,0BA6BC;IAED;;;;;OAKG;IACH,cAJW,MAAM,KACN,MAAM,GACJ,OAAO,CAsCnB;IAGL;;;;OAIG;IACH,gBAFU,OAAO,CAEE;CAPlB"}
+{"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/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);

package/src/engine/control/first-person/DESIGN_COLLISION.md

@@ -195,34 +195,84 @@ lives here.
 
 ### Phase 3 — Stairs  ✅ **landed**
 Real stair climbing, gated by `stepHeight` (default 0.3 m, just under
-the capsule radius).
-
-The implementation diverged from the planned explicit "up-forward-down"
-step sweep — that was tried and removed. The capsule's *round bottom*
-already rolls up a riser shorter than its radius (the slide moves the
-player up positionally), and an explicit step-up fought it (incremental
-wall-climbing, edge-wedging). What was actually needed was **honest
-ground categorization on a step edge**, which two probes split cleanly:
-
-  - **Step-DOWN** = the ground-stick reach is `stepHeight`: walking off
-    a drop ≤ stepHeight snaps onto the lower surface (stays grounded);
-    a larger drop goes airborne.
-  - **Step-UP** = categorize takes **walkability from a centre raycast**
-    (sees the real planar surface; ignores a step's convex top edge and
-    a wall's side face — so a steep *slope* is correctly not-grounded)
-    and **rest height from a footprint shapecast** (raises onto a step
-    the leading edge overhangs, capped at `stepHeight`). A single probe
-    can't tell a climbable step edge from a steep slope — both are
-    steep-normal contacts — which is why the two are split.
-
-This is also what fixed the "launch off every low step" jank: with the
-player correctly grounded through the roll, the per-tick vertical
-velocity is zeroed and never accumulates.
-
-**Guard tests** (`collision/Stairs.spec.js`, all green): climb a 5-step
-staircase staying grounded; clear a single curb without stalling; a
-0.5 m riser (> stepHeight) blocks; descend a staircase grounded the
-whole way (no launch off each lip).
+the capsule radius). Three cooperating pieces — it took iterating to
+find that all three are needed:
+
+  1. **Explicit step-up** (`_tryStepUp`, Source/Jolt up-forward-down).
+     When a grounded move is blocked, decide step-vs-wall with a **thin
+     horizontal ray at the step-height plane** (`sy + stepHeight + skin`),
+     then — only if clear — lift by stepHeight, advance the residual
+     forward, drop onto the step, commit when it gained ground within
+     stepHeight, and **restore the horizontal velocity**. The velocity
+     restore is the crux for REALISTIC stairs: the capsule's round bottom
+     also rolls up low risers, but only with sustained forward momentum,
+     and a controller that reads back the slide-clipped velocity loses
+     that momentum at the riser and stalls. The step-up climbs without
+     depending on momentum and hands the velocity back so the player keeps
+     moving up the flight.
+
+     The step-vs-wall ray is what stops the round bottom climbing a
+     too-tall wall — and the reason it's a THIN ray, not the obvious
+     "lift the capsule and sweep it forward" clearance cast: lifted so its
+     tip sits at stepHeight, the capsule's rounded bottom narrows through
+     the band `(stepHeight, stepHeight+radius)`, so a wall whose top lands
+     in that band is never reached by the swept shape — it reads "clear"
+     and the player climbs it, *faster speed reaching further into the
+     round-off* (the gray-box bug: jitter at a walk, clean climb at a
+     sprint). A thin ray has no round-off: it reads the obstacle's true
+     height, so a step (top below the plane) is passed over and a wall
+     (top above) is struck on its front face, at any approach speed.
+
+     The ray is cast along the **blocked direction** (the horizontal
+     velocity the slide removed = the obstacle's inward normal), from the
+     **pre-slide** centre, reaching the swept distance plus a forward
+     extent. Both matter for OBLIQUE approaches: at 45° the capsule meets a
+     wall with its normal-direction extent, so a ray along *travel* stops
+     short of the face and reads a wall as clear (climbing it); and
+     rounding a convex corner the slide carries the *post*-slide centre
+     just past the corner, so a ray from there shoots past the obstacle —
+     the pre-slide centre was still in front of what blocked it. The reach
+     tracking the sweep isn't the banned speed coupling: the climb-or-block
+     decision is the step-height plane alone; the reach only governs how
+     far ahead to look for what the slide already hit.
+
+     A single ray still can't catch a convex *point*: grazing a corner a
+     few degrees off its bisector, the blocked normal runs nearly parallel
+     to a face, so the ray slips past the corner just outside the footprint
+     and reads clear. The backstop is a post-hoc OVERLAP query — after
+     up-forward-down, if the destination overlaps geometry the climb landed
+     the round body ON a wall corner, not on a step (a real step top is
+     rested on `skin` above, never overlapping), so it's rejected. Probe for
+     the common case, overlap-test to catch what a ray threads past.
+
+     The same round-bottom perch is why the slide keeps every contact's true
+     normal (no "flatten steep contacts to vertical" — that would also rob
+     a too-steep *slope* of its downhill slide) and why the footprint
+     mount in (2) is gated on height above the **centre surface**, not the
+     feet (gating on the feet lets a capsule that rode up a hair mount the
+     next sliver and ratchet up a wall).
+  2. **Two-probe ground categorize** for honest grounded-ness on a step
+     edge — *walkability* from a centre raycast (ignores a step's convex
+     top edge and a wall's side face, so a steep *slope* is correctly
+     not-grounded) and *rest height* from a footprint shapecast (mounts
+     a step the leading edge overhangs). A single probe can't tell a
+     climbable step edge from a steep slope; the split can.
+  3. **Step-DOWN** = the ground-stick reach is `stepHeight`: walking off
+     a drop ≤ stepHeight snaps onto the lower surface (stays grounded);
+     a larger drop goes airborne.
+
+Footgun caught in the prototype: my first stair test used *deep
+overlapping* steps, where the round-bottom roll alone climbs and the
+explicit step-up looked unnecessary. Realistic *thin* treads (shallower
+than the capsule footprint) need the step-up — see the thin-tread tests.
+
+**Guard tests** (`collision/Stairs.spec.js` + `KinematicMoverIntegration.spec.js`,
+all green): climb a 5-step staircase; climb a thin-tread staircase
+(treads < footprint) both at the mover level and through the full
+controller; clear a single curb; a 0.5 m riser (> stepHeight) blocks;
+a 0.5 m riser is a **clean wall — no edge ride-up, and clearing is
+speed-independent** (walk and sprint both stop dead, the gray-box guard);
+descend a staircase grounded the whole way.
 
 ### Phase 4 — Motor seam + delete old code  ✅ **landed**
 The mover is now the **only** collision path when a `PhysicsSystem` is

package/src/engine/control/first-person/FirstPersonPlayerControllerSystem.d.ts

@@ -182,6 +182,19 @@ export class FirstPersonPlayerControllerSystem extends System<any, any, any, any
      * @param {number} dt
      */
     private _integrateVerticalAndResolveGround;
+    /**
+     * Resolve the current `runtime.velocity*` against the world — the
+     * physics-backed {@link KinematicMover} (recover + sweep-and-slide +
+     * ground-categorize) when a PhysicsSystem is present, else the no-physics
+     * flat-ground fallback. Gravity is NOT applied here: the standard path
+     * applies it in {@link _applyGravity} just before, and abilities with a
+     * non-standard vertical model (WallRun's reduced gravity) apply their own
+     * and then call this directly — so motion routes through one motor for
+     * everyone (sweep-and-slide, anti-tunnel, land/leave events) rather than
+     * a bespoke `position._add` + hand-rolled ground-catch.
+     * @private
+     */
+    private _resolveMotion;
     /**
      * Motor: integrate gravity into `velocityY` with the fall / variable-
      * cut multipliers. The mover never invents motion, so gravity lives

package/src/engine/control/first-person/FirstPersonPlayerControllerSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FirstPersonPlayerControllerSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerControllerSystem.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"FirstPersonPlayerControllerSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerControllerSystem.js"],"names":[],"mappings":"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"}

package/src/engine/control/first-person/FirstPersonPlayerControllerSystem.js

@@ -1128,14 +1128,28 @@ export class FirstPersonPlayerControllerSystem extends System {
      */
     _integrateVerticalAndResolveGround(controller, runtime, bodyTransform, dt) {
         this._applyGravity(controller, runtime, dt);
+        this._resolveMotion(controller, runtime, bodyTransform, dt);
+        this._detectJumpApex(controller, runtime, bodyTransform);
+    }
 
+    /**
+     * Resolve the current `runtime.velocity*` against the world — the
+     * physics-backed {@link KinematicMover} (recover + sweep-and-slide +
+     * ground-categorize) when a PhysicsSystem is present, else the no-physics
+     * flat-ground fallback. Gravity is NOT applied here: the standard path
+     * applies it in {@link _applyGravity} just before, and abilities with a
+     * non-standard vertical model (WallRun's reduced gravity) apply their own
+     * and then call this directly — so motion routes through one motor for
+     * everyone (sweep-and-slide, anti-tunnel, land/leave events) rather than
+     * a bespoke `position._add` + hand-rolled ground-catch.
+     * @private
+     */
+    _resolveMotion(controller, runtime, bodyTransform, dt) {
         if (this.physicsSystem !== null) {
             this._moveViaMover(controller, runtime, bodyTransform, dt);
         } else {
             this._moveFlatGround(controller, runtime, bodyTransform, dt);
         }
-
-        this._detectJumpApex(controller, runtime, bodyTransform);
     }
 
     /**

package/src/engine/control/first-person/abilities/WallRun.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WallRun.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/abilities/WallRun.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAMQ,qDAAqD;IACrD,iBAAiB;IACjB,yDAAyD;IACzD,cAAgB;IAGpB,kEAiBC;IAED,gDAqBC;IAED;;;;OAIG;IACH,wBAEC;IAED,uFAiFC;CAKJ;wBAlLuB,cAAc"}
+{"version":3,"file":"WallRun.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/abilities/WallRun.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAMQ,qDAAqD;IACrD,iBAAiB;IACjB,yDAAyD;IACzD,cAAgB;IAGpB,kEAiBC;IAED,gDAqBC;IAED;;;;OAIG;IACH,wBAEC;IAED,uFAgEC;CAKJ;wBAjKuB,cAAc"}

package/src/engine/control/first-person/abilities/WallRun.js

@@ -131,43 +131,26 @@ export class WallRun extends Ability {
         const rollSign = this._side === "L" ? -1 : 1;
         runtime.leanTargetRad = rollSign * cfg.cameraRollDeg * DEG_TO_RAD;
 
-        // -- Reduced gravity.
+        // -- Reduced gravity. This is wall-run's OWN vertical model (a
+        // fraction of base gravity, no fall multiplier), applied here rather
+        // than via the system's standard gravity step.
         runtime.velocityY -= runtime.gravity * cfg.gravityFactor * dt;
 
-        // -- Integrate position (manual — don't call the system's vertical
-        // phase because that would re-apply gravity with the fall multiplier).
-        bodyTransform.position._add(
-            runtime.velocityX * dt,
-            runtime.velocityY * dt,
-            runtime.velocityZ * dt,
-        );
-
-        // -- Ground catch. Reduced gravity is still gravity; over the
-        // wall-run's lifetime the player drifts down. Without a ground
-        // check here, the player can integrate PAST the floor — at
-        // which point the wall sensor eventually drops out, base
-        // resumes, and base's downward groundResolver raycast (from
-        // below the floor) doesn't find anything above. Player free-
-        // falls forever.
-        //
-        // Consult the same effective ground the base integrator uses:
-        // max(useBuiltInFlatGround baseline, groundResolver). If we've
-        // sunk to or past it, snap, zero vy, and release — base will
-        // mark grounded on the next tick.
-        let groundY = system.useBuiltInFlatGround ? system.groundY : null;
-        if (system.groundResolver !== null) {
-            const resolved = system.groundResolver(
-                bodyTransform.position.x,
-                bodyTransform.position.y,
-                bodyTransform.position.z,
-            );
-            if (resolved !== null && (groundY === null || resolved > groundY)) {
-                groundY = resolved;
-            }
-        }
-        if (groundY !== null && bodyTransform.position.y <= groundY) {
-            bodyTransform.position.setY(groundY);
-            runtime.velocityY = 0;
+        // -- Resolve the move through the shared motor. With the reduced-
+        // gravity velocity set above, route it through the same sweep-and-
+        // slide + ground-categorize the base locomotion uses (the mover when
+        // physics is present, else the flat-ground fallback). _resolveMotion
+        // does NOT re-apply gravity. This replaces a raw `position._add` plus
+        // a hand-rolled groundResolver catch: the wall-runner now (a) can't
+        // drift INTO geometry (the sweep clips it) nor sail OFF a ledge the
+        // mover would have caught, and (b) gets the motor's anti-tunnel
+        // ground catch for free — the same reason base no longer free-falls
+        // past a floor. The motor sets `state.grounded` and fires land/leave.
+        system._resolveMotion(controller, runtime, bodyTransform, dt);
+
+        // -- Exit: the motor caught a floor at the wall's foot (we ran out
+        // onto the ground). Release; base resumes next tick.
+        if (controller.state.grounded) {
             return false;
         }
 

package/src/engine/control/first-person/collision/KinematicMover.d.ts

@@ -45,11 +45,12 @@ export class KinematicMover {
      *   `MIN_WALK_NORMAL` / Source `normal.z ≥ 0.7`.
      * @param {number} [options.stepHeight=0.3] maximum step the player
      *   traverses, both up and down:
-     *   - UP: ground-categorize mounts the player onto a surface up to
-     *     `stepHeight` above the feet (a step the capsule's leading edge
-     *     reaches); a taller riser isn't mounted and the slide blocks it.
-     *     The capsule's round bottom does the actual climbing motion;
-     *     `stepHeight` is the gate on how high categorize will stick.
+     *   - UP: a riser no taller than this is climbed — by the explicit
+     *     step-up ({@link _tryStepUp}, up-forward-down, which works
+     *     regardless of forward momentum) and by `_categorizeGround`
+     *     mounting the player onto a surface within `stepHeight` of the
+     *     feet. A taller riser blocks (the slide stops the player; the
+     *     step-up's forward clearance cast detects the wall and aborts).
      *   - DOWN: the ground-stick reach — walking off a drop no larger
      *     than this snaps the player onto the lower surface (stays
      *     grounded); a larger drop goes airborne (a real ledge).
@@ -76,6 +77,7 @@ export class KinematicMover {
     _penDir: Float64Array;
     _planes: Float64Array;
     _cand: Float64Array;
+    _support: Float64Array;
     /**
      * Reused result. `grounded` / `groundNormal` are Phase 2 outputs;
      * in Phase 1 they're left at their defaults (the mover doesn't
@@ -110,6 +112,34 @@ export class KinematicMover {
         grounded: boolean;
         groundNormal: Vector3;
     };
+    /**
+     * Stair step-up. Called after a slide that hit something while the
+     * player was trying to move horizontally on the ground. Re-runs the
+     * horizontal move from the pre-slide position lifted by `stepHeight`,
+     * guarded by a forward CLEARANCE cast: if the path is still blocked at
+     * the lifted height the obstacle is taller than a step (a wall) and we
+     * abandon the attempt; if clear it's a step, so advance over it and
+     * drop. Commits only when it advances farther horizontally than the
+     * plain slide and the rise is within `stepHeight`. On success the
+     * horizontal velocity is restored (the riser wasn't a wall) so the
+     * controller doesn't read back a stalled speed; the vertical is left
+     * for `_categorizeGround` to settle on the step.
+     *
+     * @private
+     */
+    private _tryStepUp;
+    /**
+     * Distance the shape can sweep along a unit axis before contact (less
+     * `skin`), or the full `maxDist` if clear. For the step-up lift/drop.
+     * @private
+     */
+    private _castDistance;
+    /**
+     * True when a centre raycast at (x,y,z) finds a walkable surface
+     * within stick range — gates step-up on "actually standing".
+     * @private
+     */
+    private _groundedAt;
     /**
      * Push the capsule out of any geometry it currently overlaps. Each
      * pass queries overlaps, finds the single deepest penetration via

package/src/engine/control/first-person/collision/KinematicMover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KinematicMover.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/collision/KinematicMover.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IACI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,2BA7BW,OAAO,uCAAuC,EAAE,aAAa,OAC7D,OAAO,wCAAwC,EAAE,sBAAsB;QAKtD,IAAI,GAArB,MAAM;QAEW,kBAAkB,GAAnC,MAAM;QAEW,oBAAoB,GAArC,MAAM;QAEW,aAAa,GAA9B,MAAM;QAIW,UAAU,GAA3B,MAAM;OAqChB;IAvBG,6EAAkC;IAClC,6EAAc;IACd,aAA6D;IAC7D,2BAAmG;IACnG,6BAAyG;IACzG,sBAAsF;IACtF,mBAA6E;IAG7E,WAAsB;IACtB,0BAAqC;IACrC,yBAAsC;IACtC,sBAAkC;IAClC,sBAAoD;IACpD,oBAAgC;IAEhC;;;;;OAKG;IACH,SAFU;QAAC,GAAG,EAAC,OAAO,CAAC;QAAC,QAAQ,EAAC,OAAO,CAAC;QAAC,YAAY,EAAC,OAAO,CAAA;KAAC,CAEmB;IAGtF;;;;;;;;;;;;OAYG;IACH,eATW,OAAO,YACP;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,SACrC,OAAO,mDAAmD,EAAE,eAAe,YAC3E,OAAO,MACP,MAAM,mBACE,MAAM,YAAW,QAAQ,KAAG,OAAO,GAEzC;QAAC,GAAG,EAAC,OAAO,CAAC;QAAC,QAAQ,EAAC,OAAO,CAAC;QAAC,YAAY,EAAC,OAAO,CAAA;KAAC,CA+BjE;IAED;;;;;;;;;OASG;IACH,iBAwCC;IAED;;;;;;;;OAQG;IACH,eA0HC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,0BAgDC;IAED;;;;;OAKG;IACH,cAKC;CACJ;qBAtaoB,sCAAsC;oCAIvB,iDAAiD;oBALjE,kCAAkC;yBAG7B,kCAAkC"}
+{"version":3,"file":"KinematicMover.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/collision/KinematicMover.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IACI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,2BA9BW,OAAO,uCAAuC,EAAE,aAAa,OAC7D,OAAO,wCAAwC,EAAE,sBAAsB;QAKtD,IAAI,GAArB,MAAM;QAEW,kBAAkB,GAAnC,MAAM;QAEW,oBAAoB,GAArC,MAAM;QAEW,aAAa,GAA9B,MAAM;QAIW,UAAU,GAA3B,MAAM;OAuChB;IAxBG,6EAAkC;IAClC,6EAAc;IACd,aAA6D;IAC7D,2BAAmG;IACnG,6BAAyG;IACzG,sBAAsF;IACtF,mBAA6E;IAG7E,WAAsB;IACtB,0BAAqC;IACrC,yBAAsC;IACtC,sBAAkC;IAClC,sBAAoD;IACpD,oBAAgC;IAChC,uBAAmC;IAEnC;;;;;OAKG;IACH,SAFU;QAAC,GAAG,EAAC,OAAO,CAAC;QAAC,QAAQ,EAAC,OAAO,CAAC;QAAC,YAAY,EAAC,OAAO,CAAA;KAAC,CAEmB;IAGtF;;;;;;;;;;;;OAYG;IACH,eATW,OAAO,YACP;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,SACrC,OAAO,mDAAmD,EAAE,eAAe,YAC3E,OAAO,MACP,MAAM,mBACE,MAAM,YAAW,QAAQ,KAAG,OAAO,GAEzC;QAAC,GAAG,EAAC,OAAO,CAAC;QAAC,QAAQ,EAAC,OAAO,CAAC;QAAC,YAAY,EAAC,OAAO,CAAA;KAAC,CA4CjE;IAED;;;;;;;;;;;;;;OAcG;IACH,mBA0FC;IAED;;;;OAIG;IACH,sBAQC;IAED;;;;OAIG;IACH,oBASC;IAED;;;;;;;;;OASG;IACH,iBAwCC;IAED;;;;;;;;OAQG;IACH,eAmIC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,0BAsDC;IAED;;;;;OAKG;IACH,cAKC;CACJ;qBA9kBoB,sCAAsC;oCAIvB,iDAAiD;oBALjE,kCAAkC;yBAG7B,kCAAkC"}

package/src/engine/control/first-person/collision/KinematicMover.js

@@ -64,11 +64,12 @@ export class KinematicMover {
      *   `MIN_WALK_NORMAL` / Source `normal.z ≥ 0.7`.
      * @param {number} [options.stepHeight=0.3] maximum step the player
      *   traverses, both up and down:
-     *   - UP: ground-categorize mounts the player onto a surface up to
-     *     `stepHeight` above the feet (a step the capsule's leading edge
-     *     reaches); a taller riser isn't mounted and the slide blocks it.
-     *     The capsule's round bottom does the actual climbing motion;
-     *     `stepHeight` is the gate on how high categorize will stick.
+     *   - UP: a riser no taller than this is climbed — by the explicit
+     *     step-up ({@link _tryStepUp}, up-forward-down, which works
+     *     regardless of forward momentum) and by `_categorizeGround`
+     *     mounting the player onto a surface within `stepHeight` of the
+     *     feet. A taller riser blocks (the slide stops the player; the
+     *     step-up's forward clearance cast detects the wall and aborts).
      *   - DOWN: the ground-stick reach — walking off a drop no larger
      *     than this snaps the player onto the lower surface (stays
      *     grounded); a larger drop goes airborne (a real ledge).
@@ -91,6 +92,7 @@ export class KinematicMover {
         this._penDir = new Float64Array(3);          // compute_penetration out
         this._planes = new Float64Array(MAX_CLIP_PLANES * 3);
         this._cand = new Float64Array(3);            // clipped-velocity candidate
+        this._support = new Float64Array(3);         // shape support point (forward extent)
 
         /**
          * Reused result. `grounded` / `groundNormal` are Phase 2 outputs;
@@ -139,12 +141,163 @@ export class KinematicMover {
         // 2. Sweep-and-slide the desired motion.
         this._slide(position, rotation, shape, velocity, dt, filter, result);
 
+        // 2b. Stairs — if a grounded move was blocked, try to step up and
+        //     over a low riser. The capsule's round bottom also rolls up
+        //     low steps via the slide, but only with enough forward
+        //     momentum; a controller that reads back the slide-clipped
+        //     velocity loses that momentum at the riser and gets stuck.
+        //     The explicit step-up climbs without depending on momentum
+        //     AND restores the horizontal velocity, so the player keeps
+        //     moving up the flight.
+        if (this.stepHeight > 0 && !ascending && result.hit) {
+            this._tryStepUp(position, rotation, shape, velocity,
+                sx, sy, sz, svx, svy, svz, dt, filter);
+        }
+
         // 3. Ground categorize + stick + slope velocity clip.
         this._categorizeGround(position, rotation, shape, velocity, filter, result, ascending);
 
         return result;
     }
 
+    /**
+     * Stair step-up. Called after a slide that hit something while the
+     * player was trying to move horizontally on the ground. Re-runs the
+     * horizontal move from the pre-slide position lifted by `stepHeight`,
+     * guarded by a forward CLEARANCE cast: if the path is still blocked at
+     * the lifted height the obstacle is taller than a step (a wall) and we
+     * abandon the attempt; if clear it's a step, so advance over it and
+     * drop. Commits only when it advances farther horizontally than the
+     * plain slide and the rise is within `stepHeight`. On success the
+     * horizontal velocity is restored (the riser wasn't a wall) so the
+     * controller doesn't read back a stalled speed; the vertical is left
+     * for `_categorizeGround` to settle on the step.
+     *
+     * @private
+     */
+    _tryStepUp(position, rotation, shape, velocity, sx, sy, sz, svx, svy, svz, dt, filter) {
+        const hdx = svx * dt, hdz = svz * dt;
+        const forwardLen = Math.sqrt(hdx * hdx + hdz * hdz);
+        if (forwardLen < MIN_MOVE) return; // no horizontal intent
+        // Only step from a grounded start — never mid-air (else a player
+        // could climb a wall by jumping into it).
+        if (!this._groundedAt(sx, sy, sz, filter)) return;
+
+        const slideProg = (position.x - sx) * (position.x - sx) + (position.z - sz) * (position.z - sz);
+        const px = position.x, py = position.y, pz = position.z;
+        const pvx = velocity.x, pvy = velocity.y, pvz = velocity.z;
+        const fnx = hdx / forwardLen, fnz = hdz / forwardLen; // travel direction
+
+        // Direction the slide was BLOCKED in — the inward normal of the
+        // obstacle the player walked into = the horizontal velocity the
+        // slide removed (pre-slide minus clipped). For a head-on approach
+        // this equals the travel direction; for an OBLIQUE one it's the
+        // wall's normal, which is what we must probe along: the capsule
+        // meets the wall with its normal-direction extent, so a probe cast
+        // along TRAVEL would stop short of the face (it only has to reach
+        // radius/​cos θ along travel, but radius along the normal) and read a
+        // wall as clear, climbing it. Deriving it from the velocity change
+        // needs no slide-internal normal plumbed out.
+        let bdx = svx - velocity.x, bdz = svz - velocity.z;
+        const bdLen = Math.sqrt(bdx * bdx + bdz * bdz);
+        if (bdLen < MIN_MOVE) return; // nothing opposed the horizontal move — no wall/step ahead
+        bdx /= bdLen; bdz /= bdLen;
+
+        // ── Step-vs-wall decision: a THIN horizontal ray at the step-height
+        //    plane ──────────────────────────────────────────────────────
+        // The obvious "lift the capsule by stepHeight and sweep it forward"
+        // clearance test is fooled by the capsule's ROUNDED bottom: lifted
+        // so its tip sits at stepHeight, the hemisphere narrows through the
+        // band (stepHeight, stepHeight+radius), so a wall whose top lands in
+        // that band is never reached by the swept capsule — it reads "clear"
+        // and the player climbs a too-tall wall (and does so speed-
+        // dependently, since a faster sweep reaches further into the round-
+        // off). A thin ray has no such round-off. Cast it INTO the obstacle
+        // (along the blocked normal) at exactly the highest climbable height:
+        // anything taller than a step has solid material crossing that plane
+        // and is struck on its front face; a genuine step (top below the
+        // plane) is passed clean over. This reads the obstacle's true height,
+        // independent of how the round bottom would perch on its edge — so
+        // "clear it or don't" holds at any speed and any approach angle.
+        //
+        // Origin at the PRE-slide centre, not post-slide: rounding a convex
+        // corner, the slide can carry the centre just past the corner (out
+        // of the obstacle's footprint) so a probe from there shoots past it
+        // and reads clear, climbing the corner. The pre-slide centre was
+        // still in front of what blocked it. Reach spans the swept move
+        // (`forwardLen`) plus a forward-extent to the leading edge plus a
+        // few skins — enough to cross the front face wherever along the
+        // sweep contact happened. The reach tracking the sweep is not the
+        // banned speed coupling: the climb-or-block DECISION is the
+        // step-height plane alone; the reach only governs how far ahead we
+        // look for the thing the slide already hit.
+        shape.support(this._support, 0, bdx, 0, bdz);
+        const lead = this._support[0] * bdx + this._support[2] * bdz; // extent toward the wall (capsule radius)
+        const ray = this._ray;
+        ray.setOrigin(sx, sy + this.stepHeight + this.skin, sz);
+        ray.setDirection(bdx, 0, bdz);
+        ray.tMax = forwardLen + lead + 4 * this.skin;
+        if (this.physicsSystem.raycast(ray, this._hit, filter)) return; // taller than a step — a wall; keep the plain slide
+
+        // Confirmed climbable (nothing crosses the step-height plane ahead).
+        // Up–forward–down places the capsule onto the step top.
+        position.set(sx, sy, sz);
+        const up = this._castDistance(position, rotation, shape, 0, 1, 0, this.stepHeight, filter);
+        position._add(0, up, 0);
+        position._add(fnx * forwardLen, 0, fnz * forwardLen);
+        const down = this._castDistance(position, rotation, shape, 0, -1, 0, up + this.skin, filter);
+        position._add(0, -down, 0);
+
+        // Reject a climb that ends INSIDE geometry. The thin step-height
+        // probe is a single ray, so at a convex CORNER it can thread past
+        // the corner point (the contact normal there is near-parallel to a
+        // face, so the ray runs alongside the box just outside its
+        // footprint) and read clear — then up-forward-down perches the round
+        // body on that corner, overlapping it. A genuine step top is rested
+        // on `skin` ABOVE, never overlapping; so an overlap at the
+        // destination is the tell that we climbed onto a wall, not a step.
+        const stepProg = (position.x - sx) * (position.x - sx) + (position.z - sz) * (position.z - sz);
+        const heightGain = position.y - sy;
+        const overlaps = this.physicsSystem.overlap(shape, position, rotation, this._overlapBuf, 0, filter) > 0;
+        if (stepProg > slideProg + 1e-8 && heightGain <= this.stepHeight + this.skin && !overlaps) {
+            velocity.set(svx, svy, svz); // restore horizontal; vertical settled by categorize
+        } else {
+            position.set(px, py, pz);
+            velocity.set(pvx, pvy, pvz);
+        }
+    }
+
+    /**
+     * Distance the shape can sweep along a unit axis before contact (less
+     * `skin`), or the full `maxDist` if clear. For the step-up lift/drop.
+     * @private
+     */
+    _castDistance(position, rotation, shape, dx, dy, dz, maxDist, filter) {
+        const ray = this._ray;
+        ray.setOrigin(position.x, position.y, position.z);
+        ray.setDirection(dx, dy, dz);
+        ray.tMax = maxDist;
+        if (!this.physicsSystem.shapeCast(ray, shape, rotation, this._hit, filter)) return maxDist;
+        const t = this._hit.t - this.skin;
+        return t > 0 ? t : 0;
+    }
+
+    /**
+     * True when a centre raycast at (x,y,z) finds a walkable surface
+     * within stick range — gates step-up on "actually standing".
+     * @private
+     */
+    _groundedAt(x, y, z, filter) {
+        const ray = this._ray;
+        const lift = this.stepHeight;
+        ray.setOrigin(x, y + lift, z);
+        ray.setDirection(0, -1, 0);
+        ray.tMax = lift + this.stepHeight + this.skin;
+        if (!this.physicsSystem.raycast(ray, this._hit, filter)) return false;
+        if (this._hit.normal.y < this.minWalkNormal) return false;
+        return (y + lift - this._hit.t) <= y + this.skin;
+    }
+
     /**
      * Push the capsule out of any geometry it currently overlaps. Each
      * pass queries overlaps, finds the single deepest penetration via
@@ -272,6 +425,15 @@ export class KinematicMover {
                 vx = vy = vz = 0;
                 break;
             }
+            // Store the true contact plane for velocity clipping. The
+            // capsule's round bottom does NOT roll up a too-tall obstacle:
+            // standing on the floor it meets a wall with its full-radius
+            // cylinder side (a horizontal normal — a clean stop), and
+            // CLIMBING a step ≤ stepHeight is the explicit step-up's job,
+            // gated by a thin step-height probe that reads true obstacle
+            // height regardless of approach speed. So the slide keeps every
+            // surface's real normal — flattening steep contacts to vertical
+            // here would also rob a too-steep SLOPE of its downhill slide.
             const po = numPlanes * 3;
             planes[po] = hit.normal.x;
             planes[po + 1] = hit.normal.y;
@@ -375,7 +537,8 @@ export class KinematicMover {
         const nx = hit.normal.x, ny = hit.normal.y, nz = hit.normal.z;
         result.groundNormal.set(nx, ny, nz);
         if (ny < this.minWalkNormal) return; // steep slope under the feet — slide, not grounded
-        let surfaceY = position.y + lift - hit.t;
+        const centreSurfaceY = position.y + lift - hit.t; // the planar ground under the feet
+        let surfaceY = centreSurfaceY;
 
         // (B) Footprint shapecast — mount a step the leading edge overhangs.
         ray.setOrigin(position.x, position.y + lift, position.z);
@@ -383,10 +546,15 @@ export class KinematicMover {
         ray.tMax = reach;
         if (this.physicsSystem.shapeCast(ray, shape, rotation, hit, filter) && hit.t > this.skin) {
             const stepY = position.y + lift - hit.t;
-            // Raise onto it only if it's higher than the centre surface
-            // and within a climbable step (a taller one is a wall the
-            // slide blocks — leave the player on the centre surface).
-            if (stepY > surfaceY && stepY - position.y <= this.stepHeight + this.skin) {
+            // Mount it only if it's higher than the centre surface and no
+            // more than `stepHeight` ABOVE THAT CENTRE SURFACE — not above
+            // the feet. Gating on the feet would let the player climb a
+            // wall incrementally: ride up its edge a hair, then mount the
+            // now-within-reach next sliver, and so on. Gating on the
+            // ground under the centre means a wall top is always >
+            // stepHeight above the floor the centre sees → never mounted,
+            // and a capsule that rode up gets snapped back to the floor.
+            if (stepY > surfaceY && stepY - centreSurfaceY <= this.stepHeight + this.skin) {
                 surfaceY = stepY;
             }
         }

package/src/engine/physics/PLAN.md

@@ -604,13 +604,44 @@ scaffolding is in place.
       bodies where speculative margin isn't enough. The bench's falling
       tower (1km drop onto a 1cm floor) is the concrete reproducer —
       180 / 1000 bodies tunnel.
-- [ ] **Broadphase BVH balance / raycast traversal cost**: the raycast bench
-      (`queries/raycast.bench.spec.js`) shows ~linear-in-N per-ray cost
-      (~50 µs/ray at 500 bodies), i.e. a ray walks most of the tree — the static
-      BVH built by sequential `link` inserts is poorly balanced. Orthogonal to
-      raycast narrowphase (which adds only per-crossed-leaf refine, <1% here);
-      affects every BVH query. Needs a balanced/refitting build (SAH or
-      incremental rotation) on the static tree.
+- [x] **Broadphase BVH balance — SAH rotation.** The dynamic AABB tree
+      (`core/bvh2/bvh3/BVH.js`, a Box2D port) used SAH-cost insertion but a
+      *height-only* AVL rotation (`balance_height`): height-balanced yet not
+      SAH-balanced, so queries walked more nodes than needed. Replaced the
+      rotation in `bubble_up_update` with `balance_rotate` — the Box2D-v3 /
+      Kensler SAH-reducing rotation (for node A with children B, C, evaluate the
+      four child↔grandchild swaps and apply the one that most reduces the
+      surface-area cost). Deterministic; identical pair set.
+        - Measured (same-session A/B, heavy benches): raycast **−9%**
+          (28.2→25.6 µs/ray), falling-tower median **−10%**, settling-grid
+          median **−12%**, and the **990/1000-churn stress −27%**
+          (63.95→46.68 ms mean over 10k ticks) — biggest where the tree churns
+          hardest. Determinism (8-trial bit-identical) holds.
+        - **Insertion cost (measured):** `balance_rotate` does 4 surface-area
+          evaluations per bubble-up level vs `balance_height`'s single height
+          compare, so *pure bulk insertion* is **~1.4–1.5× slower** — the 100k
+          synthetic insert bench (`BVH.spec.js`, drift-controlled interleaved
+          A/B) drops from **~37k → ~25k inserts/sec** (~27→~40 µs/insert). This
+          is the balancer's worst case (insert-only, zero queries/refits to
+          amortise against). It does not show up end-to-end: static trees are
+          built once then queried forever, dynamic bodies insert once then
+          refit/query every frame, and even the 990/1000-swap stress test — the
+          maximal insert-churn workload — is net **−27%**. Accepted.
+        - **Tradeoff (documented):** the contact solver's Gauss-Seidel order
+          follows broadphase traversal order (see `generate_pairs`), so the
+          different tree shape shifts convergence on near-aligned stacks — the
+          synthetic 128-cube wall now sleeps at ~10 s (was ~6.9 s). It still
+          settles, doesn't creep / topple (all bug-guard assertions hold); only
+          the sleep *time* moved (that test's budget was bumped 9→11 s with a
+          note). Random-shape scenes (falling tower) were faster *and* settled
+          fine.
+        - **Follow-up:** decouple the solve order from tree shape — sort the
+          broadphase pair list by `(idA, idB)` before narrowphase so contact
+          order is body-id-deterministic regardless of tree shape. Then no tree
+          change can affect convergence (and the stack settles identically under
+          either balancer). Has a per-step sort cost + wide test re-baseline, so
+          it's its own task. `balance_height` is retained for comparison /
+          fallback.
 - [ ] **Per-island parallel solve**: today's island data layout would
       allow worker-based solving once `SharedArrayBuffer` is available.
       Out-of-scope unless / until SAB is universally usable.
@@ -637,8 +668,19 @@ scaffolding is in place.
 - [ ] **Convex hull shape** with eigen-based principal-axes inertia
       derivation. Hooks `matrix_eigenvalues_in_place` from the existing
       linalg layer.
-- [ ] **Cylinder / cone shapes** (closed-form pairs against the existing
-      family + GJK+EPA fallback for general convex).
+- [~] **Cylinder / cone shapes.**
+    - [x] **`CylinderShape3D`** — Y-aligned solid cylinder (radius + full
+          height, flat caps; the capsule's flat-cap sibling). Exact `support`,
+          capped-cylinder SDF, bounds, `contains` / `nearest_point` /
+          volume-sampling, equals/hash, `'cylinder'` JSON tag, `isCylinderShape3D`
+          marker. Convex → routes through the narrowphase **GJK + EPA** fallback
+          (no marker dispatch needed); spec asserts overlap-detected +
+          MTV-separates vs sphere/box. Closed-form cylinder-vs-X contact pairs
+          are a future refinement (the curved side is the usual smooth-support
+          EPA case — same status as pre-closed-form sphere/capsule).
+    - [ ] Closed-form cylinder contact pairs (cylinder × box / sphere / capsule
+          / plane) for multi-point cap manifolds + stable resting.
+    - [ ] **Cone shape** (+ closed-form / GJK fallback).
 
 ### API polish
 - [x] **`overlap(shape, position, rotation, output, output_offset,