@woosh/meep-engine 2.138.20 → 2.139.0

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

@@ -11,11 +11,28 @@ export class FirstPersonPlayerControllerConfig {
         /** Standing eye height, meters above body origin. */
         height: 1.80,
         /** Crouched eye height. */
-        crouchHeight: 1.10,
+        crouchHeight: 0.8,
+        /** Prone eye height (used by slide). Body is horizontal — eye
+         *  just above ground level, head turned toward the direction
+         *  of travel. */
+        proneHeight: 0.4,
         /** Capsule radius, for downstream physics. */
-        radius: 0.35,
-        /** Kilograms — drives bob amplitude and land-impact magnitude. */
+        radius: 0.34,
+        /** Kilograms — affects bob, jump, landing, accel, and exertion via massRatio. */
         mass: 80,
+        /** Reference mass against which `mass` is normalized (massRatio = mass/refMass). */
+        referenceMass: 80,
+        /**
+         * How strongly `mass` couples into derived effects. 0 = mass is
+         * cosmetic; 1.0 = full coupling (heavier ⇒ lower jump, lower accel,
+         * harder landing, faster exhaustion). At 1.0 a 25% mass increase
+         * yields:
+         *   jump peak       ≈ 0.83×   (∝ 1/√massRatio — kinematically motivated)
+         *   ground accel    ≈ 0.80×   (∝ 1/massRatio — F = ma at fixed force)
+         *   landing dip     ≈ 1.25×   (∝ massRatio — higher momentum to absorb)
+         *   exertion rise   ≈ 1.25×   (∝ massRatio — more body to move)
+         */
+        massCouplingStrength: 1.0,
     };
 
     // Defaults are tuned toward an "athlete with juice" feel — plausible
