@woosh/meep-engine 2.138.19 → 2.139.0

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

@@ -19,7 +19,7 @@
 export class FirstPersonPlayerControllerSystem extends System<any, any, any, any, any> {
     constructor();
     dependencies: (typeof Transform | typeof FirstPersonPlayerController)[];
-    components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof Camera>)[];
+    components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof Camera> | ResourceAccessSpecification<typeof RigidBody>)[];
     /**
      * Per-entity runtime, keyed by entity id.
      * @type {Map<number, PerEntityRuntime>}
@@ -37,6 +37,24 @@ export class FirstPersonPlayerControllerSystem extends System<any, any, any, any
      * @type {number}
      */
     groundY: number;
+    /**
+     * Optional callback that returns the surface Y under the player
+     * for ground resolution. Called each tick with the player's
+     * current (x, y, z); returns the world-Y of the ground below,
+     * or null if no ground is below (gap / void).
+     *
+     * Combines with `useBuiltInFlatGround`: the effective ground for
+     * the tick is `max(this.groundY when enabled, resolver(...))`.
+     * Set both off (`useBuiltInFlatGround=false`, `groundResolver=null`)
+     * to defer to external physics entirely.
+     *
+     * Designed for prototypes / gyms that need elevated platforms
+     * without a full physics layer. Production should wire a real
+     * physics system instead.
+     *
+     * @type {((x:number, y:number, z:number) => number|null) | null}
+     */
+    groundResolver: (x: number, y: number, z: number) => number | null;
     /**
      * @param {FirstPersonPlayerController} controller
      * @param {Transform} bodyTransform
@@ -49,6 +67,16 @@ export class FirstPersonPlayerControllerSystem extends System<any, any, any, any
      * @param {number} entity
      */
     unlink(controller: FirstPersonPlayerController, bodyTransform: Transform, entity: number): void;
+    /**
+     * Look up the per-entity runtime for an entity that has this
+     * controller. Used by cross-system code (sensors system, future
+     * ability-driven systems) to reach internal state without leaking
+     * it onto the controller component itself.
+     *
+     * @param {number} entity
+     * @returns {PerEntityRuntime|undefined}  undefined if entity is not linked
+     */
+    getRuntime(entity: number): PerEntityRuntime | undefined;
     _currentDt: number;
     _currentRenderDt: number;
     /**
@@ -64,6 +92,81 @@ export class FirstPersonPlayerControllerSystem extends System<any, any, any, any
      * @returns {boolean}
      */
     private _resolveCrouchHeld;
