@jgengine/core 0.18.0 → 0.19.0

package/dist/runtime/inputSnapshot.js

@@ -1,10 +1,12 @@
 import { sampleAxisBindings } from "../input/axisInput.js";
+import { createHapticChannels } from "../input/haptics.js";
 export function createInputSnapshot() {
     let heldSet = new Set();
     let previousHeldSet = new Set();
     let heldList = [];
     let pointerState = null;
     let analogValues = null;
+    const haptics = new Map();
     const value = (action) => {
         const analog = analogValues?.[action];
         if (analog !== undefined)
@@ -12,6 +14,15 @@ export function createInputSnapshot() {
         return heldSet.has(action) ? 1 : 0;
     };
     return {
+        rumble: async () => false,
+        haptics(userId) {
+            let channels = haptics.get(userId);
+            if (channels === undefined) {
+                channels = createHapticChannels();
+                haptics.set(userId, channels);
+            }
+            return channels;
+        },
         publish(held) {
             previousHeldSet = heldSet;
             heldList = Object.freeze([...held]);

package/dist/runtime/localPlayers.d.ts

@@ -0,0 +1,73 @@
+import type { GameContext } from "./gameContext.js";
+import { type InputSnapshot } from "./inputSnapshot.js";
+/** One local seat on a shared screen: a stable slot id, the user id the game spawns for it, and the device driving it. */
+export interface LocalPlayerSlot {
+    readonly slotId: string;
+    readonly index: number;
+    readonly userId: string;
+    /** Device that claimed the seat (`"gamepad:1"`), `null` for the primary seat before a device claims it. */
+    readonly deviceId: string | null;
+}
+/** Retunable seat policy. */
+export interface LocalPlayersConfig {
+    /** Seats on this screen, including the primary (default `1`: every device drives the primary player). */
+    maxSlots: number;
+    /**
+     * Whether the first device to press something claims the primary seat alongside keyboard and touch
+     * (`"first"`, default), or the primary stays keyboard/touch-only and every pad opens a new seat (`"none"`).
+     */
+    claimPrimary?: "first" | "none";
+}
+/** Options for {@link createLocalPlayers}. */
+export interface LocalPlayersOptions extends LocalPlayersConfig {
+    /** User id of seat 0 — `ctx.player.userId`. */
+    primaryUserId: string;
+    /** Input of seat 0 — `ctx.input`; other seats get their own snapshot. */
+    primaryInput?: InputSnapshot;
+    /** User id for seat `index >= 1` (default `` `${primaryUserId}:p${index + 1}` ``). */
+    userIdFor?: (index: number) => string;
+}
+/** Result of {@link LocalPlayers.assign}. */
+export interface LocalPlayerAssignment {
+    slot: LocalPlayerSlot;
+    /** True when this call opened the seat: spawn its entity through `onNewPlayer`. */
+    joined: boolean;
+}
+/** Serializable seat table. */
+export interface LocalPlayersSnapshot {
+    maxSlots: number;
+    claimPrimary: "first" | "none";
+    slots: LocalPlayerSlot[];
+}
+/** Seats for couch co-op: devices hot-join into slots, each slot has its own input. */
+export interface LocalPlayers {
+    /** Seat for a device that just produced input: its existing seat, the primary seat, a newly opened seat, or `null` when full. */
+    assign(deviceId: string): LocalPlayerAssignment | null;
+    /** Free a seat other than the primary; its device may hot-join again. */
+    release(slotId: string): boolean;
+    slots(): readonly LocalPlayerSlot[];
+    slot(slotId: string): LocalPlayerSlot | null;
+    slotForDevice(deviceId: string): LocalPlayerSlot | null;
+    /** The seat's user id and input, or `null` for an unknown seat. Seat 0 returns `ctx.player`'s id and `ctx.input`. */
+    local(slotId: string): {
+        userId: string;
+        input: InputSnapshot;
+    } | null;
+    /** Called after every assign that changes the table, release, restore and retune; returns an unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    config(): Required<LocalPlayersConfig>;
+    /** Change seat count or claim policy mid-game; seats above a lowered `maxSlots` stay until released. */
+    retune(next: LocalPlayersConfig): void;
+    snapshot(): LocalPlayersSnapshot;
+    restore(snapshot: LocalPlayersSnapshot): void;
+}
+/**
+ * Seat table for local multiplayer on one screen.
+ * @capability local-players Couch co-op seats: devices hot-join into slots, each with its own user id and input snapshot.
+ */
+export declare function createLocalPlayers(options: LocalPlayersOptions): LocalPlayers;
+/**
+ * The seat table of a game context, created on first use with one seat for `ctx.player` and `ctx.input`.
+ * The shell retunes it from `defineGame({ localPlayers })` and hot-joins pads into it.
+ */
+export declare function localPlayers(ctx: GameContext): LocalPlayers;

package/dist/runtime/localPlayers.js

@@ -0,0 +1,119 @@
+import { createInputSnapshot } from "./inputSnapshot.js";
+const PRIMARY_SLOT = "slot:0";
+/**
+ * Seat table for local multiplayer on one screen.
+ * @capability local-players Couch co-op seats: devices hot-join into slots, each with its own user id and input snapshot.
+ */
+export function createLocalPlayers(options) {
+    const userIdFor = options.userIdFor ?? ((index) => `${options.primaryUserId}:p${index + 1}`);
+    const primaryInput = options.primaryInput ?? createInputSnapshot();
+    let config = {
+        maxSlots: Math.max(1, Math.floor(options.maxSlots)),
+        claimPrimary: options.claimPrimary ?? "first",
+    };
+    let slots = [];
+    const inputs = new Map();
+    const listeners = new Set();
+    const changed = () => {
+        for (const listener of [...listeners])
+            listener();
+    };
+    const primarySlot = (deviceId) => Object.freeze({ slotId: PRIMARY_SLOT, index: 0, userId: options.primaryUserId, deviceId });
+    const reset = (next) => {
+        slots = next.map((slot) => Object.freeze({ ...slot }));
+        if (!slots.some((slot) => slot.index === 0))
+            slots.unshift(primarySlot(null));
+        slots.sort((a, b) => a.index - b.index);
+        for (const slotId of [...inputs.keys()]) {
+            if (!slots.some((slot) => slot.slotId === slotId))
+                inputs.delete(slotId);
+        }
+    };
+    reset([]);
+    const inputFor = (slot) => {
+        if (slot.index === 0)
+            return primaryInput;
+        let input = inputs.get(slot.slotId);
+        if (input === undefined) {
+            input = createInputSnapshot();
+            inputs.set(slot.slotId, input);
+        }
+        return input;
+    };
+    return {
+        assign(deviceId) {
+            const existing = slots.find((slot) => slot.deviceId === deviceId);
+            if (existing !== undefined)
+                return { slot: existing, joined: false };
+            if (config.claimPrimary === "first" || config.maxSlots === 1) {
+                const primary = slots[0];
+                if (primary.deviceId === null) {
+                    slots[0] = primarySlot(deviceId);
+                    changed();
+                    return { slot: slots[0], joined: false };
+                }
+                if (config.maxSlots === 1)
+                    return { slot: primary, joined: false };
+            }
+            if (slots.length >= config.maxSlots)
+                return null;
+            let index = 1;
+            while (slots.some((slot) => slot.index === index))
+                index += 1;
+            const slot = Object.freeze({ slotId: `slot:${index}`, index, userId: userIdFor(index), deviceId });
+            slots = [...slots, slot].sort((a, b) => a.index - b.index);
+            changed();
+            return { slot, joined: true };
+        },
+        release(slotId) {
+            if (slotId === PRIMARY_SLOT)
+                return false;
+            const next = slots.filter((slot) => slot.slotId !== slotId);
+            if (next.length === slots.length)
+                return false;
+            slots = next;
+            inputs.delete(slotId);
+            changed();
+            return true;
+        },
+        slots: () => slots,
+        slot: (slotId) => slots.find((slot) => slot.slotId === slotId) ?? null,
+        slotForDevice: (deviceId) => slots.find((slot) => slot.deviceId === deviceId) ?? null,
+        local(slotId) {
+            const slot = slots.find((candidate) => candidate.slotId === slotId);
+            return slot === undefined ? null : { userId: slot.userId, input: inputFor(slot) };
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        config: () => config,
+        retune(next) {
+            config = { maxSlots: Math.max(1, Math.floor(next.maxSlots)), claimPrimary: next.claimPrimary ?? config.claimPrimary };
+            changed();
+        },
+        snapshot() {
+            return { ...config, slots: slots.map((slot) => ({ ...slot })) };
+        },
+        restore(snapshot) {
+            config = { maxSlots: Math.max(1, Math.floor(snapshot.maxSlots)), claimPrimary: snapshot.claimPrimary };
+            reset(snapshot.slots);
+            changed();
+        },
+    };
+}
+const LOCAL_PLAYERS = new WeakMap();
+/**
+ * The seat table of a game context, created on first use with one seat for `ctx.player` and `ctx.input`.
+ * The shell retunes it from `defineGame({ localPlayers })` and hot-joins pads into it.
+ */
+export function localPlayers(ctx) {
+    let players = LOCAL_PLAYERS.get(ctx);
+    if (players === undefined) {
+        players = createLocalPlayers({ maxSlots: 1, primaryUserId: ctx.player.userId, primaryInput: ctx.input });
+        LOCAL_PLAYERS.set(ctx, players);
+    }
+    return players;
+}

package/dist/runtime/poseInterpolation.d.ts

@@ -0,0 +1,36 @@
+import type { EntityStore } from "../scene/entityStore.js";
+/** A render pose sampled between two simulation steps: `[x, y, z, rotationY]`. */
+export type RenderPose = [x: number, y: number, z: number, rotationY: number];
+/** Serializable previous-step poses keyed by entity id. */
+export interface PoseHistoryState {
+    previous: Record<string, RenderPose>;
+}
+/** Previous-step pose buffer: capture at each fixed step, sample between steps for rendering. */
+export interface PoseHistory {
+    /** Capture every entity's current pose as the "previous" step. Call once at the start of each fixed step. */
+    beginStep(entities: EntityStore): void;
+    /**
+     * Write the pose `alpha` of the way from the previous step to the live pose into `out`. Returns `false` (and
+     * leaves `out` untouched) when the entity is unknown; an entity with no history or one that jumped farther
+     * than `snapDistance` gets its live pose.
+     */
+    sample(entities: EntityStore, id: string, alpha: number, out: RenderPose): boolean;
+    /** Forget an entity's previous pose so its next frame renders live (respawn, teleport). */
+    snap(id: string): void;
+    retune(options: {
+        snapDistance?: number;
+    }): void;
+    snapshot(): PoseHistoryState;
+    restore(state: PoseHistoryState): void;
+}
+/** Shortest-arc interpolation between two yaw angles. */
+export declare function lerpAngle(from: number, to: number, t: number): number;
+/**
+ * Previous-step pose buffer for render interpolation under a fixed-step loop. Reuses one 4-slot array per
+ * entity so a step over N entities allocates only for entities seen for the first time.
+ *
+ * @capability pose-interpolation render entity poses between fixed simulation steps without stutter
+ */
+export declare function createPoseHistory(options?: {
+    snapDistance?: number;
+}): PoseHistory;

package/dist/runtime/poseInterpolation.js

@@ -0,0 +1,91 @@
+const TWO_PI = Math.PI * 2;
+/** Shortest-arc interpolation between two yaw angles. */
+export function lerpAngle(from, to, t) {
+    let delta = (to - from) % TWO_PI;
+    if (delta > Math.PI)
+        delta -= TWO_PI;
+    else if (delta < -Math.PI)
+        delta += TWO_PI;
+    return from + delta * t;
+}
+/**
+ * Previous-step pose buffer for render interpolation under a fixed-step loop. Reuses one 4-slot array per
+ * entity so a step over N entities allocates only for entities seen for the first time.
+ *
+ * @capability pose-interpolation render entity poses between fixed simulation steps without stutter
+ */
+export function createPoseHistory(options) {
+    let snapDistance = options?.snapDistance ?? 8;
+    const previous = new Map();
+    const seen = new Set();
+    return {
+        beginStep(entities) {
+            seen.clear();
+            for (const entity of entities.list()) {
+                seen.add(entity.id);
+                let slot = previous.get(entity.id);
+                if (slot === undefined) {
+                    slot = [0, 0, 0, 0];
+                    previous.set(entity.id, slot);
+                }
+                slot[0] = entity.position[0];
+                slot[1] = entity.position[1];
+                slot[2] = entity.position[2];
+                slot[3] = entity.rotationY;
+            }
+            if (previous.size !== seen.size) {
+                for (const id of previous.keys()) {
+                    if (!seen.has(id))
+                        previous.delete(id);
+                }
+            }
+        },
+        sample(entities, id, alpha, out) {
+            const live = entities.get(id);
+            if (live === null)
+                return false;
+            const prev = previous.get(id);
+            const t = alpha < 0 ? 0 : alpha > 1 ? 1 : alpha;
+            if (prev === undefined || t >= 1) {
+                out[0] = live.position[0];
+                out[1] = live.position[1];
+                out[2] = live.position[2];
+                out[3] = live.rotationY;
+                return true;
+            }
+            const dx = live.position[0] - prev[0];
+            const dy = live.position[1] - prev[1];
+            const dz = live.position[2] - prev[2];
+            if (dx * dx + dy * dy + dz * dz > snapDistance * snapDistance) {
+                out[0] = live.position[0];
+                out[1] = live.position[1];
+                out[2] = live.position[2];
+                out[3] = live.rotationY;
+                return true;
+            }
+            out[0] = prev[0] + dx * t;
+            out[1] = prev[1] + dy * t;
+            out[2] = prev[2] + dz * t;
+            out[3] = lerpAngle(prev[3], live.rotationY, t);
+            return true;
+        },
+        snap(id) {
+            previous.delete(id);
+        },
+        retune(next) {
+            if (next.snapDistance !== undefined)
+                snapDistance = next.snapDistance;
+        },
+        snapshot() {
+            const copy = {};
+            for (const [id, pose] of previous)
+                copy[id] = [pose[0], pose[1], pose[2], pose[3]];
+            return { previous: copy };
+        },
+        restore(state) {
+            previous.clear();
+            for (const [id, pose] of Object.entries(state.previous))
+                previous.set(id, [pose[0], pose[1], pose[2], pose[3]]);
+        },
+    };
+}

package/dist/runtime/prediction.d.ts

@@ -0,0 +1,45 @@
+import type { InputFrame } from "./inputSnapshot.js";
+/** Deterministic state transition used to advance one predicted input frame. */
+export type PredictionStep<S> = (state: S, input: InputFrame, dt: number) => S;
+/** One input, tick, and resulting state retained for authoritative replay. */
+export type PredictionRecord<S> = {
+    tick: number;
+    input: InputFrame;
+    state: S;
+    dt: number;
+};
+/** Serializable prediction state containing the confirmation baseline and pending input history. */
+export type PredictionSnapshot<S> = {
+    confirmedTick: number;
+    confirmed: S;
+    predicted: S;
+    records: PredictionRecord<S>[];
+};
+/** Stateful prediction handle supporting recording, reconciliation, inspection, and restoration. */
+export type PredictionBuffer<S> = {
+    record(input: InputFrame, dt?: number, observedState?: S): S;
+    reconcile(tick: number, authoritative: S): {
+        error: number;
+        replayed: number;
+        snapped: boolean;
+        state: S;
+    };
+    state(): S;
+    snapshot(): PredictionSnapshot<S>;
+    restore(next: PredictionSnapshot<S>): void;
+};
+/**
+ * Keeps local input predictions ahead of the last server confirmation. Reconciliation replaces the
+ * confirmed state and deterministically replays unconfirmed inputs through the supplied step function.
+ * `maxTicks` bounds retained work and memory; dropped inputs are folded into the confirmed baseline.
+ * @capability client-side input prediction with replay reconciliation
+ */
+export declare function createPredictionBuffer<S>(config: {
+    initial: S;
+    step: PredictionStep<S>;
+    maxTicks: number;
+    startTick?: number;
+    dt?: number;
+    /** Error above which a caller should snap its rendered pose to the reconciled result. */
+    snapThreshold?: number;
+}): PredictionBuffer<S>;

package/dist/runtime/prediction.js

@@ -0,0 +1,62 @@
+/**
+ * Keeps local input predictions ahead of the last server confirmation. Reconciliation replaces the
+ * confirmed state and deterministically replays unconfirmed inputs through the supplied step function.
+ * `maxTicks` bounds retained work and memory; dropped inputs are folded into the confirmed baseline.
+ * @capability client-side input prediction with replay reconciliation
+ */
+export function createPredictionBuffer(config) {
+    const maxTicks = Math.max(1, Math.floor(config.maxTicks));
+    const step = config.step;
+    let confirmedTick = config.startTick ?? 0;
+    let confirmed = config.initial;
+    let predicted = config.initial;
+    let records = [];
+    const defaultDt = config.dt ?? 1 / 60;
+    const snapThreshold = Math.max(0, config.snapThreshold ?? 0.1);
+    const replay = (base, pending) => {
+        let next = base;
+        for (const record of pending)
+            next = step(next, record.input, record.dt);
+        return next;
+    };
+    return {
+        record(input, dt = defaultDt, observedState) {
+            const tick = confirmedTick + records.length + 1;
+            const state = observedState === undefined ? step(predicted, input, dt) : observedState;
+            records.push({ tick, input, state, dt });
+            predicted = state;
+            if (records.length > maxTicks) {
+                const oldest = records.shift();
+                confirmedTick = oldest.tick;
+                confirmed = oldest.state;
+            }
+            return predicted;
+        },
+        reconcile(tick, authoritative) {
+            const predictedAtTick = records.find((record) => record.tick === tick)?.state ?? confirmed;
+            const distance = (a, b) => {
+                if (typeof a === "number" && typeof b === "number")
+                    return Math.abs(a - b);
+                if (Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((v) => typeof v === "number") && b.every((v) => typeof v === "number")) {
+                    return Math.sqrt(a.reduce((sum, value, index) => sum + (Number(value) - Number(b[index])) ** 2, 0));
+                }
+                return JSON.stringify(a) === JSON.stringify(b) ? 0 : 1;
+            };
+            const dx = distance(predictedAtTick, authoritative);
+            const pending = records.filter((record) => record.tick > tick);
+            confirmedTick = tick;
+            confirmed = authoritative;
+            records = pending;
+            predicted = replay(confirmed, records);
+            return { error: dx, replayed: records.length, snapped: dx > snapThreshold, state: predicted };
+        },
+        state: () => predicted,
+        snapshot: () => ({ confirmedTick, confirmed, predicted, records: records.map((record) => ({ ...record })) }),
+        restore(next) {
+            confirmedTick = next.confirmedTick;
+            confirmed = next.confirmed;
+            predicted = next.predicted;
+            records = next.records.map((record) => ({ ...record }));
+        },
+    };
+}

package/dist/runtime/simContext.d.ts

@@ -0,0 +1,45 @@
+import type { EntityStore } from "../scene/entityStore.js";
+import { type PoseHistory, type RenderPose } from "./poseInterpolation.js";
+import { type SimAdvanceResult, type SimLoop, type SimulationConfig } from "./simLoop.js";
+/** Where a registered stage runs inside one simulation step. */
+export type SimStagePhase = "beforeMovement" | "afterMovement" | "afterTick";
+/** Extra work a game or engine seam (a physics backend, a netcode buffer) runs inside every simulation step. */
+export interface SimStage {
+    id: string;
+    phase: SimStagePhase;
+    run(dt: number, tick: number): void;
+}
+/** Serializable `ctx.sim` state: loop position plus the interpolation pose history. */
+export interface SimContextState {
+    loop: ReturnType<SimLoop["snapshot"]>;
+    poses: ReturnType<PoseHistory["snapshot"]>;
+}
+/**
+ * `ctx.sim`: the simulation stepper shared by every driver plus the render-side interpolation it enables.
+ * Drivers call {@link advance} with real elapsed seconds and do their per-step work inside the callback;
+ * renderers call {@link renderPose} each frame.
+ */
+export interface SimContext {
+    readonly loop: SimLoop;
+    /** Advance the loop; `body` runs once per simulation step with that step's dt. Pose history is captured before each step. */
+    advance(realDt: number, body: (dt: number, tick: number) => void): SimAdvanceResult;
+    tick(): number;
+    /** Interpolation fraction for the current frame, 1 on a variable loop. */
+    alpha(): number;
+    /** Interpolated pose for rendering; live pose on a variable loop. `false` when the entity does not exist. */
+    renderPose(id: string, out: RenderPose): boolean;
+    /** Forget an entity's interpolation history so it renders at its live pose next frame. */
+    snapPose(id: string): void;
+    /** Register a stage; returns an unregister handle. Stages run in registration order within a phase. */
+    addStage(stage: SimStage): () => void;
+    /** Run every stage registered for `phase`; drivers call this from inside {@link advance}'s body. */
+    runStages(phase: SimStagePhase, dt: number): void;
+    retune(config: SimulationConfig): void;
+    snapshot(): SimContextState;
+    restore(state: SimContextState): void;
+}
+/** Build `ctx.sim` for a context; `createGameContext` calls this from `definition.simulation`. */
+export declare function createSimContext(options: {
+    config?: SimulationConfig;
+    entities: EntityStore;
+}): SimContext;

package/dist/runtime/simContext.js

@@ -0,0 +1,65 @@
+import { createPoseHistory } from "./poseInterpolation.js";
+import { createSimLoop } from "./simLoop.js";
+/** Build `ctx.sim` for a context; `createGameContext` calls this from `definition.simulation`. */
+export function createSimContext(options) {
+    const { entities } = options;
+    const loop = createSimLoop(options.config);
+    const poses = createPoseHistory({ snapDistance: loop.config().snapDistance });
+    const stages = new Map();
+    let advancing = false;
+    return {
+        loop,
+        advance(realDt, body) {
+            if (advancing)
+                throw new Error("ctx.sim.advance is not reentrant");
+            advancing = true;
+            try {
+                return loop.advance(realDt, (dt, tick) => {
+                    if (loop.isFixed())
+                        poses.beginStep(entities);
+                    body(dt, tick);
+                });
+            }
+            finally {
+                advancing = false;
+            }
+        },
+        tick: () => loop.tick(),
+        alpha: () => loop.alpha(),
+        renderPose(id, out) {
+            return poses.sample(entities, id, loop.isFixed() ? loop.alpha() : 1, out);
+        },
+        snapPose: (id) => poses.snap(id),
+        addStage(stage) {
+            const list = stages.get(stage.phase) ?? [];
+            list.push(stage);
+            stages.set(stage.phase, list);
+            return () => {
+                const current = stages.get(stage.phase);
+                if (current === undefined)
+                    return;
+                const index = current.indexOf(stage);
+                if (index >= 0)
+                    current.splice(index, 1);
+            };
+        },
+        runStages(phase, dt) {
+            const list = stages.get(phase);
+            if (list === undefined)
+                return;
+            const tick = loop.tick();
+            for (const stage of list)
+                stage.run(dt, tick);
+        },
+        retune(config) {
+            loop.retune(config);
+            if (config.snapDistance !== undefined)
+                poses.retune({ snapDistance: config.snapDistance });
+        },
+        snapshot: () => ({ loop: loop.snapshot(), poses: poses.snapshot() }),
+        restore(state) {
+            loop.restore(state.loop);
+            poses.restore(state.poses);
+        },
+    };
+}

package/dist/runtime/simLoop.d.ts

@@ -0,0 +1,52 @@
+/** How the simulation is stepped: a fixed rate with a catch-up cap, or once per frame with the frame's dt. */
+export interface SimulationConfig {
+    /**
+     * Fixed simulation rate in steps per second, or `"variable"` to run one step per frame with the frame's
+     * clamped dt. Default `"variable"` (the historical behavior). A fixed rate makes every step's dt identical,
+     * which is what determinism, replay, rollback, and a stable physics solver need; renderers read
+     * `ctx.sim.renderPose` to interpolate between steps.
+     */
+    hz?: number | "variable";
+    /** Fixed steps run per advance before the loop drops the remaining time instead of spiralling. Default 5. */
+    maxCatchUpSteps?: number;
+    /** Entities that move farther than this in one step snap instead of interpolating (teleports, respawns). Default 8 world units. */
+    snapDistance?: number;
+}
+/** Serializable loop position: the tick count and the real seconds accumulated toward the next fixed step. */
+export interface SimLoopState {
+    tick: number;
+    accumulator: number;
+}
+/** What one {@link SimLoop.advance} did. */
+export interface SimAdvanceResult {
+    /** Steps run this advance. */
+    steps: number;
+    /** Fraction of a step accumulated but not yet simulated, 0..1; always 1 on a variable loop. */
+    alpha: number;
+    /** Tick count after this advance. */
+    tick: number;
+    /** Steps discarded because the catch-up cap was hit. */
+    dropped: number;
+}
+/** The stepper handle: advance with real time, read the tick and interpolation alpha, retune the rate, snapshot and restore. */
+export interface SimLoop {
+    /** Feed real elapsed seconds; runs `step(dt, tick)` zero or more times and returns what happened. */
+    advance(realDt: number, step: (dt: number, tick: number) => void): SimAdvanceResult;
+    tick(): number;
+    alpha(): number;
+    /** Seconds per fixed step, `null` on a variable loop. */
+    stepSeconds(): number | null;
+    isFixed(): boolean;
+    retune(config: SimulationConfig): void;
+    config(): Readonly<Required<SimulationConfig>>;
+    snapshot(): SimLoopState;
+    restore(state: SimLoopState): void;
+}
+/**
+ * The simulation stepper every driver (shell frame, headless runner, authoritative host) advances through, so
+ * the sim sees the same dt sequence regardless of who drives it. Fixed mode accumulates real time and steps in
+ * equal slices with a catch-up cap; variable mode steps once per advance.
+ *
+ * @capability sim-loop fixed-step or variable simulation stepping with tick count, catch-up cap, and interpolation alpha
+ */
+export declare function createSimLoop(initial?: SimulationConfig): SimLoop;