@jgengine/core 0.18.1 → 0.21.0

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,13 +2,18 @@ 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 CharacterControllerConfig } from "./characterController.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 { PhysicsBackend } from "../physics/physicsBackend.js";
-import { type MovementTuningOverrides } from "./movementModel.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 {
+    /** The simulation driver already clamps frame stalls; integrate its scaled step in full. */
+    authoritativeStep?: boolean;
     collision?: VoxelCollisionConfig;
     movement?: PlayerMovementConfig;
     physics?: MovementTuningOverrides;
@@ -33,8 +38,49 @@ export declare function resolvePlayerMovementTuning(opts: {
     physics?: PhysicsConfig;
     world?: WorldFeature;
 }): PlayerMovementTuning;
+/** Last completed shared movement step for one entity; a live read-only view, not a save snapshot. */
+export interface PlayerMovementTelemetry {
+    grounded: boolean;
+    verticalVelocity: number;
+    crouching: boolean;
+    /** Accepted physical height for heightfield walking; absent for other collision paths. */
+    collisionHeight?: number;
+    /** Live authored height requested for this completed heightfield step. */
+    requestedCollisionHeight?: number;
+    /** Growth is waiting for headroom; the accepted physical height remains collisionHeight. */
+    collisionHeightBlocked?: boolean;
+}
+/**
+ * Read the entity's last shared movement result through indexed possession ownership. Returns `null` before a
+ * step, after movement restore/forget, when a commit policy replaces the motor proposal, or for an entity not
+ * currently driven by this motor. Reuses one live view;
+ * custom movers supply their own animation parameters. Flight never reports ground contact or a walking crouch.
+ *
+ * @capability movement-telemetry read physical grounded, vertical velocity and crouch state without animation-store writes
+ */
+export declare function playerMovementTelemetry(ctx: GameContext, entityId: string): Readonly<PlayerMovementTelemetry> | null;
 /** 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;
+    /** Accepted heightfield body height. Older walking snapshots retain their historical 1.8m span. */
+    heightfieldHeight?: number | null;
+    /** Pawn that accepted heightfieldHeight; omission binds legacy dimensions to the active pawn on restore. */
+    heightfieldEntityId?: string | 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. Pending state survives until first spawn; a driven actor's despawn clears it. */
+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;
 /**