@jgengine/core 0.1.0

package/dist/inventory/inventoryModel.js

@@ -0,0 +1,208 @@
+export function createEmptyInventory(layout) {
+    return { slots: new Array(layout.slots).fill(null) };
+}
+function violatesKind(layout, traits, itemId) {
+    if (layout.accepts === undefined || traits.kind === undefined)
+        return false;
+    const kind = traits.kind(itemId);
+    if (Array.isArray(layout.accepts))
+        return kind === null || !layout.accepts.includes(kind);
+    return kind !== layout.accepts;
+}
+function computeCapacity(state, traits, itemId) {
+    const limit = traits.stackLimit(itemId);
+    let existingRoom = 0;
+    let freeSlots = 0;
+    for (const slot of state.slots) {
+        if (slot === null)
+            freeSlots += 1;
+        else if (slot.itemId === itemId)
+            existingRoom += Math.max(0, limit - slot.count);
+    }
+    return { limit, existingRoom, freeCapacity: freeSlots * limit };
+}
+function fillSlots(slots, itemId, limit, amount) {
+    let remaining = amount;
+    for (let i = 0; i < slots.length && remaining > 0; i++) {
+        const slot = slots[i];
+        if (slot !== null && slot.itemId === itemId && slot.count < limit) {
+            const add = Math.min(limit - slot.count, remaining);
+            slots[i] = { itemId, count: slot.count + add };
+            remaining -= add;
+        }
+    }
+    for (let i = 0; i < slots.length && remaining > 0; i++) {
+        if (slots[i] === null) {
+            const add = Math.min(limit, remaining);
+            slots[i] = { itemId, count: add };
+            remaining -= add;
+        }
+    }
+    return remaining;
+}
+function autoPut(state, layout, traits, itemId, count) {
+    if (violatesKind(layout, traits, itemId))
+        return { status: "rejected", reason: "wrong-kind" };
+    if (count <= 0)
+        return { status: "ok", state };
+    const { limit, existingRoom, freeCapacity } = computeCapacity(state, traits, itemId);
+    if (existingRoom + freeCapacity < count)
+        return { status: "rejected", reason: "no-space" };
+    const slots = state.slots.slice();
+    fillSlots(slots, itemId, limit, count);
+    return { status: "ok", state: { slots } };
+}
+function explicitPut(state, layout, traits, itemId, count, slot) {
+    if (slot < 0 || slot >= state.slots.length)
+        return { status: "rejected", reason: "invalid-slot" };
+    if (violatesKind(layout, traits, itemId))
+        return { status: "rejected", reason: "wrong-kind" };
+    if (count <= 0)
+        return { status: "ok", state };
+    const limit = traits.stackLimit(itemId);
+    const existing = state.slots[slot];
+    const slots = state.slots.slice();
+    if (existing === null) {
+        if (count > limit)
+            return { status: "rejected", reason: "no-space" };
+        slots[slot] = { itemId, count };
+        return { status: "ok", state: { slots } };
+    }
+    if (existing.itemId !== itemId)
+        return { status: "rejected", reason: "slot-occupied" };
+    const newCount = existing.count + count;
+    if (newCount > limit)
+        return { status: "rejected", reason: "no-space" };
+    slots[slot] = { itemId, count: newCount };
+    return { status: "ok", state: { slots } };
+}
+export function putItem(state, layout, traits, itemId, count, options) {
+    if (options?.slot !== undefined)
+        return explicitPut(state, layout, traits, itemId, count, options.slot);
+    return autoPut(state, layout, traits, itemId, count);
+}
+export function takeItem(state, itemId, count) {
+    if (count <= 0)
+        return { status: "ok", state };
+    if (countItem(state, itemId) < count)
+        return { status: "rejected", reason: "insufficient" };
+    const slots = state.slots.slice();
+    let remaining = count;
+    for (let i = slots.length - 1; i >= 0 && remaining > 0; i--) {
+        const slot = slots[i];
+        if (slot !== null && slot.itemId === itemId) {
+            const removed = Math.min(slot.count, remaining);
+            const newCount = slot.count - removed;
+            slots[i] = newCount > 0 ? { itemId, count: newCount } : null;
+            remaining -= removed;
+        }
+    }
+    return { status: "ok", state: { slots } };
+}
+export function countItem(state, itemId) {
+    let total = 0;
+    for (const slot of state.slots)
+        if (slot !== null && slot.itemId === itemId)
+            total += slot.count;
+    return total;
+}
+export function hasItem(state, itemId, count) {
+    return countItem(state, itemId) >= count;
+}
+export function moveItem(from, fromSlot, to, toLayout, traits, toSlot) {
+    if (fromSlot < 0 || fromSlot >= from.slots.length)
+        return { status: "rejected", reason: "invalid-slot" };
+    const source = from.slots[fromSlot];
+    if (source === null)
+        return { status: "rejected", reason: "empty-slot" };
+    if (violatesKind(toLayout, traits, source.itemId))
+        return { status: "rejected", reason: "wrong-kind" };
+    const sameInventory = from === to;
+    if (sameInventory && toSlot === undefined) {
+        return { status: "ok", from, to };
+    }
+    if (sameInventory && toSlot === fromSlot) {
+        return { status: "ok", from, to };
+    }
+    const fromSlots = from.slots.slice();
+    const toSlots = sameInventory ? fromSlots : to.slots.slice();
+    const limit = traits.stackLimit(source.itemId);
+    if (toSlot !== undefined) {
+        if (toSlot < 0 || toSlot >= toSlots.length)
+            return { status: "rejected", reason: "invalid-slot" };
+        const dest = toSlots[toSlot];
+        if (dest === null) {
+            toSlots[toSlot] = { itemId: source.itemId, count: source.count };
+            fromSlots[fromSlot] = null;
+        }
+        else if (dest.itemId === source.itemId) {
+            const merged = dest.count + source.count;
+            const placed = Math.min(merged, limit);
+            const remainder = merged - placed;
+            toSlots[toSlot] = { itemId: source.itemId, count: placed };
+            fromSlots[fromSlot] = remainder > 0 ? { itemId: source.itemId, count: remainder } : null;
+        }
+        else {
+            toSlots[toSlot] = source;
+            fromSlots[fromSlot] = dest;
+        }
+    }
+    else {
+        const { existingRoom, freeCapacity } = computeCapacity({ slots: toSlots }, traits, source.itemId);
+        if (existingRoom + freeCapacity < source.count)
+            return { status: "rejected", reason: "no-space" };
+        fillSlots(toSlots, source.itemId, limit, source.count);
+        fromSlots[fromSlot] = null;
+    }
+    return {
+        status: "ok",
+        from: { slots: fromSlots },
+        to: sameInventory ? { slots: fromSlots } : { slots: toSlots },
+    };
+}
+export function createInventorySet(layouts, traits) {
+    const states = new Map();
+    for (const id of Object.keys(layouts)) {
+        states.set(id, createEmptyInventory(layouts[id]));
+    }
+    function requireState(id) {
+        const current = states.get(id);
+        if (current === undefined)
+            throw new Error(`unknown inventory id: ${id}`);
+        return current;
+    }
+    return {
+        put(id, itemId, count, options) {
+            const result = putItem(requireState(id), layouts[id], traits, itemId, count, options);
+            if (result.status === "ok")
+                states.set(id, result.state);
+            return result;
+        },
+        take(id, itemId, count) {
+            const result = takeItem(requireState(id), itemId, count);
+            if (result.status === "ok")
+                states.set(id, result.state);
+            return result;
+        },
+        move(fromId, fromSlot, toId, toSlot) {
+            const result = moveItem(requireState(fromId), fromSlot, requireState(toId), layouts[toId], traits, toSlot);
+            if (result.status === "ok") {
+                states.set(fromId, result.from);
+                states.set(toId, result.to);
+            }
+            return result;
+        },
+        count(id, itemId) {
+            return countItem(requireState(id), itemId);
+        },
+        has(id, itemId, count) {
+            return hasItem(requireState(id), itemId, count);
+        },
+        state(id) {
+            return requireState(id);
+        },
+        replaceState(id, state) {
+            states.set(id, state);
+        },
+    };
+}

