@woosh/meep-engine 2.138.17 → 2.138.19

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

@@ -0,0 +1,205 @@
+/**
+ * Tunable parameters for {@link FirstPersonPlayerController}. The full
+ * config is the only serialized portion of the component — everything else
+ * (intent, state, pose, signals) is transient and rebuilt on link.
+ *
+ * Defaults aim for a baseline "human soldier" feel — see DESIGN.md §4.1.
+ * Every value is exposed so designers can mod it to taste.
+ */
+export class FirstPersonPlayerControllerConfig {
+    body = {
+        /** Standing eye height, meters above body origin. */
+        height: 1.80,
+        /** Crouched eye height. */
+        crouchHeight: 1.10,
+        /** Capsule radius, for downstream physics. */
+        radius: 0.35,
+        /** Kilograms — drives bob amplitude and land-impact magnitude. */
+        mass: 80,
+    };
+
+    // Defaults are tuned toward an "athlete with juice" feel — plausible
+    // but biased for fun: snappy accel, fast top speed, generous air
+    // control, satisfying jump. Realistic-soldier values would roughly
+    // halve walk/sprint/airControl and use peakHeight ≈ 1.0–1.2.
+    motion = {
+        walkSpeed: 4.5,         // brisk jog — quicker than a real walk
+        sprintSpeed: 9.0,       // fast but sub-Olympic (~12 m/s is human peak)
+        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
+        /** m/s^2 horizontal deceleration toward 0 when intent is zero. */
+        groundDecel: 75,        // crisp stops, no skating
+        /** m/s^2 horizontal acceleration while airborne. */
+        airAccel: 14,           // mid-air agility for course-correction
+    };
+
+    jump = {
+        /** Apex height of a clean jump, meters. */
+        peakHeight: 1.8,        // matches eye height — the iconic "athlete leap"
+        /** Seconds to reach apex from launch. Together these two derive g. */
+        timeToApex: 0.35,       // snappier rise
+        coyoteTime: 0.14,       // generous for forgiving platforming
+        bufferTime: 0.16,
+        /** Gravity multiplier while falling (vy <= 0). */
+        fallGravityMult: 2.4,   // fast fall — classic Mario/Sonic feel
+        /** Gravity multiplier when jump released early during ascent. */
+        cutGravityMult: 2.0,    // sharper variable-height differentiation
+        anticipation: {
+            duration: 0.06,     // short — keeps jumps responsive
+            dipAmount: 0.08,    // but visibly squashes
+        },
+    };
+
+    landing = {
+        /** m/s impact threshold; below = soft landing signal. */
+        softThreshold: 3.0,
+        /** m/s impact threshold; above = hard landing signal. */
+        hardThreshold: 7.5,
+        recovery: {
+            /** Meters of eye dip per m/s of impact velocity. */
+            dipPerVy: 0.016,    // beefier squash on landing
+            /** Clamp on total dip. */
+            dipMax: 0.24,
+            spring: {
+                halfLife: 0.11,
+                /** zeta < 1 → rings once before settling, reads as compression. */
+                zeta: 0.50,     // a touch more bounce
+            },
+        },
+    };
+
+    crouch = {
+        /** Seconds to lerp eye height between standing and crouched. */
+        transitionTime: 0.18,
+        /** "hold" or "toggle" */
+        mode: "hold",
+    };
+
+    bob = {
+        stepFreqAtWalk: 1.8,
+        stepFreqExp: 0.75,      // sub-linear so sprint isn't frantic
+        verticalAmpAtWalk: 0.055,
+        lateralAmpAtWalk: 0.030,
+        /** Extra amplitude per kg above 80kg (reference mass). */
+        ampMassScale: 0.005,
+        rollAtWalkDeg: 0.8,     // a touch more visible head sway
+        /** Speeds below this don't tick the stride at all. */
+        minStepSpeed: 0.2,
+    };
+
+    breath = {
+        rateRestHz: 0.23,
+        rateMaxHz: 0.70,
+        amplitudeRestM: 0.004,
+        amplitudeMaxM: 0.022,
+        pitchAmpRestDeg: 0.10,
+        pitchAmpMaxDeg: 0.55,
+        /** ±20% amplitude noise rides on the sine. */
+        noiseAmount: 0.20,
+    };
+
+    exertion = {
+        sprintRiseRate: 0.20,
+        jumpRise: 0.08,
+        idleDecayRate: 0.12,
+        rateDecayHalfLife: 4.0,
+        ampDecayHalfLife: 2.0,
+    };
+
+    lean = {
+        enabled: true,
+        /** Degrees of roll per (lateral m/s^2 / 9.81). */
+        maxRollDeg: 3.2,        // more visible lean into turns — sells the athleticism
+        spring: { halfLife: 0.16, zeta: 1.0 },
+    };
+
+    fov = {
+        base: 75,               // wider baseline — more energetic
+        sprintAdd: 10,          // dramatic punch on sprint (Apex/Titanfall feel)
+        crouchAdd: -4,
+        smoothHalfLife: 0.18,   // slightly snappier transitions
+    };
+
+    look = {
+        pitchMinDeg: -85,
+        pitchMaxDeg: 85,
+        invertY: false,
+    };
+
+    gravity = {
+        /** Default gravity magnitude (m/s^2). Overridden by computeJumpFromApex once
+         *  the jump tunables are resolved; kept here so non-jumping entities (NPCs,
+         *  paused players) still have a sensible fall behavior. */
+        magnitude: 9.81,
+    };
+
+    toJSON() {
+        return {
+            body: { ...this.body },
+            motion: { ...this.motion },
+            jump: { ...this.jump, anticipation: { ...this.jump.anticipation } },
+            landing: {
+                ...this.landing,
+                recovery: {
+                    ...this.landing.recovery,
+                    spring: { ...this.landing.recovery.spring },
+                },
+            },
+            crouch: { ...this.crouch },
+            bob: { ...this.bob },
+            breath: { ...this.breath },
+            exertion: { ...this.exertion },
+            lean: { ...this.lean, spring: { ...this.lean.spring } },
+            fov: { ...this.fov },
+            look: { ...this.look },
+            gravity: { ...this.gravity },
+        };
+    }
+
+    fromJSON(json) {
+        if (json.body) Object.assign(this.body, json.body);
+        if (json.motion) Object.assign(this.motion, json.motion);
+        if (json.jump) {
+            const { anticipation, ...rest } = json.jump;
+            Object.assign(this.jump, rest);
+            if (anticipation) Object.assign(this.jump.anticipation, anticipation);
+        }
+        if (json.landing) {
+            const { recovery, ...rest } = json.landing;
+            Object.assign(this.landing, rest);
+            if (recovery) {
+                const { spring, ...rrest } = recovery;
+                Object.assign(this.landing.recovery, rrest);
+                if (spring) Object.assign(this.landing.recovery.spring, spring);
+            }
+        }
+        if (json.crouch) Object.assign(this.crouch, json.crouch);
+        if (json.bob) Object.assign(this.bob, json.bob);
+        if (json.breath) Object.assign(this.breath, json.breath);
+        if (json.exertion) Object.assign(this.exertion, json.exertion);
+        if (json.lean) {
+            const { spring, ...rest } = json.lean;
+            Object.assign(this.lean, rest);
+            if (spring) Object.assign(this.lean.spring, spring);
+        }
+        if (json.fov) Object.assign(this.fov, json.fov);
+        if (json.look) Object.assign(this.look, json.look);
+        if (json.gravity) Object.assign(this.gravity, json.gravity);
+    }
+
+    /**
+     * @param {FirstPersonPlayerControllerConfig} other
+     */
+    copy(other) {
+        this.fromJSON(other.toJSON());
+    }
+
+    clone() {
+        const c = new FirstPersonPlayerControllerConfig();
+        c.copy(this);
+        return c;
+    }
+}

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

