@woosh/meep-engine 2.138.17 → 2.138.19

package/src/engine/control/first-person/math/computeJumpFromApex.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Convert designer-friendly jump parameters (apex height in meters, time to
+ * reach apex in seconds) into the gravity and initial vertical velocity that
+ * produce that jump exactly.
+ *
+ * The standard ballistic equations:
+ *   y(t)  = v0 * t  -  0.5 * g * t^2
+ *   y'(t) = v0      -  g * t
+ *
+ * At apex y'(t) = 0, so t_apex = v0 / g.
+ * Solving with the desired apex height h:
+ *   g  = 2h / t_apex^2
+ *   v0 = 2h / t_apex
+ *
+ * @param {number} peakHeight  desired apex height in meters (must be > 0)
+ * @param {number} timeToApex  seconds to reach apex (must be > 0)
+ * @param {{gravity:number, initialVelocity:number}} out
+ */
+export function computeJumpFromApex(peakHeight: number, timeToApex: number, out: {
+    gravity: number;
+    initialVelocity: number;
+}): void;
+//# sourceMappingURL=computeJumpFromApex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"computeJumpFromApex.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/math/computeJumpFromApex.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,gDAJW,MAAM,cACN,MAAM,OACN;IAAC,OAAO,EAAC,MAAM,CAAC;IAAC,eAAe,EAAC,MAAM,CAAA;CAAC,QAMlD"}

package/src/engine/control/first-person/math/computeJumpFromApex.js

@@ -0,0 +1,23 @@
+/**
+ * Convert designer-friendly jump parameters (apex height in meters, time to
+ * reach apex in seconds) into the gravity and initial vertical velocity that
+ * produce that jump exactly.
+ *
+ * The standard ballistic equations:
+ *   y(t)  = v0 * t  -  0.5 * g * t^2
+ *   y'(t) = v0      -  g * t
+ *
+ * At apex y'(t) = 0, so t_apex = v0 / g.
+ * Solving with the desired apex height h:
+ *   g  = 2h / t_apex^2
+ *   v0 = 2h / t_apex
+ *
+ * @param {number} peakHeight  desired apex height in meters (must be > 0)
+ * @param {number} timeToApex  seconds to reach apex (must be > 0)
+ * @param {{gravity:number, initialVelocity:number}} out
+ */
+export function computeJumpFromApex(peakHeight, timeToApex, out) {
+    const t = timeToApex;
+    out.gravity = (2 * peakHeight) / (t * t);
+    out.initialVelocity = (2 * peakHeight) / t;
+}

package/src/engine/control/first-person/math/criticallyDampedSpring.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Critically damped spring step, parameterized by half-life rather than
+ * angular frequency. A critically damped spring reaches its goal as fast as
+ * possible without oscillation — ideal for FOV, crouch height, and lean.
+ *
+ * Form follows Daniel Holden, "Spring-It-On" — `theorangeduck.com/page/spring-roll-call`.
+ *
+ *   y  = ln(2) / halfLife
+ *   eyt = exp(-y * dt)
+ *   j1 = v + (x - target) * y
+ *   x' = target + (x - target + j1 * dt) * eyt
+ *   v' = (v - j1 * y * dt) * eyt
+ *
+ * @param {{value:number, velocity:number}} state mutated in place
+ * @param {number} target  goal value
+ * @param {number} halfLife seconds for the gap to halve (smaller = snappier)
+ * @param {number} dt
+ */
+export function criticallyDampedSpringStep(state: {
+    value: number;
+    velocity: number;
+}, target: number, halfLife: number, dt: number): void;
+//# sourceMappingURL=criticallyDampedSpring.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"criticallyDampedSpring.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/math/criticallyDampedSpring.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,kDALW;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,QAAQ,EAAC,MAAM,CAAA;CAAC,UAC/B,MAAM,YACN,MAAM,MACN,MAAM,QAiBhB"}

package/src/engine/control/first-person/math/criticallyDampedSpring.js

