@woosh/meep-engine 2.138.20 → 2.140.0

package/src/engine/control/first-person/math/Spring.js

@@ -0,0 +1,71 @@
+import { dampedSpringStep } from "./dampedSpringStep.js";
+
+/**
+ * Damped spring with a value and velocity. Half-life parameterized.
+ *
+ * Convention: zeta = 1.0 is critically damped (no overshoot, fastest settle).
+ * zeta < 1.0 under-damps (oscillation/ringing, useful for impact bounces).
+ * zeta > 1.0 over-damps (slow approach, rarely useful in this engine).
+ *
+ * Use kick() to inject a velocity impulse (e.g. footfall impact, gunfire
+ * recoil, knockback). Use stepTo() each fixed update to advance the
+ * simulation toward a target value.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Spring {
+    /**
+     * @param {number} [value] initial value
+     * @param {number} [velocity] initial velocity
+     */
+    constructor(value = 0, velocity = 0) {
+        this.value = value;
+        this.velocity = velocity;
+    }
+
+    /**
+     * Advance the spring toward `target`. Same half-life form used by the
+     * pre-existing dampedSpringStep / criticallyDampedSpringStep helpers.
+     *
+     * @param {number} target target value
+     * @param {number} halfLife seconds for the envelope to halve (smaller → snappier)
+     * @param {number} zeta damping ratio (1=critical, <1=ring, >1=sluggish)
+     * @param {number} dt
+     */
+    stepTo(target, halfLife, zeta, dt) {
+        dampedSpringStep(this, target, halfLife, zeta, dt);
+    }
+
+    /**
+     * Inject a velocity impulse. Use for one-shot events that should result
+     * in an immediate "snap" (footfall down-kick, recoil push, blow-back).
+     *
+     * @param {number} impulse velocity to add
+     */
+    kick(impulse) {
+        this.velocity += impulse;
+    }
+
+    /**
+     * Instantaneously place the spring at a value with zero velocity. Use
+     * when initializing or hard-resetting (e.g. teleport).
+     *
+     * @param {number} [value]
+     */
+    settle(value = 0) {
+        this.value = value;
+        this.velocity = 0;
+    }
+
+    /**
+     * Displace value while preserving velocity. Used for "land here, then
+     * decay" — see landing recovery where we want the impact dip displaced
+     * but the velocity to ride out from there.
+     *
+     * @param {number} value
+     */
+    setValue(value) {
+        this.value = value;
+    }
+}

package/src/engine/control/first-person/math/computeLRCBreathRate.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Locomotor-respiratory coupling — compute the breath-rate target by
+ * blending the metabolic-demand rate with a stride-aligned sub-multiple.
+ *
+ * Empirical basis: in steady-state running, breath naturally locks to a
+ * sub-multiple of stride (2:1, 3:1, 4:1 depending on speed — see Bramble &
+ * Carrier 1983, Bernasconi & Kohl 1993). In *dynamic* activity (varied
+ * terrain, sports, untrained) the coupling is much weaker and the breath
+ * rate is dictated mostly by metabolic demand.
+ *
+ * We blend the two: at low exertion (or below the strideFreq threshold)
+ * the output is purely metabolic. At high exertion AND active gait, the
+ * output is pulled toward the integer-ratio aligned rate. This is
+ * FREQUENCY-only coupling — no phase lock — so the breath "rides" the
+ * gait without being constrained to it, matching loose dynamic-activity
+ * coupling rather than tight steady-state coupling.
+ *
+ * @param {number} metabolicRate the rate driven by exertion alone (Hz)
+ * @param {number} strideFreqHz current stride frequency (Hz, 0 if not striding)
+ * @param {number} exertion in [0..1]
+ * @param {number} couplingMax coupling strength at exertion=1
+ * @param {number} minStrideFreqHz coupling does not engage below this
+ * @returns {number} target breath rate (Hz)
+ */
+export function computeLRCBreathRate(metabolicRate: number, strideFreqHz: number, exertion: number, couplingMax: number, minStrideFreqHz: number): number;
+//# sourceMappingURL=computeLRCBreathRate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"computeLRCBreathRate.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/math/computeLRCBreathRate.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,oDAPW,MAAM,gBACN,MAAM,YACN,MAAM,eACN,MAAM,mBACN,MAAM,GACJ,MAAM,CAgBlB"}

package/src/engine/control/first-person/math/computeLRCBreathRate.js

