@jgengine/core 0.10.0 → 0.11.0

package/dist/movement/formation.js

@@ -0,0 +1,194 @@
+/**
+ * Group destination assignment: slot a moving group into a formation around a
+ * target point, then match members to slots. Shape is caller data — a
+ * {@link FormationSlotGenerator} emits slot offsets in the group's local frame
+ * ("right" = +x, "forward" = +y) and the engine ships line/box/wedge/circle
+ * only as samples; a custom generator needs no engine change. Placement and
+ * matching are pure and deterministic so the same inputs always yield the same
+ * world slots and the same assignment, which keeps them replay- and
+ * network-safe. Route planning and local collision avoidance are deliberately
+ * separate seams (`movement/avoidance`, `nav/pathFollow`): this module answers
+ * only "where should each member stand", not "how does it get there".
+ */
+import { yawForward, yawRight } from "./steering.js";
+/**
+ * Engine yaw (`rotationY`, radians) that faces from `from` toward `to` on the
+ * XZ plane, matching the `forward = (sin yaw, cos yaw)` convention. Feed the
+ * result as the `facing` of {@link placeFormation} to orient a formation along
+ * its travel direction. Returns `0` when the points coincide.
+ *
+ * @capability formation-facing group facing yaw from a travel direction on the XZ plane
+ * @consumer squad and crowd movement — orient a destination formation along its heading
+ */
+export function facingYaw(from, to) {
+    const dx = to[0] - from[0];
+    const dz = to[1] - from[1];
+    if (dx * dx + dz * dz <= 1e-18)
+        return 0;
+    return Math.atan2(dx, dz);
+}
+/**
+ * Transform a generator's local slot offsets into world XZ positions around a
+ * `destination`, rotated by `facing` (engine yaw). Slot `i` in the returned
+ * array is `generator(count)[i]` mapped through the group frame, so it stays
+ * aligned with {@link assignFormationSlots}' slot indices. Pure and allocation-
+ * light: one array of `count` points, no per-call closures retained.
+ *
+ * @capability formation-placement place a group formation's world slots around a destination
+ * @consumer squad/party/convoy movement — generate per-member destination slots around a target
+ */
+export function placeFormation(destination, facing, count, generator) {
+    if (count <= 0)
+        return [];
+    const forward = yawForward(facing);
+    const right = yawRight(facing);
+    const local = generator(count);
+    const slots = [];
+    for (let i = 0; i < count; i += 1) {
+        const offset = local[i] ?? ZERO;
+        const r = offset[0];
+        const f = offset[1];
+        slots.push([
+            destination[0] + right[0] * r + forward[0] * f,
+            destination[1] + right[1] * r + forward[1] * f,
+        ]);
+    }
+    return slots;
+}
+/**
+ * Match `members` to `slots` by a deterministic greedy nearest assignment:
+ * every (member, slot) pair is ranked by squared travel distance (minus a
+ * stickiness bonus for a member's previous slot) and assigned in order while
+ * both ends are free. Returns `assignment[member] = slot`, or `-1` for members
+ * left unmatched when there are fewer slots than members. Ties break by member
+ * then slot index, so the result is stable across runs and independent of input
+ * ordering — the property replay and lockstep multiplayer rely on. Groups are
+ * bounded, so the `O(members·slots·log)` sort is fine; this is not a per-frame
+ * whole-world pass.
+ *
+ * @capability formation-assignment stable deterministic member-to-slot matching for a group formation
+ * @consumer squad/party movement — assign each member a destination slot with low reshuffle churn
+ */
+export function assignFormationSlots(members, slots, options = {}) {
+    const memberCount = members.length;
+    const slotCount = slots.length;
+    const assignment = new Array(memberCount).fill(-1);
+    if (memberCount === 0 || slotCount === 0)
+        return assignment;
+    const previous = options.previous;
+    const stickiness = options.stickiness ?? 0;
+    const pairs = [];
+    for (let m = 0; m < memberCount; m += 1) {
+        const member = members[m];
+        const keepSlot = previous?.[m];
+        for (let s = 0; s < slotCount; s += 1) {
+            const slot = slots[s];
+            const dx = slot[0] - member[0];
+            const dz = slot[1] - member[1];
+            let cost = dx * dx + dz * dz;
+            if (stickiness > 0 && keepSlot === s)
+                cost -= stickiness;
+            pairs.push({ member: m, slot: s, cost });
+        }
+    }
+    pairs.sort((a, b) => a.cost !== b.cost ? a.cost - b.cost : a.member !== b.member ? a.member - b.member : a.slot - b.slot);
+    const slotTaken = new Array(slotCount).fill(false);
+    let filled = 0;
+    const need = Math.min(memberCount, slotCount);
+    for (let p = 0; p < pairs.length && filled < need; p += 1) {
+        const pair = pairs[p];
+        if (assignment[pair.member] !== -1 || slotTaken[pair.slot])
+            continue;
+        assignment[pair.member] = pair.slot;
+        slotTaken[pair.slot] = true;
+        filled += 1;
+    }
+    return assignment;
+}
+const ZERO = [0, 0];
+/**
+ * A single rank abreast, centered on the destination and facing forward — a
+ * skirmish line or a chorus row. Slots run left→right along the group's right
+ * axis.
+ *
+ * @capability formation-line line (abreast) slot generator for group destinations
+ * @consumer squad movement — line formation sample policy for {@link placeFormation}
+ */
+export function lineFormation(options) {
+    const spacing = options.spacing;
+    return (count) => {
+        const slots = [];
+        const mid = (count - 1) / 2;
+        for (let i = 0; i < count; i += 1)
+            slots.push([(i - mid) * spacing, 0]);
+        return slots;
+    };
+}
+/**
+ * A rectangular grid centered on the destination, front row toward `+forward` —
+ * a marching block or a phalanx. Rows fill front-to-back, left-to-right.
+ *
+ * @capability formation-box box/grid slot generator for group destinations
+ * @consumer squad movement — box formation sample policy for {@link placeFormation}
+ */
+export function boxFormation(options) {
+    const spacing = options.spacing;
+    const fixedColumns = options.columns;
+    return (count) => {
+        const columns = Math.max(1, fixedColumns ?? Math.ceil(Math.sqrt(count)));
+        const rows = Math.ceil(count / columns);
+        const midCol = (columns - 1) / 2;
+        const midRow = (rows - 1) / 2;
+        const slots = [];
+        for (let i = 0; i < count; i += 1) {
+            const row = Math.floor(i / columns);
+            const col = i % columns;
+            slots.push([(col - midCol) * spacing, (midRow - row) * spacing]);
+        }
+        return slots;
+    };
+}
+/**
+ * A "V"/arrowhead with the apex at the destination and arms trailing back — a
+ * flying-wedge charge or a goose skein. Slot 0 is the tip; later slots alternate
+ * right then left, each rank stepping one `spacing` outward and backward.
+ *
+ * @capability formation-wedge wedge/arrowhead slot generator for group destinations
+ * @consumer squad movement — wedge formation sample policy for {@link placeFormation}
+ */
+export function wedgeFormation(options) {
+    const spacing = options.spacing;
+    return (count) => {
+        const slots = [];
+        for (let i = 0; i < count; i += 1) {
+            if (i === 0) {
+                slots.push([0, 0]);
+                continue;
+            }
+            const rank = Math.ceil(i / 2);
+            const side = i % 2 === 1 ? 1 : -1;
+            slots.push([side * rank * spacing, -rank * spacing]);
+        }
+        return slots;
+    };
+}
+/**
+ * An evenly spaced ring around the destination — a guard cordon, a huddle, or a
+ * surround. Slot 0 sits `startAngle` from forward; slots advance evenly around
+ * the circle.
+ *
+ * @capability formation-circle ring/cordon slot generator for group destinations
+ * @consumer squad/crowd movement — circle formation sample policy for {@link placeFormation}
+ */
+export function circleFormation(options) {
+    const radius = options.radius;
+    const startAngle = options.startAngle ?? 0;
+    return (count) => {
+        const slots = [];
+        for (let i = 0; i < count; i += 1) {
+            const angle = startAngle + (2 * Math.PI * i) / count;
+            slots.push([radius * Math.sin(angle), radius * Math.cos(angle)]);
+        }
+        return slots;
+    };
+}

