@woosh/meep-engine 2.138.19 → 2.139.0

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

@@ -0,0 +1,133 @@
+import { AnimationCurve } from "../../../animation/curve/AnimationCurve.js";
+import { Keyframe } from "../../../animation/curve/Keyframe.js";
+import { DecisionPoint } from "./DecisionPoint.js";
+import { MasteryEvaluator } from "./MasteryEvaluator.js";
+
+/**
+ * Symmetric curve over breath phase ∈ [0, 1):
+ *   0.00 → neutral (mid-inhale-to-exhale transition)
+ *   0.25 → trough: inhaling (small penalty)
+ *   0.50 → neutral
+ *   0.75 → peak: exhaling (small bonus)
+ *
+ * Physically motivated. Power-output research (weightlifting, sports
+ * biomechanics) consistently finds that peak force output happens during
+ * controlled exhalation. Holding breath produces a brief assist but
+ * inhaling during exertion is measurably worse. Bonus magnitude > penalty
+ * magnitude per the project design rule (asymmetric in magnitude).
+ *
+ * The curve is parameterizable so the same evaluator can serve multiple
+ * roles: large peak/trough for "action" decisions (jump, slide, wall-
+ * jump), small peak/trough for "continuous" decisions (ground accel
+ * during running in-sync with breath).
+ */
+export function makeBreathRhythmCurve(peakBonus, troughPenalty) {
+    return AnimationCurve.from([
+        Keyframe.from(0.00, 1.0),
+        Keyframe.from(0.25, 1.0 - troughPenalty),
+        Keyframe.from(0.50, 1.0),
+        Keyframe.from(0.75, 1.0 + peakBonus),
+        Keyframe.from(1.00, 1.0),
+    ]);
+}
+
+/**
+ * Mastery evaluator: scales the queried quantity by breath-phase timing.
+ * Multi-decision-point — same instance fires on whatever decision points
+ * are configured. Two canonical use cases:
+ *
+ *   1. **Action evaluators** (jump, slide-start, wall-jump, mantle-exit):
+ *      Default magnitudes (+3% peak / −1% trough). Fires once per event;
+ *      players naturally hold or release breath when committing to an
+ *      action.
+ *
+ *   2. **Sustained-action evaluator** (ground accel during in-sync run):
+ *      Smaller magnitudes (+1.5% / −0.5%) and gated by exertion (only
+ *      meaningful when the player is actually breathing heavily; matches
+ *      the locomotor-respiratory-coupling principle — coupling-bonus
+ *      kicks in at high exertion).
+ *
+ * The "smallest bonus in the system" rule applies here: this evaluator's
+ * defaults are tiny on purpose. Compounded across a long run with many
+ * actions, a breath-aware player gets a noticeable lift; a casual player
+ * who never notices the rhythm pays barely anything.
+ *
+ * Example usage:
+ *
+ *     // Action bonuses — fires on jump/slide-entry/wall-jump
+ *     controller.mastery.add(new BreathRhythmEvaluator());
+ *
+ *     // Speed bonus during sustained heavy breathing
+ *     controller.mastery.add(new BreathRhythmEvaluator({
+ *         decisionPoints: [DecisionPoint.GroundAccel],
+ *         peakBonus: 0.015,
+ *         troughPenalty: 0.005,
+ *         requireExertionAbove: 0.3,
+ *     }));
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BreathRhythmEvaluator extends MasteryEvaluator {
+    /**
+     * @param {object} [opts]
+     * @param {number[]} [opts.decisionPoints]  Defaults to action points
+     *   (jump, slide entry, wall-jump). Pass [GroundAccel] for the
+     *   "running in sync" speed bonus.
+     * @param {number} [opts.peakBonus]  Default 0.03 = +3% at exhale.
+     * @param {number} [opts.troughPenalty]  Default 0.01 = −1% at inhale.
+     * @param {number} [opts.requireExertionAbove]  Below this exertion
+     *   level (default 0) the evaluator returns identity. Use ~0.3 for
+     *   "only when breathing heavily" semantics.
+     */
+    constructor({
+        decisionPoints,
+        peakBonus = 0.03,
+        troughPenalty = 0.01,
+        requireExertionAbove = 0.0,
+    } = {}) {
+        super();
+        this.name = "BreathRhythm";
+
+        /**
+         * Set of decision points this evaluator answers. Default: the
+         * three classic "action" points.
+         * @type {Set<number>}
+         */
+        this.decisionPoints = new Set(decisionPoints || [
+            DecisionPoint.JumpImpulse,
+            DecisionPoint.SlideEntryVelocity,
+            DecisionPoint.WallJumpImpulse,
+        ]);
+
+        /** @type {number} */
+        this.peakBonus = peakBonus;
+        /** @type {number} */
+        this.troughPenalty = troughPenalty;
+        /** @type {number} */
+        this.requireExertionAbove = requireExertionAbove;
+
+        /** Magnitude exponent — scales the deviation around 1.0. */
+        this.flatBoost = 1.0;
+
+        /** @private */
+        this._curve = makeBreathRhythmCurve(peakBonus, troughPenalty);
+    }
+
+    /**
+     * Rebuild the curve from current peakBonus/troughPenalty. Call after
+     * mutating those fields if you want the change to take effect.
+     */
+    rebuildCurve() {
+        this._curve = makeBreathRhythmCurve(this.peakBonus, this.troughPenalty);
+    }
+
+    evaluate(decisionPoint, controller, _runtime) {
+        if (!this.decisionPoints.has(decisionPoint)) return 1.0;
+        if (controller.state.exertion < this.requireExertionAbove) return 1.0;
+
+        const phase = controller.state.breathPhase;
+        const raw = this._curve.evaluate(phase);
+        return 1.0 + (raw - 1.0) * this.flatBoost;
+    }
+}

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