@@ -0,0 +1,41 @@
+import { lerp } from "../../../../core/math/lerp.js";
+
+/**
+ * Locomotor-respiratory coupling — compute the breath-rate target by
+ * blending the metabolic-demand rate with a stride-aligned sub-multiple.
+ *
+ * Empirical basis: in steady-state running, breath naturally locks to a
+ * sub-multiple of stride (2:1, 3:1, 4:1 depending on speed — see Bramble &
+ * Carrier 1983, Bernasconi & Kohl 1993). In *dynamic* activity (varied
+ * terrain, sports, untrained) the coupling is much weaker and the breath
+ * rate is dictated mostly by metabolic demand.
+ *
+ * We blend the two: at low exertion (or below the strideFreq threshold)
+ * the output is purely metabolic. At high exertion AND active gait, the
+ * output is pulled toward the integer-ratio aligned rate. This is
+ * FREQUENCY-only coupling — no phase lock — so the breath "rides" the
+ * gait without being constrained to it, matching loose dynamic-activity
+ * coupling rather than tight steady-state coupling.
+ *
+ * @param {number} metabolicRate the rate driven by exertion alone (Hz)
+ * @param {number} strideFreqHz current stride frequency (Hz, 0 if not striding)
+ * @param {number} exertion in [0..1]
+ * @param {number} couplingMax coupling strength at exertion=1
+ * @param {number} minStrideFreqHz coupling does not engage below this
+ * @returns {number} target breath rate (Hz)
+ */
+export function computeLRCBreathRate(
+    metabolicRate,
+    strideFreqHz,
+    exertion,
+    couplingMax,
+    minStrideFreqHz,
+) {
+    if (strideFreqHz < minStrideFreqHz || metabolicRate <= 1e-3) {
+        return metabolicRate;
+    }
+    const stridesPerBreath = Math.max(1, Math.round(strideFreqHz / metabolicRate));
+    const strideAlignedRate = strideFreqHz / stridesPerBreath;
+    const coupling = couplingMax * exertion;
+    return lerp(metabolicRate, strideAlignedRate, coupling);
+}

package/src/engine/control/first-person/math/computeMassRatios.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Derive the per-effect mass scaling factors from the body config. Computed
+ * once at link time (mass is not expected to change at runtime); the system
+ * caches the result on the runtime.
+ *
+ * Each scaling is mixed with coupling-strength ∈ [0, 1]: at 0 the ratio is
+ * identity (mass becomes purely cosmetic, useful for prototypes); at 1 the
+ * full kinematic relationship applies.
+ *
+ *   massRatio = mass / referenceMass
+ *   coupled(r, k) = 1 + (r - 1) · k       // identity at k=0, full r at k=1
+ *   jumpV0Scale       = 1 / √coupled(massRatio, k)        ∝ 1/√mass
+ *   groundAccelScale  = 1 / coupled(massRatio, k)         ∝ 1/mass
+ *   landingDipScale   =   coupled(massRatio, k)           ∝   mass
+ *   exertionRiseScale =   coupled(massRatio, k)           ∝   mass
+ *
+ * @param {number} mass
+ * @param {number} referenceMass
+ * @param {number} couplingStrength  [0..1]
+ * @returns {{
+ *   massRatio: number,
+ *   jumpV0Scale: number,
+ *   groundAccelScale: number,
+ *   landingDipScale: number,
+ *   exertionRiseScale: number,
+ * }}
+ */
+export function computeMassRatios(mass: number, referenceMass: number, couplingStrength: number): {
+    massRatio: number;
+    jumpV0Scale: number;
+    groundAccelScale: number;
+    landingDipScale: number;
+    exertionRiseScale: number;
+};
+//# sourceMappingURL=computeMassRatios.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"computeMassRatios.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/math/computeMassRatios.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wCAXW,MAAM,iBACN,MAAM,oBACN,MAAM,GACJ;IACZ,SAAa,EAAE,MAAM,CAAC;IACtB,WAAe,EAAE,MAAM,CAAC;IACxB,gBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAqB,EAAE,MAAM,CAAC;CAC3B,CAkBH"}

package/src/engine/control/first-person/math/computeMassRatios.js

