@woosh/meep-engine 2.142.0 → 2.144.0

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

@@ -88,38 +88,23 @@ evaluator then scales. Two-step change.
 
 Estimated effort: 1 day (more wiring than the others).
 
-## Move-and-slide follow-ups
-
-### Slide along non-axis-aligned walls
-**Landed.** `PhysicsSystem.shapeCast` now writes the true contact
-normal (narrowphase-refined via GJK + EPA at TOI), and `_moveAndSlide`
-uses the canonical iterative slide: stop at first contact, project the
-residual onto the contact tangent, sweep again, repeat up to 4 times.
-Multi-contact corners stop cleanly; diagonal approaches slide along
-both axis-aligned and oblique surfaces.
-
-### Vertical sweep (anti-tunnel for floors and ceilings)
-`_moveAndSlide` is currently called for horizontal motion only. The
-vertical phase still does a direct position add. For fast falls past
-the ground-resolver's 0.1 m raycast lift, the player can sink through
-the floor in one tick; for vertical wall-jumps into a ceiling, no
-contact is detected.
-
-Wiring a vertical sweep into `_integrateVerticalAndResolveGround`
-needs to be coordinated with the SKIN clearance — landing at
-`floor + SKIN` would re-flag the player as airborne by the resolver,
-which would re-apply gravity and bounce. Either drop SKIN on
-floor-normal contacts, or have the resolver use a tolerance instead
-of strict `position.y <= testY`.
-
-### Ability motion routing
-Slide and WallRun integrate position manually (slide friction in the
-ability tick; wall-run reduced-gravity integration). Once the slide-
-along-walls work above lands, threading those through `_moveAndSlide`
-would prevent wall-runners from drifting into the wall and sliders
-from penetrating obstacles in their path. The controller-side change
-is a few lines per ability; the gating issue is having a usable
-surface normal.
+## Collision (KinematicMover) follow-ups
+
+The legacy `_moveAndSlide` + scalar-resolver regime was replaced by the
+`collision/KinematicMover` rebuild (Phases 1–4; see DESIGN_COLLISION.md).
+Slide-along-walls (axis + oblique), vertical anti-tunnel (floors and
+ceilings), depenetration, slopes, stick-to-ground, and stairs all landed
+there. Remaining:
+
+### Route WallRun through the mover
+Slide already routes its motion through the mover (it calls
+`_integrateVerticalAndResolveGround` → `_moveViaMover`). **WallRun still
+self-integrates** its reduced-gravity model and so doesn't get
+sweep-and-slide — a wall-runner can still drift into / off geometry the
+mover would have resolved. Thread WallRun's per-tick motion through
+`mover.move()` (keeping its reduced-gravity as the vertical input). The
+gating issue (a usable surface normal) is solved now — `result.groundNormal`
+and the narrowphase contact normals are available.
 
 ## Other open notes
 

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

