@woosh/meep-engine 2.155.0 → 2.156.0

package/src/engine/control/first-person/FirstPersonMotionPhase.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The single source of motion-phase transition logic: given the current phase
+ * and a per-tick input snapshot, return the next phase. Pure — no side effects,
+ * no controller/runtime coupling — so it's exhaustively unit-testable.
+ *
+ * @param {number} phase current {@link MotionPhase}
+ * @param {{
+ *   grounded: boolean,          // on a walkable surface this tick (from the mover)
+ *   ascending: boolean,         // velocityY > 0 this tick
+ *   jumpEdge: boolean,          // jump pressed this tick (rising edge)
+ *   coyote: boolean,            // within the post-walk-off coyote window
+ *   anticipationDone: boolean,  // the squash timer elapsed this tick
+ * }} input
+ * @returns {number} next {@link MotionPhase}
+ */
+export function selectMotionPhase(phase: number, input: {
+    grounded: boolean;
+    ascending: boolean;
+    jumpEdge: boolean;
+    coyote: boolean;
+    anticipationDone: boolean;
+}): number;
+/**
+ * Build the shared {@link SimpleStateMachineDescription} — the declared state
+ * graph (states + valid edges). Each controller entity instantiates a
+ * {@link SimpleStateMachine} over this one description and registers its own
+ * entry/exit handlers. The transition LOGIC lives in {@link selectMotionPhase};
+ * the graph here documents and (optionally) validates the reachable edges.
+ *
+ * @returns {SimpleStateMachineDescription}
+ */
+export function buildMotionPhaseDescription(): SimpleStateMachineDescription;
+/**
+ * Drive a {@link SimpleStateMachine} one step by the pure transition logic,
+ * transitioning ONLY on an actual change so the machine's entry/exit handlers
+ * fire once per real transition (SimpleStateMachine.setState fires them on
+ * every call, including same-state — we guard that here).
+ *
+ * @param {import("../../../core/fsm/simple/SimpleStateMachine.js").SimpleStateMachine} machine
+ * @param {object} input see {@link selectMotionPhase}
+ * @returns {number} the phase after the step
+ */
+export function advanceMotionPhase(machine: import("../../../core/fsm/simple/SimpleStateMachine.js").SimpleStateMachine, input: object): number;
+export namespace MotionPhase {
+    let Grounded: number;
+    let Anticipating: number;
+    let Rising: number;
+    let Falling: number;
+}
+/** Human-readable phase names, indexed by phase id. For diagnostics. */
+export const MOTION_PHASE_NAME: string[];
+/** Shared description instance — stateless, reused by every controller entity. */
+export const MOTION_PHASE_DESCRIPTION: SimpleStateMachineDescription;
+import { SimpleStateMachineDescription } from "../../../core/fsm/simple/SimpleStateMachineDescription.js";
+//# sourceMappingURL=FirstPersonMotionPhase.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FirstPersonMotionPhase.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonMotionPhase.js"],"names":[],"mappings":"AAwCA;;;;;;;;;;;;;;GAcG;AACH,yCAVW,MAAM,SACN;IACV,QAAY,EAAE,OAAO,CAAC;IACtB,SAAa,EAAE,OAAO,CAAC;IACvB,QAAY,EAAE,OAAO,CAAC;IACtB,MAAU,EAAE,OAAO,CAAC;IACpB,gBAAoB,EAAE,OAAO,CAAC;CAC3B,GACS,MAAM,CA+BlB;AAED;;;;;;;;GAQG;AACH,+CAFa,6BAA6B,CAkBzC;AAKD;;;;;;;;;GASG;AACH,4CAJW,OAAO,gDAAgD,EAAE,kBAAkB,SAC3E,MAAM,GACJ,MAAM,CASlB;;;;;;;AAhGD,wEAAwE;AACxE,yCAAmF;AA2EnF,kFAAkF;AAClF,qEAAsE;8CAlHxB,2DAA2D"}

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

