@woosh/meep-engine 2.138.20 → 2.139.0

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

@@ -1,3 +1,4 @@
+import { assert } from "../../../core/assert.js";
 import Quaternion from "../../../core/geom/Quaternion.js";
 import Vector3 from "../../../core/geom/Vector3.js";
 import { clamp } from "../../../core/math/clamp.js";
@@ -10,12 +11,19 @@ import Entity from "../../ecs/Entity.js";
 import { System } from "../../ecs/System.js";
 import { Transform } from "../../ecs/transform/Transform.js";
 import { Camera } from "../../graphics/ecs/camera/Camera.js";
+import { EyeOffsetStack } from "./composer/EyeOffsetStack.js";
+import { BodyKind } from "../../physics/ecs/BodyKind.js";
+import { RigidBody } from "../../physics/ecs/RigidBody.js";
 import { FirstPersonPlayerController } from "./FirstPersonPlayerController.js";
+import { DecisionPoint } from "./mastery/DecisionPoint.js";
 import { computeJumpFromApex } from "./math/computeJumpFromApex.js";
-import { criticallyDampedSpringStep } from "./math/criticallyDampedSpring.js";
-import { dampedSpringStep } from "./math/dampedSpringStep.js";
+import { computeLRCBreathRate } from "./math/computeLRCBreathRate.js";
+import { computeMassRatios } from "./math/computeMassRatios.js";
+import { Spring } from "./math/Spring.js";
 import { stepTowards } from "./math/stepTowards.js";
-import { FirstPersonActionState } from "./pose/FirstPersonPose.js";
+import { FirstPersonActionState, FirstPersonLocomotionMode } from "./pose/FirstPersonPose.js";
+import { FirstPersonPosture } from "./pose/FirstPersonPosture.js";
+import { FirstPersonSensors } from "./sensors/FirstPersonSensors.js";
 
 // ---------------------------------------------------------------------------
 // Scratch allocations — reused per frame to avoid GC pressure
