@woosh/meep-engine 2.155.0 → 2.157.0

package/src/engine/asset/loaders/JavascriptAssetLoader.js

@@ -1,47 +1,31 @@
-import { AssetLoader } from "./AssetLoader.js";
-import { GameAssetType } from "../GameAssetType.js";
-import { FunctionCompiler } from "../../../core/function/FunctionCompiler.js";
-import { Asset } from "../Asset.js";
-
-class JavascriptAsset extends Asset {
-    constructor(code) {
-        super();
-
-        this.code = code;
-
-        this.byteSize = 128;
-
-    }
-
-    create(args) {
-
-        return FunctionCompiler.INSTANCE.compile({ code: this.code, args });
-    }
-}
-
-export class JavascriptAssetLoader extends AssetLoader {
-
-    load(scope, path, success, failure, progress) {
-        this.assetManager.get({
-            path: path,
-            scope,
-            type: GameAssetType.Text,
-            callback: (textAsset) => {
-
-                const text = textAsset.create();
-
-                let asset;
-
-                try {
-                    asset = new JavascriptAsset(text);
-                } catch (e) {
-                    failure(e);
-                    return;
-                }
-
-                success(asset);
-
-            }, failure: failure, progress: progress
-        });
-    }
-}
+import { AssetLoader } from "./AssetLoader.js";
+import { GameAssetType } from "../GameAssetType.js";
+import { FunctionCompiler } from "../../../core/function/FunctionCompiler.js";
+import { Asset } from "../Asset.js";
+
+class JavascriptAsset extends Asset {
+    constructor(code) {
+        super();
+
+        this.code = code;
+
+        this.byteSize = 128;
+
+    }
+
+    create(args) {
+
+        return FunctionCompiler.INSTANCE.compile({ code: this.code, args });
+    }
+}
+
+export class JavascriptAssetLoader extends AssetLoader {
+
+    async load(scope, path, success, failure, progress) {
+        const textAsset = await this.assetManager.promise(path, GameAssetType.Text, { scope, progress });
+
+        const text = textAsset.create();
+
+        success(new JavascriptAsset(text));
+    }
+}

package/src/engine/asset/loaders/JsonAssetLoader.js

