@woosh/meep-engine 2.139.0 → 2.140.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> | ResourceAccessSpecification<typeof RigidBody>)[];
+    components_used: (ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof Camera>)[];
     /**
      * Per-entity runtime, keyed by entity id.
      * @type {Map<number, PerEntityRuntime>}
@@ -55,6 +55,16 @@ export class FirstPersonPlayerControllerSystem extends System<any, any, any, any
      * @type {((x:number, y:number, z:number) => number|null) | null}
      */
     groundResolver: (x: number, y: number, z: number) => number | null;
+    /**
+     * PhysicsSystem reference used by {@link _moveAndSlide}. Auto-
+     * acquired at startup; can be overridden by the caller. When
+     * null (no physics in the world), move-and-slide degrades to a
+     * direct position add — useful for spec setups that don't wire
+     * physics.
+     * @type {PhysicsSystem|null}
+     */
+    physicsSystem: PhysicsSystem | null;
+    startup(entityManager: any): Promise<void>;
     /**
      * @param {FirstPersonPlayerController} controller
      * @param {Transform} bodyTransform
@@ -91,7 +101,23 @@ export class FirstPersonPlayerControllerSystem extends System<any, any, any, any
      * @param {PerEntityRuntime} runtime
      * @returns {boolean}
      */
-    private _resolveCrouchHeld;
+    /**
+     * Swap {@link Collider.shape} to the pre-built capsule that matches
+     * the player's current posture. Cheap — just a reference swap when
+     * the posture changed, no-op otherwise. The pre-built shapes live
+     * on the runtime (see {@link PerEntityRuntime.colliderShapeStand}
+     * etc.) so this method allocates nothing per tick.
+     *
+     * Hang posture reuses Stand: the player's body is full-extent,
+     * hanging below the ledge — the rig handles the arms-up animation,
+     * but the collision volume is unchanged. If a game ever wants a
+     * narrower hang silhouette (e.g. wedging into a chimney) it can
+     * add a `colliderShapeHang` and route here.
+     *
+     * @private
+     */
+    private _syncColliderShape;
+    _resolveCrouchHeld(controller: any, runtime: any): any;
     /**
      * Jump finite-state-machine: button-edge detection, buffer + coyote
      * grace, anticipation timer, impulse on completion. Variable-height
@@ -105,6 +131,40 @@ export class FirstPersonPlayerControllerSystem extends System<any, any, any, any
      * @param {number} dt
      */
     private _advanceJumpFsm;
+    /**
+     * Sweep the player's collider along (dx, dy, dz) via
+     * {@link PhysicsSystem.shapeCast} and translate the Transform up to
+     * (but not past) the first contact. Prevents tunneling through
+     * static geometry and creep-penetration over many ticks.
+     *
+     * v1 limitations:
+     *   - The broadphase shape-cast returns the back-along-the-sweep
+     *     normal (`−direction`), not the true surface normal. With
+     *     that, the principled "slide along the surface" residual is
+     *     `delta -= dot(delta, n)·n = 0` — i.e. the player stops at
+     *     contact instead of sliding tangent to the wall. Once
+     *     narrowphase refinement lands and `result.normal` becomes the
+     *     true surface normal, the same residual computation will
+     *     naturally produce sliding without an API change.
+     *   - SKIN clearance (5 mm) keeps the player just shy of the wall
+     *     so the next cast doesn't start with the capsule already in
+     *     contact. Picking this too small risks GJK reporting `t = 0`
+     *     and the player getting stuck; too large is visible as a gap.
+     *
+     * Falls through to a direct position add when the host hasn't
+     * wired a {@link PhysicsSystem} — useful for spec setups that
+     * don't bring physics up.
+     *
+     * @private
+     * @param {PerEntityRuntime} runtime
+     * @param {Transform} bodyTransform
+     * @param {number} deltaX
+     * @param {number} deltaY
+     * @param {number} deltaZ
+     * @returns {boolean} true if a contact occurred (and the sweep was
+     *     truncated); false on a clean full advance.
+     */
+    private _moveAndSlide;
     /**
      * Gravity (with fall and cut multipliers), vertical integration,
      * built-in flat-floor resolution (land event + impulse), and jump-apex
@@ -178,9 +238,9 @@ export class FirstPersonPlayerControllerSystem extends System<any, any, any, any
 import { System } from "../../ecs/System.js";
 import { Transform } from "../../ecs/transform/Transform.js";
 import { FirstPersonPlayerController } from "./FirstPersonPlayerController.js";
+import { RigidBody } from "../../physics/ecs/RigidBody.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
@@ -197,6 +257,42 @@ declare class PerEntityRuntime {
      * @type {RigidBody|null}
      */
     rigidBody: RigidBody | null;