@@ -0,0 +1,134 @@
+import { SimpleStateMachineDescription } from "../../../core/fsm/simple/SimpleStateMachineDescription.js";
+
+/**
+ * Explicit ground/air/jump phase for the first-person controller.
+ *
+ * Today the controller tracks this with a handful of loose booleans
+ * (`grounded`, `inJumpAnticipation`, `midJump`, `isAscending`,
+ * `isVariableJumpCut`, `apexFired`) written by base locomotion AND by
+ * abilities, with no single owner — a fragile implicit state machine. This
+ * makes the phase EXPLICIT and the transitions a single, pure, unit-testable
+ * function, so a wrong transition (the kind that surfaces as a camera snap a
+ * frame or seconds later) is inspectable instead of smeared across the hot
+ * path.
+ *
+ * States:
+ *  - Grounded      — on a walkable surface, not committed to a jump.
+ *  - Anticipating  — grounded squash window after a jump press, before the
+ *                    impulse fires (and the coyote-jump entry from Falling).
+ *  - Rising        — airborne with upward velocity from a jump impulse.
+ *  - Falling       — airborne with non-upward velocity (apex passed, or walked
+ *                    off a ledge without jumping).
+ *
+ * Drive it with {@link advanceMotionPhase}, which only transitions on an actual
+ * change (so a SimpleStateMachine's entry/exit handlers fire once per real
+ * transition — the natural home for onLand / onLeaveGround / jump-impulse /
+ * apex side effects — rather than every tick).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const MotionPhase = {
+    Grounded: 0,
+    Anticipating: 1,
+    Rising: 2,
+    Falling: 3,
+};
+
+/** Human-readable phase names, indexed by phase id. For diagnostics. */
+export const MOTION_PHASE_NAME = ["Grounded", "Anticipating", "Rising", "Falling"];
+
+/**
+ * The single source of motion-phase transition logic: given the current phase
+ * and a per-tick input snapshot, return the next phase. Pure — no side effects,
+ * no controller/runtime coupling — so it's exhaustively unit-testable.
+ *
+ * @param {number} phase current {@link MotionPhase}
+ * @param {{
+ *   grounded: boolean,          // on a walkable surface this tick (from the mover)
+ *   ascending: boolean,         // velocityY > 0 this tick
+ *   jumpEdge: boolean,          // jump pressed this tick (rising edge)
+ *   coyote: boolean,            // within the post-walk-off coyote window
+ *   anticipationDone: boolean,  // the squash timer elapsed this tick
+ * }} input
+ * @returns {number} next {@link MotionPhase}
+ */
+export function selectMotionPhase(phase, input) {
+    switch (phase) {
+        case MotionPhase.Grounded:
+            // Grounded can always commit a jump; otherwise it only leaves the
+            // ground by losing contact (walk off a ledge).
+            if (input.jumpEdge) return MotionPhase.Anticipating;
+            return input.grounded ? MotionPhase.Grounded : MotionPhase.Falling;
+
+        case MotionPhase.Anticipating:
+            // The squash commits to the jump: it holds until the timer elapses
+            // (even if the ground slid out — rug-pull / moving platform), then
+            // the impulse fires (→ Rising).
+            return input.anticipationDone ? MotionPhase.Rising : MotionPhase.Anticipating;
+
+        case MotionPhase.Rising:
+            // A jump that bonks a ceiling or lands instantly re-grounds; else it
+            // rises until velocity stops being upward (apex → Falling).
+            if (input.grounded) return MotionPhase.Grounded;
+            return input.ascending ? MotionPhase.Rising : MotionPhase.Falling;
+
+        case MotionPhase.Falling:
+            // Coyote jump: a jump press shortly after walking off still takes.
+            // Otherwise we fall until we land.
+            if (input.jumpEdge && input.coyote) return MotionPhase.Anticipating;
+            return input.grounded ? MotionPhase.Grounded : MotionPhase.Falling;
+
+        default:
+            return phase;
+    }
+}
+
+/**
+ * Build the shared {@link SimpleStateMachineDescription} — the declared state
+ * graph (states + valid edges). Each controller entity instantiates a
+ * {@link SimpleStateMachine} over this one description and registers its own
+ * entry/exit handlers. The transition LOGIC lives in {@link selectMotionPhase};
+ * the graph here documents and (optionally) validates the reachable edges.
+ *
+ * @returns {SimpleStateMachineDescription}
+ */
+export function buildMotionPhaseDescription() {
+    const d = new SimpleStateMachineDescription();
+    d.createState(MotionPhase.Grounded);
+    d.createState(MotionPhase.Anticipating);
+    d.createState(MotionPhase.Rising);
+    d.createState(MotionPhase.Falling);
+
+    d.createEdge(MotionPhase.Grounded, MotionPhase.Anticipating);
+    d.createEdge(MotionPhase.Grounded, MotionPhase.Falling);
+    d.createEdge(MotionPhase.Anticipating, MotionPhase.Rising);
+    d.createEdge(MotionPhase.Rising, MotionPhase.Grounded);
+    d.createEdge(MotionPhase.Rising, MotionPhase.Falling);
+    d.createEdge(MotionPhase.Falling, MotionPhase.Grounded);
+    d.createEdge(MotionPhase.Falling, MotionPhase.Anticipating);
+
+    return d;
+}
+
+/** Shared description instance — stateless, reused by every controller entity. */
+export const MOTION_PHASE_DESCRIPTION = buildMotionPhaseDescription();
+
+/**
+ * Drive a {@link SimpleStateMachine} one step by the pure transition logic,
+ * transitioning ONLY on an actual change so the machine's entry/exit handlers
+ * fire once per real transition (SimpleStateMachine.setState fires them on
+ * every call, including same-state — we guard that here).
+ *
+ * @param {import("../../../core/fsm/simple/SimpleStateMachine.js").SimpleStateMachine} machine
+ * @param {object} input see {@link selectMotionPhase}
+ * @returns {number} the phase after the step
+ */
+export function advanceMotionPhase(machine, input) {
+    const current = machine.getState();
+    const next = selectMotionPhase(current, input);
+    if (next !== current) {
+        machine.setState(next);
+    }
+    return next;
+}

