@woosh/meep-engine 2.138.20 → 2.140.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"MasteryScore.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/mastery/MasteryScore.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IACI;;OAEG;IACH,uBAFW,MAAM,EA0BhB;IAvBG;;;;OAIG;IACH,UAFU,MAAM,CAEQ;IAExB;;;;;OAKG;IACH,WAFU,MAAM,CAEE;IAElB;;;;;;OAMG;IACH,SAFU,MAAM,EAAE,CAEoC;IAG1D;;;;;;;OAOG;IACH,sBAHW,MAAM,cACN,MAAM,QAYhB;IAED;;;;;OAKG;IACH,UAFW,MAAM,QAUhB;IAED;;OAEG;IACH,cAKC;CACJ"}

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

@@ -0,0 +1,100 @@
+import { DecisionPoint } from "./DecisionPoint.js";
+
+const LN2 = Math.log(2);
+
+/**
+ * Exponential moving average of mastery contributions. Provides a per-
+ * decision-point and a global aggregate score, both centred at 0:
+ *
+ *   `score === 0` → on average, evaluators returned 1.0 (neutral)
+ *   `score > 0`   → trending bonus (player is consistently timing well)
+ *   `score < 0`   → trending penalty (player is consistently mistiming)
+ *
+ * The controller does NOT consume this score itself. It's a side-channel
+ * for downstream systems (HUDs, post-match summaries, training-mode
+ * coaching, achievement triggers, leaderboards) to expose mastery
+ * progress however they see fit, without forcing any visual treatment on
+ * the controller.
+ *
+ * Samples are added by {@link MasterySet} as evaluators fire. Time-based
+ * decay (so old samples wash out) is applied via {@link tick}.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class MasteryScore {
+    /**
+     * @param {number} [halfLife] seconds for any sample's contribution to halve
+     */
+    constructor(halfLife = 8.0) {
+        /**
+         * Time-half-life of the EMA. A score sample 1×halfLife ago counts ½
+         * as much as a fresh one. Tune for "how recent should mastery feel".
+         * @type {number}
+         */
+        this.halfLife = halfLife;
+
+        /**
+         * EMA of (multiplier − 1.0) across ALL evaluator contributions.
+         * Useful as a single-number "how skilled has the player been
+         * recently" indicator.
+         * @type {number}
+         */
+        this.aggregate = 0;
+
+        /**
+         * EMA per decision point — same metric, sliced by which interaction
+         * the contribution came from. Index space matches DecisionPoint.
+         * Useful for telemetry like "you're nailing jump timing but poor at
+         * slide initiation".
+         * @type {number[]}
+         */
+        this.byPoint = new Array(DecisionPoint._Count).fill(0);
+    }
+
+    /**
+     * Record a contribution from an evaluator. Call once per evaluator per
+     * decision-point evaluation. The multiplier is converted to a signed
+     * deviation from neutral (1.0) for EMA accumulation.
+     *
+     * @param {number} decisionPoint
+     * @param {number} multiplier  raw evaluator output (1.0 = neutral)
+     */
+    record(decisionPoint, multiplier) {
+        const dev = multiplier - 1.0;
+        // Light blend on each sample; the per-tick time decay (apply()) is
+        // what actually carries the EMA character.
+        const blend = 0.1;
+        this.aggregate = (1 - blend) * this.aggregate + blend * dev;
+        const pi = decisionPoint;
+        if (pi >= 0 && pi < this.byPoint.length) {
+            this.byPoint[pi] = (1 - blend) * this.byPoint[pi] + blend * dev;
+        }
+    }
+
+    /**
+     * Apply time-based decay so stale samples wash out. Call once per
+     * fixed step; the system handles this for you.
+     *
+     * @param {number} dt seconds
+     */
+    decay(dt) {
+        if (this.halfLife <= 0 || dt <= 0) return;
+        // Multiplicative decay toward 0 with the given half-life.
+        const alpha = Math.exp(-LN2 * dt / this.halfLife);
+        this.aggregate *= alpha;
+        for (let i = 0; i < this.byPoint.length; i++) {
+            this.byPoint[i] *= alpha;
+        }
+    }
+
+    /**
+     * Reset to neutral. Useful on respawn / scene change.
+     */
+    reset() {
+        this.aggregate = 0;
+        for (let i = 0; i < this.byPoint.length; i++) {
+            this.byPoint[i] = 0;
+        }
+    }
+}

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

@@ -0,0 +1,60 @@
+/**
+ * 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 {
+    /**
+     * Registered evaluators, in insertion order.
+     * @type {MasteryEvaluator[]}
+     */
+    evaluators: MasteryEvaluator[];
+    /**
+     * Telemetry EMA. The controller doesn't consume it; downstream
+     * systems read it for player-facing mastery feedback.
+     * @type {MasteryScore}
+     */
+    score: MasteryScore;
+    /**
+     * Add an evaluator. Order does not affect the final result
+     * (multiplication is commutative).
+     * @param {MasteryEvaluator} evaluator
+     */
+    add(evaluator: MasteryEvaluator): void;
+    /**
+     * Remove an evaluator if present.
+     * @param {MasteryEvaluator} evaluator
+     */
+    remove(evaluator: MasteryEvaluator): void;
+    /**
+     * 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: number, controller: any, runtime: any): number;
+    /**
+     * Advance the score's time-based decay. Call once per fixed step.
+     * @param {number} dt
+     */
+    tick(dt: number): void;
+}
+import { MasteryScore } from "./MasteryScore.js";
+//# sourceMappingURL=MasterySet.d.ts.map

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