@woosh/meep-engine 2.138.20 → 2.139.0

package/src/engine/control/first-person/mastery/MasterySet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MasterySet.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/mastery/MasterySet.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH;IAEQ;;;OAGG;IACH,YAFU,kBAAkB,CAER;IAEpB;;;;OAIG;IACH,OAFU,YAAY,CAES;IAGnC;;;;OAIG;IACH,uCAEC;IAED;;;OAGG;IACH,0CAGC;IAED;;;;;;;;;OASG;IACH,wBALW,MAAM,kCAGJ,MAAM,CAclB;IAED;;;OAGG;IACH,SAFW,MAAM,QAIhB;CACJ;6BArF4B,mBAAmB"}

package/src/engine/control/first-person/mastery/MasterySet.js

@@ -0,0 +1,86 @@
+import { MasteryScore } from "./MasteryScore.js";
+
+/**
+ * Aggregates {@link MasteryEvaluator} instances and exposes a single
+ * `evaluate(decisionPoint, ...)` entry point that composes all evaluators
+ * for that point multiplicatively.
+ *
+ * Identity behaviour: with zero evaluators registered, every query returns
+ * `1.0`, leaving the base controller behaviour untouched. This is the
+ * default state — mastery is opt-in.
+ *
+ * Composition: contributions multiply, NOT sum. So a +10% and a +5% give
+ * +15.5% (1.10 × 1.05 = 1.155). And a +10% with a −5% gives +4.5% (1.10
+ * × 0.95 = 1.045). Mistiming partially offsets bonuses from other
+ * evaluators — exactly what we want for honest "your timing matters
+ * everywhere" feel.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class MasterySet {
+    constructor() {
+        /**
+         * Registered evaluators, in insertion order.
+         * @type {MasteryEvaluator[]}
+         */
+        this.evaluators = [];
+
+        /**
+         * Telemetry EMA. The controller doesn't consume it; downstream
+         * systems read it for player-facing mastery feedback.
+         * @type {MasteryScore}
+         */
+        this.score = new MasteryScore();
+    }
+
+    /**
+     * Add an evaluator. Order does not affect the final result
+     * (multiplication is commutative).
+     * @param {MasteryEvaluator} evaluator
+     */
+    add(evaluator) {
+        this.evaluators.push(evaluator);
+    }
+
+    /**
+     * Remove an evaluator if present.
+     * @param {MasteryEvaluator} evaluator
+     */
+    remove(evaluator) {
+        const i = this.evaluators.indexOf(evaluator);
+        if (i !== -1) this.evaluators.splice(i, 1);
+    }
+
+    /**
+     * Compose all registered evaluators against `decisionPoint`. Each
+     * evaluator's contribution is recorded into the score for telemetry,
+     * then multiplied into the running product.
+     *
+     * @param {number} decisionPoint
+     * @param {*} controller
+     * @param {*} runtime
+     * @returns {number} composed multiplier; 1.0 if no evaluators care
+     */
+    evaluate(decisionPoint, controller, runtime) {
+        let product = 1.0;
+        const n = this.evaluators.length;
+        for (let i = 0; i < n; i++) {
+            const v = this.evaluators[i].evaluate(decisionPoint, controller, runtime);
+            // Defensive: ignore evaluators returning non-finite or non-positive
+            // values (would corrupt downstream math). Treat as identity.
+            if (!Number.isFinite(v) || v <= 0) continue;
+            product *= v;
+            this.score.record(decisionPoint, v);
+        }
+        return product;
+    }
+
+    /**
+     * Advance the score's time-based decay. Call once per fixed step.
+     * @param {number} dt
+     */
+    tick(dt) {
+        this.score.decay(dt);
+    }
+}