@@ -0,0 +1,34 @@
+/**
+ * Critically damped spring step, parameterized by half-life rather than
+ * angular frequency. A critically damped spring reaches its goal as fast as
+ * possible without oscillation — ideal for FOV, crouch height, and lean.
+ *
+ * Form follows Daniel Holden, "Spring-It-On" — `theorangeduck.com/page/spring-roll-call`.
+ *
+ *   y  = ln(2) / halfLife
+ *   eyt = exp(-y * dt)
+ *   j1 = v + (x - target) * y
+ *   x' = target + (x - target + j1 * dt) * eyt
+ *   v' = (v - j1 * y * dt) * eyt
+ *
+ * @param {{value:number, velocity:number}} state mutated in place
+ * @param {number} target  goal value
+ * @param {number} halfLife seconds for the gap to halve (smaller = snappier)
+ * @param {number} dt
+ */
+export function criticallyDampedSpringStep(state, target, halfLife, dt) {
+    if (halfLife <= 0) {
+        state.value = target;
+        state.velocity = 0;
+        return;
+    }
+
+    const y = 0.6931471805599453 / halfLife; // ln(2) / halfLife
+    const eyt = Math.exp(-y * dt);
+
+    const delta = state.value - target;
+    const j1 = state.velocity + delta * y;
+
+    state.value = target + (delta + j1 * dt) * eyt;
+    state.velocity = (state.velocity - j1 * y * dt) * eyt;
+}

package/src/engine/control/first-person/math/dampedSpringStep.d.ts

@@ -0,0 +1,23 @@
+/**
+ * General damped spring step (under/critically/over-damped), used for
+ * landing recovery where a small ring/overshoot is desirable.
+ *
+ * Uses the half-life form of natural frequency and an explicit damping
+ * ratio zeta. zeta=1 → critically damped (no ring), zeta<1 → under-damped
+ * (rings), zeta>1 → over-damped (sluggish).
+ *
+ * Numerically stable for any zeta via the closed-form solutions of the
+ * 2nd-order ODE. Reference: Allen Chou,
+ * `allenchou.net/2015/04/game-math-precise-control-over-numeric-springing/`.
+ *
+ * @param {{value:number, velocity:number}} state mutated in place
+ * @param {number} target
+ * @param {number} halfLife seconds for the *envelope* to halve
+ * @param {number} zeta damping ratio (e.g. 0.55 for a slight ring)
+ * @param {number} dt
+ */
+export function dampedSpringStep(state: {
+    value: number;
+    velocity: number;
+}, target: number, halfLife: number, zeta: number, dt: number): void;
+//# sourceMappingURL=dampedSpringStep.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dampedSpringStep.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/math/dampedSpringStep.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wCANW;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,QAAQ,EAAC,MAAM,CAAA;CAAC,UAC/B,MAAM,YACN,MAAM,QACN,MAAM,MACN,MAAM,QAuDhB"}

package/src/engine/control/first-person/math/dampedSpringStep.js