@@ -0,0 +1,176 @@
+/**
+ * Kinematic character collision solver — Phase 1 (recover +
+ * unified sweep-and-slide). See DESIGN_COLLISION.md.
+ *
+ * The mover is controller-agnostic: it knows about a capsule pose, a
+ * desired velocity, and the physics world. Its job is to take the
+ * velocity the control layer wants and return the position it actually
+ * reaches plus the velocity corrected for whatever it hit. It invents
+ * no motion — gravity / jump impulses live in the control layer and
+ * arrive folded into `velocity`.
+ *
+ * One move is a sequence (Phase 1 implements steps 1-2; ground
+ * categorize / stairs / settle land in later phases):
+ *
+ *   1. RECOVER  — depenetration via `overlap()` + `compute_penetration`,
+ *      run unconditionally so the move starts clear even from a
+ *      start-solid state a pure sweep can't escape.
+ *   2. SLIDE    — unified 3D collide-and-slide via `shapeCast`, clipping
+ *      velocity onto true narrowphase contact normals. Crease-aware
+ *      (Quake `SV_FlyMove`): a second plane re-violating the first is
+ *      handled by sliding along their seam; a third (or a velocity
+ *      reversal) dead-stops. Floors / ceilings / walls are all just
+ *      contact planes, so vertical anti-tunnelling is automatic.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class KinematicMover {
+    /**
+     * @param {import("../../../physics/ecs/PhysicsSystem.js").PhysicsSystem} physicsSystem
+     * @param {import("../../../ecs/EntityComponentDataset.js").EntityComponentDataset} ecd
+     *   used to resolve an overlapping `body_id` (via
+     *   `physicsSystem.entityOf`) back to its {@link Transform} +
+     *   {@link Collider} for `compute_penetration`.
+     * @param {object} [options]
+     * @param {number} [options.skin=0.005] clearance left after each
+     *   sweep stop / push-out so the next query doesn't start in contact.
+     * @param {number} [options.maxSlideIterations=4] slide "bumps" per
+     *   move (Quake `numbumps`).
+     * @param {number} [options.maxRecoverIterations=4] depenetration
+     *   passes before giving up (deepest body pushed out per pass).
+     * @param {number} [options.minWalkNormal=0.7] minimum ground-normal Y
+     *   to count as standable (~45.6°). Below it the surface is "too
+     *   steep" — the player slides instead of grounding. Matches Quake3
+     *   `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.
+     *   - 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).
+     *   Source `sv_stepsize` is ~0.34 m; the default is just under the
+     *   capsule radius so low ledges don't feel "magnetic".
+     */
+    constructor(physicsSystem: import("../../../physics/ecs/PhysicsSystem.js").PhysicsSystem, ecd: import("../../../ecs/EntityComponentDataset.js").EntityComponentDataset, options?: {
+        skin?: number;
+        maxSlideIterations?: number;
+        maxRecoverIterations?: number;
+        minWalkNormal?: number;
+        stepHeight?: number;
+    });
+    physicsSystem: import("../../../physics/ecs/PhysicsSystem.js").PhysicsSystem;
+    ecd: import("../../../ecs/EntityComponentDataset.js").EntityComponentDataset;
+    skin: number;
+    maxSlideIterations: number;
+    maxRecoverIterations: number;
+    minWalkNormal: number;
+    stepHeight: number;
+    _ray: Ray3;
+    _hit: PhysicsSurfacePoint;
+    _overlapBuf: Uint32Array;
+    _penDir: Float64Array;
+    _planes: Float64Array;
+    _cand: Float64Array;
+    /**
+     * Reused result. `grounded` / `groundNormal` are Phase 2 outputs;
+     * in Phase 1 they're left at their defaults (the mover doesn't
+     * categorize ground yet).
+     * @type {{hit:boolean, grounded:boolean, groundNormal:Vector3}}
+     */
+    _result: {
+        hit: boolean;
+        grounded: boolean;
+        groundNormal: Vector3;
+    };
+    /**
+     * Resolve one move. Mutates `position` to the resolved location and
+     * `velocity` to the corrected value.
+     *
+     * @param {Vector3} position in/out — current pose, written to the resolved pose
+     * @param {{x:number,y:number,z:number,w:number}} rotation capsule orientation (read)
+     * @param {import("../../../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D} shape convex capsule
+     * @param {Vector3} velocity in/out — desired velocity, written to the corrected velocity
+     * @param {number} dt
+     * @param {(entity:number, collider:Collider)=>boolean} filter excludes
+     *   the player's own body in integration; accept-all in isolation
+     * @returns {{hit:boolean, grounded:boolean, groundNormal:Vector3}} reused result
+     */
+    move(position: Vector3, rotation: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    }, shape: import("../../../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D, velocity: Vector3, dt: number, filter: (entity: number, collider: Collider) => boolean): {
+        hit: boolean;
+        grounded: boolean;
+        groundNormal: Vector3;
+    };
+    /**
+     * Push the capsule out of any geometry it currently overlaps. Each
+     * pass queries overlaps, finds the single deepest penetration via
+     * {@link compute_penetration}, and pushes out along its separation
+     * axis by `depth + skin`; re-queries until clear or the iteration
+     * cap is hit. Deepest-first converges multi-body resting contact
+     * (each pass removes the worst offender) without solving a system.
+     *
+     * @private
+     */
+    private _recover;
+    /**
+     * Unified 3D collide-and-slide. Faithful to Quake's `SV_FlyMove`:
+     * sweep the velocity for the remaining time, stop at contact, clip
+     * the (original) velocity against every plane hit so far, slide
+     * along the seam of a two-plane crease, dead-stop on a third plane
+     * or a velocity reversal.
+     *
+     * @private
+     */
+    private _slide;
+    /**
+     * Ground categorization + stick-to-ground + slope velocity clip.
+     * Probes below the feet to decide grounded-ness, the surface height
+     * to rest on, and the surface normal for the velocity clip.
+     *
+     *   - `ascending` (jumped this tick) → never grounded; skip entirely
+     *     so the snap can't cancel the jump.
+     *   - no surface within `stepHeight` below the feet → airborne.
+     *
+     * Two probes, with a deliberate division of labour that's what makes
+     * stairs AND slopes both work (they're the same steep-normal contact
+     * to a single probe, so one probe can't tell them apart):
+     *
+     *   (A) WALKABILITY + base height — a centre-point RAYCAST. It sees
+     *       the actual planar surface under the feet and ignores both a
+     *       step's convex top EDGE (whose normal is misleadingly steep)
+     *       and a wall's vertical SIDE face. A steep normal here means a
+     *       genuine steep SLOPE → not grounded (slide).
+     *   (B) STEP height — a footprint capsule SHAPECAST. It raises the
+     *       rest height onto a step the leading edge overhangs (which the
+     *       centre ray, aimed behind the riser, misses). Used only when
+     *       it genuinely swept (`hit.t > skin`, not start-solid in a wall)
+     *       and the step is within `stepHeight`.
+     *
+     * Reference point is the capsule bottom (`position.y`), matching the
+     * feet-at-origin player capsule.
+     *
+     * @private
+     */
+    private _categorizeGround;
+    /**
+     * `out = v - n·(v·n)` — project `v` onto the plane with unit normal
+     * `n` (overbounce 1.0; clearance handled by `skin`, so no extra
+     * nudge — equivalent in practice to Quake3's `OVERCLIP 1.001`).
+     * @private
+     */
+    private _clip;
+}
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { PhysicsSurfacePoint } from "../../../physics/queries/PhysicsSurfacePoint.js";
+import Vector3 from "../../../../core/geom/Vector3.js";
+import { Collider } from "../../../physics/ecs/Collider.js";
+//# sourceMappingURL=KinematicMover.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,424 @@
+import Vector3 from "../../../../core/geom/Vector3.js";
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { Collider } from "../../../physics/ecs/Collider.js";
+import { compute_penetration } from "../../../physics/narrowphase/compute_penetration.js";
+import { PhysicsSurfacePoint } from "../../../physics/queries/PhysicsSurfacePoint.js";
+
+/**
+ * Maximum simultaneous clip planes tracked within a single slide,
+ * matching Quake's `MAX_CLIP_PLANES`. A move that contacts more than
+ * this many distinct planes in one tick is in pathological geometry
+ * (a cone of inward-pointing walls); we dead-stop rather than thrash.
+ * @type {number}
+ */
+const MAX_CLIP_PLANES = 5;
+
+/** Below this speed/length we treat the remaining motion as spent. */
+const MIN_MOVE = 1e-6;
+
+/**
+ * Kinematic character collision solver — Phase 1 (recover +
+ * unified sweep-and-slide). See DESIGN_COLLISION.md.
+ *
+ * The mover is controller-agnostic: it knows about a capsule pose, a
+ * desired velocity, and the physics world. Its job is to take the
+ * velocity the control layer wants and return the position it actually
+ * reaches plus the velocity corrected for whatever it hit. It invents
+ * no motion — gravity / jump impulses live in the control layer and
+ * arrive folded into `velocity`.
+ *
+ * One move is a sequence (Phase 1 implements steps 1-2; ground
+ * categorize / stairs / settle land in later phases):
+ *
+ *   1. RECOVER  — depenetration via `overlap()` + `compute_penetration`,
+ *      run unconditionally so the move starts clear even from a
+ *      start-solid state a pure sweep can't escape.
+ *   2. SLIDE    — unified 3D collide-and-slide via `shapeCast`, clipping
+ *      velocity onto true narrowphase contact normals. Crease-aware
+ *      (Quake `SV_FlyMove`): a second plane re-violating the first is
+ *      handled by sliding along their seam; a third (or a velocity
+ *      reversal) dead-stops. Floors / ceilings / walls are all just
+ *      contact planes, so vertical anti-tunnelling is automatic.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class KinematicMover {
+    /**
+     * @param {import("../../../physics/ecs/PhysicsSystem.js").PhysicsSystem} physicsSystem
+     * @param {import("../../../ecs/EntityComponentDataset.js").EntityComponentDataset} ecd
+     *   used to resolve an overlapping `body_id` (via
+     *   `physicsSystem.entityOf`) back to its {@link Transform} +
+     *   {@link Collider} for `compute_penetration`.
+     * @param {object} [options]
+     * @param {number} [options.skin=0.005] clearance left after each
+     *   sweep stop / push-out so the next query doesn't start in contact.
+     * @param {number} [options.maxSlideIterations=4] slide "bumps" per
+     *   move (Quake `numbumps`).
+     * @param {number} [options.maxRecoverIterations=4] depenetration
+     *   passes before giving up (deepest body pushed out per pass).
+     * @param {number} [options.minWalkNormal=0.7] minimum ground-normal Y
+     *   to count as standable (~45.6°). Below it the surface is "too
+     *   steep" — the player slides instead of grounding. Matches Quake3
+     *   `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.
+     *   - 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).
+     *   Source `sv_stepsize` is ~0.34 m; the default is just under the
+     *   capsule radius so low ledges don't feel "magnetic".
+     */
+    constructor(physicsSystem, ecd, options = {}) {
+        this.physicsSystem = physicsSystem;
+        this.ecd = ecd;
+        this.skin = options.skin !== undefined ? options.skin : 0.005;
+        this.maxSlideIterations = options.maxSlideIterations !== undefined ? options.maxSlideIterations : 4;
+        this.maxRecoverIterations = options.maxRecoverIterations !== undefined ? options.maxRecoverIterations : 4;
+        this.minWalkNormal = options.minWalkNormal !== undefined ? options.minWalkNormal : 0.7;
+        this.stepHeight = options.stepHeight !== undefined ? options.stepHeight : 0.3;
+
+        // ── Scratch — reused per move, no per-call allocation ──────────
+        this._ray = new Ray3();
+        this._hit = new PhysicsSurfacePoint();
+        this._overlapBuf = new Uint32Array(16);
+        this._penDir = new Float64Array(3);          // compute_penetration out
+        this._planes = new Float64Array(MAX_CLIP_PLANES * 3);
+        this._cand = new Float64Array(3);            // clipped-velocity candidate
+
+        /**
+         * Reused result. `grounded` / `groundNormal` are Phase 2 outputs;
+         * in Phase 1 they're left at their defaults (the mover doesn't
+         * categorize ground yet).
+         * @type {{hit:boolean, grounded:boolean, groundNormal:Vector3}}
+         */
+        this._result = { hit: false, grounded: false, groundNormal: new Vector3(0, 1, 0) };
+    }
+
+    /**
+     * Resolve one move. Mutates `position` to the resolved location and
+     * `velocity` to the corrected value.
+     *
+     * @param {Vector3} position in/out — current pose, written to the resolved pose
+     * @param {{x:number,y:number,z:number,w:number}} rotation capsule orientation (read)
+     * @param {import("../../../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D} shape convex capsule
+     * @param {Vector3} velocity in/out — desired velocity, written to the corrected velocity
+     * @param {number} dt
+     * @param {(entity:number, collider:Collider)=>boolean} filter excludes
+     *   the player's own body in integration; accept-all in isolation
+     * @returns {{hit:boolean, grounded:boolean, groundNormal:Vector3}} reused result
+     */
+    move(position, rotation, shape, velocity, dt, filter) {
+        const result = this._result;
+        result.hit = false;
+        result.grounded = false;
+        result.groundNormal.set(0, 1, 0);
+
+        // Capture intent-to-leave BEFORE the slide. A positive input
+        // vertical velocity is a jump / launch (the only thing that sets
+        // one — gravity is negative); on those ticks we must NOT
+        // stick-to-ground or the snap cancels the jump on its first
+        // frame. A ramp's upward velocity is produced INSIDE the slide
+        // (the ramp is a contact plane), so it doesn't show up here —
+        // which is exactly why we gate on the pre-slide value.
+        const ascending = velocity.y > MIN_MOVE;
+
+        // 1. Recover — start the move penetration-free.
+        this._recover(position, rotation, shape, filter);
+
+        // Snapshot pre-slide state for a possible stair step-up retry.
+        const sx = position.x, sy = position.y, sz = position.z;
+        const svx = velocity.x, svy = velocity.y, svz = velocity.z;
+
+        // 2. Sweep-and-slide the desired motion.
+        this._slide(position, rotation, shape, velocity, dt, filter, result);
+
+        // 3. Ground categorize + stick + slope velocity clip.
+        this._categorizeGround(position, rotation, shape, velocity, filter, result, ascending);
+
+        return result;
+    }
+
+    /**
+     * Push the capsule out of any geometry it currently overlaps. Each
+     * pass queries overlaps, finds the single deepest penetration via
+     * {@link compute_penetration}, and pushes out along its separation
+     * axis by `depth + skin`; re-queries until clear or the iteration
+     * cap is hit. Deepest-first converges multi-body resting contact
+     * (each pass removes the worst offender) without solving a system.
+     *
+     * @private
+     */
+    _recover(position, rotation, shape, filter) {
+        const physics = this.physicsSystem;
+        const ecd = this.ecd;
+        const buf = this._overlapBuf;
+        const dir = this._penDir;
+
+        for (let iter = 0; iter < this.maxRecoverIterations; iter++) {
+            const n = physics.overlap(shape, position, rotation, buf, 0, filter);
+            if (n === 0) return;
+
+            let bestDepth = 0;
+            let bestX = 0, bestY = 0, bestZ = 0;
+
+            for (let i = 0; i < n; i++) {
+                const bodyId = buf[i];
+                const entity = physics.entityOf(bodyId);
+                if (entity < 0) continue;
+                const otherT = ecd.getComponent(entity, Transform);
+                const otherC = ecd.getComponent(entity, Collider);
+                if (otherT === undefined || otherC === undefined) continue;
+
+                // depth + unit B→A separation (A = our capsule, B = other).
+                const depth = compute_penetration(
+                    dir,
+                    shape, position, rotation,
+                    otherC.shape, otherT.position, otherT.rotation,
+                );
+                if (depth > bestDepth) {
+                    bestDepth = depth;
+                    bestX = dir[0]; bestY = dir[1]; bestZ = dir[2];
+                }
+            }
+
+            // Overlap reported but no actionable depth (touching boundary,
+            // or MPR/overlap disagreement at the kiss) — treat as clear.
+            if (bestDepth <= 0) return;
+
+            const push = bestDepth + this.skin;
+            position._add(bestX * push, bestY * push, bestZ * push);
+        }
+    }
+
+    /**
+     * Unified 3D collide-and-slide. Faithful to Quake's `SV_FlyMove`:
+     * sweep the velocity for the remaining time, stop at contact, clip
+     * the (original) velocity against every plane hit so far, slide
+     * along the seam of a two-plane crease, dead-stop on a third plane
+     * or a velocity reversal.
+     *
+     * @private
+     */
+    _slide(position, rotation, shape, velocity, dt, filter, result) {
+        const physics = this.physicsSystem;
+        const ray = this._ray;
+        const hit = this._hit;
+        const planes = this._planes;
+        const cand = this._cand;
+        const skin = this.skin;
+
+        // Original desired velocity — clipping is always done against
+        // this, not the running value (Quake's invariant; prevents
+        // accumulated rounding from spiralling the direction).
+        const ovx = velocity.x, ovy = velocity.y, ovz = velocity.z;
+        let vx = ovx, vy = ovy, vz = ovz;
+        let timeLeft = dt;
+        let numPlanes = 0;
+
+        for (let bump = 0; bump < this.maxSlideIterations; bump++) {
+            const speed = Math.sqrt(vx * vx + vy * vy + vz * vz);
+            if (speed < MIN_MOVE) break;
+            const len = speed * timeLeft;
+            if (len < MIN_MOVE) break;
+
+            const inv = 1 / speed;
+            const ndx = vx * inv, ndy = vy * inv, ndz = vz * inv;
+
+            ray.setOrigin(position.x, position.y, position.z);
+            ray.setDirection(ndx, ndy, ndz);
+            ray.tMax = len;
+
+            const didHit = physics.shapeCast(ray, shape, rotation, hit, filter);
+
+            if (!didHit) {
+                // Clear path — consume the whole remaining move.
+                position._add(ndx * len, ndy * len, ndz * len);
+                break;
+            }
+
+            // Separating contact: `shapeCast` reports a start-in-contact
+            // hit (t≈0) even when we're moving AWAY from the touched
+            // surface — e.g. jumping off a floor we're resting on, where
+            // the down-normal floor is behind the upward motion. If the
+            // sweep direction points along the outward contact normal
+            // (dir·n ≥ 0) the surface isn't in our way; take the full
+            // remaining move rather than clipping the velocity into it
+            // (which would cancel the jump). A genuine blocker is only
+            // reachable by moving INTO it (dir·n < 0).
+            const dirDotN = ndx * hit.normal.x + ndy * hit.normal.y + ndz * hit.normal.z;
+            if (dirDotN >= 0) {
+                position._add(ndx * len, ndy * len, ndz * len);
+                break;
+            }
+
+            result.hit = true;
+
+            // Advance up to the contact (less skin), and consume the
+            // corresponding fraction of the remaining time.
+            const advance = hit.t - skin > 0 ? hit.t - skin : 0;
+            if (advance > 0) position._add(ndx * advance, ndy * advance, ndz * advance);
+            const fraction = hit.t / len; // time uses the true TOI, not the skinned advance
+            timeLeft -= timeLeft * (fraction > 1 ? 1 : fraction);
+
+            if (numPlanes >= MAX_CLIP_PLANES) {
+                // Too many planes — wedged. Stop.
+                vx = vy = vz = 0;
+                break;
+            }
+            const po = numPlanes * 3;
+            planes[po] = hit.normal.x;
+            planes[po + 1] = hit.normal.y;
+            planes[po + 2] = hit.normal.z;
+            numPlanes++;
+
+            // Re-derive velocity: find a plane the ORIGINAL velocity can
+            // slide along without violating any other plane.
+            let resolved = false;
+            for (let i = 0; i < numPlanes; i++) {
+                const ix = planes[i * 3], iy = planes[i * 3 + 1], iz = planes[i * 3 + 2];
+                this._clip(ovx, ovy, ovz, ix, iy, iz, cand);
+                let ok = true;
+                for (let j = 0; j < numPlanes; j++) {
+                    if (j === i) continue;
+                    const jx = planes[j * 3], jy = planes[j * 3 + 1], jz = planes[j * 3 + 2];
+                    if (cand[0] * jx + cand[1] * jy + cand[2] * jz < 0) { ok = false; break; }
+                }
+                if (ok) {
+                    vx = cand[0]; vy = cand[1]; vz = cand[2];
+                    resolved = true;
+                    break;
+                }
+            }
+
+            if (!resolved) {
+                // No single plane works — slide along the crease of two.
+                // (More than two simultaneously-violated planes ⇒ corner;
+                // dead-stop.)
+                if (numPlanes !== 2) {
+                    vx = vy = vz = 0;
+                    break;
+                }
+                const ax = planes[0], ay = planes[1], az = planes[2];
+                const bx = planes[3], by = planes[4], bz = planes[5];
+                // seam = a × b
+                let cx = ay * bz - az * by;
+                let cy = az * bx - ax * bz;
+                let cz = ax * by - ay * bx;
+                const clen = Math.sqrt(cx * cx + cy * cy + cz * cz);
+                if (clen < MIN_MOVE) { vx = vy = vz = 0; break; }
+                const cinv = 1 / clen;
+                cx *= cinv; cy *= cinv; cz *= cinv;
+                const d = cx * ovx + cy * ovy + cz * ovz;
+                vx = cx * d; vy = cy * d; vz = cz * d;
+            }
+
+            // Anti-oscillation: if the new velocity opposes the original
+            // intent, we'd bounce back into the geometry — stop instead.
+            if (vx * ovx + vy * ovy + vz * ovz <= 0) {
+                vx = vy = vz = 0;
+                break;
+            }
+        }
+
+        velocity.set(vx, vy, vz);
+    }
+
+    /**
+     * Ground categorization + stick-to-ground + slope velocity clip.
+     * Probes below the feet to decide grounded-ness, the surface height
+     * to rest on, and the surface normal for the velocity clip.
+     *
+     *   - `ascending` (jumped this tick) → never grounded; skip entirely
+     *     so the snap can't cancel the jump.
+     *   - no surface within `stepHeight` below the feet → airborne.
+     *
+     * Two probes, with a deliberate division of labour that's what makes
+     * stairs AND slopes both work (they're the same steep-normal contact
+     * to a single probe, so one probe can't tell them apart):
+     *
+     *   (A) WALKABILITY + base height — a centre-point RAYCAST. It sees
+     *       the actual planar surface under the feet and ignores both a
+     *       step's convex top EDGE (whose normal is misleadingly steep)
+     *       and a wall's vertical SIDE face. A steep normal here means a
+     *       genuine steep SLOPE → not grounded (slide).
+     *   (B) STEP height — a footprint capsule SHAPECAST. It raises the
+     *       rest height onto a step the leading edge overhangs (which the
+     *       centre ray, aimed behind the riser, misses). Used only when
+     *       it genuinely swept (`hit.t > skin`, not start-solid in a wall)
+     *       and the step is within `stepHeight`.
+     *
+     * Reference point is the capsule bottom (`position.y`), matching the
+     * feet-at-origin player capsule.
+     *
+     * @private
+     */
+    _categorizeGround(position, rotation, shape, velocity, filter, result, ascending) {
+        if (ascending) return; // jump / launch — stay airborne this tick
+
+        const ray = this._ray;
+        const hit = this._hit;
+        const lift = this.stepHeight;                       // probe starts this high above the feet
+        const reach = lift + this.stepHeight + this.skin;   // …down to stepHeight below the feet
+
+        // (A) Centre raycast — walkability + base surface height.
+        ray.setOrigin(position.x, position.y + lift, position.z);
+        ray.setDirection(0, -1, 0);
+        ray.tMax = reach;
+        if (!this.physicsSystem.raycast(ray, hit, filter)) return; // airborne
+        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;
+
+        // (B) Footprint shapecast — mount a step the leading edge overhangs.
+        ray.setOrigin(position.x, position.y + lift, position.z);
+        ray.setDirection(0, -1, 0);
+        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) {
+                surfaceY = stepY;
+            }
+        }
+
+        result.grounded = true;
+
+        // Stick: rest the feet `skin` above the surface (snaps down for a
+        // descent, up onto a step / out of a grazing contact).
+        position.y = surfaceY + this.skin;
+
+        // Clip the into-ground velocity component (gravity on flat ground;
+        // the into-slope part on a ramp), leaving tangential motion.
+        const vdot = velocity.x * nx + velocity.y * ny + velocity.z * nz;
+        if (vdot < 0) {
+            velocity.set(
+                velocity.x - vdot * nx,
+                velocity.y - vdot * ny,
+                velocity.z - vdot * nz,
+            );
+        }
+    }
+
+    /**
+     * `out = v - n·(v·n)` — project `v` onto the plane with unit normal
+     * `n` (overbounce 1.0; clearance handled by `skin`, so no extra
+     * nudge — equivalent in practice to Quake3's `OVERCLIP 1.001`).
+     * @private
+     */
+    _clip(vx, vy, vz, nx, ny, nz, out) {
+        const backoff = vx * nx + vy * ny + vz * nz;
+        out[0] = vx - nx * backoff;
+        out[1] = vy - ny * backoff;
+        out[2] = vz - nz * backoff;
+    }
+}