@@ -0,0 +1,10 @@
+export namespace DecisionPoint {
+    let JumpImpulse: number;
+    let GroundAccel: number;
+    let SlideEntryVelocity: number;
+    let WallJumpImpulse: number;
+    let MantleExitSpeed: number;
+    let WallRunGravity: number;
+    let _Count: number;
+}
+//# sourceMappingURL=DecisionPoint.d.ts.map

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

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

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

@@ -0,0 +1,30 @@
+/**
+ * Discrete moments in the controller's update where mastery evaluators get
+ * to weigh in on a single numeric quantity.
+ *
+ * Each decision point has an associated meaning for its multiplier:
+ *   - `1.0` → no opinion (use base value)
+ *   - `> 1.0` → bonus (apply a percentage scaling up)
+ *   - `< 1.0` → penalty (apply a percentage scaling down)
+ *
+ * Evaluator contributions compose multiplicatively per decision point. See
+ * {@link MasterySet}.
+ *
+ * @readonly enum
+ */
+export const DecisionPoint = {
+    /** Multiplier applied to jump initial vertical velocity at impulse fire. */
+    JumpImpulse: 0,
+    /** Multiplier applied to ground acceleration each fixed step. */
+    GroundAccel: 1,
+    /** Multiplier applied to slide-entry velocity preservation. */
+    SlideEntryVelocity: 2,
+    /** Multiplier applied to wall-jump impulse magnitude. */
+    WallJumpImpulse: 3,
+    /** Multiplier applied to mantle exit horizontal speed. */
+    MantleExitSpeed: 4,
+    /** Multiplier applied to wall-run effective gravity (lower → longer hang). */
+    WallRunGravity: 5,
+    /** Sentinel — total count; useful for fixed-size arrays keyed by point. */
+    _Count: 6,
+};

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

