@jgengine/core 0.10.0 → 0.12.0

package/dist/movement/movementModel.d.ts

@@ -12,6 +12,7 @@
  */
 export type MovementKey = "w" | "a" | "s" | "d" | "shift" | "control" | "c" | "space";
 export type MovementKeysState = Record<MovementKey, boolean>;
+/** @internal */
 export declare function createEmptyMovementKeys(): MovementKeysState;
 /**
  * Frame-independent description of what the player is asking the avatar to do.
@@ -31,7 +32,8 @@ export interface MovementIntent {
  * Translate the set of held keys into an intent. When `canMove` is false (a
  * menu is open, the world is paused) the avatar is fully idle so it never
  * drifts behind an overlay.
- */
+  * @internal
+  */
 export declare function resolveMovementIntent(keys: MovementKeysState, canMove: boolean): MovementIntent;
 /**
  * Kinematics + feel tuning for the first-person controller. Centralised here so
@@ -43,6 +45,8 @@ export declare const MOVEMENT_TUNING: {
     readonly walkSpeedMultiplier: 1.75;
     readonly runSpeedMultiplier: 2.25;
     readonly crouchSpeedMultiplier: 0.45;
+    /** Backward (S) travels this fraction of walk speed so retreating reads slower than advancing. */
+    readonly backpedalSpeedMultiplier: 0.65;
     readonly groundAcceleration: 26;
     readonly airAcceleration: 12;
     readonly groundFriction: 18;
@@ -74,6 +78,7 @@ export interface PlayerMotionState {
     grounded: boolean;
     jumpHeld: boolean;
 }