package/src/engine/control/first-person/FirstPersonPlayerController.d.ts

@@ -48,12 +48,13 @@ export class FirstPersonPlayerController {
                 radius: number;
                 mass: number;
                 referenceMass: number;
+                jumpPushoffDistance: number;
                 massCouplingStrength: number;
             };
             motion: {
                 walkSpeed: number;
                 sprintSpeed: number;
-                crouchSpeed: number;
+                crouchSpeed: number; /** Set true when crouch was released but a ceiling above prevents standing. */
                 airControl: number;
                 groundAccelHalfLife: number;
                 groundDecel: number;
@@ -95,12 +96,31 @@ export class FirstPersonPlayerController {
                 exertionRiseRate: number;
                 minAirborneTime: number;
                 mantleUpUpFactor: number;
+                shimmySpeed: number;
+                pullUpFacingConeDeg: number;
+                moveTowardThreshold: number;
+                moveAwayThreshold: number;
+                regrabCooldown: number;
+                shimmyLateralMin: number;
+                shimmyClearanceGap: number;
+                shimmyClearanceProbeY: number;
+                shimmyEdgeProbeForward: number;
+                shimmyContinuityProbeUp: number;
+                shimmyContinuityProbeDown: number;
+                shimmyContinuityTol: number;
+                shimmyExertionFactor: number;
             };
             mantle: {
                 minHeight: number;
                 maxHeight: number;
                 duration: number;
                 forwardOffsetOnLand: number;
+                pullUpMaxHeight: number;
+                vaultDistance: number;
+                vaultApexClearance: number;
+                vaultDropOnExit: number;
+                vaultExitSpeed: number;
+                vaultExitDownSpeed: number;
             };
             wallRun: {
                 minSpeed: number;
@@ -185,6 +205,7 @@ export class FirstPersonPlayerController {
                 pitchMinDeg: number;
                 pitchMaxDeg: number;
                 invertY: boolean;
+                maxFrameDeltaRad: number;
             };
             posture: {
                 sprintForwardPitchDeg: number;
@@ -308,7 +329,7 @@ declare class FirstPersonSignals {
     onBreathOut: Signal<any, any, any, any, any, any, any, any>;
     /** {ledgeHeight:number} — fired when LedgeGrab activates. */
     onLedgeGrab: Signal<any, any, any, any, any, any, any, any>;
-    /** {reason:"mantle-up"|"drop"|"slip"|"shuffle-off"} */
+    /** {reason:"mantle-up"|"vault"|"drop"|"slip"|"shuffle-off"} */
     onLedgeRelease: Signal<any, any, any, any, any, any, any, any>;
 }
 import { MasterySet } from "./mastery/MasterySet.js";

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

@@ -1 +1 @@
-{"version":3,"file":"FirstPersonPlayerController.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerController.js"],"names":[],"mappings":"AA8HA;;;;;;;;;;GAUG;AACH;IACI,wBAAgD;IAG5C,0CAAqD;IACrD,0BAAqC;IACrC,wBAAmC;IACnC,sBAAiC;IACjC,4BAAuC;IAEvC;;;;;;OAMG;IACH,SAFU,UAAU,CAEW;IAE/B;;;;;OAKG;IACH,WAFU,UAAU,CAEa;IAEjC;;;;;;OAMG;IACH,WAFU,MAAM,CAEG;IAGvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAEC;IAED,0BAIC;IAED;;OAEG;IACH,YAFW,2BAA2B,QAKrC;IAED,qCAIC;IAED,4BAGC;IAED,eAGC;CACJ;;;;;kDA3MiD,wCAAwC;AAK1F;;;;;;;;GAQG;AACH;IACI,oEAAoE;IACpE,MADyD,OAAO,CACvC;IAEzB;;;;OAIG;IACH,MAFU,OAAO,CAEQ;IAEzB,mEAAmE;IACnE,MADwD,OAAO,CAClD;IAEb,0EAA0E;IAC1E,QAD+D,OAAO,CACvD;IAEf,qEAAqE;IACrE,QAD0D,OAAO,CAClD;CAClB;AAED;;;GAGG;AACH;IACI,kBAAgB;IAChB,0BAAsB;IAEtB,4EAA4E;IAC5E,sBAAoC;IACpC,gBAAkB;IAElB,cAAU;IACV,4DAA4D;IAC5D,wBAAoB;IACpB,yEAAyE;IACzE,uBAAgD;IAEhD,sBAAkB;IAClB,qBAAiB;IACjB,qBAAiB;IAEjB,4BAAwB;IACxB,4BAA2B;IAC3B,2BAA0B;IAC1B,2EAA2E;IAC3E,qBAAoB;IAEpB,iBAAa;IACb,oBAAgB;IAChB,qBAAiB;IACjB,yBAAqB;IAErB,oBAAgB;IAChB,kBAAc;IACd,kDAAkD;IAClD,iBAAa;IAEb,kBAAiB;IAEjB,+EAA+E;IAC/E,uBAAsB;IACtB,6EAA6E;IAC7E,sBAAqB;IAErB;;;;;;;OAOG;IACH,SAFU,MAAM,CAEmB;IAEnC,oBAAgB;CACnB;gCAzFkF,2BAA2B;AA2F9G;;;GAGG;AACH;IACI,uDAAuD;IACvD,2DAA0B;IAC1B,yEAAyE;IACzE,4DAA2B;IAC3B,kBAAkB;IAClB,2DAA0B;IAC1B,6BAA6B;IAC7B,8DAA6B;IAC7B,iDAAiD;IACjD,uDAAsB;IACtB,8DAA6B;IAC7B,6DAA4B;IAC5B,8DAA6B;IAC7B,6DAA4B;IAC5B,2EAA2E;IAC3E,2DAA0B;IAC1B,2EAA2E;IAC3E,4DAA2B;IAC3B,6DAA6D;IAC7D,4DAA2B;IAC3B,uDAAuD;IACvD,+DAA8B;CACjC;2BAvH0B,yBAAyB;2BAFzB,2BAA2B;uCAG6B,2BAA2B;0CAA3B,2BAA2B;oBAL1F,+BAA+B;oBAC/B,+BAA+B;mBAFhC,uCAAuC"}
+{"version":3,"file":"FirstPersonPlayerController.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerController.js"],"names":[],"mappings":"AA8HA;;;;;;;;;;GAUG;AACH;IACI,wBAAgD;IAG5C,0CAAqD;IACrD,0BAAqC;IACrC,wBAAmC;IACnC,sBAAiC;IACjC,4BAAuC;IAEvC;;;;;;OAMG;IACH,SAFU,UAAU,CAEW;IAE/B;;;;;OAKG;IACH,WAFU,UAAU,CAEa;IAEjC;;;;;;OAMG;IACH,WAFU,MAAM,CAEG;IAGvB;;;;;;;;;;;;;;;qCA/FA,+EAA+E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAiG9E;IAED,0BAIC;IAED;;OAEG;IACH,YAFW,2BAA2B,QAKrC;IAED,qCAIC;IAED,4BAGC;IAED,eAGC;CACJ;;;;;kDA3MiD,wCAAwC;AAK1F;;;;;;;;GAQG;AACH;IACI,oEAAoE;IACpE,MADyD,OAAO,CACvC;IAEzB;;;;OAIG;IACH,MAFU,OAAO,CAEQ;IAEzB,mEAAmE;IACnE,MADwD,OAAO,CAClD;IAEb,0EAA0E;IAC1E,QAD+D,OAAO,CACvD;IAEf,qEAAqE;IACrE,QAD0D,OAAO,CAClD;CAClB;AAED;;;GAGG;AACH;IACI,kBAAgB;IAChB,0BAAsB;IAEtB,4EAA4E;IAC5E,sBAAoC;IACpC,gBAAkB;IAElB,cAAU;IACV,4DAA4D;IAC5D,wBAAoB;IACpB,yEAAyE;IACzE,uBAAgD;IAEhD,sBAAkB;IAClB,qBAAiB;IACjB,qBAAiB;IAEjB,4BAAwB;IACxB,4BAA2B;IAC3B,2BAA0B;IAC1B,2EAA2E;IAC3E,qBAAoB;IAEpB,iBAAa;IACb,oBAAgB;IAChB,qBAAiB;IACjB,yBAAqB;IAErB,oBAAgB;IAChB,kBAAc;IACd,kDAAkD;IAClD,iBAAa;IAEb,kBAAiB;IAEjB,+EAA+E;IAC/E,uBAAsB;IACtB,6EAA6E;IAC7E,sBAAqB;IAErB;;;;;;;OAOG;IACH,SAFU,MAAM,CAEmB;IAEnC,oBAAgB;CACnB;gCAzFkF,2BAA2B;AA2F9G;;;GAGG;AACH;IACI,uDAAuD;IACvD,2DAA0B;IAC1B,yEAAyE;IACzE,4DAA2B;IAC3B,kBAAkB;IAClB,2DAA0B;IAC1B,6BAA6B;IAC7B,8DAA6B;IAC7B,iDAAiD;IACjD,uDAAsB;IACtB,8DAA6B;IAC7B,6DAA4B;IAC5B,8DAA6B;IAC7B,6DAA4B;IAC5B,2EAA2E;IAC3E,2DAA0B;IAC1B,2EAA2E;IAC3E,4DAA2B;IAC3B,6DAA6D;IAC7D,4DAA2B;IAC3B,+DAA+D;IAC/D,+DAA8B;CACjC;2BAvH0B,yBAAyB;2BAFzB,2BAA2B;uCAG6B,2BAA2B;0CAA3B,2BAA2B;oBAL1F,+BAA+B;oBAC/B,+BAA+B;mBAFhC,uCAAuC"}

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

@@ -120,7 +120,7 @@ class FirstPersonSignals {
     onBreathOut = new Signal();
     /** {ledgeHeight:number} — fired when LedgeGrab activates. */
     onLedgeGrab = new Signal();
-    /** {reason:"mantle-up"|"drop"|"slip"|"shuffle-off"} */
+    /** {reason:"mantle-up"|"vault"|"drop"|"slip"|"shuffle-off"} */
     onLedgeRelease = new Signal();
 }
 

package/src/engine/control/first-person/FirstPersonPlayerControllerConfig.d.ts

@@ -22,6 +22,15 @@ export class FirstPersonPlayerControllerConfig {
         mass: number;
         /** Reference mass against which `mass` is normalized (massRatio = mass/refMass). */
         referenceMass: number;
+        /**
+         * Leg push-off distance, meters — the crouch-to-full-extension travel
+         * over which the legs do their launching work. Together with `mass` it
+         * turns a jump FORCE (newtons) into a launch velocity via the work-energy
+         * model in {@link jumpDynamics} (`v₀ = √(2·F·d/m)`). ~0.45 m matches a
+         * ~1.8 m human countermovement jump. See {@link jumpForceForHeight} for
+         * the back-calculation from a desired apex height.
+         */
+        jumpPushoffDistance: number;
         /**
          * How strongly `mass` couples into derived effects. 0 = mass is
          * cosmetic; 1.0 = full coupling (heavier ⇒ lower jump, lower accel,
@@ -158,6 +167,38 @@ export class FirstPersonPlayerControllerConfig {
          *  is allowed (when not already wall-running). */
         nearWallMaxDistance: number;
     };
+    /**
+     * Scramble-up ability — a short vertical wall-run up a wall the player runs
+     * INTO (à la Assassin's Creed), to reach a high ledge to grab or to kick
+     * off. Fields here are consumed by the {@link ScrambleUp} ability if
+     * registered; ignored otherwise.
+     */
+    scrambleUp: {
+        /** Standstill push-off force (N) — a scramble jumped with no run-up. At
+         *  the default 80 kg body + 0.45 m push-off this launches ~5 m/s (~0.9 m
+         *  up the wall at the default decel). */
+        baseJumpForce: number;
+        /** Force (N) added per m/s of horizontal approach speed at the jump —
+         *  the running-start reward, in the same physical currency as the base. */
+        momentumForcePerSpeed: number;
+        /** Cap on the push-off force (N) — a full sprint run-up tops out here
+         *  (~9 m/s launch, ~2.9 m climb at the default body + decel). */
+        maxJumpForce: number;
+        /** Upward deceleration (m/s²) — strong, so the climb is a SHORT burst:
+         *  apex ≈ launchVy²/(2·decel) m high, reached in launchVy/decel s. */
+        decel: number;
+        /** Small into-wall speed (m/s) holding the body against the face as it
+         *  climbs (the mover clips the penetration). */
+        hugSpeed: number;
+        /** Safety cap on scramble duration (s) — releases even if the apex
+         *  somehow isn't reached. */
+        maxDuration: number;
+        /** Wall-kick (jump during the scramble): outward impulse (m/s along the
+         *  wall normal). The kick's UPWARD launch is not tuned here — it uses the
+         *  body's full jump push-off force (`runtime.jumpForce`), so a wall-kick
+         *  rises like a max-height jump. */
+        kickOutwardImpulse: number;
+    };
     /**
      * Ledge-grab ability — snap to a forward ledge while descending and
      * hang from it until the player releases. Climbing fatigue is
@@ -186,6 +227,44 @@ export class FirstPersonPlayerControllerConfig {
          *  ledge so mantle's ledgeAhead probe still resolves correctly
          *  on the next tick. */
         mantleUpUpFactor: number;
+        /** Shimmy speed along the edge (m/s). */
+        shimmySpeed: number;
+        /** Pressing jump pulls up only when facing within this half-cone of
+         *  the wall (degrees); facing further away leaves you hanging. */
+        pullUpFacingConeDeg: number;
+        /** World-move toward the wall above this (unit move) triggers pull-up. */
+        moveTowardThreshold: number;
+        /** World-move away from the wall must exceed this AND dominate the
+         *  lateral component to trigger a drop. Set HIGHER than
+         *  `moveTowardThreshold` on purpose: dismounting (you fall) is more
+         *  consequential than a pull-up or a shimmy, so it takes a clearly
+         *  committed, off-the-wall push — a strafe taken while looking somewhat
+         *  off the wall reads as a shimmy, not an ejection. */
+        moveAwayThreshold: number;
+        /** Refractory window (seconds) after ANY ledge release during which the
+         *  auto-catch can't re-grab. A deliberate dismount drops you straight
+         *  down the wall face, where the forward/ledge probes keep firing — so
+         *  without this the auto-catch would immediately re-grab the same lip,
+         *  snapping the body back onto the wall. ~0.3s lets the body fall clear
+         *  of the grab window first. (The old forward-intent grab gate hid this;
+         *  auto-catch needs it explicit.) */
+        regrabCooldown: number;
+        /** Lateral world-move above this (and dominant) triggers a shimmy step. */
+        shimmyLateralMin: number;
+        /** Extra gap beyond the capsule radius the lateral clearance ray needs. */
+        shimmyClearanceGap: number;
+        /** Height (relative to the edge) to cast the lateral clearance ray. */
+        shimmyClearanceProbeY: number;
+        /** Forward (into-wall) offset of the continuity down-probe past the edge. */
+        shimmyEdgeProbeForward: number;
+        /** Continuity down-probe starts this far above the edge… */
+        shimmyContinuityProbeUp: number;
+        /** …and reaches this far below it. */
+        shimmyContinuityProbeDown: number;
+        /** Continuity hit must be within this of the edge height to count. */
+        shimmyContinuityTol: number;
+        /** Exertion rises this much faster while actively shimmying. */
+        shimmyExertionFactor: number;
     };
     /**
      * Mantle ability — auto-triggers when the player approaches a
@@ -209,6 +288,19 @@ export class FirstPersonPlayerControllerConfig {
          *  forward bias so the player ends on top of the surface, not
          *  on the edge. */
         forwardOffsetOnLand: number;
