@woosh/meep-engine 2.145.0 → 2.147.0

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

@@ -94,17 +94,19 @@ 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.
+there.
+
+### Route WallRun through the mover ✅ done
+WallRun used to self-integrate its reduced-gravity model (`position._add`
++ a hand-rolled groundResolver catch), so it got no sweep-and-slide and
+could drift into / off geometry. It now applies its reduced gravity and
+routes the move through the shared `_resolveMotion` (the mover when
+physics is present, else the flat-ground fallback) — same motor as base
+locomotion and Slide. So **every** motion path goes through one collision
+seam now: it can't drift into a wall (the sweep clips it) nor sail off a
+ledge / through a floor the mover would catch. Guard: `WallRun.spec.js`
+"physics: a wall-runner slides along a real wall and is caught by the
+mover's real floor". No remaining collision follow-ups.
 
 ## Other open notes
 

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

@@ -49,10 +49,15 @@
  * @copyright Company Named Limited (c) 2026
  */
 export class LedgeGrab extends Ability {
-    /** @private World-space ledge edge position captured at onActivate. */
-    private _edgeX;
+    /** @private Wall-face anchor (x,z), the face's outward normal (x,z),
+     *  and the top-edge height (y) — captured at onActivate. The hang pose
+     *  is built from the WALL, not from the (possibly oblique) body
+     *  facing, so it stays just outside the wall at any approach angle. */
+    private _anchorX;
+    _anchorZ: number;
+    _nx: number;
+    _nz: number;
     _edgeY: number;
-    _edgeZ: number;
     canActivate(controller: any, runtime: any, sensors: any): boolean;
     onActivate(controller: any, runtime: any): void;
     canInterrupt(): boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"LedgeGrab.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/abilities/LedgeGrab.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH;IAMQ,uEAAuE;IACvE,eAAe;IACf,eAAe;IACf,eAAe;IAGnB,kEAkBC;IAED,gDA8BC;IAED,wBAKC;IAED,wFAwEC;CACJ;wBApMuB,cAAc"}
+{"version":3,"file":"LedgeGrab.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/abilities/LedgeGrab.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH;IAMQ;;;2EAGuE;IACvE,iBAAiB;IACjB,iBAAiB;IACjB,YAAY;IACZ,YAAY;IACZ,eAAe;IAGnB,kEAkBC;IAED,gDAkCC;IAED,wBAKC;IAED,wFA6EC;CACJ;wBAlNuB,cAAc"}

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