+    /**
+     * Jump finite-state-machine: button-edge detection, buffer + coyote
+     * grace, anticipation timer, impulse on completion. Variable-height
+     * cut is captured here as a `state.isVariableJumpCut` flag that the
+     * gravity step in `_integrateVerticalAndResolveGround` consumes.
+     *
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {PerEntityRuntime} runtime
+     * @param {Transform} bodyTransform
+     * @param {number} dt
+     */
+    private _advanceJumpFsm;
+    /**
+     * Gravity (with fall and cut multipliers), vertical integration,
+     * built-in flat-floor resolution (land event + impulse), and jump-apex
+     * detection. The full vertical phase of one fixed step.
+     *
+     * The built-in flat-floor branch only runs when `useBuiltInFlatGround`
+     * is true (the prototype's standalone mode); with an external physics
+     * layer attached the system relies on the layer to set `state.grounded`
+     * and only maintains airborne/grounded timers here.
+     *
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {PerEntityRuntime} runtime
+     * @param {Transform} bodyTransform
+     * @param {number} dt
+     */
+    private _integrateVerticalAndResolveGround;
+    /**
+     * Run the base (no-ability) L1 locomotion phases: speed selection,
+     * desired-velocity computation, accel/decel, jump FSM, gravity, body
+     * integration, ground resolution. Only invoked when no ability owns
+     * the tick (see {@link AbilitySet.tick}).
+     *
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {PerEntityRuntime} runtime
+     * @param {Transform} bodyTransform
+     * @param {number} dt
+     * @param {boolean} isCrouchActive
+     * @param {boolean} isSprintIntent
+     * @param {boolean} isBackwardIntent
+     */
+    private _runBaseLocomotion;
+    /**
+     * Compute the natural camera lean for this tick: lat-accel-driven
+     * roll into a turn, plus a yaw-rate look-lean contribution, both
+     * clamped. The result is the target the lean spring chases each
+     * tick when no ability has opinions.
+     *
+     * Pure-ish helper — reads `controller`, `runtime`, `dt`; returns a
+     * number. Extracted so both base and any future ability that wants
+     * to compose its lean on top of the natural value can call it.
+     *
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {PerEntityRuntime} runtime
+     * @param {number} dt
+     * @returns {number} target roll in radians
+     */
+    private _computeNaturalLeanTarget;
+    /**
+     * Snapshot the per-tick "what is the body doing" information into the
+     * pose channels for downstream consumption (skeleton, sound, AI).
+     * Read-only with respect to controller state — this is purely a publish
+     * step.
+     *
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {PerEntityRuntime} runtime
+     * @param {Transform} bodyTransform
+     */
+    private _publishPose;
     /**
      * Compose the eye transform from body + state-driven offsets.
      * @private
@@ -77,6 +180,7 @@ import { Transform } from "../../ecs/transform/Transform.js";
 import { FirstPersonPlayerController } from "./FirstPersonPlayerController.js";
 import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
 import { Camera } from "../../graphics/ecs/camera/Camera.js";
+import { RigidBody } from "../../physics/ecs/RigidBody.js";
 /**
  * Per-entity runtime state the system maintains internally — too transient
  * even for {@link FirstPersonPlayerController}'s `state` member, because it
@@ -84,10 +188,21 @@ import { Camera } from "../../graphics/ecs/camera/Camera.js";
  * never see directly.
  */
 declare class PerEntityRuntime {
+    /**
+     * Co-attached kinematic body. Set by {@link FirstPersonPlayerControllerSystem.link}
+     * after asserting it's present. The controller writes Transform.position
+     * directly (existing motion logic); physics derives the body's velocity
+     * from the per-step delta. Other physics systems (raycasts, contact
+     * events) see the player through this body.
+     * @type {RigidBody|null}
+     */
+    rigidBody: RigidBody | null;
     /** Eye pitch in radians, clamped to config.look limits. */
     eyePitch: number;
     /** Body yaw in radians (around world up). */
     bodyYaw: number;
+    /** Yaw rate (rad/s) computed in look consumption — for evaluators. */
+    yawRateRadPerSec: number;
     /** Horizontal+vertical velocity. We integrate these inside the system
      *  when no external physics layer is attached. */
     velocityX: number;
@@ -103,28 +218,31 @@ declare class PerEntityRuntime {
     anticipationRemaining: number;
     /** Cached derived gravity (m/s^2) from peakHeight + timeToApex. */
     gravity: number;
-    /** Cached derived jump impulse (m/s upward). */
+    /** Cached derived jump impulse (m/s upward), post-mass-scaling. */
     jumpInitialVy: number;
-    /** Spring state for landing dip (mutated in place). */
-    landSpring: {
-        value: number;
-        velocity: number;
-    };
-    /** Spring state for FOV. */
-    fovSpring: {
-        value: number;
-        velocity: number;
-    };
-    /** Spring state for eye height (crouch). */
-    eyeHeightSpring: {
-        value: number;
-        velocity: number;
-    };
-    /** Spring state for lean roll (radians). */
-    leanSpring: {
-        value: number;
-        velocity: number;
-    };
+    /**
+     * Cached mass scaling factors — computed once at link. See
+     * {@link computeMassRatios}. Heavier ⇒ lower jumpV0Scale, lower
+     * groundAccelScale, higher landingDipScale + exertionRiseScale.
+     */
+    massRatios: any;
+    /** Spring for landing dip (under-damped → rings after impact). */
+    landSpring: Spring;
+    /** Spring for FOV (critically damped). */
+    fovSpring: Spring;
+    /** Spring for eye height (crouch transition). */
+    eyeHeightSpring: Spring;
+    /** Spring for lean roll (radians) — banks into lateral acceleration. */
+    leanSpring: Spring;
+    /**
+     * Lean target this tick (radians). Always set; L2.f spring-steps
+     * toward this value. Whoever owned motion this tick wrote it:
+     * base writes the lat-accel + look-lean derived value at the end
+     * of {@link _runBaseLocomotion}; abilities that want to override
+     * (WallRun → tilt-into-wall, Slide/Mantle/LedgeGrab → zero) write
+     * their own value in tick. Uniform channel — no null sentinel.
+     */
+    leanTargetRad: number;
     /** Previous horizontal velocity — for lateral acceleration → lean. */
     prevVelocityX: number;
     prevVelocityZ: number;
@@ -144,8 +262,88 @@ declare class PerEntityRuntime {
     prevBreathPhase: number;
     /** Which foot fires next — flipped on each footstep signal. */
     nextFootSide: string;
+    /**
+     * Which foot is currently bearing the body's weight (the foot that
+     * most recently landed). Drives the lateral-bob direction: at R
+     * midstance the COM is over the right foot, so the head shifts
+     * laterally toward screen-right; at L midstance the opposite.
+     * Coupled to the same signal the footstep emits, so anything that
+     * listens to onFootStep.side will see the bob agree.
+     * Initialized "L" so the very first footstep fires "R" and the
+     * standingFoot updates to "R" — putting the head laterally right
+     * during the first half-stride, as expected.
+     */
+    standingFoot: string;
+    /**
+     * [0..1] How "backward" the player is currently moving. Derived in
+     * fixedUpdate from velocity · screen-forward, normalized to sprint
+     * speed. Drives the gait wobble amplifier on the L3 camera-composition
+     * pass. Stored on runtime (rather than state) because it's a render-
+     * side input — downstream observers should look at velocity directly.
+     */
+    backwardness: number;
+    /**
+     * Smoothed bob amplitude envelope. Target = max(speedNormalized,
+     * backwardness) when grounded, 0 airborne. Spring decay prevents
+     * the whiplash where stopping motion would snap the bob to neutral.
+     */
+    bobIntensitySpring: Spring;
+    /**
+     * Vertical impact spring — kicked downward at each footfall, decays
+     * with a slight under-damped overshoot. Produces the impact-arrest +
+     * leg-push curve. value units: meters (added directly to eyeLocal.y).
+     */
+    verticalImpactSpring: Spring;
+    /**
+     * Sprint-posture spring — eye pitches forward as the player commits
+     * to a sprint, returns to neutral when they slow. Value is in
+     * radians; slower half-life than other springs so it feels like
+     * a posture change rather than an input twitch. See cfg.posture.
+     */
+    sprintPostureSpring: Spring;
+    /**
+     * Head-droop spring — additional forward pitch as exertion rises.
+     * Sells fatigue subtly. Target tracks exertion-driven max droop
+     * angle; spring lag keeps the transition slow and physical.
+     */
+    headDroopSpring: Spring;
+    /**
+     * [0..1] sprintness — how much of the walk→sprint speed range the
+     * body is currently in. Computed in fixedUpdate, read by L3 for FOV
+     * and the sprint-posture pitch / forward-shift offset.
+     */
+    sprintness: number;
+    /**
+     * Cached sin/cos of current body yaw — written once per fixedUpdate
+     * after look intent is consumed, read by every downstream step
+     * (locomotion, backwardness, lean look-rate, pose channels). Avoids
+     * recomputing the trig 3+ times per tick.
+     */
+    sinYaw: number;
+    cosYaw: number;
+    /** Cached horizontal speed (m/s) for this tick — written in derived-state. */
+    horizSpeed: number;
+    /** Cached stride frequency (Hz) for this tick — written in breath block, read by stride. */
+    strideFreqHz: number;
+    /**
+     * Additive accumulator for body-local eye-position offsets. The
+     * system pushes its own contributions (bob, breath, landing,
+     * sprint posture) each render frame; external systems can push
+     * recoil/shake/knockback contributions via the same interface.
+     */
+    eyeOffsetStack: EyeOffsetStack;
+    /**
+     * Spatial-query results populated by {@link FirstPersonSensorsSystem}
+     * (when present). Abilities and the locomotion FSM read this.
+     * Lives on runtime so other systems can populate it without
+     * touching the controller component's public surface.
+     */
+    sensors: FirstPersonSensors;
     /** Cached eye entity ID. -1 until link assigns it. */
     eyeEntity: number;
 }
+import { Spring } from "./math/Spring.js";
+import { EyeOffsetStack } from "./composer/EyeOffsetStack.js";
+import { FirstPersonSensors } from "./sensors/FirstPersonSensors.js";
 export {};
 //# sourceMappingURL=FirstPersonPlayerControllerSystem.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"FirstPersonPlayerControllerSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerControllerSystem.js"],"names":[],"mappings":"AAqGA;;;;;;;;;;;;;;;;;GAiBG;AACH;IACI,cA6BC;IA1BG,wEAA4D;IAE5D,gHAGC;IAED;;;OAGG;IACH,SAFU,IAAI,MAAM,EAAE,gBAAgB,CAAC,CAEf;IAExB;;;;OAIG;IACH,sBAFU,OAAO,CAEe;IAEhC;;;;OAIG;IACH,SAFU,MAAM,CAEA;IAGpB;;;;OAIG;IACH,iBAJW,2BAA2B,iBAC3B,SAAS,UACT,MAAM,QAmDhB;IAED;;;;OAIG;IACH,mBAJW,2BAA2B,iBAC3B,SAAS,UACT,MAAM,QAWhB;IAUG,mBAAoB;IAYpB,yBAA0B;IAI9B;;;;OAIG;IACH,oBAsXC;IAED;;;;;OAKG;IACH,2BAeC;IAED;;;;;OAKG;IACH,oBAsGC;CACJ;uBA/uBsB,qBAAqB;0BAClB,kCAAkC;4CAEhB,kCAAkC;4CANlC,oDAAoD;uBAKzE,qCAAqC;AAqB5D;;;;;GAKG;AACH;IAEQ,2DAA2D;IAC3D,iBAAiB;IACjB,6CAA6C;IAC7C,gBAAgB;IAEhB;sDACkD;IAClD,kBAAkB;IAClB,kBAAkB;IAClB,kBAAkB;IAElB,qEAAqE;IACrE,sBAAyB;IACzB,oEAAoE;IACpE,wBAA2B;IAC3B,yEAAyE;IACzE,uBAA0B;IAE1B,wEAAwE;IACxE,8BAA8B;IAC9B,mEAAmE;IACnE,gBAAmB;IACnB,gDAAgD;IAChD,sBAAwB;IAExB,uDAAuD;IACvD;;;MAA2C;IAC3C,4BAA4B;IAC5B;;;MAA2C;IAC3C,4CAA4C;IAC5C;;;MAAmD;IACnD,4CAA4C;IAC5C;;;MAA2C;IAE3C,sEAAsE;IACtE,sBAAsB;IACtB,sBAAsB;IAEtB,iDAAiD;IACjD,sBAAwB;IACxB,uDAAuD;IACvD,kBAAkB;IAClB,0EAA0E;IAC1E,qBAAqB;IACrB,+DAA+D;IAC/D,iBAAoB;IACpB,oDAAoD;IACpD,mBAAsB;IAEtB,2EAA2E;IAC3E,wBAAwB;IACxB,gFAAgF;IAChF,wBAAwB;IACxB,+DAA+D;IAC/D,qBAAuB;IAEvB,sDAAsD;IACtD,kBAAmB;CAE1B"}
+{"version":3,"file":"FirstPersonPlayerControllerSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerControllerSystem.js"],"names":[],"mappings":"AAgOA;;;;;;;;;;;;;;;;;GAiBG;AACH;IACI,cAuDC;IA9CG,wEAA4D;IAE5D,gKAIC;IAED;;;OAGG;IACH,SAFU,IAAI,MAAM,EAAE,gBAAgB,CAAC,CAEf;IAExB;;;;OAIG;IACH,sBAFU,OAAO,CAEe;IAEhC;;;;OAIG;IACH,SAFU,MAAM,CAEA;IAEhB;;;;;;;;;;;;;;;;OAgBG;IACH,oBAFc,MAAM,KAAI,MAAM,KAAI,MAAM,KAAK,MAAM,GAAC,IAAI,CAE9B;IAG9B;;;;OAIG;IACH,iBAJW,2BAA2B,iBAC3B,SAAS,UACT,MAAM,QA2EhB;IAED;;;;OAIG;IACH,mBAJW,2BAA2B,iBAC3B,SAAS,UACT,MAAM,QAWhB;IAED;;;;;;;;OAQG;IACH,mBAHW,MAAM,GACJ,gBAAgB,GAAC,SAAS,CAItC;IAUG,mBAAoB;IAYpB,yBAA0B;IAI9B;;;;OAIG;IACH,oBAgUC;IAED;;;;;OAKG;IACH,2BAeC;IAED;;;;;;;;;;;OAWG;IACH,wBAkEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,2CA6GC;IAED;;;;;;;;;;;;;;OAcG;IACH,2BA4EC;IAED;;;;;;;;;;;;;;;OAeG;IACH,kCAsDC;IAED;;;;;;;;;;OAUG;IACH,qBA8CC;IAED;;;;;OAKG;IACH,oBA4JC;CACJ;uBAv1CsB,qBAAqB;0BAClB,kCAAkC;4CAKhB,kCAAkC;4CATlC,oDAAoD;uBAKzE,qCAAqC;0BAGlC,gCAAgC;AAyB1D;;;;;GAKG;AACH;IAEQ;;;;;;;OAOG;IACH,WAFU,SAAS,GAAC,IAAI,CAEH;IAErB,2DAA2D;IAC3D,iBAAiB;IACjB,6CAA6C;IAC7C,gBAAgB;IAChB,sEAAsE;IACtE,yBAAyB;IAEzB;sDACkD;IAClD,kBAAkB;IAClB,kBAAkB;IAClB,kBAAkB;IAElB,qEAAqE;IACrE,sBAAyB;IACzB,oEAAoE;IACpE,wBAA2B;IAC3B,yEAAyE;IACzE,uBAA0B;IAE1B,wEAAwE;IACxE,8BAA8B;IAC9B,mEAAmE;IACnE,gBAAmB;IACnB,mEAAmE;IACnE,sBAAwB;IACxB;;;;OAIG;IACH,gBAAsB;IAEtB,kEAAkE;IAClE,mBAA8B;IAC9B,0CAA0C;IAC1C,kBAA+B;IAC/B,iDAAiD;IACjD,wBAAuC;IACvC,wEAAwE;IACxE,mBAA8B;IAC9B;;;;;;;OAOG;IACH,sBAAsB;IAEtB,sEAAsE;IACtE,sBAAsB;IACtB,sBAAsB;IAEtB,iDAAiD;IACjD,sBAAwB;IACxB,uDAAuD;IACvD,kBAAkB;IAClB,0EAA0E;IAC1E,qBAAqB;IACrB,+DAA+D;IAC/D,iBAAoB;IACpB,oDAAoD;IACpD,mBAAsB;IAEtB,2EAA2E;IAC3E,wBAAwB;IACxB,gFAAgF;IAChF,wBAAwB;IACxB,+DAA+D;IAC/D,qBAAuB;IACvB;;;;;;;;;;OAUG;IACH,qBAAuB;IAEvB;;;;;;OAMG;IACH,qBAAqB;IAErB;;;;OAIG;IACH,2BAAsC;IAEtC;;;;OAIG;IACH,6BAAwC;IAExC;;;;;OAKG;IACH,4BAAuC;IAEvC;;;;OAIG;IACH,wBAAmC;IAEnC;;;;OAIG;IACH,mBAAmB;IAEnB;;;;;OAKG;IACH,eAAe;IACf,eAAe;IAEf,8EAA8E;IAC9E,mBAAmB;IAEnB,4FAA4F;IAC5F,qBAAqB;IAErB;;;;;OAKG;IACH,+BAA0C;IAE1C;;;;;OAKG;IACH,4BAAuC;IAEvC,sDAAsD;IACtD,kBAAmB;CAE1B;uBAzMsB,kBAAkB;+BARV,8BAA8B;mCAY1B,iCAAiC"}