+        /** Reachable-height ceiling when pulling up from a hang (vs maxHeight
+         *  for auto-mantle) — the hang sits right at ~maxHeight, so give slack. */
+        pullUpMaxHeight: number;
+        /** How far past the grab edge the vault carries the body before release. */
+        vaultDistance: number;
+        /** Apex height above the edge the vault hump rises to. */
+        vaultApexClearance: number;
+        /** How far below the apex the vault descends before it releases. */
+        vaultDropOnExit: number;
+        /** Forward speed handed back on a vault release (carries you over). */
+        vaultExitSpeed: number;
+        /** Downward speed handed back on a vault release (so you commit over). */
+        vaultExitDownSpeed: number;
     };
     /**
      * Slide ability — activates from sprint+crouch when grounded. The
@@ -422,6 +514,14 @@ export class FirstPersonPlayerControllerConfig {
         pitchMinDeg: number;
         pitchMaxDeg: number;
         invertY: boolean;
+        /** Input-SPIKE rejection. A single render frame whose look delta
+         *  (radians, after sensitivity) exceeds this is treated as a corrupt
+         *  mouse/driver `movementX` glitch — NOT a real turn — and dropped. This
+         *  is what stops the 20–100° camera snap from a high-res mouse under OS
+         *  pointer acceleration / a browser pointer-lock burst. Even an
+         *  extremely fast flick stays well under this at render rate (~0.3 rad ≈
+         *  17° in one frame would already be ~4000°/s). */
+        maxFrameDeltaRad: number;
     };
     /**
      * Postural shifts driven by intent — distinct from look (which is
@@ -461,6 +561,15 @@ export class FirstPersonPlayerControllerConfig {
             mass: number;
             /** Reference mass against which `mass` is normalized (massRatio = mass/refMass). */
             referenceMass: number;
