@woosh/meep-engine 2.139.0 → 2.141.0

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

@@ -1,211 +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 { 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;
+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;

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

@@ -40,8 +40,27 @@ export class FirstPersonPlayerControllerConfig {
         crouchSpeed: number;
         /** [0..1] how much intent influences velocity while airborne. */
         airControl: number;
-        /** m/s^2 horizontal acceleration toward intent on ground. */
-        groundAccel: number;
+        /**
+         * Half-life (seconds) for the mono-exponential approach to top
+         * sprint speed on the ground. The controller's ground-accel
+         * model is Hill-based:
+         *     v(t) = v_max · (1 − e^(−t / τ))
+         * with τ = halfLife / ln 2. At each tick the velocity halves
+         * the remaining gap to `targetSpeed` every `halfLife` seconds.
+         *
+         * Default `0.116 s` gives ~95 % of `sprintSpeed` reached in
+         * 500 ms — the Apex Legends / Titanfall / modern CoD ramp
+         * window. The curve is naturally non-uniform: roughly 45 %
+         * of top speed in the first 100 ms, then the last 5 % takes
+         * 300 ms — so a quick tap-and-go still feels snappy while
+         * follow-up moves (slide, sprint-jump) require committed
+         * sprint time to be at top speed.
+         *
+         * Literature: Hill 1927 / Furusawa-Hill 1928 (force-velocity
+         * curve, original analytical formulation); Morin & Samozino
+         * 2016 (modern sprint profiling using the same mono-exp fit).
+         */
+        groundAccelHalfLife: number;
         /** m/s^2 horizontal deceleration toward 0 when intent is zero. */
         groundDecel: number;
         /** m/s^2 horizontal acceleration while airborne. */
@@ -191,8 +210,21 @@ export class FirstPersonPlayerControllerConfig {
      * on the controller; unused if Slide is not in use.
      */
     slide: {
-        /** Required horizontal speed to start a slide. Below this, crouch+
-         *  sprint just transitions to a normal crouched walk. */
+        /**
+         * Required horizontal speed to start a slide. Below this,
+         * crouch + sprint just transitions to a normal crouched walk.
+         *
+         * The default — `7.5 m/s` — sits between walkSpeed (4.5) and
+         * sprintSpeed (9), at ~83 % of sprint. Earning the slide is
+         * enforced by the ground-accel model: with
+         * `groundAccelHalfLife = 0.116 s`, reaching this threshold
+         * from standstill takes ~300 ms of sustained sprint — well
+         * past a normal reaction window. Walking off a ledge or
+         * accelerating down a slope into a slide is explicitly
+         * supported: anything that brings the player's horizontal
+         * speed above this threshold lets crouch engage a slide.
+         * (Following Apex Legends' velocity-only gate at 200 hu/s.)
+         */
         minEntrySpeed: number;
         /** Auto-exit threshold — slide ends when speed drops below this. */
         endSpeed: number;
@@ -441,8 +473,27 @@ export class FirstPersonPlayerControllerConfig {
             crouchSpeed: number;
             /** [0..1] how much intent influences velocity while airborne. */
             airControl: number;
-            /** m/s^2 horizontal acceleration toward intent on ground. */
-            groundAccel: number;
+            /**
+             * Half-life (seconds) for the mono-exponential approach to top
+             * sprint speed on the ground. The controller's ground-accel
+             * model is Hill-based:
+             *     v(t) = v_max · (1 − e^(−t / τ))
+             * with τ = halfLife / ln 2. At each tick the velocity halves
+             * the remaining gap to `targetSpeed` every `halfLife` seconds.
+             *
+             * Default `0.116 s` gives ~95 % of `sprintSpeed` reached in
+             * 500 ms — the Apex Legends / Titanfall / modern CoD ramp
+             * window. The curve is naturally non-uniform: roughly 45 %
+             * of top speed in the first 100 ms, then the last 5 % takes
+             * 300 ms — so a quick tap-and-go still feels snappy while
+             * follow-up moves (slide, sprint-jump) require committed
+             * sprint time to be at top speed.
+             *
+             * Literature: Hill 1927 / Furusawa-Hill 1928 (force-velocity
+             * curve, original analytical formulation); Morin & Samozino
+             * 2016 (modern sprint profiling using the same mono-exp fit).
+             */
+            groundAccelHalfLife: number;
             /** m/s^2 horizontal deceleration toward 0 when intent is zero. */
             groundDecel: number;
             /** m/s^2 horizontal acceleration while airborne. */
@@ -561,8 +612,21 @@ export class FirstPersonPlayerControllerConfig {
             nearWallMaxDistance: number;
         };
         slide: {
-            /** Required horizontal speed to start a slide. Below this, crouch+
-             *  sprint just transitions to a normal crouched walk. */
+            /**
+             * Required horizontal speed to start a slide. Below this,
+             * crouch + sprint just transitions to a normal crouched walk.
+             *
+             * The default — `7.5 m/s` — sits between walkSpeed (4.5) and
+             * sprintSpeed (9), at ~83 % of sprint. Earning the slide is
+             * enforced by the ground-accel model: with
+             * `groundAccelHalfLife = 0.116 s`, reaching this threshold
+             * from standstill takes ~300 ms of sustained sprint — well
+             * past a normal reaction window. Walking off a ledge or
+             * accelerating down a slope into a slide is explicitly
+             * supported: anything that brings the player's horizontal
+             * speed above this threshold lets crouch engage a slide.
+             * (Following Apex Legends' velocity-only gate at 200 hu/s.)
+             */
             minEntrySpeed: number;
             /** Auto-exit threshold — slide ends when speed drops below this. */
             endSpeed: number;

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

@@ -1 +1 @@
-{"version":3,"file":"FirstPersonPlayerControllerConfig.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerControllerConfig.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"FirstPersonPlayerControllerConfig.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerControllerConfig.js"],"names":[],"mappings":"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"}

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

@@ -45,8 +45,27 @@ export class FirstPersonPlayerControllerConfig {
         crouchSpeed: 2.2,
         /** [0..1] how much intent influences velocity while airborne. */
         airControl: 0.5,
-        /** m/s^2 horizontal acceleration toward intent on ground. */
-        groundAccel: 60,        // ~6g start-up — near-instant feel
+        /**
+         * Half-life (seconds) for the mono-exponential approach to top
+         * sprint speed on the ground. The controller's ground-accel
+         * model is Hill-based:
+         *     v(t) = v_max · (1 − e^(−t / τ))
+         * with τ = halfLife / ln 2. At each tick the velocity halves
+         * the remaining gap to `targetSpeed` every `halfLife` seconds.
+         *
+         * Default `0.116 s` gives ~95 % of `sprintSpeed` reached in
+         * 500 ms — the Apex Legends / Titanfall / modern CoD ramp
+         * window. The curve is naturally non-uniform: roughly 45 %
+         * of top speed in the first 100 ms, then the last 5 % takes
+         * 300 ms — so a quick tap-and-go still feels snappy while
+         * follow-up moves (slide, sprint-jump) require committed
+         * sprint time to be at top speed.
+         *
+         * Literature: Hill 1927 / Furusawa-Hill 1928 (force-velocity
+         * curve, original analytical formulation); Morin & Samozino
+         * 2016 (modern sprint profiling using the same mono-exp fit).
+         */
+        groundAccelHalfLife: 0.116,
         /** m/s^2 horizontal deceleration toward 0 when intent is zero. */
         groundDecel: 75,        // crisp stops, no skating
         /** m/s^2 horizontal acceleration while airborne. */
@@ -204,9 +223,22 @@ export class FirstPersonPlayerControllerConfig {
      * on the controller; unused if Slide is not in use.
      */
     slide = {
-        /** Required horizontal speed to start a slide. Below this, crouch+
-         *  sprint just transitions to a normal crouched walk. */
-        minEntrySpeed: 5.0,
+        /**
+         * Required horizontal speed to start a slide. Below this,
+         * crouch + sprint just transitions to a normal crouched walk.
+         *
+         * The default — `7.5 m/s` — sits between walkSpeed (4.5) and
+         * sprintSpeed (9), at ~83 % of sprint. Earning the slide is
+         * enforced by the ground-accel model: with
+         * `groundAccelHalfLife = 0.116 s`, reaching this threshold
+         * from standstill takes ~300 ms of sustained sprint — well
+         * past a normal reaction window. Walking off a ledge or
+         * accelerating down a slope into a slide is explicitly
+         * supported: anything that brings the player's horizontal
+         * speed above this threshold lets crouch engage a slide.
+         * (Following Apex Legends' velocity-only gate at 200 hu/s.)
+         */
+        minEntrySpeed: 7.5,
         /** Auto-exit threshold — slide ends when speed drops below this. */
         endSpeed: 2.0,
         /** Horizontal deceleration (m/s²) while sliding. Lower than the