package/dist/item/use.d.ts

@@ -0,0 +1,25 @@
+import type { Aim } from "../scene/spatial.js";
+export interface ItemUseInput {
+    from: string;
+    itemId: string;
+    inventoryId?: string;
+    aim?: Aim;
+}
+export interface ItemUseRejection {
+    reason: string;
+}
+export interface ItemUseResult<TState> {
+    state: TState;
+    error?: string;
+}
+export interface ItemUseHandler<TState> {
+    can?(state: TState, input: ItemUseInput): ItemUseRejection | null;
+    apply(state: TState, input: ItemUseInput): ItemUseResult<TState>;
+}
+export interface ItemUse<TState> {
+    register(handlers: Record<string, ItemUseHandler<TState>>): void;
+    registered(): string[];
+    can(state: TState, input: ItemUseInput): ItemUseRejection | null;
+    use(state: TState, input: ItemUseInput): ItemUseResult<TState>;
+}
+export declare function createItemUse<TState>(resolveUse: (itemId: string) => string | null | undefined): ItemUse<TState>;

package/dist/item/use.js

@@ -0,0 +1,40 @@
+export function createItemUse(resolveUse) {
+    const handlers = new Map();
+    function resolveHandler(itemId) {
+        const useName = resolveUse(itemId);
+        if (!useName)
+            return { rejection: { reason: "not-usable" } };
+        const handler = handlers.get(useName);
+        if (!handler)
+            return { rejection: { reason: "unknown-handler" } };
+        return { handler };
+    }
+    return {
+        register(newHandlers) {
+            for (const [name, handler] of Object.entries(newHandlers)) {
+                if (handlers.has(name)) {
+                    throw new Error(`Item use handler "${name}" is already registered.`);
+                }
+                handlers.set(name, handler);
+            }
+        },
+        registered() {
+            return Array.from(handlers.keys());
+        },
+        can(state, input) {
+            const resolved = resolveHandler(input.itemId);
+            if ("rejection" in resolved)
+                return resolved.rejection;
+            return resolved.handler.can?.(state, input) ?? null;
+        },
+        use(state, input) {
+            const resolved = resolveHandler(input.itemId);
+            if ("rejection" in resolved)
+                return { state, error: resolved.rejection.reason };
+            const rejection = resolved.handler.can?.(state, input);
+            if (rejection)
+                return { state, error: rejection.reason };
+            return resolved.handler.apply(state, input);
+        },
+    };
+}

