@woosh/meep-engine 2.143.0 → 2.145.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/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

@@ -0,0 +1,206 @@
+/**
+ * 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: 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).
+     *   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;
+    _support: 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;
+    };
+    /**
+     * 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
+     * {@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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}