@woosh/meep-engine 2.155.0 → 2.157.0

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

@@ -35,6 +35,12 @@ export class Mantle extends Ability {
     _endX: number;
     _endY: number;
     _endZ: number;
+    /** @private "mantle" = climb ONTO a standable top (lands grounded);
+     *  "vault" = pull up and OVER a too-thin top (releases airborne on the
+     *  far side). Chosen in onActivate from the ledge-pull-up request. */
+    private _kind;
+    /** @private Apex height of the vault hump. */
+    private _apexY;
     canActivate(controller: any, runtime: any, sensors: any): boolean;
     onActivate(controller: any, runtime: any): void;
     canInterrupt(): boolean;

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,kEA+BC;IAED,gDAyCC;IAED,wBAGC;IAED,wFAwCC;IAED,oDAEC;CACJ;wBAjMuB,cAAc"}
+{"version":3,"file":"Mantle.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/abilities/Mantle.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAOQ,6CAA6C;IAC7C,WAAW;IACX,uCAAuC;IACvC,kBAAoB;IACpB,gBAAgB;IAChB,gBAAgB;IAChB,gBAAgB;IAChB,cAAc;IACd,cAAc;IACd,cAAc;IACd;;0EAEsE;IACtE,cAAqB;IACrB,8CAA8C;IAC9C,eAAe;IAGnB,kEAgCC;IAED,gDAiEC;IAED,wBAGC;IAED,wFA0DC;IAED,oDAEC;CACJ;wBA3PuB,cAAc"}

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

@@ -1,3 +1,4 @@
+import { assert } from "../../../../core/assert.js";
 import { FirstPersonPosture } from "../pose/FirstPersonPosture.js";
 import { Ability } from "./Ability.js";
 
@@ -21,6 +22,15 @@ function easeOutCubic(t) {
     return 1 - Math.pow(1 - t, 3);
 }
 
+/**
+ * Back-loaded ease — gentle start, accelerating finish. Used for the
+ * DESCENDING half of a vault hump (you crest the edge then drop over).
+ * @param {number} t  [0..1]
+ */
+function easeInCubic(t) {
+    return t * t * t;
+}
+
 /**
  * Mantle ability — auto-triggers when the player walks/runs into a
  * reachable obstacle with forward intent. The body follows a scripted
@@ -64,6 +74,12 @@ export class Mantle extends Ability {
         this._endX = 0;
         this._endY = 0;
         this._endZ = 0;
+        /** @private "mantle" = climb ONTO a standable top (lands grounded);
+         *  "vault" = pull up and OVER a too-thin top (releases airborne on the
+         *  far side). Chosen in onActivate from the ledge-pull-up request. */
+        this._kind = "mantle";
+        /** @private Apex height of the vault hump. */
+        this._apexY = 0;
     }
 
     canActivate(controller, runtime, sensors) {
@@ -77,24 +93,25 @@ export class Mantle extends Ability {
         if (!sensors.obstacleAhead.hit) return false;
         if (!sensors.ledgeAhead.hit) return false;
 
-        // Only vault onto a top we can actually STAND on. A too-thin wall /
-        // knife-edge isn't a mantle target — the body would land overhanging
-        // and fall right back off (on a wall-run wall this is the reported
-        // violent snap-then-drop). Ledge-grab, which can hang from a thin
-        // edge, takes those instead.
-        if (!sensors.ledgeStandable) 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.
+        // AUTO-mantle only onto a top we can STAND on — a thin knife-edge
+        // would leave the body overhanging and it'd fall off (on a wall-run
+        // wall, the reported snap-then-drop). A ledge-grab PULL-UP
+        // (`runtime.ledgePullUpRequest`) is allowed onto a thin top too: it
+        // VAULTS over instead of onto (see onActivate). Likewise the pull-up
+        // already expressed commitment, so it needn't re-assert forward intent.
+        const pullUp = runtime.ledgePullUpRequest;
+        if (!sensors.ledgeStandable && !pullUp) return false;
+        if (controller.intent.move.y < 0.1 && !pullUp) return false;
+
+        // Height check: the target surface must be within the reachable band.
+        // A pull-up starts from a full hang (~maxHeight below the lip), so give
+        // that path a slacker ceiling.
         const surfaceTopY = sensors.ledgeAhead.point.y;
         const playerFootY = controller.pose.rootPosition.y;
         const heightDiff = surfaceTopY - playerFootY;
+        const maxH = pullUp ? cfg.pullUpMaxHeight : cfg.maxHeight;
         if (heightDiff < cfg.minHeight) return false;
-        if (heightDiff > cfg.maxHeight) return false;
+        if (heightDiff > maxH) return false;
 
         return true;
     }
@@ -112,15 +129,39 @@ export class Mantle extends Ability {
         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).
+        // Climb ONTO a standable top, or VAULT OVER a too-thin one (a ledge
+        // pull-up onto a non-standable lip). Consume the one-shot request.
         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;
+        const ledge = sensors.ledgeAhead.point;
+        this._kind = (runtime.ledgePullUpRequest && !sensors.ledgeStandable) ? "vault" : "mantle";
+        runtime.ledgePullUpRequest = false;
+        if (this._kind === "vault") {
+            // Carry the body forward PAST the far edge; it crests an apex above
+            // the lip then drops over, releasing airborne on the far side.
+            this._endX = ledge.x + fx * cfg.vaultDistance;
+            this._endY = ledge.y;
+            this._endZ = ledge.z + fz * cfg.vaultDistance;
+            this._apexY = ledge.y + cfg.vaultApexClearance;
+        } else {
+            // Land ON TOP, displaced slightly forward of the edge so the body
+            // ends standing on the surface (not balancing on the lip).
+            this._endX = ledge.x + fx * cfg.forwardOffsetOnLand;
+            this._endY = ledge.y;
+            this._endZ = ledge.z + fz * cfg.forwardOffsetOnLand;
+        }
+
+        // -- Preconditions (dev-only; compiled out of prod). The scripted path
+        //    interpolates toward this end every tick — a non-finite endpoint
+        //    would drive the body (and camera) to NaN.
+        assert.ok(sensors.obstacleAhead.hit && sensors.ledgeAhead.hit,
+            "Mantle: activated without obstacle+ledge sensor hits");
+        assert.ok(
+            Number.isFinite(this._endX) && Number.isFinite(this._endY) && Number.isFinite(this._endZ)
+            && Number.isFinite(this._apexY),
+            "Mantle: computed a non-finite end/apex position",
+        );
 
         // Zero velocity — the body is on a path, not under integration.
         runtime.velocityX = 0;
@@ -156,37 +197,55 @@ export class Mantle extends Ability {
         // until release.
         controller.state.posture = FirstPersonPosture.Stand;
 
+        const cfg = controller.config.mantle;
         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;
+        const t = this._t < 1 ? this._t : 1;
+
+        // Horizontal: ease-in-out lerp start→end (both kinds).
+        const horizT = easeInOutCubic(t);
+        const x = this._startX + (this._endX - this._startX) * horizT;
+        const z = this._startZ + (this._endZ - this._startZ) * horizT;
+        // Vertical: a CLIMB (ease-out up to the top) or a vault HUMP (rise to an
+        // apex above the lip, then drop over it on the back half).
+        let y;
+        if (this._kind === "vault") {
+            const tApex = 0.55;
+            y = t <= tApex
+                ? this._startY + (this._apexY - this._startY) * easeOutCubic(t / tApex)
+                : this._apexY - cfg.vaultDropOnExit * easeInCubic((t - tApex) / (1 - tApex));
+        } else {
+            y = this._startY + (this._endY - this._startY) * easeOutCubic(t);
         }
-
-        // 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.
+        bodyTransform.position.set(x, y, z);
+        // On the path — no integration; velocity stays 0 until release.
         runtime.velocityX = 0;
         runtime.velocityY = 0;
         runtime.velocityZ = 0;
 
-        return true;
+        if (this._t < 1.0) return true;
+
+        // -- Completed --
+        if (this._kind === "vault") {
+            // Release AIRBORNE past the far edge: hand back forward + a little
+            // down so the body commits OVER. Base + the mover resolve the far
+            // side — ground catches it, or it falls into a gap (both are "over").
+            const yaw = runtime.bodyYaw;
+            runtime.velocityX = Math.sin(yaw) * cfg.vaultExitSpeed;
+            runtime.velocityZ = Math.cos(yaw) * cfg.vaultExitSpeed;
+            runtime.velocityY = -cfg.vaultExitDownSpeed;
+            controller.state.grounded = false;
+            controller.state.isAscending = false;
+            controller.signals.onLeaveGround.send1({ reason: "vault" });
+            controller.signals.onLedgeRelease.send1({ reason: "vault" });
+            return false;
+        }
+        // Mantle: landed on top.
+        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;
     }
 
     onDeactivate(_controller, _runtime) {

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

@@ -0,0 +1,61 @@
+/**
+ * Scramble-up ability — a short vertical wall-run up a wall the player JUMPS
+ * at while facing it, à la Assassin's Creed. A deliberate jump (not just
+ * walking into the wall) launches a brief upward climb; a running start gives
+ * higher purchase, so the player can reach a high ledge to grab, or kick off.
+ *
+ * Activation:
+ *   - A fresh JUMP press (rising edge). A scramble is a deliberate jump at the
+ *     wall — and the edge means it can't auto-loop scramble→fall→land→scramble:
+ *     each one needs its own press.
+ *   - Grounded — a ground-initiated move: run or stand AT the wall and jump.
+ *   - `sensors.wallFront.hit` + `!sensors.ledgeAhead.hit` — facing a wall whose
+ *     top is OUT of mantle/grab reach (a reachable top is Mantle's job; this
+ *     makes the two mutually exclusive).
+ *   - Forward intent (`intent.move.y > 0.5`) — committed into the wall, so a
+ *     plain jump near a wall (no forward) is still just a jump.
+ *
+ * Behaviour:
+ *   - Launches upward off a physical PUSH-OFF FORCE: `baseJumpForce` + the
+ *     horizontal approach speed × `momentumForcePerSpeed` (capped at
+ *     `maxJumpForce`), converted to a launch velocity through the body's mass +
+ *     push-off distance (see {@link jumpDynamics}). A running start climbs high,
+ *     a standstill gives a small hop, and a heavier character scrambles lower
+ *     for the same force — just like a jump. Horizontal velocity is replaced by
+ *     a small into-wall "hug" so the body climbs the face (the mover clips the
+ *     penetration). The climb DECELERATES (`decel`): a short burst, roughly
+ *     `launchVy²/(2·decel)` m high over `launchVy/decel` s.
+ *   - Motion routes through the shared mover, so the climb is collision-checked
+ *     and the ledge sensors update as the body rises.
+ *
+ * Exit:
+ *   - Apex (`velocityY <= 0`) → release. If a ledge is now within reach,
+ *     LedgeGrab (which needs a descent) catches on the way down; otherwise the
+ *     player falls back.
+ *   - A SECOND jump press (released then re-pressed during the climb) → WALL-
+ *     KICK off the front wall: impulse out along the normal, plus an upward
+ *     launch off the body's full jump push-off force (`runtime.jumpForce`) — so
+ *     the kick rises like a max-height jump. The front-wall counterpart of
+ *     wall-run → wall-jump.
+ *   - Lost the wall (`!wallFront.hit`) → reached the top (or it ended); release.
+ *   - Timer (`maxDuration`) or re-grounded → release.
+ *
+ * Priority 55 — above wall-run (50, an ALONG-wall move) and below wall-jump
+ * (60). It hands off to LedgeGrab (40) via the apex→descent.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ScrambleUp extends Ability {
+    /** @private Captured wall outward normal (x,z) — for the hug + the kick. */
+    private _nx;
+    _nz: number;
+    /** @private Seconds since activation. */
+    private _elapsed;
+    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=ScrambleUp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ScrambleUp.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/abilities/ScrambleUp.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH;IAMQ,4EAA4E;IAC5E,YAAY;IACZ,YAAY;IACZ,yCAAyC;IACzC,iBAAiB;IAGrB,kEAiBC;IAED,gDAgCC;IAED,wBAIC;IAED,uFAwDC;CACJ;wBAnLuB,cAAc"}

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

@@ -0,0 +1,182 @@
+import { launchVelocityForForce } from "../math/jumpDynamics.js";
+import { FirstPersonPosture } from "../pose/FirstPersonPosture.js";
+import { Ability } from "./Ability.js";
+
+/**
+ * Scramble-up ability — a short vertical wall-run up a wall the player JUMPS
+ * at while facing it, à la Assassin's Creed. A deliberate jump (not just
+ * walking into the wall) launches a brief upward climb; a running start gives
+ * higher purchase, so the player can reach a high ledge to grab, or kick off.
+ *
+ * Activation:
+ *   - A fresh JUMP press (rising edge). A scramble is a deliberate jump at the
+ *     wall — and the edge means it can't auto-loop scramble→fall→land→scramble:
+ *     each one needs its own press.
+ *   - Grounded — a ground-initiated move: run or stand AT the wall and jump.
+ *   - `sensors.wallFront.hit` + `!sensors.ledgeAhead.hit` — facing a wall whose
+ *     top is OUT of mantle/grab reach (a reachable top is Mantle's job; this
+ *     makes the two mutually exclusive).
+ *   - Forward intent (`intent.move.y > 0.5`) — committed into the wall, so a
+ *     plain jump near a wall (no forward) is still just a jump.
+ *
+ * Behaviour:
+ *   - Launches upward off a physical PUSH-OFF FORCE: `baseJumpForce` + the
+ *     horizontal approach speed × `momentumForcePerSpeed` (capped at
+ *     `maxJumpForce`), converted to a launch velocity through the body's mass +
+ *     push-off distance (see {@link jumpDynamics}). A running start climbs high,
+ *     a standstill gives a small hop, and a heavier character scrambles lower
+ *     for the same force — just like a jump. Horizontal velocity is replaced by
+ *     a small into-wall "hug" so the body climbs the face (the mover clips the
+ *     penetration). The climb DECELERATES (`decel`): a short burst, roughly
+ *     `launchVy²/(2·decel)` m high over `launchVy/decel` s.
+ *   - Motion routes through the shared mover, so the climb is collision-checked
+ *     and the ledge sensors update as the body rises.
+ *
+ * Exit:
+ *   - Apex (`velocityY <= 0`) → release. If a ledge is now within reach,
+ *     LedgeGrab (which needs a descent) catches on the way down; otherwise the
+ *     player falls back.
+ *   - A SECOND jump press (released then re-pressed during the climb) → WALL-
+ *     KICK off the front wall: impulse out along the normal, plus an upward
+ *     launch off the body's full jump push-off force (`runtime.jumpForce`) — so
+ *     the kick rises like a max-height jump. The front-wall counterpart of
+ *     wall-run → wall-jump.
+ *   - Lost the wall (`!wallFront.hit`) → reached the top (or it ended); release.
+ *   - Timer (`maxDuration`) or re-grounded → release.
+ *
+ * Priority 55 — above wall-run (50, an ALONG-wall move) and below wall-jump
+ * (60). It hands off to LedgeGrab (40) via the apex→descent.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ScrambleUp extends Ability {
+    constructor() {
+        super();
+        this.name = "ScrambleUp";
+        this.priority = 55;
+
+        /** @private Captured wall outward normal (x,z) — for the hug + the kick. */
+        this._nx = 0;
+        this._nz = 0;
+        /** @private Seconds since activation. */
+        this._elapsed = 0;
+    }
+
+    canActivate(controller, runtime, sensors) {
+        const cfg = controller.config.scrambleUp;
+        if (!cfg) return false;
+        if (sensors === undefined || sensors === null) return false;
+
+        // A deliberate JUMP at the wall starts a scramble — walking into it is
+        // not enough. The fresh-press edge is also what prevents an automatic
+        // scramble→fall→land→scramble loop: each one needs its own press.
+        if (!controller.intent.jump || runtime.prevJumpHeld) return false;
+        // Ground-initiated: run or stand AT the wall and jump.
+        if (!controller.state.grounded) return false;
+        // Facing a wall whose top is out of reach, committed forward into it.
+        if (!sensors.wallFront.hit) return false;
+        if (sensors.ledgeAhead.hit) return false;
+        if (controller.intent.move.y <= 0.5) return false;
+
+        return true;
+    }
+
+    onActivate(controller, runtime) {
+        const cfg = controller.config.scrambleUp;
+        const sensors = runtime.sensors;
+        this._elapsed = 0;
+        this._nx = sensors.wallFront.normal.x;
+        this._nz = sensors.wallFront.normal.z;
+
+        // Reward forward momentum: the leg PUSH-OFF FORCE scales with the
+        // horizontal approach speed at the jump — a standstill gives the base
+        // force, a full sprint run-up the capped maximum. The force becomes a
+        // launch velocity through the body's mass + push-off distance, so a
+        // heavier character scrambles lower for the same effort (like a jump).
+        const body = controller.config.body;
+        const approach = Math.hypot(runtime.velocityX, runtime.velocityZ);
+        const force = Math.min(cfg.baseJumpForce + approach * cfg.momentumForcePerSpeed, cfg.maxJumpForce);
+        const launchVy = launchVelocityForForce(force, body.mass, body.jumpPushoffDistance);
+
+        runtime.velocityY = launchVy;
+        runtime.velocityX = -this._nx * cfg.hugSpeed;
+        runtime.velocityZ = -this._nz * cfg.hugSpeed;
+
+        // Climbing — airborne; clear any in-progress jump state.
+        controller.state.grounded = false;
+        runtime.midJump = false;
+        runtime.apexFired = false;
+        controller.state.isVariableJumpCut = false;
+        controller.state.isAscending = true;
+        // Consume the launch press so the first tick's wall-kick edge doesn't
+        // fire on it — the kick is a SEPARATE press during the climb.
+        runtime.prevJumpHeld = true;
+
+        controller.signals.onLeaveGround.send1({ reason: "scramble" });
+    }
+
+    canInterrupt() {
+        // Wall-jump (60) is the only higher-priority ability; the scramble's own
+        // jump-kick consumes the press first, so a preempt never lands.
+        return true;
+    }
+
+    tick(controller, runtime, bodyTransform, dt, system) {
+        const cfg = controller.config.scrambleUp;
+        const sensors = runtime.sensors;
+        const intent = controller.intent;
+        this._elapsed += dt;
+
+        // Climbing upright; body pinned to the wall — no lean.
+        controller.state.posture = FirstPersonPosture.Stand;
+        runtime.leanTargetRad = 0;
+
+        // -- Exit: timer (safety; the apex normally releases first).
+        if (this._elapsed >= cfg.maxDuration) return false;
+
+        // -- Exit: a FRESH jump press (released then re-pressed since the launch)
+        //    → WALL-KICK off the front wall (out along the normal + up).
+        if (intent.jump && !runtime.prevJumpHeld) {
+            const body = controller.config.body;
+            runtime.velocityX += this._nx * cfg.kickOutwardImpulse;
+            runtime.velocityZ += this._nz * cfg.kickOutwardImpulse;
+            // Up off the wall with the SAME push-off force as a max-height jump
+            // (runtime.jumpForce), converted through this body — so the kick's
+            // vertical launch equals a full jump's, not a reduced fraction.
+            runtime.velocityY = launchVelocityForForce(runtime.jumpForce, body.mass, body.jumpPushoffDistance);
+            runtime.prevJumpHeld = true;
+            runtime.midJump = true;
+            controller.state.isVariableJumpCut = false;
+            controller.state.isAscending = true;
+            controller.signals.onJumpStart.send1({ peakHeight: controller.config.jump.peakHeight });
+            controller.signals.onLeaveGround.send1({ reason: "scramble-kick" });
+            return false;
+        }
+        // Track the jump button so a release→re-press reads as a fresh edge next
+        // tick (base, which normally owns this, isn't running while we do).
+        runtime.prevJumpHeld = intent.jump;
+
+        // -- Exit: lost the wall — reached the top (or it ended).
+        if (!sensors.wallFront.hit) return false;
+
+        // -- Decelerate the climb; release at the apex. On the way down LedgeGrab
+        //    catches if a ledge is now in reach, else the player falls back.
+        runtime.velocityY -= cfg.decel * dt;
+        if (runtime.velocityY <= 0) return false;
+
+        // Hug the wall while climbing (re-assert each tick; the mover clips it).
+        runtime.velocityX = -this._nx * cfg.hugSpeed;
+        runtime.velocityZ = -this._nz * cfg.hugSpeed;
+
+        // Resolve the climb through the shared mover (sweep-and-slide + ground/
+        // ledge categorize). Gravity is NOT re-applied — the scramble owns the
+        // vertical model, like wall-run.
+        system._resolveMotion(controller, runtime, bodyTransform, dt);
+
+        // -- Exit: the mover caught a floor (shouldn't happen rising, but safe).
+        if (controller.state.grounded) return false;
+
+        return true;
+    }
+}