package/dist/item/weapon.d.ts

@@ -0,0 +1,8 @@
+export interface WeaponEntry {
+    weapon?: Record<string, unknown>;
+}
+export declare function getWeaponStat(entry: WeaponEntry | null | undefined, stat: string): number | null;
+export interface WeaponStats {
+    getStat(itemId: string, stat: string): number | null;
+}
+export declare function createWeaponStats(resolveEntry: (itemId: string) => WeaponEntry | null | undefined): WeaponStats;

package/dist/item/weapon.js

@@ -0,0 +1,18 @@
+export function getWeaponStat(entry, stat) {
+    if (!entry?.weapon)
+        return null;
+    let value = entry.weapon;
+    for (const key of stat.split(".")) {
+        if (typeof value !== "object" || value === null)
+            return null;
+        value = value[key];
+    }
+    return typeof value === "number" ? value : null;
+}
+export function createWeaponStats(resolveEntry) {
+    return {
+        getStat(itemId, stat) {
+            return getWeaponStat(resolveEntry(itemId), stat);
+        },
+    };
+}

package/dist/movement/avatarGait.d.ts

@@ -0,0 +1,14 @@
+export interface GaitTuning {
+    /** Stride cycles per world unit travelled — ties step cadence to actual speed. */
+    stridesPerUnit: number;
+    bobAmplitude: number;
+    swayAmplitude: number;
+    /** Speed at which bob/sway reach full intensity. */
+    fullIntensitySpeed: number;
+}
+export declare const DEFAULT_GAIT_TUNING: GaitTuning;
+export declare function advanceGaitPhase(phase: number, speedUnitsPerSec: number, dtSec: number, tuning?: GaitTuning): number;
+/** Vertical hop per footfall — two peaks per stride cycle. */
+export declare function gaitBobOffset(phase: number, speedUnitsPerSec: number, tuning?: GaitTuning): number;
+/** Signed side-to-side lean alternating with each footfall. */
+export declare function gaitSwayAngle(phase: number, speedUnitsPerSec: number, tuning?: GaitTuning): number;

