@jgengine/core 0.19.0 → 0.22.0

package/dist/runtime/hostedWorldSession.d.ts

@@ -7,7 +7,12 @@ import type { WorldDiff } from "./worldReplication.js";
 import type { SnapshotViewer, WorldSnapshot } from "./worldSnapshot.js";
 import type { HostedWorldRecord, HostedWorldStore, SyncHostedWorldStore } from "./hostedWorldStore.js";
 export type { HostedWorldRecord, HostedWorldStore, SyncHostedWorldStore } from "./hostedWorldStore.js";
-/** In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host.
+/** @internal Decode the retry envelope shared by authoritative hosts. */
+export declare function unwrapOpEnvelope(input: unknown): {
+    opId: string;
+    input: unknown;
+} | null;
+/** Detached in-process {@link SyncHostedWorldStore} for tests, local play, and the browser-tab P2P host.
  * @internal
  */
 export declare function memoryWorldStore(seed?: HostedWorldRecord): SyncHostedWorldStore;
@@ -30,8 +35,10 @@ export interface HostedWorldSessionOptions<TAssetRef extends ModelAssetRef, TMul
     now?: () => number;
     /** Where the authoritative snapshot persists; defaults to {@link memoryWorldStore}. */
     store?: SyncHostedWorldStore;
-    /** Minimum elapsed ms between auto-saves on tick, measured against `now` (defaults to `Date.now` when omitted). Default `0` — persist on every revision-changing tick. */
+    /** Minimum elapsed ms between automatic saves, measured against `now` (default `Date.now`). Default `0`; private clock/simulation changes also count. A pending write defers automatic capture until a later tick. */
     saveIntervalMs?: number;
+    /** Retained retry receipts per player. Default `64`; retries after eviction are new operations. */
+    operationHistoryLimit?: number;
     /** Render-model lookup for collider auto-fit, forwarded to the runner — see {@link HostedGameRunnerOptions.models}. */
     models?: GameContextModels;
 }
