@woosh/meep-engine 2.155.0 → 2.156.0

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

@@ -1,213 +1,405 @@
-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;
-    }
-}
+import { assert } from "../../../../core/assert.js";
+import { clamp } from "../../../../core/math/clamp.js";
+import { DEG_TO_RAD } from "../../../../core/math/DEG_TO_RAD.js";
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { PhysicsSurfacePoint } from "../../../physics/queries/PhysicsSurfacePoint.js";
+import { FirstPersonPosture } from "../pose/FirstPersonPosture.js";
+import { Ability } from "./Ability.js";
+
+/**
+ * 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 (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).
+ *
+ * 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.
+ *
+ *   - `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.
+ *
+ * @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 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. */
+        this._anchorX = 0;
+        this._anchorZ = 0;
+        this._nx = 0;
+        this._nz = 0;
+        this._edgeY = 0;
+
+        /** @private Scratch query primitives for the shimmy probes — refilled
+         *  in place so a hanging player doesn't allocate each tick. */
+        this._ray = new Ray3();
+        this._hit = new PhysicsSurfacePoint();
+    }
+
+    canActivate(controller, runtime, sensors) {
+        const cfg = controller.config.ledgeGrab;
+        if (!cfg) return false;
+        if (sensors === undefined || sensors === null) return false;
+
+        // Refractory window after a release — don't immediately re-grab the
+        // lip we just dismounted from (the auto-catch is otherwise eager
+        // enough to snap us straight back onto it while we're still falling
+        // clear of it).
+        if (runtime.ledgeRegrabCooldown > 0) 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;
+        // 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.
+        if (controller.intent.crouch) return false;
+        if (controller.state.exertion >= 1.0) return false;
+
+        // Auto-catch, but not a ledge we're deliberately LEAVING: decompose
+        // the world move against the obstacle face normal (ledgeAhead.hit
+        // implies obstacleAhead.hit, so the face data is present). Moving away
+        // past the threshold refuses the grab — which also prevents a same-tick
+        // re-grab right after an away-dismount.
+        const face = sensors.obstacleAhead;
+        if (face.hit) {
+            const away = this._worldMoveDot(controller, runtime, face.normal.x, face.normal.z);
+            if (away > cfg.moveAwayThreshold) return false;
+        }
+
+        return true;
+    }
+
+    onActivate(controller, runtime) {
+        const sensors = runtime.sensors;
+
+        // Clear any stale pull-up request — a fresh grab starts neutral.
+        runtime.ledgePullUpRequest = false;
+
+        // 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;
+
+        // -- Preconditions (dev-only; compiled out of prod). The hang frame is
+        //    built entirely from these — a bad capture here is the kind of
+        //    thing that silently produces a degenerate pose now and an
+        //    inexplicable camera jump later.
+        assert.ok(sensors.obstacleAhead.hit,
+            "LedgeGrab: activated without an obstacleAhead hit (no wall to anchor the hang)");
+        assert.ok(sensors.ledgeAhead.hit,
+            "LedgeGrab: activated without a ledgeAhead hit (no edge to grab)");
+        // The wall normal must be roughly horizontal + unit — the whole
+        // wall-frame model (toward/away/lateral, shimmy tangent, hang standoff)
+        // assumes it. A near-zero horizontal normal (e.g. a floor/slope hit)
+        // would collapse the frame.
+        assert.greaterThan(Math.hypot(this._nx, this._nz), 0.5,
+            "LedgeGrab: wall normal is not horizontal — degenerate hang/shimmy frame");
+        assert.ok(
+            Number.isFinite(this._anchorX) && Number.isFinite(this._anchorZ) && Number.isFinite(this._edgeY),
+            "LedgeGrab: captured a non-finite hang anchor/edge",
+        );
+
+        // 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; 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;
+    }
+
+    onDeactivate(controller, runtime) {
+        // Open the re-grab refractory window on EVERY release (drop, slip,
+        // pull-up, shuffle-off). Covers the case where the dismount input
+        // returns to neutral while the body is still inside the grab window —
+        // without this the auto-catch re-fires next tick and snaps us back
+        // onto the lip.
+        runtime.ledgeRegrabCooldown = controller.config.ledgeGrab.regrabCooldown;
+    }
+
+    tick(controller, runtime, bodyTransform, dt, _system) {
+        const cfg = controller.config.ledgeGrab;
+        const intent = controller.intent;
+
+        // Re-assert posture each tick (defence against any layer resetting it
+        // before L2 reads). Body parked against the wall — no lean.
+        controller.state.posture = FirstPersonPosture.Hang;
+        runtime.leanTargetRad = 0;
+
+        // -- Exit: lost the ledge. Probe the CAPTURED anchor (not the
+        //    facing-relative sensor) so turning to look away from the wall
+        //    never reads as "ledge lost" — that's the whole point of the
+        //    wall-frame model. Releases only when the lip genuinely isn't
+        //    under us any more (e.g. the wall was removed).
+        if (!this._ledgeStillThere(runtime, cfg, _system)) {
+            controller.signals.onLedgeRelease.send1({ reason: "shuffle-off" });
+            return false;
+        }
+
+        // -- Decompose the move intent against the captured wall frame. These
+        //    are facing-INDEPENDENT (built from n/t, not the camera) — looking
+        //    away changes `facing` but not away/lateral, so it can't dismount.
+        const away = this._worldMoveDot(controller, runtime, this._nx, this._nz);
+        const lateral = this._worldMoveDot(controller, runtime, -this._nz, this._nx);
+        const { sinYaw, cosYaw } = runtime;
+        const facing = sinYaw * (-this._nx) + cosYaw * (-this._nz);
+        const jumpEdge = intent.jump && !runtime.prevJumpHeld;
+        const coneCos = Math.cos(cfg.pullUpFacingConeDeg * DEG_TO_RAD);
+
+        // -- (1) Pull-up / vault: moving toward the wall, OR a jump press while
+        //    facing into it. Request the climb; Mantle (next tick) resolves it
+        //    onto a standable top, or vaults over a too-thin one. The small
+        //    upward kick keeps mantle's ledgeAhead probe resolving correctly.
+        if (away < -cfg.moveTowardThreshold || (jumpEdge && facing > coneCos)) {
+            runtime.ledgePullUpRequest = true;
+            runtime.velocityY = runtime.jumpInitialVy * cfg.mantleUpUpFactor;
+            if (jumpEdge) runtime.prevJumpHeld = true;
+            runtime.midJump = true;
+            controller.state.isAscending = true;
+            controller.signals.onLedgeRelease.send1({ reason: "mantle-up" });
+            return false;
+        }
+        // Consume a jump press that DIDN'T pull up (facing away) so it doesn't
+        // fire later; stay hanging — looking away never auto-acts.
+        if (jumpEdge) runtime.prevJumpHeld = true;
+
+        // -- (2) Dismount. Crouch is an explicit, unconditional dismount.
+        //    Movement-away is CONSERVATIVE: leaving the hang (you fall) is more
+        //    consequential than shimmying, so a strafe taken while looking
+        //    somewhat off the wall — which bleeds a little into `away` — reads
+        //    as a SHIMMY (handled below), not an ejection. Only a stick that
+        //    clearly points OFF the edge (away-DOMINANT, past the threshold)
+        //    drops you.
+        if (intent.crouch) {
+            controller.signals.onLedgeRelease.send1({ reason: "drop" });
+            return false;
+        }
+        if (away > cfg.moveAwayThreshold && away > Math.abs(lateral)) {
+            controller.signals.onLedgeRelease.send1({ reason: "drop" });
+            return false;
+        }
+
+        // -- (5) Slip: exertion saturated → forced release.
+        if (controller.state.exertion >= 1.0) {
+            controller.signals.onLedgeRelease.send1({ reason: "slip" });
+            return false;
+        }
+
+        // -- (3) Shimmy: lateral intent dominant → try one step along the edge.
+        //    A blocked or discontinuous edge clamps (we stay hanging here),
+        //    never drops.
+        let shimmying = false;
+        if (Math.abs(lateral) > cfg.shimmyLateralMin && Math.abs(lateral) >= Math.abs(away)) {
+            shimmying = this._tryShimmy(controller, runtime, cfg, Math.sign(lateral), dt, _system);
+        }
+
+        // -- (4) Hold (or post-shimmy advance): snap to the hang pose just
+        //    OUTSIDE the wall face, gripping the top edge. The body centre sits
+        //    a capsule radius (+ a small gap) out from the face along its
+        //    outward normal — anchoring on the WALL keeps the body clear even
+        //    when the ledge was reached obliquely (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;
+
+        // Teleport-snap the camera on a parked (non-shimmying) hang: the body
+        // was just snapped onto the wall from wherever it was falling, so the
+        // render interpolation must JUMP to the hang pose, not glide into it.
+        // During a shimmy the body moves smoothly, so we let it interpolate.
+        if (!shimmying) runtime.renderSnap = true;
+
+        // Exertion rises while hanging — fatigue. Faster while actively
+        // shimmying. Mass-scaled like the rest of the exertion system.
+        const exertRate = cfg.exertionRiseRate * (shimmying ? cfg.shimmyExertionFactor : 1);
+        controller.state.exertion = clamp(
+            controller.state.exertion + exertRate * dt
+                * runtime.massRatios.exertionRiseScale,
+            0, 1,
+        );
+
+        return true;
+    }
+
+    /**
+     * 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
+     */
+    _worldMoveDot(controller, runtime, ax, az) {
+        const { sinYaw, cosYaw } = runtime;
+        let mx = controller.intent.move.x;
+        let my = controller.intent.move.y;
+        const len = Math.hypot(mx, my);
+        if (len > 1) { mx /= len; my /= len; }
+        const wmx = sinYaw * my - cosYaw * mx;
+        const wmz = cosYaw * my + sinYaw * mx;
+        return wmx * ax + wmz * az;
+    }
+
+    /**
+     * 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
+     */
+    _ledgeStillThere(runtime, cfg, system) {
+        const physics = system && system.physicsSystem;
+        if (!physics) return runtime.sensors.ledgeAhead.hit;
+
+        const ray = this._ray;
+        const hit = this._hit;
+        ray.setOrigin(
+            this._anchorX - this._nx * cfg.shimmyEdgeProbeForward,
+            this._edgeY + cfg.shimmyContinuityProbeUp,
+            this._anchorZ - this._nz * cfg.shimmyEdgeProbeForward,
+        );
+        ray.setDirection(0, -1, 0);
+        ray.tMax = cfg.shimmyContinuityProbeUp + cfg.shimmyContinuityProbeDown;
+        const filter = (_e, c) => c !== runtime.collider;
+        if (!physics.raycast(ray, hit, filter)) return false;
+        return Math.abs(hit.position.y - this._edgeY) <= cfg.shimmyContinuityTol;
+    }
+
+    /**
+     * 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
+     */
+    _tryShimmy(controller, runtime, cfg, dir, dt, system) {
+        const physics = system && system.physicsSystem;
+        if (!physics) return false; // no spatial backend → can't verify → clamp
+
+        const r = controller.config.body.radius;
+        const standoff = r + cfg.hangOffsetForward;
+        // Edge tangent (n is unit, so t is unit). dir picks the direction.
+        const tx = dir * (-this._nz);
+        const tz = dir * this._nx;
+        const step = cfg.shimmySpeed * dt;
+        const filter = (_e, c) => c !== runtime.collider; // exclude own body
+        const ray = this._ray;
+        const hit = this._hit;
+
+        // Body centre at the current hang pose.
+        const bx = this._anchorX + this._nx * standoff;
+        const bz = this._anchorZ + this._nz * standoff;
+
+        // (A) Lateral clearance along the tangent.
+        ray.setOrigin(bx, this._edgeY + cfg.shimmyClearanceProbeY, bz);
+        ray.setDirection(tx, 0, tz);
+        ray.tMax = step + r + cfg.shimmyClearanceGap;
+        if (physics.raycast(ray, hit, filter)) return false; // blocked → clamp
+
+        // (B) Edge continuity: down-probe just past the SHIFTED edge. The top
+        //     surface sits INTO the wall from the face (along -n), so offset the
+        //     probe that way before dropping it.
+        const nex = this._anchorX + tx * step;
+        const nez = this._anchorZ + tz * step;
+        ray.setOrigin(
+            nex - this._nx * cfg.shimmyEdgeProbeForward,
+            this._edgeY + cfg.shimmyContinuityProbeUp,
+            nez - this._nz * cfg.shimmyEdgeProbeForward,
+        );
+        ray.setDirection(0, -1, 0);
+        ray.tMax = cfg.shimmyContinuityProbeUp + cfg.shimmyContinuityProbeDown;
+        if (!physics.raycast(ray, hit, filter)) return false; // edge ended → clamp
+        if (Math.abs(hit.position.y - this._edgeY) > cfg.shimmyContinuityTol) return false;
+
+        // Commit: advance along the face and track the (possibly undulating)
+        // lip. The wall normal is kept constant — a straight face is the common
+        // case; wrapping a curving/convex wall is a v2 refinement.
+        this._anchorX = nex;
+        this._anchorZ = nez;
+        this._edgeY = hit.position.y;
+        return true;
+    }
+}