@@ -0,0 +1,72 @@
+/**
+ * General damped spring step (under/critically/over-damped), used for
+ * landing recovery where a small ring/overshoot is desirable.
+ *
+ * Uses the half-life form of natural frequency and an explicit damping
+ * ratio zeta. zeta=1 → critically damped (no ring), zeta<1 → under-damped
+ * (rings), zeta>1 → over-damped (sluggish).
+ *
+ * Numerically stable for any zeta via the closed-form solutions of the
+ * 2nd-order ODE. Reference: Allen Chou,
+ * `allenchou.net/2015/04/game-math-precise-control-over-numeric-springing/`.
+ *
+ * @param {{value:number, velocity:number}} state mutated in place
+ * @param {number} target
+ * @param {number} halfLife seconds for the *envelope* to halve
+ * @param {number} zeta damping ratio (e.g. 0.55 for a slight ring)
+ * @param {number} dt
+ */
+export function dampedSpringStep(state, target, halfLife, zeta, dt) {
+    if (halfLife <= 0) {
+        state.value = target;
+        state.velocity = 0;
+        return;
+    }
+
+    // omega such that the envelope decays by 1/2 in halfLife
+    // for the under-damped case the envelope is exp(-zeta * omega * t)
+    // → omega = ln(2) / (zeta * halfLife). For zeta=1 this matches the
+    // critically damped form.
+    const omega = 0.6931471805599453 / (Math.max(zeta, 1e-4) * halfLife);
+
+    const x = state.value - target;
+    const v = state.velocity;
+
+    if (zeta < 1.0) {
+        // Under-damped: rings
+        const omega_d = omega * Math.sqrt(1 - zeta * zeta);
+        const za = zeta * omega;
+        const exp_term = Math.exp(-za * dt);
+        const cos_term = Math.cos(omega_d * dt);
+        const sin_term = Math.sin(omega_d * dt);
+        const A = x;
+        const B = (v + za * x) / omega_d;
+
+        state.value = target + exp_term * (A * cos_term + B * sin_term);
+        state.velocity = exp_term * (
+            (-za) * (A * cos_term + B * sin_term)
+            + omega_d * (-A * sin_term + B * cos_term)
+        );
+    } else if (zeta > 1.0) {
+        // Over-damped: two real roots
+        const za = zeta * omega;
+        const zb = omega * Math.sqrt(zeta * zeta - 1);
+        const r1 = -za + zb;
+        const r2 = -za - zb;
+        const c2 = (v - x * r1) / (r2 - r1);
+        const c1 = x - c2;
+        const e1 = Math.exp(r1 * dt);
+        const e2 = Math.exp(r2 * dt);
+
+        state.value = target + c1 * e1 + c2 * e2;
+        state.velocity = c1 * r1 * e1 + c2 * r2 * e2;
+    } else {
+        // Critically damped: shared root
+        const exp_term = Math.exp(-omega * dt);
+        const A = x;
+        const B = v + omega * x;
+
+        state.value = target + exp_term * (A + B * dt);
+        state.velocity = exp_term * (B - omega * (A + B * dt));
+    }
+}

package/src/engine/control/first-person/math/stepTowards.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Linearly step a scalar toward a target by at most `maxStep`. If the gap
+ * is smaller than the step, snaps to target. Used for accel/decel on
+ * horizontal velocity.
+ *
+ * @param {number} current
+ * @param {number} target
+ * @param {number} maxStep must be >= 0
+ * @returns {number}
+ */
+export function stepTowards(current: number, target: number, maxStep: number): number;
+//# sourceMappingURL=stepTowards.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stepTowards.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/math/stepTowards.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qCALW,MAAM,UACN,MAAM,WACN,MAAM,GACJ,MAAM,CAWlB"}

package/src/engine/control/first-person/math/stepTowards.js

@@ -0,0 +1,20 @@
+/**
+ * Linearly step a scalar toward a target by at most `maxStep`. If the gap
+ * is smaller than the step, snaps to target. Used for accel/decel on
+ * horizontal velocity.
+ *
+ * @param {number} current
+ * @param {number} target
+ * @param {number} maxStep must be >= 0
+ * @returns {number}
+ */
+export function stepTowards(current, target, maxStep) {
+    const delta = target - current;
+    if (delta > maxStep) {
+        return current + maxStep;
+    }
+    if (delta < -maxStep) {
+        return current - maxStep;
+    }
+    return target;
+}

package/src/engine/control/first-person/pose/FirstPersonPose.d.ts