@@ -3,7 +3,7 @@ import { AssetLoader } from "./AssetLoader.js";
 
 export class JsonAssetLoader extends AssetLoader {
     load(scope, path, callback, failure, progress) {
-        xhr(path, function (data) {
+        xhr(this.resolvePath(path), function (data) {
             let object;
             try {
                 object = JSON.parse(data);

package/src/engine/asset/loaders/SVGAssetLoader.js

@@ -2,9 +2,9 @@ import { AssetLoader } from "./AssetLoader.js";
 
 export class SVGAssetLoader extends AssetLoader {
 
-    load(scope,url, callback, failure, progress) {
+    load(scope, url, callback, failure, progress) {
         const xhr = new XMLHttpRequest();
-        xhr.open('GET', url, true);
+        xhr.open('GET', this.resolvePath(url), true);
 
         xhr.addEventListener('load', function () {
             if (xhr.readyState === xhr.DONE && xhr.status === 200) {

package/src/engine/asset/loaders/SoundAssetLoader.js

@@ -20,7 +20,7 @@ export class SoundAssetLoader extends AssetLoader {
         // Load a sound file using an ArrayBuffer XMLHttpRequest.
         const request = new XMLHttpRequest();
 
-        request.open("GET", path, true);
+        request.open("GET", this.resolvePath(path), true);
 
         request.responseType = "arraybuffer";
 

package/src/engine/asset/loaders/TextAssetLoader.js

@@ -2,8 +2,8 @@ import xhr from "../../network/xhr.js";
 import { AssetLoader } from "./AssetLoader.js";
 
 export class TextAssetLoader extends AssetLoader {
-    load(scope,path, callback, failure, progress) {
-        xhr(path, function (data) {
+    load(scope, path, callback, failure, progress) {
+        xhr(this.resolvePath(path), function (data) {
             const asset = {
                 create: function () {
                     return data;

package/src/{core → engine/asset/loaders}/font/FontAsset.d.ts

@@ -6,5 +6,5 @@ export class FontAsset extends Asset<any> {
     constructor(font: Font);
     __data: Font;
 }
-import { Asset } from "../../engine/asset/Asset.js";
+import { Asset } from "../../Asset.js";
 //# sourceMappingURL=FontAsset.d.ts.map

package/src/engine/asset/loaders/font/FontAsset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FontAsset.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/asset/loaders/font/FontAsset.js"],"names":[],"mappings":"AAEA;IACI;;;OAGG;IACH,wBAIC;IADG,aAAkB;CAUzB;sBApBqB,gBAAgB"}

package/src/{core → engine/asset/loaders}/font/FontAsset.js

@@ -1,21 +1,21 @@
-import { Asset } from "../../engine/asset/Asset.js";
-
-export class FontAsset extends Asset {
-    /**
-     *
-     * @param {Font} font
-     */
-    constructor(font) {
-        super();
-
-        this.__data = font;
-    }
-
-    /**
-     *
-     * @return {Font}
-     */
-    create() {
-        return this.__data;
-    }
-}
+import { Asset } from "../../Asset.js";
+
+export class FontAsset extends Asset {
+    /**
+     *
+     * @param {Font} font
+     */
+    constructor(font) {
+        super();
+
+        this.__data = font;
+    }
+
+    /**
+     *
+     * @return {Font}
+     */
+    create() {
+        return this.__data;
+    }
+}

package/src/{core → engine/asset/loaders}/font/FontAssetLoader.d.ts

@@ -2,5 +2,5 @@ export class FontAssetLoader extends AssetLoader<any, any> {
     constructor();
     load(scope: any, path: any, success: any, failure: any, progress: any): void;
 }
-import { AssetLoader } from "../../engine/asset/loaders/AssetLoader.js";
+import { AssetLoader } from "../AssetLoader.js";
 //# sourceMappingURL=FontAssetLoader.d.ts.map

package/src/engine/asset/loaders/font/FontAssetLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FontAssetLoader.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/asset/loaders/font/FontAssetLoader.js"],"names":[],"mappings":"AAKA;;IACI,6EAYC;CACJ;4BAlB2B,mBAAmB"}

package/src/{core → engine/asset/loaders}/font/FontAssetLoader.js

@@ -1,20 +1,20 @@
-import { load } from "opentype.js";
-import { AssetLoader } from "../../engine/asset/loaders/AssetLoader.js";
-import { FontAsset } from "./FontAsset.js";
-
-
-export class FontAssetLoader extends AssetLoader {
-    load(scope,path, success, failure, progress) {
-        load(path, function (err, font) {
-            if (err) {
-                failure(err);
-            } else {
-
-                const asset = new FontAsset(font);
-
-                success(asset);
-
-            }
-        },{});
-    }
-}
+import { load } from "opentype.js";
+import { AssetLoader } from "../AssetLoader.js";
+import { FontAsset } from "./FontAsset.js";
+
+
+export class FontAssetLoader extends AssetLoader {
+    load(scope, path, success, failure, progress) {
+        load(this.resolvePath(path), function (err, font) {
+            if (err) {
+                failure(err);
+            } else {
+
+                const asset = new FontAsset(font);
+
+                success(asset);
+
+            }
+        },{});
+    }
+}

package/src/engine/asset/loaders/image/ImageRGBADataLoader.d.ts

@@ -32,7 +32,7 @@ export class ImageRGBADataLoader extends AssetLoader<any, any> {
      * @private
      */
     private __standard;
-    load(scope: any, path: any, success: any, failure: any, progress: any): void;
+    load(scope: any, path: any, success: any, failure: any, progress: any): Promise<void>;
 }
 import { AssetLoader } from "../AssetLoader.js";
 import { CodecWithFallback } from "./codec/CodecWithFallback.js";

package/src/engine/asset/loaders/image/ImageRGBADataLoader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ImageRGBADataLoader.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/asset/loaders/image/ImageRGBADataLoader.js"],"names":[],"mappings":"AAYA;IACI;;;OAGG;IACH,8BAFW,MAAM,EAehB;IARG;;;OAGG;IACH,SAFU,kBAAkB;QAAC,IAAI,CAAC;QAAC,KAAK,EAAC,MAAM,CAAC;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,QAAQ,EAAC,MAAM,CAAC;QAAC,QAAQ,EAAC,MAAM,CAAA;KAAC,CAAC,CAKjG;IAGL,oDAOC;IAED;;;;;;OAMG;IACH,4BASC;IAED;;;;;;OAMG;IACH,mBAyBC;IAED,6EAiCC;CACJ;4BA3H2B,mBAAmB;kCACb,8BAA8B"}
+{"version":3,"file":"ImageRGBADataLoader.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/asset/loaders/image/ImageRGBADataLoader.js"],"names":[],"mappings":"AAYA;IACI;;;OAGG;IACH,8BAFW,MAAM,EAehB;IARG;;;OAGG;IACH,SAFU,kBAAkB;QAAC,IAAI,CAAC;QAAC,KAAK,EAAC,MAAM,CAAC;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,QAAQ,EAAC,MAAM,CAAC;QAAC,QAAQ,EAAC,MAAM,CAAA;KAAC,CAAC,CAKjG;IAGL,oDAOC;IAED;;;;;;OAMG;IACH,4BASC;IAED;;;;;;OAMG;IACH,mBAyBC;IAED,sFAwBC;CACJ;4BAlH2B,mBAAmB;kCACb,8BAA8B"}

package/src/engine/asset/loaders/image/ImageRGBADataLoader.js

@@ -91,37 +91,28 @@ export class ImageRGBADataLoader extends AssetLoader {
         return new ImageRGBADataAsset(data, bitmap.width, bitmap.height, bitmap.itemSize);
     }
 
-    load(scope, path, success, failure, progress) {
+    async load(scope, path, success, failure, progress) {
         const extension = computeFileExtension(path);
 
         if (extension === 'dds') {
             //compressed texture
-            this.assetManager.get({
-                path: path,
-                scope,
-                type: GameAssetType.Texture,
-                callback: asset => {
+            const asset = await this.assetManager.promise(path, GameAssetType.Texture, { scope, progress });
 
-                    /**
-                     *
-                     * @type {Texture}
-                     */
-                    const texture = asset.create();
+            /**
+             *
+             * @type {Texture}
+             */
+            const texture = asset.create();
 
-                    const sampler2D = convertTexture2Sampler2D(texture);
+            const sampler2D = convertTexture2Sampler2D(texture);
 
-                    texture.dispose();
+            texture.dispose();
 
-                    const f = new ImageRGBADataAsset(sampler2D.data, sampler2D.width, sampler2D.height, sampler2D.itemSize);
-
-                    success(f);
-
-                }, failure: failure, progress: progress
-            });
+            success(new ImageRGBADataAsset(sampler2D.data, sampler2D.width, sampler2D.height, sampler2D.itemSize));
 
         } else {
 
-            this.__standard(path, scope).then(success, failure);
+            success(await this.__standard(path, scope));
 
         }
     }

package/src/engine/asset/loaders/texture/TextureAssetLoader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TextureAssetLoader.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/asset/loaders/texture/TextureAssetLoader.js"],"names":[],"mappings":"AAKA;;IACI,6EAgCC;CACJ;4BAvC2B,mBAAmB"}
+{"version":3,"file":"TextureAssetLoader.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/asset/loaders/texture/TextureAssetLoader.js"],"names":[],"mappings":"AAKA;;IACI,6EAsCC;CACJ;4BA7C2B,mBAAmB"}

package/src/engine/asset/loaders/texture/TextureAssetLoader.js

@@ -8,6 +8,9 @@ export class TextureAssetLoader extends AssetLoader {
         //figure out what kind of a texture it is
         let fileExtension = computeFileExtension(path);
 
+        // data URIs carry their payload inline, network path resolution must not touch them
+        let is_data_uri = false;
+
         if (fileExtension === null) {
             //check if it's a data path
 
@@ -19,18 +22,21 @@ export class TextureAssetLoader extends AssetLoader {
             } else {
                 //seems ok
                 fileExtension = match[1];
+                is_data_uri = true;
             }
 
         }
 
+        const resolved_path = is_data_uri ? path : this.resolvePath(path);
+
         const lowerCaseExtension = fileExtension.toLowerCase();
         switch (lowerCaseExtension) {
             case  'dds':
-                loadDDSTexture(path, success, failure, progress);
+                loadDDSTexture(resolved_path, success, failure, progress);
                 break;
             case 'png':
             case 'jpg':
-                loadStandardImageTexture(path, success, failure, progress);
+                loadStandardImageTexture(resolved_path, success, failure, progress);
                 break;
             default:
                 throw new Error(`Unsupported texture file format: '${lowerCaseExtension}'`);

package/src/engine/asset/preloader/AssetPreloader.js

@@ -41,7 +41,7 @@ export class AssetPreloader {
      * @return {number}
      */
     get totalAssetCount() {
-        return this.#asset_count++;
+        return this.#asset_count;
     }
 
     /**

package/src/engine/control/first-person/DESIGN.md

@@ -537,7 +537,7 @@ For landing recovery, use the same form with `zeta = 0.55` so it overshoots once
 ### 5.4 Edge cases and rules
 
 - **Look-pitch clamp** is *non-wrapping*: the pitch is stored as a separate scalar so it cannot accidentally roll over. Yaw on the body wraps freely.
-- **Crouch under a ceiling**: if `intent.crouch` releases but the entity cannot stand up (raycast collides), the controller *holds* crouch and exposes `state.crouchBlocked = true`. Standing happens automatically when clear. This rule lives in the controller because it's universal; the raycast itself is a service-injection point.
+- **Posture is intent-driven; ceilings only block RISING, never push you down**: low geometry constrains posture in exactly one direction. If `intent.crouch` releases but an *already-crouched* (or -prone) entity cannot grow into the taller posture (headroom up-cast collides), the controller *holds* the lower posture and exposes `state.crouchBlocked = true`; standing resumes automatically when clear. The converse is deliberately NOT done: a *standing* player who walks under a low overhang is **not** auto-crouched, and a crouching player who meets a sub-crouch overhang is **not** auto-proned. Their current-posture capsule simply doesn't fit, so the mover blocks their forward motion — "if I can't clear it, I don't move forward." Dropping to a lower stance is always the player's choice (press crouch / slide), never the ceiling's. This rule lives in the controller because it's universal; the headroom cast itself is a service-injection point.
 - **Sprint requires forward intent**: sideways-only or backwards movement should not consume exertion at sprint rates. Specifically `sprint = intent.sprint && intent.move.y > 0.5 && state.grounded`.
 - **No bob in air**: stride does not advance while `!grounded`. Phase freezes so landing doesn't re-fire a stale footstep.
 - **Jump cancel during anticipation**: if grounded becomes false during anticipation (e.g. ground pulled out), drop the queued impulse and emit `onLeaveGround{reason:"fall"}` without `onJumpStart`.

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

@@ -0,0 +1,55 @@
+/**
+ * The single source of motion-phase transition logic: given the current phase
+ * and a per-tick input snapshot, return the next phase. Pure — no side effects,
+ * no controller/runtime coupling — so it's exhaustively unit-testable.
+ *
+ * @param {number} phase current {@link MotionPhase}
+ * @param {{
+ *   grounded: boolean,          // on a walkable surface this tick (from the mover)
+ *   ascending: boolean,         // velocityY > 0 this tick
+ *   jumpEdge: boolean,          // jump pressed this tick (rising edge)
+ *   coyote: boolean,            // within the post-walk-off coyote window
+ *   anticipationDone: boolean,  // the squash timer elapsed this tick
+ * }} input
+ * @returns {number} next {@link MotionPhase}
+ */
+export function selectMotionPhase(phase: number, input: {
+    grounded: boolean;
+    ascending: boolean;
+    jumpEdge: boolean;
+    coyote: boolean;
+    anticipationDone: boolean;
+}): number;
+/**
+ * Build the shared {@link SimpleStateMachineDescription} — the declared state
+ * graph (states + valid edges). Each controller entity instantiates a
+ * {@link SimpleStateMachine} over this one description and registers its own
+ * entry/exit handlers. The transition LOGIC lives in {@link selectMotionPhase};
+ * the graph here documents and (optionally) validates the reachable edges.
+ *
+ * @returns {SimpleStateMachineDescription}
+ */
+export function buildMotionPhaseDescription(): SimpleStateMachineDescription;
+/**
+ * Drive a {@link SimpleStateMachine} one step by the pure transition logic,
+ * transitioning ONLY on an actual change so the machine's entry/exit handlers
+ * fire once per real transition (SimpleStateMachine.setState fires them on
+ * every call, including same-state — we guard that here).
+ *
+ * @param {import("../../../core/fsm/simple/SimpleStateMachine.js").SimpleStateMachine} machine
+ * @param {object} input see {@link selectMotionPhase}
+ * @returns {number} the phase after the step
+ */
+export function advanceMotionPhase(machine: import("../../../core/fsm/simple/SimpleStateMachine.js").SimpleStateMachine, input: object): number;
+export namespace MotionPhase {
+    let Grounded: number;
+    let Anticipating: number;
+    let Rising: number;
+    let Falling: number;
+}
+/** Human-readable phase names, indexed by phase id. For diagnostics. */
+export const MOTION_PHASE_NAME: string[];
+/** Shared description instance — stateless, reused by every controller entity. */
+export const MOTION_PHASE_DESCRIPTION: SimpleStateMachineDescription;
+import { SimpleStateMachineDescription } from "../../../core/fsm/simple/SimpleStateMachineDescription.js";
+//# sourceMappingURL=FirstPersonMotionPhase.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FirstPersonMotionPhase.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonMotionPhase.js"],"names":[],"mappings":"AAwCA;;;;;;;;;;;;;;GAcG;AACH,yCAVW,MAAM,SACN;IACV,QAAY,EAAE,OAAO,CAAC;IACtB,SAAa,EAAE,OAAO,CAAC;IACvB,QAAY,EAAE,OAAO,CAAC;IACtB,MAAU,EAAE,OAAO,CAAC;IACpB,gBAAoB,EAAE,OAAO,CAAC;CAC3B,GACS,MAAM,CA+BlB;AAED;;;;;;;;GAQG;AACH,+CAFa,6BAA6B,CAkBzC;AAKD;;;;;;;;;GASG;AACH,4CAJW,OAAO,gDAAgD,EAAE,kBAAkB,SAC3E,MAAM,GACJ,MAAM,CASlB;;;;;;;AAhGD,wEAAwE;AACxE,yCAAmF;AA2EnF,kFAAkF;AAClF,qEAAsE;8CAlHxB,2DAA2D"}

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

@@ -0,0 +1,134 @@
+import { SimpleStateMachineDescription } from "../../../core/fsm/simple/SimpleStateMachineDescription.js";
+
+/**
+ * Explicit ground/air/jump phase for the first-person controller.
+ *
+ * Today the controller tracks this with a handful of loose booleans
+ * (`grounded`, `inJumpAnticipation`, `midJump`, `isAscending`,
+ * `isVariableJumpCut`, `apexFired`) written by base locomotion AND by
+ * abilities, with no single owner — a fragile implicit state machine. This
+ * makes the phase EXPLICIT and the transitions a single, pure, unit-testable
+ * function, so a wrong transition (the kind that surfaces as a camera snap a
+ * frame or seconds later) is inspectable instead of smeared across the hot
+ * path.
+ *
+ * States:
+ *  - Grounded      — on a walkable surface, not committed to a jump.
+ *  - Anticipating  — grounded squash window after a jump press, before the
+ *                    impulse fires (and the coyote-jump entry from Falling).
+ *  - Rising        — airborne with upward velocity from a jump impulse.
+ *  - Falling       — airborne with non-upward velocity (apex passed, or walked
+ *                    off a ledge without jumping).
+ *
+ * Drive it with {@link advanceMotionPhase}, which only transitions on an actual
+ * change (so a SimpleStateMachine's entry/exit handlers fire once per real
+ * transition — the natural home for onLand / onLeaveGround / jump-impulse /
+ * apex side effects — rather than every tick).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const MotionPhase = {
+    Grounded: 0,
+    Anticipating: 1,
+    Rising: 2,
+    Falling: 3,
+};
+
+/** Human-readable phase names, indexed by phase id. For diagnostics. */
+export const MOTION_PHASE_NAME = ["Grounded", "Anticipating", "Rising", "Falling"];
+
+/**
+ * The single source of motion-phase transition logic: given the current phase
+ * and a per-tick input snapshot, return the next phase. Pure — no side effects,
+ * no controller/runtime coupling — so it's exhaustively unit-testable.
+ *
+ * @param {number} phase current {@link MotionPhase}
+ * @param {{
+ *   grounded: boolean,          // on a walkable surface this tick (from the mover)
+ *   ascending: boolean,         // velocityY > 0 this tick
+ *   jumpEdge: boolean,          // jump pressed this tick (rising edge)
+ *   coyote: boolean,            // within the post-walk-off coyote window
+ *   anticipationDone: boolean,  // the squash timer elapsed this tick
+ * }} input
+ * @returns {number} next {@link MotionPhase}
+ */
+export function selectMotionPhase(phase, input) {
+    switch (phase) {
+        case MotionPhase.Grounded:
+            // Grounded can always commit a jump; otherwise it only leaves the
+            // ground by losing contact (walk off a ledge).
+            if (input.jumpEdge) return MotionPhase.Anticipating;
+            return input.grounded ? MotionPhase.Grounded : MotionPhase.Falling;
+
+        case MotionPhase.Anticipating:
+            // The squash commits to the jump: it holds until the timer elapses
+            // (even if the ground slid out — rug-pull / moving platform), then
+            // the impulse fires (→ Rising).
+            return input.anticipationDone ? MotionPhase.Rising : MotionPhase.Anticipating;
+
+        case MotionPhase.Rising:
+            // A jump that bonks a ceiling or lands instantly re-grounds; else it
+            // rises until velocity stops being upward (apex → Falling).
+            if (input.grounded) return MotionPhase.Grounded;
+            return input.ascending ? MotionPhase.Rising : MotionPhase.Falling;
+
+        case MotionPhase.Falling:
+            // Coyote jump: a jump press shortly after walking off still takes.
+            // Otherwise we fall until we land.
+            if (input.jumpEdge && input.coyote) return MotionPhase.Anticipating;
+            return input.grounded ? MotionPhase.Grounded : MotionPhase.Falling;
+
+        default:
+            return phase;
+    }
+}
+
+/**
+ * Build the shared {@link SimpleStateMachineDescription} — the declared state
+ * graph (states + valid edges). Each controller entity instantiates a
+ * {@link SimpleStateMachine} over this one description and registers its own
+ * entry/exit handlers. The transition LOGIC lives in {@link selectMotionPhase};
+ * the graph here documents and (optionally) validates the reachable edges.
+ *
+ * @returns {SimpleStateMachineDescription}
+ */
+export function buildMotionPhaseDescription() {
+    const d = new SimpleStateMachineDescription();
+    d.createState(MotionPhase.Grounded);
+    d.createState(MotionPhase.Anticipating);
+    d.createState(MotionPhase.Rising);
+    d.createState(MotionPhase.Falling);
+
+    d.createEdge(MotionPhase.Grounded, MotionPhase.Anticipating);
+    d.createEdge(MotionPhase.Grounded, MotionPhase.Falling);
+    d.createEdge(MotionPhase.Anticipating, MotionPhase.Rising);
+    d.createEdge(MotionPhase.Rising, MotionPhase.Grounded);
+    d.createEdge(MotionPhase.Rising, MotionPhase.Falling);
+    d.createEdge(MotionPhase.Falling, MotionPhase.Grounded);
+    d.createEdge(MotionPhase.Falling, MotionPhase.Anticipating);
+
+    return d;
+}
+
+/** Shared description instance — stateless, reused by every controller entity. */
+export const MOTION_PHASE_DESCRIPTION = buildMotionPhaseDescription();
+
+/**
+ * Drive a {@link SimpleStateMachine} one step by the pure transition logic,
+ * transitioning ONLY on an actual change so the machine's entry/exit handlers
+ * fire once per real transition (SimpleStateMachine.setState fires them on
+ * every call, including same-state — we guard that here).
+ *
+ * @param {import("../../../core/fsm/simple/SimpleStateMachine.js").SimpleStateMachine} machine
+ * @param {object} input see {@link selectMotionPhase}
+ * @returns {number} the phase after the step
+ */
+export function advanceMotionPhase(machine, input) {
+    const current = machine.getState();
+    const next = selectMotionPhase(current, input);
+    if (next !== current) {
+        machine.setState(next);
+    }
+    return next;
+}

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

@@ -48,12 +48,13 @@ export class FirstPersonPlayerController {
                 radius: number;
                 mass: number;
                 referenceMass: number;
+                jumpPushoffDistance: number;
                 massCouplingStrength: number;
             };
             motion: {
                 walkSpeed: number;
                 sprintSpeed: number;
-                crouchSpeed: number;
+                crouchSpeed: number; /** Set true when crouch was released but a ceiling above prevents standing. */
                 airControl: number;
                 groundAccelHalfLife: number;
                 groundDecel: number;
@@ -95,12 +96,31 @@ export class FirstPersonPlayerController {
                 exertionRiseRate: number;
                 minAirborneTime: number;
                 mantleUpUpFactor: number;
+                shimmySpeed: number;
+                pullUpFacingConeDeg: number;
+                moveTowardThreshold: number;
+                moveAwayThreshold: number;
+                regrabCooldown: number;
+                shimmyLateralMin: number;
+                shimmyClearanceGap: number;
+                shimmyClearanceProbeY: number;
+                shimmyEdgeProbeForward: number;
+                shimmyContinuityProbeUp: number;
+                shimmyContinuityProbeDown: number;
+                shimmyContinuityTol: number;
+                shimmyExertionFactor: number;
             };
             mantle: {
                 minHeight: number;
                 maxHeight: number;
                 duration: number;
                 forwardOffsetOnLand: number;
+                pullUpMaxHeight: number;
+                vaultDistance: number;
+                vaultApexClearance: number;
+                vaultDropOnExit: number;
+                vaultExitSpeed: number;
+                vaultExitDownSpeed: number;
             };
             wallRun: {
                 minSpeed: number;
@@ -185,6 +205,7 @@ export class FirstPersonPlayerController {
                 pitchMinDeg: number;
                 pitchMaxDeg: number;
                 invertY: boolean;
+                maxFrameDeltaRad: number;
             };
             posture: {
                 sprintForwardPitchDeg: number;
@@ -308,7 +329,7 @@ declare class FirstPersonSignals {
     onBreathOut: Signal<any, any, any, any, any, any, any, any>;
     /** {ledgeHeight:number} — fired when LedgeGrab activates. */
     onLedgeGrab: Signal<any, any, any, any, any, any, any, any>;
-    /** {reason:"mantle-up"|"drop"|"slip"|"shuffle-off"} */
+    /** {reason:"mantle-up"|"vault"|"drop"|"slip"|"shuffle-off"} */
     onLedgeRelease: Signal<any, any, any, any, any, any, any, any>;
 }
 import { MasterySet } from "./mastery/MasterySet.js";

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

@@ -1 +1 @@
-{"version":3,"file":"FirstPersonPlayerController.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerController.js"],"names":[],"mappings":"AA8HA;;;;;;;;;;GAUG;AACH;IACI,wBAAgD;IAG5C,0CAAqD;IACrD,0BAAqC;IACrC,wBAAmC;IACnC,sBAAiC;IACjC,4BAAuC;IAEvC;;;;;;OAMG;IACH,SAFU,UAAU,CAEW;IAE/B;;;;;OAKG;IACH,WAFU,UAAU,CAEa;IAEjC;;;;;;OAMG;IACH,WAFU,MAAM,CAEG;IAGvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAEC;IAED,0BAIC;IAED;;OAEG;IACH,YAFW,2BAA2B,QAKrC;IAED,qCAIC;IAED,4BAGC;IAED,eAGC;CACJ;;;;;kDA3MiD,wCAAwC;AAK1F;;;;;;;;GAQG;AACH;IACI,oEAAoE;IACpE,MADyD,OAAO,CACvC;IAEzB;;;;OAIG;IACH,MAFU,OAAO,CAEQ;IAEzB,mEAAmE;IACnE,MADwD,OAAO,CAClD;IAEb,0EAA0E;IAC1E,QAD+D,OAAO,CACvD;IAEf,qEAAqE;IACrE,QAD0D,OAAO,CAClD;CAClB;AAED;;;GAGG;AACH;IACI,kBAAgB;IAChB,0BAAsB;IAEtB,4EAA4E;IAC5E,sBAAoC;IACpC,gBAAkB;IAElB,cAAU;IACV,4DAA4D;IAC5D,wBAAoB;IACpB,yEAAyE;IACzE,uBAAgD;IAEhD,sBAAkB;IAClB,qBAAiB;IACjB,qBAAiB;IAEjB,4BAAwB;IACxB,4BAA2B;IAC3B,2BAA0B;IAC1B,2EAA2E;IAC3E,qBAAoB;IAEpB,iBAAa;IACb,oBAAgB;IAChB,qBAAiB;IACjB,yBAAqB;IAErB,oBAAgB;IAChB,kBAAc;IACd,kDAAkD;IAClD,iBAAa;IAEb,kBAAiB;IAEjB,+EAA+E;IAC/E,uBAAsB;IACtB,6EAA6E;IAC7E,sBAAqB;IAErB;;;;;;;OAOG;IACH,SAFU,MAAM,CAEmB;IAEnC,oBAAgB;CACnB;gCAzFkF,2BAA2B;AA2F9G;;;GAGG;AACH;IACI,uDAAuD;IACvD,2DAA0B;IAC1B,yEAAyE;IACzE,4DAA2B;IAC3B,kBAAkB;IAClB,2DAA0B;IAC1B,6BAA6B;IAC7B,8DAA6B;IAC7B,iDAAiD;IACjD,uDAAsB;IACtB,8DAA6B;IAC7B,6DAA4B;IAC5B,8DAA6B;IAC7B,6DAA4B;IAC5B,2EAA2E;IAC3E,2DAA0B;IAC1B,2EAA2E;IAC3E,4DAA2B;IAC3B,6DAA6D;IAC7D,4DAA2B;IAC3B,uDAAuD;IACvD,+DAA8B;CACjC;2BAvH0B,yBAAyB;2BAFzB,2BAA2B;uCAG6B,2BAA2B;0CAA3B,2BAA2B;oBAL1F,+BAA+B;oBAC/B,+BAA+B;mBAFhC,uCAAuC"}
+{"version":3,"file":"FirstPersonPlayerController.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerController.js"],"names":[],"mappings":"AA8HA;;;;;;;;;;GAUG;AACH;IACI,wBAAgD;IAG5C,0CAAqD;IACrD,0BAAqC;IACrC,wBAAmC;IACnC,sBAAiC;IACjC,4BAAuC;IAEvC;;;;;;OAMG;IACH,SAFU,UAAU,CAEW;IAE/B;;;;;OAKG;IACH,WAFU,UAAU,CAEa;IAEjC;;;;;;OAMG;IACH,WAFU,MAAM,CAEG;IAGvB;;;;;;;;;;;;;;;qCA/FA,+EAA+E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAiG9E;IAED,0BAIC;IAED;;OAEG;IACH,YAFW,2BAA2B,QAKrC;IAED,qCAIC;IAED,4BAGC;IAED,eAGC;CACJ;;;;;kDA3MiD,wCAAwC;AAK1F;;;;;;;;GAQG;AACH;IACI,oEAAoE;IACpE,MADyD,OAAO,CACvC;IAEzB;;;;OAIG;IACH,MAFU,OAAO,CAEQ;IAEzB,mEAAmE;IACnE,MADwD,OAAO,CAClD;IAEb,0EAA0E;IAC1E,QAD+D,OAAO,CACvD;IAEf,qEAAqE;IACrE,QAD0D,OAAO,CAClD;CAClB;AAED;;;GAGG;AACH;IACI,kBAAgB;IAChB,0BAAsB;IAEtB,4EAA4E;IAC5E,sBAAoC;IACpC,gBAAkB;IAElB,cAAU;IACV,4DAA4D;IAC5D,wBAAoB;IACpB,yEAAyE;IACzE,uBAAgD;IAEhD,sBAAkB;IAClB,qBAAiB;IACjB,qBAAiB;IAEjB,4BAAwB;IACxB,4BAA2B;IAC3B,2BAA0B;IAC1B,2EAA2E;IAC3E,qBAAoB;IAEpB,iBAAa;IACb,oBAAgB;IAChB,qBAAiB;IACjB,yBAAqB;IAErB,oBAAgB;IAChB,kBAAc;IACd,kDAAkD;IAClD,iBAAa;IAEb,kBAAiB;IAEjB,+EAA+E;IAC/E,uBAAsB;IACtB,6EAA6E;IAC7E,sBAAqB;IAErB;;;;;;;OAOG;IACH,SAFU,MAAM,CAEmB;IAEnC,oBAAgB;CACnB;gCAzFkF,2BAA2B;AA2F9G;;;GAGG;AACH;IACI,uDAAuD;IACvD,2DAA0B;IAC1B,yEAAyE;IACzE,4DAA2B;IAC3B,kBAAkB;IAClB,2DAA0B;IAC1B,6BAA6B;IAC7B,8DAA6B;IAC7B,iDAAiD;IACjD,uDAAsB;IACtB,8DAA6B;IAC7B,6DAA4B;IAC5B,8DAA6B;IAC7B,6DAA4B;IAC5B,2EAA2E;IAC3E,2DAA0B;IAC1B,2EAA2E;IAC3E,4DAA2B;IAC3B,6DAA6D;IAC7D,4DAA2B;IAC3B,+DAA+D;IAC/D,+DAA8B;CACjC;2BAvH0B,yBAAyB;2BAFzB,2BAA2B;uCAG6B,2BAA2B;0CAA3B,2BAA2B;oBAL1F,+BAA+B;oBAC/B,+BAA+B;mBAFhC,uCAAuC"}

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

@@ -120,7 +120,7 @@ class FirstPersonSignals {
     onBreathOut = new Signal();
     /** {ledgeHeight:number} — fired when LedgeGrab activates. */
     onLedgeGrab = new Signal();
-    /** {reason:"mantle-up"|"drop"|"slip"|"shuffle-off"} */
+    /** {reason:"mantle-up"|"vault"|"drop"|"slip"|"shuffle-off"} */
     onLedgeRelease = new Signal();
 }