@@ -43,11 +50,14 @@ export interface HostedWorldSessionOptions<TAssetRef extends ModelAssetRef, TMul
  */
 export interface HostedWorldSession {
     join(userId: string, isNew: boolean): void;
+    /** Whether this identity has joined before, including across leave/restart. */
+    hasPlayer(userId: string): boolean;
     leave(userId: string): void;
     input(userId: string, frame: InputFrame): void;
-    command(userId: string, name: string, input: unknown): CommandResult<GameContext>;
+    /** Optional stable operation id deduplicates retries across reconnect/restart; the receipt persists atomically with state. */
+    command(userId: string, name: string, input: unknown, operationId?: string): CommandResult<GameContext>;
     tick(dt: number): number;
-    /** Replication pull: `null`/`0` cursor → full baseline; a prior revision → a diff since it. */
+    /** Replication pull: a fresh, pre-restart or future cursor receives a baseline; an in-session revision receives a diff. */
     sync(sinceRevision: number | null): HostedWorldSync;
     /** Alias used by host transports when pulling the next baseline or diff for a subscriber. */
     pull(sinceRevision: number | null): HostedWorldSync;
@@ -58,7 +68,9 @@ export interface HostedWorldSession {
     revision(): number;
     members(): readonly string[];
     /** Force-persist the current world to the store. */
-    save(): void;
+    save(): void | Promise<void>;
+    /** Most recent automatic save failure; cleared by a successful write. Explicit `save()` also rejects. */
+    persistenceError(): unknown | null;
     runner(): HostedGameRunner;
 }
 /** Build a {@link HostedWorldSession} — a live runner loaded from a {@link HostedWorldStore} and auto-persisted on tick.

package/dist/runtime/hostedWorldSession.js

@@ -1,22 +1,34 @@
 import { createHostedGameRunner } from "./hostedGameRunner.js";
-/** In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host.
+import { applyWorldSnapshot } from "./worldSnapshot.js";
+/** @internal Decode the retry envelope shared by authoritative hosts. */
+export function unwrapOpEnvelope(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return null;
+    const record = input;
+    const opId = record["__jgWsOpId"];
+    if (typeof opId !== "string")
+        return null;
+    const { __jgWsOpId: _opId, ...rest } = record;
+    return { opId, input: rest };
+}
+/** Detached in-process {@link SyncHostedWorldStore} for tests, local play, and the browser-tab P2P host.
  * @internal
  */
 export function memoryWorldStore(seed) {
-    let record = seed ?? null;
+    let record = seed === undefined ? null : structuredClone(seed);
     return {
-        load: () => record,
+        load: () => record === null ? null : structuredClone(record),
         save(next) {
-            record = { snapshot: next.snapshot, revision: next.revision };
+            record = structuredClone(next);
         },
     };
 }
 /** Async in-process store for callers exercising the production persistence contract. */
 export function asyncMemoryWorldStore(seed) {
-    let record = seed ?? null;
+    let record = seed === undefined ? null : structuredClone(seed);
     return {
-        async load() { return record; },
-        async save(next) { record = { snapshot: next.snapshot, revision: next.revision }; },
+        async load() { return record === null ? null : structuredClone(record); },
+        async save(next) { record = structuredClone(next); },
     };
 }
 /** Build a {@link HostedWorldSession} — a live runner loaded from a {@link HostedWorldStore} and auto-persisted on tick.
@@ -33,32 +45,157 @@ export function createHostedWorldSession(options) {
         ...(host === undefined ? {} : { host }),
         ...(now === undefined ? {} : { now }),
         ...(loaded === null ? {} : { restore: loaded.snapshot }),
+        revision: loaded?.revision ?? 0,
         ...(options.models === undefined ? {} : { models: options.models }),
     });
+    const knownPlayers = new Set();
+    const operations = new Map();
+    const configuredHistory = options.operationHistoryLimit ?? 64;
+    const historyLimit = Number.isFinite(configuredHistory) ? Math.max(1, Math.floor(configuredHistory)) : 64;
+    const sessionModule = {
+        key: "hostSession",
+        snapshot: () => ({ players: [...knownPlayers], operations: [...operations] }),
+        hydrate(state) {
+            knownPlayers.clear();
+            for (const userId of state.players)
+                knownPlayers.add(userId);
+            operations.clear();
+            for (const [userId, receipts] of state.operations)
+                operations.set(userId, receipts.slice(-historyLimit));
+        },
+        decode(raw) {
+            if (raw === null || typeof raw !== "object" || !("players" in raw) || !("operations" in raw))
+                return null;
+            if (!Array.isArray(raw.players) || !raw.players.every((id) => typeof id === "string") || !Array.isArray(raw.operations))
+                return null;
+            for (const entry of raw.operations) {
+                if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== "string" || !Array.isArray(entry[1]))
+                    return null;
+                for (const receipt of entry[1]) {
+                    if (receipt === null || typeof receipt !== "object" || typeof receipt.id !== "string" ||
+                        typeof receipt.command !== "string" || typeof receipt.input !== "string" ||
+                        !["applied", "rejected", "unknown-command"].includes(receipt.outcome) ||
+                        (receipt.outcome === "rejected" && typeof receipt.reason !== "string"))
+                        return null;
+                }
+            }
+            return raw;
+        },
+    };
+    runner.context().game.registerSave?.(sessionModule);
+    if (loaded !== null) {
+        if (Object.hasOwn(loaded.snapshot, "hostSession") && sessionModule.decode(loaded.snapshot["hostSession"]) === null) {
+            throw new Error("Invalid hosted player/retry state; save left untouched");
+        }
+        applyWorldSnapshot([sessionModule], loaded.snapshot);
+    }
     let savedRevision = loaded?.revision ?? 0;
+    let savedVersion = runner.context().version();
+    let savedSimTick = runner.context().sim.tick();
     let lastSaveAt = clock();
+    let writing = null;
+    let saveFailure = null;
     function persist() {
-        savedRevision = runner.revision();
-        store.save({ snapshot: runner.snapshot(), revision: savedRevision });
+        const record = { snapshot: runner.state(), revision: runner.revision() };
+        const version = runner.context().version();
+        const simTick = runner.context().sim.tick();
+        const success = () => {
+            savedRevision = record.revision;
+            savedVersion = version;
+            savedSimTick = simTick;
+            saveFailure = null;
+        };
+        const write = () => store.save(record);
+        let pending;
+        try {
+            pending = writing === null ? write() : writing.catch(() => { }).then(write);
+        }
+        catch (error) {
+            saveFailure = error;
+            throw error;
+        }
+        if (pending === undefined) {
+            success();
+            return;
+        }
+        const completion = pending.then(success, (error) => {
+            saveFailure = error;
+            throw error;
+        });
+        writing = completion;
+        void completion.catch(() => { }).finally(() => {
+            if (writing === completion)
+                writing = null;
+        });
+        return completion;
     }
     const pull = (sinceRevision) => {
-        if (sinceRevision === null || sinceRevision <= 0) {
+        if (sinceRevision === null || sinceRevision <= (loaded?.revision ?? 0) || sinceRevision > runner.revision()) {
             return { kind: "baseline", revision: runner.revision(), snapshot: runner.snapshot() };
         }
         return { kind: "diff", diff: runner.diff(sinceRevision) };
     };
     return {
-        join: (userId, isNew) => runner.join(userId, isNew),
-        leave: (userId) => runner.leave(userId),
+        join(userId, isNew) {
+            runner.join(userId, knownPlayers.has(userId) ? false : isNew);
+            knownPlayers.add(userId);
+            runner.context().touch();
+            runner.commit();
+        },
+        hasPlayer: (userId) => knownPlayers.has(userId),
+        leave(userId) {
+            runner.leave(userId);
+            runner.commit();
+        },
         input: (userId, frame) => runner.input(userId, frame),
-        command: (userId, name, input) => runner.command(userId, name, input),
+        command(userId, name, input, operationId) {
+            const envelope = unwrapOpEnvelope(input);
+            if (envelope !== null) {
+                operationId ??= envelope.opId;
+                input = envelope.input;
+            }
+            const receipts = operations.get(userId) ?? [];
+            const inputJson = JSON.stringify(input) ?? "null";
+            const receipt = operationId === undefined ? undefined : receipts.find((entry) => entry.id === operationId);
+            if (receipt !== undefined) {
+                if (receipt.command !== name || receipt.input !== inputJson)
+                    return { status: "rejected", reason: "operation-conflict" };
+                if (receipt.outcome === "applied")
+                    return { status: "applied", state: runner.context() };
+                if (receipt.outcome === "rejected")
+                    return { status: "rejected", reason: receipt.reason };
+                return { status: "unknown-command" };
+            }
+            const before = runner.state();
+            let result;
+            try {
+                result = runner.command(userId, name, input);
+            }
+            catch (error) {
+                runner.context().restore(before);
+                throw error;
+            }
+            if (result.status !== "applied")
+                runner.context().restore(before);
+            if (operationId !== undefined) {
+                receipts.push({ id: operationId, command: name, input: inputJson, outcome: result.status,
+                    ...(result.status === "rejected" ? { reason: result.reason } : {}) });
+                operations.set(userId, receipts.slice(-historyLimit));
+                runner.context().touch();
+            }
+            runner.commit();
+            return result;
+        },
         tick(dt) {
             const revision = runner.tick(dt);
-            if (revision !== savedRevision) {
+            if (writing === null && (revision !== savedRevision || runner.context().version() !== savedVersion || runner.context().sim.tick() !== savedSimTick)) {
                 const at = clock();
                 if (saveIntervalMs <= 0 || at - lastSaveAt >= saveIntervalMs) {
                     lastSaveAt = at;
-                    persist();
+                    try {
+                        persist();
+                    }
+                    catch { /* Exposed by persistenceError and retried by the next save. */ }
                 }
             }
             return revision;