+/** @internal */
 export declare function createPlayerMotionState(): PlayerMotionState;
 /** Horizontal step (world units) the avatar should commit this frame. */
 export interface MovementFrameStep {
@@ -87,6 +92,19 @@ export interface MovementFrameStep {
 export interface MovementTuningOverrides {
     gravityAcceleration?: number;
     jumpVelocity?: number;
+    /** Fraction of walk speed while backpedalling; overrides {@link MOVEMENT_TUNING.backpedalSpeedMultiplier}. */
+    backpedalSpeedMultiplier?: number;
+}
+/**
+ * Per-frame dynamic modifiers for {@link advancePlayerMotion} — state the caller
+ * recomputes each tick (unlike the static {@link MovementTuningOverrides}). Omitted
+ * fields leave the integrator at its default behavior.
+ */
+export interface MotionFrameOptions {
+    /** 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;
 }
 /**
  * Advance one frame of avatar kinematics. Mutates `motion` (velocity, jump,
@@ -97,14 +115,29 @@ export interface MovementTuningOverrides {
  * (need not be normalized); the avatar's right axis is derived from it. Pulling
  * this out of the render loop is what lets us assert "held forward for N frames
  * crosses the room" in a unit test instead of only in the live game.
- */
-export declare function advancePlayerMotion(motion: PlayerMotionState, intent: MovementIntent, forwardX: number, forwardZ: number, baseSpeed: number, rawDeltaSeconds: number, tuning?: MovementTuningOverrides): MovementFrameStep;
+  * @internal
+  */
+export declare function advancePlayerMotion(motion: PlayerMotionState, intent: MovementIntent, forwardX: number, forwardZ: number, baseSpeed: number, rawDeltaSeconds: number, tuning?: MovementTuningOverrides, options?: MotionFrameOptions): MovementFrameStep;
 /** A placed scene object the walking player collides against as a circle-vs-AABB obstacle. */
 export interface CollisionObstacle {
     position: readonly [number, number, number];
-    /** Box half-size on each axis. Default `[0.5, 0.5, 0.5]` (unit-box scene objects). */
+    /** Box half-size on each axis. Default `[0.5, 0.5, 0.5]` (unit-box scene objects). Ignored when `boxes` is set. */
     halfExtents?: readonly [number, number, number];
+    /** Local center shift added to `position` for the single-AABB path (the collider's yaw-rotated offset). Ignored when `boxes` is set. */
+    offset?: readonly [number, number, number];
+    /**
+     * Optional compound solid: axis-aligned sub-boxes as `min`/`max` **relative to `position`** (add
+     * `position` for world space), already yaw-rotated and conservatively expanded by the caller. When
+     * present the capsule slides against EACH sub-box instead of the single `halfExtents` AABB, so a
+     * concave opening (the gap between an archway's pillars/lintel) lets the capsule pass through.
+     */
+    boxes?: readonly {
+        min: readonly [number, number, number];
+        max: readonly [number, number, number];
+    }[];
 }
+/** @internal Player radius the walking obstruction inflates obstacles by; callers gather within reach of it. */
+export declare const DEFAULT_OBSTACLE_PLAYER_RADIUS = 0.3;
 /**
  * Resolve a horizontal step against nearby placed objects with classic
  * axis-separated sliding (try X, then Z against the post-X position) so
@@ -113,21 +146,29 @@ export interface CollisionObstacle {
  * by `playerRadius`; an obstacle whose vertical span misses the player's
  * feet-to-head span is skipped entirely. Callers should pre-filter to nearby
  * objects — this also early-exits per obstacle on horizontal distance.
- */
+  * @internal
+  */
 export declare function resolveObstacleStep(current: readonly [number, number, number], stepX: number, stepZ: number, obstacles: readonly CollisionObstacle[], playerRadius?: number): MovementFrameStep;
-/** Placed objects within `radius` (XZ) of `center`, as {@link CollisionObstacle}s to pre-filter for {@link resolveObstacleStep}. */
+/** Placed objects within `radius` (XZ) of `center`, as {@link CollisionObstacle}s to pre-filter for {@link resolveObstacleStep}.
+ * @internal
+ */
 export declare function nearbyObstacles(objects: readonly {
     position: readonly [number, number, number];
 }[], center: readonly [number, number, number], radius?: number): CollisionObstacle[];
-/** Zeroes the off-axis component so travel is locked to a single world axis (`PlayerMovementConfig.mode: "axis"`). */
+/** Zeroes the off-axis component so travel is locked to a single world axis (`PlayerMovementConfig.mode: "axis"`).
+ * @internal
+ */
 export declare function constrainStepToAxis(stepX: number, stepZ: number, axis: "x" | "z"): MovementFrameStep;
 /**
  * Snap a world position to its containing cell's center, matching the
  * bounds-free form of `navGrid`'s and `tacticalGrid`'s `floor` + half-cell
  * convention (`PlayerMovementConfig.mode: "grid"`).
- */
+  * @internal
+  */
 export declare function snapPositionToGrid(x: number, z: number, cellSize: number): [number, number];
 /** Peak jump height from MOVEMENT_TUNING.jumpVelocity + gravity, with small buffer. */
 export declare const MAX_JUMP_OFFSET = 1.15;
-/** Camera yaw looks along -Z; character mesh faces +Z at body rotation.y = 0. */
+/** Camera yaw looks along -Z; character mesh faces +Z at body rotation.y = 0.
+ * @internal
+ */
 export declare function cameraYawToAvatarBodyYaw(cameraYaw: number): number;

package/dist/movement/movementModel.js

@@ -10,6 +10,7 @@
  * 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 };
 }
@@ -25,7 +26,8 @@ const IDLE_INTENT = {
  * Translate the set of held keys into an intent. When `canMove` is false (a
  * menu is open, the world is paused) the avatar is fully idle so it never
  * drifts behind an overlay.
- */
+  * @internal
+  */
 export function resolveMovementIntent(keys, canMove) {
     if (!canMove)
         return IDLE_INTENT;
@@ -52,6 +54,8 @@ export const MOVEMENT_TUNING = {
     walkSpeedMultiplier: 1.75,
     runSpeedMultiplier: 2.25,
     crouchSpeedMultiplier: 0.45,
+    /** Backward (S) travels this fraction of walk speed so retreating reads slower than advancing. */
+    backpedalSpeedMultiplier: 0.65,
     groundAcceleration: 26,
     airAcceleration: 12,
     groundFriction: 18,
@@ -70,15 +74,24 @@ export const MOVEMENT_TUNING = {
     /** Largest physics step we integrate so a stalled tab can't teleport the player. */
     maxFrameSeconds: 0.05,
 };
-/** Speed (units/s) the avatar should target given the active intent. */
-function resolveTargetSpeed(intent, baseSpeed) {
+/**
+ * Speed (units/s) the avatar should target given the active intent. Crouch and run
+ * take precedence over backpedal; a plain backward intent (`forward < 0`) slows to
+ * {@link MOVEMENT_TUNING.backpedalSpeedMultiplier} (overridable via `tuning`), while a
+ * pure strafe keeps full speed.
+ */
+function resolveTargetSpeed(intent, baseSpeed, tuning) {
+    const backpedal = tuning?.backpedalSpeedMultiplier ?? MOVEMENT_TUNING.backpedalSpeedMultiplier;
     const speedMultiplier = intent.crouching
         ? MOVEMENT_TUNING.crouchSpeedMultiplier
         : intent.running
             ? MOVEMENT_TUNING.runSpeedMultiplier
-            : 1;
+            : intent.forward < 0
+                ? backpedal
+                : 1;
     return baseSpeed * MOVEMENT_TUNING.walkSpeedMultiplier * speedMultiplier;
 }
+/** @internal */
 export function createPlayerMotionState() {
     return {
         horizontalVelocityX: 0,
@@ -98,10 +111,11 @@ export function createPlayerMotionState() {
  * (need not be normalized); the avatar's right axis is derived from it. Pulling
  * this out of the render loop is what lets us assert "held forward for N frames
  * crosses the room" in a unit test instead of only in the live game.
- */
-export function advancePlayerMotion(motion, intent, forwardX, forwardZ, baseSpeed, rawDeltaSeconds, tuning) {
+  * @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);
+    const targetSpeed = resolveTargetSpeed(intent, baseSpeed, tuning) * (options?.speedScale ?? 1);
     const gravityAcceleration = tuning?.gravityAcceleration ?? MOVEMENT_TUNING.gravityAcceleration;
     const jumpVelocity = tuning?.jumpVelocity ?? MOVEMENT_TUNING.jumpVelocity;
     let targetVelocityX = 0;
@@ -146,13 +160,19 @@ export function advancePlayerMotion(motion, intent, forwardX, forwardZ, baseSpee
         motion.horizontalVelocityX *= friction;
         motion.horizontalVelocityZ *= friction;
     }
+    const floating = options?.floating === true;
     const jumpPressed = intent.jumping;
-    if (jumpPressed && !motion.jumpHeld && motion.grounded && !intent.crouching) {
+    if (jumpPressed && !motion.jumpHeld && motion.grounded && !intent.crouching && !floating) {
         motion.verticalVelocity = jumpVelocity;
         motion.grounded = false;
     }
     motion.jumpHeld = jumpPressed;
-    if (!motion.grounded || motion.verticalVelocity > 0) {
+    if (floating) {
+        motion.verticalVelocity = 0;
+        motion.jumpOffset = 0;
+        motion.grounded = true;
+    }
+    else if (!motion.grounded || motion.verticalVelocity > 0) {
         motion.verticalVelocity -= gravityAcceleration * deltaSeconds;
         motion.jumpOffset += motion.verticalVelocity * deltaSeconds;
         if (motion.jumpOffset <= 0) {
@@ -167,7 +187,8 @@ export function advancePlayerMotion(motion, intent, forwardX, forwardZ, baseSpee
     };
 }
 const DEFAULT_OBSTACLE_HALF_EXTENTS = [0.5, 0.5, 0.5];
-const DEFAULT_OBSTACLE_PLAYER_RADIUS = 0.3;
+/** @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;
 function clampAxisStep(originalCoord, step, min, max) {
@@ -188,29 +209,47 @@ function clampAxisStep(originalCoord, step, min, max) {
  * by `playerRadius`; an obstacle whose vertical span misses the player's
  * feet-to-head span is skipped entirely. Callers should pre-filter to nearby
  * objects — this also early-exits per obstacle on horizontal distance.
- */
+  * @internal
+  */
 export function resolveObstacleStep(current, stepX, stepZ, obstacles, playerRadius = DEFAULT_OBSTACLE_PLAYER_RADIUS) {
     const feetY = current[1];
     const headY = feetY + OBSTACLE_PLAYER_HEIGHT;
     const reachX = Math.abs(stepX) + playerRadius;
     const reachZ = Math.abs(stepZ) + playerRadius;
     const nearby = [];
-    for (const obstacle of obstacles) {
-        const halfExtents = obstacle.halfExtents ?? DEFAULT_OBSTACLE_HALF_EXTENTS;
-        const obstacleBottom = obstacle.position[1] - halfExtents[1];
-        const obstacleTop = obstacle.position[1] + halfExtents[1];
-        if (obstacleTop <= feetY || obstacleBottom >= headY)
-            continue;
-        const dx = obstacle.position[0] - current[0];
-        const dz = obstacle.position[2] - current[2];
-        if (Math.abs(dx) > halfExtents[0] + reachX || Math.abs(dz) > halfExtents[2] + reachZ)
-            continue;
+    const considerBox = (minX, maxX, minY, maxY, minZ, maxZ) => {
+        // Vertical-span cull: a sub-box entirely above the head (walk under the lintel) or below the feet is skipped.
+        if (maxY <= feetY || minY >= headY)
+            return;
+        const centerX = (minX + maxX) / 2;
+        const centerZ = (minZ + maxZ) / 2;
+        const halfX = (maxX - minX) / 2;
+        const halfZ = (maxZ - minZ) / 2;
+        if (Math.abs(centerX - current[0]) > halfX + reachX || Math.abs(centerZ - current[2]) > halfZ + reachZ)
+            return;
         nearby.push({
-            minX: obstacle.position[0] - halfExtents[0] - playerRadius,
-            maxX: obstacle.position[0] + halfExtents[0] + playerRadius,
-            minZ: obstacle.position[2] - halfExtents[2] - playerRadius,
-            maxZ: obstacle.position[2] + halfExtents[2] + playerRadius,
+            minX: minX - playerRadius,
+            maxX: maxX + playerRadius,
+            minZ: minZ - playerRadius,
+            maxZ: maxZ + playerRadius,
         });
+    };
+    for (const obstacle of obstacles) {
+        const px = obstacle.position[0];
+        const py = obstacle.position[1];
+        const pz = obstacle.position[2];
+        if (obstacle.boxes !== undefined && obstacle.boxes.length > 0) {
+            for (const box of obstacle.boxes) {
+                considerBox(px + box.min[0], px + box.max[0], py + box.min[1], py + box.max[1], pz + box.min[2], pz + box.max[2]);
+            }
+            continue;
+        }
+        const halfExtents = obstacle.halfExtents ?? DEFAULT_OBSTACLE_HALF_EXTENTS;
+        const offset = obstacle.offset;
+        const cx = px + (offset !== undefined ? offset[0] : 0);
+        const cy = py + (offset !== undefined ? offset[1] : 0);
+        const cz = pz + (offset !== undefined ? offset[2] : 0);
+        considerBox(cx - halfExtents[0], cx + halfExtents[0], cy - halfExtents[1], cy + halfExtents[1], cz - halfExtents[2], cz + halfExtents[2]);
     }
     let resultX = stepX;
     for (const box of nearby) {
@@ -228,7 +267,9 @@ export function resolveObstacleStep(current, stepX, stepZ, obstacles, playerRadi
     return { stepX: resultX, stepZ: resultZ };
 }
 const OBSTACLE_GATHER_RADIUS = 3;
-/** Placed objects within `radius` (XZ) of `center`, as {@link CollisionObstacle}s to pre-filter for {@link resolveObstacleStep}. */
+/** Placed objects within `radius` (XZ) of `center`, as {@link CollisionObstacle}s to pre-filter for {@link resolveObstacleStep}.
+ * @internal
+ */
 export function nearbyObstacles(objects, center, radius = OBSTACLE_GATHER_RADIUS) {
     const radiusSq = radius * radius;
     const result = [];
@@ -240,7 +281,9 @@ export function nearbyObstacles(objects, center, radius = OBSTACLE_GATHER_RADIUS
     }
     return result;
 }
-/** Zeroes the off-axis component so travel is locked to a single world axis (`PlayerMovementConfig.mode: "axis"`). */
+/** Zeroes the off-axis component so travel is locked to a single world axis (`PlayerMovementConfig.mode: "axis"`).
+ * @internal
+ */
 export function constrainStepToAxis(stepX, stepZ, axis) {
     return axis === "x" ? { stepX, stepZ: 0 } : { stepX: 0, stepZ };
 }
@@ -248,13 +291,16 @@ export function constrainStepToAxis(stepX, stepZ, axis) {
  * Snap a world position to its containing cell's center, matching the
  * bounds-free form of `navGrid`'s and `tacticalGrid`'s `floor` + half-cell
  * convention (`PlayerMovementConfig.mode: "grid"`).
- */
+  * @internal
+  */
 export function snapPositionToGrid(x, z, cellSize) {
     return [(Math.floor(x / cellSize) + 0.5) * cellSize, (Math.floor(z / cellSize) + 0.5) * cellSize];
 }
 /** Peak jump height from MOVEMENT_TUNING.jumpVelocity + gravity, with small buffer. */
 export const MAX_JUMP_OFFSET = 1.15;
-/** Camera yaw looks along -Z; character mesh faces +Z at body rotation.y = 0. */
+/** Camera yaw looks along -Z; character mesh faces +Z at body rotation.y = 0.
+ * @internal
+ */
 export function cameraYawToAvatarBodyYaw(cameraYaw) {
     return cameraYaw + Math.PI;
 }

package/dist/movement/playerMovement.js

@@ -1,10 +1,16 @@
 import { applyHorizontalImpulses, applyMotionImpulses } from "../runtime/motionIntents.js";
-import { groundFieldFor, hasEnvironmentTerrain } from "../world/terrain.js";
-import { advancePlayerMotion, constrainStepToAxis, createEmptyMovementKeys, createPlayerMotionState, nearbyObstacles, resolveMovementIntent, resolveObstacleStep, snapPositionToGrid, } from "./movementModel.js";
-import { steerYaw } from "./steering.js";
+import { groundFieldFor, hasEnvironmentTerrain, sampleSlope } from "../world/terrain.js";
+import { resolveColliders } from "../scene/colliders.js";
+import { advancePlayerMotion, constrainStepToAxis, createEmptyMovementKeys, createPlayerMotionState, DEFAULT_OBSTACLE_PLAYER_RADIUS, resolveMovementIntent, resolveObstacleStep, snapPositionToGrid, } from "./movementModel.js";
+import { approachYaw, steerYaw } from "./steering.js";
 import { advanceVoxelPlayer, createVoxelPlayerBody, } from "./voxelController.js";
 const DEFAULT_TURN_SPEED = 2.4;
 const DEFAULT_WALK_SPEED = 2;
+const DEFAULT_SWIM_SPEED_MULTIPLIER = 0.65;
+/** Minimum ground-normal `y` the player can stand on before slope-slide kicks in — cos(50°) ≈ 0.643. */
+const DEFAULT_MAX_CLIMB_NORMAL_Y = Math.cos((50 * Math.PI) / 180);
+/** Downhill slide speed (units/s) per unit of slope steepness while on too-steep ground. */
+const SLOPE_SLIDE_SPEED = 4;
 /**
  * Maps a game's declared `physics` onto the movement controllers' tuning. `PhysicsConfig.gravity` is a signed
  * world acceleration (negative points down), but the controllers integrate `velocityY -= gravityAcceleration * dt`
@@ -25,10 +31,12 @@ 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 overrides = backpedal === undefined ? physics : { ...(physics ?? {}), backpedalSpeedMultiplier: backpedal };
     return {
         ...(opts.collision === undefined ? {} : { collision: opts.collision }),
         ...(opts.movement === undefined ? {} : { movement: opts.movement }),
-        ...(physics === undefined ? {} : { physics }),
+        ...(overrides === undefined ? {} : { physics: overrides }),
         ground: groundFieldFor(opts.world),
         hasTerrain: hasEnvironmentTerrain(opts.world),
     };
@@ -45,7 +53,7 @@ function storeFor(ctx) {
 function stateFor(store, userId) {
     let state = store.players.get(userId);
     if (state === undefined) {
-        state = { heading: 0, voxelBody: null, motion: null };
+        state = { heading: 0, facing: null, voxelBody: null, motion: null };
         store.players.set(userId, state);
     }
     return state;
@@ -58,6 +66,25 @@ export function playerMovementHeading(ctx, userId) {
 export function forgetPlayerMovement(ctx, userId) {
     stores.get(ctx)?.players.delete(userId);
 }
+/**
+ * Rendered body yaw to commit this frame. With `turnSpeed` unset the body snaps
+ * to its movement heading exactly as before (no opt-in, no behavior change); with
+ * `turnSpeed` set it rotates toward that heading at `turnSpeed` rad/s along the
+ * shortest arc, so strafing and backpedalling read as a turning body rather than
+ * an instant flip. Retained per player so the smoothing is continuous across frames.
+ */
+function resolveBodyFacing(state, moving, velocityX, velocityZ, fallbackYaw, turnSpeed, dt) {
+    if (turnSpeed === undefined) {
+        const snapped = moving ? Math.atan2(velocityX, velocityZ) : fallbackYaw;
+        state.facing = snapped;
+        return snapped;
+    }
+    const from = state.facing ?? fallbackYaw;
+    const target = moving ? Math.atan2(velocityX, velocityZ) : from;
+    const next = approachYaw(from, target, turnSpeed, dt);
+    state.facing = next;
+    return next;
+}
 /**
  * Integrate one player's movement for a tick from their held-input frame and commit the pose — the single
  * genre-agnostic controller both the shell (its local player) and a host (each connected player in `onTick`) call,
@@ -80,8 +107,9 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, 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, DEFAULT_TURN_SPEED, dt);
+            state.heading = steerYaw(state.heading, turnInput, turnSpeed, dt);
     }
     const forwardX = Math.sin(state.heading);
     const forwardZ = Math.cos(state.heading);
@@ -120,7 +148,7 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
             body.y = motionBatch.y;
         ctx.scene.entity.setPose(playerId, {
             position: [body.x, body.y, body.z],
-            rotationY: intent.moving ? Math.atan2(body.velocityX, body.velocityZ) : player.rotationY,
+            rotationY: resolveBodyFacing(state, intent.moving, body.velocityX, body.velocityZ, player.rotationY, tuning.movement?.turnSpeed, dt),
             dt,
         });
         return;
@@ -132,7 +160,19 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
     }
     motion.verticalVelocity = applyMotionImpulses(motion.verticalVelocity, motionBatch);
     [motion.horizontalVelocityX, motion.horizontalVelocityZ] = applyHorizontalImpulses(motion.horizontalVelocityX, motion.horizontalVelocityZ, motionBatch);
-    const step = advancePlayerMotion(motion, intent, forwardX, forwardZ, walkSpeed, dt, tuning.physics);
+    const swimCfg = tuning.movement?.swim;
+    const swimEnabled = swimCfg === true || (typeof swimCfg === "object" && swimCfg !== null);
+    const swimSpeedMultiplier = typeof swimCfg === "object" && swimCfg !== null
+        ? swimCfg.speedMultiplier ?? DEFAULT_SWIM_SPEED_MULTIPLIER
+        : DEFAULT_SWIM_SPEED_MULTIPLIER;
+    const waterLevel = tuning.ground.waterLevel;
+    const submerged = swimEnabled &&
+        waterLevel !== undefined &&
+        tuning.ground.sampleHeight(player.position[0], player.position[2]) < waterLevel;
+    const motionOptions = submerged
+        ? { speedScale: swimSpeedMultiplier, floating: true }
+        : undefined;
+    const step = advancePlayerMotion(motion, intent, forwardX, forwardZ, walkSpeed, dt, tuning.physics, motionOptions);
     let stepX = step.stepX;
     let stepZ = step.stepZ;
     if (tuning.movement?.mode === "axis") {
@@ -141,7 +181,7 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
         stepZ = constrained.stepZ;
     }
     if (tuning.movement?.collideObjects === true) {
-        const obstacles = nearbyObstacles(ctx.scene.object.list(), player.position);
+        const obstacles = gatherMovementObstacles(ctx, player.position, stepX, stepZ);
         const resolved = resolveObstacleStep(player.position, stepX, stepZ, obstacles);
         stepX = resolved.stepX;
         stepZ = resolved.stepZ;
@@ -153,10 +193,26 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
         nextX = snapped[0];
         nextZ = snapped[1];
     }
-    let nextY = tuning.ground.sampleHeight(nextX, nextZ) + motion.jumpOffset;
+    const slideCfg = tuning.movement?.slopeSlide;
+    if (slideCfg === true || (typeof slideCfg === "object" && slideCfg !== null)) {
+        const maxClimbNormalY = typeof slideCfg === "object" && slideCfg.maxClimbSlope !== undefined
+            ? slideCfg.maxClimbSlope
+            : DEFAULT_MAX_CLIMB_NORMAL_Y;
+        if (tuning.ground.sampleNormal(nextX, nextZ)[1] < maxClimbNormalY) {
+            const slope = sampleSlope(tuning.ground, nextX, nextZ);
+            const slide = SLOPE_SLIDE_SPEED * slope.steepness * dt;
+            nextX += slope.downhill[0] * slide;
+            nextZ += slope.downhill[1] * slide;
+        }
+    }
+    const groundAtNext = tuning.ground.sampleHeight(nextX, nextZ);
+    let nextY = groundAtNext + motion.jumpOffset;
     if (motionBatch !== null && motionBatch.y !== null) {
         nextY = motionBatch.y;
-        motion.jumpOffset = motionBatch.y - tuning.ground.sampleHeight(nextX, nextZ);
+        motion.jumpOffset = motionBatch.y - groundAtNext;
+    }
+    else if (swimEnabled && waterLevel !== undefined && groundAtNext < waterLevel) {
+        nextY = waterLevel;
     }
     if (tuning.movement?.beforeCommit !== undefined) {
         const frame = {
@@ -175,7 +231,106 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
     }
     ctx.scene.entity.setPose(playerId, {
         position: [nextX, nextY, nextZ],
-        rotationY: intent.moving ? Math.atan2(motion.horizontalVelocityX, motion.horizontalVelocityZ) : player.rotationY,
+        rotationY: resolveBodyFacing(state, intent.moving, motion.horizontalVelocityX, motion.horizontalVelocityZ, player.rotationY, tuning.movement?.turnSpeed, dt),
         dt,
     });
 }
+/** Feet-to-head span the obstruction test uses; matches `movementModel`'s `OBSTACLE_PLAYER_HEIGHT`. */
+const OBSTACLE_PLAYER_HEIGHT = 1.8;
+/**
+ * Largest collider half-extent the bounded broadphase assumes, so an object whose blocking box reaches
+ * the player still has its center inside the `inBox` query — a ~4m wall (half-extent ~2m) is caught. An
+ * object wider than this on an axis could be missed at its far edge; raise it if a wider blocker exists.
+ */
+const OBSTACLE_MAX_HALF_EXTENT = 4;
+/**
+ * Gather the player's nearby blocking obstacles from resolved colliders — the mesh-accurate replacement
+ * for the old `nearbyObstacles(list(), …)` which emitted a default 1×1×1 box per object. Bounded by an
+ * `inBox` broadphase (reach ≥ player radius + max half-extent so wide walls can't be missed), then, per
+ * candidate, keeps only blocking physical colliders and emits their real half-extents/offset (or, for a
+ * mesh collider carrying `boxes`, the compound sub-boxes), conservatively yaw-rotated by the object's
+ * `rotationY`. Objects with no resolved collider fall back to the default box; objects whose colliders
+ * don't block stop obstructing. Runs for both the shell's local player and a host, so parity is automatic.
+ */
+function gatherMovementObstacles(ctx, position, stepX, stepZ) {
+    const reachX = Math.abs(stepX) + DEFAULT_OBSTACLE_PLAYER_RADIUS + OBSTACLE_MAX_HALF_EXTENT;
+    const reachZ = Math.abs(stepZ) + DEFAULT_OBSTACLE_PLAYER_RADIUS + OBSTACLE_MAX_HALF_EXTENT;
+    const min = [
+        position[0] - reachX,
+        position[1] - OBSTACLE_MAX_HALF_EXTENT,
+        position[2] - reachZ,
+    ];
+    const max = [
+        position[0] + reachX,
+        position[1] + OBSTACLE_PLAYER_HEIGHT + OBSTACLE_MAX_HALF_EXTENT,
+        position[2] + reachZ,
+    ];
+    const obstacles = [];
+    for (const object of ctx.scene.object.inBox(min, max)) {
+        const set = ctx.scene.object.collidersOf(object.instanceId);
+        if (set === null) {
+            // No resolved collider: preserve today's default 1×1×1 box.
+            obstacles.push({ position: object.position });
+            continue;
+        }
+        for (const collider of resolveColliders(set)) {
+            if (!collider.blocks || collider.purpose !== "physical")
+                continue;
+            obstacles.push(obstacleFromCollider(collider, object.position, object.rotationY));
+        }
+    }
+    return obstacles;
+}
+/** One blocking collider as a {@link CollisionObstacle}: a compound `boxes` obstacle for a mesh collider
+ * carrying sub-boxes, else a single half-extents/offset AABB. Yaw is applied by conservatively expanding
+ * each AABB to its rotated extent (mirroring `worldOffset`), so the obstruction never under-covers. */
+function obstacleFromCollider(collider, position, rotationY) {
+    const cos = Math.cos(rotationY);
+    const sin = Math.sin(rotationY);
+    const shape = collider.shape;
+    if (shape.kind === "mesh" && shape.boxes !== undefined && shape.boxes.length > 0) {
+        return {
+            position,
+            boxes: shape.boxes.map((b) => yawExpandLocalBox(b.min, b.max, cos, sin)),
+        };
+    }
+    let hx;
+    let hy;
+    let hz;
+    if (shape.kind === "sphere") {
+        hx = hy = hz = shape.radius;
+    }
+    else {
+        hx = shape.halfExtents[0];
+        hy = shape.halfExtents[1];
+        hz = shape.halfExtents[2];
+    }
+    const offset = shape.offset;
+    const ox = offset !== undefined ? offset[0] : 0;
+    const oy = offset !== undefined ? offset[1] : 0;
+    const oz = offset !== undefined ? offset[2] : 0;
+    return {
+        position,
+        // Rotate the offset by yaw (mirror of colliders.worldOffset), expand the extents to the rotated AABB.
+        offset: [ox * cos + oz * sin, oy, -ox * sin + oz * cos],
+        halfExtents: [Math.abs(hx * cos) + Math.abs(hz * sin), hy, Math.abs(hx * sin) + Math.abs(hz * cos)],
+    };
+}
+/** Yaw-rotate an entity-local AABB about the object origin and re-fit it to an axis-aligned box, expressed
+ * as `min`/`max` relative to `position`. Conservative: the rotated box is grown to its enclosing AABB. */
+function yawExpandLocalBox(boxMin, boxMax, cos, sin) {
+    const centerX = (boxMin[0] + boxMax[0]) / 2;
+    const centerY = (boxMin[1] + boxMax[1]) / 2;
+    const centerZ = (boxMin[2] + boxMax[2]) / 2;
+    const halfX = (boxMax[0] - boxMin[0]) / 2;
+    const halfY = (boxMax[1] - boxMin[1]) / 2;
+    const halfZ = (boxMax[2] - boxMin[2]) / 2;
+    const rcX = centerX * cos + centerZ * sin;
+    const rcZ = -centerX * sin + centerZ * cos;
+    const rhX = Math.abs(halfX * cos) + Math.abs(halfZ * sin);
+    const rhZ = Math.abs(halfX * sin) + Math.abs(halfZ * cos);
+    return {
+        min: [rcX - rhX, centerY - halfY, rcZ - rhZ],
+        max: [rcX + rhX, centerY + halfY, rcZ + rhZ],
+    };
+}

package/dist/movement/poseState.d.ts

@@ -13,11 +13,24 @@ export interface PoseAllowedStates {
 export interface PoseRejection {
     reason: string;
 }
+export interface PoseSnapshot {
+    poses: Record<string, MovementPose>;
+    aims: Record<string, AimMode>;
+}
 export interface PoseState {
     getPose(instanceId: string): MovementPose;
     setPose(instanceId: string, pose: MovementPose): PoseRejection | null;
     getAim(instanceId: string): AimMode;
     setAim(instanceId: string, mode: AimMode): PoseRejection | null;
     clear(instanceId: string): void;
+    /** Snapshot every entity's pose and aim for a whole-world save. */
+    snapshotAll(): PoseSnapshot;
+    /** Restore every entity's pose and aim from a {@link snapshotAll} payload. */
+    hydrateAll(state: PoseSnapshot): void;
 }
+/**
+ * Stance/pose transitions — stand, crouch, prone — that change the hitbox and movement.
+ *
+ * @capability crouch-prone stance/pose transitions that change the hitbox
+ */
 export declare function createPoseState(resolveAllowed: (instanceId: string) => PoseAllowedStates | null | undefined): PoseState;

package/dist/movement/poseState.js

@@ -23,6 +23,11 @@ export const POSE_HITBOX = {
         speedMultiplier: MOVEMENT_TUNING.runSpeedMultiplier,
     },
 };
+/**
+ * Stance/pose transitions — stand, crouch, prone — that change the hitbox and movement.
+ *
+ * @capability crouch-prone stance/pose transitions that change the hitbox
+ */
 export function createPoseState(resolveAllowed) {
     const poses = new Map();
     const aims = new Map();
@@ -57,5 +62,16 @@ export function createPoseState(resolveAllowed) {
             poses.delete(instanceId);
             aims.delete(instanceId);
         },
+        snapshotAll() {
+            return { poses: Object.fromEntries(poses), aims: Object.fromEntries(aims) };
+        },
+        hydrateAll(state) {
+            poses.clear();
+            for (const [id, pose] of Object.entries(state.poses))
+                poses.set(id, pose);
+            aims.clear();
+            for (const [id, aim] of Object.entries(state.aims))
+                aims.set(id, aim);
+        },
     };
 }

package/dist/movement/steering.d.ts

@@ -25,3 +25,11 @@ export declare function steerYaw(yaw: number, steerRight: number, turnRatePerSec
  * it into [-1, 1] at the call site.
  */
 export declare function steerToward(yaw: number, desiredYaw: number): number;
+/**
+ * @internal Rotate `yaw` toward `targetYaw` by at most `turnRatePerSecond * dt`
+ * radians, always along the shortest arc, snapping exactly onto the target once
+ * within a single step so it converges without overshoot or jitter — the
+ * smoothing behind a rendered body-turn (`PlayerMovementConfig.turnSpeed`). A
+ * large enough rate (or `dt`) reaches the target in one call, matching a snap.
+ */
+export declare function approachYaw(yaw: number, targetYaw: number, turnRatePerSecond: number, dt: number): number;