@@ -0,0 +1,61 @@
+/**
+ * Default symmetric foot-asymmetry curve. Input is signed alignment
+ * ∈ [-1, +1]:
+ *   +1 = optimal (turn direction matches the standing-foot's push-off side)
+ *    0 = no turn, or no relevant standing foot
+ *   −1 = anti-optimal (turning AWAY from the push-off direction)
+ *
+ * Asymmetric magnitude per the design rule: +5% peak bonus vs −2% trough.
+ */
+export function makeDefaultFootAsymmetryTurnCurve(): AnimationCurve;
+/**
+ * Mastery evaluator: ground acceleration is modulated by which foot is
+ * standing relative to which way you're turning.
+ *
+ * Physically motivated: when you turn while running, you push off the
+ * grounded foot to redirect momentum. The most powerful push-off comes
+ * from the LEFT foot when turning right, and the RIGHT foot when
+ * turning left. (Think of how runners plant on the outside leg before
+ * cutting in the opposite direction.) Players who time their turns to
+ * align with the right foot's swing/stance phase carry more momentum
+ * through the turn.
+ *
+ * The bonus is small (max ~5%) by design — it's mastery, not magic.
+ * Compounded over a long turn under sprint, it accumulates into
+ * meaningfully more distance covered.
+ *
+ * Engineering note: we read `runtime.yawRateRadPerSec` (computed during
+ * look consumption) rather than recomputing from yaw deltas. That keeps
+ * the evaluator simple and avoids assumptions about controller internals.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FootAsymmetryTurnEvaluator extends MasteryEvaluator {
+    /**
+     * Alignment ∈ [-1, +1] → multiplier curve. Symmetric in behaviour
+     * (both sides exist) and asymmetric in magnitude (bonus side
+     * larger than penalty side).
+     * @type {AnimationCurve}
+     */
+    curve: AnimationCurve;
+    /**
+     * Exponent applied to (curve - 1.0). Scales overall magnitude
+     * while preserving symmetry around 1.0. Default 1.0 = use curve
+     * as authored.
+     * @type {number}
+     */
+    flatBoost: number;
+    /**
+     * Yaw rate magnitude (rad/s) at which alignment saturates to ±1.
+     * Slow turns produce weaker alignment; fast turns saturate. ~1.5
+     * rad/s ≈ 86°/s — a brisk but not-flicky turn. Sub-second
+     * 180° turns saturate.
+     * @type {number}
+     */
+    saturationYawRate: number;
+    evaluate(decisionPoint: any, controller: any, runtime: any): number;
+}
+import { AnimationCurve } from "../../../animation/curve/AnimationCurve.js";
+import { MasteryEvaluator } from "./MasteryEvaluator.js";
+//# sourceMappingURL=FootAsymmetryTurnEvaluator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FootAsymmetryTurnEvaluator.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/mastery/FootAsymmetryTurnEvaluator.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AACH,oEAMC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAKQ;;;;;OAKG;IACH,OAFU,cAAc,CAEwB;IAEhD;;;;;OAKG;IACH,WAFU,MAAM,CAEI;IAEpB;;;;;;OAMG;IACH,mBAFU,MAAM,CAEY;IAGhC,oEA8BC;CACJ;+BA3G8B,4CAA4C;iCAG1C,uBAAuB"}

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