package/dist/movement/avatarGait.js

@@ -0,0 +1,20 @@
+export const DEFAULT_GAIT_TUNING = {
+    stridesPerUnit: 0.95,
+    bobAmplitude: 0.05,
+    swayAmplitude: 0.035,
+    fullIntensitySpeed: 4.5,
+};
+export function advanceGaitPhase(phase, speedUnitsPerSec, dtSec, tuning = DEFAULT_GAIT_TUNING) {
+    return phase + speedUnitsPerSec * dtSec * tuning.stridesPerUnit * Math.PI * 2;
+}
+function gaitIntensity(speedUnitsPerSec, tuning) {
+    return Math.min(1, Math.max(0, speedUnitsPerSec / tuning.fullIntensitySpeed));
+}
+/** Vertical hop per footfall — two peaks per stride cycle. */
+export function gaitBobOffset(phase, speedUnitsPerSec, tuning = DEFAULT_GAIT_TUNING) {
+    return Math.abs(Math.sin(phase)) * tuning.bobAmplitude * gaitIntensity(speedUnitsPerSec, tuning);
+}
+/** Signed side-to-side lean alternating with each footfall. */
+export function gaitSwayAngle(phase, speedUnitsPerSec, tuning = DEFAULT_GAIT_TUNING) {
+    return Math.sin(phase) * tuning.swayAmplitude * gaitIntensity(speedUnitsPerSec, tuning);
+}

package/dist/movement/cameraRig.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Camera-rig feel math: the pure per-frame computations behind the first-person
+ * camera (eye-height crouch blending, head bob, tracking smoothing, pitch
+ * clamping). Kept alongside movementModel.ts so a renderer-side controller can
+ * apply the results to its own three.js camera/vectors without owning the math.
+ */
+export declare const CAMERA_PITCH_LIMIT = 1.45;
+export declare function clampCameraPitch(pitch: number): number;
+export declare function resolveTargetEyeHeight(crouching: boolean, grounded: boolean): number;
+export declare function advanceEyeHeight(currentEyeHeight: number, targetEyeHeight: number, deltaSeconds: number): number;
+export declare function resolveHeadBobRate(crouching: boolean, running: boolean): number;
+export declare function resolveHeadBobAmplitude(crouching: boolean, running: boolean, grounded: boolean): number;
+export declare function advanceHeadBobTime(currentHeadBobTime: number, moving: boolean, grounded: boolean, bobRate: number, deltaSeconds: number): number;
+export declare function resolveHeadBobOffset(headBobTime: number, bobAmplitude: number): number;
+export declare function resolveCameraTrackingBlend(deltaSeconds: number): number;

package/dist/movement/cameraRig.js