@@ -34,6 +51,19 @@ export class FirstPersonPlayerControllerConfig {
         groundDecel: 75,        // crisp stops, no skating
         /** m/s^2 horizontal acceleration while airborne. */
         airAccel: 14,           // mid-air agility for course-correction
+        /**
+         * Top-speed multiplier applied while the move intent has a backward
+         * component (intent.move.y < 0). Backpedaling is mechanically slower
+         * than running forward — this also enforces a hard cap rather than
+         * letting "backward sprint" reach the same speed as forward sprint.
+         */
+        backwardSpeedFactor: 0.65,
+        /**
+         * Acceleration multiplier while moving backward. Body has worse
+         * mechanical advantage when reversing — slower to start, slower to
+         * stop, sells the "fighting the gait" feel.
+         */
+        backwardAccelFactor: 0.65,
     };
 
     jump = {
@@ -78,6 +108,123 @@ export class FirstPersonPlayerControllerConfig {
         mode: "hold",
     };
 
+    /**
+     * Wall-run ability — airborne + lateral wall + speed → run along the
+     * wall with reduced gravity. Camera tilts into the wall via the
+     * shared lean spring (consistent with the rest of the camera).
+     * Fields here are consumed by the {@link WallRun} ability when
+     * registered.
+     */
+    wallRun = {
+        /** Minimum horizontal speed (m/s) to engage wall-run. */
+        minSpeed: 4.0,
+        /** Player must be airborne at least this long before wall-run can
+         *  engage — prevents wall-run triggering off a jump's first frames. */
+        minAirborneTime: 0.1,
+        /** Maximum wall-run duration (s). Auto-exits at the end. */
+        maxDuration: 2.0,
+        /** Multiplier on base gravity while wall-running. Lower = longer hang. */
+        gravityFactor: 0.25,
+        /** Camera tilt magnitude (deg) into the wall. Disabled by the
+         *  motion-sickness toggle alongside the standard lean. */
+        cameraRollDeg: 12,
+    };
+
+    /**
+     * Wall-jump ability — instantaneous off-wall impulse. Fires from
+     * either an active wall-run state or from near-wall airborne (a
+     * short window where the player is close enough to push off).
+     */
+    wallJump = {
+        /** Impulse magnitude away from the wall (m/s, applied along wall normal). */
+        outwardImpulse: 6.0,
+        /** Upward component multiplier on jumpInitialVy. */
+        upFactor: 0.9,
+        /** Max distance to wall (m) at which a near-wall-airborne wall-jump
+         *  is allowed (when not already wall-running). */
+        nearWallMaxDistance: 0.6,
+    };
+
+    /**
+     * Ledge-grab ability — snap to a forward ledge while descending and
+     * hang from it until the player releases. Climbing fatigue is
+     * modelled via the shared exertion channel: hang too long and you
+     * slip. Fields here are consumed by the {@link LedgeGrab} ability
+     * if registered; ignored otherwise.
+     */
+    ledgeGrab = {
+        /** Body Y offset from ledge top while hanging (negative — feet
+         *  below the ledge so the body looks like it's gripping the
+         *  edge). */
+        hangOffsetY: -1.4,
+        /** Forward offset from the ledge edge (negative = pulled BACK
+         *  from the edge so the body is against the wall under the
+         *  ledge). */
+        hangOffsetForward: -0.2,
+        /** Exertion rise per second while hanging — drives slip-by-
+         *  fatigue. The base exertion rise scale (massRatios) applies. */
+        exertionRiseRate: 0.15,
+        /** Player must be airborne at least this long before a ledge-
+         *  grab can engage — prevents auto-catching mid-jump. */
+        minAirborneTime: 0.3,
+        /** Vertical kick (multiplier on jumpInitialVy) given on a
+         *  mantle-up release. Just enough to put the body above the
+         *  ledge so mantle's ledgeAhead probe still resolves correctly
+         *  on the next tick. */
+        mantleUpUpFactor: 0.3,
+    };
+
+    /**
+     * Mantle ability — auto-triggers when the player approaches a
+     * reachable obstacle with forward intent. The body follows a scripted
+     * path (horizontal + vertical eases) onto the surface; player input
+     * is suspended for the path's duration. Fields here are consumed by
+     * the {@link Mantle} ability if registered; ignored otherwise.
+     */
+    mantle = {
+        /** Below this height (m above feet), the obstacle is just a step
+         *  the player can walk over — no mantle. */
+        minHeight: 0.4,
+        /** Above this, the surface is out of reach — no mantle. ~1.4m
+         *  is chest height for a 1.8m body, which is the canonical
+         *  "obstacle you can climb on but not over without help". */
+        maxHeight: 1.4,
+        /** Total scripted-path duration (seconds). Short enough that the
+         *  brief loss of player control isn't frustrating. */
+        duration: 0.5,
+        /** How far past the obstacle edge the player lands (m). Slight
+         *  forward bias so the player ends on top of the surface, not
+         *  on the edge. */
+        forwardOffsetOnLand: 0.4,
+    };
+
+    /**
+     * Slide ability — activates from sprint+crouch when grounded. The
+     * fields here are read by the {@link Slide} ability if it's registered
+     * on the controller; unused if Slide is not in use.
+     */
+    slide = {
+        /** Required horizontal speed to start a slide. Below this, crouch+
+         *  sprint just transitions to a normal crouched walk. */
+        minEntrySpeed: 5.0,
+        /** Auto-exit threshold — slide ends when speed drops below this. */
+        endSpeed: 2.0,
+        /** Horizontal deceleration (m/s²) while sliding. Lower than the
+         *  normal groundDecel so slides preserve momentum longer. */
+        friction: 3.0,
+        /** Non-interruptible window (seconds) after slide start — higher-
+         *  priority abilities can't preempt during this window so the
+         *  player isn't yanked out the instant they commit to a slide. */
+        startupWindow: 0.15,
+        /** Multiplier on the jump initial Vy for slide-jump. 1.0 = same
+         *  height as a standing jump; >1 gives slide-jump some extra
+         *  reward for chaining the input. */
+        slideJumpUpFactor: 1.05,
+        /** Vertical-impact-spring kick (m/s) at slide entry — the
+         *  satisfying "thud" of dropping into the slide. */
+        entryImpactVelocity: 0.6,
+    };
+
     bob = {
         stepFreqAtWalk: 1.8,
         stepFreqExp: 0.75,      // sub-linear so sprint isn't frantic
@@ -88,6 +235,60 @@ export class FirstPersonPlayerControllerConfig {
         rollAtWalkDeg: 0.8,     // a touch more visible head sway
         /** Speeds below this don't tick the stride at all. */
         minStepSpeed: 0.2,
+        /**
+         * Half-life of the bob-amplitude envelope (seconds). When the player
+         * starts/stops moving, the bob amplitude springs toward its natural
+         * value rather than cutting on/off — so releasing a movement key
+         * doesn't whiplash the head from full sway back to neutral. The
+         * stride phase itself still freezes when stationary; only the
+         * AMPLITUDE is temporally smoothed.
+         */
+        intensityHalfLife: 0.22,
+        /**
+         * Vertical impact spring — kicked downward at each footfall. The
+         * spring's response shapes the actual vertical motion of the head:
+         * a sharp dip (foot arresting the head's fall), recovery through
+         * neutral, and a slight overshoot above neutral as the standing
+         * leg injects energy into the body (the "push" phase). Models the
+         * gait COM trajectory more accurately than a smooth sinusoid.
+         */
+        impactSpringHalfLife: 0.14,
+        /** zeta < 1 → spring overshoots after impact, sells the leg-push. */
+        impactSpringZeta: 0.50,
+        /**
+         * Multiplier converting "desired peak dip" (verticalAmpAtWalk + mass
+         * boost, scaled by intensity and back-pedal factor) into the actual
+         * velocity impulse delivered at footfall. Empirical — tuned so the
+         * default verticalAmpAtWalk produces the expected peak dip with the
+         * spring params above.
+         */
+        impactKickMultiplier: 30,
+        /**
+         * Multipliers applied to bob amplitude when the player is moving
+         * backward (interpolated by "backwardness" — the negative dot of
+         * velocity onto screen-forward, normalized to sprint speed). At
+         * full back-pedal these are fully applied; at rest they have no
+         * effect.
+         *
+         * Lateral is intentionally larger than vertical: real back-gait
+         * has worse side-to-side balance than vertical compression, so
+         * the visual wobble should track that. Roll boosts each footfall's
+         * head-tilt for the same reason — sells "unstable footing".
+         */
+        backwardVerticalAmpFactor: 1.2,
+        backwardLateralAmpFactor: 1.4,
+        backwardRollFactor: 1.3,
+        /**
+         * Bob roll × lean coupling: when the body is leaning into a turn
+         * (lean spring displaced), the per-stride head roll is biased
+         * toward the lean direction. At 0 the bob roll is symmetric
+         * regardless of lean. At 1.0 the bob roll excursions in the lean
+         * direction are doubled and the opposite-direction excursions go to
+         * zero. Typical 0.3–0.6 reads as a cohesive "leaning while running"
+         * gait. Normalized against cfg.lean.maxRollDeg so the coupling
+         * stays proportional regardless of how aggressive lean is tuned.
+         */
+        leanCouplingFactor: 0.45,
     };
 
     breath = {
@@ -99,14 +300,70 @@ export class FirstPersonPlayerControllerConfig {
         pitchAmpMaxDeg: 0.55,
         /** ±20% amplitude noise rides on the sine. */
         noiseAmount: 0.20,
+        /**
+         * Locomotor-respiratory coupling strength at full exertion. The
+         * breath-rate target is blended between purely metabolic (driven by
+         * exertion) and stride-aligned (an integer N strides per breath
+         * cycle). At 0 no coupling; at 1 breath rate is fully pulled toward
+         * the stride-aligned target.
+         *
+         * Coupling is SCALED by exertion — low exertion means the breath is
+         * dictated by metabolic demand alone, high sustained effort lets
+         * the diaphragm couple to gait impacts (mechanistically: heavier
+         * breathing means deeper chest excursions, which the gait's
+         * vertical accelerations bias toward integer ratios). Matches
+         * empirical findings in dynamic activity (Bernasconi & Kohl 1993,
+         * Bramble & Carrier 1983) — much weaker than steady-state running.
+         *
+         * Frequency-coupled only, NOT phase-locked: breath rate matches a
+         * sub-multiple of stride rate, but phase drifts. Holds the "loose"
+         * character the user asked for.
+         */
+        locomotorCouplingMax: 0.45,
+        /** Coupling does not engage below this stride frequency (Hz). At
+         *  walking pace your gait is too slow to mechanically influence
+         *  breath; coupling really shows up at jog+ pace. */
+        couplingMinStrideFreqHz: 1.5,
     };
 
     exertion = {
+        // -- Sustained drivers (continuous accumulation per second) ---
+        /** Per-second accumulation while sprinting (mass-scaled internally). */
         sprintRiseRate: 0.20,
-        jumpRise: 0.08,
+        /** Per-second decay toward 0 when not under sustained load. */
         idleDecayRate: 0.12,
+
+        // -- Impulse drivers (one-shot bumps on discrete events) ------
+        /** Bump on jump fire — the muscular impulse of pushing off. */
+        jumpRise: 0.08,
+        /** Bump on crouch-enter — the knee-grip on absorbing into a crouch.
+         *  Small; we don't want crouch-spamming to instantly exhaust. */
+        crouchEnterRise: 0.03,
+        /**
+         * Per-(m/s) impulse on landing — proportional to vertical impact
+         * speed. A clean low-jump landing barely registers; a hard fall
+         * delivers a noticeable bump. Clamped internally so an impossible
+         * fall doesn't max out exertion in one tick.
+         */
+        landImpulsePerVy: 0.012,
+        /** Max impulse magnitude added by any single landing. */
+        landImpulseMax: 0.20,
+
+        // -- Breath coupling (existing — unchanged contract) ----------
+        /** How long after exertion subsides before breath rate normalizes. */
         rateDecayHalfLife: 4.0,
+        /** How long after exertion subsides before breath amplitude normalizes. */
         ampDecayHalfLife: 2.0,
+
+        // -- Output coupling: exertion affects how the body moves -----
+        /** At full exertion, bob lateral amp is multiplied by 1 + this.
+         *  Sells "tired wobble" — modest effect (10–20% recommended). */
+        bobLateralBoostAtMax: 0.20,
+        /** At full exertion, the head droops forward by this many degrees.
+         *  Sells visual fatigue without compromising aim. Subtle. */
+        headDroopAtMaxDeg: 1.5,
+        /** Spring half-life for the head-droop transition. */
+        headDroopHalfLife: 0.6,
     };
 
     lean = {
@@ -114,12 +371,35 @@ export class FirstPersonPlayerControllerConfig {
         /** Degrees of roll per (lateral m/s^2 / 9.81). */
         maxRollDeg: 3.2,        // more visible lean into turns — sells the athleticism
         spring: { halfLife: 0.16, zeta: 1.0 },
+        /**
+         * Yaw-rate "look-lean": camera banks into mouse-driven turns even
+         * without strafe input. Disable for motion-sickness sensitivity.
+         */
+        lookLeanEnabled: true,
+        /**
+         * Degrees of roll per rad/s of yaw rate. ~3 means a 180°/s turn
+         * (slow camera pan) gives ~16.5° of bank; a fast mouse flick at
+         * 5 rad/s (≈286°/s) would saturate against the clamp below.
+         */
+        lookLeanDegPerRadPerSec: 3.0,
+        /** Yaw rate is clamped to ±this (rad/s) before scaling — prevents
+         *  single-frame flicks from spiking the lean target. */
+        lookLeanYawRateClamp: 4.0,
+        /**
+         * Multiplier applied to look-lean (yaw-rate banking) when crouched.
+         * Crouched stance is low and stable; banking from a mouse turn
+         * reads as unmotivated. Default 0 fully disables; dial up to add
+         * a subtle tilt without it feeling like you're running. The lateral-
+         * acceleration lean is NOT affected by this — it scales naturally
+         * with crouch speeds since accel magnitudes drop.
+         */
+        crouchLookLeanFactor: 0.0,
     };
 
     fov = {
         base: 75,               // wider baseline — more energetic
-        sprintAdd: 10,          // dramatic punch on sprint (Apex/Titanfall feel)
-        crouchAdd: -4,
+        sprintAdd: 7,          // dramatic punch on sprint (Apex/Titanfall feel)
+        crouchAdd: -3,
         smoothHalfLife: 0.18,   // slightly snappier transitions
     };
 
@@ -129,6 +409,23 @@ export class FirstPersonPlayerControllerConfig {
         invertY: false,
     };
 
+    /**
+     * Postural shifts driven by intent — distinct from look (which is
+     * player-driven) and from bob (which is procedural). Models
+     * Mirror's Edge-style "commitment to motion": sprinting tilts the head
+     * forward as the body leans into the run. Slow spring so it builds up
+     * over a second or so rather than snapping — it's a *posture* change,
+     * not a flick.
+     */
+    posture = {
+        /** Forward pitch (deg) applied to the eye at full sprint. Positive = look-down. */
+        sprintForwardPitchDeg: 4.0,
+        /** Spring half-life for the sprint pitch transition. */
+        sprintForwardPitchHalfLife: 0.32,
+        /** Small forward eye-position shift (m) at full sprint — head leads the hips. */
+        sprintForwardShiftM: 0.04,
+    };
+
     gravity = {
         /** Default gravity magnitude (m/s^2). Overridden by computeJumpFromApex once
          *  the jump tunables are resolved; kept here so non-jumping entities (NPCs,
@@ -149,12 +446,18 @@ export class FirstPersonPlayerControllerConfig {
                 },
             },
             crouch: { ...this.crouch },
+            ledgeGrab: { ...this.ledgeGrab },
+            mantle: { ...this.mantle },
+            wallRun: { ...this.wallRun },
+            wallJump: { ...this.wallJump },
+            slide: { ...this.slide },
             bob: { ...this.bob },
             breath: { ...this.breath },
             exertion: { ...this.exertion },
             lean: { ...this.lean, spring: { ...this.lean.spring } },
             fov: { ...this.fov },
             look: { ...this.look },
+            posture: { ...this.posture },
             gravity: { ...this.gravity },
         };
     }
@@ -177,6 +480,11 @@ export class FirstPersonPlayerControllerConfig {
             }
         }
         if (json.crouch) Object.assign(this.crouch, json.crouch);
+        if (json.ledgeGrab) Object.assign(this.ledgeGrab, json.ledgeGrab);
+        if (json.mantle) Object.assign(this.mantle, json.mantle);
+        if (json.wallRun) Object.assign(this.wallRun, json.wallRun);
+        if (json.wallJump) Object.assign(this.wallJump, json.wallJump);
+        if (json.slide) Object.assign(this.slide, json.slide);
         if (json.bob) Object.assign(this.bob, json.bob);
         if (json.breath) Object.assign(this.breath, json.breath);
         if (json.exertion) Object.assign(this.exertion, json.exertion);
@@ -187,6 +495,7 @@ export class FirstPersonPlayerControllerConfig {
         }
         if (json.fov) Object.assign(this.fov, json.fov);
         if (json.look) Object.assign(this.look, json.look);
+        if (json.posture) Object.assign(this.posture, json.posture);
         if (json.gravity) Object.assign(this.gravity, json.gravity);
     }