package/src/engine/control/first-person/math/jumpDynamics.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Jump power as physics, not a magic velocity.
+ *
+ * A jump is the legs doing WORK: a push-off force `F` (newtons) applied over a
+ * leg-extension distance `d` (meters) while the body is still on the ground.
+ * That work becomes the body's kinetic energy at the instant it leaves the
+ * ground, which gravity then trades back for height:
+ *
+ *     F · d   =   ½ · m · v₀²          (leg work → launch kinetic energy)
+ *     ½ · m · v₀²   =   m · g · h      (launch KE → potential energy at apex)
+ *
+ * Eliminating v₀ collapses the two into a single, mass-honest relationship
+ * between the force the legs deliver and the apex the body reaches:
+ *
+ *     h   =   F · d / (m · g)
+ *     F   =   m · g · h / d
+ *     v₀  =   √(2 · F · d / m)   =   √(2 · g · h)
+ *
+ * Why express jump power as a FORCE (newtons) rather than a launch velocity?
+ *   - It is a property of the CHARACTER (the legs), not of the jump. A fixed
+ *     leg force makes a heavier body jump lower — `h ∝ 1/m` — for free, which a
+ *     raw launch-velocity number cannot express (the same v₀ ignores mass).
+ *   - It composes: momentum, fatigue, and surface bonuses all add/scale in the
+ *     same physical currency (newtons) before a single conversion to velocity.
+ *
+ * `d` (the push-off distance) is the one extra parameter a newtons model needs:
+ * force alone can't determine a launch without the distance (or time) it acts
+ * over. It is a body constant — roughly the crouch-to-full-extension travel of
+ * the legs (~0.4–0.5 m for a ~1.8 m human countermovement jump).
+ *
+ * All three functions are pure and frame-independent. The headline is
+ * {@link jumpForceForHeight}: the newtons a designer needs to reach a desired
+ * apex on a given character. {@link launchVelocityForForce} is the forward
+ * conversion an ability applies at launch.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * The push-off force (newtons) the legs must deliver for the body to reach a
+ * given apex height — i.e. newtons BACK-CALCULATED from the desired maximum
+ * jump height on this character.
+ *
+ *     F = m · g · h / d
+ *
+ * Heavier body → more force for the same height; stronger gravity → more force;
+ * a longer push-off distance → less force (the work is spread over more travel).
+ *
+ * @param {number} mass             body mass, kg (> 0)
+ * @param {number} gravity          gravitational acceleration, m/s² (> 0)
+ * @param {number} pushoffDistance  leg push-off distance, m (> 0)
+ * @param {number} height           desired apex height above launch, m (>= 0)
+ * @returns {number} push-off force in newtons
+ */
+export function jumpForceForHeight(mass: number, gravity: number, pushoffDistance: number, height: number): number;
+/**
+ * The apex height (meters) a given push-off force produces on this character —
+ * the inverse of {@link jumpForceForHeight}.
+ *
+ *     h = F · d / (m · g)
+ *
+ * @param {number} force            push-off force, newtons (>= 0)
+ * @param {number} mass             body mass, kg (> 0)
+ * @param {number} gravity          gravitational acceleration, m/s² (> 0)
+ * @param {number} pushoffDistance  leg push-off distance, m (> 0)
+ * @returns {number} apex height above launch, meters
+ */
+export function jumpHeightForForce(force: number, mass: number, gravity: number, pushoffDistance: number): number;
+/**
+ * The launch velocity (m/s) a given push-off force imparts to this character —
+ * the forward conversion an ability applies at the instant of launch.
+ *
+ *     v₀ = √(2 · F · d / m)
+ *
+ * Note this is independent of gravity: gravity only governs the apex the launch
+ * velocity then reaches, not the launch itself.
+ *
+ * @param {number} force            push-off force, newtons (>= 0)
+ * @param {number} mass             body mass, kg (> 0)
+ * @param {number} pushoffDistance  leg push-off distance, m (> 0)
+ * @returns {number} launch velocity, m/s
+ */
+export function launchVelocityForForce(force: number, mass: number, pushoffDistance: number): number;
+//# sourceMappingURL=jumpDynamics.d.ts.map

package/src/engine/control/first-person/math/jumpDynamics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jumpDynamics.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/math/jumpDynamics.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,yCANW,MAAM,WACN,MAAM,mBACN,MAAM,UACN,MAAM,GACJ,MAAM,CASlB;AAED;;;;;;;;;;;GAWG;AACH,0CANW,MAAM,QACN,MAAM,WACN,MAAM,mBACN,MAAM,GACJ,MAAM,CASlB;AAED;;;;;;;;;;;;;GAaG;AACH,8CALW,MAAM,QACN,MAAM,mBACN,MAAM,GACJ,MAAM,CAQlB"}