@@ -0,0 +1,43 @@
+/**
+ * Camera-rig feel math: the pure per-frame computations behind the first-person
+ * camera (eye-height crouch blending, head bob, tracking smoothing, pitch
+ * clamping). Kept alongside movementModel.ts so a renderer-side controller can
+ * apply the results to its own three.js camera/vectors without owning the math.
+ */
+import { MOVEMENT_TUNING } from "./movementModel.js";
+export const CAMERA_PITCH_LIMIT = 1.45;
+export function clampCameraPitch(pitch) {
+    return Math.max(-CAMERA_PITCH_LIMIT, Math.min(CAMERA_PITCH_LIMIT, pitch));
+}
+export function resolveTargetEyeHeight(crouching, grounded) {
+    return crouching && grounded ? MOVEMENT_TUNING.crouchEyeHeight : MOVEMENT_TUNING.standEyeHeight;
+}
+export function advanceEyeHeight(currentEyeHeight, targetEyeHeight, deltaSeconds) {
+    const blend = 1 - Math.exp(-MOVEMENT_TUNING.crouchTransitionSpeed * deltaSeconds);
+    return currentEyeHeight + (targetEyeHeight - currentEyeHeight) * blend;
+}
+export function resolveHeadBobRate(crouching, running) {
+    return crouching
+        ? MOVEMENT_TUNING.crouchBobRate
+        : running
+            ? MOVEMENT_TUNING.runBobRate
+            : MOVEMENT_TUNING.walkBobRate;
+}
+export function resolveHeadBobAmplitude(crouching, running, grounded) {
+    if (!grounded)
+        return 0;
+    return crouching
+        ? MOVEMENT_TUNING.crouchBobAmplitude
+        : running
+            ? MOVEMENT_TUNING.runBobAmplitude
+            : MOVEMENT_TUNING.walkBobAmplitude;
+}
+export function advanceHeadBobTime(currentHeadBobTime, moving, grounded, bobRate, deltaSeconds) {
+    return moving && grounded ? currentHeadBobTime + deltaSeconds * bobRate : 0;
+}
+export function resolveHeadBobOffset(headBobTime, bobAmplitude) {
+    return Math.sin(headBobTime * Math.PI * 2) * bobAmplitude;
+}
+export function resolveCameraTrackingBlend(deltaSeconds) {
+    return 1 - Math.exp(-MOVEMENT_TUNING.cameraTrackingSpeed * deltaSeconds);
+}

package/dist/movement/movementModel.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Movement core (pure model).
+ *
+ * This module owns the raw key model, the pure translation from held keys
+ * into a frame-independent {@link MovementIntent}, and the kinematics
+ * integration. Keeping it framework-free means the kinematics controller,
+ * the keyboard handler and the on-screen touch D-pad all speak the same
+ * vocabulary, and the translation is unit testable without a renderer.
+ * DOM capture, pointer lock, and the per-frame look channel live in
+ * movementInput.ts.
+ */
+export type MovementKey = "w" | "a" | "s" | "d" | "shift" | "control" | "c" | "space";
+export type MovementKeysState = Record<MovementKey, boolean>;
+export declare function createEmptyMovementKeys(): MovementKeysState;
+/**
+ * Frame-independent description of what the player is asking the avatar to do.
+ * `forward`/`right` are in the range -1..1 in the avatar's local frame; the
+ * controller rotates them into world space against the camera each frame.
+ */
+export interface MovementIntent {
+    forward: number;
+    right: number;
+    crouching: boolean;
+    running: boolean;
+    jumping: boolean;
+    /** True when there is any directional input this frame. */
+    moving: boolean;
+}
+/**
+ * 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.
+ */
+export declare function resolveMovementIntent(keys: MovementKeysState, canMove: boolean): MovementIntent;
+/**
+ * Kinematics + feel tuning for the first-person controller. Centralised here so
+ * movement feel lives in one place rather than scattered through the renderer.
+ */
+export declare const MOVEMENT_TUNING: {
+    readonly standEyeHeight: 1.7;
+    readonly crouchEyeHeight: 1.15;
+    readonly walkSpeedMultiplier: 1.75;
+    readonly runSpeedMultiplier: 2.25;
+    readonly crouchSpeedMultiplier: 0.45;
+    readonly groundAcceleration: 26;
+    readonly airAcceleration: 12;
+    readonly groundFriction: 18;
+    readonly jumpVelocity: 7.1;
+    readonly gravityAcceleration: 24;
+    readonly cameraTrackingSpeed: 24;
+    readonly crouchTransitionSpeed: 14;
+    readonly crouchBobRate: 0.5;
+    readonly walkBobRate: 1.5;
+    readonly runBobRate: 2.5;
+    readonly crouchBobAmplitude: 0.02;
+    readonly walkBobAmplitude: 0.045;
+    readonly runBobAmplitude: 0.06;
+    /** Below this horizontal speed the avatar is treated as standing still. */
+    readonly movingSpeedThreshold: 0.2;
+    /** Largest physics step we integrate so a stalled tab can't teleport the player. */
+    readonly maxFrameSeconds: 0.05;
+};
+/**
+ * Mutable kinematic state carried between frames by the controller. Kept here so
+ * the velocity / jump / gravity integration is a pure function testable without
+ * a renderer — the controller just owns the ref.
+ */
+export interface PlayerMotionState {
+    horizontalVelocityX: number;
+    horizontalVelocityZ: number;
+    verticalVelocity: number;
+    jumpOffset: number;
+    grounded: boolean;
+    jumpHeld: boolean;
+}
+export declare function createPlayerMotionState(): PlayerMotionState;
+/** Horizontal step (world units) the avatar should commit this frame. */
+export interface MovementFrameStep {
+    stepX: number;
+    stepZ: number;
+}
+/**
+ * Advance one frame of avatar kinematics. Mutates `motion` (velocity, jump,
+ * gravity, grounded) and returns the horizontal step to commit through the
+ * collision-resolving stepper.
+ *
+ * `forwardX`/`forwardZ` are the camera heading projected onto the ground plane
+ * (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): MovementFrameStep;
+/** 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. */
+export declare function cameraYawToAvatarBodyYaw(cameraYaw: number): number;