@@ -0,0 +1,69 @@
+export namespace FirstPersonActionState {
+    let Grounded: number;
+    let Anticipating: number;
+    let Airborne: number;
+    let Landing: number;
+}
+export class FirstPersonPose {
+    /**
+     * World-space body root.
+     * @type {Vector3}
+     */
+    rootPosition: Vector3;
+    /**
+     * Body facing yaw (radians, around world up).
+     * @type {number}
+     */
+    rootYawRad: number;
+    /**
+     * Head decoupled from body. For most first-person controllers
+     * headYawRad === rootYawRad; surfaced separately so future torso-twist
+     * rigs can lag the head.
+     * @type {number}
+     */
+    headYawRad: number;
+    /**
+     * @type {number}
+     */
+    headPitchRad: number;
+    /**
+     * Includes lean roll.
+     * @type {number}
+     */
+    headRollRad: number;
+    /**
+     * Stride phase, [0..1). Same value the camera bob uses, so a feet rig
+     * driven by this will land its footfalls on the same frames the camera
+     * dips.
+     * @type {number}
+     */
+    locomotionPhase: number;
+    /**
+     * m/s, horizontal speed. Drives a blend tree.
+     * @type {number}
+     */
+    locomotionSpeed: number;
+    /**
+     * [-1..1] lateral component, for strafe-blend space.
+     * @type {number}
+     */
+    locomotionStrafe: number;
+    /**
+     * See {@link FirstPersonActionState}.
+     * @type {number}
+     */
+    actionState: number;
+    /**
+     * [0..1] interpolation between standing and fully-crouched pose.
+     * @type {number}
+     */
+    crouchAmount: number;
+    /**
+     * Same as headPitchRad, surfaced separately for IK consumers that only
+     * need the aim axis.
+     * @type {number}
+     */
+    aimPitch: number;
+}
+import Vector3 from "../../../../core/geom/Vector3.js";
+//# sourceMappingURL=FirstPersonPose.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FirstPersonPose.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/pose/FirstPersonPose.js"],"names":[],"mappings":";;;;;;AAoBA;IACI;;;OAGG;IACH,cAFU,OAAO,CAEY;IAE7B;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;;OAKG;IACH,YAFU,MAAM,CAED;IAEf;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;;OAKG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;;OAGG;IACH,aAFU,MAAM,CAE8B;IAE9C;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,UAFU,MAAM,CAEH;CAChB;oBA1FmB,kCAAkC"}

package/src/engine/control/first-person/pose/FirstPersonPose.js

@@ -0,0 +1,91 @@
+import Vector3 from "../../../../core/geom/Vector3.js";
+
+/**
+ * Read-only outputs intended for a downstream skeleton system to consume.
+ *
+ * Surfaced as a separate struct (rather than reading {@link FirstPersonState}
+ * directly) so that the skeleton-driving contract is stable even if
+ * internal state representations change later. A future first-person arms
+ * rig, third-person body rig, and network-replicated remote rig should all
+ * be able to drive themselves from these channels alone.
+ *
+ * @readonly enum
+ */
+export const FirstPersonActionState = {
+    Grounded: 0,
+    Anticipating: 1, // squashing down before jump impulse
+    Airborne: 2,
+    Landing: 3
+};
+
+export class FirstPersonPose {
+    /**
+     * World-space body root.
+     * @type {Vector3}
+     */
+    rootPosition = new Vector3();
+
+    /**
+     * Body facing yaw (radians, around world up).
+     * @type {number}
+     */
+    rootYawRad = 0;
+
+    /**
+     * Head decoupled from body. For most first-person controllers
+     * headYawRad === rootYawRad; surfaced separately so future torso-twist
+     * rigs can lag the head.
+     * @type {number}
+     */
+    headYawRad = 0;
+
+    /**
+     * @type {number}
+     */
+    headPitchRad = 0;
+
+    /**
+     * Includes lean roll.
+     * @type {number}
+     */
+    headRollRad = 0;
+
+    /**
+     * Stride phase, [0..1). Same value the camera bob uses, so a feet rig
+     * driven by this will land its footfalls on the same frames the camera
+     * dips.
+     * @type {number}
+     */
+    locomotionPhase = 0;
+
+    /**
+     * m/s, horizontal speed. Drives a blend tree.
+     * @type {number}
+     */
+    locomotionSpeed = 0;
+
+    /**
+     * [-1..1] lateral component, for strafe-blend space.
+     * @type {number}
+     */
+    locomotionStrafe = 0;
+
+    /**
+     * See {@link FirstPersonActionState}.
+     * @type {number}
+     */
+    actionState = FirstPersonActionState.Grounded;
+
+    /**
+     * [0..1] interpolation between standing and fully-crouched pose.
+     * @type {number}
+     */
+    crouchAmount = 0;
+
+    /**
+     * Same as headPitchRad, surfaced separately for IK consumers that only
+     * need the aim axis.
+     * @type {number}
+     */
+    aimPitch = 0;
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=prototype_first_person_controller.d.ts.map

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

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