@@ -0,0 +1,151 @@
+/**
+ * Drives a first-person camera + body from intent fields. See sibling
+ * DESIGN.md for goals, architecture, and the five processing layers (L0..L4).
+ *
+ * - fixedUpdate runs L1 (locomotion), L2 (pose state), and L4 (events) so
+ *   the simulation remains deterministic.
+ * - update runs L3 (camera composition) at render rate so the eye is never
+ *   smoother than the screen.
+ *
+ * The system itself integrates a simple flat-floor at y = `config.gravity.magnitude > 0
+ * ? state.groundY : -Infinity` for the prototype. A real physics layer should
+ * write `state.grounded`/`state.groundNormal` from outside instead; the
+ * built-in resolver is just a convenience to keep the controller usable
+ * without dependencies.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FirstPersonPlayerControllerSystem extends System<any, any, any, any, any> {
+    constructor();
+    dependencies: (typeof Transform | typeof FirstPersonPlayerController)[];
+    components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof Camera>)[];
+    /**
+     * Per-entity runtime, keyed by entity id.
+     * @type {Map<number, PerEntityRuntime>}
+     */
+    runtime: Map<number, PerEntityRuntime>;
+    /**
+     * If true, the system clamps body y >= groundY and writes
+     * state.grounded itself. Turn off when wiring a real physics layer.
+     * @type {boolean}
+     */
+    useBuiltInFlatGround: boolean;
+    /**
+     * The flat-ground y for the built-in resolver. Ignored when
+     * useBuiltInFlatGround is false.
+     * @type {number}
+     */
+    groundY: number;
+    /**
+     * @param {FirstPersonPlayerController} controller
+     * @param {Transform} bodyTransform
+     * @param {number} entity
+     */
+    link(controller: FirstPersonPlayerController, bodyTransform: Transform, entity: number): void;
+    /**
+     * @param {FirstPersonPlayerController} controller
+     * @param {Transform} bodyTransform
+     * @param {number} entity
+     */
+    unlink(controller: FirstPersonPlayerController, bodyTransform: Transform, entity: number): void;
+    _currentDt: number;
+    _currentRenderDt: number;
+    /**
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {number} entity
+     */
+    private _tickEntity;
+    /**
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {PerEntityRuntime} runtime
+     * @returns {boolean}
+     */
+    private _resolveCrouchHeld;
+    /**
+     * Compose the eye transform from body + state-driven offsets.
+     * @private
+     * @param {FirstPersonPlayerController} controller
+     * @param {number} entity
+     */
+    private _composeEye;
+}
+import { System } from "../../ecs/System.js";
+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";
+/**
+ * Per-entity runtime state the system maintains internally — too transient
+ * even for {@link FirstPersonPlayerController}'s `state` member, because it
+ * encodes input-edge bookkeeping and timer values the public surface should
+ * never see directly.
+ */
+declare class PerEntityRuntime {
+    /** Eye pitch in radians, clamped to config.look limits. */
+    eyePitch: number;
+    /** Body yaw in radians (around world up). */
+    bodyYaw: number;
+    /** Horizontal+vertical velocity. We integrate these inside the system
+     *  when no external physics layer is attached. */
+    velocityX: number;
+    velocityY: number;
+    velocityZ: number;
+    /** Previous-tick jump intent — for rising/falling edge detection. */
+    prevJumpHeld: boolean;
+    /** Previous-tick crouch intent — for toggle-mode edge detection. */
+    prevCrouchHeld: boolean;
+    /** True while crouch toggle is latched on (used only in toggle mode). */
+    crouchLatched: boolean;
+    /** Remaining time in jump anticipation, or <= 0 if not anticipating. */
+    anticipationRemaining: number;
+    /** Cached derived gravity (m/s^2) from peakHeight + timeToApex. */
+    gravity: number;
+    /** Cached derived jump impulse (m/s upward). */
+    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;
+    };
+    /** Previous horizontal velocity — for lateral acceleration → lean. */
+    prevVelocityX: number;
+    prevVelocityZ: number;
+    /** Previous-tick grounded for edge detection. */
+    prevGrounded: boolean;
+    /** Vertical speed at moment of last "leave ground". */
+    takeoffVy: number;
+    /** Max vertical position since last takeoff — for jump apex detection. */
+    peakAltitude: number;
+    /** Set true once a jump has been launched; cleared on land. */
+    midJump: boolean;
+    /** Apex already fired for this airborne segment? */
+    apexFired: boolean;
+    /** Stride phase from previous fixed step — for footstep edge detection. */
+    prevStridePhase: number;
+    /** Breath phase from previous fixed step — for inhale/exhale edge detection. */
+    prevBreathPhase: number;
+    /** Which foot fires next — flipped on each footstep signal. */
+    nextFootSide: string;
+    /** Cached eye entity ID. -1 until link assigns it. */
+    eyeEntity: number;
+}
+export {};
+//# sourceMappingURL=FirstPersonPlayerControllerSystem.d.ts.map

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

@@ -0,0 +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"}