@woosh/meep-engine 2.138.20 → 2.139.0

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

@@ -0,0 +1,44 @@
+/**
+ * Derive the per-effect mass scaling factors from the body config. Computed
+ * once at link time (mass is not expected to change at runtime); the system
+ * caches the result on the runtime.
+ *
+ * Each scaling is mixed with coupling-strength ∈ [0, 1]: at 0 the ratio is
+ * identity (mass becomes purely cosmetic, useful for prototypes); at 1 the
+ * full kinematic relationship applies.
+ *
+ *   massRatio = mass / referenceMass
+ *   coupled(r, k) = 1 + (r - 1) · k       // identity at k=0, full r at k=1
+ *   jumpV0Scale       = 1 / √coupled(massRatio, k)        ∝ 1/√mass
+ *   groundAccelScale  = 1 / coupled(massRatio, k)         ∝ 1/mass
+ *   landingDipScale   =   coupled(massRatio, k)           ∝   mass
+ *   exertionRiseScale =   coupled(massRatio, k)           ∝   mass
+ *
+ * @param {number} mass
+ * @param {number} referenceMass
+ * @param {number} couplingStrength  [0..1]
+ * @returns {{
+ *   massRatio: number,
+ *   jumpV0Scale: number,
+ *   groundAccelScale: number,
+ *   landingDipScale: number,
+ *   exertionRiseScale: number,
+ * }}
+ */
+export function computeMassRatios(mass, referenceMass, couplingStrength) {
+    const r = mass / Math.max(referenceMass, 1e-6);
+    const k = Math.max(0, Math.min(1, couplingStrength));
+    const coupled = 1 + (r - 1) * k;
+
+    // Guard: at very low coupled values 1/coupled blows up. Clamp the
+    // *minimum* coupled to avoid division blow-ups for tiny-mass exotic configs.
+    const safeCoupled = Math.max(coupled, 0.1);
+
+    return {
+        massRatio: r,
+        jumpV0Scale: 1 / Math.sqrt(safeCoupled),
+        groundAccelScale: 1 / safeCoupled,
+        landingDipScale: safeCoupled,
+        exertionRiseScale: safeCoupled,
+    };
+}

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

@@ -4,6 +4,12 @@ export namespace FirstPersonActionState {
     let Airborne: number;
     let Landing: number;
 }