@@ -1,199 +1,213 @@
-import { clamp } from "../../../../core/math/clamp.js";
-import { FirstPersonPosture } from "../pose/FirstPersonPosture.js";
-import { Ability } from "./Ability.js";
-
-/**
- * Ledge-grab ability — snap to a forward ledge while descending and hang
- * from it until the player chooses (or is forced) to release.
- *
- * Activation:
- *   - `sensors.ledgeAhead.hit` (a forward+up obstacle probe found a grab-
- *     able edge — typically the same probe mantle uses).
- *   - `runtime.velocityY <= 0` — the player is descending or static. We
- *     don't auto-catch ledges on the way UP — that would feel like the
- *     world is grabbing the player mid-jump.
- *   - `state.airborneTime >= minAirborneTime` — leaves a small window
- *     after takeoff where ledge-grab can't fire, even if the player is
- *     instantly at apex (which would otherwise satisfy `velocityY <= 0`).
- *   - Forward intent (`intent.move.y > 0.1`) — the player must be
- *     committing into the ledge. Walking backwards off an edge shouldn't
- *     auto-catch the lip.
- *
- * Behaviour:
- *   - Body position snaps to a "hang from edge" pose: at the ledge edge
- *     X/Z (with a small back-offset so the body is pulled against the
- *     wall below), and Y offset down by ~bodyHeight so the hands grip
- *     the edge with the body suspended below.
- *   - Velocity is zeroed each tick — the body is parked.
- *   - Exertion rises at `cfg.exertionRiseRate` per second, scaled by
- *     mass. Climbing fatigue: hang too long and the next exit is
- *     forced (a slip).
- *   - Grounded stays false (the player is hanging in air).
- *
- * Exit:
- *   - Jump pressed (rising edge) → mantle-up. Release with a small
- *     upward velocity so mantle's ledgeAhead probe still hits next
- *     tick; mantle (priority 30) then takes over and animates the
- *     climb-onto-surface path.
- *   - Back-intent (`intent.move.y < -0.1`) → drop. Release with zero
- *     velocity; the player falls under base gravity.
- *   - Crouch pressed → drop. Same as back-intent.
- *   - Exertion saturates (`>= 1`) → slip. Release with zero velocity.
- *   - `sensors.ledgeAhead.hit` becomes false → shuffled off the edge.
- *     Release with zero velocity.
- *
- * Priority 40 — above mantle (30), below wall-run (50). Mantle CAN'T
- * preempt an active ledge-grab — that's the point of placing ledge
- * higher. Otherwise mantle would fire mid-hang and snap the body away.
- * Wall-run and wall-jump can preempt — but in practice they need lateral
- * walls + speed (wall-run) or a jump press near a side wall (wall-jump),
- * conditions which rarely hold while hanging.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class LedgeGrab extends Ability {
-    constructor() {
-        super();
-        this.name = "LedgeGrab";
-        this.priority = 40;
-
-        /** @private World-space ledge edge position captured at onActivate. */
-        this._edgeX = 0;
-        this._edgeY = 0;
-        this._edgeZ = 0;
-    }
-
-    canActivate(controller, runtime, sensors) {
-        const cfg = controller.config.ledgeGrab;
-        if (!cfg) return false;
-        if (sensors === undefined || sensors === null) return false;
-
-        if (!sensors.ledgeAhead.hit) return false;
-        if (runtime.velocityY > 0) return false; // not on the way up
-        if (controller.state.grounded) return false;
-        if (controller.state.airborneTime < cfg.minAirborneTime) return false;
-        if (controller.intent.move.y < 0.1) return false;
-        // Crouch or exhausted: don't re-grab. These are the same exit
-        // conditions that would IMMEDIATELY release after activation, so
-        // gating them here prevents a same-tick re-activation flicker
-        // after a crouch-release or slip.
-        if (controller.intent.crouch) return false;
-        if (controller.state.exertion >= 1.0) return false;
-
-        return true;
-    }
-
-    onActivate(controller, runtime) {
-        const sensors = runtime.sensors;
-        const edge = sensors.ledgeAhead.point;
-
-        this._edgeX = edge.x;
-        this._edgeY = edge.y;
-        this._edgeZ = edge.z;
-
-        // Zero velocity — the body is now parked on the ledge.
-        runtime.velocityX = 0;
-        runtime.velocityY = 0;
-        runtime.velocityZ = 0;
-
-        // Clear any in-progress jump state — hanging supersedes them.
-        runtime.midJump = false;
-        runtime.apexFired = false;
-        controller.state.isVariableJumpCut = false;
-        controller.state.isAscending = false;
-
-        // The body is hanging — not on the ground.
-        controller.state.grounded = false;
-
-        // Body is suspended by the hands; no striding feet, head near
-        // the hands gripping the edge. L2 reads posture to gate gait
-        // and set eye height.
-        controller.state.posture = FirstPersonPosture.Hang;
-
-        controller.signals.onLedgeGrab.send1({
-            ledgeHeight: this._edgeY - controller.pose.rootPosition.y,
-        });
-    }
-
-    canInterrupt() {
-        // Wall-run / wall-jump can preempt if their conditions
-        // somehow hold (unusual mid-hang). Higher-priority abilities
-        // shouldn't be blocked.
-        return true;
-    }
-
-    tick(controller, runtime, bodyTransform, dt, _system) {
-        const cfg = controller.config.ledgeGrab;
-        const sensors = runtime.sensors;
-
-        // Re-assert posture each tick (defence against any layer
-        // resetting it before L2 reads).
-        controller.state.posture = FirstPersonPosture.Hang;
-        // Body is parked against the wall under the ledge — no lean.
-        runtime.leanTargetRad = 0;
-
-        // -- Exit: lost the ledge (shuffled past the edge, ledge ended).
-        if (!sensors.ledgeAhead.hit) {
-            controller.signals.onLedgeRelease.send1({ reason: "shuffle-off" });
-            return false;
-        }
-
-        // -- Exit: jump rising-edge → mantle-up. Apply small upward
-        // velocity so the next tick's mantle.canActivate finds an
-        // obstacleAhead + ledgeAhead at the right relative height.
-        if (controller.intent.jump && !runtime.prevJumpHeld) {
-            runtime.velocityY = runtime.jumpInitialVy * cfg.mantleUpUpFactor;
-            runtime.prevJumpHeld = true;
-            runtime.midJump = true;
-            controller.state.isAscending = true;
-            controller.signals.onLedgeRelease.send1({ reason: "mantle-up" });
-            return false;
-        }
-
-        // -- Exit: back-intent → drop. Zero velocity (let gravity take over
-        // on the next tick).
-        if (controller.intent.move.y < -0.1) {
-            controller.signals.onLedgeRelease.send1({ reason: "drop" });
-            return false;
-        }
-
-        // -- Exit: crouch → drop.
-        if (controller.intent.crouch) {
-            controller.signals.onLedgeRelease.send1({ reason: "drop" });
-            return false;
-        }
-
-        // -- Exit: exertion saturated → slip.
-        if (controller.state.exertion >= 1.0) {
-            controller.signals.onLedgeRelease.send1({ reason: "slip" });
-            return false;
-        }
-
-        // -- Hold: snap to hang position, zero velocity, tick exertion.
-        // Pull the body slightly back from the ledge edge along the
-        // body's forward direction so it visually grips the lip rather
-        // than sitting directly on it.
-        const fx = Math.sin(runtime.bodyYaw);
-        const fz = Math.cos(runtime.bodyYaw);
-        bodyTransform.position.set(
-            this._edgeX + fx * cfg.hangOffsetForward,
-            this._edgeY + cfg.hangOffsetY,
-            this._edgeZ + fz * cfg.hangOffsetForward,
-        );
-        runtime.velocityX = 0;
-        runtime.velocityY = 0;
-        runtime.velocityZ = 0;
-        controller.state.grounded = false;
-
-        // Exertion rises while hanging — fatigue. Mass-scaled like the
-        // rest of the exertion system.
-        controller.state.exertion = clamp(
-            controller.state.exertion + cfg.exertionRiseRate * dt
-                * runtime.massRatios.exertionRiseScale,
-            0, 1,
-        );
-
-        return true;
-    }
-}
+import { clamp } from "../../../../core/math/clamp.js";
+import { FirstPersonPosture } from "../pose/FirstPersonPosture.js";
+import { Ability } from "./Ability.js";
+
+/**
+ * Ledge-grab ability — snap to a forward ledge while descending and hang
+ * from it until the player chooses (or is forced) to release.
+ *
+ * Activation:
+ *   - `sensors.ledgeAhead.hit` (a forward+up obstacle probe found a grab-
+ *     able edge — typically the same probe mantle uses).
+ *   - `runtime.velocityY <= 0` — the player is descending or static. We
+ *     don't auto-catch ledges on the way UP — that would feel like the
+ *     world is grabbing the player mid-jump.
+ *   - `state.airborneTime >= minAirborneTime` — leaves a small window
+ *     after takeoff where ledge-grab can't fire, even if the player is
+ *     instantly at apex (which would otherwise satisfy `velocityY <= 0`).
+ *   - Forward intent (`intent.move.y > 0.1`) — the player must be
+ *     committing into the ledge. Walking backwards off an edge shouldn't
+ *     auto-catch the lip.
+ *
+ * Behaviour:
+ *   - Body position snaps to a "hang from edge" pose: at the ledge edge
+ *     X/Z (with a small back-offset so the body is pulled against the
+ *     wall below), and Y offset down by ~bodyHeight so the hands grip
+ *     the edge with the body suspended below.
+ *   - Velocity is zeroed each tick — the body is parked.
+ *   - Exertion rises at `cfg.exertionRiseRate` per second, scaled by
+ *     mass. Climbing fatigue: hang too long and the next exit is
+ *     forced (a slip).
+ *   - Grounded stays false (the player is hanging in air).
+ *
+ * Exit:
+ *   - Jump pressed (rising edge) → mantle-up. Release with a small
+ *     upward velocity so mantle's ledgeAhead probe still hits next
+ *     tick; mantle (priority 30) then takes over and animates the
+ *     climb-onto-surface path.
+ *   - Back-intent (`intent.move.y < -0.1`) → drop. Release with zero
+ *     velocity; the player falls under base gravity.
+ *   - Crouch pressed → drop. Same as back-intent.
+ *   - Exertion saturates (`>= 1`) → slip. Release with zero velocity.
+ *   - `sensors.ledgeAhead.hit` becomes false → shuffled off the edge.
+ *     Release with zero velocity.
+ *
+ * Priority 40 — above mantle (30), below wall-run (50). Mantle CAN'T
+ * preempt an active ledge-grab — that's the point of placing ledge
+ * higher. Otherwise mantle would fire mid-hang and snap the body away.
+ * Wall-run and wall-jump can preempt — but in practice they need lateral
+ * walls + speed (wall-run) or a jump press near a side wall (wall-jump),
+ * conditions which rarely hold while hanging.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class LedgeGrab extends Ability {
+    constructor() {
+        super();
+        this.name = "LedgeGrab";
+        this.priority = 40;
+
+        /** @private Wall-face anchor (x,z), the face's outward normal (x,z),
+         *  and the top-edge height (y) — captured at onActivate. The hang pose
+         *  is built from the WALL, not from the (possibly oblique) body
+         *  facing, so it stays just outside the wall at any approach angle. */
+        this._anchorX = 0;
+        this._anchorZ = 0;
+        this._nx = 0;
+        this._nz = 0;
+        this._edgeY = 0;
+    }
+
+    canActivate(controller, runtime, sensors) {
+        const cfg = controller.config.ledgeGrab;
+        if (!cfg) return false;
+        if (sensors === undefined || sensors === null) return false;
+
+        if (!sensors.ledgeAhead.hit) return false;
+        if (runtime.velocityY > 0) return false; // not on the way up
+        if (controller.state.grounded) return false;
+        if (controller.state.airborneTime < cfg.minAirborneTime) return false;
+        if (controller.intent.move.y < 0.1) return false;
+        // Crouch or exhausted: don't re-grab. These are the same exit
+        // conditions that would IMMEDIATELY release after activation, so
+        // gating them here prevents a same-tick re-activation flicker
+        // after a crouch-release or slip.
+        if (controller.intent.crouch) return false;
+        if (controller.state.exertion >= 1.0) return false;
+
+        return true;
+    }
+
+    onActivate(controller, runtime) {
+        const sensors = runtime.sensors;
+
+        // Anchor on the wall face + its outward normal (ledgeAhead is only
+        // probed when obstacleAhead hits, so the face data is always present
+        // here). The top-edge height comes from the ledge probe.
+        this._anchorX = sensors.obstacleAhead.point.x;
+        this._anchorZ = sensors.obstacleAhead.point.z;
+        this._nx = sensors.obstacleAhead.normal.x;
+        this._nz = sensors.obstacleAhead.normal.z;
+        this._edgeY = sensors.ledgeAhead.point.y;
+
+        // Zero velocity — the body is now parked on the ledge.
+        runtime.velocityX = 0;
+        runtime.velocityY = 0;
+        runtime.velocityZ = 0;
+
+        // Clear any in-progress jump state — hanging supersedes them.
+        runtime.midJump = false;
+        runtime.apexFired = false;
+        controller.state.isVariableJumpCut = false;
+        controller.state.isAscending = false;
+
+        // The body is hanging — not on the ground.
+        controller.state.grounded = false;
+
+        // Body is suspended by the hands; no striding feet, head near
+        // the hands gripping the edge. L2 reads posture to gate gait
+        // and set eye height.
+        controller.state.posture = FirstPersonPosture.Hang;
+
+        controller.signals.onLedgeGrab.send1({
+            ledgeHeight: this._edgeY - controller.pose.rootPosition.y,
+        });
+    }
+
+    canInterrupt() {
+        // Wall-run / wall-jump can preempt if their conditions
+        // somehow hold (unusual mid-hang). Higher-priority abilities
+        // shouldn't be blocked.
+        return true;
+    }
+
+    tick(controller, runtime, bodyTransform, dt, _system) {
+        const cfg = controller.config.ledgeGrab;
+        const sensors = runtime.sensors;
+
+        // Re-assert posture each tick (defence against any layer
+        // resetting it before L2 reads).
+        controller.state.posture = FirstPersonPosture.Hang;
+        // Body is parked against the wall under the ledge — no lean.
+        runtime.leanTargetRad = 0;
+
+        // -- Exit: lost the ledge (shuffled past the edge, ledge ended).
+        if (!sensors.ledgeAhead.hit) {
+            controller.signals.onLedgeRelease.send1({ reason: "shuffle-off" });
+            return false;
+        }
+
+        // -- Exit: jump rising-edge → mantle-up. Apply small upward
+        // velocity so the next tick's mantle.canActivate finds an
+        // obstacleAhead + ledgeAhead at the right relative height.
+        // (On a top too thin to STAND on, mantle is gated, so this currently
+        // just bumps you up and re-grabs — a clean "pull up & OVER" there
+        // needs a scripted vault, tracked as a follow-up.)
+        if (controller.intent.jump && !runtime.prevJumpHeld) {
+            runtime.velocityY = runtime.jumpInitialVy * cfg.mantleUpUpFactor;
+            runtime.prevJumpHeld = true;
+            runtime.midJump = true;
+            controller.state.isAscending = true;
+            controller.signals.onLedgeRelease.send1({ reason: "mantle-up" });
+            return false;
+        }
+
+        // -- Exit: back-intent → drop. Zero velocity (let gravity take over
+        // on the next tick).
+        if (controller.intent.move.y < -0.1) {
+            controller.signals.onLedgeRelease.send1({ reason: "drop" });
+            return false;
+        }
+
+        // -- Exit: crouch → drop.
+        if (controller.intent.crouch) {
+            controller.signals.onLedgeRelease.send1({ reason: "drop" });
+            return false;
+        }
+
+        // -- Exit: exertion saturated → slip.
+        if (controller.state.exertion >= 1.0) {
+            controller.signals.onLedgeRelease.send1({ reason: "slip" });
+            return false;
+        }
+
+        // -- Hold: snap to hang position, zero velocity, tick exertion.
+        // Hang just OUTSIDE the wall face, gripping the top edge: the body
+        // centre sits a capsule radius (+ a small face gap) out from the face
+        // along its outward normal. Anchoring on the wall — not the body's
+        // facing — keeps the body clear of the wall even when the ledge was
+        // reached at an oblique angle (e.g. off a wall-run into the wall),
+        // where a facing-relative offset would sink it into a thin wall.
+        const standoff = controller.config.body.radius + cfg.hangOffsetForward;
+        bodyTransform.position.set(
+            this._anchorX + this._nx * standoff,
+            this._edgeY + cfg.hangOffsetY,
+            this._anchorZ + this._nz * standoff,
+        );
+        runtime.velocityX = 0;
+        runtime.velocityY = 0;
+        runtime.velocityZ = 0;
+        controller.state.grounded = false;
+
+        // Exertion rises while hanging — fatigue. Mass-scaled like the
+        // rest of the exertion system.
+        controller.state.exertion = clamp(
+            controller.state.exertion + cfg.exertionRiseRate * dt
+                * runtime.massRatios.exertionRiseScale,
+            0, 1,
+        );
+
+        return true;
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"Mantle.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/abilities/Mantle.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAOQ,6CAA6C;IAC7C,WAAW;IACX,uCAAuC;IACvC,kBAAoB;IACpB,gBAAgB;IAChB,gBAAgB;IAChB,gBAAgB;IAChB,cAAc;IACd,cAAc;IACd,cAAc;IAGlB,kEAwBC;IAED,gDAyCC;IAED,wBAGC;IAED,wFAwCC;IAED,oDAEC;CACJ;wBA1LuB,cAAc"}
+{"version":3,"file":"Mantle.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/abilities/Mantle.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAOQ,6CAA6C;IAC7C,WAAW;IACX,uCAAuC;IACvC,kBAAoB;IACpB,gBAAgB;IAChB,gBAAgB;IAChB,gBAAgB;IAChB,cAAc;IACd,cAAc;IACd,cAAc;IAGlB,kEA+BC;IAED,gDAyCC;IAED,wBAGC;IAED,wFAwCC;IAED,oDAEC;CACJ;wBAjMuB,cAAc"}