@woosh/meep-engine 2.138.20 → 2.140.0

package/src/engine/control/first-person/FirstPersonPlayerController.d.ts

@@ -16,6 +16,21 @@ export class FirstPersonPlayerController {
     state: FirstPersonState;
     pose: FirstPersonPose;
     signals: FirstPersonSignals;
+    /**
+     * Mastery layer — registry of {@link MasteryEvaluator}s and the
+     * telemetry score they feed. Designers register evaluators here;
+     * the controller's system queries them at each decision point.
+     * Empty by default (no mastery effects unless the game adds them).
+     * @type {MasterySet}
+     */
+    mastery: MasterySet;
+    /**
+     * Movement abilities (wall-run, mantle, slide, etc.). Empty by
+     * default — base locomotion is unchanged unless the game adds
+     * abilities here.
+     * @type {AbilitySet}
+     */
+    abilities: AbilitySet;
     /**
      * ID of the entity carrying the eye Transform + Camera. Created by
      * the system on link if -1. Held as a plain number rather than
@@ -29,17 +44,22 @@ export class FirstPersonPlayerController {
             body: {
                 height: number;
                 crouchHeight: number;
+                proneHeight: number;
                 radius: number;
                 mass: number;
+                referenceMass: number;
+                massCouplingStrength: number;
             };
             motion: {
-                walkSpeed: number; /** Hold state — true while jump button is held. @type {boolean} */
+                walkSpeed: number;
                 sprintSpeed: number;
                 crouchSpeed: number;
                 airControl: number;
-                groundAccel: number;
+                groundAccelHalfLife: number;
                 groundDecel: number;
                 airAccel: number;
+                backwardSpeedFactor: number;
+                backwardAccelFactor: number;
             };
             jump: {
                 anticipation: {
@@ -48,6 +68,17 @@ export class FirstPersonPlayerController {
                 };
                 peakHeight: number;
                 timeToApex: number;
+                /**
+                 * First-person camera + body controller. See DESIGN.md (sibling file) for
+                 * the goals, layered architecture, and tuning rationale.
+                 *
+                 * Lifecycle: only `config` is serialized. `intent`, `state`, `pose`,
+                 * `signals`, and `eyeEntity` are transient — rebuilt by the system on
+                 * link.
+                 *
+                 * @author Alex Goldring
+                 * @copyright Company Named Limited (c) 2026
+                 */
                 coyoteTime: number;
                 bufferTime: number;
                 fallGravityMult: number;
@@ -57,7 +88,7 @@ export class FirstPersonPlayerController {
                 recovery: {
                     spring: {
                         halfLife: number;
-                        zeta: number; /** {verticalSpeed:number, kind:"soft"|"hard"} */
+                        zeta: number;
                     };
                     dipPerVy: number;
                     dipMax: number;
@@ -69,6 +100,41 @@ export class FirstPersonPlayerController {
                 transitionTime: number;
                 mode: string;
             };
+            ledgeGrab: {
+                hangOffsetY: number;
+                hangOffsetForward: number;
+                exertionRiseRate: number;
+                minAirborneTime: number;
+                mantleUpUpFactor: number;
+            };
+            mantle: {
+                minHeight: number;
+                maxHeight: number;
+                duration: number;
+                forwardOffsetOnLand: number;
+            };
+            wallRun: {
+                minSpeed: number;
+                minAirborneTime: number; /**
+                 * @param {FirstPersonPlayerController} other
+                 */
+                maxDuration: number;
+                gravityFactor: number;
+                cameraRollDeg: number;
+            };
+            wallJump: {
+                outwardImpulse: number;
+                upFactor: number;
+                nearWallMaxDistance: number;
+            };
+            slide: {
+                minEntrySpeed: number;
+                endSpeed: number;
+                friction: number;
+                startupWindow: number;
+                slideJumpUpFactor: number;
+                entryImpactVelocity: number;
+            };
             bob: {
                 stepFreqAtWalk: number;
                 stepFreqExp: number;
@@ -77,6 +143,14 @@ export class FirstPersonPlayerController {
                 ampMassScale: number;
                 rollAtWalkDeg: number;
                 minStepSpeed: number;
+                intensityHalfLife: number;
+                impactSpringHalfLife: number;
+                impactSpringZeta: number;
+                impactKickMultiplier: number;
+                backwardVerticalAmpFactor: number;
+                backwardLateralAmpFactor: number;
+                backwardRollFactor: number;
+                leanCouplingFactor: number;
             };
             breath: {
                 rateRestHz: number;
@@ -86,13 +160,21 @@ export class FirstPersonPlayerController {
                 pitchAmpRestDeg: number;
                 pitchAmpMaxDeg: number;
                 noiseAmount: number;
+                locomotorCouplingMax: number;
+                couplingMinStrideFreqHz: number;
             };
             exertion: {
                 sprintRiseRate: number;
-                jumpRise: number;
                 idleDecayRate: number;
+                jumpRise: number;
+                crouchEnterRise: number;
+                landImpulsePerVy: number;
+                landImpulseMax: number;
                 rateDecayHalfLife: number;
                 ampDecayHalfLife: number;
+                bobLateralBoostAtMax: number;
+                headDroopAtMaxDeg: number;
+                headDroopHalfLife: number;
             };
             lean: {
                 spring: {
@@ -101,6 +183,10 @@ export class FirstPersonPlayerController {
                 };
                 enabled: boolean;
                 maxRollDeg: number;
+                lookLeanEnabled: boolean;
+                lookLeanDegPerRadPerSec: number;
+                lookLeanYawRateClamp: number;
+                crouchLookLeanFactor: number;
             };
             fov: {
                 base: number;
@@ -111,9 +197,12 @@ export class FirstPersonPlayerController {
             look: {
                 pitchMinDeg: number;
                 pitchMaxDeg: number;
-                invertY: boolean; /**
-                 * @param {FirstPersonPlayerController} other
-                 */
+                invertY: boolean;
+            };
+            posture: {
+                sprintForwardPitchDeg: number;
+                sprintForwardPitchHalfLife: number;
+                sprintForwardShiftM: number;
             };
             gravity: {
                 magnitude: number;
@@ -131,6 +220,7 @@ export class FirstPersonPlayerController {
 }
 export namespace FirstPersonPlayerController {
     export { FirstPersonActionState as ActionState };
+    export { FirstPersonLocomotionMode as LocomotionMode };
 }
 import { FirstPersonPlayerControllerConfig } from "./FirstPersonPlayerControllerConfig.js";
 /**
@@ -171,8 +261,8 @@ declare class FirstPersonState {
     speed: number;
     /** [0..1] vs sprint speed — drives bob amp and FOV kick. */
     speedNormalized: number;
-    /** "Idle" | "Walk" | "Sprint" | "Crouch" | "Air" */
-    moveMode: string;
+    /** Horizontal locomotion mode. See {@link FirstPersonLocomotionMode}. */
+    locomotionMode: number;
     verticalSpeed: number;
     airborneTime: number;
     fallDistance: number;
@@ -194,6 +284,15 @@ declare class FirstPersonState {
     crouchBlocked: boolean;
     /** True while in crouch pose (independent of intent — see crouchBlocked). */
     crouchActive: boolean;
+    /**
+     * Body posture. Set each tick by whichever layer owns motion: the
+     * base derives Stand/Crouch from intent; an active ability can
+     * force Prone (slide) or Hang (ledge-grab). See
+     * {@link FirstPersonPosture}. Drives eye-height target and gait
+     * gating (stride, footsteps, bob).
+     * @type {number}
+     */
+    posture: number;
     leanRollRad: number;
 }
 import { FirstPersonPose } from "./pose/FirstPersonPose.js";
@@ -220,8 +319,15 @@ declare class FirstPersonSignals {
     onBreathIn: Signal<any, any, any, any, any, any, any, any>;
     /** {amplitude:number, rateHz:number} fired at peak exhale (phase 0.75). */
     onBreathOut: Signal<any, any, any, any, any, any, any, any>;
+    /** {ledgeHeight:number} — fired when LedgeGrab activates. */
+    onLedgeGrab: Signal<any, any, any, any, any, any, any, any>;
+    /** {reason:"mantle-up"|"drop"|"slip"|"shuffle-off"} */
+    onLedgeRelease: Signal<any, any, any, any, any, any, any, any>;
 }
+import { MasterySet } from "./mastery/MasterySet.js";
+import { AbilitySet } from "./abilities/AbilitySet.js";
 import { FirstPersonActionState } from "./pose/FirstPersonPose.js";
+import { FirstPersonLocomotionMode } from "./pose/FirstPersonPose.js";
 import Vector2 from "../../../core/geom/Vector2.js";
 import Vector3 from "../../../core/geom/Vector3.js";
 import Signal from "../../../core/events/signal/Signal.js";

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

@@ -1 +1 @@
-{"version":3,"file":"FirstPersonPlayerController.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerController.js"],"names":[],"mappings":"AA6GA;;;;;;;;;;GAUG;AACH;IACI,wBAAgD;IAG5C,0CAAqD;IACrD,0BAAqC;IACrC,wBAAmC;IACnC,sBAAiC;IACjC,4BAAuC;IAEvC;;;;;;OAMG;IACH,WAFU,MAAM,CAEG;IAGvB;;;;;;;;;mCAlHA,mEAAmE;;;;;;;;;;;;;;;;;;;;;;;;sCAuEnE,iDAAiD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kCAqDjD;;mBAEG;;;;;;MAVF;IAED,0BAIC;IAED;;OAEG;IACH,YAFW,2BAA2B,QAKrC;IAED,qCAIC;IAED,4BAGC;IAED,eAGC;CACJ;;;;kDA1KiD,wCAAwC;AAG1F;;;;;;;;GAQG;AACH;IACI,oEAAoE;IACpE,MADyD,OAAO,CACvC;IAEzB;;;;OAIG;IACH,MAFU,OAAO,CAEQ;IAEzB,mEAAmE;IACnE,MADwD,OAAO,CAClD;IAEb,0EAA0E;IAC1E,QAD+D,OAAO,CACvD;IAEf,qEAAqE;IACrE,QAD0D,OAAO,CAClD;CAClB;AAED;;;GAGG;AACH;IACI,kBAAgB;IAChB,0BAAsB;IAEtB,4EAA4E;IAC5E,sBAAoC;IACpC,gBAAkB;IAElB,cAAU;IACV,4DAA4D;IAC5D,wBAAoB;IACpB,oDAAoD;IACpD,iBAAkB;IAElB,sBAAkB;IAClB,qBAAiB;IACjB,qBAAiB;IAEjB,4BAAwB;IACxB,4BAA2B;IAC3B,2BAA0B;IAC1B,2EAA2E;IAC3E,qBAAoB;IAEpB,iBAAa;IACb,oBAAgB;IAChB,qBAAiB;IACjB,yBAAqB;IAErB,oBAAgB;IAChB,kBAAc;IACd,kDAAkD;IAClD,iBAAa;IAEb,kBAAiB;IAEjB,+EAA+E;IAC/E,uBAAsB;IACtB,6EAA6E;IAC7E,sBAAqB;IAErB,oBAAgB;CACnB;gCA9EuD,2BAA2B;AAgFnF;;;GAGG;AACH;IACI,uDAAuD;IACvD,2DAA0B;IAC1B,yEAAyE;IACzE,4DAA2B;IAC3B,kBAAkB;IAClB,2DAA0B;IAC1B,6BAA6B;IAC7B,8DAA6B;IAC7B,iDAAiD;IACjD,uDAAsB;IACtB,8DAA6B;IAC7B,6DAA4B;IAC5B,8DAA6B;IAC7B,6DAA4B;IAC5B,2EAA2E;IAC3E,2DAA0B;IAC1B,2EAA2E;IAC3E,4DAA2B;CAC9B;uCAvGuD,2BAA2B;oBAH/D,+BAA+B;oBAC/B,+BAA+B;mBAFhC,uCAAuC"}
+{"version":3,"file":"FirstPersonPlayerController.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerController.js"],"names":[],"mappings":"AA8HA;;;;;;;;;;GAUG;AACH;IACI,wBAAgD;IAG5C,0CAAqD;IACrD,0BAAqC;IACrC,wBAAmC;IACnC,sBAAiC;IACjC,4BAAuC;IAEvC;;;;;;OAMG;IACH,SAFU,UAAU,CAEW;IAE/B;;;;;OAKG;IACH,WAFU,UAAU,CAEa;IAEjC;;;;;;OAMG;IACH,WAFU,MAAM,CAEG;IAGvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gBAhDJ;;;;;;;;;;mBAUG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yCAgDC;;mBAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAVF;IAED,0BAIC;IAED;;OAEG;IACH,YAFW,2BAA2B,QAKrC;IAED,qCAIC;IAED,4BAGC;IAED,eAGC;CACJ;;;;;kDA3MiD,wCAAwC;AAK1F;;;;;;;;GAQG;AACH;IACI,oEAAoE;IACpE,MADyD,OAAO,CACvC;IAEzB;;;;OAIG;IACH,MAFU,OAAO,CAEQ;IAEzB,mEAAmE;IACnE,MADwD,OAAO,CAClD;IAEb,0EAA0E;IAC1E,QAD+D,OAAO,CACvD;IAEf,qEAAqE;IACrE,QAD0D,OAAO,CAClD;CAClB;AAED;;;GAGG;AACH;IACI,kBAAgB;IAChB,0BAAsB;IAEtB,4EAA4E;IAC5E,sBAAoC;IACpC,gBAAkB;IAElB,cAAU;IACV,4DAA4D;IAC5D,wBAAoB;IACpB,yEAAyE;IACzE,uBAAgD;IAEhD,sBAAkB;IAClB,qBAAiB;IACjB,qBAAiB;IAEjB,4BAAwB;IACxB,4BAA2B;IAC3B,2BAA0B;IAC1B,2EAA2E;IAC3E,qBAAoB;IAEpB,iBAAa;IACb,oBAAgB;IAChB,qBAAiB;IACjB,yBAAqB;IAErB,oBAAgB;IAChB,kBAAc;IACd,kDAAkD;IAClD,iBAAa;IAEb,kBAAiB;IAEjB,+EAA+E;IAC/E,uBAAsB;IACtB,6EAA6E;IAC7E,sBAAqB;IAErB;;;;;;;OAOG;IACH,SAFU,MAAM,CAEmB;IAEnC,oBAAgB;CACnB;gCAzFkF,2BAA2B;AA2F9G;;;GAGG;AACH;IACI,uDAAuD;IACvD,2DAA0B;IAC1B,yEAAyE;IACzE,4DAA2B;IAC3B,kBAAkB;IAClB,2DAA0B;IAC1B,6BAA6B;IAC7B,8DAA6B;IAC7B,iDAAiD;IACjD,uDAAsB;IACtB,8DAA6B;IAC7B,6DAA4B;IAC5B,8DAA6B;IAC7B,6DAA4B;IAC5B,2EAA2E;IAC3E,2DAA0B;IAC1B,2EAA2E;IAC3E,4DAA2B;IAC3B,6DAA6D;IAC7D,4DAA2B;IAC3B,uDAAuD;IACvD,+DAA8B;CACjC;2BAvH0B,yBAAyB;2BAFzB,2BAA2B;uCAG6B,2BAA2B;0CAA3B,2BAA2B;oBAL1F,+BAA+B;oBAC/B,+BAA+B;mBAFhC,uCAAuC"}

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

@@ -1,176 +1,211 @@
-import Signal from "../../../core/events/signal/Signal.js";
-import Vector2 from "../../../core/geom/Vector2.js";
-import Vector3 from "../../../core/geom/Vector3.js";
-import { FirstPersonPlayerControllerConfig } from "./FirstPersonPlayerControllerConfig.js";
-import { FirstPersonActionState, FirstPersonPose } from "./pose/FirstPersonPose.js";
-
-/**
- * Intent — what the player (or AI) wants the body to do. All fields are
- * latched ("hold-state") except `look`, which accumulates deltas between
- * fixed updates and is zeroed by the system on consume.
- *
- * The system performs its own edge detection on `jump` (and on `crouch`
- * when toggle-mode is configured). This is what guarantees a held jump
- * button does not produce repeated jumps.
- */
-class FirstPersonIntent {
-    /** [-1..1, -1..1] forward+/right+ in body-local. @type {Vector2} */
-    move = new Vector2(0, 0);
-
-    /**
-     * Accumulated look delta (radians). x = yaw, y = pitch. Consumed and
-     * zeroed by the system in fixedUpdate.
-     * @type {Vector2}
-     */
-    look = new Vector2(0, 0);
-
-    /** Hold state — true while jump button is held. @type {boolean} */
-    jump = false;
-
-    /** Hold state — meaning depends on config.crouch.mode. @type {boolean} */
-    crouch = false;
-
-    /** Hold state — true while sprint button is held. @type {boolean} */
-    sprint = false;
-}
-
-/**
- * Derived state — read-only outputs. Useful for HUDs, sound systems, AI
- * sensors that need to know "is the player crouched / sprinting / etc."
- */
-class FirstPersonState {
-    grounded = true;
-    timeSinceGrounded = 0;
-
-    /** Set by the physics layer (or the prototype's flat-ground integrator). */
-    groundNormal = new Vector3(0, 1, 0);
-    surfaceTag = null;
-
-    speed = 0;
-    /** [0..1] vs sprint speed — drives bob amp and FOV kick. */
-    speedNormalized = 0;
-    /** "Idle" | "Walk" | "Sprint" | "Crouch" | "Air" */
-    moveMode = "Idle";
-
-    verticalSpeed = 0;
-    airborneTime = 0;
-    fallDistance = 0;
-
-    jumpBufferRemaining = 0;
-    inJumpAnticipation = false;
-    isVariableJumpCut = false;
-    /** Set to true while jumping ascent until apex; gates the cut behavior. */
-    isAscending = false;
-
-    exertion = 0;
-    breathPhase = 0;
-    breathRateHz = 0;
-    breathAmplitudeM = 0;
-
-    stridePhase = 0;
-    stepCount = 0;
-    /** Which foot fires next: 0 = right, 1 = left. */
-    nextFoot = 0;
-
-    eyeHeight = 1.80;
-
-    /** Set true when crouch was released but a ceiling above prevents standing. */
-    crouchBlocked = false;
-    /** True while in crouch pose (independent of intent — see crouchBlocked). */
-    crouchActive = false;
-
-    leanRollRad = 0;
-}
-
-/**
- * Event surface. All signals are sent from fixedUpdate so listeners see
- * consistent state across the same simulation tick.
- */
-class FirstPersonSignals {
-    /** {side:"L"|"R", speed:number, surfaceTag:string?} */
-    onFootStep = new Signal();
-    /** {peakHeight:number} fired at impulse, after anticipation finishes. */
-    onJumpStart = new Signal();
-    /** No payload. */
-    onJumpApex = new Signal();
-    /** {reason:"jump"|"fall"} */
-    onLeaveGround = new Signal();
-    /** {verticalSpeed:number, kind:"soft"|"hard"} */
-    onLand = new Signal();
-    onCrouchEnter = new Signal();
-    onCrouchExit = new Signal();
-    onSprintStart = new Signal();
-    onSprintStop = new Signal();
-    /** {amplitude:number, rateHz:number} fired at peak inhale (phase 0.25). */
-    onBreathIn = new Signal();
-    /** {amplitude:number, rateHz:number} fired at peak exhale (phase 0.75). */
-    onBreathOut = new Signal();
-}
-
-/**
- * First-person camera + body controller. See DESIGN.md (sibling file) for
- * the goals, layered architecture, and tuning rationale.
- *
- * Lifecycle: only `config` is serialized. `intent`, `state`, `pose`,
- * `signals`, and `eyeEntity` are transient — rebuilt by the system on
- * link.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class FirstPersonPlayerController {
-    static typeName = "FirstPersonPlayerController";
-
-    constructor() {
-        this.config = new FirstPersonPlayerControllerConfig();
-        this.intent = new FirstPersonIntent();
-        this.state = new FirstPersonState();
-        this.pose = new FirstPersonPose();
-        this.signals = new FirstPersonSignals();
-
-        /**
-         * ID of the entity carrying the eye Transform + Camera. Created by
-         * the system on link if -1. Held as a plain number rather than
-         * EntityReference to keep serialization simple — the relationship
-         * is rebuilt on link anyway.
-         * @type {number}
-         */
-        this.eyeEntity = -1;
-    }
-
-    toJSON() {
-        return { config: this.config.toJSON() };
-    }
-
-    fromJSON(json) {
-        if (json && json.config) {
-            this.config.fromJSON(json.config);
-        }
-    }
-
-    /**
-     * @param {FirstPersonPlayerController} other
-     */
-    copy(other) {
-        this.config.copy(other.config);
-        // intent/state/pose/signals/eyeEntity are transient
-    }
-
-    clone() {
-        const c = new FirstPersonPlayerController();
-        c.copy(this);
-        return c;
-    }
-
-    equals(other) {
-        // config-only equality (the rest is runtime state)
-        return JSON.stringify(this.config.toJSON()) === JSON.stringify(other.config.toJSON());
-    }
-
-    hash() {
-        // hashing transient state is undesirable; the config is large; return 0
-        return 0;
-    }
-}
-
-FirstPersonPlayerController.ActionState = FirstPersonActionState;
+import Signal from "../../../core/events/signal/Signal.js";
+import Vector2 from "../../../core/geom/Vector2.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { AbilitySet } from "./abilities/AbilitySet.js";
+import { FirstPersonPlayerControllerConfig } from "./FirstPersonPlayerControllerConfig.js";
+import { MasterySet } from "./mastery/MasterySet.js";
+import { FirstPersonActionState, FirstPersonLocomotionMode, FirstPersonPose } from "./pose/FirstPersonPose.js";
+import { FirstPersonPosture } from "./pose/FirstPersonPosture.js";
+
+/**
+ * Intent — what the player (or AI) wants the body to do. All fields are
+ * latched ("hold-state") except `look`, which accumulates deltas between
+ * fixed updates and is zeroed by the system on consume.
+ *
+ * The system performs its own edge detection on `jump` (and on `crouch`
+ * when toggle-mode is configured). This is what guarantees a held jump
+ * button does not produce repeated jumps.
+ */
+class FirstPersonIntent {
+    /** [-1..1, -1..1] forward+/right+ in body-local. @type {Vector2} */
+    move = new Vector2(0, 0);
+
+    /**
+     * Accumulated look delta (radians). x = yaw, y = pitch. Consumed and
+     * zeroed by the system in fixedUpdate.
+     * @type {Vector2}
+     */
+    look = new Vector2(0, 0);
+
+    /** Hold state — true while jump button is held. @type {boolean} */
+    jump = false;
+
+    /** Hold state — meaning depends on config.crouch.mode. @type {boolean} */
+    crouch = false;
+
+    /** Hold state — true while sprint button is held. @type {boolean} */
+    sprint = false;
+}
+
+/**
+ * Derived state — read-only outputs. Useful for HUDs, sound systems, AI
+ * sensors that need to know "is the player crouched / sprinting / etc."
+ */
+class FirstPersonState {
+    grounded = true;
+    timeSinceGrounded = 0;
+
+    /** Set by the physics layer (or the prototype's flat-ground integrator). */
+    groundNormal = new Vector3(0, 1, 0);
+    surfaceTag = null;
+
+    speed = 0;
+    /** [0..1] vs sprint speed — drives bob amp and FOV kick. */
+    speedNormalized = 0;
+    /** Horizontal locomotion mode. See {@link FirstPersonLocomotionMode}. */
+    locomotionMode = FirstPersonLocomotionMode.Idle;
+
+    verticalSpeed = 0;
+    airborneTime = 0;
+    fallDistance = 0;
+
+    jumpBufferRemaining = 0;
+    inJumpAnticipation = false;
+    isVariableJumpCut = false;
+    /** Set to true while jumping ascent until apex; gates the cut behavior. */
+    isAscending = false;
+
+    exertion = 0;
+    breathPhase = 0;
+    breathRateHz = 0;
+    breathAmplitudeM = 0;
+
+    stridePhase = 0;
+    stepCount = 0;
+    /** Which foot fires next: 0 = right, 1 = left. */
+    nextFoot = 0;
+
+    eyeHeight = 1.80;
+
+    /** Set true when crouch was released but a ceiling above prevents standing. */
+    crouchBlocked = false;
+    /** True while in crouch pose (independent of intent — see crouchBlocked). */
+    crouchActive = false;
+
+    /**
+     * Body posture. Set each tick by whichever layer owns motion: the
+     * base derives Stand/Crouch from intent; an active ability can
+     * force Prone (slide) or Hang (ledge-grab). See
+     * {@link FirstPersonPosture}. Drives eye-height target and gait
+     * gating (stride, footsteps, bob).
+     * @type {number}
+     */
+    posture = FirstPersonPosture.Stand;
+
+    leanRollRad = 0;
+}
+
+/**
+ * Event surface. All signals are sent from fixedUpdate so listeners see
+ * consistent state across the same simulation tick.
+ */
+class FirstPersonSignals {
+    /** {side:"L"|"R", speed:number, surfaceTag:string?} */
+    onFootStep = new Signal();
+    /** {peakHeight:number} fired at impulse, after anticipation finishes. */
+    onJumpStart = new Signal();
+    /** No payload. */
+    onJumpApex = new Signal();
+    /** {reason:"jump"|"fall"} */
+    onLeaveGround = new Signal();
+    /** {verticalSpeed:number, kind:"soft"|"hard"} */
+    onLand = new Signal();
+    onCrouchEnter = new Signal();
+    onCrouchExit = new Signal();
+    onSprintStart = new Signal();
+    onSprintStop = new Signal();
+    /** {amplitude:number, rateHz:number} fired at peak inhale (phase 0.25). */
+    onBreathIn = new Signal();
+    /** {amplitude:number, rateHz:number} fired at peak exhale (phase 0.75). */
+    onBreathOut = new Signal();
+    /** {ledgeHeight:number} — fired when LedgeGrab activates. */
+    onLedgeGrab = new Signal();
+    /** {reason:"mantle-up"|"drop"|"slip"|"shuffle-off"} */
+    onLedgeRelease = new Signal();
+}
+
+/**
+ * First-person camera + body controller. See DESIGN.md (sibling file) for
+ * the goals, layered architecture, and tuning rationale.
+ *
+ * Lifecycle: only `config` is serialized. `intent`, `state`, `pose`,
+ * `signals`, and `eyeEntity` are transient — rebuilt by the system on
+ * link.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FirstPersonPlayerController {
+    static typeName = "FirstPersonPlayerController";
+
+    constructor() {
+        this.config = new FirstPersonPlayerControllerConfig();
+        this.intent = new FirstPersonIntent();
+        this.state = new FirstPersonState();
+        this.pose = new FirstPersonPose();
+        this.signals = new FirstPersonSignals();
+
+        /**
+         * Mastery layer — registry of {@link MasteryEvaluator}s and the
+         * telemetry score they feed. Designers register evaluators here;
+         * the controller's system queries them at each decision point.
+         * Empty by default (no mastery effects unless the game adds them).
+         * @type {MasterySet}
+         */
+        this.mastery = new MasterySet();
+
+        /**
+         * Movement abilities (wall-run, mantle, slide, etc.). Empty by
+         * default — base locomotion is unchanged unless the game adds
+         * abilities here.
+         * @type {AbilitySet}
+         */
+        this.abilities = new AbilitySet();
+
+        /**
+         * ID of the entity carrying the eye Transform + Camera. Created by
+         * the system on link if -1. Held as a plain number rather than
+         * EntityReference to keep serialization simple — the relationship
+         * is rebuilt on link anyway.
+         * @type {number}
+         */
+        this.eyeEntity = -1;
+    }
+
+    toJSON() {
+        return { config: this.config.toJSON() };
+    }
+
+    fromJSON(json) {
+        if (json && json.config) {
+            this.config.fromJSON(json.config);
+        }
+    }
+
+    /**
+     * @param {FirstPersonPlayerController} other
+     */
+    copy(other) {
+        this.config.copy(other.config);
+        // intent/state/pose/signals/eyeEntity are transient
+    }
+
+    clone() {
+        const c = new FirstPersonPlayerController();
+        c.copy(this);
+        return c;
+    }
+
+    equals(other) {
+        // config-only equality (the rest is runtime state)
+        return JSON.stringify(this.config.toJSON()) === JSON.stringify(other.config.toJSON());
+    }
+
+    hash() {
+        // hashing transient state is undesirable; the config is large; return 0
+        return 0;
+    }
+}
+
+FirstPersonPlayerController.ActionState = FirstPersonActionState;
+FirstPersonPlayerController.LocomotionMode = FirstPersonLocomotionMode;