@@ -70,6 +207,7 @@ export function createHostedWorldSession(options) {
         revision: () => runner.revision(),
         members: () => runner.members(),
         save: persist,
+        persistenceError: () => saveFailure,
         runner: () => runner,
     };
 }
@@ -81,7 +219,7 @@ export async function createHostedWorldSessionAsync(options) {
         ...sessionOptions,
         store: {
             load: () => loaded,
-            save: (record) => { void store.save(record); },
+            save: (record) => store.save(record),
         },
     });
     return session;

package/dist/runtime/hostedWorldStore.d.ts

@@ -13,8 +13,8 @@ export interface HostedWorldStore {
     load(): Promise<HostedWorldRecord | null>;
     save(record: HostedWorldRecord): Promise<void>;
 }
-/** Synchronous store adapter retained for deterministic in-process tests. */
+/** Already-loaded store adapter: synchronous reads, with synchronous or asynchronous writes. */
 export interface SyncHostedWorldStore {
     load(): HostedWorldRecord | null;
-    save(record: HostedWorldRecord): void;
+    save(record: HostedWorldRecord): void | Promise<void>;
 }

package/dist/runtime/inputRecorder.d.ts

@@ -10,7 +10,7 @@ export interface InputRecorderState {
 }
 /** Tick-indexed input log: record per tick, look up the frame in force at any tick. */
 export interface InputRecorder {
-    /** Store the frame in force from `tick` onward. Recording the same tick twice replaces the earlier frame. */
+    /** Store held state from `tick` onward and presses on that tick only. Same-tick recordings merge press identities while replacing continuous state. */
     record(tick: number, frame: InputFrame): void;
     /** The frame in force at `tick`: the latest recorded frame whose tick is at most `tick`, or `null` before the first. */
     frameAt(tick: number): InputFrame | null;

package/dist/runtime/inputRecorder.js

@@ -2,6 +2,7 @@ function cloneFrame(frame) {
     return {
         held: [...frame.held],
         pointer: frame.pointer === null ? null : { ...frame.pointer },
+        ...(frame.presses === undefined ? {} : { presses: frame.presses.map(press => ({ ...press })) }),
         ...(frame.analog === undefined ? {} : { analog: frame.analog === null ? null : { ...frame.analog } }),
         ...(frame.tick === undefined ? {} : { tick: frame.tick }),
     };
@@ -14,6 +15,7 @@ function cloneFrame(frame) {
  */
 export function createInputRecorder() {
     let frames = [];
+    const continuousFrames = new WeakMap();
     function indexAtOrBefore(tick) {
         let lo = 0;
         let hi = frames.length - 1;
@@ -35,6 +37,13 @@ export function createInputRecorder() {
             const entry = { tick, frame: cloneFrame(frame) };
             const index = indexAtOrBefore(tick);
             if (index >= 0 && frames[index].tick === tick) {
+                const previous = frames[index].frame.presses;
+                if (previous !== undefined) {
+                    const presses = new Map(previous.map(press => [press.seq, press]));
+                    for (const press of entry.frame.presses ?? [])
+                        presses.set(press.seq, press);
+                    entry.frame.presses = [...presses.values()].map(press => ({ ...press }));
+                }
                 frames[index] = entry;
                 return;
             }
@@ -42,7 +51,18 @@ export function createInputRecorder() {
         },
         frameAt(tick) {
             const index = indexAtOrBefore(tick);
-            return index < 0 ? null : frames[index].frame;
+            if (index < 0)
+                return null;
+            const entry = frames[index];
+            if (entry.tick === tick || entry.frame.presses === undefined)
+                return entry.frame;
+            let heldFrame = continuousFrames.get(entry.frame);
+            if (heldFrame === undefined) {
+                const { presses: _presses, ...continuous } = entry.frame;
+                heldFrame = continuous;
+                continuousFrames.set(entry.frame, heldFrame);
+            }
+            return heldFrame;
         },
         frames: () => frames,
         lastTick: () => (frames.length === 0 ? -1 : frames[frames.length - 1].tick),

package/dist/runtime/inputSnapshot.d.ts

@@ -1,10 +1,17 @@
 import type { PointerAxisState } from "../input/pointerAxis.js";
 import { type AxisBinding, type AxisRange } from "../input/axisInput.js";
 import { type HapticChannels } from "../input/haptics.js";
-/** One client's input for a tick — the semantic held-action set plus pointer state, the serializable, over-the-wire counterpart of {@link InputSnapshot} the host stores per connected player. */
+/** One discrete press, identified across retransmitted live input frames. */
+export interface InputPress {
+    action: string;
+    seq: number;
+}
+/** One client's serializable held state and discrete edges for a simulation tick. */
 export interface InputFrame {
     held: readonly string[];
     pointer: PointerAxisState | null;
+    /** Discrete presses retained through release until the host accepts them. Each identity applies once, on its recorded simulation tick. */
+    presses?: readonly InputPress[];
     /** Analog per-action magnitudes (0..1) for actions driven by a continuous source (virtual joystick, gamepad stick); absent/null means every held action is fully pressed. */
     analog?: Readonly<Record<string, number>> | null;
     /** Simulation tick (`ctx.sim.tick()`) the frame was captured for; hosts and replay align inputs on it. Absent from senders that predate the fixed-step loop. */
@@ -22,8 +29,13 @@ export interface InputSnapshot {
      * and the shell mixes them by priority onto that user's pad. Local only — never in a snapshot or on the wire.
      */
     haptics(userId: string): HapticChannels;
-    /** Replaces the held-action set for this frame, rolling the previous held set forward for edge detection (#671). Called by the shell before `onTick` each frame; does not bump `ctx.version()` or notify `ctx.subscribe` listeners — per-frame publishes would storm subscribers. */
-    publish(held: readonly string[]): void;
+    /** Replaces held state without notifying subscribers. Supplying `edges` buffers short presses until `beginStep`; `reset` discards the current owner's pending edges. Without `edges`, legacy publication-based edge detection is preserved. */
+    publish(held: readonly string[], edges?: {
+        pressed?: readonly string[];
+        reset?: boolean;
+    }): void;
+    /** Sample buffered input once before a simulation step. Zero-step render frames retain presses; subsequent steps retire the sampled edges. */
+    beginStep(): void;
     /** Replaces the normalized pointer-position state for this frame (#293). Same no-notify contract as `publish`. */
     publishPointer(state: PointerAxisState | null): void;
     /** Replaces the analog per-action magnitudes for this frame (#1370) — the virtual joystick's continuous vector, split into 0..1 values per movement action. `null` clears back to digital-only. Same no-notify contract as `publish`. */
@@ -31,7 +43,7 @@ export interface InputSnapshot {
     isDown(action: string): boolean;
     /** The held-action set for this frame — an owned, frozen array; the array {@link publish} was called with is never aliased or returned. */
     held(): readonly string[];
-    /** True only on the frame `action` transitions from up to down (#671) — derived from the last two published held sets, so it stays replay-safe. */
+    /** True on the sampled simulation step containing a press; legacy publishers use the last two held sets. */
     justPressed(action: string): boolean;
     /** True only on the frame `action` transitions from down to up (#671); mirrors {@link justPressed}. */
     justReleased(action: string): boolean;

package/dist/runtime/inputSnapshot.js

@@ -6,6 +6,11 @@ export function createInputSnapshot() {
     let heldList = [];
     let pointerState = null;
     let analogValues = null;
+    let buffered = false;
+    let stepHeld = new Set();
+    const pendingPressed = new Set();
+    let stepPressed = new Set();
+    let stepReleased = new Set();
     const haptics = new Map();
     const value = (action) => {
         const analog = analogValues?.[action];
@@ -23,10 +28,33 @@ export function createInputSnapshot() {
             }
             return channels;
         },
-        publish(held) {
+        publish(held, edges) {
             previousHeldSet = heldSet;
             heldList = Object.freeze([...held]);
             heldSet = new Set(held);
+            if (edges !== undefined) {
+                buffered = true;
+                if (edges.reset) {
+                    pendingPressed.clear();
+                    stepPressed.clear();
+                    stepReleased.clear();
+                    stepHeld = new Set(held);
+                }
+                else {
+                    for (const action of edges.pressed ?? [])
+                        pendingPressed.add(action);
+                }
+            }
+        },
+        beginStep() {
+            buffered = true;
+            stepPressed = new Set(pendingPressed);
+            pendingPressed.clear();
+            for (const action of heldSet)
+                if (!stepHeld.has(action))
+                    stepPressed.add(action);
+            stepReleased = new Set([...stepHeld].filter(action => !heldSet.has(action)));
+            stepHeld = new Set(heldSet);
         },
         publishPointer(state) {
             pointerState = state === null ? null : Object.freeze({ ...state });
@@ -40,7 +68,7 @@ export function createInputSnapshot() {
         value,
         analog: () => analogValues,
         axis: (bindings, ranges) => sampleAxisBindings(bindings, (action) => heldSet.has(action), pointerState, ranges, value),
-        justPressed: (action) => heldSet.has(action) && !previousHeldSet.has(action),
-        justReleased: (action) => !heldSet.has(action) && previousHeldSet.has(action),
+        justPressed: (action) => buffered ? stepPressed.has(action) : heldSet.has(action) && !previousHeldSet.has(action),
+        justReleased: (action) => buffered ? stepReleased.has(action) : !heldSet.has(action) && previousHeldSet.has(action),
     };
 }

package/dist/runtime/runtimeSave.d.ts

@@ -2,7 +2,7 @@ import { type SaveBackend, type SaveStatus, type SaveTimers } from "../game/save
 import type { WorldSnapshot } from "./worldSnapshot.js";
 /**
  * The narrow slice of a live `GameContext` a runtime save reads and writes — a
- * `GameContext` satisfies it directly (`ctx.snapshot`/`ctx.hydrate`/`ctx.subscribe`).
+ * `GameContext` satisfies it directly (`ctx.state`/`ctx.restore`/`ctx.subscribe`).
  * Depending on this instead of the full context keeps the save controller a deep,
  * decoupled module: it captures and restores the *whole* opted-in world without
  * knowing any subsystem.
@@ -10,6 +10,10 @@ import type { WorldSnapshot } from "./worldSnapshot.js";
 export interface RuntimeSaveTarget {
     snapshot(): WorldSnapshot;
     hydrate(snapshot: WorldSnapshot): void;
+    /** Complete authoritative capture when the target distinguishes persistence from replication. */
+    state?(): WorldSnapshot;
+    /** Authoritative inverse of `state`; used together with it instead of replication hydration. */
+    restore?(state: WorldSnapshot): void;
     subscribe(listener: () => void): () => void;
 }
 /** `"autosave"` writes a fresh capture on a trailing timer while the world changes (at most once per `autosaveMs`, so a never-idle world still persists); `"manual"` writes only on an explicit `save()`/`checkpoint()` — the save-point / quest-trigger model. */
@@ -39,8 +43,8 @@ export interface RuntimeSaveConfig {
 export type RuntimeSaveOptions = Omit<RuntimeSaveConfig, "target">;
 /**
  * Whole-world save/load bound to a live world and a pluggable backend. `save()`
- * captures `target.snapshot()` and writes it; `load()` reads it back and
- * `target.hydrate()`s the whole world. In `autosave` mode it also writes on a
+ * captures `target.state()` and writes it; `load()` reads it back and
+ * calls `target.restore()`. Older targets use `snapshot()`/`hydrate()`. In `autosave` mode it also writes on a
  * trailing timer while the world keeps changing. Named slots, versioned migration, and offline↔cloud
  * (backend swap) all come for free from the underlying save store.
  */
@@ -51,13 +55,13 @@ export interface RuntimeSave {
     save(): Promise<void>;
     /** Semantic alias for `save()` — call it from a save point, a quest-complete or area-enter handler. */
     checkpoint(): Promise<void>;
-    /** Load the active slot and hydrate the whole world; resolves `true` when a real save was applied, `false` for an empty slot. */
+    /** Load the active slot and hydrate the whole world; resolves `true` when a real save was applied, `false` for an empty slot or failed payload read. Failed reads never restore cached state. */
     load(): Promise<boolean>;
-    /** Whether the active slot holds a saved world — gate a title-screen "Continue" on it. */
+    /** Whether the active slot holds a saved world — gate a title-screen "Continue" on it. Failed payload reads resolve false and report error status. */
     hasSave(): Promise<boolean>;
     /** Delete the active slot's save. */
     clear(): Promise<void>;
-    /** Switch slot and load it, hydrating the world when that slot has a save. */
+    /** Switch slot and load it, hydrating the world when that slot has a save. Failed payload reads resolve false without restoring cached state. */
     switchSlot(slot: string): Promise<boolean>;
     /** The slots this game has written — back a load/save menu. */
     slots(): Promise<string[]>;

package/dist/runtime/runtimeSave.js

@@ -48,7 +48,7 @@ export function createRuntimeSave(config) {
     }
     function persist() {
         clearTimer();
-        store.set(config.target.snapshot());
+        store.set(config.target.state?.() ?? config.target.snapshot());
         return store.save();
     }
     /**
@@ -77,7 +77,10 @@ export function createRuntimeSave(config) {
             return false;
         restoring = true;
         try {
-            config.target.hydrate(snapshot);
+            if (config.target.restore !== undefined)
+                config.target.restore(snapshot);
+            else
+                config.target.hydrate(snapshot);
         }
         finally {
             restoring = false;
@@ -91,15 +94,18 @@ export function createRuntimeSave(config) {
         save,
         checkpoint: save,
         async load() {
-            return applyLoaded(await store.load());
+            const snapshot = await store.load();
+            return store.status() !== "error" && applyLoaded(snapshot);
         },
         async hasSave() {
-            return hasContent(await store.load());
+            const snapshot = await store.load();
+            return store.status() !== "error" && hasContent(snapshot);
         },
         clear: () => store.clear(),
         async switchSlot(slot) {
             clearTimer();
-            return applyLoaded(await store.switchSlot(slot));
+            const snapshot = await store.switchSlot(slot);
+            return store.status() !== "error" && applyLoaded(snapshot);
         },
         slots: () => store.slots(),
         subscribe: (listener) => store.subscribe(listener),

package/dist/runtime/simContext.d.ts

@@ -1,4 +1,5 @@
 import type { EntityStore } from "../scene/entityStore.js";
+import type { SimClock } from "../time/simClock.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. */
@@ -7,7 +8,8 @@ export type SimStagePhase = "beforeMovement" | "afterMovement" | "afterTick";
 export interface SimStage {
     id: string;
     phase: SimStagePhase;
-    run(dt: number, tick: number): void;
+    /** dt is real seconds; gameDt is the scaled authoritative game-seconds for this step. */
+    run(dt: number, tick: number, gameDt: number): void;
 }
 /** Serializable `ctx.sim` state: loop position plus the interpolation pose history. */
 export interface SimContextState {
@@ -21,8 +23,10 @@ export interface SimContextState {
  */
 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;
+    /** Advance simulation and its game clock once per step. The callback receives real dt, tick and scaled game dt. Prediction can opt out of clock advancement. */
+    advance(realDt: number, body: (dt: number, tick: number, gameDt: number) => void, options?: {
+        advanceTime?: boolean;
+    }): SimAdvanceResult;
     tick(): number;
     /** Interpolation fraction for the current frame, 1 on a variable loop. */
     alpha(): number;
@@ -42,4 +46,5 @@ export interface SimContext {
 export declare function createSimContext(options: {
     config?: SimulationConfig;
     entities: EntityStore;
+    time?: Pick<SimClock, "advance">;
 }): SimContext;

package/dist/runtime/simContext.js

@@ -7,9 +7,10 @@ export function createSimContext(options) {
     const poses = createPoseHistory({ snapDistance: loop.config().snapDistance });
     const stages = new Map();
     let advancing = false;
+    let currentGameDt = 0;
     return {
         loop,
-        advance(realDt, body) {
+        advance(realDt, body, stepOptions) {
             if (advancing)
                 throw new Error("ctx.sim.advance is not reentrant");
             advancing = true;
@@ -17,11 +18,14 @@ export function createSimContext(options) {
                 return loop.advance(realDt, (dt, tick) => {
                     if (loop.isFixed())
                         poses.beginStep(entities);
-                    body(dt, tick);
+                    const gameDt = stepOptions?.advanceTime === false ? 0 : options.time?.advance(dt) ?? dt;
+                    currentGameDt = gameDt;
+                    body(dt, tick, gameDt);
                 });
             }
             finally {
                 advancing = false;
+                currentGameDt = 0;
             }
         },
         tick: () => loop.tick(),
@@ -49,7 +53,7 @@ export function createSimContext(options) {
                 return;
             const tick = loop.tick();
             for (const stage of list)
-                stage.run(dt, tick);
+                stage.run(dt, tick, advancing ? currentGameDt : dt);
         },
         retune(config) {
             loop.retune(config);

package/dist/runtime/simSnapshot.js

@@ -47,6 +47,8 @@ export function createContextSimSnapshot(ctx) {
         capture: () => structuredClone(ctx.snapshot()),
         restore: (data) => ctx.hydrate(structuredClone(data)),
     });
+    registry.register({ id: "projectiles", capture: ctx.scene.entity.projectileState, restore: ctx.scene.entity.restoreProjectiles });
+    registry.register({ id: "environment", capture: ctx.environment.snapshot, restore: ctx.environment.restore });
     registry.register({ id: "clock", capture: () => ctx.time.snapshot(), restore: (data) => ctx.time.hydrate(data) });
     registry.register({ id: "sim", capture: () => ctx.sim.snapshot(), restore: (data) => ctx.sim.restore(data) });
     if (rngStateOf(ctx.rng) !== null) {

package/dist/runtime/worldReplication.d.ts

@@ -35,6 +35,8 @@ export interface WorldDiff {
  */
 export interface WorldReplicatorOptions {
     worldVersion?: () => number;
+    /** Cursor loaded with a persisted baseline; new commits continue above it. Default `0`. */
+    initialRevision?: number;
 }
 /**
  * Turns successive full {@link WorldSnapshot}s into per-client {@link WorldDiff}s. Each `commit()` re-reads the

package/dist/runtime/worldReplication.js

@@ -10,7 +10,7 @@ const CORE_KEYS = new Set(["entities", "stats", "store"]);
 export function createWorldReplicator(takeSnapshot, options = {}) {
     const worldVersion = options.worldVersion;
     let committedVersion;
-    let revision = 0;
+    let revision = options.initialRevision ?? 0;
     const entities = new Map();
     const removedEntities = new Map();
     const stats = new Map();