@@ -0,0 +1,109 @@
+import { clamp } from "../../../../core/math/clamp.js";
+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 foot-asymmetry curve. Input is signed alignment
+ * ∈ [-1, +1]:
+ *   +1 = optimal (turn direction matches the standing-foot's push-off side)
+ *    0 = no turn, or no relevant standing foot
+ *   −1 = anti-optimal (turning AWAY from the push-off direction)
+ *
+ * Asymmetric magnitude per the design rule: +5% peak bonus vs −2% trough.
+ */
+export function makeDefaultFootAsymmetryTurnCurve() {
+    return AnimationCurve.from([
+        Keyframe.from(-1.0, 0.98),  // anti-aligned: −2% accel
+        Keyframe.from(0.0, 1.00),
+        Keyframe.from(1.0, 1.05),   // aligned: +5% accel
+    ]);
+}
+
+/**
+ * Mastery evaluator: ground acceleration is modulated by which foot is
+ * standing relative to which way you're turning.
+ *
+ * Physically motivated: when you turn while running, you push off the
+ * grounded foot to redirect momentum. The most powerful push-off comes
+ * from the LEFT foot when turning right, and the RIGHT foot when
+ * turning left. (Think of how runners plant on the outside leg before
+ * cutting in the opposite direction.) Players who time their turns to
+ * align with the right foot's swing/stance phase carry more momentum
+ * through the turn.
+ *
+ * The bonus is small (max ~5%) by design — it's mastery, not magic.
+ * Compounded over a long turn under sprint, it accumulates into
+ * meaningfully more distance covered.
+ *
+ * Engineering note: we read `runtime.yawRateRadPerSec` (computed during
+ * look consumption) rather than recomputing from yaw deltas. That keeps
+ * the evaluator simple and avoids assumptions about controller internals.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FootAsymmetryTurnEvaluator extends MasteryEvaluator {
+    constructor() {
+        super();
+        this.name = "FootAsymmetryTurn";
+
+        /**
+         * Alignment ∈ [-1, +1] → multiplier curve. Symmetric in behaviour
+         * (both sides exist) and asymmetric in magnitude (bonus side
+         * larger than penalty side).
+         * @type {AnimationCurve}
+         */
+        this.curve = makeDefaultFootAsymmetryTurnCurve();
+
+        /**
+         * Exponent applied to (curve - 1.0). Scales overall magnitude
+         * while preserving symmetry around 1.0. Default 1.0 = use curve
+         * as authored.
+         * @type {number}
+         */
+        this.flatBoost = 1.0;
+
+        /**
+         * Yaw rate magnitude (rad/s) at which alignment saturates to ±1.
+         * Slow turns produce weaker alignment; fast turns saturate. ~1.5
+         * rad/s ≈ 86°/s — a brisk but not-flicky turn. Sub-second
+         * 180° turns saturate.
+         * @type {number}
+         */
+        this.saturationYawRate = 1.5;
+    }
+
+    evaluate(decisionPoint, controller, runtime) {
+        if (decisionPoint !== DecisionPoint.GroundAccel) return 1.0;
+        // Only meaningful when grounded and actually moving.
+        if (!controller.state.grounded) return 1.0;
+        if (controller.state.speed < 0.5) return 1.0;
+
+        const yawRate = runtime.yawRateRadPerSec;
+        if (!yawRate || Math.abs(yawRate) < 1e-4) return 1.0; // not turning
+
+        // Sign convention: in our engine, yawRate < 0 means turning RIGHT
+        // (mouse-right decreases bodyYaw). Encode turn direction as +1
+        // for right, -1 for left.
+        const turnSign = yawRate < 0 ? 1 : -1;
+
+        // Optimal-foot encoding: standing on the LEFT foot is good for
+        // RIGHT turns (you push off the left to swing right); standing on
+        // the RIGHT foot is good for LEFT turns.
+        const footSign = runtime.standingFoot === "L" ? 1 : -1;
+
+        // Yaw intensity: 0 (no turn) to 1 (saturated). Smooth ramp.
+        const intensity = clamp(
+            Math.abs(yawRate) / Math.max(this.saturationYawRate, 1e-4),
+            0, 1,
+        );
+
+        // Alignment ∈ [-1, +1].  Aligned when turnSign × footSign > 0.
+        const alignment = turnSign * footSign * intensity;
+
+        const raw = this.curve.evaluate(alignment);
+        return 1.0 + (raw - 1.0) * this.flatBoost;
+    }
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Base class for mastery evaluators. Each evaluator observes the
+ * controller's state at a given {@link DecisionPoint} and returns a
+ * multiplier:
+ *
+ *   `1.0`       → no opinion (identity)
+ *   `> 1.0`     → bonus (e.g. 1.10 = +10%)
+ *   `< 1.0`     → penalty (e.g. 0.95 = −5%)
+ *
+ * Multiple evaluators registered against the same point compose
+ * multiplicatively. The composition pattern is intentionally symmetric:
+ * the same curve drives both bonus and penalty regions — well-timed
+ * inputs land in the bonus half, poorly-timed in the penalty half. Per the
+ * project design convention the bonus side is bigger than the penalty
+ * side (e.g. ±5% penalty for ~+12% bonus) — that's handled at the
+ * curve-authoring level by asymmetric peak/trough heights.
+ *
+ * Subclasses override {@link evaluate}. They typically own an
+ * `AnimationCurve` and a `flatBoost` exponent — see
+ * `StrideTimingJumpEvaluator` for the canonical pattern.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class MasteryEvaluator {
+    /**
+     * Human-readable identifier for telemetry (mastery score keying,
+     * debugging overlays). Subclasses should set a stable string.
+     * @type {string}
+     */
+    name: string;
+    /**
+     * @param {number} decisionPoint  one of {@link DecisionPoint}
+     * @param {*} controller          the FirstPersonPlayerController
+     * @param {*} runtime             per-entity runtime state
+     * @returns {number}              multiplier; 1.0 = no opinion
+     */
+    evaluate(decisionPoint: number, controller: any, runtime: any): number;
+}
+//# sourceMappingURL=MasteryEvaluator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MasteryEvaluator.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/mastery/MasteryEvaluator.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAEQ;;;;OAIG;IACH,MAFU,MAAM,CAEc;IAGlC;;;;;OAKG;IAEH,wBANW,MAAM,kCAGJ,MAAM,CAKlB;CACJ"}

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