+    /**
+     * Co-attached collider, cached at link. Same source the physics
+     * narrowphase uses, so move-and-slide casts the player's
+     * actual collision shape against the world.
+     * @type {Collider|null}
+     */
+    collider: Collider | null;
+    /**
+     * Pre-allocated move-and-slide scratch — Ray3 and PhysicsSurfacePoint
+     * reused per cast so the controller doesn't churn the allocator
+     * each fixed step. Lazily filled by {@link _moveAndSlide}.
+     * @private
+     * @type {Ray3|null}
+     */
+    private slideRay;
+    /** @private @type {PhysicsSurfacePoint|null} */
+    private slideHit;
+    /**
+     * Pre-built capsule colliders, one per posture. Cached at link
+     * from `config.body.{height, crouchHeight, proneHeight, radius}`
+     * so {@link _syncColliderShape} can swap the collider's shape on
+     * a posture change with zero per-tick allocation. Hang reuses
+     * Stand (the player's body is full-extent, just hanging below
+     * the ledge — the rig animates the arms-up pose). Sentinel
+     * `lastPosture = -1` forces a sync on the first tick after
+     * link, so the initial shape always matches Stand.
+     * @private
+     * @type {TransformedShape3D|null}
+     */
+    private colliderShapeStand;
+    /** @private @type {TransformedShape3D|null} */
+    private colliderShapeCrouch;
+    /** @private @type {TransformedShape3D|null} */
+    private colliderShapeProne;
+    /** @private */
+    private lastPosture;
     /** Eye pitch in radians, clamped to config.look limits. */
     eyePitch: number;
     /** Body yaw in radians (around world up). */
@@ -342,6 +438,8 @@ declare class PerEntityRuntime {
     /** Cached eye entity ID. -1 until link assigns it. */
     eyeEntity: number;
 }
+import { PhysicsSystem } from "../../physics/ecs/PhysicsSystem.js";
+import { Collider } from "../../physics/ecs/Collider.js";
 import { Spring } from "./math/Spring.js";
 import { EyeOffsetStack } from "./composer/EyeOffsetStack.js";
 import { FirstPersonSensors } from "./sensors/FirstPersonSensors.js";

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":"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"}
+{"version":3,"file":"FirstPersonPlayerControllerSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerControllerSystem.js"],"names":[],"mappings":"AA0TA;;;;;;;;;;;;;;;;;GAiBG;AACH;IACI,cAiEC;IAxDG,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;IAE1B;;;;;;;OAOG;IACH,eAFU,aAAa,GAAC,IAAI,CAEH;IAG7B,2CAMC;IAED;;;;OAIG;IACH,iBAJW,2BAA2B,iBAC3B,SAAS,UACT,MAAM,QAuGhB;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,oBAyUC;IAED;;;;;OAKG;IACH;;;;;;;;;;;;;;OAcG;IACH,2BAaC;IAED,uDAeC;IAED;;;;;;;;;;;OAWG;IACH,wBA0EC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,sBAgGC;IAED;;;;;;;;;;;;;;;OAeG;IACH,2CAuHC;IAED;;;;;;;;;;;;;;OAcG;IACH,2BA6HC;IAED;;;;;;;;;;;;;;;OAeG;IACH,kCAsDC;IAED;;;;;;;;;;OAUG;IACH,qBA8CC;IAED;;;;;OAKG;IACH,oBA4JC;CACJ;uBA5sDsB,qBAAqB;0BAClB,kCAAkC;4CAWhB,kCAAkC;0BAFpD,gCAAgC;4CAbd,oDAAoD;uBAKzE,qCAAqC;AA+E5D;;;;;GAKG;AACH;IAEQ;;;;;;;OAOG;IACH,WAFU,SAAS,GAAC,IAAI,CAEH;IAErB;;;;;OAKG;IACH,UAFU,QAAQ,GAAC,IAAI,CAEH;IAEpB;;;;;;OAMG;IACH,iBAAoB;IACpB,gDAAgD;IAChD,iBAAoB;IAEpB;;;;;;;;;;;OAWG;IACH,2BAA8B;IAC9B,+CAA+C;IAC/C,4BAA+B;IAC/B,+CAA+C;IAC/C,2BAA8B;IAC9B,eAAe;IACf,oBAAqB;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;8BArS6B,oCAAoC;yBADzC,+BAA+B;uBASjC,kBAAkB;+BAdV,8BAA8B;mCAkB1B,iCAAiC"}