@jgengine/core 0.18.0 → 0.19.0

package/dist/movement/movementModel.d.ts

@@ -1,3 +1,4 @@
+import type { InputBuffer } from "../input/inputBuffer.js";
 /**
  * Movement core (pure model).
  *
@@ -83,6 +84,16 @@ export interface PlayerMotionState {
     jumpOffset: number;
     grounded: boolean;
     jumpHeld: boolean;
+    /** Integrated time, ms; the clock jump buffering and coyote time read. */
+    clockMs: number;
+    /** `clockMs` of the last grounded frame; `null` after a jump spends it. */
+    groundedAtMs: number | null;
+    /** `clockMs` of the last landing; `null` before the first. */
+    landedAtMs: number | null;
+    /** Rising from the player's own jump, so releasing jump may cut it. */
+    jumpRising: boolean;
+    /** Ended the last frame in the air. */
+    wasAirborne: boolean;
 }
 /** @internal */
 export declare function createPlayerMotionState(): PlayerMotionState;
@@ -100,6 +111,32 @@ export interface MovementTuningOverrides {
     jumpVelocity?: number;
     /** Fraction of walk speed while backpedalling; overrides {@link MOVEMENT_TUNING.backpedalSpeedMultiplier}. */
     backpedalSpeedMultiplier?: number;
+    /** Ground velocity response, 1/s: how fast the body reaches its target velocity (default 26). */
+    groundAcceleration?: number;
+    /** Air velocity response, 1/s: air control (default 12; `0` locks the jump arc). */
+    airAcceleration?: number;
+    /** Ground stopping response with no input, 1/s (default 18; lower slides). */
+    groundFriction?: number;
+    /** Sprint speed as a multiple of walk speed (default 2.25). */
+    runSpeedMultiplier?: number;
+    /** Crouch speed as a multiple of walk speed (default 0.45). */
+    crouchSpeedMultiplier?: number;
+    /** A jump pressed up to this many ms before landing still fires on landing (default 0). Needs {@link MotionFrameOptions.buffer}. */
+    jumpBufferMs?: number;
+    /** A jump pressed up to this many ms after walking off a ledge still fires (default 0). */
+    coyoteMs?: number;
+    /** Rising speed kept when jump is released early, 0..1 (default 1: no cut). Lower makes a tap a hop. */
+    jumpCutFactor?: number;
+    /** Gravity multiplier near the peak, while vertical speed is under {@link MovementTuningOverrides.apexSpeed} (default 1). */
+    apexGravityScale?: number;
+    /** Vertical speed under which the apex gravity scale applies, m/s (default 1.5). */
+    apexSpeed?: number;
+    /** Gravity multiplier while falling (default 1). Above 1 drops faster than it rose. */
+    fallGravityScale?: number;
+    /** After landing, jumps wait and walk speed ramps back from {@link MovementTuningOverrides.landingSpeedScale} over this many ms (default 0). */
+    landingRecoveryMs?: number;
+    /** Walk speed share right after landing when `landingRecoveryMs` is set (default 0.5). */
+    landingSpeedScale?: number;
 }
 /**
  * Per-frame dynamic modifiers for {@link advancePlayerMotion} — state the caller
@@ -111,6 +148,8 @@ export interface MotionFrameOptions {
     speedScale?: number;
     /** Suppress gravity/jump integration and hold the avatar afloat this frame (e.g. swimming). Default false. */
     floating?: boolean;
