@jgengine/core 0.19.0 → 0.22.0

package/dist/movement/playerMovement.js

@@ -2,11 +2,14 @@ import { createInputBuffer } from "../input/inputBuffer.js";
 import { applyHorizontalImpulses, applyMotionImpulses } from "../runtime/motionIntents.js";
 import { createCharacterController, } from "./characterController.js";
 import { groundFieldFor, hasEnvironmentTerrain, sampleSlope } from "../world/terrain.js";
-import { advancePlayerMotion, constrainStepToAxis, createEmptyMovementKeys, createPlayerMotionState, DEFAULT_OBSTACLE_PLAYER_RADIUS, obstacleSupportHeight, resolveMovementIntent, resolveObstacleStep, snapPositionToGrid, MOVEMENT_TUNING, } from "./movementModel.js";
+import { advancePlayerMotion, constrainStepToAxis, createEmptyMovementKeys, createPlayerMotionState, DEFAULT_OBSTACLE_PLAYER_RADIUS, DEFAULT_OBSTACLE_PLAYER_HEIGHT, motionStepSeconds, obstacleSupportHeight, resolveMovementIntent, resolveObstacleStep, resolveObstacleVerticalStep, snapPositionToGrid, } from "./movementModel.js";
 import { advanceFreeFlight, createFreeFlightState, resolveFlightStep, resolveFreeFlightIntentFromInput, } from "./freeFlight.js";
 import { solidObstaclesNear } from "./solidObstacles.js";
+import { withPoseRollback } from "./poseState.js";
 import { approachYaw, steerYaw } from "./steering.js";
+import { resolveTerrainGradeStep } from "./terrainGrade.js";
 import { advanceVoxelPlayer, createVoxelPlayerBody, } from "./voxelController.js";
+const CONTROLLER_CONFIG_FIELDS = ["radius", "height", "stepHeight", "maxSlopeDeg", "skinWidth", "crouchHeight", "snapDistance", "maxSlides", "mask"];
 const DEFAULT_TURN_SPEED = 2.4;
 const DEFAULT_WALK_SPEED = 2;
 const DEFAULT_SWIM_SPEED_MULTIPLIER = 0.65;
@@ -35,42 +38,41 @@ export function resolvePhysicsTuning(physics) {
 }
 /** Gather a game's collision/movement/physics/world config into a {@link PlayerMovementTuning} — call once per world; both the shell and a host pass the result to {@link stepPlayerMovement}. */
 export function resolvePlayerMovementTuning(opts) {
-    const physics = resolvePhysicsTuning(opts.physics);
-    const backpedal = opts.movement?.backpedalMult;
-    const feel = opts.movement?.feel;
-    const feelOverrides = {
-        ...(backpedal === undefined ? {} : { backpedalSpeedMultiplier: backpedal }),
-        ...(feel?.groundAcceleration === undefined ? {} : { groundAcceleration: feel.groundAcceleration }),
-        ...(feel?.airAcceleration === undefined ? {} : { airAcceleration: feel.airAcceleration }),
-        ...(feel?.groundFriction === undefined ? {} : { groundFriction: feel.groundFriction }),
-        ...(feel?.runMultiplier === undefined ? {} : { runSpeedMultiplier: feel.runMultiplier }),
-        ...(feel?.crouchMultiplier === undefined ? {} : { crouchSpeedMultiplier: feel.crouchMultiplier }),
-        ...(feel?.jumpBufferMs === undefined ? {} : { jumpBufferMs: feel.jumpBufferMs }),
-        ...(feel?.coyoteMs === undefined ? {} : { coyoteMs: feel.coyoteMs }),
-        ...(feel?.jumpCutFactor === undefined ? {} : { jumpCutFactor: feel.jumpCutFactor }),
-        ...(feel?.apexGravityScale === undefined ? {} : { apexGravityScale: feel.apexGravityScale }),
-        ...(feel?.apexSpeed === undefined ? {} : { apexSpeed: feel.apexSpeed }),
-        ...(feel?.fallGravityScale === undefined ? {} : { fallGravityScale: feel.fallGravityScale }),
-        ...(feel?.landingRecoveryMs === undefined ? {} : { landingRecoveryMs: feel.landingRecoveryMs }),
-        ...(feel?.landingSpeedScale === undefined ? {} : { landingSpeedScale: feel.landingSpeedScale }),
+    const overrides = {
+        get gravityAcceleration() { return opts.physics?.gravity === undefined ? undefined : -opts.physics.gravity; },
+        get jumpVelocity() { return opts.physics?.jumpVelocity; },
+        get backpedalSpeedMultiplier() { return opts.movement?.backpedalMult; },
+        get groundAcceleration() { return opts.movement?.feel?.groundAcceleration; },
+        get airAcceleration() { return opts.movement?.feel?.airAcceleration; },
+        get groundFriction() { return opts.movement?.feel?.groundFriction; },
+        get runSpeedMultiplier() { return opts.movement?.feel?.runMultiplier; },
+        get crouchSpeedMultiplier() { return opts.movement?.feel?.crouchMultiplier; },
+        get jumpBufferMs() { return opts.movement?.feel?.jumpBufferMs; },
+        get coyoteMs() { return opts.movement?.feel?.coyoteMs; },
+        get jumpCutFactor() { return opts.movement?.feel?.jumpCutFactor; },
+        get apexGravityScale() { return opts.movement?.feel?.apexGravityScale; },
+        get apexSpeed() { return opts.movement?.feel?.apexSpeed; },
+        get fallGravityScale() { return opts.movement?.feel?.fallGravityScale; },
+        get landingRecoveryMs() { return opts.movement?.feel?.landingRecoveryMs; },
+        get landingSpeedScale() { return opts.movement?.feel?.landingSpeedScale; },
+    };
+    const defaultCapsule = {
+        radius: DEFAULT_OBSTACLE_PLAYER_RADIUS,
+        height: 1.8,
+        stepHeight: DEFAULT_PLAYER_STEP_HEIGHT,
+    };
+    const controller = {
+        get backend() { return opts.physics.backend; },
+        get capsule() { return opts.physics?.controller ?? defaultCapsule; },
     };
-    const overrides = Object.keys(feelOverrides).length === 0 ? physics : { ...(physics ?? {}), ...feelOverrides };
     return {
-        ...(opts.collision === undefined ? {} : { collision: opts.collision }),
-        ...(opts.movement === undefined ? {} : { movement: opts.movement }),
-        ...(overrides === undefined ? {} : { physics: overrides }),
-        ...(opts.physics?.backend === undefined
-            ? {}
-            : {
-                controller: {
-                    backend: opts.physics.backend,
-                    capsule: opts.physics.controller ?? {
-                        radius: DEFAULT_OBSTACLE_PLAYER_RADIUS,
-                        height: 1.8,
-                        stepHeight: DEFAULT_PLAYER_STEP_HEIGHT,
-                    },
-                },
-            }),
+        get collision() { return opts.collision; },
+        get movement() { return opts.movement; },
+        get physics() {
+            return opts.physics === undefined && opts.movement?.feel === undefined && opts.movement?.backpedalMult === undefined
+                ? undefined : overrides;
+        },
+        get controller() { return opts.physics?.backend === undefined ? undefined : controller; },
         ground: groundFieldFor(opts.world),
         hasTerrain: hasEnvironmentTerrain(opts.world),
     };
@@ -84,10 +86,24 @@ function storeFor(ctx) {
             solids: { count: -1, set: new Set() },
         };
         stores.set(ctx, store);
+        const retained = store;
+        ctx.scene.entity.subscribeMembership(() => {
+            for (const [userId, state] of retained.players) {
+                if (state.liveEntityId !== null) {
+                    if (ctx.scene.entity.get(state.liveEntityId) === null)
+                        retained.players.delete(userId);
+                }
+                else {
+                    const entityId = ctx.player.possession.active(userId);
+                    if (ctx.scene.entity.get(entityId) !== null)
+                        state.liveEntityId = entityId;
+                }
+            }
+        });
     }
     return store;
 }