@@ -0,0 +1,44 @@
+/**
+ * Derive the per-effect mass scaling factors from the body config. Computed
+ * once at link time (mass is not expected to change at runtime); the system
+ * caches the result on the runtime.
+ *
+ * Each scaling is mixed with coupling-strength ∈ [0, 1]: at 0 the ratio is
+ * identity (mass becomes purely cosmetic, useful for prototypes); at 1 the
+ * full kinematic relationship applies.
+ *
+ *   massRatio = mass / referenceMass
+ *   coupled(r, k) = 1 + (r - 1) · k       // identity at k=0, full r at k=1
+ *   jumpV0Scale       = 1 / √coupled(massRatio, k)        ∝ 1/√mass
+ *   groundAccelScale  = 1 / coupled(massRatio, k)         ∝ 1/mass
+ *   landingDipScale   =   coupled(massRatio, k)           ∝   mass
+ *   exertionRiseScale =   coupled(massRatio, k)           ∝   mass
+ *
+ * @param {number} mass
+ * @param {number} referenceMass
+ * @param {number} couplingStrength  [0..1]
+ * @returns {{
+ *   massRatio: number,
+ *   jumpV0Scale: number,
+ *   groundAccelScale: number,
+ *   landingDipScale: number,
+ *   exertionRiseScale: number,
+ * }}
+ */
+export function computeMassRatios(mass, referenceMass, couplingStrength) {
+    const r = mass / Math.max(referenceMass, 1e-6);
+    const k = Math.max(0, Math.min(1, couplingStrength));
+    const coupled = 1 + (r - 1) * k;
+
+    // Guard: at very low coupled values 1/coupled blows up. Clamp the
+    // *minimum* coupled to avoid division blow-ups for tiny-mass exotic configs.
+    const safeCoupled = Math.max(coupled, 0.1);
+
+    return {
+        massRatio: r,
+        jumpV0Scale: 1 / Math.sqrt(safeCoupled),
+        groundAccelScale: 1 / safeCoupled,
+        landingDipScale: safeCoupled,
+        exertionRiseScale: safeCoupled,
+    };
+}

package/src/engine/control/first-person/pose/FirstPersonPose.d.ts

@@ -4,6 +4,12 @@ export namespace FirstPersonActionState {
     let Airborne: number;
     let Landing: number;
 }