+    /** Buffers jump presses for `jumpBufferMs`. Without it a jump fires only on the press frame. */
+    buffer?: InputBuffer;
 }
 /**
  * Advance one frame of avatar kinematics. Mutates `motion` (velocity, jump,

package/dist/movement/movementModel.js

@@ -1,15 +1,3 @@
-/**
- * Movement core (pure model).
- *
- * This module owns the raw key model, the pure translation from held keys
- * into a frame-independent {@link MovementIntent}, and the kinematics
- * integration. Keeping it framework-free means the kinematics controller,
- * the keyboard handler and the on-screen touch D-pad all speak the same
- * vocabulary, and the translation is unit testable without a renderer.
- * DOM capture lives in `@jgengine/shell`'s GamePlayerShell (keyboard and
- * touch controls) and its camera rigs (pointer lock, the per-frame look
- * channel).
- */
 /** @internal */
 export function createEmptyMovementKeys() {
     return { w: false, a: false, s: false, d: false, shift: false, control: false, c: false, space: false };
@@ -90,9 +78,9 @@ export const MOVEMENT_TUNING = {
 function resolveTargetSpeed(intent, baseSpeed, tuning) {
     const backpedal = tuning?.backpedalSpeedMultiplier ?? MOVEMENT_TUNING.backpedalSpeedMultiplier;
     const speedMultiplier = intent.crouching
-        ? MOVEMENT_TUNING.crouchSpeedMultiplier
+        ? (tuning?.crouchSpeedMultiplier ?? MOVEMENT_TUNING.crouchSpeedMultiplier)
         : intent.running
-            ? MOVEMENT_TUNING.runSpeedMultiplier
+            ? (tuning?.runSpeedMultiplier ?? MOVEMENT_TUNING.runSpeedMultiplier)
             : intent.forward < 0
                 ? backpedal
                 : 1;
@@ -107,6 +95,11 @@ export function createPlayerMotionState() {
         jumpOffset: 0,
         grounded: true,
         jumpHeld: false,
+        clockMs: 0,
+        groundedAtMs: 0,
+        landedAtMs: null,
+        jumpRising: false,
+        wasAirborne: false,
     };
 }
 /**
@@ -122,7 +115,19 @@ export function createPlayerMotionState() {
   */
 export function advancePlayerMotion(motion, intent, forwardX, forwardZ, baseSpeed, rawDeltaSeconds, tuning, options) {
     const deltaSeconds = Math.min(rawDeltaSeconds, MOVEMENT_TUNING.maxFrameSeconds);
-    const targetSpeed = resolveTargetSpeed(intent, baseSpeed, tuning) * (options?.speedScale ?? 1);
+    const now = (motion.clockMs ?? 0) + deltaSeconds * 1000;
+    motion.clockMs = now;
+    if (motion.grounded && motion.wasAirborne)
+        motion.landedAtMs = now;
+    const airborneAtStart = !motion.grounded;
+    const landingRecoveryMs = tuning?.landingRecoveryMs ?? 0;
+    const landedAtMs = motion.landedAtMs ?? null;
+    const recovery = landingRecoveryMs > 0 && motion.grounded && landedAtMs !== null && now - landedAtMs < landingRecoveryMs
+        ? (now - landedAtMs) / landingRecoveryMs
+        : 1;
+    const landingSpeedScale = tuning?.landingSpeedScale ?? 0.5;
+    const recoverySpeedScale = landingSpeedScale + (1 - landingSpeedScale) * recovery;
+    const targetSpeed = resolveTargetSpeed(intent, baseSpeed, tuning) * (options?.speedScale ?? 1) * recoverySpeedScale;
     const gravityAcceleration = tuning?.gravityAcceleration ?? MOVEMENT_TUNING.gravityAcceleration;
     const jumpVelocity = tuning?.jumpVelocity ?? MOVEMENT_TUNING.jumpVelocity;
     let targetVelocityX = 0;
@@ -161,29 +166,64 @@ export function advancePlayerMotion(motion, intent, forwardX, forwardZ, baseSpee
             targetVelocityZ = 0;
         }
     }
-    const acceleration = motion.grounded ? MOVEMENT_TUNING.groundAcceleration : MOVEMENT_TUNING.airAcceleration;
+    const acceleration = motion.grounded
+        ? (tuning?.groundAcceleration ?? MOVEMENT_TUNING.groundAcceleration)
+        : (tuning?.airAcceleration ?? MOVEMENT_TUNING.airAcceleration);
     const accelerationBlend = 1 - Math.exp(-acceleration * deltaSeconds);
     motion.horizontalVelocityX += (targetVelocityX - motion.horizontalVelocityX) * accelerationBlend;
     motion.horizontalVelocityZ += (targetVelocityZ - motion.horizontalVelocityZ) * accelerationBlend;
     if (!intent.moving && motion.grounded) {
-        const friction = Math.exp(-MOVEMENT_TUNING.groundFriction * deltaSeconds);
+        const friction = Math.exp(-(tuning?.groundFriction ?? MOVEMENT_TUNING.groundFriction) * deltaSeconds);
         motion.horizontalVelocityX *= friction;
         motion.horizontalVelocityZ *= friction;
     }
     const floating = options?.floating === true;
     const jumpPressed = intent.jumping;
-    if (jumpPressed && !motion.jumpHeld && motion.grounded && !intent.crouching && !floating) {
+    if (motion.grounded)
+        motion.groundedAtMs = now;
+    const coyoteMs = tuning?.coyoteMs ?? 0;
+    const groundedAtMs = motion.groundedAtMs ?? null;
+    const canJump = !intent.crouching &&
+        !floating &&
+        recovery >= 1 &&
+        (motion.grounded ||
+            (coyoteMs > 0 && motion.verticalVelocity <= 0 && groundedAtMs !== null && now - groundedAtMs <= coyoteMs));
+    const pressEdge = jumpPressed && !motion.jumpHeld;
+    const buffer = options?.buffer;
+    if (buffer !== undefined) {
+        if (pressEdge)
+            buffer.press("jump", now);
+        else if (!jumpPressed && motion.jumpHeld)
+            buffer.release("jump", now);
+    }
+    const jump = canJump && (buffer === undefined ? pressEdge : buffer.consume("jump", now, tuning?.jumpBufferMs ?? 0));
+    if (jump) {
         motion.verticalVelocity = jumpVelocity;
         motion.grounded = false;
+        motion.groundedAtMs = null;
+        motion.jumpRising = true;
+    }
+    else if (motion.jumpRising && !jumpPressed && motion.jumpHeld && motion.verticalVelocity > 0) {
+        motion.verticalVelocity *= Math.max(0, Math.min(1, tuning?.jumpCutFactor ?? 1));
+        motion.jumpRising = false;
     }
     motion.jumpHeld = jumpPressed;
     if (floating) {
         motion.verticalVelocity = 0;
         motion.jumpOffset = 0;
         motion.grounded = true;
+        motion.jumpRising = false;
     }
     else if (!motion.grounded || motion.verticalVelocity > 0) {
-        motion.verticalVelocity -= gravityAcceleration * deltaSeconds;
+        const apexSpeed = tuning?.apexSpeed ?? 1.5;
+        const gravityScale = Math.abs(motion.verticalVelocity) < apexSpeed
+            ? (tuning?.apexGravityScale ?? 1)
+            : motion.verticalVelocity < 0
+                ? (tuning?.fallGravityScale ?? 1)
+                : 1;
+        motion.verticalVelocity -= gravityAcceleration * gravityScale * deltaSeconds;
+        if (motion.verticalVelocity <= 0)
+            motion.jumpRising = false;
         motion.jumpOffset += motion.verticalVelocity * deltaSeconds;
         if (motion.jumpOffset <= 0) {
             motion.jumpOffset = 0;
@@ -191,6 +231,9 @@ export function advancePlayerMotion(motion, intent, forwardX, forwardZ, baseSpee
             motion.grounded = true;
         }
     }
+    if (airborneAtStart && motion.grounded)
+        motion.landedAtMs = now;
+    motion.wasAirborne = !motion.grounded;
     return {
         stepX: motion.horizontalVelocityX * deltaSeconds,
         stepZ: motion.horizontalVelocityZ * deltaSeconds,

package/dist/movement/movementProbe.d.ts

@@ -0,0 +1,51 @@
+import type { PhysicsConfig } from "../game/defineGame.js";
+import type { PlayerMovementConfig } from "../game/playableGame.js";
+/** The walk character {@link measureMovement} drives: the same fields a game passes to `defineGame`. */
+export interface MovementProbeSubject {
+    /** `defineGame({ movement })`; `feel` and `backpedalMult` shape the walk. */
+    movement?: PlayerMovementConfig;
+    /** `defineGame({ physics })`; `gravity` and `jumpVelocity` shape the jump. */
+    physics?: PhysicsConfig;
+    /** The player entity's `movement.walkSpeed` (default `2`, the controller default). */
+    walkSpeed?: number;
+}
+/** Scenario settings for {@link measureMovement}; every field has a default. */
+export interface MovementProbeOptions {
+    /** Fixed tick, s (default `1/60`). */
+    dt?: number;
+    /** Measure with sprint held (default `false`). */
+    sprint?: boolean;
+    /** How long jump is held for `tapJumpHeight`, s (default `0.1`). */
+    tapSeconds?: number;
+}
+/** Deterministic walk-feel metrics. `Infinity` means the target was never reached. */
+export interface MovementReport {
+    /** Steady ground speed holding forward, m/s. */
+    topSpeed: number;
+    /** Standing start until speed reaches 90% of `topSpeed`, s. */
+    timeToTopSpeed: number;
+    /** Distance slid after releasing input at `topSpeed`, until speed is under 0.05 m/s, m. */
+    stopDistance: number;
+    /** Seconds from releasing input at `topSpeed` until speed is under 0.05 m/s. */
+    stopTime: number;
+    /** Seconds from reversing direction at `topSpeed` until speed along the new heading reaches 90% of `topSpeed`. */
+    turnAroundTime: number;
+    /** Peak height of a held standing jump, m. */
+    jumpHeight: number;
+    /** Peak height of a standing jump released after `tapSeconds`, m. Lower than `jumpHeight` when `jumpCutFactor` is set. */
+    tapJumpHeight: number;
+    /** Seconds from takeoff to the jump's peak. */
+    apexTime: number;
+    /** Seconds from takeoff to landing. */
+    airTime: number;
+    /** Sideways distance covered by strafing from the first airborne tick of a standing jump until landing, m. */
+    airControlReach: number;
+}
+/**
+ * Drives a walk character through fixed scenarios (standing start, release to stop, reversal, a standing
+ * jump, a tapped jump, a strafed jump) on the same integrator `stepPlayerMovement` uses, and reports the feel metrics a
+ * test can assert. Deterministic: the same subject and options always produce the same report, so a feel
+ * change shows up as a number moving. Collision, terrain and swimming are out of scope; it measures flat ground.
+ * @capability movement-metrics measure a walking character's feel as numbers — time to top speed, stop distance, jump height and apex, air control, turn-around
+ */
+export declare function measureMovement(subject?: MovementProbeSubject, options?: MovementProbeOptions): MovementReport;

package/dist/movement/movementProbe.js

@@ -0,0 +1,119 @@
+import { createInputBuffer } from "../input/inputBuffer.js";
+import { advancePlayerMotion, createEmptyMovementKeys, createPlayerMotionState, resolveMovementIntent, } from "./movementModel.js";
+import { resolvePlayerMovementTuning } from "./playerMovement.js";
+const ARRIVED = 0.9;
+const STOPPED = 0.05;
+const SETTLE_SECONDS = 5;
+const LIMIT_SECONDS = 10;
+function held(keys) {
+    return resolveMovementIntent({ ...createEmptyMovementKeys(), ...keys }, true);
+}
+function speedOf(motion) {
+    return Math.hypot(motion.horizontalVelocityX, motion.horizontalVelocityZ);
+}
+/**
+ * Drives a walk character through fixed scenarios (standing start, release to stop, reversal, a standing
+ * jump, a tapped jump, a strafed jump) on the same integrator `stepPlayerMovement` uses, and reports the feel metrics a
+ * test can assert. Deterministic: the same subject and options always produce the same report, so a feel
+ * change shows up as a number moving. Collision, terrain and swimming are out of scope; it measures flat ground.
+ * @capability movement-metrics measure a walking character's feel as numbers — time to top speed, stop distance, jump height and apex, air control, turn-around
+ */
+export function measureMovement(subject = {}, options = {}) {
+    const dt = options.dt ?? 1 / 60;
+    const sprint = options.sprint === true;
+    const walkSpeed = subject.walkSpeed ?? 2;
+    const tuning = resolvePlayerMovementTuning({
+        ...(subject.movement === undefined ? {} : { movement: subject.movement }),
+        ...(subject.physics === undefined ? {} : { physics: subject.physics }),
+    }).physics;
+    const buffer = createInputBuffer({ windowMs: 0 });
+    const step = (motion, intent, forwardZ = 1, forwardX = 0) => advancePlayerMotion(motion, intent, forwardX, forwardZ, walkSpeed, dt, tuning, { buffer });
+    const forward = held({ w: true, shift: sprint });
+    const idle = held({});
+    const ticks = (seconds) => Math.ceil(seconds / dt);
+    const fresh = () => {
+        buffer.restore({ windowMs: 0, actions: {} });
+        return createPlayerMotionState();
+    };
+    const settled = () => {
+        const motion = fresh();
+        for (let i = 0; i < ticks(SETTLE_SECONDS); i += 1)
+            step(motion, forward);
+        return motion;
+    };
+    const topSpeed = speedOf(settled());
+    let timeToTopSpeed = Number.POSITIVE_INFINITY;
+    {
+        const motion = fresh();
+        for (let i = 1; i <= ticks(LIMIT_SECONDS); i += 1) {
+            step(motion, forward);
+            if (speedOf(motion) >= topSpeed * ARRIVED) {
+                timeToTopSpeed = i * dt;
+                break;
+            }
+        }
+    }
+    let stopDistance = Number.POSITIVE_INFINITY;
+    let stopTime = Number.POSITIVE_INFINITY;
+    {
+        const motion = settled();
+        let distance = 0;
+        for (let i = 1; i <= ticks(LIMIT_SECONDS); i += 1) {
+            const moved = step(motion, idle);
+            distance += Math.hypot(moved.stepX, moved.stepZ);
+            if (speedOf(motion) < STOPPED) {
+                stopDistance = distance;
+                stopTime = i * dt;
+                break;
+            }
+        }
+    }
+    let turnAroundTime = Number.POSITIVE_INFINITY;
+    {
+        const motion = settled();
+        for (let i = 1; i <= ticks(LIMIT_SECONDS); i += 1) {
+            step(motion, forward, -1);
+            if (-motion.horizontalVelocityZ >= topSpeed * ARRIVED) {
+                turnAroundTime = i * dt;
+                break;
+            }
+        }
+    }
+    const jump = (airborne, releaseAfter = Number.POSITIVE_INFINITY) => {
+        const motion = fresh();
+        const takeoff = held({ space: true });
+        const released = held({ d: airborne.right !== 0, shift: sprint });
+        let height = 0;
+        let apex = 0;
+        let lateral = 0;
+        let landed = Number.POSITIVE_INFINITY;
+        for (let i = 1; i <= ticks(LIMIT_SECONDS); i += 1) {
+            const moved = step(motion, i === 1 ? takeoff : i * dt > releaseAfter ? released : airborne);
+            lateral += moved.stepX;
+            if (motion.jumpOffset > height) {
+                height = motion.jumpOffset;
+                apex = i * dt;
+            }
+            if (motion.grounded && i > 1) {
+                landed = i * dt;
+                break;
+            }
+        }
+        return { height, apex, lateral, landed };
+    };
+    const standing = jump(held({ space: true }));
+    const strafed = jump(held({ space: true, d: true, shift: sprint }));
+    const tapped = jump(held({ space: true }), options.tapSeconds ?? 0.1);
+    return {
+        topSpeed,
+        timeToTopSpeed,
+        stopDistance,
+        stopTime,
+        turnAroundTime,
+        jumpHeight: standing.height,
+        tapJumpHeight: tapped.height,
+        apexTime: standing.apex,
+        airTime: standing.landed,
+        airControlReach: Math.abs(strafed.lateral),
+    };
+}

package/dist/movement/playerMovement.d.ts

@@ -2,14 +2,24 @@ import type { PhysicsConfig } from "../game/defineGame.js";
 import type { PlayerMovementConfig, VoxelCollisionConfig } from "../game/playableGame.js";
 import type { GameContext } from "../runtime/gameContext.js";
 import type { InputFrame } from "../runtime/inputSnapshot.js";
+import { type InputBufferSnapshot } from "../input/inputBuffer.js";
+import { type CharacterControllerConfig, type CharacterControllerState } from "./characterController.js";
 import { type TerrainField } from "../world/terrain.js";
 import type { WorldFeature } from "../world/features.js";
-import { type MovementTuningOverrides } from "./movementModel.js";
+import type { PhysicsBackend } from "../physics/physicsBackend.js";
+import { type MovementTuningOverrides, type PlayerMotionState } from "./movementModel.js";
+import { type FreeFlightState } from "./freeFlight.js";
+import { type VoxelPlayerBody } from "./voxelController.js";
 /** The resolved, per-world movement configuration {@link stepPlayerMovement} integrates against — the same inputs the shell FrameDriver used to read piecemeal, gathered into one struct so single-player and host movement run identical math. */
 export interface PlayerMovementTuning {
     collision?: VoxelCollisionConfig;
     movement?: PlayerMovementConfig;
     physics?: MovementTuningOverrides;
+    /** Optional physics-backed capsule controller; when present it replaces terrain/AABB walking collision. */
+    controller?: {
+        backend: PhysicsBackend;
+        capsule: CharacterControllerConfig;
+    };
     ground: TerrainField;
     hasTerrain: boolean;
 }
@@ -28,6 +38,22 @@ export declare function resolvePlayerMovementTuning(opts: {
 }): PlayerMovementTuning;
 /** One player's current heading (radians), integrated by {@link stepPlayerMovement} — the shell reads it back into its camera/aim yaw. */
 export declare function playerMovementHeading(ctx: GameContext, userId: string): number;
+/** One player's serializable movement state: heading, facing, velocities, jump latch and controller capsule. The entity pose lives in the entity store. */
+export interface PlayerMovementSnapshot {
+    heading: number;
+    facing: number | null;
+    voxelBody: VoxelPlayerBody | null;
+    motion: PlayerMotionState | null;
+    flight: FreeFlightState | null;
+    controller: CharacterControllerState | null;
+    controllerJumpHeld: boolean;
+    /** Buffered jump presses; absent in snapshots taken before jump buffering existed. */
+    jumpBuffer?: InputBufferSnapshot | null;
+}
+/** Copy one player's movement state for prediction, rollback or a save; `null` when the player has not moved yet. */
+export declare function snapshotPlayerMovement(ctx: GameContext, userId: string): PlayerMovementSnapshot | null;
+/** Put a player's movement state back to a {@link snapshotPlayerMovement} copy, so the next {@link stepPlayerMovement} replays from there. */
+export declare function restorePlayerMovement(ctx: GameContext, userId: string, snapshot: PlayerMovementSnapshot): void;
 /** Drop a player's retained movement state (heading + kinematic body) — call on leave so a rejoin starts fresh instead of resuming stale velocity. */
 export declare function forgetPlayerMovement(ctx: GameContext, userId: string): void;
 /**
@@ -36,6 +62,7 @@ export declare function forgetPlayerMovement(ctx: GameContext, userId: string):
  * so single-player and server-authoritative movement are identical. Reads the player's controlled entity, terrain,
  * scene solids, and pending motion impulses; writes the entity pose via `setPose`. Retains heading + kinematic body
  * per `userId` on the `ctx`. Pass `heading` to override the internally-integrated yaw (the shell owns yaw for its
- * camera); omit it and the controller turns from the frame's `turnLeft`/`turnRight` actions.
+ * camera); omit it and the controller turns from the frame's `turnLeft`/`turnRight` actions. Pass `pitch` for
+ * 6DOF spectator flight when `alignWithLook` is set.
  */
-export declare function stepPlayerMovement(ctx: GameContext, userId: string, input: InputFrame, dt: number, tuning: PlayerMovementTuning, heading?: number): void;
+export declare function stepPlayerMovement(ctx: GameContext, userId: string, input: InputFrame, dt: number, tuning: PlayerMovementTuning, heading?: number, pitch?: number): void;