@@ -0,0 +1,45 @@
+/**
+ * Base class for mastery evaluators. Each evaluator observes the
+ * controller's state at a given {@link DecisionPoint} and returns a
+ * multiplier:
+ *
+ *   `1.0`       → no opinion (identity)
+ *   `> 1.0`     → bonus (e.g. 1.10 = +10%)
+ *   `< 1.0`     → penalty (e.g. 0.95 = −5%)
+ *
+ * Multiple evaluators registered against the same point compose
+ * multiplicatively. The composition pattern is intentionally symmetric:
+ * the same curve drives both bonus and penalty regions — well-timed
+ * inputs land in the bonus half, poorly-timed in the penalty half. Per the
+ * project design convention the bonus side is bigger than the penalty
+ * side (e.g. ±5% penalty for ~+12% bonus) — that's handled at the
+ * curve-authoring level by asymmetric peak/trough heights.
+ *
+ * Subclasses override {@link evaluate}. They typically own an
+ * `AnimationCurve` and a `flatBoost` exponent — see
+ * `StrideTimingJumpEvaluator` for the canonical pattern.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class MasteryEvaluator {
+    constructor() {
+        /**
+         * Human-readable identifier for telemetry (mastery score keying,
+         * debugging overlays). Subclasses should set a stable string.
+         * @type {string}
+         */
+        this.name = "MasteryEvaluator";
+    }
+
+    /**
+     * @param {number} decisionPoint  one of {@link DecisionPoint}
+     * @param {*} controller          the FirstPersonPlayerController
+     * @param {*} runtime             per-entity runtime state
+     * @returns {number}              multiplier; 1.0 = no opinion
+     */
+    // eslint-disable-next-line no-unused-vars
+    evaluate(decisionPoint, controller, runtime) {
+        return 1.0;
+    }
+}

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

@@ -0,0 +1,68 @@
+/**
+ * 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?: number);
+    /**
+     * 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}
+     */
+    halfLife: number;
+    /**
+     * EMA of (multiplier − 1.0) across ALL evaluator contributions.
+     * Useful as a single-number "how skilled has the player been
+     * recently" indicator.
+     * @type {number}
+     */
+    aggregate: number;
+    /**
+     * 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[]}
+     */
+    byPoint: number[];
+    /**
+     * 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: number, multiplier: number): void;
+    /**
+     * 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: number): void;
+    /**
+     * Reset to neutral. Useful on respawn / scene change.
+     */
+    reset(): void;
+}
+//# sourceMappingURL=MasteryScore.d.ts.map

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