@jgengine/core 0.9.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,17 +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;
-/** Zeroes the off-axis component so travel is locked to a single world axis (`PlayerMovementConfig.mode: "axis"`). */
+/** 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"`).
+ * @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;
@@ -227,7 +248,24 @@ export function resolveObstacleStep(current, stepX, stepZ, obstacles, playerRadi
     }
     return { stepX: resultX, stepZ: resultZ };
 }
-/** Zeroes the off-axis component so travel is locked to a single world axis (`PlayerMovementConfig.mode: "axis"`). */
+const OBSTACLE_GATHER_RADIUS = 3;
+/** 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 = [];
+    for (const object of objects) {
+        const dx = object.position[0] - center[0];
+        const dz = object.position[2] - center[2];
+        if (dx * dx + dz * dz <= radiusSq)
+            result.push({ position: object.position });
+    }
+    return result;
+}
+/** 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 };
 }
@@ -235,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.d.ts

@@ -0,0 +1,41 @@
+import type { PhysicsConfig } from "../game/defineGame.js";
+import type { PlayerMovementConfig, VoxelCollisionConfig } from "../game/playableGame.js";
+import type { GameContext } from "../runtime/gameContext.js";
+import type { InputFrame } from "../runtime/inputSnapshot.js";
+import { type TerrainField } from "../world/terrain.js";
+import type { WorldFeature } from "../world/features.js";
+import { type MovementTuningOverrides } from "./movementModel.js";
+/** The resolved, per-world movement configuration {@link stepPlayerMovement} integrates against — the same inputs the shell FrameDriver used to read piecemeal, gathered into one struct so single-player and host movement run identical math. */
+export interface PlayerMovementTuning {
+    collision?: VoxelCollisionConfig;
+    movement?: PlayerMovementConfig;
+    physics?: MovementTuningOverrides;
+    ground: TerrainField;
+    hasTerrain: boolean;
+}
+/**
+ * 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`
+ * and expect a positive downward magnitude — so gravity is negated here to keep down-pointing gravity pulling down.
+ */
+export declare function resolvePhysicsTuning(physics: PhysicsConfig | undefined): MovementTuningOverrides | undefined;
+/** 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 declare function resolvePlayerMovementTuning(opts: {
+    collision?: VoxelCollisionConfig;
+    movement?: PlayerMovementConfig;
+    physics?: PhysicsConfig;
+    world?: WorldFeature;
+}): PlayerMovementTuning;
+/** One player's current heading (radians), integrated by {@link stepPlayerMovement} — the shell reads it back into its camera/aim yaw. */
+export declare function playerMovementHeading(ctx: GameContext, userId: string): number;
+/** Drop a player's retained movement state (heading + kinematic body) — call on leave so a rejoin starts fresh instead of resuming stale velocity. */
+export declare function forgetPlayerMovement(ctx: GameContext, userId: string): void;
+/**
+ * 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,
+ * so single-player and server-authoritative movement are identical. Reads the player's controlled entity, terrain,
+ * scene solids, and pending motion impulses; writes the entity pose via `setPose`. Retains heading + kinematic body
+ * per `userId` on the `ctx`. Pass `heading` to override the internally-integrated yaw (the shell owns yaw for its
+ * camera); omit it and the controller turns from the frame's `turnLeft`/`turnRight` actions.
+ */
+export declare function stepPlayerMovement(ctx: GameContext, userId: string, input: InputFrame, dt: number, tuning: PlayerMovementTuning, heading?: number): void;