@woosh/meep-engine 2.138.20 → 2.140.0

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

@@ -0,0 +1,62 @@
+/**
+ * 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 {
+    /** @private World-space ledge edge position captured at onActivate. */
+    private _edgeX;
+    _edgeY: number;
+    _edgeZ: number;
+    canActivate(controller: any, runtime: any, sensors: any): boolean;
+    onActivate(controller: any, runtime: any): void;
+    canInterrupt(): boolean;
+    tick(controller: any, runtime: any, bodyTransform: any, dt: any, _system: any): boolean;
+}
+import { Ability } from "./Ability.js";
+//# sourceMappingURL=LedgeGrab.d.ts.map

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

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

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

@@ -0,0 +1,199 @@
+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;
+    }
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Mantle ability — auto-triggers when the player walks/runs into a
+ * reachable obstacle with forward intent. The body follows a scripted
+ * parametric path (horizontal lerp on an ease-in-out, vertical lerp on
+ * an ease-out) for {@link cfg.mantle.duration} seconds, landing on top
+ * of the surface.
+ *
+ * Activation requires both `sensors.obstacleAhead.hit` (something in
+ * front to climb) AND `sensors.ledgeAhead.hit` (there's a top surface
+ * to land on). Heights between `cfg.mantle.minHeight` and `maxHeight`
+ * are accepted; below is "just step over", above is "out of reach".
+ *
+ * The ability is FULLY non-interruptible once committed — `canInterrupt`
+ * returns false throughout. This prevents the body from teleporting
+ * mid-mantle if a higher-priority ability fires; the trade-off is the
+ * player has limited control during the short window. Player input
+ * for THIS frame is effectively suspended.
+ *
+ * Priority 30: above Slide (10) so an obstacle vault-into preempts a
+ * slide; below Wall-run / Wall-jump so those high-air abilities still
+ * win if their conditions are simultaneously met (which would be
+ * unusual — typically you mantle from the ground).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Mantle extends Ability {
+    /** @private Elapsed fraction of duration. */
+    private _t;
+    /** @private Captured at activation. */
+    private _duration;
+    _startX: number;
+    _startY: number;
+    _startZ: number;
+    _endX: number;
+    _endY: number;
+    _endZ: number;
+    canActivate(controller: any, runtime: any, sensors: any): boolean;
+    onActivate(controller: any, runtime: any): void;
+    canInterrupt(): boolean;
+    tick(controller: any, runtime: any, bodyTransform: any, dt: any, _system: any): boolean;
+    onDeactivate(_controller: any, _runtime: any): void;
+}
+import { Ability } from "./Ability.js";
+//# sourceMappingURL=Mantle.d.ts.map

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

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

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