package/src/engine/control/first-person/mastery/SlideInitiationTimingEvaluator.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Default symmetric stride-timing curve for slide entry. Peaks at the
+ * midstance phases (≈0.25 R-mid, ≈0.75 L-mid) — committing to the slide
+ * at midstance lets you convert your push-off momentum into the slide's
+ * forward velocity cleanly. Troughs near footfall transitions (≈0, ≈0.5)
+ * where the leg's loading-response decelerates the body and a slide
+ * commitment loses energy to the foot-ground transition.
+ *
+ * Designed shape: smaller range than the jump curve. Slide is a forgiving
+ * mechanic — the bonus is at most ~+6%, the penalty at most ~−3%. Both
+ * are well below the JumpImpulse curve's swing (peak +12%, trough −4%)
+ * because slide timing is harder to feel deliberately than jump timing.
+ *
+ * @returns {AnimationCurve}
+ */
+export function makeDefaultSlideInitiationTimingCurve(): AnimationCurve;
+/**
+ * Mastery evaluator: slide-entry velocity preservation scales with
+ * stride-phase timing at the moment of crouch-press. Committing at
+ * midstance lets the body convert push-off momentum directly into the
+ * slide's launch velocity. Committing at footfall means the leg is
+ * absorbing the body's downward momentum just as the slide starts, and
+ * the transition loses energy.
+ *
+ * Physically motivated: real-world athletes diving into a slide at the
+ * right gait moment land flatter and keep more momentum than at the
+ * wrong one. The range is tight (≈±5%) because slide is a forgiving
+ * action — the design rule "slide is forgiving — small skill ceiling"
+ * (DESIGN_EXTENSIONS Phase 7).
+ *
+ * Symmetry: behaves on both sides (bonus and penalty), asymmetric in
+ * magnitude (bonus larger). Bonus side is the design's "reward the
+ * timing" half; penalty side discourages mashing crouch arbitrarily.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class SlideInitiationTimingEvaluator extends MasteryEvaluator {
+    /**
+     * Curve mapping stridePhase ∈ [0..1) → multiplier on the slide-
+     * entry velocity preservation. Symmetric in behaviour, asymmetric
+     * in magnitude (peak farther from 1.0 than trough).
+     * @type {AnimationCurve}
+     */
+    curve: AnimationCurve;
+    /**
+     * Exponent applied to (curve − 1.0) to scale overall response.
+     * Convention shared with {@link StrideTimingJumpEvaluator}:
+     * tune deviation, not curve directly, so symmetry around 1.0 is
+     * preserved.
+     * @type {number}
+     */
+    flatBoost: number;
+    evaluate(decisionPoint: any, controller: any, _runtime: any): number;
+}
+import { AnimationCurve } from "../../../animation/curve/AnimationCurve.js";
+import { MasteryEvaluator } from "./MasteryEvaluator.js";
+//# sourceMappingURL=SlideInitiationTimingEvaluator.d.ts.map

package/src/engine/control/first-person/mastery/SlideInitiationTimingEvaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SlideInitiationTimingEvaluator.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/mastery/SlideInitiationTimingEvaluator.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,yDAFa,cAAc,CAS1B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAKQ;;;;;OAKG;IACH,OAFU,cAAc,CAE4B;IAEpD;;;;;;OAMG;IACH,WAFU,MAAM,CAEI;IAGxB,qEAQC;CACJ;+BAlF8B,4CAA4C;iCAG1C,uBAAuB"}

package/src/engine/control/first-person/mastery/SlideInitiationTimingEvaluator.js