package/dist/movement/glideModel.d.ts

@@ -41,4 +41,9 @@ export interface GlideModel {
     pose(): GlideStep;
     launch(position: GlideVec3, heading: number, initialSpeed?: number): void;
 }
+/**
+ * Gliding/wingsuit descent control — lift, drag, and steering from a launch.
+ *
+ * @capability glide gliding/wingsuit descent control from a launch
+ */
 export declare function createGlideModel(config?: GlideModelConfig): GlideModel;

package/dist/movement/glideModel.js

@@ -1,3 +1,8 @@
+/**
+ * Gliding/wingsuit descent control — lift, drag, and steering from a launch.
+ *
+ * @capability glide gliding/wingsuit descent control from a launch
+ */
 export function createGlideModel(config = {}) {
     const gravity = (config.gravity ?? 20) * (config.gravityScale ?? 0.25);
     const thrustAccel = config.thrustAccel ?? 10;

package/dist/movement/grappleSwing.d.ts

@@ -31,4 +31,9 @@ export interface GrappleSwing {
     /** Constrain one frame. `reeling` shortens the rope; returns the corrected position/velocity. */
     step(position: SwingVec3, velocity: SwingVec3, dt: number, reeling?: boolean): GrappleSwingStep;
 }
+/**
+ * Grappling-hook rope swing physics with anchor, pendulum motion, and reel-in.
+ *
+ * @capability grapple-swing grappling-hook rope swing physics with reel-in
+ */
 export declare function createGrappleSwing(config?: GrappleSwingConfig): GrappleSwing;

package/dist/movement/grappleSwing.js

@@ -1,3 +1,8 @@
+/**
+ * Grappling-hook rope swing physics with anchor, pendulum motion, and reel-in.
+ *
+ * @capability grapple-swing grappling-hook rope swing physics with reel-in
+ */
 export function createGrappleSwing(config = {}) {
     const reelSpeed = config.reelSpeed ?? 0;
     const minLength = config.minLength ?? 1;

package/dist/movement/leaderTrail.d.ts

@@ -26,4 +26,9 @@ export interface LeaderTrail {
     /** Drop all history (teleport, respawn) and optionally restart from a position. */
     reset(position?: TrailPoint): void;
 }
+/**
+ * A trailing follower formation that chases a leader along its past path — snake/convoy trails.
+ *
+ * @capability follow-trail trailing follower/snake formation that chases a leader
+ */
 export declare function createLeaderTrail(config: LeaderTrailConfig): LeaderTrail;

package/dist/movement/leaderTrail.js

@@ -1,3 +1,8 @@
+/**
+ * A trailing follower formation that chases a leader along its past path — snake/convoy trails.
+ *
+ * @capability follow-trail trailing follower/snake formation that chases a leader
+ */
 export function createLeaderTrail(config) {
     if (!(config.spacing > 0))
         throw new Error(`leader trail spacing must be positive, got ${config.spacing}`);

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,8 +115,9 @@ 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];
@@ -113,21 +132,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) {
@@ -188,7 +208,8 @@ 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;
@@ -228,7 +249,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 +263,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 +273,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,15 @@
 import { applyHorizontalImpulses, applyMotionImpulses } from "../runtime/motionIntents.js";
-import { groundFieldFor, hasEnvironmentTerrain } from "../world/terrain.js";
+import { groundFieldFor, hasEnvironmentTerrain, sampleSlope } from "../world/terrain.js";
 import { advancePlayerMotion, constrainStepToAxis, createEmptyMovementKeys, createPlayerMotionState, nearbyObstacles, resolveMovementIntent, resolveObstacleStep, snapPositionToGrid, } from "./movementModel.js";
-import { steerYaw } from "./steering.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 +30,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 +52,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 +65,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 +106,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 +147,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 +159,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") {
@@ -153,10 +192,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 +230,7 @@ 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,
     });
 }

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;