@@ -0,0 +1,188 @@
+import { FirstPersonPosture } from "../pose/FirstPersonPosture.js";
+import { Ability } from "./Ability.js";
+
+/**
+ * Smoothstep-style horizontal interpolation: slow-fast-slow.
+ * @param {number} t  [0..1]
+ */
+function easeInOutCubic(t) {
+    return t < 0.5
+        ? 4 * t * t * t
+        : 1 - Math.pow(-2 * t + 2, 3) / 2;
+}
+
+/**
+ * Front-loaded ease — fast rise then gentle settle. Used for the vertical
+ * curve so the body lifts off the ground quickly (matching the hand-grip
+ * pull-up dynamic) and decelerates as it approaches the surface top.
+ * @param {number} t  [0..1]
+ */
+function easeOutCubic(t) {
+    return 1 - Math.pow(1 - t, 3);
+}
+
+/**
+ * Mantle ability — auto-triggers when the player walks/runs into a
+ * reachable obstacle with forward intent. The body follows a scripted
+ * parametric path (horizontal lerp on an ease-in-out, vertical lerp on
+ * an ease-out) for {@link cfg.mantle.duration} seconds, landing on top
+ * of the surface.
+ *
+ * Activation requires both `sensors.obstacleAhead.hit` (something in
+ * front to climb) AND `sensors.ledgeAhead.hit` (there's a top surface
+ * to land on). Heights between `cfg.mantle.minHeight` and `maxHeight`
+ * are accepted; below is "just step over", above is "out of reach".
+ *
+ * The ability is FULLY non-interruptible once committed — `canInterrupt`
+ * returns false throughout. This prevents the body from teleporting
+ * mid-mantle if a higher-priority ability fires; the trade-off is the
+ * player has limited control during the short window. Player input
+ * for THIS frame is effectively suspended.
+ *
+ * Priority 30: above Slide (10) so an obstacle vault-into preempts a
+ * slide; below Wall-run / Wall-jump so those high-air abilities still
+ * win if their conditions are simultaneously met (which would be
+ * unusual — typically you mantle from the ground).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Mantle extends Ability {
+    constructor() {
+        super();
+        this.name = "Mantle";
+        this.priority = 30;
+
+        // -- per-instance scripted-path state --
+        /** @private Elapsed fraction of duration. */
+        this._t = 0;
+        /** @private Captured at activation. */
+        this._duration = 0.5;
+        this._startX = 0;
+        this._startY = 0;
+        this._startZ = 0;
+        this._endX = 0;
+        this._endY = 0;
+        this._endZ = 0;
+    }
+
+    canActivate(controller, runtime, sensors) {
+        const cfg = controller.config.mantle;
+        if (!cfg) return false;
+        if (sensors === undefined || sensors === null) return false;
+
+        // Must have BOTH the face probe (obstacleAhead) AND the top probe
+        // (ledgeAhead) — otherwise we don't know if there's anywhere to
+        // land. obstacleAhead alone could be a wall too tall to climb.
+        if (!sensors.obstacleAhead.hit) return false;
+        if (!sensors.ledgeAhead.hit) return false;
+
+        // Forward intent is required — the player must be committing
+        // into the obstacle, otherwise we don't want to grab them.
+        if (controller.intent.move.y < 0.1) return false;
+
+        // Height check: the target surface must be within the reachable
+        // band.
+        const surfaceTopY = sensors.ledgeAhead.point.y;
+        const playerFootY = controller.pose.rootPosition.y;
+        const heightDiff = surfaceTopY - playerFootY;
+        if (heightDiff < cfg.minHeight) return false;
+        if (heightDiff > cfg.maxHeight) return false;
+
+        return true;
+    }
+
+    onActivate(controller, runtime) {
+        const cfg = controller.config.mantle;
+        const sensors = runtime.sensors;
+
+        this._t = 0;
+        this._duration = cfg.duration;
+
+        // Capture start position (body's current world position).
+        const startPos = controller.pose.rootPosition;
+        this._startX = startPos.x;
+        this._startY = startPos.y;
+        this._startZ = startPos.z;
+
+        // Compute end position: above the ledge surface, displaced
+        // forward by `forwardOffsetOnLand` so the player ends standing
+        // on the surface (not balancing on the edge).
+        const yaw = runtime.bodyYaw;
+        const fx = Math.sin(yaw);
+        const fz = Math.cos(yaw);
+        this._endX = sensors.ledgeAhead.point.x + fx * cfg.forwardOffsetOnLand;
+        this._endY = sensors.ledgeAhead.point.y;
+        this._endZ = sensors.ledgeAhead.point.z + fz * cfg.forwardOffsetOnLand;
+
+        // Zero velocity — the body is on a path, not under integration.
+        runtime.velocityX = 0;
+        runtime.velocityY = 0;
+        runtime.velocityZ = 0;
+
+        // Clear airborne/jump state — the scripted path supersedes them.
+        runtime.midJump = false;
+        runtime.apexFired = false;
+        controller.state.isVariableJumpCut = false;
+        controller.state.isAscending = false;
+
+        // Body is climbing — upright posture (not Hang, even if we got
+        // here from ledge-grab). Animators read posture for the rig
+        // blend; this signals "switch from the hang clip to the climb /
+        // upright clip".
+        controller.state.posture = FirstPersonPosture.Stand;
+
+        controller.signals.onLeaveGround.send1({ reason: "mantle" });
+    }
+
+    canInterrupt() {
+        // Non-interruptible. Mantle commits.
+        return false;
+    }
+
+    tick(controller, runtime, bodyTransform, dt, _system) {
+        // Body is on a scripted path — no lat-accel-driven lean. Hold
+        // the camera level for the duration of the mantle.
+        runtime.leanTargetRad = 0;
+        // Re-assert posture in case anything reset it. Mantle is a
+        // committed climb; we want the rig in the climb/stand blend
+        // until release.
+        controller.state.posture = FirstPersonPosture.Stand;
+
+        this._t += dt / this._duration;
+
+        if (this._t >= 1.0) {
+            // Completed: snap to end, mark grounded, release.
+            bodyTransform.position.set(this._endX, this._endY, this._endZ);
+            runtime.velocityX = 0;
+            runtime.velocityY = 0;
+            runtime.velocityZ = 0;
+            controller.state.grounded = true;
+            controller.state.verticalSpeed = 0;
+            controller.state.airborneTime = 0;
+            controller.state.timeSinceGrounded = 0;
+            controller.signals.onLand.send1({ verticalSpeed: 0, kind: "soft" });
+            return false;
+        }
+
+        // Sample the parametric path.
+        const horizT = easeInOutCubic(this._t);
+        const vertT = easeOutCubic(this._t);
+        bodyTransform.position.set(
+            this._startX + (this._endX - this._startX) * horizT,
+            this._startY + (this._endY - this._startY) * vertT,
+            this._startZ + (this._endZ - this._startZ) * horizT,
+        );
+
+        // Body is on a path — no integration this tick. Velocity stays 0.
+        runtime.velocityX = 0;
+        runtime.velocityY = 0;
+        runtime.velocityZ = 0;
+
+        return true;
+    }
+
+    onDeactivate(_controller, _runtime) {
+        this._t = 0;
+    }
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Slide ability — sprint + crouch-press while grounded transitions into
+ * a low-friction slide that preserves horizontal momentum. Exit on:
+ *   - crouch released
+ *   - horizontal speed falls below `cfg.slide.endSpeed`
+ *   - airborne (lost ground contact)
+ *   - jump pressed → fires a slide-jump (preserves momentum + adds jump
+ *     impulse; the only way to exit while keeping all your speed)
+ *
+ * The ability has a non-interruptible startup window — once the player
+ * commits to a slide, higher-priority abilities can't yank them out for
+ * `cfg.slide.startupWindow` seconds. This protects the slide-jump
+ * timing window in particular: you can buffer a wall-jump press during
+ * slide-startup without losing the slide first.
+ *
+ * Priority is the lowest among movement abilities (10) — anything
+ * dynamic (wall-jump, mantle, ledge-grab) wins. Slide is the "default
+ * extension" of running.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Slide extends Ability {
+    /** @private Counts down during the non-interruptible window. */
+    private _startupRemaining;
+    canActivate(controller: any, runtime: any, _sensors: any): boolean;
+    onActivate(controller: any, runtime: any): void;
+    canInterrupt(_controller: any, _runtime: any): boolean;
+    tick(controller: any, runtime: any, bodyTransform: any, dt: any, system: any): boolean;
+    onDeactivate(_controller: any, _runtime: any): void;
+}
+import { Ability } from "./Ability.js";
+//# sourceMappingURL=Slide.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Slide.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/abilities/Slide.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAOQ,gEAAgE;IAChE,0BAA0B;IAG9B,mEAuBC;IAED,gDAuBC;IAED,uDAGC;IAED,uFAmEC;IAED,oDAEC;CACJ;wBAlKuB,cAAc"}