@woosh/meep-engine 2.155.0 → 2.157.0

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

@@ -23,6 +23,7 @@ import { PhysicsSurfacePoint } from "../../physics/queries/PhysicsSurfacePoint.j
 import { FirstPersonPlayerController } from "./FirstPersonPlayerController.js";
 import { DecisionPoint } from "./mastery/DecisionPoint.js";
 import { computeJumpFromApex } from "./math/computeJumpFromApex.js";
+import { jumpForceForHeight, launchVelocityForForce } from "./math/jumpDynamics.js";
 import { computeLRCBreathRate } from "./math/computeLRCBreathRate.js";
 import { computeMassRatios } from "./math/computeMassRatios.js";
 import { Spring } from "./math/Spring.js";
@@ -143,6 +144,26 @@ class PerEntityRuntime {
         /** Yaw rate (rad/s) computed in look consumption — for evaluators. */
         this.yawRateRadPerSec = 0;
 
+        // -- Render-rate look + position interpolation ---------------------
+        // The camera DIRECTION (yaw/pitch) is consumed at RENDER rate (see the
+        // controller's _consumeLook), so it tracks the mouse smoothly instead of
+        // being aliased by the 60Hz sim sampling — consuming the accumulated
+        // mouse delta once per fixed step beats against an unaligned mouse
+        // report rate and makes a slow turn lurch (the reported snap). The body
+        // POSITION still advances only at the fixed step, so it's blended
+        // between the last two steps by the sub-step alpha to stay smooth on a
+        // high-refresh display.
+        /** Body yaw at the end of the previous fixed step — used to derive the
+         *  per-step turn RATE that drives look-lean, decoupled from per-frame
+         *  input jitter. */
+        this.prevFixedYaw = 0;
+        this.renderPrevPos = new Vector3();
+        this.renderCurPos = new Vector3();
+        /** When true, the next position snapshot collapses prev=cur (no blend)
+         *  — set on a body teleport (e.g. the ledge-grab hang snap) so the
+         *  camera doesn't glide across the jump. */
+        this.renderSnap = false;
+
         /** Horizontal+vertical velocity. We integrate these inside the system
          *  when no external physics layer is attached. */
         this.velocityX = 0;
@@ -160,6 +181,13 @@ class PerEntityRuntime {
         this.anticipationRemaining = 0;
         /** Cached derived gravity (m/s^2) from peakHeight + timeToApex. */
         this.gravity = 9.81;
+        /**
+         * Cached jump PUSH-OFF FORCE (newtons) — the physical leg force that
+         * reaches `peakHeight` at the reference mass, the quantity jump power is
+         * expressed in. Derived at link via {@link jumpForceForHeight}; abilities
+         * (e.g. the scramble wall-kick) launch off this same force.
+         */
+        this.jumpForce = 0;
         /** Cached derived jump impulse (m/s upward), post-mass-scaling. */
         this.jumpInitialVy = 5.0;
         /**
@@ -299,6 +327,23 @@ class PerEntityRuntime {
 
         /** Cached eye entity ID. -1 until link assigns it. */
         this.eyeEntity = -1;
+
+        /**
+         * One-shot hand-off flag: LedgeGrab sets it on a pull-up release so
+         * Mantle (next tick) knows this is a ledge pull-up — it then allows a
+         * too-thin top (auto-mantle still requires a standable one) and vaults
+         * OVER instead of onto. Mantle consumes it in onActivate.
+         */
+        this.ledgePullUpRequest = false;
+
+        /**
+         * Seconds remaining in the post-release ledge re-grab refractory
+         * window. Set by {@link LedgeGrab} on deactivation, aged down by dt
+         * each fixed step, and read by LedgeGrab.canActivate — so a deliberate
+         * dismount can fall clear of the grab window without the auto-catch
+         * snapping the body straight back onto the same lip.
+         */
+        this.ledgeRegrabCooldown = 0;
     }
 }
 