@@ -38,10 +46,22 @@ const LN2 = Math.log(2);
  */
 class PerEntityRuntime {
     constructor() {
+        /**
+         * Co-attached kinematic body. Set by {@link FirstPersonPlayerControllerSystem.link}
+         * after asserting it's present. The controller writes Transform.position
+         * directly (existing motion logic); physics derives the body's velocity
+         * from the per-step delta. Other physics systems (raycasts, contact
+         * events) see the player through this body.
+         * @type {RigidBody|null}
+         */
+        this.rigidBody = null;
+
         /** Eye pitch in radians, clamped to config.look limits. */
         this.eyePitch = 0;
         /** Body yaw in radians (around world up). */
         this.bodyYaw = 0;
+        /** Yaw rate (rad/s) computed in look consumption — for evaluators. */
+        this.yawRateRadPerSec = 0;
 
         /** Horizontal+vertical velocity. We integrate these inside the system
          *  when no external physics layer is attached. */
@@ -60,17 +80,32 @@ class PerEntityRuntime {
         this.anticipationRemaining = 0;
         /** Cached derived gravity (m/s^2) from peakHeight + timeToApex. */
         this.gravity = 9.81;
-        /** Cached derived jump impulse (m/s upward). */
+        /** Cached derived jump impulse (m/s upward), post-mass-scaling. */
         this.jumpInitialVy = 5.0;
-
-        /** Spring state for landing dip (mutated in place). */
-        this.landSpring = { value: 0, velocity: 0 };
-        /** Spring state for FOV. */
-        this.fovSpring = { value: 70, velocity: 0 };
-        /** Spring state for eye height (crouch). */
-        this.eyeHeightSpring = { value: 1.80, velocity: 0 };
-        /** Spring state for lean roll (radians). */
-        this.leanSpring = { value: 0, velocity: 0 };
+        /**
+         * Cached mass scaling factors — computed once at link. See
+         * {@link computeMassRatios}. Heavier ⇒ lower jumpV0Scale, lower
+         * groundAccelScale, higher landingDipScale + exertionRiseScale.
+         */
+        this.massRatios = null;
+
+        /** Spring for landing dip (under-damped → rings after impact). */
+        this.landSpring = new Spring();
+        /** Spring for FOV (critically damped). */
+        this.fovSpring = new Spring(70);
+        /** Spring for eye height (crouch transition). */
+        this.eyeHeightSpring = new Spring(1.80);
+        /** Spring for lean roll (radians) — banks into lateral acceleration. */
+        this.leanSpring = new Spring();
+        /**
+         * Lean target this tick (radians). Always set; L2.f spring-steps
+         * toward this value. Whoever owned motion this tick wrote it:
+         * base writes the lat-accel + look-lean derived value at the end
+         * of {@link _runBaseLocomotion}; abilities that want to override
+         * (WallRun → tilt-into-wall, Slide/Mantle/LedgeGrab → zero) write
+         * their own value in tick. Uniform channel — no null sentinel.
+         */
+        this.leanTargetRad = 0;
 
         /** Previous horizontal velocity — for lateral acceleration → lean. */
         this.prevVelocityX = 0;
@@ -93,6 +128,94 @@ class PerEntityRuntime {
         this.prevBreathPhase = 0;
         /** Which foot fires next — flipped on each footstep signal. */
         this.nextFootSide = "R";
+        /**
+         * Which foot is currently bearing the body's weight (the foot that
+         * most recently landed). Drives the lateral-bob direction: at R
+         * midstance the COM is over the right foot, so the head shifts
+         * laterally toward screen-right; at L midstance the opposite.
+         * Coupled to the same signal the footstep emits, so anything that
+         * listens to onFootStep.side will see the bob agree.
+         * Initialized "L" so the very first footstep fires "R" and the
+         * standingFoot updates to "R" — putting the head laterally right
+         * during the first half-stride, as expected.
+         */
+        this.standingFoot = "L";
+
+        /**
+         * [0..1] How "backward" the player is currently moving. Derived in
+         * fixedUpdate from velocity · screen-forward, normalized to sprint
+         * speed. Drives the gait wobble amplifier on the L3 camera-composition
+         * pass. Stored on runtime (rather than state) because it's a render-
+         * side input — downstream observers should look at velocity directly.
+         */
+        this.backwardness = 0;
+
+        /**
+         * Smoothed bob amplitude envelope. Target = max(speedNormalized,
+         * backwardness) when grounded, 0 airborne. Spring decay prevents
+         * the whiplash where stopping motion would snap the bob to neutral.
+         */
+        this.bobIntensitySpring = new Spring();
+
+        /**
+         * Vertical impact spring — kicked downward at each footfall, decays
+         * with a slight under-damped overshoot. Produces the impact-arrest +
+         * leg-push curve. value units: meters (added directly to eyeLocal.y).
+         */
+        this.verticalImpactSpring = new Spring();
+
+        /**
+         * Sprint-posture spring — eye pitches forward as the player commits
+         * to a sprint, returns to neutral when they slow. Value is in
+         * radians; slower half-life than other springs so it feels like
+         * a posture change rather than an input twitch. See cfg.posture.
+         */
+        this.sprintPostureSpring = new Spring();
+
+        /**
+         * Head-droop spring — additional forward pitch as exertion rises.
+         * Sells fatigue subtly. Target tracks exertion-driven max droop
+         * angle; spring lag keeps the transition slow and physical.
+         */
+        this.headDroopSpring = new Spring();
+
+        /**
+         * [0..1] sprintness — how much of the walk→sprint speed range the
+         * body is currently in. Computed in fixedUpdate, read by L3 for FOV
+         * and the sprint-posture pitch / forward-shift offset.
+         */
+        this.sprintness = 0;
+
+        /**
+         * Cached sin/cos of current body yaw — written once per fixedUpdate
+         * after look intent is consumed, read by every downstream step
+         * (locomotion, backwardness, lean look-rate, pose channels). Avoids
+         * recomputing the trig 3+ times per tick.
+         */
+        this.sinYaw = 0;
+        this.cosYaw = 1;
+
+        /** Cached horizontal speed (m/s) for this tick — written in derived-state. */
+        this.horizSpeed = 0;
+
+        /** Cached stride frequency (Hz) for this tick — written in breath block, read by stride. */
+        this.strideFreqHz = 0;
+
+        /**
+         * Additive accumulator for body-local eye-position offsets. The
+         * system pushes its own contributions (bob, breath, landing,
+         * sprint posture) each render frame; external systems can push
+         * recoil/shake/knockback contributions via the same interface.
+         */
+        this.eyeOffsetStack = new EyeOffsetStack();
+
+        /**
+         * Spatial-query results populated by {@link FirstPersonSensorsSystem}
+         * (when present). Abilities and the locomotion FSM read this.
+         * Lives on runtime so other systems can populate it without
+         * touching the controller component's public surface.
+         */
+        this.sensors = new FirstPersonSensors();
 
         /** Cached eye entity ID. -1 until link assigns it. */
         this.eyeEntity = -1;
@@ -121,11 +244,18 @@ export class FirstPersonPlayerControllerSystem extends System {
     constructor() {
         super();
 
+        // Dependencies kept to (controller, transform) so we can ASSERT on
+        // RigidBody at link time and emit a clear error if missing. If
+        // RigidBody were a hard dep, entities lacking one would silently
+        // never link — the controller would appear inert with no
+        // diagnostic. The assert below catches the missing-body case
+        // explicitly.
         this.dependencies = [FirstPersonPlayerController, Transform];
 
         this.components_used = [
             ResourceAccessSpecification.from(Transform, ResourceAccessKind.Write),
             ResourceAccessSpecification.from(Camera, ResourceAccessKind.Write),
+            ResourceAccessSpecification.from(RigidBody, ResourceAccessKind.Write),
         ];
 
         /**
@@ -147,6 +277,25 @@ export class FirstPersonPlayerControllerSystem extends System {
          * @type {number}
          */
         this.groundY = 0;
+
+        /**
+         * Optional callback that returns the surface Y under the player
+         * for ground resolution. Called each tick with the player's
+         * current (x, y, z); returns the world-Y of the ground below,
+         * or null if no ground is below (gap / void).
+         *
+         * Combines with `useBuiltInFlatGround`: the effective ground for
+         * the tick is `max(this.groundY when enabled, resolver(...))`.
+         * Set both off (`useBuiltInFlatGround=false`, `groundResolver=null`)
+         * to defer to external physics entirely.
+         *
+         * Designed for prototypes / gyms that need elevated platforms
+         * without a full physics layer. Production should wire a real
+         * physics system instead.
+         *
+         * @type {((x:number, y:number, z:number) => number|null) | null}
+         */
+        this.groundResolver = null;
     }
 
     /**
@@ -157,14 +306,38 @@ export class FirstPersonPlayerControllerSystem extends System {
     link(controller, bodyTransform, entity) {
         const ecd = this.entityManager.dataset;
 
+        // The controller assumes a kinematic-position RigidBody is co-
+        // attached on this entity. The body is the spatial proxy used
+        // for sensor raycasts and physics-side observers (other entities
+        // raycasting against the player, dynamic bodies colliding with
+        // the capsule, etc.). The controller writes Transform directly,
+        // physics derives velocity from the per-step delta. If a body is
+        // missing the controller could still drive the camera, but the
+        // physics integration silently breaks — assert here so the
+        // misconfiguration is caught at link time.
+        const rigidBody = ecd.getComponent(entity, RigidBody);
+        assert.ok(rigidBody !== undefined,
+            "FirstPersonPlayerController entity must have a co-attached RigidBody "
+            + "(kinematic capsule). See prototype_first_person_controller.js for setup.");
+        assert.equal(rigidBody.kind, BodyKind.KinematicPosition,
+            "FirstPersonPlayerController RigidBody must be BodyKind.KinematicPosition; "
+            + "the controller owns the Transform and physics derives velocity.");
+
         const runtime = new PerEntityRuntime();
+        runtime.rigidBody = rigidBody;
         this.runtime.set(entity, runtime);
 
-        // Derive gravity + jump impulse from designer-friendly params
+        // Derive gravity + jump impulse from designer-friendly params, then
+        // mass-scale the initial velocity (heavier ⇒ lower jump).
+        runtime.massRatios = computeMassRatios(
+            controller.config.body.mass,
+            controller.config.body.referenceMass,
+            controller.config.body.massCouplingStrength,
+        );
         const derived = { gravity: 0, initialVelocity: 0 };
         computeJumpFromApex(controller.config.jump.peakHeight, controller.config.jump.timeToApex, derived);
         runtime.gravity = derived.gravity;
-        runtime.jumpInitialVy = derived.initialVelocity;
+        runtime.jumpInitialVy = derived.initialVelocity * runtime.massRatios.jumpV0Scale;
 
         // Seed yaw from the starting body rotation. `toEulerAnglesYXZ`
         // returns (pitch, yaw, roll) — we only care about y.
@@ -173,8 +346,8 @@ export class FirstPersonPlayerControllerSystem extends System {
         runtime.eyePitch = 0;
 
         // Initialize springs to standing-eye-height baseline
-        runtime.eyeHeightSpring.value = controller.config.body.height;
-        runtime.fovSpring.value = controller.config.fov.base;
+        runtime.eyeHeightSpring.settle(controller.config.body.height);
+        runtime.fovSpring.settle(controller.config.fov.base);
         controller.state.eyeHeight = controller.config.body.height;
 
         // Create eye entity if one wasn't supplied
@@ -221,6 +394,19 @@ export class FirstPersonPlayerControllerSystem extends System {
         this.runtime.delete(entity);
     }
 
+    /**
+     * Look up the per-entity runtime for an entity that has this
+     * controller. Used by cross-system code (sensors system, future
+     * ability-driven systems) to reach internal state without leaking
+     * it onto the controller component itself.
+     *
+     * @param {number} entity
+     * @returns {PerEntityRuntime|undefined}  undefined if entity is not linked
+     */
+    getRuntime(entity) {
+        return this.runtime.get(entity);
+    }
+
     /**
      * Deterministic simulation step — L1 + L2 + L4.
      * @param {number} dt
@@ -264,6 +450,12 @@ export class FirstPersonPlayerControllerSystem extends System {
         const bodyTransform = ecd.getComponent(entity, Transform);
         if (bodyTransform === undefined) return;
 
+        // Decay the mastery score's EMA. Doing this once per tick keeps the
+        // score's time-window characteristic stable regardless of how many
+        // evaluators fire (they each *record* a sample, the decay
+        // independently ages all samples).
+        controller.mastery.tick(dt);
+
         // -- L1.a: Consume look delta -----------------------------------
         // intent.look is zeroed after consume so accumulated input doesn't
         // re-apply on the next fixed step.
@@ -283,6 +475,11 @@ export class FirstPersonPlayerControllerSystem extends System {
         const pitchDelta = intent.look.y * pitchSign;
         intent.look.set(0, 0);
 
+        // Cache yaw rate for mastery evaluators (look-lean, foot-asymmetry-
+        // turn, etc.). Rad/s, signed (negative = turning right in our
+        // convention — matches yawDelta).
+        runtime.yawRateRadPerSec = yawDelta / Math.max(dt, 1e-4);
+
         runtime.bodyYaw += yawDelta;
         // keep yaw bounded (purely cosmetic — sin/cos handle wraparound fine)
         if (runtime.bodyYaw > Math.PI) runtime.bodyYaw -= TWO_PI;
@@ -297,68 +494,311 @@ export class FirstPersonPlayerControllerSystem extends System {
         // Write body yaw back to transform (pure yaw, no pitch on body)
         bodyTransform.rotation.fromAxisAngle(Vector3.up, runtime.bodyYaw);
 
-        // -- L1.b: Speed selection --------------------------------------
+        // -- Shared flags. Computed BEFORE the ability tick so abilities
+        //    can read them. `isCrouchActive` is deliberately computed
+        //    AFTER the ability tick because `_resolveCrouchHeld` mutates
+        //    `runtime.prevCrouchHeld` — abilities like Slide need to see
+        //    the previous-tick value to detect a rising edge on the
+        //    crouch press.
         const isSprintIntent = intent.sprint && intent.move.y > 0.5 && state.grounded;
+        const isBackwardIntent = intent.move.y < 0;
+        runtime.sinYaw = Math.sin(runtime.bodyYaw);
+        runtime.cosYaw = Math.cos(runtime.bodyYaw);
+        // L2 observers read sinYaw/cosYaw as locals — destructure once.
+        const { sinYaw, cosYaw } = runtime;
+
+        // -- Ability layer: at most one active ability owns motion. The
+        //    set returns true when no ability owned the tick, in which
+        //    case base L1.b-h runs below; false means an ability fully
+        //    handled this tick (it called the system's helpers for any
+        //    standard work it wanted to keep, e.g. gravity).
+        const runBaseLocomotion = controller.abilities.tick(
+            controller, runtime, bodyTransform, runtime.sensors, dt, this,
+        );
+
+        // Now resolve crouch (updates prevCrouchHeld) — used by base and L2.
         const isCrouchActive = this._resolveCrouchHeld(controller, runtime);
 
-        let targetSpeed;
+        if (runBaseLocomotion) {
+            this._runBaseLocomotion(
+                controller, runtime, bodyTransform, dt,
+                isCrouchActive, isSprintIntent, isBackwardIntent,
+            );
+        }
+
+        // (everything below this line runs every tick — L2 observers don't
+        //  care who owned motion)
+
+        // -- L2.a: speed / moveMode ------------------------------------
+        // -- L2.a: speed / moveMode ------------------------------------
+        const horizSpeed = Math.hypot(runtime.velocityX, runtime.velocityZ);
+        runtime.horizSpeed = horizSpeed;
+        state.speed = horizSpeed;
+        state.speedNormalized = clamp(horizSpeed / Math.max(cfg.motion.sprintSpeed, 1e-3), 0, 1);
+
+        // Backwardness: 0 = moving forward (or sideways), 1 = moving directly
+        // backward at the back-pedal speed ceiling. Derived from the actual
+        // velocity (not the intent) so external knockback or stuck states
+        // also register as "moving backward" and the gait wobble reflects it.
+        //
+        // Reference speed is the *achievable* backward max — walkSpeed ×
+        // backwardSpeedFactor — NOT the sprint speed. Backward can never
+        // reach sprint, so normalizing against sprint would cap backwardness
+        // at ~0.3 and the wobble multipliers below would barely apply.
+        const screenFwdVel = runtime.velocityX * sinYaw + runtime.velocityZ * cosYaw;
+        const maxBackwardSpeed = Math.max(cfg.motion.walkSpeed * cfg.motion.backwardSpeedFactor, 1e-3);
+        runtime.backwardness = clamp(-screenFwdVel / maxBackwardSpeed, 0, 1);
+
+        // Locomotion mode is the *intent-driven* horizontal mode. Airborne
+        // state is tracked separately on pose.actionState — they're
+        // orthogonal facets (you can be Sprint+Airborne after a jump).
+        const prevLocomotionMode = state.locomotionMode;
         if (isCrouchActive) {
-            targetSpeed = cfg.motion.crouchSpeed;
-        } else if (isSprintIntent) {
-            targetSpeed = cfg.motion.sprintSpeed;
+            state.locomotionMode = FirstPersonLocomotionMode.Crouch;
+        } else if (isSprintIntent && horizSpeed > 0.1) {
+            state.locomotionMode = FirstPersonLocomotionMode.Sprint;
+        } else if (horizSpeed > 0.1) {
+            state.locomotionMode = FirstPersonLocomotionMode.Walk;
         } else {
-            targetSpeed = cfg.motion.walkSpeed;
+            state.locomotionMode = FirstPersonLocomotionMode.Idle;
         }
 
-        // -- L1.c: Move intent → desired horizontal velocity -----------
-        //
-        // Player-perceived axes at yaw=0 (looking +Z through the engine's
-        // inverted-camera presentation):
-        //   forward (W) → +Z velocity
-        //   right   (D) → -X velocity   (camera presents -X as screen-right)
-        //
-        // In closed form for arbitrary yaw, screen-forward and screen-right
-        // are 90° apart with screen-right being LEFT of screen-forward
-        // (the inversion is purely a consequence of camera-side coordinate
-        // handling — non-camera entities use the usual right = +X).
+        if (state.locomotionMode === FirstPersonLocomotionMode.Sprint
+            && prevLocomotionMode !== FirstPersonLocomotionMode.Sprint) {
+            sig.onSprintStart.send0();
+        } else if (prevLocomotionMode === FirstPersonLocomotionMode.Sprint
+            && state.locomotionMode !== FirstPersonLocomotionMode.Sprint) {
+            sig.onSprintStop.send0();
+        }
+
+        // -- L2.b: Exertion --------------------------------------------
+        // Heavier bodies tire faster — sprint rise scales with massRatios.exertionRiseScale.
+        const exertionRise = isSprintIntent
+            ? cfg.exertion.sprintRiseRate * runtime.massRatios.exertionRiseScale
+            : 0;
+        const exertionFall = exertionRise > 0 ? 0 : cfg.exertion.idleDecayRate;
+        state.exertion = clamp(state.exertion + (exertionRise - exertionFall) * dt, 0, 1);
+
+        // -- L2.c: Breath ----------------------------------------------
+        // breathRate and breathAmplitude lag exertion through separate
+        // exponential decays. Rate hangs around longer than amplitude.
+        const metabolicRate = lerp(cfg.breath.rateRestHz, cfg.breath.rateMaxHz, state.exertion);
+        const targetAmp = lerp(cfg.breath.amplitudeRestM, cfg.breath.amplitudeMaxM, state.exertion);
+
+        // Locomotor-respiratory coupling — see math/computeLRCBreathRate.
+        // The pure function is unit-tested; this site just provides inputs.
         //
-        //   screen_forward(θ) = ( sin θ, 0,  cos θ )
-        //   screen_right  (θ) = (-cos θ, 0,  sin θ )
-        const sinYaw = Math.sin(runtime.bodyYaw);
-        const cosYaw = Math.cos(runtime.bodyYaw);
+        // Gait is gated on a "feet strike the ground" posture (Stand /
+        // Crouch). Prone (slide) and Hang (ledge-grab) have no stride —
+        // the body's feet are not making contact in a walking pattern,
+        // so stride frequency drops to zero and downstream gait
+        // signals (footsteps, bob intensity) go quiet.
+        const feetStriking = state.posture === FirstPersonPosture.Stand
+            || state.posture === FirstPersonPosture.Crouch;
+        const strideFreqHz = feetStriking && state.grounded && horizSpeed > cfg.bob.minStepSpeed
+            ? cfg.bob.stepFreqAtWalk * Math.pow(
+                Math.max(horizSpeed, 1e-3) / Math.max(cfg.motion.walkSpeed, 1e-3),
+                cfg.bob.stepFreqExp,
+            )
+            : 0;
+        const targetRate = computeLRCBreathRate(
+            metabolicRate,
+            strideFreqHz,
+            state.exertion,
+            cfg.breath.locomotorCouplingMax,
+            cfg.breath.couplingMinStrideFreqHz,
+        );
+        state.breathRateHz = exponentialApproach(state.breathRateHz, targetRate, cfg.exertion.rateDecayHalfLife, dt);
+        state.breathAmplitudeM = exponentialApproach(state.breathAmplitudeM, targetAmp, cfg.exertion.ampDecayHalfLife, dt);
 
-        // Normalize the move vector (so diagonal isn't √2× faster)
-        const mvX = intent.move.x; // strafe (right+)
-        const mvY = intent.move.y; // forward (forward+)
-        const mvMag = Math.hypot(mvX, mvY);
-        const nmvX = mvMag > 1 ? mvX / mvMag : mvX;
-        const nmvY = mvMag > 1 ? mvY / mvMag : mvY;
+        runtime.prevBreathPhase = state.breathPhase;
+        state.breathPhase += state.breathRateHz * dt;
+        state.breathPhase -= Math.floor(state.breathPhase); // wrap [0,1)
 
-        const desiredVx = sinYaw * nmvY + -cosYaw * nmvX;
-        const desiredVz = cosYaw * nmvY + sinYaw * nmvX;
+        // Breath edge detection — inhale at 0.25, exhale at 0.75
+        if (phaseCrossed(runtime.prevBreathPhase, state.breathPhase, 0.25)) {
+            sig.onBreathIn.send1({ amplitude: state.breathAmplitudeM, rateHz: state.breathRateHz });
+        }
+        if (phaseCrossed(runtime.prevBreathPhase, state.breathPhase, 0.75)) {
+            sig.onBreathOut.send1({ amplitude: state.breathAmplitudeM, rateHz: state.breathRateHz });
+        }
 
-        const desiredHorizontalVx = desiredVx * targetSpeed;
-        const desiredHorizontalVz = desiredVz * targetSpeed;
+        // -- L2.d: Stride ----------------------------------------------
+        // strideFreqHz computed above in the breath block; reused here.
+        runtime.prevStridePhase = state.stridePhase;
+        if (strideFreqHz > 0) {
+            // 1 full stride cycle = 2 footfalls; phase advances at freq/2 of cycle
+            state.stridePhase += (strideFreqHz * 0.5) * dt;
+            state.stridePhase -= Math.floor(state.stridePhase);
+        }
+        // Footstep on phase wraparound past 0 (R) or past 0.5 (L). Same
+        // posture gate as stride advance — feet must be striking.
+        if (feetStriking && state.grounded && horizSpeed > cfg.bob.minStepSpeed) {
+            const fireFootstep = () => {
+                state.stepCount++;
+                const side = runtime.nextFootSide;
+                runtime.nextFootSide = side === "R" ? "L" : "R";
+                // The foot that just fired is now the one bearing weight
+                // through the upcoming half-stride. Drives lateral-bob sign.
+                runtime.standingFoot = side;
+                sig.onFootStep.send1({ side, speed: horizSpeed, surfaceTag: state.surfaceTag });
+                // Kick the vertical impact spring DOWNWARD. The kick magnitude
+                // is the per-step desired peak dip × impactKickMultiplier; the
+                // multiplier is empirical (depends on impact spring params) so
+                // that "verticalAmpAtWalk" still corresponds approximately to
+                // the visible peak dip depth. Scaled by bobIntensity so a
+                // mid-deceleration footstep doesn't deliver a full-strength
+                // impulse.
+                const massBoost = (cfg.body.mass - 80) * cfg.bob.ampMassScale;
+                const ampVMult = 1 + (cfg.bob.backwardVerticalAmpFactor - 1) * runtime.backwardness;
+                const peakDip = (cfg.bob.verticalAmpAtWalk + massBoost) * runtime.bobIntensitySpring.value * ampVMult;
+                runtime.verticalImpactSpring.kick(-peakDip * cfg.bob.impactKickMultiplier);
+            };
+            if (phaseCrossed(runtime.prevStridePhase, state.stridePhase, 0)) {
+                fireFootstep();
+            }
+            if (phaseCrossed(runtime.prevStridePhase, state.stridePhase, 0.5)) {
+                fireFootstep();
+            }
+        }
 
-        // -- L1.d: Apply accel/decel to horizontal velocity -------------
-        // Velocity lives on the runtime — we don't depend on Motion existing,
-        // because the system runs its own integrator when no external
-        // physics layer is attached.
-        const intentLen = Math.hypot(nmvX, nmvY);
-        let horizAccel;
-        if (!state.grounded) {
-            horizAccel = cfg.motion.airAccel;
-        } else if (intentLen < 1e-4) {
-            horizAccel = cfg.motion.groundDecel;
-        } else {
-            horizAccel = cfg.motion.groundAccel;
+        // -- L2.d.bob-intensity & impact -------------------------------
+        // Smoothed bob amplitude envelope: when the player starts/stops
+        // moving the visible bob fades in/out rather than cutting on/off.
+        // Target = the "natural" amp scale (max of speed and backwardness)
+        // while grounded, zero while airborne so the bob disappears mid-jump.
+        const naturalBobIntensity = Math.max(state.speedNormalized, runtime.backwardness);
+        // Bob fades to zero whenever feet aren't striking (airborne, or
+        // Prone/Hang posture). The verticalImpactSpring (separate
+        // channel) still carries any entry/landing kicks through to the
+        // camera, but no recurring step bob.
+        const targetBobIntensity = (state.grounded && feetStriking) ? naturalBobIntensity : 0;
+        runtime.bobIntensitySpring.stepTo(targetBobIntensity, cfg.bob.intensityHalfLife, 1.0, dt);
+
+        // Vertical impact spring — damped decay toward 0, with the under-
+        // damped overshoot that produces the recovery + leg-push curve.
+        runtime.verticalImpactSpring.stepTo(0, cfg.bob.impactSpringHalfLife, cfg.bob.impactSpringZeta, dt);
+
+        // Sprint posture — head pitches forward as commitment to sprint
+        // builds. Driven by "sprintness" — how much of the gap between
+        // walk and sprint speed the player is *currently* in (0..1). The
+        // pitch target is multiplied by sprintness, then critically damped.
+        // Only applies while grounded — pitching into airborne motion looks weird.
+        const sprintness = clamp(
+            (state.speed - cfg.motion.walkSpeed)
+            / Math.max(cfg.motion.sprintSpeed - cfg.motion.walkSpeed, 1e-3),
+            0, 1,
+        );
+        const targetSprintPitch = state.grounded
+            ? cfg.posture.sprintForwardPitchDeg * DEG_TO_RAD * sprintness
+            : 0;
+        runtime.sprintPostureSpring.stepTo(
+            targetSprintPitch,
+            cfg.posture.sprintForwardPitchHalfLife,
+            1.0, dt,
+        );
+        runtime.sprintness = sprintness;
+
+        // Head droop — exertion drives a subtle additional forward pitch.
+        // Combines with sprintPostureSpring (sprint = head down to commit)
+        // so a fatigued sprinter has BOTH effects layered.
+        const targetDroopRad = cfg.exertion.headDroopAtMaxDeg * DEG_TO_RAD * state.exertion;
+        runtime.headDroopSpring.stepTo(targetDroopRad, cfg.exertion.headDroopHalfLife, 1.0, dt);
+
+        // -- L2.e: Posture → eye height --------------------------------
+        // Posture is set by whichever layer owned motion this tick: base
+        // writes Stand / Crouch from isCrouchActive (see end of
+        // _runBaseLocomotion); active abilities write Prone (Slide) or
+        // Hang (LedgeGrab) in their tick. Mapping is one switch — adding
+        // a new posture is one enum value + one case.
+        let targetEyeH;
+        switch (state.posture) {
+            case FirstPersonPosture.Prone:  targetEyeH = cfg.body.proneHeight; break;
+            case FirstPersonPosture.Crouch: targetEyeH = cfg.body.crouchHeight; break;
+            case FirstPersonPosture.Hang:   targetEyeH = cfg.body.height; break;
+            case FirstPersonPosture.Stand:
+            default:                        targetEyeH = cfg.body.height; break;
         }
+        const crouchHalfLife = cfg.crouch.transitionTime / 4; // halfLife is ~quarter of full transition
+        runtime.eyeHeightSpring.stepTo(targetEyeH, crouchHalfLife, 1.0, dt);
+        state.eyeHeight = runtime.eyeHeightSpring.value;
 
-        const maxStep = horizAccel * dt;
-        runtime.velocityX = stepTowards(runtime.velocityX, desiredHorizontalVx, maxStep);
-        runtime.velocityZ = stepTowards(runtime.velocityZ, desiredHorizontalVz, maxStep);
+        if (isCrouchActive !== state.crouchActive) {
+            state.crouchActive = isCrouchActive;
+            if (isCrouchActive) {
+                sig.onCrouchEnter.send0();
+                // Impulse: dropping into a crouch grips the knees. Small
+                // bump — we don't want crouch-spamming to instantly tire.
+                state.exertion = clamp(
+                    state.exertion + cfg.exertion.crouchEnterRise * runtime.massRatios.exertionRiseScale,
+                    0, 1,
+                );
+            } else {
+                sig.onCrouchExit.send0();
+            }
+        }
+
+        // -- L2.f: Lean spring → camera roll ---------------------------
+        // The TARGET for this tick was written by whichever layer owned
+        // motion: base writes the lat-accel + look-lean derived value at
+        // the end of _runBaseLocomotion; abilities override (WallRun
+        // tilts toward the wall; Slide / LedgeGrab / Mantle force zero).
+        // L2.f is now a flat spring-step + commit — no branching, no
+        // null sentinel.
+        runtime.prevVelocityX = runtime.velocityX;
+        runtime.prevVelocityZ = runtime.velocityZ;
+        runtime.leanSpring.stepTo(runtime.leanTargetRad, cfg.lean.spring.halfLife, cfg.lean.spring.zeta, dt);
+        state.leanRollRad = runtime.leanSpring.value;
+
+        // -- L2.g: Land spring decay (drives the landing recovery dip) -
+        // Target is 0; under-damped (cfg zeta < 1) so it rings.
+        runtime.landSpring.stepTo(0, cfg.landing.recovery.spring.halfLife, cfg.landing.recovery.spring.zeta, dt);
+
+        // -- L2.h: Publish pose channels --------------------------------
+        this._publishPose(controller, runtime, bodyTransform);
+    }
+
+    /**
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {PerEntityRuntime} runtime
+     * @returns {boolean}
+     */
+    _resolveCrouchHeld(controller, runtime) {
+        const cfg = controller.config;
+        const intent = controller.intent;
+
+        if (cfg.crouch.mode === "toggle") {
+            // Edge: rising press flips the latch
+            if (intent.crouch && !runtime.prevCrouchHeld) {
+                runtime.crouchLatched = !runtime.crouchLatched;
+            }
+            runtime.prevCrouchHeld = intent.crouch;
+            return runtime.crouchLatched;
+        }
+        // "hold" mode
+        runtime.prevCrouchHeld = intent.crouch;
+        return intent.crouch;
+    }
+
+    /**
+     * Jump finite-state-machine: button-edge detection, buffer + coyote
+     * grace, anticipation timer, impulse on completion. Variable-height
+     * cut is captured here as a `state.isVariableJumpCut` flag that the
+     * gravity step in `_integrateVerticalAndResolveGround` consumes.
+     *
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {PerEntityRuntime} runtime
+     * @param {Transform} bodyTransform
+     * @param {number} dt
+     */
+    _advanceJumpFsm(controller, runtime, bodyTransform, dt) {
+        const cfg = controller.config;
+        const intent = controller.intent;
+        const state = controller.state;
+        const sig = controller.signals;
 
-        // -- L1.e: Jump (edge-triggered, buffered, coyote-graced) -------
         const jumpPressedEdge = intent.jump && !runtime.prevJumpHeld;
         const jumpReleasedEdge = !intent.jump && runtime.prevJumpHeld;
         runtime.prevJumpHeld = intent.jump;
@@ -381,37 +821,68 @@ export class FirstPersonPlayerControllerSystem extends System {
             state.jumpBufferRemaining = 0; // claimed
         }
 
-        // Variable-height cut: only valid during ascent and once jump has launched
+        // Variable-height cut: only valid during ascent, post-launch.
         if (jumpReleasedEdge && runtime.midJump && runtime.velocityY > 0) {
             state.isVariableJumpCut = true;
         }
 
-        // Anticipation timer; impulse on completion
+        // Anticipation timer; impulse on completion.
         if (state.inJumpAnticipation) {
-            // If the entity goes airborne mid-anticipation (ground rug-pulled),
-            // abandon the queued impulse — fire onLeaveGround{fall} instead.
             if (!state.grounded) {
+                // Ground rug-pulled mid-anticipation — abandon the queued
+                // impulse; the airborne-transition path will fire onLeaveGround.
                 state.inJumpAnticipation = false;
                 runtime.anticipationRemaining = 0;
             } else {
                 runtime.anticipationRemaining -= dt;
                 if (runtime.anticipationRemaining <= 0) {
-                    runtime.velocityY = runtime.jumpInitialVy;
+                    // Mastery: gather a multiplier from all evaluators
+                    // registered for JumpImpulse. Default (no evaluators)
+                    // returns 1.0 → unchanged behaviour.
+                    const masteryMul = controller.mastery.evaluate(
+                        DecisionPoint.JumpImpulse, controller, runtime,
+                    );
+                    runtime.velocityY = runtime.jumpInitialVy * masteryMul;
                     runtime.midJump = true;
                     runtime.apexFired = false;
                     runtime.peakAltitude = bodyTransform.position.y;
                     state.inJumpAnticipation = false;
                     state.isVariableJumpCut = false;
                     state.isAscending = true;
-                    controller.state.exertion = clamp(controller.state.exertion + cfg.exertion.jumpRise, 0, 1);
+                    state.exertion = clamp(
+                        state.exertion + cfg.exertion.jumpRise * runtime.massRatios.exertionRiseScale,
+                        0, 1,
+                    );
 
                     sig.onJumpStart.send1({ peakHeight: cfg.jump.peakHeight });
                     sig.onLeaveGround.send1({ reason: "jump" });
                 }
             }
         }
+    }
+
+    /**
+     * Gravity (with fall and cut multipliers), vertical integration,
+     * built-in flat-floor resolution (land event + impulse), and jump-apex
+     * detection. The full vertical phase of one fixed step.
+     *
+     * The built-in flat-floor branch only runs when `useBuiltInFlatGround`
+     * is true (the prototype's standalone mode); with an external physics
+     * layer attached the system relies on the layer to set `state.grounded`
+     * and only maintains airborne/grounded timers here.
+     *
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {PerEntityRuntime} runtime
+     * @param {Transform} bodyTransform
+     * @param {number} dt
+     */
+    _integrateVerticalAndResolveGround(controller, runtime, bodyTransform, dt) {
+        const cfg = controller.config;
+        const state = controller.state;
+        const sig = controller.signals;
 
-        // -- L1.f: Gravity ---------------------------------------------
+        // Gravity with fall/cut multipliers.
         let gMag = runtime.gravity;
         if (runtime.velocityY <= 0) {
             gMag *= cfg.jump.fallGravityMult;
@@ -419,37 +890,63 @@ export class FirstPersonPlayerControllerSystem extends System {
         } else if (state.isVariableJumpCut) {
             gMag *= cfg.jump.cutGravityMult;
         }
-
         runtime.velocityY -= gMag * dt;
 
-        // -- L1.g: Integrate position ----------------------------------
+        // Integrate position.
         bodyTransform.position._add(
             runtime.velocityX * dt,
             runtime.velocityY * dt,
             runtime.velocityZ * dt,
         );
 
-        // -- L1.h: Ground resolution (built-in flat floor) -------------
-        if (this.useBuiltInFlatGround) {
-            if (bodyTransform.position.y <= this.groundY) {
-                bodyTransform.position.setY(this.groundY);
+        // Ground resolution.
+        // Effective ground = max(built-in flat ground, optional resolver).
+        // - useBuiltInFlatGround=true gives a baseline floor at groundY.
+        // - groundResolver lets the host scene raise the floor under
+        //   platforms / terrain. Returns the surface Y under the player,
+        //   or null when no ground is below (gap / void).
+        // If both are off, the original "external physics" branch
+        // (else-block below) just tracks timers and leaves grounded
+        // alone — the host's physics layer is expected to set it.
+        if (this.useBuiltInFlatGround || this.groundResolver !== null) {
+            let testY = this.useBuiltInFlatGround ? this.groundY : Number.NEGATIVE_INFINITY;
+            if (this.groundResolver !== null) {
+                const resolved = this.groundResolver(
+                    bodyTransform.position.x,
+                    bodyTransform.position.y,
+                    bodyTransform.position.z,
+                );
+                if (resolved !== null && resolved > testY) testY = resolved;
+            }
+            const haveGround = testY !== Number.NEGATIVE_INFINITY;
+            if (haveGround && bodyTransform.position.y <= testY) {
+                bodyTransform.position.setY(testY);
 
                 if (!state.grounded) {
-                    // Land
-                    const impactVy = -runtime.velocityY; // positive magnitude
+                    // Land — apply all state changes first, then fire the
+                    // signal LAST so handlers see the fully-reacted state.
+                    const impactVy = -runtime.velocityY;
                     const kind = impactVy >= cfg.landing.hardThreshold ? "hard"
                         : (impactVy >= cfg.landing.softThreshold ? "soft" : "soft");
-                    sig.onLand.send1({ verticalSpeed: impactVy, kind });
 
-                    // Land dip — drives the under-damped spring downward
-                    const dip = clamp(impactVy * cfg.landing.recovery.dipPerVy, 0, cfg.landing.recovery.dipMax);
-                    runtime.landSpring.value = -dip; // start displaced
-                    runtime.landSpring.velocity = 0;
+                    const massScaledDip = impactVy * cfg.landing.recovery.dipPerVy
+                        * runtime.massRatios.landingDipScale;
+                    const dip = clamp(massScaledDip, 0, cfg.landing.recovery.dipMax);
+                    runtime.landSpring.settle(-dip);
+
+                    const landImpulse = clamp(
+                        impactVy * cfg.exertion.landImpulsePerVy * runtime.massRatios.exertionRiseScale,
+                        0,
+                        cfg.exertion.landImpulseMax,
+                    );
+                    state.exertion = clamp(state.exertion + landImpulse, 0, 1);
 
                     runtime.midJump = false;
                     state.isAscending = false;
                     state.isVariableJumpCut = false;
                     state.fallDistance = 0;
+
+                    sig.onLand.send1({ verticalSpeed: impactVy, kind });
                 }
 
                 state.grounded = true;
@@ -470,8 +967,7 @@ export class FirstPersonPlayerControllerSystem extends System {
                 state.fallDistance += Math.max(0, -runtime.velocityY * dt);
             }
         } else {
-            // External physics is expected to maintain state.grounded /
-            // state.verticalSpeed; we still track airborne timer.
+            // External physics maintains state.grounded; just track timers.
             if (state.grounded) {
                 state.timeSinceGrounded = 0;
                 state.airborneTime = 0;
@@ -481,7 +977,7 @@ export class FirstPersonPlayerControllerSystem extends System {
             }
         }
 
-        // Detect jump apex
+        // Jump apex detection.
         if (runtime.midJump && !runtime.apexFired) {
             if (bodyTransform.position.y > runtime.peakAltitude) {
                 runtime.peakAltitude = bodyTransform.position.y;
@@ -490,163 +986,230 @@ export class FirstPersonPlayerControllerSystem extends System {
                 runtime.apexFired = true;
             }
         }
+    }
 
-        // -- L2.a: speed / moveMode ------------------------------------
-        const horizSpeed = Math.hypot(runtime.velocityX, runtime.velocityZ);
-        state.speed = horizSpeed;
-        state.speedNormalized = clamp(horizSpeed / Math.max(cfg.motion.sprintSpeed, 1e-3), 0, 1);
+    /**
+     * Run the base (no-ability) L1 locomotion phases: speed selection,
+     * desired-velocity computation, accel/decel, jump FSM, gravity, body
+     * integration, ground resolution. Only invoked when no ability owns
+     * the tick (see {@link AbilitySet.tick}).
+     *
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {PerEntityRuntime} runtime
+     * @param {Transform} bodyTransform
+     * @param {number} dt
+     * @param {boolean} isCrouchActive
+     * @param {boolean} isSprintIntent
+     * @param {boolean} isBackwardIntent
+     */
+    _runBaseLocomotion(controller, runtime, bodyTransform, dt,
+                       isCrouchActive, isSprintIntent, isBackwardIntent) {
+        const cfg = controller.config;
+        const intent = controller.intent;
+        const state = controller.state;
 
-        const prevMoveMode = state.moveMode;
-        if (!state.grounded) {
-            state.moveMode = "Air";
-        } else if (isCrouchActive) {
-            state.moveMode = "Crouch";
-        } else if (isSprintIntent && horizSpeed > 0.1) {
-            state.moveMode = "Sprint";
-        } else if (horizSpeed > 0.1) {
-            state.moveMode = "Walk";
+        // -- L1.b: Speed selection ------------------------------------
+        let targetSpeed;
+        if (isCrouchActive) {
+            targetSpeed = cfg.motion.crouchSpeed;
+        } else if (isSprintIntent) {
+            targetSpeed = cfg.motion.sprintSpeed;
         } else {
-            state.moveMode = "Idle";
+            targetSpeed = cfg.motion.walkSpeed;
         }
-
-        if (state.moveMode === "Sprint" && prevMoveMode !== "Sprint") {
-            sig.onSprintStart.send0();
-        } else if (prevMoveMode === "Sprint" && state.moveMode !== "Sprint") {
-            sig.onSprintStop.send0();
+        if (isBackwardIntent) {
+            targetSpeed *= cfg.motion.backwardSpeedFactor;
         }
 
-        // -- L2.b: Exertion --------------------------------------------
-        const exertionRise = isSprintIntent ? cfg.exertion.sprintRiseRate : 0;
-        const exertionFall = exertionRise > 0 ? 0 : cfg.exertion.idleDecayRate;
-        state.exertion = clamp(state.exertion + (exertionRise - exertionFall) * dt, 0, 1);
-
-        // -- L2.c: Breath ----------------------------------------------
-        // breathRate and breathAmplitude lag exertion through separate
-        // exponential decays. Rate hangs around longer than amplitude.
-        const targetRate = lerp(cfg.breath.rateRestHz, cfg.breath.rateMaxHz, state.exertion);
-        const targetAmp = lerp(cfg.breath.amplitudeRestM, cfg.breath.amplitudeMaxM, state.exertion);
-        state.breathRateHz = exponentialApproach(state.breathRateHz, targetRate, cfg.exertion.rateDecayHalfLife, dt);
-        state.breathAmplitudeM = exponentialApproach(state.breathAmplitudeM, targetAmp, cfg.exertion.ampDecayHalfLife, dt);
-
-        runtime.prevBreathPhase = state.breathPhase;
-        state.breathPhase += state.breathRateHz * dt;
-        state.breathPhase -= Math.floor(state.breathPhase); // wrap [0,1)
+        // -- L1.c: Move intent → desired horizontal velocity ----------
+        //   screen_forward(θ) = ( sin θ, 0,  cos θ )
+        //   screen_right  (θ) = (-cos θ, 0,  sin θ )
+        const { sinYaw, cosYaw } = runtime;
+        const mvX = intent.move.x;
+        const mvY = intent.move.y;
+        const mvMag = Math.hypot(mvX, mvY);
+        const nmvX = mvMag > 1 ? mvX / mvMag : mvX;
+        const nmvY = mvMag > 1 ? mvY / mvMag : mvY;
+        const desiredVx = sinYaw * nmvY + -cosYaw * nmvX;
+        const desiredVz = cosYaw * nmvY + sinYaw * nmvX;
+        const desiredHorizontalVx = desiredVx * targetSpeed;
+        const desiredHorizontalVz = desiredVz * targetSpeed;
 
-        // Breath edge detection — inhale at 0.25, exhale at 0.75
-        if (phaseCrossed(runtime.prevBreathPhase, state.breathPhase, 0.25)) {
-            sig.onBreathIn.send1({ amplitude: state.breathAmplitudeM, rateHz: state.breathRateHz });
-        }
-        if (phaseCrossed(runtime.prevBreathPhase, state.breathPhase, 0.75)) {
-            sig.onBreathOut.send1({ amplitude: state.breathAmplitudeM, rateHz: state.breathRateHz });
+        // -- L1.d: Accel/decel toward desired velocity ----------------
+        const intentLen = Math.hypot(nmvX, nmvY);
+        let horizAccel;
+        if (!state.grounded) {
+            horizAccel = cfg.motion.airAccel;
+        } else if (intentLen < 1e-4) {
+            horizAccel = cfg.motion.groundDecel;
+        } else {
+            horizAccel = cfg.motion.groundAccel;
         }
-
-        // -- L2.d: Stride ----------------------------------------------
-        runtime.prevStridePhase = state.stridePhase;
-        if (state.grounded && horizSpeed > cfg.bob.minStepSpeed) {
-            const freq = cfg.bob.stepFreqAtWalk
-                * Math.pow(Math.max(horizSpeed, 1e-3) / Math.max(cfg.motion.walkSpeed, 1e-3), cfg.bob.stepFreqExp);
-            // 1 full stride cycle = 2 footfalls; phase advances at freq/2 of cycle
-            state.stridePhase += (freq * 0.5) * dt;
-            state.stridePhase -= Math.floor(state.stridePhase);
+        if (isBackwardIntent && state.grounded) {
+            horizAccel *= cfg.motion.backwardAccelFactor;
         }
-        // Footstep on phase wraparound past 0 (R) or past 0.5 (L)
-        if (state.grounded && horizSpeed > cfg.bob.minStepSpeed) {
-            if (phaseCrossed(runtime.prevStridePhase, state.stridePhase, 0)) {
-                state.stepCount++;
-                const side = runtime.nextFootSide === "L" ? "L" : "R";
-                runtime.nextFootSide = side === "R" ? "L" : "R";
-                sig.onFootStep.send1({ side, speed: horizSpeed, surfaceTag: state.surfaceTag });
-            }
-            if (phaseCrossed(runtime.prevStridePhase, state.stridePhase, 0.5)) {
-                state.stepCount++;
-                const side = runtime.nextFootSide === "L" ? "L" : "R";
-                runtime.nextFootSide = side === "R" ? "L" : "R";
-                sig.onFootStep.send1({ side, speed: horizSpeed, surfaceTag: state.surfaceTag });
-            }
+        if (state.grounded) {
+            horizAccel *= runtime.massRatios.groundAccelScale;
+            // Mastery: GroundAccel evaluators can scale per-tick accel
+            // (e.g. foot-asymmetry-turn bonus). Default (no evaluators)
+            // returns 1.0 → unchanged.
+            horizAccel *= controller.mastery.evaluate(
+                DecisionPoint.GroundAccel, controller, runtime,
+            );
         }
+        const maxStep = horizAccel * dt;
+        runtime.velocityX = stepTowards(runtime.velocityX, desiredHorizontalVx, maxStep);
+        runtime.velocityZ = stepTowards(runtime.velocityZ, desiredHorizontalVz, maxStep);
 
-        // -- L2.e: Crouch eye height -----------------------------------
-        const targetEyeH = isCrouchActive ? cfg.body.crouchHeight : cfg.body.height;
-        const crouchHalfLife = cfg.crouch.transitionTime / 4; // halfLife is ~quarter of full transition
-        criticallyDampedSpringStep(runtime.eyeHeightSpring, targetEyeH, crouchHalfLife, dt);
-        state.eyeHeight = runtime.eyeHeightSpring.value;
+        // -- L1.e/f/g/h: jump FSM + vertical integration --------------
+        this._advanceJumpFsm(controller, runtime, bodyTransform, dt);
+        this._integrateVerticalAndResolveGround(controller, runtime, bodyTransform, dt);
+
+        // -- Publish posture for L2 consumers (eye height, gait gating).
+        //   Base owns posture when no ability is active: Crouch if the
+        //   crouch intent is resolved active, otherwise Stand. Abilities
+        //   that need a different posture (slide → Prone, ledge-grab →
+        //   Hang) set state.posture themselves in their tick.
+        controller.state.posture = isCrouchActive
+            ? FirstPersonPosture.Crouch
+            : FirstPersonPosture.Stand;
+
+        // -- Publish lean target for L2.f. Base writes the natural
+        //   (lat-accel + look-lean) value; abilities override in their
+        //   own tick. L2.f spring-steps toward whatever's here.
+        runtime.leanTargetRad = this._computeNaturalLeanTarget(controller, runtime, dt);
+    }
 
-        if (isCrouchActive !== state.crouchActive) {
-            state.crouchActive = isCrouchActive;
-            if (isCrouchActive) sig.onCrouchEnter.send0();
-            else sig.onCrouchExit.send0();
-        }
+    /**
+     * Compute the natural camera lean for this tick: lat-accel-driven
+     * roll into a turn, plus a yaw-rate look-lean contribution, both
+     * clamped. The result is the target the lean spring chases each
+     * tick when no ability has opinions.
+     *
+     * Pure-ish helper — reads `controller`, `runtime`, `dt`; returns a
+     * number. Extracted so both base and any future ability that wants
+     * to compose its lean on top of the natural value can call it.
+     *
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {PerEntityRuntime} runtime
+     * @param {number} dt
+     * @returns {number} target roll in radians
+     */
+    _computeNaturalLeanTarget(controller, runtime, dt) {
+        const cfg = controller.config;
+        const state = controller.state;
+        if (!cfg.lean.enabled) return 0;
 
-        // -- L2.f: Lean (lateral acceleration → roll) ------------------
-        let leanTargetRad = 0;
-        if (cfg.lean.enabled) {
-            // Lateral acceleration projected onto screen-right.
-            // accel_world = (vel - prevVel) / dt; screen_right = (-cos θ, 0, sin θ).
-            const accWorldX = (runtime.velocityX - runtime.prevVelocityX) / Math.max(dt, 1e-4);
-            const accWorldZ = (runtime.velocityZ - runtime.prevVelocityZ) / Math.max(dt, 1e-4);
-            const latAccel = accWorldX * (-cosYaw) + accWorldZ * sinYaw;
-            const normalized = clamp(latAccel / 9.81, -2, 2);
-            // Negative roll on rightward accel = leaning into the turn
-            leanTargetRad = -normalized * cfg.lean.maxRollDeg * DEG_TO_RAD;
+        const sinYaw = runtime.sinYaw;
+        const cosYaw = runtime.cosYaw;
+
+        // Lateral acceleration projected onto screen-right.
+        // accel_world = (vel - prevVel) / dt;  screen_right = (-cos θ, 0, sin θ).
+        const accWorldX = (runtime.velocityX - runtime.prevVelocityX) / Math.max(dt, 1e-4);
+        const accWorldZ = (runtime.velocityZ - runtime.prevVelocityZ) / Math.max(dt, 1e-4);
+        const latAccel = accWorldX * (-cosYaw) + accWorldZ * sinYaw;
+        const normalized = clamp(latAccel / 9.81, -2, 2);
+        //
+        // Sign convention for the roll (the eye composes the rotation
+        // as qYaw * qPitch * qRoll, where qRoll is around (0,0,1)).
+        // After the engine's camera-invert pipeline:
+        //   φ > 0  →  camera-up tilts toward screen-right (−X)  →  HEAD TILTS RIGHT
+        //   φ < 0  →  camera-up tilts toward screen-left  (+X)  →  HEAD TILTS LEFT
+        //
+        // For the "bank into the turn" feel (Apex / Titanfall / Mirror's
+        // Edge): accelerating right (latAccel > 0) should tilt the head
+        // RIGHT, i.e. positive φ. So leanTargetRad has the SAME sign
+        // as latAccel.
+        let leanTargetRad = normalized * cfg.lean.maxRollDeg * DEG_TO_RAD;
+
+        // Look-lean: yaw-rate-driven banking. runtime.yawRateRadPerSec
+        // was cached at L1.a — negative is the "turn right" convention.
+        // For "bank into the turn": turning right → head tilts right →
+        // positive engine roll. So lookLean = -yawRate * scale matches
+        // sign.
+        //
+        // Crouched players are in a low, stable, low-momentum stance —
+        // banking the head from a mouse turn reads as unmotivated. We
+        // scale the contribution down (default to 0) while crouched.
+        // Lat-accel lean is left alone: its magnitude naturally tracks
+        // the (lower) crouch acceleration, so it stays motivated.
+        if (cfg.lean.lookLeanEnabled) {
+            const yawRate = clamp(
+                runtime.yawRateRadPerSec,
+                -cfg.lean.lookLeanYawRateClamp,
+                cfg.lean.lookLeanYawRateClamp,
+            );
+            const crouchFactor = state.crouchActive ? cfg.lean.crouchLookLeanFactor : 1.0;
+            leanTargetRad += -yawRate * cfg.lean.lookLeanDegPerRadPerSec * DEG_TO_RAD * crouchFactor;
         }
-        runtime.prevVelocityX = runtime.velocityX;
-        runtime.prevVelocityZ = runtime.velocityZ;
-        criticallyDampedSpringStep(runtime.leanSpring, leanTargetRad, cfg.lean.spring.halfLife, dt);
-        state.leanRollRad = runtime.leanSpring.value;
 
-        // -- L2.g: Land spring decay (drives the landing recovery dip) -
-        // Target is 0; under-damped so it rings.
-        dampedSpringStep(
-            runtime.landSpring, 0,
-            cfg.landing.recovery.spring.halfLife,
-            cfg.landing.recovery.spring.zeta,
-            dt,
-        );
+        // Final clamp on the sum: cap the combined target to ±2 ×
+        // maxRollDeg (matches the latAccel normalized clamp range) so
+        // even simultaneous max-strafe-accel + max-yaw-flick produces a
+        // sane upper bound.
+        const maxTotal = cfg.lean.maxRollDeg * DEG_TO_RAD * 2;
+        return clamp(leanTargetRad, -maxTotal, maxTotal);
+    }
 
-        // -- L2.h: Publish pose channels --------------------------------
+    /**
+     * Snapshot the per-tick "what is the body doing" information into the
+     * pose channels for downstream consumption (skeleton, sound, AI).
+     * Read-only with respect to controller state — this is purely a publish
+     * step.
+     *
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {PerEntityRuntime} runtime
+     * @param {Transform} bodyTransform
+     */
+    _publishPose(controller, runtime, bodyTransform) {
+        const cfg = controller.config;
+        const state = controller.state;
         const pose = controller.pose;
+
         pose.rootPosition.copy(bodyTransform.position);
         pose.rootYawRad = runtime.bodyYaw;
         pose.headYawRad = runtime.bodyYaw;
         pose.headPitchRad = runtime.eyePitch;
         pose.headRollRad = state.leanRollRad;
         pose.locomotionPhase = state.stridePhase;
-        pose.locomotionSpeed = horizSpeed;
+        pose.locomotionSpeed = runtime.horizSpeed;
         // Strafe component: project velocity onto screen-right (-cos θ, 0, sin θ).
-        // Positive = moving to the player's right (animation blend-space convention).
-        pose.locomotionStrafe = (runtime.velocityX * (-cosYaw) + runtime.velocityZ * sinYaw)
+        // Positive = moving to the player's right.
+        pose.locomotionStrafe = (runtime.velocityX * (-runtime.cosYaw) + runtime.velocityZ * runtime.sinYaw)
             / Math.max(cfg.motion.sprintSpeed, 1e-3);
         pose.actionState =
             state.inJumpAnticipation ? FirstPersonActionState.Anticipating
             : !state.grounded ? FirstPersonActionState.Airborne
             : (Math.abs(runtime.landSpring.value) > 0.01 ? FirstPersonActionState.Landing
             : FirstPersonActionState.Grounded);
+        pose.locomotionMode = state.locomotionMode;
         const crouchSpan = Math.max(cfg.body.height - cfg.body.crouchHeight, 1e-3);
         pose.crouchAmount = clamp((cfg.body.height - state.eyeHeight) / crouchSpan, 0, 1);
-        pose.aimPitch = runtime.eyePitch;
-    }
 
-    /**
-     * @private
-     * @param {FirstPersonPlayerController} controller
-     * @param {PerEntityRuntime} runtime
-     * @returns {boolean}
-     */
-    _resolveCrouchHeld(controller, runtime) {
-        const cfg = controller.config;
-        const intent = controller.intent;
-
-        if (cfg.crouch.mode === "toggle") {
-            // Edge: rising press flips the latch
-            if (intent.crouch && !runtime.prevCrouchHeld) {
-                runtime.crouchLatched = !runtime.crouchLatched;
-            }
-            runtime.prevCrouchHeld = intent.crouch;
-            return runtime.crouchLatched;
+        // Posture channel for downstream animation: which body shape +
+        // how far the body is into it from the standing neutral.
+        //
+        // `posture` is the enum (Stand / Crouch / Prone / Hang) — picks
+        // the animation track. `postureAmount` is the [0..1] blend
+        // weight from standing toward that posture, derived from the
+        // eye-height spring so the value transitions smoothly across
+        // changes (matches the visible camera motion).
+        pose.posture = state.posture;
+        let postureTargetH;
+        switch (state.posture) {
+            case FirstPersonPosture.Prone:  postureTargetH = cfg.body.proneHeight; break;
+            case FirstPersonPosture.Crouch: postureTargetH = cfg.body.crouchHeight; break;
+            case FirstPersonPosture.Hang:   postureTargetH = cfg.body.height; break;
+            case FirstPersonPosture.Stand:
+            default:                        postureTargetH = cfg.body.height; break;
         }
-        // "hold" mode
-        runtime.prevCrouchHeld = intent.crouch;
-        return intent.crouch;
+        const postureSpan = Math.max(cfg.body.height - postureTargetH, 1e-3);
+        pose.postureAmount = clamp((cfg.body.height - state.eyeHeight) / postureSpan, 0, 1);
+
+        pose.aimPitch = runtime.eyePitch;
     }
 
     /**
@@ -672,40 +1235,71 @@ export class FirstPersonPlayerControllerSystem extends System {
         const camera = ecd.getComponent(controller.eyeEntity, Camera);
         if (eyeTransform === undefined || camera === undefined) return;
 
-        // -- Body-local eye offset --------------------------------------
-        const eyeLocal = SCRATCH_V3_A.set(0, state.eyeHeight, 0);
-
-        // Bob — only when grounded & moving
-        if (state.grounded && state.speed > cfg.bob.minStepSpeed) {
-            const phase = state.stridePhase * TWO_PI; // one full cycle = 2 steps
+        // -- Body-local eye offset, composed via the additive stack ----
+        // The base (0, eyeHeight, 0) is the standing/crouched neutral; each
+        // additional contribution (bob, breath, landing, anticipation,
+        // sprint posture) goes through the stack so external systems can
+        // push their own contributions on the same channel.
+        const stack = runtime.eyeOffsetStack;
+        stack.clear();
+        stack.push("eyeHeight", 0, state.eyeHeight, 0);
+
+        // Bob — gated on grounded only (the impact spring decays naturally
+        // even at rest, so the bob fade-out is smooth; lateral amp uses the
+        // bob-intensity envelope which spring-decays after stopping).
+        if (state.grounded) {
+            const phase = state.stridePhase * TWO_PI;
             const massBoost = (cfg.body.mass - 80) * cfg.bob.ampMassScale;
-            const ampV = (cfg.bob.verticalAmpAtWalk + massBoost) * state.speedNormalized;
-            const ampL = (cfg.bob.lateralAmpAtWalk + massBoost) * state.speedNormalized;
-
-            eyeLocal.y += -ampV * Math.abs(Math.sin(phase));
-            eyeLocal.x += ampL * Math.sin(phase * 0.5);
+            const intensity = runtime.bobIntensitySpring.value;
+
+            // Back-pedal amp boost — lateral grows more than vertical because
+            // backward gait has worse side-to-side balance than vertical compression.
+            // Exertion adds a smaller boost on top: tired = wobbly gait.
+            const ampLMult = 1 + (cfg.bob.backwardLateralAmpFactor - 1) * runtime.backwardness;
+            const exertionBoost = 1 + cfg.exertion.bobLateralBoostAtMax * state.exertion;
+            const ampL = (cfg.bob.lateralAmpAtWalk + massBoost) * intensity * ampLMult * exertionBoost;
+
+            // Vertical: read directly from the impact spring (footfall kicks,
+            // under-damped recovery → trough + leg-push overshoot).
+            stack.push("bob.impact", 0, runtime.verticalImpactSpring.value, 0);
+
+            // Lateral: head shifts toward the foot bearing weight. Polarity
+            // sourced from runtime.standingFoot — the same signal the
+            // footstep emits — so bob direction and footstep side agree.
+            // |sin(phase)| is the non-negative "midstance envelope".
+            const lateralPolarity = runtime.standingFoot === "R" ? -1 : 1;
+            stack.push("bob.lateral", ampL * lateralPolarity * Math.abs(Math.sin(phase)), 0, 0);
         }
 
-        // Breath — sine + tiny noise
+        // Breath — sine + tiny noise riding the rate spring.
         const breathOffset = -state.breathAmplitudeM
             * Math.sin(state.breathPhase * TWO_PI)
             * (1 + cfg.breath.noiseAmount * (Math.sin(state.breathPhase * 13.7) * 0.5));
-        eyeLocal.y += breathOffset;
+        stack.push("breath", 0, breathOffset, 0);
 
-        // Landing spring dip
-        eyeLocal.y += runtime.landSpring.value;
+        // Landing spring dip (under-damped — overshoots once on recovery).
+        stack.push("landing", 0, runtime.landSpring.value, 0);
 
-        // Jump anticipation dip (linear ramp during anticipation)
+        // Jump anticipation dip (eased ramp during the squash window).
         if (state.inJumpAnticipation) {
             const t = 1 - clamp(runtime.anticipationRemaining / Math.max(cfg.jump.anticipation.duration, 1e-3), 0, 1);
-            // Ease-out: t * (2 - t)
-            const eased = t * (2 - t);
-            eyeLocal.y -= cfg.jump.anticipation.dipAmount * eased;
+            const eased = t * (2 - t); // ease-out quad
+            stack.push("anticipation", 0, -cfg.jump.anticipation.dipAmount * eased, 0);
         }
 
-        // Transform body-local offset into world space (body has yaw only,
-        // so rotate by bodyTransform.rotation around Y)
-        const worldOffset = SCRATCH_V3_B.copy(eyeLocal);
+        // Sprint posture: head leans slightly forward as commitment builds.
+        // Pitch part is in the rotation block below; the +Z position shift
+        // sells "head leading the hips" (Mirror's Edge), tied to the same
+        // spring envelope so they move together.
+        const sprintPitch = runtime.sprintPostureSpring.value;
+        const sprintShiftFraction =
+            cfg.posture.sprintForwardPitchDeg > 0
+                ? sprintPitch / (cfg.posture.sprintForwardPitchDeg * DEG_TO_RAD)
+                : 0;
+        stack.push("posture.sprintShift", 0, 0, cfg.posture.sprintForwardShiftM * sprintShiftFraction);
+
+        // Transform body-local accumulated offset into world space.
+        const worldOffset = SCRATCH_V3_B.copy(stack.offset);
         worldOffset.applyQuaternion(bodyTransform.rotation);
 
         eyeTransform.position.copy(bodyTransform.position);
@@ -717,16 +1311,42 @@ export class FirstPersonPlayerControllerSystem extends System {
         // breath; merged into the main pitch so we don't pay an extra quat
         // multiply and the composition stays trivially correct.
         let rollTotal = state.leanRollRad;
-        if (state.grounded && state.speed > cfg.bob.minStepSpeed) {
+        if (state.grounded) {
+            // Roll: head tilts toward the standing foot, in phase with the
+            // lateral sway. Polarity sourced from runtime.standingFoot for
+            // consistency with the lateral bob. Positive engine roll = head
+            // tilts RIGHT (camera-invert convention), so R-foot midstance =
+            // positive roll, L-foot midstance = negative roll.
             const phase = state.stridePhase * TWO_PI;
-            const ampRoll = cfg.bob.rollAtWalkDeg * DEG_TO_RAD * state.speedNormalized;
-            rollTotal += ampRoll * Math.sin(phase * 0.5);
+            const rollBackMult = 1 + (cfg.bob.backwardRollFactor - 1) * runtime.backwardness;
+            const ampRoll = cfg.bob.rollAtWalkDeg * DEG_TO_RAD * runtime.bobIntensitySpring.value * rollBackMult;
+            const rollPolarity = runtime.standingFoot === "R" ? 1 : -1;
+            const rollEnvelope = Math.abs(Math.sin(phase));
+            const bobRollSigned = ampRoll * rollPolarity * rollEnvelope;
+
+            // Lean × bob coupling: excursions in the lean direction get
+            // amplified, opposite excursions attenuated. Lean is normalized
+            // against maxRollDeg so the coupling magnitude stays bounded
+            // regardless of how aggressively lean is configured.
+            const maxLeanRad = Math.max(cfg.lean.maxRollDeg * DEG_TO_RAD, 1e-6);
+            const leanFraction = clamp(state.leanRollRad / maxLeanRad, -1, 1);
+            // sign(bobRollSigned) matches lean? amplify; else attenuate.
+            const sameSign = (bobRollSigned * leanFraction) >= 0;
+            const couplingMag = cfg.bob.leanCouplingFactor * Math.abs(leanFraction);
+            const couplingScale = sameSign ? (1 + couplingMag) : (1 - couplingMag);
+            rollTotal += bobRollSigned * couplingScale;
         }
 
         const breathPitch = lerp(cfg.breath.pitchAmpRestDeg, cfg.breath.pitchAmpMaxDeg, state.exertion)
             * DEG_TO_RAD
             * Math.cos(state.breathPhase * TWO_PI);
-        const pitchTotal = runtime.eyePitch + breathPitch;
+        // Combined pitch contributions: player input + breath nod + sprint
+        // commitment + fatigue droop. All in the same "positive = look-down"
+        // convention so they sum cleanly.
+        const pitchTotal = runtime.eyePitch
+            + breathPitch
+            + runtime.sprintPostureSpring.value
+            + runtime.headDroopSpring.value;
 
         // composition: yaw * pitch * roll
         //   pitch around world X — yaw applied after, so effective axis is camera-local right
@@ -741,14 +1361,11 @@ export class FirstPersonPlayerControllerSystem extends System {
         // -- FOV ---------------------------------------------------------
         let fovTarget = cfg.fov.base;
         if (cfg.fov.sprintAdd !== 0) {
-            // Add proportionally — at sprint-speed cap we hit sprintAdd
-            const sprintness = clamp((state.speed - cfg.motion.walkSpeed)
-                / Math.max(cfg.motion.sprintSpeed - cfg.motion.walkSpeed, 1e-3), 0, 1);
-            fovTarget += cfg.fov.sprintAdd * sprintness;
+            fovTarget += cfg.fov.sprintAdd * runtime.sprintness;
         }
         if (state.crouchActive) fovTarget += cfg.fov.crouchAdd;
 
-        criticallyDampedSpringStep(runtime.fovSpring, fovTarget, cfg.fov.smoothHalfLife, dt);
+        runtime.fovSpring.stepTo(fovTarget, cfg.fov.smoothHalfLife, 1.0, dt);
         // Write directly to the underlying Three.js camera. Going through
         // camera.fov.set() fires onChanged which triggers a full camera
         // rebuild in CameraSystem — far too expensive to do per frame.