@jgengine/core 0.18.1 → 0.21.0

package/dist/movement/characterController.d.ts

@@ -2,7 +2,7 @@ import type { BodyHandle, BodyShape, PhysicsBackend, PhysicsVec3 } from "../phys
 /** Capsule dimensions and the walk rules a controller applies; every field is retunable during play. */
 export interface CharacterControllerConfig {
     radius: number;
-    /** Standing height from feet to crown. */
+    /** Standing height from feet to crown, at least twice `radius`. */
     height: number;
     /** Height the feet may pop up to clear a ledge in one move. Default 0.35. */
     stepHeight?: number;
@@ -10,7 +10,7 @@ export interface CharacterControllerConfig {
     maxSlopeDeg?: number;
     /** Gap kept between the capsule and any surface so casts never start inside geometry. Default 0.02. */
     skinWidth?: number;
-    /** Height while crouched. Default `height * 0.6`. */
+    /** Height while crouched, between the capsule diameter and standing height. Default max(`height * 0.6`, diameter). */
     crouchHeight?: number;
     /** How far below the feet the ground may be while still counting as grounded (stairs down, small bumps). Default 0.3. */
     snapDistance?: number;
@@ -64,12 +64,15 @@ export interface CharacterController {
     shape(): BodyShape;
     /** Capsule center for the current state. */
     center(): [number, number, number];
+    /** Set stance before resolving movement intent. Returns false only when standing lacks headroom. */
+    setCrouch(backend: PhysicsBackend, crouch: boolean, self?: BodyHandle): boolean;
     move(backend: PhysicsBackend, input: CharacterMoveInput): CharacterMoveResult;
 }
 /**
  * Collide-and-slide capsule controller over any {@link PhysicsBackend}: horizontal slide along walls, step-up over
  * ledges, slope limit, ceiling test, crouch with headroom check, ground snapping, and moving-platform carry read from
  * the ground body's velocity. Pure over the backend's `shapecast`/`overlap`; the caller owns input and gravity policy.
+ * Invalid dimensions or control ranges throw before configuration changes.
  *
  * @capability character-controller capsule walk over the physics backend — slide, step-up, slopes, crouch, platforms
  */

package/dist/movement/characterController.js

@@ -1,25 +1,47 @@
 function resolve(config) {
-    return {
+    const cfg = {
         radius: config.radius,
         height: config.height,
         stepHeight: config.stepHeight ?? 0.35,
         maxSlopeDeg: config.maxSlopeDeg ?? 50,
         skinWidth: config.skinWidth ?? 0.02,
-        crouchHeight: config.crouchHeight ?? config.height * 0.6,
+        crouchHeight: config.crouchHeight ?? Math.max(config.radius * 2, config.height * 0.6),
         snapDistance: config.snapDistance ?? 0.3,
         maxSlides: config.maxSlides ?? 4,
         mask: config.mask ?? 0xffffffff,
     };
+    for (const field of ["radius", "height", "crouchHeight"]) {
+        if (!Number.isFinite(cfg[field]) || cfg[field] <= 0)
+            throw new RangeError(`CharacterController.${field} must be finite and greater than zero.`);
+    }
+    const diameter = cfg.radius * 2;
+    if (cfg.height < diameter)
+        throw new RangeError(`CharacterController.height must be at least the capsule diameter (${diameter}). Increase height or reduce radius.`);
+    if (cfg.crouchHeight < diameter)
+        throw new RangeError(`CharacterController.crouchHeight must be at least the capsule diameter (${diameter}). Increase crouchHeight or reduce radius.`);
+    if (cfg.crouchHeight > cfg.height)
+        throw new RangeError("CharacterController.crouchHeight must not exceed standing height.");
+    for (const field of ["stepHeight", "skinWidth", "snapDistance"]) {
+        if (!Number.isFinite(cfg[field]) || cfg[field] < 0)
+            throw new RangeError(`CharacterController.${field} must be finite and nonnegative.`);
+    }
+    if (!Number.isFinite(cfg.maxSlopeDeg) || cfg.maxSlopeDeg < 0 || cfg.maxSlopeDeg >= 90)
+        throw new RangeError("CharacterController.maxSlopeDeg must be finite and between 0 (inclusive) and 90 (exclusive).");
+    if (!Number.isInteger(cfg.maxSlides) || cfg.maxSlides < 1)
+        throw new RangeError("CharacterController.maxSlides must be a positive integer.");
+    return cfg;
 }
 /**
  * Collide-and-slide capsule controller over any {@link PhysicsBackend}: horizontal slide along walls, step-up over
  * ledges, slope limit, ceiling test, crouch with headroom check, ground snapping, and moving-platform carry read from
  * the ground body's velocity. Pure over the backend's `shapecast`/`overlap`; the caller owns input and gravity policy.
+ * Invalid dimensions or control ranges throw before configuration changes.
  *
  * @capability character-controller capsule walk over the physics backend — slide, step-up, slopes, crouch, platforms
  */
 export function createCharacterController(initial) {
-    let cfg = resolve(initial);
+    let declaration = { ...initial };
+    let cfg = resolve(declaration);
     let state = {
         position: [0, 0, 0],
         verticalVelocity: 0,
@@ -69,10 +91,26 @@ export function createCharacterController(initial) {
         pos[2] += motion[2] * fraction;
         return { fraction, hit };
     }
+    function setCrouch(backend, crouch, self) {
+        if (crouch === state.crouching)
+            return true;
+        if (!crouch && backend.overlap({
+            shape: shapeFor(cfg.height),
+            position: centerFor(state.position, cfg.height),
+            mask: cfg.mask,
+            ...(self === undefined ? {} : { exclude: self }),
+        }).length > 0)
+            return false;
+        state.crouching = crouch;
+        return true;
+    }
     return {
         config: () => cfg,
         retune(next) {
-            cfg = resolve({ ...cfg, ...next });
+            const updated = { ...declaration, ...next };
+            const resolved = resolve(updated);
+            declaration = updated;
+            cfg = resolved;
         },
         state: () => state,
         snapshot: () => ({
@@ -95,6 +133,7 @@ export function createCharacterController(initial) {
         },
         shape: () => shapeFor(currentHeight()),
         center: () => centerFor(state.position, currentHeight()),
+        setCrouch,
         move(backend, input) {
             const { dt, self } = input;
             const result = {
@@ -108,21 +147,8 @@ export function createCharacterController(initial) {
             };
             const start = [state.position[0], state.position[1], state.position[2]];
             const pos = [start[0], start[1], start[2]];
-            if (input.crouch === true && !state.crouching) {
-                state.crouching = true;
-            }
-            else if (input.crouch === false && state.crouching) {
-                const standing = backend.overlap({
-                    shape: shapeFor(cfg.height),
-                    position: centerFor(pos, cfg.height),
-                    mask: cfg.mask,
-                    ...(self === undefined ? {} : { exclude: self }),
-                });
-                if (standing.length === 0)
-                    state.crouching = false;
-                else
-                    result.crouchBlocked = true;
-            }
+            if (input.crouch !== undefined)
+                result.crouchBlocked = !setCrouch(backend, input.crouch, self);
             const height = currentHeight();
             let carry = [0, 0, 0];
             if (state.grounded && state.groundBody !== null) {
@@ -145,7 +171,8 @@ export function createCharacterController(initial) {
                 if (!walkable(hit.normal)) {
                     result.hitWall = true;
                     slid[1] = 0;
-                    if (cfg.stepHeight > 0 && !result.steppedUp && tryStepUp(backend, pos, height, remaining, self)) {
+                    if (state.grounded && state.verticalVelocity <= 0 && input.jumpVelocity === undefined &&
+                        cfg.stepHeight > 0 && !result.steppedUp && tryStepUp(backend, pos, height, remaining, self)) {
                         result.steppedUp = true;
                         result.hitWall = false;
                         break;
@@ -178,9 +205,9 @@ export function createCharacterController(initial) {
                 state.groundBody = verticalHit.body;
                 if (state.verticalVelocity < 0)
                     state.verticalVelocity = 0;
-                // A contact at t=0 means touching or already inside; lift by the skin so the next casts start clear.
-                if (verticalHit.toi <= 0)
-                    pos[1] += cfg.skinWidth;
+                const initialGap = Math.max(0, verticalHit.toi * Math.abs(vertical));
+                if (initialGap < cfg.skinWidth)
+                    pos[1] += cfg.skinWidth - initialGap;
             }
             else {
                 state.grounded = false;

package/dist/movement/freeFlight.d.ts

@@ -1,4 +1,4 @@
-import { type AnalogMoveIntent, type CollisionObstacle, type MovementKeysState } from "./movementModel.js";
+import { type AnalogMoveIntent, type CollisionObstacle, type MovementKeysState, type MotionFrameOptions } from "./movementModel.js";
 import { type AxisBinding } from "../input/axisInput.js";
 import type { PointerAxisState } from "../input/pointerAxis.js";
 import type { ChaseCameraTuning } from "../runtime/cameraDirector.js";
@@ -91,7 +91,7 @@ export declare function resolveFreeFlightIntentFromInput(isDown: (action: string
  * Horizontal uses yaw-relative strafe (A = left, D = right) — never roll/bank.
  * Vertical is independent of pitch unless `alignWithLook` is true (spectator).
  */
-export declare function advanceFreeFlight(state: FreeFlightState, intent: FreeFlightIntent, yaw: number, pitch: number | undefined, dt: number, tuning: FreeFlightTuning): FreeFlightStep;
+export declare function advanceFreeFlight(state: FreeFlightState, intent: FreeFlightIntent, yaw: number, pitch: number | undefined, dt: number, tuning: FreeFlightTuning, options?: Pick<MotionFrameOptions, "authoritativeStep">): FreeFlightStep;
 /** Resolve a flight step against world solids (XZ slide + Y clamp). */
 export declare function resolveFlightStep(position: readonly [number, number, number], stepX: number, stepY: number, stepZ: number, obstacles: readonly CollisionObstacle[], radius?: number): {
     stepX: number;

package/dist/movement/freeFlight.js

@@ -1,4 +1,4 @@
-import { MOVEMENT_TUNING } from "./movementModel.js";
+import { motionStepSeconds } from "./movementModel.js";
 import { DEFAULT_OBSTACLE_PLAYER_RADIUS } from "./movementModel.js";
 import { sampleAxisBindings } from "../input/axisInput.js";
 const ANALOG_EPSILON = 0.02;
@@ -50,8 +50,8 @@ export function resolveFreeFlightIntentFromInput(isDown, value, pointer, binding
  * Horizontal uses yaw-relative strafe (A = left, D = right) — never roll/bank.
  * Vertical is independent of pitch unless `alignWithLook` is true (spectator).
  */
-export function advanceFreeFlight(state, intent, yaw, pitch, dt, tuning) {
-    const delta = Math.min(dt, MOVEMENT_TUNING.maxFrameSeconds);
+export function advanceFreeFlight(state, intent, yaw, pitch, dt, tuning, options) {
+    const delta = motionStepSeconds(dt, options?.authoritativeStep);
     if (delta <= 0)
         return { stepX: 0, stepY: 0, stepZ: 0 };
     const speed = tuning.speed ?? 8;

package/dist/movement/glideModel.d.ts

@@ -40,6 +40,9 @@ export interface GlideModel {
     step(dt: number, input?: GlideInput, externalVelocity?: GlideVec3): GlideStep;
     pose(): GlideStep;
     launch(position: GlideVec3, heading: number, initialSpeed?: number): void;
+    /** Plain JSON copy of the glider's position, velocity and heading. */
+    snapshot(): GlideStep;
+    restore(next: GlideStep): void;
 }
 /**
  * Gliding/wingsuit descent control — lift, drag, and steering from a launch.

package/dist/movement/glideModel.js

@@ -32,6 +32,12 @@ export function createGlideModel(config = {}) {
             vz = Math.cos(heading) * initialSpeed;
         },
         pose: snapshot,
+        snapshot,
+        restore(next) {
+            [x, y, z] = next.position;
+            [vx, vy, vz] = next.velocity;
+            heading = next.heading;
+        },
         step(dt, input = {}, externalVelocity) {
             if (dt <= 0)
                 return snapshot();

package/dist/movement/grappleSwing.d.ts

@@ -28,6 +28,8 @@ export interface GrappleSwing {
     fire(anchor: SwingVec3, from: SwingVec3): void;
     release(): void;
     state(): GrappleSwingState;
+    /** Puts a {@link GrappleSwing.state} back; `anchor: null` detaches. */
+    restore(next: GrappleSwingState): void;
     /** Constrain one frame. `reeling` shortens the rope; returns the corrected position/velocity. */
     step(position: SwingVec3, velocity: SwingVec3, dt: number, reeling?: boolean): GrappleSwingStep;
 }

package/dist/movement/grappleSwing.js

@@ -18,7 +18,11 @@ export function createGrappleSwing(config = {}) {
         release() {
             anchor = null;
         },
-        state: () => ({ attached: anchor !== null, anchor, ropeLength }),
+        state: () => ({ attached: anchor !== null, anchor: anchor === null ? null : [anchor[0], anchor[1], anchor[2]], ropeLength }),
+        restore(next) {
+            anchor = next.anchor === null ? null : [next.anchor[0], next.anchor[1], next.anchor[2]];
+            ropeLength = next.ropeLength;
+        },
         step(position, velocity, dt, reeling = false) {
             if (anchor === null || dt <= 0)
                 return { position, velocity };

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
@@ -107,10 +144,16 @@ export interface MovementTuningOverrides {
  * fields leave the integrator at its default behavior.
  */
 export interface MotionFrameOptions {
+    /** Integrate a caller-clamped simulation step in full, including scaled game time. Default false. */
+    authoritativeStep?: boolean;
     /** Extra multiplier applied on top of the resolved target speed (e.g. swimming). Default 1. */
     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;
+    /** A collision controller supplies grounded state; integrate jump velocity without landing on the synthetic offset origin. */
+    externalGrounding?: boolean;
 }
 /**
  * Advance one frame of avatar kinematics. Mutates `motion` (velocity, jump,
@@ -124,6 +167,8 @@ export interface MotionFrameOptions {
   * @internal
   */
 export declare function advancePlayerMotion(motion: PlayerMotionState, intent: MovementIntent, forwardX: number, forwardZ: number, baseSpeed: number, rawDeltaSeconds: number, tuning?: MovementTuningOverrides, options?: MotionFrameOptions): MovementFrameStep;
+/** @internal Validate trusted simulation time or apply the standalone frame-stall clamp. */
+export declare function motionStepSeconds(seconds: number, authoritativeStep?: boolean): number;
 /** A placed scene object the walking player collides against as a circle-vs-AABB obstacle. */
 export interface CollisionObstacle {
     position: readonly [number, number, number];
@@ -144,6 +189,23 @@ export interface CollisionObstacle {
 }
 /** @internal Player radius the walking obstruction inflates obstacles by; callers gather within reach of it. */
 export declare const DEFAULT_OBSTACLE_PLAYER_RADIUS = 0.3;
+/** @internal Default feet-to-head span for heightfield obstruction; matches DEFAULT_VOXEL_DIMS.height. */
+export declare const DEFAULT_OBSTACLE_PLAYER_HEIGHT = 1.8;
+/**
+ * Sweep a heightfield walker's vertical step at its accepted XZ position against blocking bounds.
+ * The nearest crossed underside stops ascent; the nearest crossed top catches descent, including
+ * thin geometry crossed in one step. Compound boxes are relative to obstacle.position; offset is
+ * used only for a single AABB. Real starting intersections are reported separately, not repaired.
+ * @internal
+ */
+export declare function resolveObstacleVerticalStep(position: readonly [number, number, number], stepY: number, obstacles: readonly CollisionObstacle[], radius?: number, playerHeight?: number): {
+    stepY: number;
+    hitCeiling: boolean;
+    ceilingFeetY: number | null;
+    ceilingTolerance: number;
+    landed: boolean;
+    initialOverlap: boolean;
+};
 /**
  * Resolve a horizontal step against nearby placed objects with classic
  * axis-separated sliding (try X, then Z against the post-X position) so
@@ -159,7 +221,7 @@ export declare const DEFAULT_OBSTACLE_PLAYER_RADIUS = 0.3;
  * tread is stepped up, not bumped into.
   * @internal
   */
-export declare function resolveObstacleStep(current: readonly [number, number, number], stepX: number, stepZ: number, obstacles: readonly CollisionObstacle[], playerRadius?: number, stepUpHeight?: number): MovementFrameStep;
+export declare function resolveObstacleStep(current: readonly [number, number, number], stepX: number, stepZ: number, obstacles: readonly CollisionObstacle[], playerRadius?: number, stepUpHeight?: number, playerHeight?: number): MovementFrameStep;
 /**
  * Highest blocking-box top the player can stand on at `(x, z)`: among obstacles whose footprint
  * (inflated by `playerRadius`, matching the blocking inflation so any horizontal contact that would

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,
     };
 }
 /**
@@ -121,8 +114,20 @@ export function createPlayerMotionState() {
   * @internal
   */
 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 deltaSeconds = motionStepSeconds(rawDeltaSeconds, options?.authoritativeStep);
+    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,48 +166,151 @@ 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) {
+        if (motion.jumpOffset <= 0 && options?.externalGrounding !== true) {
             motion.jumpOffset = 0;
             motion.verticalVelocity = 0;
             motion.grounded = true;
         }
     }
+    if (airborneAtStart && motion.grounded)
+        motion.landedAtMs = now;
+    motion.wasAirborne = !motion.grounded;
     return {
         stepX: motion.horizontalVelocityX * deltaSeconds,
         stepZ: motion.horizontalVelocityZ * deltaSeconds,
     };
 }
+/** @internal Validate trusted simulation time or apply the standalone frame-stall clamp. */
+export function motionStepSeconds(seconds, authoritativeStep = false) {
+    if (!Number.isFinite(seconds) || seconds < 0)
+        throw new RangeError("Movement step seconds must be finite and nonnegative");
+    return authoritativeStep ? seconds : Math.min(seconds, MOVEMENT_TUNING.maxFrameSeconds);
+}
 const DEFAULT_OBSTACLE_HALF_EXTENTS = [0.5, 0.5, 0.5];
 /** @internal Player radius the walking obstruction inflates obstacles by; callers gather within reach of it. */
 export const DEFAULT_OBSTACLE_PLAYER_RADIUS = 0.3;
-/** Feet-to-head span used for the obstacle's vertical overlap test; matches DEFAULT_VOXEL_DIMS.height. */
-const OBSTACLE_PLAYER_HEIGHT = 1.8;
+/** @internal Default feet-to-head span for heightfield obstruction; matches DEFAULT_VOXEL_DIMS.height. */
+export const DEFAULT_OBSTACLE_PLAYER_HEIGHT = 1.8;
 /** Extra nudge past a solid face when depenetrating so the escaped capsule lands just outside, not on, the box. */
 const PENETRATION_EPSILON = 1e-3;
+function verticalContactTolerance(feetY, headY, minY, maxY) {
+    return Number.EPSILON * 8 * Math.max(1, Math.abs(feetY), Math.abs(headY), Math.abs(minY), Math.abs(maxY));
+}
+/**
+ * Sweep a heightfield walker's vertical step at its accepted XZ position against blocking bounds.
+ * The nearest crossed underside stops ascent; the nearest crossed top catches descent, including
+ * thin geometry crossed in one step. Compound boxes are relative to obstacle.position; offset is
+ * used only for a single AABB. Real starting intersections are reported separately, not repaired.
+ * @internal
+ */
+export function resolveObstacleVerticalStep(position, stepY, obstacles, radius = DEFAULT_OBSTACLE_PLAYER_RADIUS, playerHeight = DEFAULT_OBSTACLE_PLAYER_HEIGHT) {
+    if (!Number.isFinite(stepY))
+        throw new RangeError("Vertical obstacle step must be finite.");
+    if (!Number.isFinite(playerHeight) || playerHeight <= 0)
+        throw new RangeError("Obstacle player height must be finite and positive.");
+    const feetY = position[1];
+    const headY = feetY + playerHeight;
+    const nextFeet = feetY + stepY;
+    const nextHead = nextFeet + playerHeight;
+    const result = { stepY, hitCeiling: false, ceilingFeetY: null, ceilingTolerance: 0, landed: false, initialOverlap: false };
+    const consider = (minX, maxX, minY, maxY, minZ, maxZ) => {
+        if (position[0] <= minX - radius || position[0] >= maxX + radius || position[2] <= minZ - radius || position[2] >= maxZ + radius)
+            return;
+        const tolerance = verticalContactTolerance(feetY, headY, minY, maxY);
+        if (feetY < maxY - tolerance && headY > minY + tolerance) {
+            result.initialOverlap = true;
+            return;
+        }
+        if (stepY > 0 && headY <= minY + tolerance && nextHead >= minY) {
+            const limitedStep = minY - playerHeight - tolerance - feetY;
+            if (limitedStep <= result.stepY) {
+                result.stepY = limitedStep;
+                // Keep the actual face limit separate from the tiny collision margin, so a support with
+                // exactly enough headroom remains valid at translated coordinates.
+                result.ceilingFeetY = minY - playerHeight;
+                result.ceilingTolerance = tolerance;
+            }
+            result.hitCeiling = true;
+        }
+        else if (stepY < 0 && feetY >= maxY - tolerance && nextFeet <= maxY) {
+            result.stepY = Math.max(result.stepY, maxY - feetY);
+            result.landed = true;
+        }
+    };
+    for (const obstacle of obstacles) {
+        const [x, y, z] = obstacle.position;
+        if (obstacle.boxes !== undefined && obstacle.boxes.length > 0) {
+            for (const box of obstacle.boxes)
+                consider(x + box.min[0], x + box.max[0], y + box.min[1], y + box.max[1], z + box.min[2], z + box.max[2]);
+        }
+        else {
+            const half = obstacle.halfExtents ?? DEFAULT_OBSTACLE_HALF_EXTENTS;
+            const offset = obstacle.offset;
+            const cx = x + (offset?.[0] ?? 0), cy = y + (offset?.[1] ?? 0), cz = z + (offset?.[2] ?? 0);
+            consider(cx - half[0], cx + half[0], cy - half[1], cy + half[1], cz - half[2], cz + half[2]);
+        }
+    }
+    return result;
+}
 /**
  * Swept clamp of a single-axis step against a box span. Entering from outside stops on the near
  * face — including when the raw target would land *beyond* the far face (the old form returned the
@@ -242,16 +350,18 @@ function clampAxisStep(originalCoord, step, min, max) {
  * tread is stepped up, not bumped into.
   * @internal
   */
-export function resolveObstacleStep(current, stepX, stepZ, obstacles, playerRadius = DEFAULT_OBSTACLE_PLAYER_RADIUS, stepUpHeight = 0) {
+export function resolveObstacleStep(current, stepX, stepZ, obstacles, playerRadius = DEFAULT_OBSTACLE_PLAYER_RADIUS, stepUpHeight = 0, playerHeight = DEFAULT_OBSTACLE_PLAYER_HEIGHT) {
+    if (!Number.isFinite(playerHeight) || playerHeight <= 0)
+        throw new RangeError("Obstacle player height must be finite and positive.");
     const feetY = current[1];
-    const headY = feetY + OBSTACLE_PLAYER_HEIGHT;
+    const headY = feetY + playerHeight;
     const reachX = Math.abs(stepX) + playerRadius;
     const reachZ = Math.abs(stepZ) + playerRadius;
     const nearby = [];
     const considerBox = (minX, maxX, minY, maxY, minZ, maxZ) => {
         // Vertical-span cull: a sub-box entirely above the head (walk under the lintel), below the feet,
         // or low enough to step up onto (`stepUpHeight`) is skipped — walkable ledges don't wall.
-        if (maxY <= feetY + stepUpHeight || minY >= headY)
+        if (maxY <= feetY + stepUpHeight || minY >= headY - verticalContactTolerance(feetY, headY, minY, maxY))
             return;
         const centerX = (minX + maxX) / 2;
         const centerZ = (minZ + maxZ) / 2;

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;