@woosh/meep-engine 2.138.17 → 2.138.19

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

@@ -0,0 +1,799 @@
+import Quaternion from "../../../core/geom/Quaternion.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { clamp } from "../../../core/math/clamp.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { SerializationMetadata } from "../../ecs/components/SerializationMetadata.js";
+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 { FirstPersonPlayerController } from "./FirstPersonPlayerController.js";
+import { computeJumpFromApex } from "./math/computeJumpFromApex.js";
+import { criticallyDampedSpringStep } from "./math/criticallyDampedSpring.js";
+import { dampedSpringStep } from "./math/dampedSpringStep.js";
+import { stepTowards } from "./math/stepTowards.js";
+import { FirstPersonActionState } from "./pose/FirstPersonPose.js";
+
+// ---------------------------------------------------------------------------
+// Scratch allocations — reused per frame to avoid GC pressure
+// ---------------------------------------------------------------------------
+const SCRATCH_V3_A = new Vector3();
+const SCRATCH_V3_B = new Vector3();
+const SCRATCH_V3_C = new Vector3();
+const SCRATCH_Q_A = new Quaternion();
+const SCRATCH_Q_B = new Quaternion();
+const SCRATCH_Q_C = new Quaternion();
+
+const TWO_PI = Math.PI * 2;
+const LN2 = Math.log(2);
+
+/**
+ * Per-entity runtime state the system maintains internally — too transient
+ * even for {@link FirstPersonPlayerController}'s `state` member, because it
+ * encodes input-edge bookkeeping and timer values the public surface should
+ * never see directly.
+ */
+class PerEntityRuntime {
+    constructor() {
+        /** Eye pitch in radians, clamped to config.look limits. */
+        this.eyePitch = 0;
+        /** Body yaw in radians (around world up). */
+        this.bodyYaw = 0;
+
+        /** Horizontal+vertical velocity. We integrate these inside the system
+         *  when no external physics layer is attached. */
+        this.velocityX = 0;
+        this.velocityY = 0;
+        this.velocityZ = 0;
+
+        /** Previous-tick jump intent — for rising/falling edge detection. */
+        this.prevJumpHeld = false;
+        /** Previous-tick crouch intent — for toggle-mode edge detection. */
+        this.prevCrouchHeld = false;
+        /** True while crouch toggle is latched on (used only in toggle mode). */
+        this.crouchLatched = false;
+
+        /** Remaining time in jump anticipation, or <= 0 if not anticipating. */
+        this.anticipationRemaining = 0;
+        /** Cached derived gravity (m/s^2) from peakHeight + timeToApex. */
+        this.gravity = 9.81;
+        /** Cached derived jump impulse (m/s upward). */
+        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 };
+
+        /** Previous horizontal velocity — for lateral acceleration → lean. */
+        this.prevVelocityX = 0;
+        this.prevVelocityZ = 0;
+
+        /** Previous-tick grounded for edge detection. */
+        this.prevGrounded = true;
+        /** Vertical speed at moment of last "leave ground". */
+        this.takeoffVy = 0;
+        /** Max vertical position since last takeoff — for jump apex detection. */
+        this.peakAltitude = 0;
+        /** Set true once a jump has been launched; cleared on land. */
+        this.midJump = false;
+        /** Apex already fired for this airborne segment? */
+        this.apexFired = false;
+
+        /** Stride phase from previous fixed step — for footstep edge detection. */
+        this.prevStridePhase = 0;
+        /** Breath phase from previous fixed step — for inhale/exhale edge detection. */
+        this.prevBreathPhase = 0;
+        /** Which foot fires next — flipped on each footstep signal. */
+        this.nextFootSide = "R";
+
+        /** Cached eye entity ID. -1 until link assigns it. */
+        this.eyeEntity = -1;
+    }
+}
+
+/**
+ * Drives a first-person camera + body from intent fields. See sibling
+ * DESIGN.md for goals, architecture, and the five processing layers (L0..L4).
+ *
+ * - fixedUpdate runs L1 (locomotion), L2 (pose state), and L4 (events) so
+ *   the simulation remains deterministic.
+ * - update runs L3 (camera composition) at render rate so the eye is never
+ *   smoother than the screen.
+ *
+ * The system itself integrates a simple flat-floor at y = `config.gravity.magnitude > 0
+ * ? state.groundY : -Infinity` for the prototype. A real physics layer should
+ * write `state.grounded`/`state.groundNormal` from outside instead; the
+ * built-in resolver is just a convenience to keep the controller usable
+ * without dependencies.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FirstPersonPlayerControllerSystem extends System {
+    constructor() {
+        super();
+
+        this.dependencies = [FirstPersonPlayerController, Transform];
+
+        this.components_used = [
+            ResourceAccessSpecification.from(Transform, ResourceAccessKind.Write),
+            ResourceAccessSpecification.from(Camera, ResourceAccessKind.Write),
+        ];
+
+        /**
+         * Per-entity runtime, keyed by entity id.
+         * @type {Map<number, PerEntityRuntime>}
+         */
+        this.runtime = new Map();
+
+        /**
+         * If true, the system clamps body y >= groundY and writes
+         * state.grounded itself. Turn off when wiring a real physics layer.
+         * @type {boolean}
+         */
+        this.useBuiltInFlatGround = true;
+
+        /**
+         * The flat-ground y for the built-in resolver. Ignored when
+         * useBuiltInFlatGround is false.
+         * @type {number}
+         */
+        this.groundY = 0;
+    }
+
+    /**
+     * @param {FirstPersonPlayerController} controller
+     * @param {Transform} bodyTransform
+     * @param {number} entity
+     */
+    link(controller, bodyTransform, entity) {
+        const ecd = this.entityManager.dataset;
+
+        const runtime = new PerEntityRuntime();
+        this.runtime.set(entity, runtime);
+
+        // Derive gravity + jump impulse from designer-friendly params
+        const derived = { gravity: 0, initialVelocity: 0 };
+        computeJumpFromApex(controller.config.jump.peakHeight, controller.config.jump.timeToApex, derived);
+        runtime.gravity = derived.gravity;
+        runtime.jumpInitialVy = derived.initialVelocity;
+
+        // Seed yaw from the starting body rotation. `toEulerAnglesYXZ`
+        // returns (pitch, yaw, roll) — we only care about y.
+        bodyTransform.rotation.toEulerAnglesYXZ(SCRATCH_V3_A);
+        runtime.bodyYaw = SCRATCH_V3_A.y;
+        runtime.eyePitch = 0;
+
+        // Initialize springs to standing-eye-height baseline
+        runtime.eyeHeightSpring.value = controller.config.body.height;
+        runtime.fovSpring.value = controller.config.fov.base;
+        controller.state.eyeHeight = controller.config.body.height;
+
+        // Create eye entity if one wasn't supplied
+        if (controller.eyeEntity === -1 || !ecd.entityExists(controller.eyeEntity)) {
+            const eye = new Entity();
+
+            const eyeTransform = new Transform();
+            const baseEyePos = SCRATCH_V3_A.copy(bodyTransform.position);
+            baseEyePos.y += controller.config.body.height;
+            eyeTransform.position.copy(baseEyePos);
+
+            const camera = new Camera();
+            camera.active.set(true);
+            camera.fov.set(controller.config.fov.base);
+            camera.clip_near = 0.05;
+            camera.clip_far = 1000;
+            camera.autoClip = false;
+
+            eye.add(eyeTransform);
+            eye.add(camera);
+            eye.add(SerializationMetadata.Transient);
+
+            eye.build(ecd);
+
+            controller.eyeEntity = eye.id;
+        }
+
+        runtime.eyeEntity = controller.eyeEntity;
+    }
+
+    /**
+     * @param {FirstPersonPlayerController} controller
+     * @param {Transform} bodyTransform
+     * @param {number} entity
+     */
+    unlink(controller, bodyTransform, entity) {
+        const ecd = this.entityManager.dataset;
+
+        if (controller.eyeEntity !== -1 && ecd.entityExists(controller.eyeEntity)) {
+            ecd.removeEntity(controller.eyeEntity);
+            controller.eyeEntity = -1;
+        }
+
+        this.runtime.delete(entity);
+    }
+
+    /**
+     * Deterministic simulation step — L1 + L2 + L4.
+     * @param {number} dt
+     */
+    fixedUpdate(dt) {
+        const ecd = this.entityManager.dataset;
+        if (ecd === null) return;
+
+        this._currentDt = dt;
+        ecd.traverseComponents(FirstPersonPlayerController, this._tickEntity, this);
+    }
+
+    /**
+     * Variable-rate camera composition — L3.
+     * @param {number} dt
+     */
+    update(dt) {
+        const ecd = this.entityManager.dataset;
+        if (ecd === null) return;
+
+        this._currentRenderDt = dt;
+        ecd.traverseComponents(FirstPersonPlayerController, this._composeEye, this);
+    }
+
+    /**
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {number} entity
+     */
+    _tickEntity(controller, entity) {
+        const ecd = this.entityManager.dataset;
+        const runtime = this.runtime.get(entity);
+        if (runtime === undefined) return;
+
+        const dt = this._currentDt;
+        const cfg = controller.config;
+        const intent = controller.intent;
+        const state = controller.state;
+        const sig = controller.signals;
+
+        const bodyTransform = ecd.getComponent(entity, Transform);
+        if (bodyTransform === undefined) return;
+
+        // -- L1.a: Consume look delta -----------------------------------
+        // intent.look is zeroed after consume so accumulated input doesn't
+        // re-apply on the next fixed step.
+        //
+        // Conventions (with raw mouse delta as the source — movementX/Y both
+        // positive when moving right/down):
+        //   look.x > 0 ("mouse right")  → turn right
+        //   look.y > 0 ("mouse down")   → look down  (flipped by invertY)
+        //
+        // The yaw sign is negated because the engine uses left-handed
+        // coordinates with +Z as forward; a positive Y-axis rotation takes
+        // +Z toward +X, which presents to the player as a LEFT turn through
+        // the Three.js camera (`quaternion_invert_orientation`). Negating
+        // here gives the player-intuitive "mouse right → turn right".
+        const yawDelta = -intent.look.x;
+        const pitchSign = cfg.look.invertY ? -1 : 1;
+        const pitchDelta = intent.look.y * pitchSign;
+        intent.look.set(0, 0);
+
+        runtime.bodyYaw += yawDelta;
+        // keep yaw bounded (purely cosmetic — sin/cos handle wraparound fine)
+        if (runtime.bodyYaw > Math.PI) runtime.bodyYaw -= TWO_PI;
+        else if (runtime.bodyYaw < -Math.PI) runtime.bodyYaw += TWO_PI;
+
+        runtime.eyePitch = clamp(
+            runtime.eyePitch + pitchDelta,
+            cfg.look.pitchMinDeg * DEG_TO_RAD,
+            cfg.look.pitchMaxDeg * DEG_TO_RAD,
+        );
+
+        // Write body yaw back to transform (pure yaw, no pitch on body)
+        bodyTransform.rotation.fromAxisAngle(Vector3.up, runtime.bodyYaw);
+
+        // -- L1.b: Speed selection --------------------------------------
+        const isSprintIntent = intent.sprint && intent.move.y > 0.5 && state.grounded;
+        const isCrouchActive = this._resolveCrouchHeld(controller, runtime);
+
+        let targetSpeed;
+        if (isCrouchActive) {
+            targetSpeed = cfg.motion.crouchSpeed;
+        } else if (isSprintIntent) {
+            targetSpeed = cfg.motion.sprintSpeed;
+        } else {
+            targetSpeed = cfg.motion.walkSpeed;
+        }
+
+        // -- 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).
+        //
+        //   screen_forward(θ) = ( sin θ, 0,  cos θ )
+        //   screen_right  (θ) = (-cos θ, 0,  sin θ )
+        const sinYaw = Math.sin(runtime.bodyYaw);
+        const cosYaw = Math.cos(runtime.bodyYaw);
+
+        // 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;
+
+        const desiredVx = sinYaw * nmvY + -cosYaw * nmvX;
+        const desiredVz = cosYaw * nmvY + sinYaw * nmvX;
+
+        const desiredHorizontalVx = desiredVx * targetSpeed;
+        const desiredHorizontalVz = desiredVz * targetSpeed;
+
+        // -- 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;
+        }
+
+        const maxStep = horizAccel * dt;
+        runtime.velocityX = stepTowards(runtime.velocityX, desiredHorizontalVx, maxStep);
+        runtime.velocityZ = stepTowards(runtime.velocityZ, desiredHorizontalVz, maxStep);
+
+        // -- L1.e: Jump (edge-triggered, buffered, coyote-graced) -------
+        const jumpPressedEdge = intent.jump && !runtime.prevJumpHeld;
+        const jumpReleasedEdge = !intent.jump && runtime.prevJumpHeld;
+        runtime.prevJumpHeld = intent.jump;
+
+        if (jumpPressedEdge) {
+            state.jumpBufferRemaining = cfg.jump.bufferTime;
+        }
+        state.jumpBufferRemaining = Math.max(0, state.jumpBufferRemaining - dt);
+
+        const canJumpNow =
+            (state.grounded || state.timeSinceGrounded < cfg.jump.coyoteTime)
+            && state.jumpBufferRemaining > 0
+            && !state.inJumpAnticipation
+            && !runtime.midJump;
+
+        if (canJumpNow) {
+            // Begin anticipation — squash; impulse fires after duration elapses
+            state.inJumpAnticipation = true;
+            runtime.anticipationRemaining = cfg.jump.anticipation.duration;
+            state.jumpBufferRemaining = 0; // claimed
+        }
+
+        // Variable-height cut: only valid during ascent and once jump has launched
+        if (jumpReleasedEdge && runtime.midJump && runtime.velocityY > 0) {
+            state.isVariableJumpCut = true;
+        }
+
+        // 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) {
+                state.inJumpAnticipation = false;
+                runtime.anticipationRemaining = 0;
+            } else {
+                runtime.anticipationRemaining -= dt;
+                if (runtime.anticipationRemaining <= 0) {
+                    runtime.velocityY = runtime.jumpInitialVy;
+                    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);
+
+                    sig.onJumpStart.send1({ peakHeight: cfg.jump.peakHeight });
+                    sig.onLeaveGround.send1({ reason: "jump" });
+                }
+            }
+        }
+
+        // -- L1.f: Gravity ---------------------------------------------
+        let gMag = runtime.gravity;
+        if (runtime.velocityY <= 0) {
+            gMag *= cfg.jump.fallGravityMult;
+            state.isAscending = false;
+        } else if (state.isVariableJumpCut) {
+            gMag *= cfg.jump.cutGravityMult;
+        }
+
+        runtime.velocityY -= gMag * dt;
+
+        // -- L1.g: 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);
+
+                if (!state.grounded) {
+                    // Land
+                    const impactVy = -runtime.velocityY; // positive magnitude
+                    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;
+
+                    runtime.midJump = false;
+                    state.isAscending = false;
+                    state.isVariableJumpCut = false;
+                    state.fallDistance = 0;
+                }
+
+                state.grounded = true;
+                state.verticalSpeed = 0;
+                runtime.velocityY = 0;
+                state.airborneTime = 0;
+                state.timeSinceGrounded = 0;
+            } else {
+                if (state.grounded) {
+                    sig.onLeaveGround.send1({ reason: runtime.midJump ? "jump" : "fall" });
+                    runtime.takeoffVy = runtime.velocityY;
+                    runtime.peakAltitude = bodyTransform.position.y;
+                }
+                state.grounded = false;
+                state.verticalSpeed = runtime.velocityY;
+                state.airborneTime += dt;
+                state.timeSinceGrounded += dt;
+                state.fallDistance += Math.max(0, -runtime.velocityY * dt);
+            }
+        } else {
+            // External physics is expected to maintain state.grounded /
+            // state.verticalSpeed; we still track airborne timer.
+            if (state.grounded) {
+                state.timeSinceGrounded = 0;
+                state.airborneTime = 0;
+            } else {
+                state.timeSinceGrounded += dt;
+                state.airborneTime += dt;
+            }
+        }
+
+        // Detect jump apex
+        if (runtime.midJump && !runtime.apexFired) {
+            if (bodyTransform.position.y > runtime.peakAltitude) {
+                runtime.peakAltitude = bodyTransform.position.y;
+            } else if (runtime.velocityY <= 0) {
+                sig.onJumpApex.send0();
+                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);
+
+        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";
+        } else {
+            state.moveMode = "Idle";
+        }
+
+        if (state.moveMode === "Sprint" && prevMoveMode !== "Sprint") {
+            sig.onSprintStart.send0();
+        } else if (prevMoveMode === "Sprint" && state.moveMode !== "Sprint") {
+            sig.onSprintStop.send0();
+        }
+
+        // -- 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)
+
+        // 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 });
+        }
+
+        // -- 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);
+        }
+        // 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 });
+            }
+        }
+
+        // -- 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;
+
+        if (isCrouchActive !== state.crouchActive) {
+            state.crouchActive = isCrouchActive;
+            if (isCrouchActive) sig.onCrouchEnter.send0();
+            else sig.onCrouchExit.send0();
+        }
+
+        // -- 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;
+        }
+        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,
+        );
+
+        // -- L2.h: Publish pose channels --------------------------------
+        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;
+        // 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)
+            / 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);
+        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;
+        }
+        // "hold" mode
+        runtime.prevCrouchHeld = intent.crouch;
+        return intent.crouch;
+    }
+
+    /**
+     * Compose the eye transform from body + state-driven offsets.
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {number} entity
+     */
+    _composeEye(controller, entity) {
+        const ecd = this.entityManager.dataset;
+        const runtime = this.runtime.get(entity);
+        if (runtime === undefined) return;
+
+        const dt = this._currentRenderDt;
+        const cfg = controller.config;
+        const state = controller.state;
+
+        const bodyTransform = ecd.getComponent(entity, Transform);
+        if (bodyTransform === undefined) return;
+
+        if (controller.eyeEntity === -1) return;
+        const eyeTransform = ecd.getComponent(controller.eyeEntity, Transform);
+        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
+            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);
+        }
+
+        // Breath — sine + tiny noise
+        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;
+
+        // Landing spring dip
+        eyeLocal.y += runtime.landSpring.value;
+
+        // Jump anticipation dip (linear ramp during anticipation)
+        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;
+        }
+
+        // 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);
+        worldOffset.applyQuaternion(bodyTransform.rotation);
+
+        eyeTransform.position.copy(bodyTransform.position);
+        eyeTransform.position._add(worldOffset.x, worldOffset.y, worldOffset.z);
+
+        // -- Eye rotation: body yaw × eye pitch × roll -------------------
+        // Bob roll mixes in for a subtle head sway (in phase with lateral bob).
+        // Breath pitch is a small extra nod 90° out of phase with vertical
+        // 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) {
+            const phase = state.stridePhase * TWO_PI;
+            const ampRoll = cfg.bob.rollAtWalkDeg * DEG_TO_RAD * state.speedNormalized;
+            rollTotal += ampRoll * Math.sin(phase * 0.5);
+        }
+
+        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;
+
+        // composition: yaw * pitch * roll
+        //   pitch around world X — yaw applied after, so effective axis is camera-local right
+        //   roll  around world Z — yaw and pitch applied after, so effective axis is camera-local forward
+        const qYaw = SCRATCH_Q_A.fromAxisAngle(Vector3.up, runtime.bodyYaw);
+        const qPitch = SCRATCH_Q_B.fromAxisAngle(Vector3.right, pitchTotal);
+        const qRoll = SCRATCH_Q_C.fromAxisAngle(Vector3.forward, rollTotal);
+
+        eyeTransform.rotation.multiplyQuaternions(qYaw, qPitch);
+        eyeTransform.rotation.multiply(qRoll);
+
+        // -- 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;
+        }
+        if (state.crouchActive) fovTarget += cfg.fov.crouchAdd;
+
+        criticallyDampedSpringStep(runtime.fovSpring, fovTarget, cfg.fov.smoothHalfLife, 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.
+        // The CameraSystem's visibility-construction hook calls
+        // updateProjectionMatrix() each frame anyway.
+        if (camera.object !== null) {
+            camera.object.fov = runtime.fovSpring.value;
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Exponential approach with half-life parameterization.
+ * @param {number} current
+ * @param {number} target
+ * @param {number} halfLife
+ * @param {number} dt
+ * @returns {number}
+ */
+function exponentialApproach(current, target, halfLife, dt) {
+    if (halfLife <= 0) return target;
+    const alpha = 1 - Math.exp(-LN2 * dt / halfLife);
+    return current + (target - current) * alpha;
+}
+
+/**
+ * Detect that phase value crossed a boundary in [0,1) between two ticks.
+ * Handles the wraparound case where phase jumps from e.g. 0.95 to 0.05.
+ *
+ * @param {number} prev previous phase in [0,1)
+ * @param {number} next current phase in [0,1)
+ * @param {number} boundary in [0,1)
+ * @returns {boolean}
+ */
+function phaseCrossed(prev, next, boundary) {
+    if (next >= prev) {
+        // no wrap
+        return prev < boundary && next >= boundary;
+    } else {
+        // wrapped past 1.0
+        return prev < boundary || next >= boundary;
+    }
+}
+