@@ -0,0 +1,83 @@
+import { AnimationCurve } from "../../../animation/curve/AnimationCurve.js";
+import { Keyframe } from "../../../animation/curve/Keyframe.js";
+import { DecisionPoint } from "./DecisionPoint.js";
+import { MasteryEvaluator } from "./MasteryEvaluator.js";
+
+/**
+ * Default symmetric stride-timing curve for slide entry. Peaks at the
+ * midstance phases (≈0.25 R-mid, ≈0.75 L-mid) — committing to the slide
+ * at midstance lets you convert your push-off momentum into the slide's
+ * forward velocity cleanly. Troughs near footfall transitions (≈0, ≈0.5)
+ * where the leg's loading-response decelerates the body and a slide
+ * commitment loses energy to the foot-ground transition.
+ *
+ * Designed shape: smaller range than the jump curve. Slide is a forgiving
+ * mechanic — the bonus is at most ~+6%, the penalty at most ~−3%. Both
+ * are well below the JumpImpulse curve's swing (peak +12%, trough −4%)
+ * because slide timing is harder to feel deliberately than jump timing.
+ *
+ * @returns {AnimationCurve}
+ */
+export function makeDefaultSlideInitiationTimingCurve() {
+    return AnimationCurve.from([
+        Keyframe.from(0.00, 0.97), // R-foot footfall — slight penalty
+        Keyframe.from(0.25, 1.06), // R-foot midstance — peak commitment
+        Keyframe.from(0.50, 0.97), // L-foot footfall — slight penalty
+        Keyframe.from(0.75, 1.06), // L-foot midstance — peak commitment
+    ]);
+}
+
+/**
+ * Mastery evaluator: slide-entry velocity preservation scales with
+ * stride-phase timing at the moment of crouch-press. Committing at
+ * midstance lets the body convert push-off momentum directly into the
+ * slide's launch velocity. Committing at footfall means the leg is
+ * absorbing the body's downward momentum just as the slide starts, and
+ * the transition loses energy.
+ *
+ * Physically motivated: real-world athletes diving into a slide at the
+ * right gait moment land flatter and keep more momentum than at the
+ * wrong one. The range is tight (≈±5%) because slide is a forgiving
+ * action — the design rule "slide is forgiving — small skill ceiling"
+ * (DESIGN_EXTENSIONS Phase 7).
+ *
+ * Symmetry: behaves on both sides (bonus and penalty), asymmetric in
+ * magnitude (bonus larger). Bonus side is the design's "reward the
+ * timing" half; penalty side discourages mashing crouch arbitrarily.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class SlideInitiationTimingEvaluator extends MasteryEvaluator {
+    constructor() {
+        super();
+        this.name = "SlideInitiationTiming";
+
+        /**
+         * Curve mapping stridePhase ∈ [0..1) → multiplier on the slide-
+         * entry velocity preservation. Symmetric in behaviour, asymmetric
+         * in magnitude (peak farther from 1.0 than trough).
+         * @type {AnimationCurve}
+         */
+        this.curve = makeDefaultSlideInitiationTimingCurve();
+
+        /**
+         * Exponent applied to (curve − 1.0) to scale overall response.
+         * Convention shared with {@link StrideTimingJumpEvaluator}:
+         * tune deviation, not curve directly, so symmetry around 1.0 is
+         * preserved.
+         * @type {number}
+         */
+        this.flatBoost = 1.0;
+    }
+
+    evaluate(decisionPoint, controller, _runtime) {
+        if (decisionPoint !== DecisionPoint.SlideEntryVelocity) return 1.0;
+
+        const phase = controller.state.stridePhase;
+        const raw = this.curve.evaluate(phase);
+
+        // Scale the deviation around 1.0 by flatBoost so symmetry holds.
+        return 1.0 + (raw - 1.0) * this.flatBoost;
+    }
+}

package/src/engine/control/first-person/mastery/StrideTimingJumpEvaluator.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Default symmetric stride-timing curve for the jump-impulse decision
+ * point. Peaks at the midstance phases (≈0.25 R-mid, ≈0.75 L-mid) and
+ * troughs near the footfall transitions (≈0, ≈0.5).
+ *
+ * Curve is asymmetric in magnitude per the project rule: bonus side is
+ * larger than penalty side. Default peak = +12%, default trough = −4%.
+ * The curve is keyed at the four phase critical points; the engine's
+ * tangent-interpolation gives smooth motion between them.
+ *
+ * @returns {AnimationCurve}
+ */
+export function makeDefaultStrideTimingJumpCurve(): AnimationCurve;
+/**
+ * Mastery evaluator: jump impulse magnitude scales with stride-phase
+ * timing. Pressing jump at midstance (legs straight, body high in the
+ * gait cycle, push-off power available) gives a small bonus. Pressing
+ * during loading response (just after foot strike, body's downward
+ * momentum still being absorbed) gives a small penalty.
+ *
+ * Physically motivated: real athletes get more vertical from a jump
+ * timed to ankle/knee extension than from one timed to the loading phase
+ * of the gait cycle. The bonus is small (~12% peak) because real
+ * difference is also small — this is mastery, not exploit-power.
+ *
+ * Optional foot-asymmetry: if the player has a configured
+ * `dominantFoot`, that foot's midstance peak is slightly higher
+ * (representing the natural handedness asymmetry — right-dominant
+ * humans push slightly harder off the right leg). Off by default.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class StrideTimingJumpEvaluator extends MasteryEvaluator {
+    /**
+     * Curve mapping stridePhase ∈ [0..1) → multiplier. Authored to be
+     * symmetric in *behaviour* (bonus and penalty regions both
+     * present) and asymmetric in *magnitude* (peak > 1 + ε; trough <
+     * 1 − ε, with bonus larger than penalty).
+     * @type {AnimationCurve}
+     */
+    curve: AnimationCurve;
+    /**
+     * Exponent applied to (curve − 1.0). Scales the OVERALL response
+     * magnitude without re-authoring the curve. Default 1.0 = use
+     * curve as authored. 0.5 = halve all effects. 1.5 = 50% larger.
+     * Convention: scale the deviation, not the curve directly, so
+     * the symmetry around 1.0 is preserved.
+     * @type {number}
+     */
+    flatBoost: number;
+    /**
+     * Optional foot-asymmetry: extra bonus when the dominant foot is
+     * the standing one at jump time. Set to "R" or "L" to enable.
+     * `null` (default) = no asymmetry.
+     * @type {"R"|"L"|null}
+     */
+    dominantFoot: "R" | "L" | null;
+    /**
+     * Magnitude of the foot-asymmetry contribution (additive to the
+     * multiplier). Default 0.03 = up to +3% on dominant-foot jumps.
+     * @type {number}
+     */
+    dominantFootBonus: number;
+    evaluate(decisionPoint: any, controller: any, runtime: any): number;
+}
+import { AnimationCurve } from "../../../animation/curve/AnimationCurve.js";
+import { MasteryEvaluator } from "./MasteryEvaluator.js";
+//# sourceMappingURL=StrideTimingJumpEvaluator.d.ts.map

