@jgengine/core 0.19.0 → 0.22.0

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/movementModel.d.ts

@@ -144,12 +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,
@@ -163,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];
@@ -183,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
@@ -198,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

@@ -114,7 +114,7 @@ export function createPlayerMotionState() {
   * @internal
   */
 export function advancePlayerMotion(motion, intent, forwardX, forwardZ, baseSpeed, rawDeltaSeconds, tuning, options) {
-    const deltaSeconds = Math.min(rawDeltaSeconds, MOVEMENT_TUNING.maxFrameSeconds);
+    const deltaSeconds = motionStepSeconds(rawDeltaSeconds, options?.authoritativeStep);
     const now = (motion.clockMs ?? 0) + deltaSeconds * 1000;
     motion.clockMs = now;
     if (motion.grounded && motion.wasAirborne)
@@ -225,7 +225,7 @@ export function advancePlayerMotion(motion, intent, forwardX, forwardZ, baseSpee
         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;
@@ -239,13 +239,78 @@ export function advancePlayerMotion(motion, intent, forwardX, forwardZ, baseSpee
         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
@@ -285,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/playerMovement.d.ts

@@ -12,6 +12,8 @@ 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;
@@ -36,6 +38,27 @@ 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. */
@@ -49,10 +72,14 @@ export interface PlayerMovementSnapshot {
     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, so the next {@link stepPlayerMovement} replays from there. */
+/** 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;