@woosh/meep-engine 2.138.20 → 2.140.0

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

@@ -0,0 +1,166 @@
+import { DecisionPoint } from "../mastery/DecisionPoint.js";
+import { FirstPersonLocomotionMode } from "../pose/FirstPersonPose.js";
+import { FirstPersonPosture } from "../pose/FirstPersonPosture.js";
+import { Ability } from "./Ability.js";
+
+/**
+ * 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 {
+    constructor() {
+        super();
+        this.name = "Slide";
+        /** Lowest of the movement abilities. Wall-jump, mantle, etc. preempt. */
+        this.priority = 10;
+
+        /** @private Counts down during the non-interruptible window. */
+        this._startupRemaining = 0;
+    }
+
+    canActivate(controller, runtime, _sensors) {
+        const cfg = controller.config.slide;
+        if (!cfg) return false; // slide config not present
+        if (!controller.state.grounded) return false;
+        if (!controller.intent.crouch) return false;
+        // Rising-edge crouch — runtime.prevCrouchHeld tracks the last frame's
+        // intent.crouch. If both are true we're past the press; require an
+        // actual transition. (Without this, the player could enter slide
+        // simply by holding crouch and walking up to sprint speed.)
+        if (runtime.prevCrouchHeld) return false;
+        // Need significant horizontal speed — slide is a run-into-slide,
+        // not a standstill-into-slide. The mono-exponential ground
+        // accel model (see FirstPersonPlayerControllerConfig.js's
+        // `groundAccelHalfLife`) ensures reaching this threshold from
+        // standstill naturally requires ~300 ms of committed sprint —
+        // longer than human reaction time — so the speed gate alone is
+        // enough to make slide feel earned. Speed-only is also the
+        // right model for the cases the design wants to explicitly
+        // allow: walking off a ledge or accelerating down a slope into
+        // a slide. (Following Apex Legends' velocity-only gate.)
+        const speed = Math.hypot(runtime.velocityX, runtime.velocityZ);
+        if (speed < cfg.minEntrySpeed) return false;
+        return true;
+    }
+
+    onActivate(controller, runtime) {
+        const cfg = controller.config.slide;
+        this._startupRemaining = cfg.startupWindow;
+
+        // Mastery: scale entry velocity preservation. Well-timed slides
+        // (stride midstance) bias the multiplier above 1.0; poorly-timed
+        // (foot-strike) bias it below. Default no-evaluator multiplier
+        // is 1.0 = exact velocity preservation. See
+        // {@link SlideInitiationTimingEvaluator}.
+        const masteryMul = controller.mastery.evaluate(
+            DecisionPoint.SlideEntryVelocity, controller, runtime,
+        );
+        runtime.velocityX *= masteryMul;
+        runtime.velocityZ *= masteryMul;
+
+        // Body is now horizontal — head close to ground, no striding
+        // feet. L2 reads posture to set eye height and gate gait
+        // (stride / footstep / bob).
+        controller.state.posture = FirstPersonPosture.Prone;
+
+        // Visual: kick the vertical impact spring downward for the entry
+        // "thud" — the camera dip that sells the body dropping into the slide.
+        runtime.verticalImpactSpring.kick(-cfg.entryImpactVelocity);
+    }
+
+    canInterrupt(_controller, _runtime) {
+        // Non-interruptible during the startup window.
+        return this._startupRemaining <= 0;
+    }
+
+    tick(controller, runtime, bodyTransform, dt, system) {
+        const cfg = controller.config.slide;
+
+        // Keep posture pinned each tick — if the base were to run
+        // before us on a release tick it would overwrite to Stand/Crouch;
+        // re-asserting here keeps L2 consistent across the slide.
+        controller.state.posture = FirstPersonPosture.Prone;
+        // No camera lean during slide — body is flat, head is pinned
+        // forward along the direction of travel.
+        runtime.leanTargetRad = 0;
+
+        // -- Tick the startup window (always counts down).
+        this._startupRemaining = Math.max(0, this._startupRemaining - dt);
+
+        // -- Exit conditions (checked FIRST, before any motion this tick).
+        // Released crouch.
+        if (!controller.intent.crouch) return false;
+        // Airborne.
+        if (!controller.state.grounded) return false;
+        // Speed dropped below floor — but only after the startup window
+        // (otherwise momentarily-low speed entries would auto-exit before
+        // the player has felt the slide).
+        const speed = Math.hypot(runtime.velocityX, runtime.velocityZ);
+        if (this._startupRemaining <= 0 && speed < cfg.endSpeed) return false;
+
+        // -- Slide-jump: if jump was pressed (rising edge), apply impulse
+        //    and release. Base will integrate the new vy on the same tick.
+        const jumpPressedEdge = controller.intent.jump && !runtime.prevJumpHeld;
+        // Note: we DO consume the jump-pressed edge here even though the
+        // jump FSM also reads it. Setting prevJumpHeld now means the FSM
+        // (which runs in base after we release) sees no rising edge and
+        // doesn't double-fire a normal jump.
+        runtime.prevJumpHeld = controller.intent.jump;
+        if (jumpPressedEdge) {
+            runtime.velocityY = runtime.jumpInitialVy * cfg.slideJumpUpFactor;
+            runtime.midJump = true;
+            runtime.apexFired = false;
+            runtime.peakAltitude = bodyTransform.position.y;
+            controller.state.isVariableJumpCut = false;
+            controller.state.isAscending = true;
+            // Mastery: scale the impulse via JumpImpulse evaluators if any.
+            // We deliberately reuse JumpImpulse rather than introducing a
+            // separate SlideJumpImpulse decision point — the player's
+            // skill at timing applies the same way.
+            // (Skipping for simplicity in this version; would mirror the
+            //  base controller's mastery application.)
+            controller.signals.onJumpStart.send1({ peakHeight: controller.config.jump.peakHeight });
+            controller.signals.onLeaveGround.send1({ reason: "jump" });
+            return false; // release; base handles integration this tick
+        }
+
+        // -- Motion: slide friction on horizontal velocity. Direction is
+        //    preserved (no steering in this minimal version — carving can
+        //    be added later as an evaluator-curve-driven term).
+        if (speed > 1e-6) {
+            const newSpeed = Math.max(0, speed - cfg.friction * dt);
+            const ratio = newSpeed / speed;
+            runtime.velocityX *= ratio;
+            runtime.velocityZ *= ratio;
+        }
+
+        // -- Vertical phase: delegate to the system's standard
+        //    gravity + integrate + ground resolution. Slide doesn't have
+        //    its own vertical model.
+        system._integrateVerticalAndResolveGround(controller, runtime, bodyTransform, dt);
+
+        return true;
+    }
+
+    onDeactivate(_controller, _runtime) {
+        this._startupRemaining = 0;
+    }
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Wall-jump ability — instantaneous off-wall impulse fired when the
+ * player presses jump while close to a wall. Designed to chain
+ * naturally from wall-run (its priority is higher, so it preempts wall-
+ * run's `canInterrupt()=true`) but ALSO fires from "near-wall airborne"
+ * — a window where the player is mid-jump near a wall they haven't
+ * committed to running.
+ *
+ * Activation:
+ *   - intent.jump just went true (rising edge)
+ *   - airborne (`!state.grounded`)
+ *   - a side wall sensor has hit within `nearWallMaxDistance`
+ *
+ * Behaviour:
+ *   - Apply impulse: `outwardImpulse * wall.normal + upImpulse * worldUp`
+ *     where `upImpulse = jumpInitialVy * upFactor`.
+ *   - Clear variableJumpCut so the impulse takes effect cleanly.
+ *   - Fire `onJumpStart` and `onLeaveGround{reason:"walljump"}` signals.
+ *   - Releases immediately (it's instantaneous, not a sustained state).
+ *
+ * The impulse goes through `mastery.evaluate(DecisionPoint.WallJumpImpulse)`
+ * so any registered evaluators (e.g. breath rhythm, wall-jump-angle
+ * timing) can scale it.
+ *
+ * Priority 60 — highest among movement abilities. Wall-jump must fire
+ * reliably on player press, so it preempts wall-run (50), mantle (30),
+ * and slide (10).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WallJump extends Ability {
+    canActivate(controller: any, runtime: any, sensors: any): boolean;
+    onActivate(controller: any, runtime: any): void;
+    /**
+     * Wall-jump is instantaneous — it shouldn't ever be "interrupted".
+     * tick() returns false on first call so the ability releases
+     * immediately. Returning false here doesn't matter (no other ability
+     * exceeds priority 60 in the default set).
+     */
+    canInterrupt(): boolean;
+    tick(_controller: any, _runtime: any, _bodyTransform: any, _dt: any, _system: any): boolean;
+}
+import { Ability } from "./Ability.js";
+//# sourceMappingURL=WallJump.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WallJump.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/abilities/WallJump.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;IAOI,kEAoBC;IAED,gDAgDC;IAED;;;;;OAKG;IACH,wBAEC;IAED,4FAKC;CACJ;wBAhIuB,cAAc"}

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

@@ -0,0 +1,131 @@
+import { clamp } from "../../../../core/math/clamp.js";
+import { DecisionPoint } from "../mastery/DecisionPoint.js";
+import { Ability } from "./Ability.js";
+
+/**
+ * Wall-jump ability — instantaneous off-wall impulse fired when the
+ * player presses jump while close to a wall. Designed to chain
+ * naturally from wall-run (its priority is higher, so it preempts wall-
+ * run's `canInterrupt()=true`) but ALSO fires from "near-wall airborne"
+ * — a window where the player is mid-jump near a wall they haven't
+ * committed to running.
+ *
+ * Activation:
+ *   - intent.jump just went true (rising edge)
+ *   - airborne (`!state.grounded`)
+ *   - a side wall sensor has hit within `nearWallMaxDistance`
+ *
+ * Behaviour:
+ *   - Apply impulse: `outwardImpulse * wall.normal + upImpulse * worldUp`
+ *     where `upImpulse = jumpInitialVy * upFactor`.
+ *   - Clear variableJumpCut so the impulse takes effect cleanly.
+ *   - Fire `onJumpStart` and `onLeaveGround{reason:"walljump"}` signals.
+ *   - Releases immediately (it's instantaneous, not a sustained state).
+ *
+ * The impulse goes through `mastery.evaluate(DecisionPoint.WallJumpImpulse)`
+ * so any registered evaluators (e.g. breath rhythm, wall-jump-angle
+ * timing) can scale it.
+ *
+ * Priority 60 — highest among movement abilities. Wall-jump must fire
+ * reliably on player press, so it preempts wall-run (50), mantle (30),
+ * and slide (10).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WallJump extends Ability {
+    constructor() {
+        super();
+        this.name = "WallJump";
+        this.priority = 60;
+    }
+
+    canActivate(controller, runtime, sensors) {
+        const cfg = controller.config.wallJump;
+        if (!cfg) return false;
+        if (sensors === undefined || sensors === null) return false;
+
+        // Edge-trigger: must be a fresh jump press, not a held jump.
+        if (!controller.intent.jump) return false;
+        if (runtime.prevJumpHeld) return false;
+
+        // Must be airborne — wall-jump from the ground is just a jump.
+        if (controller.state.grounded) return false;
+
+        // At least one side wall within the near-wall distance.
+        const left = sensors.wallLeft;
+        const right = sensors.wallRight;
+        const leftClose = left.hit && left.distance <= cfg.nearWallMaxDistance;
+        const rightClose = right.hit && right.distance <= cfg.nearWallMaxDistance;
+        if (!leftClose && !rightClose) return false;
+
+        return true;
+    }
+
+    onActivate(controller, runtime) {
+        const cfg = controller.config.wallJump;
+        const sensors = runtime.sensors;
+
+        // Pick the closer wall (also: if only one side is hit, use it).
+        let wallNormal;
+        const lH = sensors.wallLeft.hit;
+        const rH = sensors.wallRight.hit;
+        if (lH && (!rH || sensors.wallLeft.distance <= sensors.wallRight.distance)) {
+            wallNormal = sensors.wallLeft.normal;
+        } else {
+            wallNormal = sensors.wallRight.normal;
+        }
+
+        // Mastery: scale the impulse.
+        const masteryMul = controller.mastery.evaluate(
+            DecisionPoint.WallJumpImpulse, controller, runtime,
+        );
+
+        // Apply impulse. Outward is along the wall normal; up is along
+        // world up. Clamp upFactor positive to avoid pathological configs
+        // that would push the player into the ground.
+        const upFactor = clamp(cfg.upFactor, 0, 2);
+        runtime.velocityX += wallNormal.x * cfg.outwardImpulse * masteryMul;
+        runtime.velocityZ += wallNormal.z * cfg.outwardImpulse * masteryMul;
+        runtime.velocityY = runtime.jumpInitialVy * upFactor * masteryMul;
+
+        // Mark this as a fresh jump (so the base jump FSM doesn't think
+        // we're falling and the variable-cut logic doesn't try to cut
+        // the upward velocity).
+        runtime.midJump = true;
+        runtime.apexFired = false;
+        controller.state.isVariableJumpCut = false;
+        controller.state.isAscending = true;
+        // Consume the jump-press edge so the base jump FSM doesn't double-fire.
+        runtime.prevJumpHeld = true;
+
+        // Exertion impulse — same magnitude as a regular jump-fire.
+        const cfgExt = controller.config.exertion;
+        controller.state.exertion = clamp(
+            controller.state.exertion + cfgExt.jumpRise * runtime.massRatios.exertionRiseScale,
+            0, 1,
+        );
+
+        controller.signals.onJumpStart.send1({
+            peakHeight: controller.config.jump.peakHeight,
+        });
+        controller.signals.onLeaveGround.send1({ reason: "walljump" });
+    }
+
+    /**
+     * Wall-jump is instantaneous — it shouldn't ever be "interrupted".
+     * tick() returns false on first call so the ability releases
+     * immediately. Returning false here doesn't matter (no other ability
+     * exceeds priority 60 in the default set).
+     */
+    canInterrupt() {
+        return true;
+    }
+
+    tick(_controller, _runtime, _bodyTransform, _dt, _system) {
+        // The impulse was applied in onActivate; the ability is purely
+        // instantaneous. Release immediately so base locomotion picks up
+        // the resulting airborne arc.
+        return false;
+    }
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Wall-run ability. Activates when the player is airborne with momentum
+ * and a wall is detected to their left or right. While active:
+ *
+ *   - Gravity is reduced to `cfg.wallRun.gravityFactor × base` (typically
+ *     25%), letting the player hang on the wall for longer than a normal
+ *     jump arc.
+ *   - Horizontal velocity is projected onto the wall's tangent each tick,
+ *     so the body sticks to the wall and slides along it. Forward
+ *     momentum is preserved; into-wall and out-of-wall velocity
+ *     components are zeroed.
+ *   - Camera tilts into the wall via the shared lean spring (writes the
+ *     wall-tilt to `runtime.leanTargetRad` each tick — same channel
+ *     base writes its lat-accel-derived lean to, so transitions in and
+ *     out share the spring's smoothing).
+ *
+ * Exits on:
+ *   - Timer (`cfg.wallRun.maxDuration`)
+ *   - Lost wall contact (sensor's hit flag becomes false)
+ *   - Re-grounded (we walked onto a floor at the wall's end)
+ *   - Wall-jump preempts (higher priority — WallJump declares priority 60)
+ *
+ * Priority 50 — above Mantle (30), Slide (10), below Wall-jump (60).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WallRun extends Ability {
+    /** @private Seconds since this ability activated. */
+    private _elapsed;
+    /** @private "L" or "R" — which wall we're running on. */
+    private _side;
+    canActivate(controller: any, runtime: any, sensors: any): boolean;
+    onActivate(controller: any, runtime: any): void;
+    /**
+     * Wall-jump (priority 60) should be allowed to preempt freely; that's
+     * the canonical chain (wall-run → wall-jump). Any other higher-priority
+     * ability is also fine — wall-run is a transient state.
+     */
+    canInterrupt(): boolean;
+    tick(controller: any, runtime: any, bodyTransform: any, dt: any, system: any): boolean;
+}
+import { Ability } from "./Ability.js";
+//# sourceMappingURL=WallRun.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WallRun.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/abilities/WallRun.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAMQ,qDAAqD;IACrD,iBAAiB;IACjB,yDAAyD;IACzD,cAAgB;IAGpB,kEAiBC;IAED,gDAqBC;IAED;;;;OAIG;IACH,wBAEC;IAED,uFAiFC;CAKJ;wBAlLuB,cAAc"}

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

@@ -0,0 +1,180 @@
+import { DEG_TO_RAD } from "../../../../core/math/DEG_TO_RAD.js";
+import { Ability } from "./Ability.js";
+
+/**
+ * Wall-run ability. Activates when the player is airborne with momentum
+ * and a wall is detected to their left or right. While active:
+ *
+ *   - Gravity is reduced to `cfg.wallRun.gravityFactor × base` (typically
+ *     25%), letting the player hang on the wall for longer than a normal
+ *     jump arc.
+ *   - Horizontal velocity is projected onto the wall's tangent each tick,
+ *     so the body sticks to the wall and slides along it. Forward
+ *     momentum is preserved; into-wall and out-of-wall velocity
+ *     components are zeroed.
+ *   - Camera tilts into the wall via the shared lean spring (writes the
+ *     wall-tilt to `runtime.leanTargetRad` each tick — same channel
+ *     base writes its lat-accel-derived lean to, so transitions in and
+ *     out share the spring's smoothing).
+ *
+ * Exits on:
+ *   - Timer (`cfg.wallRun.maxDuration`)
+ *   - Lost wall contact (sensor's hit flag becomes false)
+ *   - Re-grounded (we walked onto a floor at the wall's end)
+ *   - Wall-jump preempts (higher priority — WallJump declares priority 60)
+ *
+ * Priority 50 — above Mantle (30), Slide (10), below Wall-jump (60).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WallRun extends Ability {
+    constructor() {
+        super();
+        this.name = "WallRun";
+        this.priority = 50;
+
+        /** @private Seconds since this ability activated. */
+        this._elapsed = 0;
+        /** @private "L" or "R" — which wall we're running on. */
+        this._side = "L";
+    }
+
+    canActivate(controller, runtime, sensors) {
+        const cfg = controller.config.wallRun;
+        if (!cfg) return false;
+        if (sensors === undefined || sensors === null) return false;
+        if (controller.state.grounded) return false;
+        if (controller.state.airborneTime < cfg.minAirborneTime) return false;
+
+        const speed = Math.hypot(runtime.velocityX, runtime.velocityZ);
+        if (speed < cfg.minSpeed) return false;
+
+        // Need a wall on left OR right (not front — that's a wall to bump into).
+        if (!sensors.wallLeft.hit && !sensors.wallRight.hit) return false;
+
+        // Forward intent required — wall-run is a committed action.
+        if (controller.intent.move.y < 0.1) return false;
+
+        return true;
+    }
+
+    onActivate(controller, runtime) {
+        const sensors = runtime.sensors;
+        this._elapsed = 0;
+
+        // Pick the closer wall if both detected.
+        if (sensors.wallLeft.hit
+            && (!sensors.wallRight.hit
+                || sensors.wallLeft.distance <= sensors.wallRight.distance)) {
+            this._side = "L";
+        } else {
+            this._side = "R";
+        }
+
+        // Clear any in-progress jump state — the wall-run takes over the
+        // vertical model.
+        runtime.midJump = false;
+        runtime.apexFired = false;
+        controller.state.isVariableJumpCut = false;
+        controller.state.isAscending = false;
+
+        controller.signals.onLeaveGround.send1({ reason: "wallrun" });
+    }
+
+    /**
+     * Wall-jump (priority 60) should be allowed to preempt freely; that's
+     * the canonical chain (wall-run → wall-jump). Any other higher-priority
+     * ability is also fine — wall-run is a transient state.
+     */
+    canInterrupt() {
+        return true;
+    }
+
+    tick(controller, runtime, bodyTransform, dt, system) {
+        const cfg = controller.config.wallRun;
+        this._elapsed += dt;
+
+        // -- Exit: timer.
+        if (this._elapsed >= cfg.maxDuration) {
+            return false;
+        }
+        // -- Exit: re-grounded (we ran onto a floor).
+        if (controller.state.grounded) {
+            return false;
+        }
+
+        const sensors = runtime.sensors;
+        const sensorHit = this._side === "L" ? sensors.wallLeft : sensors.wallRight;
+
+        // -- Exit: lost the wall.
+        if (!sensorHit.hit) {
+            return false;
+        }
+
+        // -- Project velocity onto the wall's tangent.
+        // The wall's normal is in the XZ plane (vertical wall). Zero the
+        // component of velocity along that normal. Forward momentum
+        // (along the wall's tangent direction) is preserved.
+        const nx = sensorHit.normal.x;
+        const nz = sensorHit.normal.z;
+        const dotN = runtime.velocityX * nx + runtime.velocityZ * nz;
+        runtime.velocityX -= dotN * nx;
+        runtime.velocityZ -= dotN * nz;
+
+        // -- Camera roll: write directly to the shared lean target.
+        // Sign convention: positive engine roll = head tilts RIGHT. Wall
+        // on LEFT → tilt LEFT → negative roll. Wall on RIGHT → tilt
+        // RIGHT → positive roll. L2.f spring-steps from this value each
+        // tick; base will overwrite once the ability releases, and the
+        // spring smooths the transition.
+        const rollSign = this._side === "L" ? -1 : 1;
+        runtime.leanTargetRad = rollSign * cfg.cameraRollDeg * DEG_TO_RAD;
+
+        // -- Reduced gravity.
+        runtime.velocityY -= runtime.gravity * cfg.gravityFactor * dt;
+
+        // -- Integrate position (manual — don't call the system's vertical
+        // phase because that would re-apply gravity with the fall multiplier).
+        bodyTransform.position._add(
+            runtime.velocityX * dt,
+            runtime.velocityY * dt,
+            runtime.velocityZ * dt,
+        );
+
+        // -- Ground catch. Reduced gravity is still gravity; over the
+        // wall-run's lifetime the player drifts down. Without a ground
+        // check here, the player can integrate PAST the floor — at
+        // which point the wall sensor eventually drops out, base
+        // resumes, and base's downward groundResolver raycast (from
+        // below the floor) doesn't find anything above. Player free-
+        // falls forever.
+        //
+        // Consult the same effective ground the base integrator uses:
+        // max(useBuiltInFlatGround baseline, groundResolver). If we've
+        // sunk to or past it, snap, zero vy, and release — base will
+        // mark grounded on the next tick.
+        let groundY = system.useBuiltInFlatGround ? system.groundY : null;
+        if (system.groundResolver !== null) {
+            const resolved = system.groundResolver(
+                bodyTransform.position.x,
+                bodyTransform.position.y,
+                bodyTransform.position.z,
+            );
+            if (resolved !== null && (groundY === null || resolved > groundY)) {
+                groundY = resolved;
+            }
+        }
+        if (groundY !== null && bodyTransform.position.y <= groundY) {
+            bodyTransform.position.setY(groundY);
+            runtime.velocityY = 0;
+            return false;
+        }
+
+        return true;
+    }
+
+    // No onDeactivate cleanup needed: on the tick we release, base runs
+    // and overwrites runtime.leanTargetRad with the natural value. The
+    // lean spring smooths the transition.
+}

package/src/engine/control/first-person/composer/EyeOffsetStack.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Additive accumulator for body-local eye-position offsets. The first-
+ * person controller's `_composeEye` clears this each frame, pushes its
+ * own contributions (bob impact, lateral bob, breath, landing, jump
+ * anticipation, sprint posture shift), then reads the accumulated offset
+ * into the eye transform.
+ *
+ * Designed so external sources — gunfire recoil, melee impact reaction,
+ * environmental shake — can push offsets without the controller having to
+ * know about them. They reach the runtime through the same interface; the
+ * controller treats all contributions identically.
+ *
+ * Translation only. Rotation composition stays explicit in the system
+ * because the multiplication order (yaw → pitch → roll) is semantically
+ * load-bearing.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class EyeOffsetStack {
+    /**
+     * @readonly
+     * @type {Vector3}
+     */
+    readonly offset: Vector3;
+    /**
+     * Reset to zero. Call once per frame before pushing.
+     */
+    clear(): void;
+    /**
+     * Add a vector contribution. `source` is purely for debugging and
+     * future inspection (e.g. a developer overlay listing each
+     * contribution); the math is a plain sum.
+     *
+     * @param {string} _source label, e.g. "bob.impact", "breath", "shake"
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    push(_source: string, x: number, y: number, z: number): void;
+    /**
+     * Convenience overload — push a Vector3.
+     * @param {string} _source
+     * @param {Vector3} v
+     */
+    pushVec(_source: string, v: Vector3): void;
+}
+import Vector3 from "../../../../core/geom/Vector3.js";
+//# sourceMappingURL=EyeOffsetStack.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EyeOffsetStack.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/composer/EyeOffsetStack.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAEQ;;;OAGG;IACH,iBAFU,OAAO,CAEU;IAG/B;;OAEG;IACH,cAEC;IAED;;;;;;;;;OASG;IACH,cALW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAIhB;IAED;;;;OAIG;IACH,iBAHW,MAAM,KACN,OAAO,QAIjB;CACJ;oBA3DmB,kCAAkC"}