package/src/engine/control/first-person/mastery/StrideTimingJumpEvaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StrideTimingJumpEvaluator.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/mastery/StrideTimingJumpEvaluator.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,oDAFa,cAAc,CAS1B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAKQ;;;;;;OAMG;IACH,OAFU,cAAc,CAEuB;IAE/C;;;;;;;OAOG;IACH,WAFU,MAAM,CAEI;IAEpB;;;;;OAKG;IACH,cAFU,GAAG,GAAC,GAAG,GAAC,IAAI,CAEE;IAExB;;;;OAIG;IACH,mBAFU,MAAM,CAEa;IAGjC,oEAqBC;CACJ;+BA5G8B,4CAA4C;iCAG1C,uBAAuB"}

package/src/engine/control/first-person/mastery/StrideTimingJumpEvaluator.js

@@ -0,0 +1,109 @@
+import { AnimationCurve } from "../../../animation/curve/AnimationCurve.js";
+import { Keyframe } from "../../../animation/curve/Keyframe.js";
+import { DecisionPoint } from "./DecisionPoint.js";
+import { MasteryEvaluator } from "./MasteryEvaluator.js";
+
+/**
+ * Default symmetric stride-timing curve for the jump-impulse decision
+ * point. Peaks at the midstance phases (≈0.25 R-mid, ≈0.75 L-mid) and
+ * troughs near the footfall transitions (≈0, ≈0.5).
+ *
+ * Curve is asymmetric in magnitude per the project rule: bonus side is
+ * larger than penalty side. Default peak = +12%, default trough = −4%.
+ * The curve is keyed at the four phase critical points; the engine's
+ * tangent-interpolation gives smooth motion between them.
+ *
+ * @returns {AnimationCurve}
+ */
+export function makeDefaultStrideTimingJumpCurve() {
+    return AnimationCurve.from([
+        Keyframe.from(0.00, 0.96),  // R-foot footfall — slight penalty (just touched down)
+        Keyframe.from(0.25, 1.12),  // R-foot midstance — peak push-off power
+        Keyframe.from(0.50, 0.96),  // L-foot footfall — slight penalty
+        Keyframe.from(0.75, 1.12),  // L-foot midstance — peak push-off power
+    ]);
+}
+
+/**
+ * Mastery evaluator: jump impulse magnitude scales with stride-phase
+ * timing. Pressing jump at midstance (legs straight, body high in the
+ * gait cycle, push-off power available) gives a small bonus. Pressing
+ * during loading response (just after foot strike, body's downward
+ * momentum still being absorbed) gives a small penalty.
+ *
+ * Physically motivated: real athletes get more vertical from a jump
+ * timed to ankle/knee extension than from one timed to the loading phase
+ * of the gait cycle. The bonus is small (~12% peak) because real
+ * difference is also small — this is mastery, not exploit-power.
+ *
+ * Optional foot-asymmetry: if the player has a configured
+ * `dominantFoot`, that foot's midstance peak is slightly higher
+ * (representing the natural handedness asymmetry — right-dominant
+ * humans push slightly harder off the right leg). Off by default.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class StrideTimingJumpEvaluator extends MasteryEvaluator {
+    constructor() {
+        super();
+        this.name = "StrideTimingJump";
+
+        /**
+         * Curve mapping stridePhase ∈ [0..1) → multiplier. Authored to be
+         * symmetric in *behaviour* (bonus and penalty regions both
+         * present) and asymmetric in *magnitude* (peak > 1 + ε; trough <
+         * 1 − ε, with bonus larger than penalty).
+         * @type {AnimationCurve}
+         */
+        this.curve = makeDefaultStrideTimingJumpCurve();
+
+        /**
+         * Exponent applied to (curve − 1.0). Scales the OVERALL response
+         * magnitude without re-authoring the curve. Default 1.0 = use
+         * curve as authored. 0.5 = halve all effects. 1.5 = 50% larger.
+         * Convention: scale the deviation, not the curve directly, so
+         * the symmetry around 1.0 is preserved.
+         * @type {number}
+         */
+        this.flatBoost = 1.0;
+
+        /**
+         * Optional foot-asymmetry: extra bonus when the dominant foot is
+         * the standing one at jump time. Set to "R" or "L" to enable.
+         * `null` (default) = no asymmetry.
+         * @type {"R"|"L"|null}
+         */
+        this.dominantFoot = null;
+
+        /**
+         * Magnitude of the foot-asymmetry contribution (additive to the
+         * multiplier). Default 0.03 = up to +3% on dominant-foot jumps.
+         * @type {number}
+         */
+        this.dominantFootBonus = 0.03;
+    }
+
+    evaluate(decisionPoint, controller, runtime) {
+        if (decisionPoint !== DecisionPoint.JumpImpulse) return 1.0;
+
+        const phase = controller.state.stridePhase;
+        const raw = this.curve.evaluate(phase);
+
+        // Scale the deviation around 1.0 by flatBoost so symmetry holds:
+        //   raw < 1 stays < 1, raw > 1 stays > 1, magnitude scales linearly.
+        let multiplier = 1.0 + (raw - 1.0) * this.flatBoost;
+
+        // Foot-asymmetry bonus only adds in the BONUS region (raw > 1),
+        // never amplifies the penalty. Keeps "favouring your dominant
+        // foot" as a strictly-additive nicety rather than a tax on the
+        // off-foot.
+        if (this.dominantFoot !== null
+            && runtime.standingFoot === this.dominantFoot
+            && raw > 1.0) {
+            multiplier *= 1.0 + this.dominantFootBonus;
+        }
+
+        return multiplier;
+    }
+}

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

@@ -0,0 +1,56 @@
+/**
+ * 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?: number, velocity?: number);
+    value: number;
+    velocity: number;
+    /**
+     * 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: number, halfLife: number, zeta: number, dt: number): void;
+    /**
+     * 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: number): void;
+    /**
+     * Instantaneously place the spring at a value with zero velocity. Use
+     * when initializing or hard-resetting (e.g. teleport).
+     *
+     * @param {number} [value]
+     */
+    settle(value?: number): void;
+    /**
+     * 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: number): void;
+}
+//# sourceMappingURL=Spring.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Spring.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/math/Spring.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH;IACI;;;OAGG;IACH,oBAHW,MAAM,aACN,MAAM,EAKhB;IAFG,cAAkB;IAClB,iBAAwB;IAG5B;;;;;;;;OAQG;IACH,eALW,MAAM,YACN,MAAM,QACN,MAAM,MACN,MAAM,QAIhB;IAED;;;;;OAKG;IACH,cAFW,MAAM,QAIhB;IAED;;;;;OAKG;IACH,eAFW,MAAM,QAKhB;IAED;;;;;;OAMG;IACH,gBAFW,MAAM,QAIhB;CACJ"}

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"}