package/dist/movement/movementModel.js

@@ -0,0 +1,171 @@
+/**
+ * Movement core (pure model).
+ *
+ * This module owns the raw key model, the pure translation from held keys
+ * into a frame-independent {@link MovementIntent}, and the kinematics
+ * integration. Keeping it framework-free means the kinematics controller,
+ * the keyboard handler and the on-screen touch D-pad all speak the same
+ * vocabulary, and the translation is unit testable without a renderer.
+ * DOM capture, pointer lock, and the per-frame look channel live in
+ * movementInput.ts.
+ */
+export function createEmptyMovementKeys() {
+    return { w: false, a: false, s: false, d: false, shift: false, control: false, c: false, space: false };
+}
+const IDLE_INTENT = {
+    forward: 0,
+    right: 0,
+    crouching: false,
+    running: false,
+    jumping: false,
+    moving: false,
+};
+/**
+ * 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.
+ */
+export function resolveMovementIntent(keys, canMove) {
+    if (!canMove)
+        return IDLE_INTENT;
+    const forward = (keys.w ? 1 : 0) - (keys.s ? 1 : 0);
+    const right = (keys.d ? 1 : 0) - (keys.a ? 1 : 0);
+    const crouching = keys.control || keys.c;
+    const running = keys.shift && !crouching;
+    return {
+        forward,
+        right,
+        crouching,
+        running,
+        jumping: keys.space,
+        moving: forward !== 0 || right !== 0,
+    };
+}
+/**
+ * Kinematics + feel tuning for the first-person controller. Centralised here so
+ * movement feel lives in one place rather than scattered through the renderer.
+ */
+export const MOVEMENT_TUNING = {
+    standEyeHeight: 1.7,
+    crouchEyeHeight: 1.15,
+    walkSpeedMultiplier: 1.75,
+    runSpeedMultiplier: 2.25,
+    crouchSpeedMultiplier: 0.45,
+    groundAcceleration: 26,
+    airAcceleration: 12,
+    groundFriction: 18,
+    jumpVelocity: 7.1,
+    gravityAcceleration: 24,
+    cameraTrackingSpeed: 24,
+    crouchTransitionSpeed: 14,
+    crouchBobRate: 0.5,
+    walkBobRate: 1.5,
+    runBobRate: 2.5,
+    crouchBobAmplitude: 0.02,
+    walkBobAmplitude: 0.045,
+    runBobAmplitude: 0.06,
+    /** Below this horizontal speed the avatar is treated as standing still. */
+    movingSpeedThreshold: 0.2,
+    /** 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) {
+    const speedMultiplier = intent.crouching
+        ? MOVEMENT_TUNING.crouchSpeedMultiplier
+        : intent.running
+            ? MOVEMENT_TUNING.runSpeedMultiplier
+            : 1;
+    return baseSpeed * MOVEMENT_TUNING.walkSpeedMultiplier * speedMultiplier;
+}
+export function createPlayerMotionState() {
+    return {
+        horizontalVelocityX: 0,
+        horizontalVelocityZ: 0,
+        verticalVelocity: 0,
+        jumpOffset: 0,
+        grounded: true,
+        jumpHeld: false,
+    };
+}
+/**
+ * Advance one frame of avatar kinematics. Mutates `motion` (velocity, jump,
+ * gravity, grounded) and returns the horizontal step to commit through the
+ * collision-resolving stepper.
+ *
+ * `forwardX`/`forwardZ` are the camera heading projected onto the ground plane
+ * (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) {
+    const deltaSeconds = Math.min(rawDeltaSeconds, MOVEMENT_TUNING.maxFrameSeconds);
+    const targetSpeed = resolveTargetSpeed(intent, baseSpeed);
+    let targetVelocityX = 0;
+    let targetVelocityZ = 0;
+    if (intent.moving) {
+        // Project the camera heading onto the ground and fall back to -Z if the
+        // player is looking straight up/down so "forward" is always well defined.
+        let fx = forwardX;
+        let fz = forwardZ;
+        const forwardLengthSq = fx * fx + fz * fz;
+        if (forwardLengthSq < 1e-6) {
+            fx = 0;
+            fz = -1;
+        }
+        else {
+            const inv = 1 / Math.sqrt(forwardLengthSq);
+            fx *= inv;
+            fz *= inv;
+        }
+        // right = forward × up, with up = (0, 1, 0) → (-fz, 0, fx); unit when forward is.
+        const rightX = -fz;
+        const rightZ = fx;
+        targetVelocityX = fx * intent.forward + rightX * intent.right;
+        targetVelocityZ = fz * intent.forward + rightZ * intent.right;
+        const lengthSq = targetVelocityX * targetVelocityX + targetVelocityZ * targetVelocityZ;
+        if (lengthSq > 1e-6) {
+            const scale = targetSpeed / Math.sqrt(lengthSq);
+            targetVelocityX *= scale;
+            targetVelocityZ *= scale;
+        }
+        else {
+            targetVelocityX = 0;
+            targetVelocityZ = 0;
+        }
+    }
+    const acceleration = motion.grounded ? MOVEMENT_TUNING.groundAcceleration : MOVEMENT_TUNING.airAcceleration;
+    const accelerationBlend = 1 - Math.exp(-acceleration * deltaSeconds);
+    motion.horizontalVelocityX += (targetVelocityX - motion.horizontalVelocityX) * accelerationBlend;
+    motion.horizontalVelocityZ += (targetVelocityZ - motion.horizontalVelocityZ) * accelerationBlend;
+    if (!intent.moving && motion.grounded) {
+        const friction = Math.exp(-MOVEMENT_TUNING.groundFriction * deltaSeconds);
+        motion.horizontalVelocityX *= friction;
+        motion.horizontalVelocityZ *= friction;
+    }
+    const jumpPressed = intent.jumping;
+    if (jumpPressed && !motion.jumpHeld && motion.grounded && !intent.crouching) {
+        motion.verticalVelocity = MOVEMENT_TUNING.jumpVelocity;
+        motion.grounded = false;
+    }
+    motion.jumpHeld = jumpPressed;
+    if (!motion.grounded || motion.verticalVelocity > 0) {
+        motion.verticalVelocity -= MOVEMENT_TUNING.gravityAcceleration * deltaSeconds;
+        motion.jumpOffset += motion.verticalVelocity * deltaSeconds;
+        if (motion.jumpOffset <= 0) {
+            motion.jumpOffset = 0;
+            motion.verticalVelocity = 0;
+            motion.grounded = true;
+        }
+    }
+    return {
+        stepX: motion.horizontalVelocityX * deltaSeconds,
+        stepZ: motion.horizontalVelocityZ * deltaSeconds,
+    };
+}
+/** 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. */
+export function cameraYawToAvatarBodyYaw(cameraYaw) {
+    return cameraYaw + Math.PI;
+}