-function stateFor(store, userId) {
+function stateFor(ctx, store, userId) {
     let state = store.players.get(userId);
     if (state === undefined) {
         state = {
@@ -97,14 +113,95 @@ function stateFor(store, userId) {
             motion: null,
             flight: null,
             controller: null,
+            controllerConfig: null,
             controllerJumpHeld: false,
             jumpBuffer: null,
             pendingController: null,
+            heightfieldHeight: null,
+            heightfieldEntityId: null,
+            liveEntityId: null,
+            entityId: null,
+            telemetry: null,
         };
+        const entityId = ctx.player.possession.active(userId);
+        if (ctx.scene.entity.get(entityId) !== null)
+            state.liveEntityId = entityId;
         store.players.set(userId, state);
     }
     return state;
 }
+function invalidateTelemetry(state) {
+    state.entityId = null;
+    state.telemetry = null;
+}
+function validateCollisionHeight(height) {
+    if (!Number.isFinite(height) || height <= 0) {
+        throw new RangeError("PlayerMovementConfig.collisionHeight must be finite and positive.");
+    }
+}
+function retuneController(state, config) {
+    const previous = state.controllerConfig;
+    if (previous !== null) {
+        let changed = false;
+        for (const field of CONTROLLER_CONFIG_FIELDS) {
+            if (previous[field] !== config[field]) {
+                changed = true;
+                break;
+            }
+        }
+        if (!changed)
+            return;
+    }
+    const next = {
+        radius: config.radius,
+        height: config.height,
+        stepHeight: config.stepHeight,
+        maxSlopeDeg: config.maxSlopeDeg,
+        skinWidth: config.skinWidth,
+        crouchHeight: config.crouchHeight,
+        snapDistance: config.snapDistance,
+        maxSlides: config.maxSlides,
+        mask: config.mask,
+    };
+    state.controller.retune(next);
+    state.controllerConfig = next;
+}
+function positionAccepted(ctx, entityId, x, y, z) {
+    const actual = ctx.scene.entity.get(entityId)?.position;
+    return actual !== undefined && actual[0] === x && actual[1] === y && actual[2] === z;
+}
+function updateTelemetry(state, entityId, grounded, verticalVelocity, crouching, collisionHeight, requestedCollisionHeight, collisionHeightBlocked) {
+    state.entityId = entityId;
+    const telemetry = state.telemetry ??= { grounded, verticalVelocity, crouching };
+    telemetry.grounded = grounded;
+    telemetry.verticalVelocity = verticalVelocity;
+    telemetry.crouching = crouching;
+    if (collisionHeight === undefined) {
+        delete telemetry.collisionHeight;
+        delete telemetry.requestedCollisionHeight;
+        delete telemetry.collisionHeightBlocked;
+    }
+    else {
+        telemetry.collisionHeight = collisionHeight;
+        telemetry.requestedCollisionHeight = requestedCollisionHeight;
+        telemetry.collisionHeightBlocked = collisionHeightBlocked;
+    }
+}
+/**
+ * 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 function playerMovementTelemetry(ctx, entityId) {
+    const userId = ctx.player.possession.ownerOf(entityId) ?? entityId;
+    if (ctx.player.possession.active(userId) !== entityId || ctx.scene.entity.get(entityId) === null)
+        return null;
+    const state = stores.get(ctx)?.players.get(userId);
+    return state?.entityId === entityId ? state.telemetry : null;
+}
 /** One player's current heading (radians), integrated by {@link stepPlayerMovement} — the shell reads it back into its camera/aim yaw. */
 export function playerMovementHeading(ctx, userId) {
     return stores.get(ctx)?.players.get(userId)?.heading ?? 0;
@@ -127,16 +224,32 @@ export function snapshotPlayerMovement(ctx, userId) {
         controller: controller === null ? null : copyController(controller),
         controllerJumpHeld: state.controllerJumpHeld,
         jumpBuffer: state.jumpBuffer?.snapshot() ?? null,
+        heightfieldHeight: state.heightfieldHeight,
+        heightfieldEntityId: state.heightfieldEntityId,
     };
 }
-/** 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 function restorePlayerMovement(ctx, userId, snapshot) {
-    const state = stateFor(storeFor(ctx), userId);
+    const heightfieldHeight = snapshot.heightfieldHeight === undefined
+        ? (snapshot.motion === null ? null : DEFAULT_OBSTACLE_PLAYER_HEIGHT) : snapshot.heightfieldHeight;
+    if (heightfieldHeight !== null)
+        validateCollisionHeight(heightfieldHeight);
+    const heightfieldEntityId = snapshot.heightfieldEntityId === undefined
+        ? (heightfieldHeight === null ? null : ctx.player.possession.active(userId)) : snapshot.heightfieldEntityId;
+    if (heightfieldEntityId !== null && typeof heightfieldEntityId !== "string") {
+        throw new RangeError("PlayerMovementSnapshot.heightfieldEntityId must be a string or null.");
+    }
+    const state = stateFor(ctx, storeFor(ctx), userId);
+    const liveEntityId = ctx.player.possession.active(userId);
+    state.liveEntityId = ctx.scene.entity.get(liveEntityId) === null ? null : liveEntityId;
+    invalidateTelemetry(state);
     state.heading = snapshot.heading;
     state.facing = snapshot.facing;
     state.voxelBody = snapshot.voxelBody === null ? null : { ...snapshot.voxelBody };
     state.motion = snapshot.motion === null ? null : { ...snapshot.motion };
     state.flight = snapshot.flight === null ? null : { ...snapshot.flight };
+    state.heightfieldHeight = heightfieldHeight;
+    state.heightfieldEntityId = heightfieldEntityId;
     state.controllerJumpHeld = snapshot.controllerJumpHeld;
     const jumpBuffer = snapshot.jumpBuffer ?? null;
     if (jumpBuffer === null) {
@@ -224,27 +337,81 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
     if (player.movement?.frozen === true)
         return;
     const store = storeFor(ctx);
-    const state = stateFor(store, userId);
+    const retainedState = store.players.get(userId);
+    const state = stateFor(ctx, store, userId);
+    let collisionHeight = DEFAULT_OBSTACLE_PLAYER_HEIGHT;
+    let requestedCollisionHeight = DEFAULT_OBSTACLE_PLAYER_HEIGHT;
+    let collisionHeightBlocked = false;
     const held = new Set(input.held);
     const isDown = (action) => held.has(action);
+    let nextHeading = state.heading;
     if (heading !== undefined) {
-        state.heading = heading;
+        nextHeading = heading;
     }
     else {
         const turnInput = (isDown("turnRight") ? 1 : 0) - (isDown("turnLeft") ? 1 : 0);
         const turnSpeed = tuning.movement?.turnSpeed ?? DEFAULT_TURN_SPEED;
         if (turnInput !== 0)
-            state.heading = steerYaw(state.heading, turnInput, turnSpeed, dt);
+            nextHeading = steerYaw(nextHeading, turnInput, turnSpeed, dt);
     }
-    const forwardX = Math.sin(state.heading);
-    const forwardZ = Math.cos(state.heading);
+    const forwardX = Math.sin(nextHeading);
+    const forwardZ = Math.cos(nextHeading);
     const keys = createEmptyMovementKeys();
     keys.w = isDown("moveForward");
     keys.s = isDown("moveBack");
     keys.a = isDown("moveLeft");
     keys.d = isDown("moveRight");
-    keys.shift = isDown("sprint") && (tuning.movement?.canSprint?.(ctx) ?? true);
-    keys.space = isDown("jump");
+    let flightTuning;
+    try {
+        flightTuning = withPoseRollback(ctx.player.movement, playerId, () => {
+            keys.shift = isDown("sprint") && (tuning.movement?.canSprint?.(ctx) ?? true);
+            keys.space = isDown("jump");
+            keys.c = isDown("crouch") && ctx.player.movement.setPose(playerId, "crouch") === null;
+            if (!keys.c && tuning.controller === undefined) {
+                const currentPose = ctx.player.movement.getPose(playerId);
+                if (currentPose !== "prone")
+                    ctx.player.movement.setPose(playerId, keys.shift ? "running" : "standing");
+            }
+            const flightTuning = flightTuningFor(tuning.movement, ctx);
+            if (flightTuning === null && tuning.controller === undefined && tuning.collision?.voxel !== true) {
+                const authoredHeight = tuning.movement?.collisionHeight;
+                requestedCollisionHeight = authoredHeight === undefined ? DEFAULT_OBSTACLE_PLAYER_HEIGHT : authoredHeight;
+                validateCollisionHeight(requestedCollisionHeight);
+                const previousHeight = state.heightfieldEntityId !== null && state.heightfieldEntityId !== playerId
+                    ? null : state.heightfieldHeight;
+                collisionHeight = previousHeight ?? requestedCollisionHeight;
+                if (tuning.movement?.collideObjects !== false &&
+                    (previousHeight === null && authoredHeight !== undefined || requestedCollisionHeight > collisionHeight)) {
+                    const swim = tuning.movement?.swim;
+                    const swimEnabled = swim === true || (typeof swim === "object" && swim !== null);
+                    const floating = swimEnabled && tuning.ground.waterLevel !== undefined &&
+                        tuning.ground.sampleHeight(player.position[0], player.position[2]) < tuning.ground.waterLevel;
+                    const groundedSupport = state.motion?.grounded !== false && (state.motion?.jumpOffset ?? 0) <= 0 && !floating;
+                    const supportStep = groundedSupport ? tuning.movement?.stepHeight ?? DEFAULT_PLAYER_STEP_HEIGHT : 0;
+                    const bounds = gatherMovementObstacles(ctx, player.position, 0, 0, 0, supportStep, Math.max(collisionHeight, requestedCollisionHeight));
+                    // An authored terrain-relative spawn can rest a few centimetres inside a walkable road plate.
+                    // Test the same support feet the grounded motor will accept, including the resulting headroom.
+                    const support = groundedSupport
+                        ? obstacleSupportHeight(player.position[0], player.position[2], player.position[1], supportStep, bounds) : null;
+                    const supportedPosition = support !== null && support > player.position[1]
+                        ? [player.position[0], support, player.position[2]] : player.position;
+                    const overlap = resolveObstacleVerticalStep(supportedPosition, 0, bounds, DEFAULT_OBSTACLE_PLAYER_RADIUS, requestedCollisionHeight).initialOverlap;
+                    if (overlap && previousHeight === null) {
+                        throw new RangeError(`PlayerMovementConfig.collisionHeight ${requestedCollisionHeight} intersects blocking geometry at entity ${playerId}. Move the authored placement or choose a height that fits.`);
+                    }
+                    collisionHeightBlocked = overlap;
+                }
+                if (!collisionHeightBlocked)
+                    collisionHeight = requestedCollisionHeight;
+            }
+            return flightTuning;
+        });
+    }
+    catch (error) {
+        if (retainedState === undefined && store.players.get(userId) === state)
+            store.players.delete(userId);
+        throw error;
+    }
     // A frame carrying analog magnitudes (virtual joystick, gamepad stick) walks at its deflection
     // instead of slamming digital ±1 axes — the fix for "a slight stick tilt reads as a full strafe".
     const analog = input.analog ?? null;
@@ -255,9 +422,14 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
             right: (analog.moveRight ?? 0) - (analog.moveLeft ?? 0),
         };
     const intent = resolveMovementIntent(keys, true, analogMove);
-    const motionBatch = ctx.player.motionFor(userId).takePending();
     const walkSpeed = player.movement?.walkSpeed ?? DEFAULT_WALK_SPEED;
-    const flightTuning = flightTuningFor(tuning.movement, ctx);
+    if (flightTuning === null && tuning.controller === undefined && tuning.collision?.voxel !== true) {
+        state.heightfieldHeight = collisionHeight;
+        state.heightfieldEntityId = playerId;
+    }
+    state.liveEntityId = playerId;
+    state.heading = nextHeading;
+    const motionBatch = ctx.player.motionFor(userId).takePending();
     if (flightTuning !== null) {
         const value = (action) => input.analog?.[action] ?? (isDown(action) ? 1 : 0);
         let flightIntent = resolveFreeFlightIntentFromInput(isDown, value, input.pointer, flightTuning.bindings);
@@ -295,7 +467,7 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
             const cam = ctx.camera;
             cam?.setChaseTuning(normalizedFlightTuning.camera ?? null);
         }
-        const step = advanceFreeFlight(flightState, flightIntent, state.heading, pitch, dt, normalizedFlightTuning);
+        const step = advanceFreeFlight(flightState, flightIntent, state.heading, pitch, dt, normalizedFlightTuning, { authoritativeStep: tuning.authoritativeStep });
         let stepX = step.stepX;
         let stepY = step.stepY;
         let stepZ = step.stepZ;
@@ -314,10 +486,12 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
                     flightState.vy = 0;
             }
         }
+        let motorProposalAccepted = true;
         let nextX = player.position[0] + stepX;
         let nextY = player.position[1] + stepY;
         let nextZ = player.position[2] + stepZ;
         if (motionBatch !== null && motionBatch.y !== null) {
+            motorProposalAccepted = motionBatch.y === nextY;
             nextY = motionBatch.y;
         }
         if (tuning.movement?.beforeCommit !== undefined) {
@@ -330,6 +504,7 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
             };
             const replacement = tuning.movement.beforeCommit(frame);
             if (replacement !== undefined) {
+                motorProposalAccepted = motorProposalAccepted && replacement[0] === nextX && replacement[1] === nextY && replacement[2] === nextZ;
                 nextX = replacement[0];
                 nextY = replacement[1];
                 nextZ = replacement[2];
@@ -340,6 +515,10 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
             rotationY: resolveBodyFacing(state, flightIntent.moving, flightState.vx, flightState.vz, player.rotationY, tuning.movement?.turnSpeed, dt),
             dt,
         });
+        if (motorProposalAccepted && positionAccepted(ctx, playerId, nextX, nextY, nextZ))
+            updateTelemetry(state, playerId, false, flightState.vy, false);
+        else
+            invalidateTelemetry(state);
         return;
     }
     if (flightTuning === null && state.flight !== null) {
@@ -361,6 +540,7 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
             });
             state.pendingController = null;
         }
+        retuneController(state, tuning.controller.capsule);
         const controllerState = controller.state();
         if (Math.hypot(controllerState.position[0] - player.position[0], controllerState.position[1] - player.position[1], controllerState.position[2] - player.position[2]) > 1e-6) {
             controller.restore({
@@ -370,43 +550,53 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
                 groundBody: null,
             });
         }
-        // Keep the existing input feel and horizontal impulse seam; the capsule owns vertical motion and collision.
         let horizontal = state.motion;
         if (horizontal === null) {
             horizontal = createPlayerMotionState();
             state.motion = horizontal;
         }
+        controller.setCrouch(tuning.controller.backend, intent.crouching);
         const grounded = controller.state().grounded;
         horizontal.grounded = grounded;
-        horizontal.verticalVelocity = 0;
+        horizontal.verticalVelocity = applyMotionImpulses(controller.state().verticalVelocity, motionBatch);
         horizontal.jumpOffset = 0;
         [horizontal.horizontalVelocityX, horizontal.horizontalVelocityZ] = applyHorizontalImpulses(horizontal.horizontalVelocityX, horizontal.horizontalVelocityZ, motionBatch);
-        const jumpPressed = intent.jumping && !state.controllerJumpHeld;
-        const horizontalStep = advancePlayerMotion(horizontal, { ...intent, jumping: false }, forwardX, forwardZ, walkSpeed, dt, tuning.physics);
-        horizontal.grounded = grounded;
-        horizontal.verticalVelocity = 0;
-        horizontal.jumpOffset = 0;
+        const controllerIntent = {
+            ...intent,
+            crouching: controller.state().crouching,
+            running: intent.running && !controller.state().crouching,
+        };
+        if (state.jumpBuffer === null) {
+            horizontal.jumpHeld = state.controllerJumpHeld;
+            state.jumpBuffer = createInputBuffer({ windowMs: tuning.physics?.jumpBufferMs ?? 0 });
+        }
+        const horizontalStep = advancePlayerMotion(horizontal, controllerIntent, forwardX, forwardZ, walkSpeed, dt, tuning.physics, { buffer: state.jumpBuffer, externalGrounding: true, authoritativeStep: tuning.authoritativeStep });
         state.controllerJumpHeld = intent.jumping;
-        const current = controller.state();
         controller.restore({
-            ...current,
-            verticalVelocity: applyMotionImpulses(current.verticalVelocity, motionBatch),
+            ...controller.state(),
+            verticalVelocity: horizontal.verticalVelocity,
+            grounded: horizontal.grounded,
         });
         const result = controller.move(tuning.controller.backend, {
             motion: [horizontalStep.stepX, 0, horizontalStep.stepZ],
-            dt,
-            gravity: tuning.physics?.gravityAcceleration ?? MOVEMENT_TUNING.gravityAcceleration,
-            ...(jumpPressed && !intent.crouching
-                ? { jumpVelocity: tuning.physics?.jumpVelocity ?? MOVEMENT_TUNING.jumpVelocity }
-                : {}),
-            crouch: intent.crouching,
+            dt: motionStepSeconds(dt, tuning.authoritativeStep),
         });
+        horizontal.verticalVelocity = controller.state().verticalVelocity;
+        horizontal.jumpOffset = 0;
+        if (!grounded && result.grounded)
+            horizontal.landedAtMs = horizontal.clockMs;
+        horizontal.wasAirborne = !result.grounded;
+        if (result.grounded)
+            horizontal.jumpRising = false;
+        ctx.player.movement.setPose(playerId, controller.state().crouching ? "crouch" : intent.running ? "running" : "standing");
+        let motorProposalAccepted = true;
         let nextPosition = [
             controller.state().position[0],
             controller.state().position[1],
             controller.state().position[2],
         ];
         if (motionBatch !== null && motionBatch.y !== null) {
+            motorProposalAccepted = motionBatch.y === nextPosition[1];
             nextPosition[1] = motionBatch.y;
             controller.restore({ ...controller.state(), position: nextPosition });
         }
@@ -420,6 +610,7 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
             };
             const replacement = tuning.movement.beforeCommit(frame);
             if (replacement !== undefined) {
+                motorProposalAccepted = motorProposalAccepted && replacement[0] === nextPosition[0] && replacement[1] === nextPosition[1] && replacement[2] === nextPosition[2];
                 nextPosition = [replacement[0], replacement[1], replacement[2]];
                 controller.restore({ ...controller.state(), position: nextPosition });
             }
@@ -430,6 +621,10 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
             rotationY: resolveBodyFacing(state, intent.moving, horizontal.horizontalVelocityX, horizontal.horizontalVelocityZ, player.rotationY, tuning.movement?.turnSpeed, dt),
             dt,
         });
+        if (motorProposalAccepted && positionAccepted(ctx, playerId, nextPosition[0], nextPosition[1], nextPosition[2]))
+            updateTelemetry(state, playerId, controller.state().grounded, controller.state().verticalVelocity, controller.state().crouching);
+        else
+            invalidateTelemetry(state);
         return;
     }
     if (tuning.collision?.voxel === true) {
@@ -452,7 +647,8 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
         };
         body.velocityY = applyMotionImpulses(body.velocityY, motionBatch);
         [body.velocityX, body.velocityZ] = applyHorizontalImpulses(body.velocityX, body.velocityZ, motionBatch);
-        advanceVoxelPlayer(body, intent, forwardX, forwardZ, walkSpeed, dt, isSolid, dims, tuning.physics, tuning.hasTerrain ? (x, z) => tuning.ground.sampleHeight(x, z) : undefined);
+        advanceVoxelPlayer(body, intent, forwardX, forwardZ, walkSpeed, dt, isSolid, dims, tuning.physics, tuning.hasTerrain ? (x, z) => tuning.ground.sampleHeight(x, z) : undefined, { authoritativeStep: tuning.authoritativeStep });
+        const motorProposalAccepted = motionBatch === null || motionBatch.y === null || motionBatch.y === body.y;
         if (motionBatch !== null && motionBatch.y !== null)
             body.y = motionBatch.y;
         ctx.scene.entity.setPose(playerId, {
@@ -460,6 +656,10 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
             rotationY: resolveBodyFacing(state, intent.moving, body.velocityX, body.velocityZ, player.rotationY, tuning.movement?.turnSpeed, dt),
             dt,
         });
+        if (motorProposalAccepted && positionAccepted(ctx, playerId, body.x, body.y, body.z))
+            updateTelemetry(state, playerId, body.grounded, body.velocityY, intent.crouching);
+        else
+            invalidateTelemetry(state);
         return;
     }
     let motion = state.motion;
@@ -485,9 +685,10 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
         state.jumpBuffer = jumpBuffer;
     }
     const motionOptions = submerged
-        ? { speedScale: swimSpeedMultiplier, floating: true, buffer: jumpBuffer }
-        : { buffer: jumpBuffer };
+        ? { speedScale: swimSpeedMultiplier, floating: true, buffer: jumpBuffer, authoritativeStep: tuning.authoritativeStep }
+        : { buffer: jumpBuffer, externalGrounding: true, authoritativeStep: tuning.authoritativeStep };
     const prevJumpOffset = motion.jumpOffset;
+    const groundedBeforeStep = motion.grounded;
     const step = advancePlayerMotion(motion, intent, forwardX, forwardZ, walkSpeed, dt, tuning.physics, motionOptions);
     // Airborne means "not resting on the surface below": any jump/impulse height before or after this
     // frame's integration. Grounded-only forgiveness (step-up) and airborne-only landing key off it.
@@ -500,11 +701,14 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
         stepZ = constrained.stepZ;
     }
     const stepHeight = tuning.movement?.stepHeight ?? DEFAULT_PLAYER_STEP_HEIGHT;
+    const verticalStep = airborne ? motion.jumpOffset - prevJumpOffset : 0;
+    const queryMinStepY = Math.min(0, verticalStep);
+    const queryMaxStepY = Math.max(stepHeight, verticalStep);
     let obstacles = null;
     if (tuning.movement?.collideObjects !== false) {
-        obstacles = gatherMovementObstacles(ctx, player.position, stepX, stepZ);
+        obstacles = gatherMovementObstacles(ctx, player.position, stepX, stepZ, queryMinStepY, queryMaxStepY, collisionHeight);
         // While grounded, a box the player could simply step onto is a ledge, not a wall.
-        const resolved = resolveObstacleStep(player.position, stepX, stepZ, obstacles, DEFAULT_OBSTACLE_PLAYER_RADIUS, airborne ? 0 : stepHeight);
+        const resolved = resolveObstacleStep(player.position, stepX, stepZ, obstacles, DEFAULT_OBSTACLE_PLAYER_RADIUS, airborne ? 0 : stepHeight, collisionHeight);
         stepX = resolved.stepX;
         stepZ = resolved.stepZ;
     }
@@ -527,46 +731,155 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
             nextZ += slope.downhill[1] * slide;
         }
     }
-    const groundAtNext = tuning.ground.sampleHeight(nextX, nextZ);
+    const maxClimbGrade = tuning.movement?.maxClimbGrade;
+    // The full/X/Z candidates share four unique grade samples (origin and three endpoints), even
+    // when headroom rejects the grade resolver's first choice. Preserve the game sampler's budget.
+    const gradeSamples = maxClimbGrade === undefined ? null : [];
+    const gradeSampler = (x, z) => {
+        for (const sample of gradeSamples)
+            if (sample.x === x && sample.z === z)
+                return sample.height;
+        const authoredSampler = tuning.movement?.climbGradeHeight;
+        const height = authoredSampler === undefined ? tuning.ground.sampleHeight(x, z) : authoredSampler(x, z);
+        gradeSamples.push({ x, z, height });
+        return height;
+    };
+    if (maxClimbGrade !== undefined) {
+        const accepted = resolveTerrainGradeStep(gradeSampler, player.position, nextX - player.position[0], nextZ - player.position[2], maxClimbGrade);
+        nextX = player.position[0] + accepted.stepX;
+        nextZ = player.position[2] + accepted.stepZ;
+    }
     // Blocking colliders are walkable surfaces: the effective ground under the player is the higher of
     // the terrain and the tallest object top the player can stand on here. While grounded a top within
     // stepHeight above the feet is stepped onto (matching the obstruction's ledge forgiveness); while
     // airborne only tops at/below the feet catch, so a jump lands ON a crate instead of sinking inside
     // it and being rubber-banded out by depenetration.
-    const supportY = obstacles !== null
-        ? obstacleSupportHeight(nextX, nextZ, player.position[1], airborne ? 0 : stepHeight, obstacles)
-        : null;
-    const effectiveGround = supportY !== null && supportY > groundAtNext ? supportY : groundAtNext;
-    let nextY;
-    if (airborne) {
-        // Integrate the jump arc in absolute space (previous feet + this frame's offset delta) so the
-        // arc stays continuous when the ground under the player changes mid-flight, and land on the
-        // effective ground — terrain or object top — the moment the descending feet reach it.
-        const nextFeet = player.position[1] + (motion.jumpOffset - prevJumpOffset);
-        if (nextFeet <= effectiveGround && motion.verticalVelocity <= 0) {
-            nextY = effectiveGround;
-            motion.jumpOffset = 0;
-            motion.verticalVelocity = 0;
-            motion.grounded = true;
-        }
-        else {
-            nextY = Math.max(nextFeet, effectiveGround);
-            motion.jumpOffset = nextY - effectiveGround;
-            motion.grounded = false;
+    const absoluteHeightOverride = motionBatch?.y !== undefined && motionBatch.y !== null;
+    const terrainSamples = [];
+    const terrainHeightAt = (x, z) => {
+        for (const sample of terrainSamples)
+            if (sample.x === x && sample.z === z)
+                return sample.height;
+        const height = tuning.ground.sampleHeight(x, z);
+        terrainSamples.push({ x, z, height });
+        return height;
+    };
+    if (obstacles !== null && !absoluteHeightOverride) {
+        // A terrain-following style may accept a rise taller than stepHeight. Include those proposed
+        // full/X/Z body spans without querying the whole world or falling all the way to distant ground.
+        const rise = Math.max(terrainHeightAt(nextX, nextZ), terrainHeightAt(nextX, player.position[2]), terrainHeightAt(player.position[0], nextZ)) - player.position[1];
+        if (rise > queryMaxStepY) {
+            obstacles = gatherMovementObstacles(ctx, player.position, nextX - player.position[0], nextZ - player.position[2], queryMinStepY, rise, collisionHeight);
         }
     }
-    else if (!submerged && player.position[1] - effectiveGround > stepHeight) {
-        // Walked off a ledge taller than a step (a crate edge, a cliff): fall under gravity from here
-        // instead of teleporting the feet down to the ground in one frame.
-        nextY = player.position[1];
-        motion.jumpOffset = nextY - effectiveGround;
-        motion.verticalVelocity = 0;
-        motion.grounded = false;
-    }
-    else {
-        nextY = effectiveGround;
+    const validStartingBounds = obstacles === null || !resolveObstacleVerticalStep(player.position, 0, obstacles, DEFAULT_OBSTACLE_PLAYER_RADIUS, collisionHeight).initialOverlap;
+    const resolveCandidate = (x, z) => {
+        const terrainHeight = terrainHeightAt(x, z);
+        const supportY = obstacles === null ? null : obstacleSupportHeight(x, z, player.position[1], airborne ? 0 : stepHeight, obstacles);
+        const ground = supportY !== null && supportY > terrainHeight ? supportY : terrainHeight;
+        let y = ground;
+        let grounded = motion.grounded;
+        let velocity = motion.verticalVelocity;
+        let offset = motion.jumpOffset;
+        let rising = motion.jumpRising;
+        let blockedRise = false;
+        if (airborne) {
+            // Keep the arc in absolute space while the terrain/support changes below it.
+            const nextFeet = player.position[1] + (motion.jumpOffset - prevJumpOffset);
+            if (nextFeet <= ground && velocity <= 0) {
+                offset = 0;
+                velocity = 0;
+                grounded = true;
+            }
+            else {
+                y = Math.max(nextFeet, ground);
+                offset = y - ground;
+                grounded = false;
+            }
+        }
+        else if (!submerged && player.position[1] - ground > stepHeight) {
+            y = player.position[1];
+            offset = y - ground;
+            velocity = 0;
+            grounded = false;
+        }
+        if (obstacles !== null && !absoluteHeightOverride) {
+            const vertical = resolveObstacleVerticalStep([x, player.position[1], z], y - player.position[1], obstacles, DEFAULT_OBSTACLE_PLAYER_RADIUS, collisionHeight);
+            if (vertical.hitCeiling) {
+                const clippedY = player.position[1] + vertical.stepY;
+                // A surface above the ceiling cannot be reached by snapping entirely through a thin roof.
+                blockedRise = ground > vertical.ceilingFeetY + vertical.ceilingTolerance;
+                y = Math.max(clippedY, ground);
+                offset = Math.max(0, y - ground);
+                velocity = 0;
+                rising = false;
+                grounded = y === ground;
+            }
+            else if (vertical.landed) {
+                y = player.position[1] + vertical.stepY;
+                offset = 0;
+                velocity = 0;
+                rising = false;
+                grounded = true;
+            }
+        }
+        const clear = obstacles === null || absoluteHeightOverride || !validStartingBounds ||
+            (!blockedRise && !resolveObstacleVerticalStep([x, y, z], 0, obstacles, DEFAULT_OBSTACLE_PLAYER_RADIUS, collisionHeight).initialOverlap);
+        return { x, z, y, ground, grounded, velocity, offset, rising, clear };
+    };
+    let candidate = resolveCandidate(nextX, nextZ);
+    if (!candidate.clear) {
+        const gradeAllows = (x, z) => {
+            if (maxClimbGrade === undefined)
+                return true;
+            const accepted = resolveTerrainGradeStep(gradeSampler, player.position, x - player.position[0], z - player.position[2], maxClimbGrade);
+            return accepted.stepX === x - player.position[0] && accepted.stepZ === z - player.position[2];
+        };
+        const tryAxis = (x, z) => {
+            if (obstacles !== null) {
+                // The original Z sweep used post-X coordinates. An alternate axis must be swept again from
+                // the original pose; reject a changed endpoint rather than accepting an unsampled grade.
+                const swept = resolveObstacleStep(player.position, x - player.position[0], z - player.position[2], obstacles, DEFAULT_OBSTACLE_PLAYER_RADIUS, airborne ? 0 : stepHeight, collisionHeight);
+                if (swept.stepX !== x - player.position[0] || swept.stepZ !== z - player.position[2])
+                    return false;
+            }
+            if (!gradeAllows(x, z))
+                return false;
+            const alternative = resolveCandidate(x, z);
+            if (!alternative.clear)
+                return false;
+            candidate = alternative;
+            return true;
+        };
+        const xAccepted = nextX !== player.position[0] && tryAxis(nextX, player.position[2]);
+        const zAccepted = !xAccepted && nextZ !== player.position[2] && tryAxis(player.position[0], nextZ);
+        if (!xAccepted && !zAccepted) {
+            candidate = resolveCandidate(player.position[0], player.position[2]);
+            if (!candidate.clear) {
+                // An inflated support edge cannot raise the body into a lintel. Retain the valid starting
+                // pose rather than forcing feet into support or repairing an illegal authored placement.
+                candidate.y = player.position[1];
+                candidate.grounded = groundedBeforeStep;
+                candidate.offset = prevJumpOffset;
+                candidate.velocity = groundedBeforeStep ? 0 : motion.verticalVelocity;
+                candidate.rising = groundedBeforeStep ? false : motion.jumpRising;
+            }
+        }
     }
+    nextX = candidate.x;
+    nextZ = candidate.z;
+    let nextY = candidate.y;
+    const effectiveGround = candidate.ground;
+    motion.grounded = candidate.grounded;
+    motion.verticalVelocity = candidate.velocity;
+    motion.jumpOffset = candidate.offset;
+    motion.jumpRising = candidate.rising;
+    let motorProposalAccepted = true;
+    if (!groundedBeforeStep && motion.grounded)
+        motion.landedAtMs = motion.clockMs;
+    motion.wasAirborne = !motion.grounded;
     if (motionBatch !== null && motionBatch.y !== null) {
+        motorProposalAccepted = motionBatch.y === nextY;
         nextY = motionBatch.y;
         motion.jumpOffset = motionBatch.y - effectiveGround;
     }
@@ -583,6 +896,7 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
         };
         const replacement = tuning.movement.beforeCommit(frame);
         if (replacement !== undefined) {
+            motorProposalAccepted = motorProposalAccepted && replacement[0] === nextX && replacement[1] === nextY && replacement[2] === nextZ;
             nextX = replacement[0];
             nextY = replacement[1];
             nextZ = replacement[2];
@@ -593,11 +907,20 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
         rotationY: resolveBodyFacing(state, intent.moving, motion.horizontalVelocityX, motion.horizontalVelocityZ, player.rotationY, tuning.movement?.turnSpeed, dt),
         dt,
     });
+    if (motorProposalAccepted && positionAccepted(ctx, playerId, nextX, nextY, nextZ))
+        updateTelemetry(state, playerId, motion.grounded, motion.verticalVelocity, intent.crouching, collisionHeight, requestedCollisionHeight, collisionHeightBlocked);
+    else
+        invalidateTelemetry(state);
 }
 /**
  * The player's blocking obstacles for this step, from the shared solid seam. A walking NPC calls
  * `resolveWalkerStep` against the same query, so "solid" means one thing engine-wide.
  */
-function gatherMovementObstacles(ctx, position, stepX, stepZ) {
-    return solidObstaclesNear(ctx, position, Math.abs(stepX) + DEFAULT_OBSTACLE_PLAYER_RADIUS, Math.abs(stepZ) + DEFAULT_OBSTACLE_PLAYER_RADIUS);
+function gatherMovementObstacles(ctx, position, stepX, stepZ, minStepY = 0, maxStepY = 0, playerHeight = DEFAULT_OBSTACLE_PLAYER_HEIGHT) {
+    if (!Number.isFinite(minStepY) || !Number.isFinite(maxStepY))
+        throw new RangeError("Movement obstacle query requires a finite vertical step.");
+    const minY = Math.min(0, minStepY);
+    const maxY = Math.max(0, maxStepY);
+    const queryPosition = minY < 0 ? [position[0], position[1] + minY, position[2]] : position;
+    return solidObstaclesNear(ctx, queryPosition, Math.abs(stepX) + DEFAULT_OBSTACLE_PLAYER_RADIUS, Math.abs(stepZ) + DEFAULT_OBSTACLE_PLAYER_RADIUS, playerHeight + maxY - minY);
 }