@woosh/meep-engine 2.143.0 → 2.145.0

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

@@ -56,14 +56,30 @@ export class FirstPersonPlayerControllerSystem extends System<any, any, any, any
      */
     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.
+     * PhysicsSystem reference. Auto-acquired at startup; can be
+     * overridden by the caller. When present, collision is resolved
+     * by the {@link KinematicMover}; when null, the controller uses
+     * the flat-ground integrator ({@link _moveFlatGround}) — useful
+     * for spec setups that don't wire physics.
      * @type {PhysicsSystem|null}
      */
     physicsSystem: PhysicsSystem | null;
+    /**
+     * The collision solver — the authoritative move resolver whenever
+     * a {@link PhysicsSystem} is present (recover + unified
+     * sweep-and-slide + ground-categorize; see DESIGN_COLLISION.md).
+     * Lazily built on first use. With no physics the controller falls
+     * back to a flat-ground integrator ({@link _moveFlatGround}).
+     * @private
+     * @type {KinematicMover|null}
+     */
+    private _mover;
+    /** @private Scratch velocity handed to the mover each tick. */
+    private _moverVelocity;
+    /** @private Scratch for the posture-headroom up-cast. */
+    private _postureRay;
+    /** @private @type {PhysicsSurfacePoint} */
+    private _postureHit;
     startup(entityManager: any): Promise<void>;
     /**
      * @param {FirstPersonPlayerController} controller
@@ -117,7 +133,27 @@ export class FirstPersonPlayerControllerSystem extends System<any, any, any, any
      * @private
      */
     private _syncColliderShape;
-    _resolveCrouchHeld(controller: any, runtime: any): any;
+    _resolveCrouchHeld(controller: any, runtime: any, bodyTransform: any): any;
+    /**
+     * Headroom probe for a posture change that GROWS the collider.
+     * Sweeps `fromShape` (the shorter posture's capsule) straight up by
+     * `growDelta` (the height the collider would gain). A hit means an
+     * overhang occupies the space the taller posture needs, so the grow
+     * is blocked. Returns true (clear) when no physics is wired or the
+     * grow is non-positive.
+     *
+     * Why an up-cast rather than an overlap-test of the taller shape:
+     * overlap would false-positive on a wall *beside* the player. The
+     * up-cast sweeps parallel to (and, per the mover's skin clearance,
+     * clear of) lateral walls so they aren't hit; the floor is below
+     * the rising probe; the player's own body is filtered out. Only
+     * genuine overhead geometry blocks the grow. Relies on the player
+     * resting at `floor+skin` (the mover's stick-to-ground), so the
+     * probe's bottom starts clear of the floor.
+     *
+     * @private
+     */
+    private _hasHeadroomToGrow;
     /**
      * Jump finite-state-machine: button-edge detection, buffer + coyote
      * grace, anticipation timer, impulse on completion. Variable-height
@@ -132,48 +168,12 @@ export class FirstPersonPlayerControllerSystem extends System<any, any, any, any
      */
     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
-     * detection. The full vertical phase of one fixed step.
-     *
-     * The built-in flat-floor branch only runs when `useBuiltInFlatGround`
-     * is true (the prototype's standalone mode); with an external physics
-     * layer attached the system relies on the layer to set `state.grounded`
-     * and only maintains airborne/grounded timers here.
+     * The vertical + collision phase of one fixed step: apply gravity
+     * (the motor), resolve the move against the world, then detect the
+     * jump apex. Collision resolution is the {@link KinematicMover} when
+     * a physics layer is present; otherwise a lightweight flat-ground
+     * integrator for headless / unit-test scenes with no collidable
+     * geometry. Land / leave-ground events flow identically from either.
      *
      * @private
      * @param {FirstPersonPlayerController} controller
@@ -182,6 +182,62 @@ export class FirstPersonPlayerControllerSystem extends System<any, any, any, any
      * @param {number} dt
      */
     private _integrateVerticalAndResolveGround;
+    /**
+     * Resolve the current `runtime.velocity*` against the world — the
+     * physics-backed {@link KinematicMover} (recover + sweep-and-slide +
+     * ground-categorize) when a PhysicsSystem is present, else the no-physics
+     * flat-ground fallback. Gravity is NOT applied here: the standard path
+     * applies it in {@link _applyGravity} just before, and abilities with a
+     * non-standard vertical model (WallRun's reduced gravity) apply their own
+     * and then call this directly — so motion routes through one motor for
+     * everyone (sweep-and-slide, anti-tunnel, land/leave events) rather than
+     * a bespoke `position._add` + hand-rolled ground-catch.
+     * @private
+     */
+    private _resolveMotion;
+    /**
+     * Motor: integrate gravity into `velocityY` with the fall / variable-
+     * cut multipliers. The mover never invents motion, so gravity lives
+     * here (callable by abilities that want standard gravity too).
+     * @private
+     */
+    private _applyGravity;
+    /**
+     * Resolve the move against the world via {@link KinematicMover}
+     * (recover + unified sweep-and-slide + ground-categorize), then map
+     * the result back to controller state and land / leave events.
+     * @private
+     */
+    private _moveViaMover;
+    /**
+     * No-physics fallback: integrate the velocity directly (there's no
+     * collidable geometry to sweep against) and resolve the floor from
+     * the built-in flat ground and/or the host `groundResolver`. For
+     * headless scenes and control-layer unit tests. With both ground
+     * sources off, an external physics layer is expected to own
+     * `state.grounded`; we only advance timers.
+     * @private
+     */
+    private _moveFlatGround;
+    /**
+     * Landing transition: dip / impact springs, exertion impulse, flag
+     * resets, and the `onLand` signal (fired LAST so handlers see fully-
+     * reacted state). Shared by both move paths. `impactVy` is the
+     * downward speed at touchdown (positive).
+     * @private
+     */
+    private _onLand;
+    /**
+     * Leave-ground transition: `onLeaveGround` signal + takeoff bookkeeping.
+     * Shared by both move paths.
+     * @private
+     */
+    private _onLeaveGround;
+    /**
+     * Fire `onJumpApex` once, when an in-progress jump stops rising.
+     * @private
+     */
+    private _detectJumpApex;
     /**
      * Run the base (no-ability) L1 locomotion phases: speed selection,
      * desired-velocity computation, accel/decel, jump FSM, gravity, body
@@ -264,16 +320,6 @@ declare class PerEntityRuntime {
      * @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}`

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":"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"}
+{"version":3,"file":"FirstPersonPlayerControllerSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerControllerSystem.js"],"names":[],"mappings":"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"}