+export namespace FirstPersonLocomotionMode {
+    let Idle: number;
+    let Walk: number;
+    let Sprint: number;
+    let Crouch: number;
+}
 export class FirstPersonPose {
     /**
      * World-space body root.
@@ -49,15 +55,39 @@ export class FirstPersonPose {
      */
     locomotionStrafe: number;
     /**
-     * See {@link FirstPersonActionState}.
+     * Kinetic vertical state. See {@link FirstPersonActionState}.
      * @type {number}
      */
     actionState: number;
+    /**
+     * Horizontal locomotion intent mode. See {@link FirstPersonLocomotionMode}.
+     * @type {number}
+     */
+    locomotionMode: number;
     /**
      * [0..1] interpolation between standing and fully-crouched pose.
+     * Legacy field — pinned to (height − eyeHeight)/(height − crouchHeight),
+     * so a body in Prone reads ≥ 1.0 (saturated). Use {@link postureAmount}
+     * if the animator needs to distinguish Crouch / Prone / Hang.
      * @type {number}
      */
     crouchAmount: number;
+    /**
+     * Current body shape. Picks which animation track the rig should
+     * blend toward — Stand / Crouch / Prone / Hang. See
+     * {@link FirstPersonPosture}.
+     * @type {number}
+     */
+    posture: number;
+    /**
+     * [0..1] blend weight from Stand toward the current {@link posture}.
+     * 0 = fully standing (postures hold-frame is the standing rig);
+     * 1 = fully in the posture's target shape. Computed from eye-height
+     * relative to the posture's target height, so the value transitions
+     * smoothly with the same spring the camera uses.
+     * @type {number}
+     */
+    postureAmount: number;
     /**
      * Same as headPitchRad, surfaced separately for IK consumers that only
      * need the aim axis.

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

@@ -1 +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"}
+{"version":3,"file":"FirstPersonPose.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/pose/FirstPersonPose.js"],"names":[],"mappings":";;;;;;;;;;;;AAuCA;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,gBAFU,MAAM,CAEgC;IAEhD;;;;;;OAMG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;;OAKG;IACH,SAFU,MAAM,CAEmB;IAEnC;;;;;;;OAOG;IACH,eAFU,MAAM,CAEE;IAElB;;;;OAIG;IACH,UAFU,MAAM,CAEH;CAChB;oBAxImB,kCAAkC"}

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

@@ -1,4 +1,5 @@
 import Vector3 from "../../../../core/geom/Vector3.js";
+import { FirstPersonPosture } from "./FirstPersonPosture.js";
 
 /**
  * Read-only outputs intended for a downstream skeleton system to consume.
@@ -8,14 +9,32 @@ import Vector3 from "../../../../core/geom/Vector3.js";
  * 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.
- *
+ */
+
+/**
+ * Vertical (kinetic) state — "what is the body doing in 3D space right now".
+ * Independent of {@link FirstPersonLocomotionMode}; the player can be
+ * Airborne while sprinting, Anticipating from a crouch, etc.
  * @readonly enum
  */
 export const FirstPersonActionState = {
     Grounded: 0,
     Anticipating: 1, // squashing down before jump impulse
     Airborne: 2,
-    Landing: 3
+    Landing: 3,
+};
+
+/**
+ * Horizontal (intent-driven) locomotion mode. Drives the blend tree for the
+ * skeletal rig's locomotion layer. Orthogonal to {@link FirstPersonActionState}
+ * — a Sprint-mode player who jumps is `(Sprint, Airborne)` until they land.
+ * @readonly enum
+ */
+export const FirstPersonLocomotionMode = {
+    Idle: 0,
+    Walk: 1,
+    Sprint: 2,
+    Crouch: 3,
 };
 
 export class FirstPersonPose {
@@ -71,17 +90,44 @@ export class FirstPersonPose {
     locomotionStrafe = 0;
 
     /**
-     * See {@link FirstPersonActionState}.
+     * Kinetic vertical state. See {@link FirstPersonActionState}.
      * @type {number}
      */
     actionState = FirstPersonActionState.Grounded;
 
+    /**
+     * Horizontal locomotion intent mode. See {@link FirstPersonLocomotionMode}.
+     * @type {number}
+     */
+    locomotionMode = FirstPersonLocomotionMode.Idle;
+
     /**
      * [0..1] interpolation between standing and fully-crouched pose.
+     * Legacy field — pinned to (height − eyeHeight)/(height − crouchHeight),
+     * so a body in Prone reads ≥ 1.0 (saturated). Use {@link postureAmount}
+     * if the animator needs to distinguish Crouch / Prone / Hang.
      * @type {number}
      */
     crouchAmount = 0;
 
+    /**
+     * Current body shape. Picks which animation track the rig should
+     * blend toward — Stand / Crouch / Prone / Hang. See
+     * {@link FirstPersonPosture}.
+     * @type {number}
+     */
+    posture = FirstPersonPosture.Stand;
+
+    /**
+     * [0..1] blend weight from Stand toward the current {@link posture}.
+     * 0 = fully standing (postures hold-frame is the standing rig);
+     * 1 = fully in the posture's target shape. Computed from eye-height
+     * relative to the posture's target height, so the value transitions
+     * smoothly with the same spring the camera uses.
+     * @type {number}
+     */
+    postureAmount = 0;
+
     /**
      * Same as headPitchRad, surfaced separately for IK consumers that only
      * need the aim axis.

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

@@ -0,0 +1,7 @@
+export namespace FirstPersonPosture {
+    let Stand: number;
+    let Crouch: number;
+    let Prone: number;
+    let Hang: number;
+}
+//# sourceMappingURL=FirstPersonPosture.d.ts.map

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

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

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

@@ -0,0 +1,27 @@
+/**
+ * Body posture — discrete shape the body holds. Drives eye height and
+ * gait gating (stride / footstep / bob).
+ *
+ * The base controller computes posture from intent each tick (Stand vs.
+ * Crouch). Abilities own the posture while they're active and can force
+ * Prone (slide) or Hang (ledge-grab). When an ability releases, the
+ * next base tick re-derives posture from intent.
+ *
+ * Why a single enum field rather than override sentinels: a uniform
+ * channel that every consumer (eye-height spring, stride gate, future
+ * skeleton animator) reads from one place. Adding a new posture means
+ * adding one enum value + one mapping, not threading "is X overriding
+ * Y" sentinels through L2.
+ *
+ * @readonly enum
+ */
+export const FirstPersonPosture = {
+    /** Upright on both feet — the default. Strides normally. */
+    Stand: 0,
+    /** Knees bent, head dropped — feet still strike the ground. */
+    Crouch: 1,
+    /** Body horizontal — sliding or diving. No stride; eye near ground. */
+    Prone: 2,
+    /** Suspended from hands — hanging on a ledge. No stride. */
+    Hang: 3,
+};