+export namespace FirstPersonLocomotionMode {
+    let Idle: number;
+    let Walk: number;
+    let Sprint: number;
+    let Crouch: number;
+}
 export class FirstPersonPose {
     /**
      * World-space body root.
@@ -49,15 +55,39 @@ export class FirstPersonPose {
      */
     locomotionStrafe: number;
     /**
-     * See {@link FirstPersonActionState}.
+     * Kinetic vertical state. See {@link FirstPersonActionState}.
      * @type {number}
      */
     actionState: number;
+    /**
+     * Horizontal locomotion intent mode. See {@link FirstPersonLocomotionMode}.
+     * @type {number}
+     */
+    locomotionMode: number;
     /**
      * [0..1] interpolation between standing and fully-crouched pose.
+     * Legacy field — pinned to (height − eyeHeight)/(height − crouchHeight),
+     * so a body in Prone reads ≥ 1.0 (saturated). Use {@link postureAmount}
+     * if the animator needs to distinguish Crouch / Prone / Hang.
      * @type {number}
      */
     crouchAmount: number;
+    /**
+     * Current body shape. Picks which animation track the rig should
+     * blend toward — Stand / Crouch / Prone / Hang. See
+     * {@link FirstPersonPosture}.
+     * @type {number}
+     */
+    posture: number;
+    /**
+     * [0..1] blend weight from Stand toward the current {@link posture}.
+     * 0 = fully standing (postures hold-frame is the standing rig);
+     * 1 = fully in the posture's target shape. Computed from eye-height
+     * relative to the posture's target height, so the value transitions
+     * smoothly with the same spring the camera uses.
+     * @type {number}
+     */
+    postureAmount: number;
     /**
      * Same as headPitchRad, surfaced separately for IK consumers that only
      * need the aim axis.

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

@@ -1 +1 @@
-{"version":3,"file":"FirstPersonPose.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/pose/FirstPersonPose.js"],"names":[],"mappings":";;;;;;AAoBA;IACI;;;OAGG;IACH,cAFU,OAAO,CAEY;IAE7B;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;;OAKG;IACH,YAFU,MAAM,CAED;IAEf;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;;OAKG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;;OAGG;IACH,aAFU,MAAM,CAE8B;IAE9C;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,UAFU,MAAM,CAEH;CAChB;oBA1FmB,kCAAkC"}
+{"version":3,"file":"FirstPersonPose.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/pose/FirstPersonPose.js"],"names":[],"mappings":";;;;;;;;;;;;AAuCA;IACI;;;OAGG;IACH,cAFU,OAAO,CAEY;IAE7B;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;;OAKG;IACH,YAFU,MAAM,CAED;IAEf;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;;OAKG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;;OAGG;IACH,aAFU,MAAM,CAE8B;IAE9C;;;OAGG;IACH,gBAFU,MAAM,CAEgC;IAEhD;;;;;;OAMG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;;OAKG;IACH,SAFU,MAAM,CAEmB;IAEnC;;;;;;;OAOG;IACH,eAFU,MAAM,CAEE;IAElB;;;;OAIG;IACH,UAFU,MAAM,CAEH;CAChB;oBAxImB,kCAAkC"}

package/src/engine/control/first-person/pose/FirstPersonPose.js

@@ -1,4 +1,5 @@
 import Vector3 from "../../../../core/geom/Vector3.js";
+import { FirstPersonPosture } from "./FirstPersonPosture.js";
 
 /**
  * Read-only outputs intended for a downstream skeleton system to consume.
@@ -8,14 +9,32 @@ import Vector3 from "../../../../core/geom/Vector3.js";
  * internal state representations change later. A future first-person arms
  * rig, third-person body rig, and network-replicated remote rig should all
  * be able to drive themselves from these channels alone.
- *
+ */
+
+/**
+ * Vertical (kinetic) state — "what is the body doing in 3D space right now".
+ * Independent of {@link FirstPersonLocomotionMode}; the player can be
+ * Airborne while sprinting, Anticipating from a crouch, etc.
  * @readonly enum
  */
 export const FirstPersonActionState = {
     Grounded: 0,
     Anticipating: 1, // squashing down before jump impulse
     Airborne: 2,
-    Landing: 3
+    Landing: 3,
+};
+
+/**
+ * Horizontal (intent-driven) locomotion mode. Drives the blend tree for the
+ * skeletal rig's locomotion layer. Orthogonal to {@link FirstPersonActionState}
+ * — a Sprint-mode player who jumps is `(Sprint, Airborne)` until they land.
+ * @readonly enum
+ */
+export const FirstPersonLocomotionMode = {
+    Idle: 0,
+    Walk: 1,
+    Sprint: 2,
+    Crouch: 3,
 };
 
 export class FirstPersonPose {
@@ -71,17 +90,44 @@ export class FirstPersonPose {
     locomotionStrafe = 0;
 
     /**
-     * See {@link FirstPersonActionState}.
+     * Kinetic vertical state. See {@link FirstPersonActionState}.
      * @type {number}
      */
     actionState = FirstPersonActionState.Grounded;
 
+    /**
+     * Horizontal locomotion intent mode. See {@link FirstPersonLocomotionMode}.
+     * @type {number}
+     */
+    locomotionMode = FirstPersonLocomotionMode.Idle;
+
     /**
      * [0..1] interpolation between standing and fully-crouched pose.
+     * Legacy field — pinned to (height − eyeHeight)/(height − crouchHeight),
+     * so a body in Prone reads ≥ 1.0 (saturated). Use {@link postureAmount}
+     * if the animator needs to distinguish Crouch / Prone / Hang.
      * @type {number}
      */
     crouchAmount = 0;
 
+    /**
+     * Current body shape. Picks which animation track the rig should
+     * blend toward — Stand / Crouch / Prone / Hang. See
+     * {@link FirstPersonPosture}.
+     * @type {number}
+     */
+    posture = FirstPersonPosture.Stand;
+
+    /**
+     * [0..1] blend weight from Stand toward the current {@link posture}.
+     * 0 = fully standing (postures hold-frame is the standing rig);
+     * 1 = fully in the posture's target shape. Computed from eye-height
+     * relative to the posture's target height, so the value transitions
+     * smoothly with the same spring the camera uses.
+     * @type {number}
+     */
+    postureAmount = 0;
+
     /**
      * Same as headPitchRad, surfaced separately for IK consumers that only
      * need the aim axis.

package/src/engine/control/first-person/pose/FirstPersonPosture.d.ts

@@ -0,0 +1,7 @@
+export namespace FirstPersonPosture {
+    let Stand: number;
+    let Crouch: number;
+    let Prone: number;
+    let Hang: number;
+}
+//# sourceMappingURL=FirstPersonPosture.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FirstPersonPosture.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/pose/FirstPersonPosture.js"],"names":[],"mappings":""}

package/src/engine/control/first-person/pose/FirstPersonPosture.js

@@ -0,0 +1,27 @@
+/**
+ * Body posture — discrete shape the body holds. Drives eye height and
+ * gait gating (stride / footstep / bob).
+ *
+ * The base controller computes posture from intent each tick (Stand vs.
+ * Crouch). Abilities own the posture while they're active and can force
+ * Prone (slide) or Hang (ledge-grab). When an ability releases, the
+ * next base tick re-derives posture from intent.
+ *
+ * Why a single enum field rather than override sentinels: a uniform
+ * channel that every consumer (eye-height spring, stride gate, future
+ * skeleton animator) reads from one place. Adding a new posture means
+ * adding one enum value + one mapping, not threading "is X overriding
+ * Y" sentinels through L2.
+ *
+ * @readonly enum
+ */
+export const FirstPersonPosture = {
+    /** Upright on both feet — the default. Strides normally. */
+    Stand: 0,
+    /** Knees bent, head dropped — feet still strike the ground. */
+    Crouch: 1,
+    /** Body horizontal — sliding or diving. No stride; eye near ground. */
+    Prone: 2,
+    /** Suspended from hands — hanging on a ledge. No stride. */
+    Hang: 3,
+};