+            /**
+             * Leg push-off distance, meters — the crouch-to-full-extension travel
+             * over which the legs do their launching work. Together with `mass` it
+             * turns a jump FORCE (newtons) into a launch velocity via the work-energy
+             * model in {@link jumpDynamics} (`v₀ = √(2·F·d/m)`). ~0.45 m matches a
+             * ~1.8 m human countermovement jump. See {@link jumpForceForHeight} for
+             * the back-calculation from a desired apex height.
+             */
+            jumpPushoffDistance: number;
             /**
              * How strongly `mass` couples into derived effects. 0 = mass is
              * cosmetic; 1.0 = full coupling (heavier ⇒ lower jump, lower accel,
@@ -578,6 +687,44 @@ export class FirstPersonPlayerControllerConfig {
              *  ledge so mantle's ledgeAhead probe still resolves correctly
              *  on the next tick. */
             mantleUpUpFactor: number;
+            /** Shimmy speed along the edge (m/s). */
+            shimmySpeed: number;
+            /** Pressing jump pulls up only when facing within this half-cone of
+             *  the wall (degrees); facing further away leaves you hanging. */
+            pullUpFacingConeDeg: number;
+            /** World-move toward the wall above this (unit move) triggers pull-up. */
+            moveTowardThreshold: number;
+            /** World-move away from the wall must exceed this AND dominate the
+             *  lateral component to trigger a drop. Set HIGHER than
+             *  `moveTowardThreshold` on purpose: dismounting (you fall) is more
+             *  consequential than a pull-up or a shimmy, so it takes a clearly
+             *  committed, off-the-wall push — a strafe taken while looking somewhat
+             *  off the wall reads as a shimmy, not an ejection. */
+            moveAwayThreshold: number;
+            /** Refractory window (seconds) after ANY ledge release during which the
+             *  auto-catch can't re-grab. A deliberate dismount drops you straight
+             *  down the wall face, where the forward/ledge probes keep firing — so
+             *  without this the auto-catch would immediately re-grab the same lip,
+             *  snapping the body back onto the wall. ~0.3s lets the body fall clear
+             *  of the grab window first. (The old forward-intent grab gate hid this;
+             *  auto-catch needs it explicit.) */
+            regrabCooldown: number;
+            /** Lateral world-move above this (and dominant) triggers a shimmy step. */
+            shimmyLateralMin: number;
+            /** Extra gap beyond the capsule radius the lateral clearance ray needs. */
+            shimmyClearanceGap: number;
+            /** Height (relative to the edge) to cast the lateral clearance ray. */
+            shimmyClearanceProbeY: number;
+            /** Forward (into-wall) offset of the continuity down-probe past the edge. */
+            shimmyEdgeProbeForward: number;
+            /** Continuity down-probe starts this far above the edge… */
+            shimmyContinuityProbeUp: number;
+            /** …and reaches this far below it. */
+            shimmyContinuityProbeDown: number;
+            /** Continuity hit must be within this of the edge height to count. */
+            shimmyContinuityTol: number;
+            /** Exertion rises this much faster while actively shimmying. */
+            shimmyExertionFactor: number;
         };
         mantle: {
             /** Below this height (m above feet), the obstacle is just a step
@@ -594,6 +741,19 @@ export class FirstPersonPlayerControllerConfig {
              *  forward bias so the player ends on top of the surface, not
              *  on the edge. */
             forwardOffsetOnLand: number;
+            /** Reachable-height ceiling when pulling up from a hang (vs maxHeight
+             *  for auto-mantle) — the hang sits right at ~maxHeight, so give slack. */
+            pullUpMaxHeight: number;
+            /** How far past the grab edge the vault carries the body before release. */
+            vaultDistance: number;
+            /** Apex height above the edge the vault hump rises to. */
+            vaultApexClearance: number;
+            /** How far below the apex the vault descends before it releases. */
+            vaultDropOnExit: number;
+            /** Forward speed handed back on a vault release (carries you over). */
+            vaultExitSpeed: number;
+            /** Downward speed handed back on a vault release (so you commit over). */
+            vaultExitDownSpeed: number;
         };
         wallRun: {
             /**
@@ -830,6 +990,14 @@ export class FirstPersonPlayerControllerConfig {
             pitchMinDeg: number;
             pitchMaxDeg: number;
             invertY: boolean;
+            /** Input-SPIKE rejection. A single render frame whose look delta
+             *  (radians, after sensitivity) exceeds this is treated as a corrupt
+             *  mouse/driver `movementX` glitch — NOT a real turn — and dropped. This
+             *  is what stops the 20–100° camera snap from a high-res mouse under OS
+             *  pointer acceleration / a browser pointer-lock burst. Even an
+             *  extremely fast flick stays well under this at render rate (~0.3 rad ≈
+             *  17° in one frame would already be ~4000°/s). */
+            maxFrameDeltaRad: number;
         };
         posture: {
             /** Forward pitch (deg) applied to the eye at full sprint. Positive = look-down. */

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

@@ -1 +1 @@
-{"version":3,"file":"FirstPersonPlayerControllerConfig.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerControllerConfig.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"FirstPersonPlayerControllerConfig.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerControllerConfig.js"],"names":[],"mappings":"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"}