@@ -491,7 +536,21 @@ export class FirstPersonPlayerControllerSystem extends System {
         const derived = { gravity: 0, initialVelocity: 0 };
         computeJumpFromApex(controller.config.jump.peakHeight, controller.config.jump.timeToApex, derived);
         runtime.gravity = derived.gravity;
-        runtime.jumpInitialVy = derived.initialVelocity * runtime.massRatios.jumpV0Scale;
+        // Express jump power as a physical push-off FORCE (newtons): the force the
+        // legs deliver to reach peakHeight at the REFERENCE mass. Stored so other
+        // moves (the scramble wall-kick) can launch off the SAME force.
+        const bodyCfg = controller.config.body;
+        runtime.jumpForce = jumpForceForHeight(
+            bodyCfg.referenceMass, runtime.gravity, bodyCfg.jumpPushoffDistance, controller.config.jump.peakHeight,
+        );
+        // Force → launch velocity for the reference body (== √(2·g·peakHeight)),
+        // then the mass-coupling dial (jumpV0Scale ∝ 1/√mass, modulated by
+        // massCouplingStrength) scales it for the actual body. Identical result
+        // to the prior `derived.initialVelocity · jumpV0Scale`, now routed
+        // through the force so jump power has a single physical source.
+        runtime.jumpInitialVy =
+            launchVelocityForForce(runtime.jumpForce, bodyCfg.referenceMass, bodyCfg.jumpPushoffDistance)
+            * runtime.massRatios.jumpV0Scale;
 
         // Seed yaw from the starting body rotation. `toEulerAnglesYXZ`
         // returns (pitch, yaw, roll) — we only care about y.
@@ -499,6 +558,11 @@ export class FirstPersonPlayerControllerSystem extends System {
         runtime.bodyYaw = SCRATCH_V3_A.y;
         runtime.eyePitch = 0;
 
+        // Seed render-rate-look + position-interpolation state to the spawn pose.
+        runtime.prevFixedYaw = runtime.bodyYaw;
+        runtime.renderPrevPos.copy(bodyTransform.position);
+        runtime.renderCurPos.copy(bodyTransform.position);
+
         // Initialize springs to standing-eye-height baseline
         runtime.eyeHeightSpring.settle(controller.config.body.height);
         runtime.fovSpring.settle(controller.config.fov.base);
@@ -610,42 +674,24 @@ export class FirstPersonPlayerControllerSystem extends System {
         // independently ages all samples).
         controller.mastery.tick(dt);
 
-        // -- L1.a: Consume look delta -----------------------------------
-        // intent.look is zeroed after consume so accumulated input doesn't
-        // re-apply on the next fixed step.
-        //
-        // Conventions (with raw mouse delta as the source — movementX/Y both
-        // positive when moving right/down):
-        //   look.x > 0 ("mouse right")  → turn right
-        //   look.y > 0 ("mouse down")   → look down  (flipped by invertY)
-        //
-        // The yaw sign is negated because the engine uses left-handed
-        // coordinates with +Z as forward; a positive Y-axis rotation takes
-        // +Z toward +X, which presents to the player as a LEFT turn through
-        // the Three.js camera (`quaternion_invert_orientation`). Negating
-        // here gives the player-intuitive "mouse right → turn right".
-        const yawDelta = -intent.look.x;
-        const pitchSign = cfg.look.invertY ? -1 : 1;
-        const pitchDelta = intent.look.y * pitchSign;
-        intent.look.set(0, 0);
-
-        // Cache yaw rate for mastery evaluators (look-lean, foot-asymmetry-
-        // turn, etc.). Rad/s, signed (negative = turning right in our
-        // convention — matches yawDelta).
-        runtime.yawRateRadPerSec = yawDelta / Math.max(dt, 1e-4);
-
-        runtime.bodyYaw += yawDelta;
-        // keep yaw bounded (purely cosmetic — sin/cos handle wraparound fine)
-        if (runtime.bodyYaw > Math.PI) runtime.bodyYaw -= TWO_PI;
-        else if (runtime.bodyYaw < -Math.PI) runtime.bodyYaw += TWO_PI;
-
-        runtime.eyePitch = clamp(
-            runtime.eyePitch + pitchDelta,
-            cfg.look.pitchMinDeg * DEG_TO_RAD,
-            cfg.look.pitchMaxDeg * DEG_TO_RAD,
-        );
-
-        // Write body yaw back to transform (pure yaw, no pitch on body)
+        // -- L1.a: Derive the per-step turn rate ------------------------
+        // Look (yaw/pitch) is consumed at RENDER rate in {@link _consumeLook} so
+        // the camera tracks the mouse without 60Hz aliasing — consuming the
+        // accumulated mouse delta once per fixed step beats against an unaligned
+        // mouse report rate and makes a slow turn lurch (the reported snap).
+        // fixedUpdate reads the latest yaw and derives the per-fixed-step turn
+        // RATE for look-lean + the turn evaluators, from the yaw change since the
+        // previous step (shortest-arc across the ±π wrap) — smooth and decoupled
+        // from per-frame input jitter.
+        let yawStep = runtime.bodyYaw - runtime.prevFixedYaw;
+        if (yawStep > Math.PI) yawStep -= TWO_PI;
+        else if (yawStep < -Math.PI) yawStep += TWO_PI;
+        runtime.yawRateRadPerSec = yawStep / Math.max(dt, 1e-4);
+        runtime.prevFixedYaw = runtime.bodyYaw;
+
+        // Write body yaw back to the transform (pure yaw, no pitch on body) —
+        // the collision sweep + sensors use it. The camera uses runtime.bodyYaw
+        // directly, which _consumeLook keeps current at render rate.
         bodyTransform.rotation.fromAxisAngle(Vector3.up, runtime.bodyYaw);
 
         // -- Shared flags. Computed BEFORE the ability tick so abilities
@@ -661,6 +707,13 @@ export class FirstPersonPlayerControllerSystem extends System {
         // L2 observers read sinYaw/cosYaw as locals — destructure once.
         const { sinYaw, cosYaw } = runtime;
 
+        // Age the ledge re-grab refractory window (dt-driven). Decremented
+        // BEFORE the ability layer so LedgeGrab.canActivate sees the current
+        // value; it gates the auto-catch for a beat after any dismount.
+        if (runtime.ledgeRegrabCooldown > 0) {
+            runtime.ledgeRegrabCooldown = Math.max(0, runtime.ledgeRegrabCooldown - dt);
+        }
+
         // -- Ability layer: at most one active ability owns motion. The
         //    set returns true when no ability owned the tick, in which
         //    case base L1.b-h runs below; false means an ability fully
@@ -670,6 +723,13 @@ export class FirstPersonPlayerControllerSystem extends System {
             controller, runtime, bodyTransform, runtime.sensors, dt, this,
         );
 
+        // The ledge-pull-up request is set and consumed WITHIN abilities.tick
+        // (LedgeGrab release → Mantle activation, same call). Clear it here as
+        // a safety net so a pull-up that didn't activate a mantle can't leak
+        // the flag into a later auto-mantle (which would let it vault a thin
+        // wall it should have refused).
+        runtime.ledgePullUpRequest = false;
+
         // Now resolve crouch (updates prevCrouchHeld) — used by base and L2.
         // Headroom-aware: force-keeps the player crouched under an overhang.
         const isCrouchActive = this._resolveCrouchHeld(controller, runtime, bodyTransform);
@@ -977,13 +1037,21 @@ export class FirstPersonPlayerControllerSystem extends System {
             wantsCrouch = intent.crouch;
         }
 
-        // Headroom override: a player who wants to STAND but has an
-        // overhang above (the Stand collider won't fit) is force-kept
-        // crouched until they clear it. Without this, growing the
-        // collider into the overhang makes the next tick's
-        // depenetration shove the player out the bottom — through the
-        // floor. `crouchBlocked` records the override for HUD / camera.
-        if (!wantsCrouch) {
+        // Headroom override — block UN-crouching under an overhang. A player who
+        // is ALREADY low (crouched or prone) and wants to stand is force-kept
+        // crouched while the Stand collider won't fit: letting it grow into the
+        // overhang would have the next tick's depenetration shove the player out
+        // the bottom, through the floor. `crouchBlocked` records this for HUD /
+        // camera.
+        //
+        // Crucially this fires ONLY when already low. A STANDING player who walks
+        // under a low ceiling is NEVER auto-pushed down into a crouch — their
+        // full-height capsule simply can't fit, so the mover blocks their forward
+        // motion instead. "If I can't clear it, I don't move forward." Dropping
+        // posture is the player's choice (press crouch), not the ceiling's.
+        const alreadyLow = runtime.lastPosture === FirstPersonPosture.Crouch
+            || runtime.lastPosture === FirstPersonPosture.Prone;
+        if (!wantsCrouch && alreadyLow) {
             const growDelta = runtime.standTop - runtime.crouchTop;
             if (!this._hasHeadroomToGrow(runtime, bodyTransform, runtime.colliderShapeCrouch, growDelta)) {
                 state.crouchBlocked = true;
@@ -1107,7 +1175,12 @@ export class FirstPersonPlayerControllerSystem extends System {
                 );
 
                 sig.onJumpStart.send1({ peakHeight: cfg.jump.peakHeight });
-                sig.onLeaveGround.send1({ reason: "jump" });
+                // NOTE: onLeaveGround is fired by the motor (_onLeaveGround)
+                // when the move actually breaks ground contact this same tick —
+                // with reason "jump" since midJump is now true. Firing it here
+                // too double-sent the signal on every grounded jump (and a
+                // spurious second "jump" leave on a coyote jump, which already
+                // left ground on the walk-off). Let the motor own it.
             }
         }
     }
@@ -1474,12 +1547,15 @@ export class FirstPersonPlayerControllerSystem extends System {
         let posture = isCrouchActive
             ? FirstPersonPosture.Crouch
             : FirstPersonPosture.Stand;
-        // Headroom floor: if even the Crouch collider can't fit under the
-        // overhang (a space lower than crouch height — e.g. a slide
-        // tunnel the player crawled / slid into), drop one more to Prone.
-        // Uses the post-move position, so it reflects where the player
-        // actually ended up this tick.
-        if (posture === FirstPersonPosture.Crouch) {
+        // Headroom floor — block UN-proning under a very low overhang. Only an
+        // ALREADY-prone body (e.g. one that slid into a crawl-height tunnel) is
+        // force-kept prone while the Crouch collider can't fit above it. A player
+        // merely crouching by intent is NOT auto-dropped to prone when they meet
+        // a lower overhang — same rule as above: the mover blocks their forward
+        // motion instead of the ceiling shoving them down. Uses the post-move
+        // position, so it reflects where the body actually ended up this tick.
+        if (posture === FirstPersonPosture.Crouch
+            && runtime.lastPosture === FirstPersonPosture.Prone) {
             const proneGrow = runtime.crouchTop - runtime.proneTop;
             if (!this._hasHeadroomToGrow(runtime, bodyTransform, runtime.colliderShapeProne, proneGrow)) {
                 posture = FirstPersonPosture.Prone;
@@ -1622,6 +1698,104 @@ export class FirstPersonPlayerControllerSystem extends System {
         pose.postureAmount = clamp((cfg.body.height - state.eyeHeight) / postureSpan, 0, 1);
 
         pose.aimPitch = runtime.eyePitch;
+
+        this._assertTickInvariants(controller, runtime, bodyTransform);
+        this._snapshotRenderPose(runtime, bodyTransform);
+    }
+
+    /**
+     * Record this fixed step's authoritative body position as the latest
+     * render-interpolation endpoint, shifting the old latest to "previous".
+     * {@link _composeEye} blends prev→cur by the sub-step alpha so the camera
+     * position is smooth at any refresh rate. (Yaw/pitch aren't snapshotted —
+     * they're render-rate.) On a teleport (`renderSnap`), prev and cur collapse
+     * to the new position so the camera jumps rather than gliding across it.
+     * @private
+     */
+    _snapshotRenderPose(runtime, bodyTransform) {
+        const p = bodyTransform.position;
+        if (runtime.renderSnap) {
+            runtime.renderSnap = false;
+            runtime.renderPrevPos.set(p.x, p.y, p.z);
+            runtime.renderCurPos.set(p.x, p.y, p.z);
+            return;
+        }
+        runtime.renderPrevPos.copy(runtime.renderCurPos);
+        runtime.renderCurPos.set(p.x, p.y, p.z);
+    }
+
+    /**
+     * Dev-only invariant guard (meep asserts compile out of prod, so this is
+     * free there). Catches the class of corruption that surfaces as an
+     * unexplained camera "snap": a NaN/Infinity leaking into the yaw/pitch the
+     * eye composes from, or into the body's velocity / position. Runs once at
+     * the END of every fixed step, so a bad value is caught the tick it appears
+     * — naming the layer that produced it — instead of manifesting as a camera
+     * jump frames (or seconds) later when something finally reads it.
+     * @private
+     */
+    _assertTickInvariants(controller, runtime, bodyTransform) {
+        const p = bodyTransform.position;
+        assert.ok(Number.isFinite(runtime.bodyYaw),
+            "FP invariant: runtime.bodyYaw is non-finite (camera yaw corrupted)");
+        assert.ok(Number.isFinite(runtime.eyePitch),
+            "FP invariant: runtime.eyePitch is non-finite (camera pitch corrupted)");
+        assert.ok(Number.isFinite(controller.state.leanRollRad),
+            "FP invariant: state.leanRollRad is non-finite (camera roll corrupted)");
+        assert.ok(
+            Number.isFinite(runtime.velocityX)
+            && Number.isFinite(runtime.velocityY)
+            && Number.isFinite(runtime.velocityZ),
+            "FP invariant: runtime.velocity is non-finite",
+        );
+        assert.ok(
+            Number.isFinite(p.x) && Number.isFinite(p.y) && Number.isFinite(p.z),
+            "FP invariant: body position is non-finite",
+        );
+    }
+
+    /**
+     * Consume the accumulated mouse-look delta into body yaw + eye pitch at
+     * RENDER rate (once per render frame, from {@link _composeEye}). This is the
+     * fix for the slow-turn camera snap: sampling `intent.look` at the 60Hz
+     * fixed step aliases an unaligned mouse report rate into an uneven turn,
+     * whereas consuming it every render frame tracks the mouse as smoothly as it
+     * arrives. `intent.look` is zeroed after consuming so the same delta isn't
+     * re-applied next frame.
+     *
+     * Conventions (raw mouse delta source — movementX/Y positive moving
+     * right/down): look.x > 0 ("mouse right") → turn right (the yaw sign is
+     * negated because the engine is left-handed with +Z forward, so a +Y
+     * rotation reads as a LEFT turn through the camera); look.y > 0 → look down,
+     * flipped by invertY.
+     * @private
+     */
+    _consumeLook(controller, runtime) {
+        const intent = controller.intent;
+        const cfg = controller.config;
+        let yawDelta = -intent.look.x;
+        const pitchSign = cfg.look.invertY ? -1 : 1;
+        let pitchDelta = intent.look.y * pitchSign;
+        intent.look.set(0, 0);
+
+        // Reject input SPIKES. A single render frame's look delta beyond a sane
+        // bound is a corrupt browser/driver `movementX` (a high-res mouse under
+        // OS pointer acceleration, or a pointer-lock burst), not a real turn —
+        // applying it snaps the camera 20–100°. Drop the spiking axis; legit
+        // turns (even fast flicks) stay well under the bound at render rate.
+        const maxDelta = cfg.look.maxFrameDeltaRad;
+        if (Math.abs(yawDelta) > maxDelta) yawDelta = 0;
+        if (Math.abs(pitchDelta) > maxDelta) pitchDelta = 0;
+
+        runtime.bodyYaw += yawDelta;
+        if (runtime.bodyYaw > Math.PI) runtime.bodyYaw -= TWO_PI;
+        else if (runtime.bodyYaw < -Math.PI) runtime.bodyYaw += TWO_PI;
+
+        runtime.eyePitch = clamp(
+            runtime.eyePitch + pitchDelta,
+            cfg.look.pitchMinDeg * DEG_TO_RAD,
+            cfg.look.pitchMaxDeg * DEG_TO_RAD,
+        );
     }
 
     /**
@@ -1635,6 +1809,10 @@ export class FirstPersonPlayerControllerSystem extends System {
         const runtime = this.runtime.get(entity);
         if (runtime === undefined) return;
 
+        // Consume mouse-look at RENDER rate so the camera direction tracks the
+        // mouse smoothly, decoupled from the aliased 60Hz sim sampling.
+        this._consumeLook(controller, runtime);
+
         const dt = this._currentRenderDt;
         const cfg = controller.config;
         const state = controller.state;
@@ -1710,11 +1888,23 @@ export class FirstPersonPlayerControllerSystem extends System {
                 : 0;
         stack.push("posture.sprintShift", 0, 0, cfg.posture.sprintForwardShiftM * sprintShiftFraction);
 
-        // Transform body-local accumulated offset into world space.
+        // Body POSITION advances only at the fixed step → blend the last two
+        // steps by the engine's sub-step alpha (the same fraction the
+        // InterpolationSystem uses for physics bodies) so it's smooth on a high-
+        // refresh display. Yaw + pitch are already render-rate (consumed in
+        // _consumeLook), so they're used directly — no blend, no aliasing.
+        const alpha = this.entityManager.getFixedStepAlpha();
+        const iPosX = lerp(runtime.renderPrevPos.x, runtime.renderCurPos.x, alpha);
+        const iPosY = lerp(runtime.renderPrevPos.y, runtime.renderCurPos.y, alpha);
+        const iPosZ = lerp(runtime.renderPrevPos.z, runtime.renderCurPos.z, alpha);
+        const qYaw0 = SCRATCH_Q_A.fromAxisAngle(Vector3.up, runtime.bodyYaw);
+
+        // Transform body-local accumulated offset into world space (about the
+        // render-rate yaw, to match the interpolated base position).
         const worldOffset = SCRATCH_V3_B.copy(stack.offset);
-        worldOffset.applyQuaternion(bodyTransform.rotation);
+        worldOffset.applyQuaternion(qYaw0);
 
-        eyeTransform.position.copy(bodyTransform.position);
+        eyeTransform.position.set(iPosX, iPosY, iPosZ);
         eyeTransform.position._add(worldOffset.x, worldOffset.y, worldOffset.z);
 
         // -- Eye rotation: body yaw × eye pitch × roll -------------------
@@ -1763,13 +1953,23 @@ export class FirstPersonPlayerControllerSystem extends System {
         // composition: yaw * pitch * roll
         //   pitch around world X — yaw applied after, so effective axis is camera-local right
         //   roll  around world Z — yaw and pitch applied after, so effective axis is camera-local forward
-        const qYaw = SCRATCH_Q_A.fromAxisAngle(Vector3.up, runtime.bodyYaw);
+        const qYaw = qYaw0; // SCRATCH_Q_A, already the render-rate yaw
         const qPitch = SCRATCH_Q_B.fromAxisAngle(Vector3.right, pitchTotal);
         const qRoll = SCRATCH_Q_C.fromAxisAngle(Vector3.forward, rollTotal);
 
         eyeTransform.rotation.multiplyQuaternions(qYaw, qPitch);
         eyeTransform.rotation.multiply(qRoll);
 
+        // Dev-only camera-output guard (compiled out of prod). The composed eye
+        // direction is exactly what the player sees; if a spring (head-droop,
+        // breath nod) or lean ever drove pitch/roll to NaN, the camera would
+        // snap to garbage. Assert it here, at the source of the visible jump.
+        const er = eyeTransform.rotation;
+        assert.ok(
+            Number.isFinite(er.x) && Number.isFinite(er.y) && Number.isFinite(er.z) && Number.isFinite(er.w),
+            "FP invariant: composed eye rotation is non-finite (camera direction corrupted)",
+        );
+
         // -- FOV ---------------------------------------------------------
         let fovTarget = cfg.fov.base;
         if (cfg.fov.sprintAdd !== 0) {

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

@@ -1,67 +1,106 @@
 /**
- * Ledge-grab ability — snap to a forward ledge while descending and hang
- * from it until the player chooses (or is forced) to release.
+ * Ledge-grab ability — catch a forward ledge while descending, then HANG
+ * from it and traverse it: shimmy along the edge, pull up / vault over it,
+ * or dismount.
  *
- * 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.
+ * Activation (AUTO-CATCH):
+ *   - `sensors.ledgeAhead.hit` — a forward+up obstacle probe found a
+ *     grabbable edge (the same probe mantle uses). This already implies the
+ *     body is facing a wall with a top, so even neutral input catches it.
+ *   - `runtime.velocityY <= 0` — descending or static. We don't auto-catch
+ *     on the way UP (that would feel like the world grabbed you mid-jump).
+ *   - `state.airborneTime >= minAirborneTime` — a small post-takeoff window
+ *     where ledge-grab can't fire even if instantly at apex.
+ *   - NOT moving away — the move intent, taken to world space and projected
+ *     onto the wall's outward normal, must not exceed `moveAwayThreshold`.
+ *     You won't catch a ledge you're deliberately leaving (this also blocks
+ *     a same-tick re-grab right after an away-dismount).
  *
- * 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).
+ * The hanging input model (evaluated every tick): the move intent is taken
+ * to WORLD space and decomposed against the wall frame captured at grab —
+ * the outward normal `n` and the horizontal edge tangent `t = (-nz, nx)`.
+ * This makes toward / away / lateral facing-INDEPENDENT, which is exactly
+ * what makes "turn the camera to look away ≠ dismount" fall out for free.
  *
- * 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.
+ *   - `away    = worldMove · n`   (>0 = off the wall, <0 = into it)
+ *   - `lateral = worldMove · t`   (signed, along the edge)
+ *   - `facing  = forward · (-n)`  (how squarely the camera faces the wall)
+ *
+ * Per-tick decision (mutually exclusive — opposite axes can't both be high):
+ *   1. PULL-UP / VAULT — moving toward the wall, OR jump pressed while
+ *      facing within `pullUpFacingConeDeg` of it. Hands off to Mantle
+ *      (`runtime.ledgePullUpRequest`): onto a standable top, or a vault
+ *      over a too-thin one.
+ *   2. DISMOUNT (drop) — crouch, or an away-DOMINANT world-move past
+ *      `moveAwayThreshold` (conservative: a strafe that merely bleeds into
+ *      `away` shimmies instead — leaving the hang is more consequential).
+ *   3. SHIMMY — lateral intent dominant: step along the edge if it stays
+ *      clear and continuous; otherwise clamp (hold) — a shimmy NEVER drops.
+ *   4. HOLD — snap to the hang pose, accrue fatigue.
+ *   5. SLIP — exertion saturates (forced release).
+ *   A jump pressed while facing AWAY is consumed (no back-hop in v1) and
+ *   you keep hanging.
  *
  * 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.
+ * preempt an active ledge-grab — that's the point of placing ledge higher.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
 export class LedgeGrab extends Ability {
     /** @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. */
+     *  and the top-edge height (y) — captured at onActivate and advanced
+     *  while shimmying. The hang pose is built from the WALL, not 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;
+    /** @private Scratch query primitives for the shimmy probes — refilled
+     *  in place so a hanging player doesn't allocate each tick. */
+    private _ray;
+    _hit: PhysicsSurfacePoint;
     canActivate(controller: any, runtime: any, sensors: any): boolean;
     onActivate(controller: any, runtime: any): void;
     canInterrupt(): boolean;
+    onDeactivate(controller: any, runtime: any): void;
     tick(controller: any, runtime: any, bodyTransform: any, dt: any, _system: any): boolean;
+    /**
+     * World-space move intent (clamped to the unit disk) dotted with a
+     * horizontal axis (ax, az). Uses the controller's own move→world
+     * convention (screen_fwd = (sinYaw, cosYaw)). Facing-independent by
+     * construction — it's the intent in WORLD space, not camera space.
+     * @private
+     */
+    private _worldMoveDot;
+    /**
+     * Is the grabbed lip still under us? Probes the CAPTURED anchor (a down-ray
+     * just past the face, into the wall along −n), independent of where the
+     * camera looks — so turning to look away never reads as "ledge lost". Falls
+     * back to the facing-relative sensor only when no physics backend is present
+     * (the flat-ground unit harness, which simulates loss via that sensor).
+     * @private
+     */
+    private _ledgeStillThere;
+    /**
+     * Attempt one shimmy step of `dir` (±1) along the edge tangent. Returns
+     * true if it stepped (clear AND continuous), false if it CLAMPED — a clamp
+     * holds in place, it never drops. On success it advances the anchor and
+     * re-captures the edge height so an undulating top is tracked.
+     *
+     * Two probes, both must pass:
+     *   (A) lateral CLEARANCE — a ray along the tangent from the body centre
+     *       must be free for the step (a perpendicular/concave wall blocks it).
+     *   (B) edge CONTINUITY — a down-ray just past the shifted edge must find
+     *       the lip still at ~edge height (else the edge ended).
+     * Needs the physics backend; without it (flat-ground unit harness) it
+     * can't verify geometry, so it clamps.
+     * @private
+     */
+    private _tryShimmy;
 }
 import { Ability } from "./Ability.js";
+import { PhysicsSurfacePoint } from "../../../physics/queries/PhysicsSurfacePoint.js";
 //# sourceMappingURL=LedgeGrab.d.ts.map

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;;;2EAGuE;IACvE,iBAAiB;IACjB,iBAAiB;IACjB,YAAY;IACZ,YAAY;IACZ,eAAe;IAGnB,kEAkBC;IAED,gDAkCC;IAED,wBAKC;IAED,wFA6EC;CACJ;wBAlNuB,cAAc"}
+{"version":3,"file":"LedgeGrab.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/abilities/LedgeGrab.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;IAMQ;;;;iCAI6B;IAC7B,iBAAiB;IACjB,iBAAiB;IACjB,YAAY;IACZ,YAAY;IACZ,eAAe;IAEf;mEAC+D;IAC/D,aAAsB;IACtB,0BAAqC;IAGzC,kEAiCC;IAED,gDAuDC;IAED,wBAIC;IAED,kDAOC;IAED,wFA6GC;IAED;;;;;;OAMG;IACH,sBASC;IAED;;;;;;;OAOG;IACH,yBAgBC;IAED;;;;;;;;;;;;;;OAcG;IACH,mBA8CC;CACJ;wBA9YuB,cAAc;oCAFF,iDAAiD"}