@jgengine/core 0.26.0 → 0.28.0

package/dist/game/gameSave.d.ts

@@ -0,0 +1,142 @@
+import { type SaveAutoConfig, type SaveBackend, type SaveStatus, type SaveTimers } from "./saveStore.js";
+/** Current save-format version of {@link GameSaveDocument}. Bump it with {@link GameSaveConfig.migrate} when the shape changes. */
+export declare const GAME_SAVE_VERSION = 1;
+/**
+ * One stateful system inside a game save: a stable `name` (its section key in the document) and the
+ * `snapshot()`/`restore()` pair every Lane B module exposes. The name is the contract — a document
+ * written by one build restores into the next build's system with the same name. `reset` runs when a
+ * loaded slot has no section for this system (a fresh slot), so switching to an empty slot starts a
+ * new game instead of leaving the previous one's state behind; a system without it is left as-is.
+ */
+export interface GameSaveSystem<T = unknown> {
+    readonly name: string;
+    snapshot(): T;
+    restore(next: T): void;
+    reset?(): void;
+}
+/** The persisted cursor of the world's shared injected RNG, plus the seed that produced it. */
+export interface GameSaveRngState {
+    /** Seed the stream was created from, so a reload can rebuild the same sequence. */
+    seed: string | number;
+    /** The stream's cursor, or `null` for a generator that carries no state. */
+    cursor: number | null;
+}
+/**
+ * The one save document: a format `version`, the game and clock metadata a save-select menu shows,
+ * the world's shared RNG cursor, and one section per registered system. There is deliberately no
+ * second per-system format — every system's state lives under `systems[<name>]`.
+ */
+export interface GameSaveDocument {
+    /** {@link GAME_SAVE_VERSION} this document was written at. */
+    version: number;
+    /** Stable game id, so a document names the game it belongs to. */
+    game: string;
+    /** Wall-clock time (ms) the document was captured. */
+    savedAt: number;
+    /** World clock (game seconds) at capture. */
+    time: number;
+    /** Seconds played at capture. */
+    playtime: number;
+    /** The shared RNG's seed and cursor, or `null` when the game injects no shared stream. */
+    rng: GameSaveRngState | null;
+    /** One entry per registered system, keyed by its name. */
+    systems: Record<string, unknown>;
+}
+/** The world's shared injected RNG: its `seed` and the live `stream` whose cursor is persisted. */
+export interface GameSaveRng {
+    readonly seed: string | number;
+    readonly stream: () => number;
+}
+/** How a {@link createGameSave} is wired. Storage is the narrow injected {@link SaveBackend}, never `localStorage` welded in. */
+export interface GameSaveConfig {
+    /** Where the document is written — {@link localSaveBackend}, {@link memorySaveBackend}, or a remote/cloud backend. */
+    readonly backend: SaveBackend;
+    /** Stable game id, stored in every document. */
+    readonly game: string;
+    /** Systems whose sections make up the document. More can be added later with `register`. */
+    readonly systems?: readonly GameSaveSystem[];
+    /** Save-format version. Default {@link GAME_SAVE_VERSION}. */
+    readonly version?: number;
+    /** The world's shared injected RNG. Its seed and cursor are stored so the same sequence resumes. */
+    readonly rng?: GameSaveRng;
+    /** World clock reader, in game seconds. Default `() => 0`. */
+    readonly clock?: () => number;
+    /** Playtime reader, in seconds. Default `() => 0`. */
+    readonly playtime?: () => number;
+    /** Active slot. Default `"default"`. */
+    readonly slot?: string;
+    /** Storage namespace. Default `game-save:<game>`. */
+    readonly key?: string;
+    /**
+     * Autosave cadence, as caller policy: `false` (default) writes only on an explicit `save()`;
+     * `true` debounces on the default window; an object sets its own debounce and ceiling.
+     */
+    readonly autosave?: boolean | SaveAutoConfig;
+    /** Injectable clock (ms) for `savedAt`. Default `Date.now`. */
+    readonly now?: () => number;
+    /** Injectable timers for autosave. Default the ambient `setTimeout`/`clearTimeout`. */
+    readonly timers?: SaveTimers;
+    /**
+     * Upgrade an older document to the current shape. Receives the stored document and the version it
+     * was written at (`0` for a pre-versioned payload) and returns a document at {@link GameSaveConfig.version}.
+     */
+    readonly migrate?: (document: unknown, fromVersion: number) => GameSaveDocument;
+    /** Notified on any backend read/write failure or a restored document written by another world. */
+    readonly onError?: (error: unknown) => void;
+    /** Register a devtools probe under this name so the overlay shows the slot, status and system count. */
+    readonly devtoolsName?: string;
+}
+/**
+ * A pluggable-backend game save: one versioned document holding a section per system, with named
+ * slots, caller-policy autosave, migration and a state digest. `capture()` builds the document from
+ * the live systems; `save()`/`touch()` write it (directly or on the autosave debounce); `load()`
+ * reads a slot and applies every section back through its system's `restore`. The shared RNG's
+ * cursor rides along, so the seed survives the save and a reloaded run continues the same sequence.
+ */
+export interface GameSave {
+    /** Register a system after construction; returns an unregister fn. Throws on a duplicate name. */
+    register(system: GameSaveSystem): () => void;
+    /** Build the current document from every registered system. Does not write. */
+    capture(): GameSaveDocument;
+    /** Write the live state to the active slot now. */
+    save(): Promise<void>;
+    /** Read the active slot and apply every section to its system. */
+    load(): Promise<GameSaveDocument>;
+    /** Flush the current slot, switch, and load the next one. */
+    switchSlot(slot: string): Promise<GameSaveDocument>;
+    /**
+     * Read a slot's document without applying it to the live systems — the save-select menu's data
+     * source. Returns `null` for an empty slot.
+     */
+    peek(slot: string): Promise<GameSaveDocument | null>;
+    /** Slots this save has written. */
+    slots(): Promise<string[]>;
+    slot(): string;
+    status(): SaveStatus;
+    /** Monotonic change counter — bumps on any value or status change. */
+    revision(): number;
+    /** Capture the live state and mark it dirty; a caller-policy autosave schedules the write. */
+    touch(): GameSaveDocument;
+    /** One hash over every section, the clock and the RNG cursor — what a determinism test compares. */
+    digest(): string;
+    /** Per-system section hashes, so a caller can see which systems the digest covers. */
+    digests(): Record<string, string>;
+    subscribe(listener: () => void): () => void;
+    dispose(): void;
+}
+/**
+ * A stable hash over the state-bearing part of a document — every system section, the world clock
+ * and the shared RNG cursor — excluding the wall-clock `savedAt`, which is not state.
+ *
+ * @capability game-save-digest hash a save document's state for a determinism test or a diff
+ */
+export declare function gameSaveDigest(document: GameSaveDocument): string;
+/**
+ * Create a {@link GameSave}. Register every stateful system once; `capture()` writes one versioned
+ * document with a section per system, `save()`/`touch()` persist it through the injected backend
+ * (autosave cadence is the caller's), `load()` restores every section and the shared RNG cursor, and
+ * `digest()`/`digests()` give a determinism test a hash over the whole state.
+ *
+ * @capability game-save one versioned save document with per-system sections, named slots, caller-policy autosave, migration and a state digest
+ */
+export declare function createGameSave(config: GameSaveConfig): GameSave;

package/dist/game/gameSave.js

@@ -0,0 +1,174 @@
+import { devtools } from "../devtools/devtools.js";
+import { hashString, restoreRng, rngStateOf } from "../random/rng.js";
+import { createSaveStore, } from "./saveStore.js";
+/** Current save-format version of {@link GameSaveDocument}. Bump it with {@link GameSaveConfig.migrate} when the shape changes. */
+export const GAME_SAVE_VERSION = 1;
+function stableStringify(value) {
+    if (value === null || value === undefined)
+        return "null";
+    const type = typeof value;
+    if (type === "number")
+        return Number.isFinite(value) ? JSON.stringify(value) : "null";
+    if (type === "boolean" || type === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    if (type === "object") {
+        const record = value;
+        const keys = Object.keys(record).filter((key) => record[key] !== undefined).sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
+    }
+    return "null";
+}
+function digestOf(value) {
+    return hashString(stableStringify(value)).toString(36);
+}
+/**
+ * A stable hash over the state-bearing part of a document — every system section, the world clock
+ * and the shared RNG cursor — excluding the wall-clock `savedAt`, which is not state.
+ *
+ * @capability game-save-digest hash a save document's state for a determinism test or a diff
+ */
+export function gameSaveDigest(document) {
+    return digestOf({
+        version: document.version,
+        game: document.game,
+        time: document.time,
+        playtime: document.playtime,
+        rng: document.rng,
+        systems: document.systems,
+    });
+}
+function emptyDocument(config, version) {
+    return {
+        version,
+        game: config.game,
+        savedAt: (config.now ?? Date.now)(),
+        time: config.clock?.() ?? 0,
+        playtime: config.playtime?.() ?? 0,
+        rng: null,
+        systems: {},
+    };
+}
+/**
+ * Create a {@link GameSave}. Register every stateful system once; `capture()` writes one versioned
+ * document with a section per system, `save()`/`touch()` persist it through the injected backend
+ * (autosave cadence is the caller's), `load()` restores every section and the shared RNG cursor, and
+ * `digest()`/`digests()` give a determinism test a hash over the whole state.
+ *
+ * @capability game-save one versioned save document with per-system sections, named slots, caller-policy autosave, migration and a state digest
+ */
+export function createGameSave(config) {
+    const version = config.version ?? GAME_SAVE_VERSION;
+    const systems = new Map();
+    function add(system) {
+        if (systems.has(system.name))
+            throw new Error(`game-save: system "${system.name}" is already registered`);
+        systems.set(system.name, system);
+    }
+    for (const system of config.systems ?? [])
+        add(system);
+    function capture() {
+        const sections = {};
+        for (const [name, system] of systems)
+            sections[name] = system.snapshot();
+        return {
+            version,
+            game: config.game,
+            savedAt: (config.now ?? Date.now)(),
+            time: config.clock?.() ?? 0,
+            playtime: config.playtime?.() ?? 0,
+            rng: config.rng === undefined
+                ? null
+                : { seed: config.rng.seed, cursor: rngStateOf(config.rng.stream) },
+            systems: sections,
+        };
+    }
+    function apply(document) {
+        const sections = document.systems ?? {};
+        for (const [name, system] of systems) {
+            if (Object.hasOwn(sections, name))
+                system.restore(sections[name]);
+            else
+                system.reset?.();
+        }
+        if (config.rng === undefined || document.rng === null)
+            return;
+        if (document.rng.seed !== config.rng.seed) {
+            config.onError?.(new Error(`game-save: document was written by world seed "${String(document.rng.seed)}", not "${String(config.rng.seed)}" — RNG cursor not restored`));
+            return;
+        }
+        if (document.rng.cursor !== null)
+            restoreRng(config.rng.stream, document.rng.cursor);
+    }
+    const store = createSaveStore({
+        backend: config.backend,
+        initial: emptyDocument(config, version),
+        key: config.key ?? `game-save:${config.game}`,
+        slot: config.slot,
+        version,
+        autosave: config.autosave,
+        now: config.now,
+        timers: config.timers,
+        onError: config.onError,
+        migrate: (data, fromVersion) => {
+            if (fromVersion === version)
+                return data;
+            if (config.migrate !== undefined)
+                return { ...config.migrate(data, fromVersion), version };
+            return { ...data, version };
+        },
+    });
+    const unregister = config.devtoolsName === undefined
+        ? null
+        : devtools.probes.register(config.devtoolsName, () => `${store.slot()} ${store.status()} rev ${store.revision()} ${systems.size} systems`);
+    return {
+        register(system) {
+            add(system);
+            return () => systems.delete(system.name);
+        },
+        capture,
+        async save() {
+            store.set(capture());
+            await store.save();
+        },
+        async load() {
+            const document = await store.load();
+            apply(document);
+            return document;
+        },
+        async switchSlot(slot) {
+            store.set(capture());
+            const document = await store.switchSlot(slot);
+            apply(document);
+            return document;
+        },
+        async peek(slot) {
+            const stored = await store.peek(slot);
+            if (stored === null)
+                return null;
+            return stored.value;
+        },
+        slots: () => store.slots(),
+        slot: () => store.slot(),
+        status: () => store.status(),
+        revision: () => store.revision(),
+        touch() {
+            const document = capture();
+            store.set(document);
+            return document;
+        },
+        digest: () => gameSaveDigest(capture()),
+        digests() {
+            const out = {};
+            for (const [name, system] of systems)
+                out[name] = digestOf(system.snapshot());
+            return out;
+        },
+        subscribe: (listener) => store.subscribe(listener),
+        dispose: () => {
+            unregister?.();
+            store.dispose();
+        },
+    };
+}

package/dist/game/playableGame.d.ts

@@ -48,7 +48,7 @@ export interface NoticePresentationConfig extends NoticeFeedConfig {
     /** Play a UI cue per new notice (deny → deny, success → confirm, else notify); a push with `silent: true` skips its own. Independent of the HUD control sounds (`audio.hudCues`). Default true. */
     cues?: boolean;
 }
-export type { CameraFollowState, CameraKeyframe, CameraProjection, CameraRigKind, CameraWeaponView, CameraShakeConfig, ChaseCameraConfig, ChaseView, CinematicCameraConfig, FirstPersonCameraConfig, GameCameraConfig, InspectionCameraConfig, InspectionZoomAnchor, LockOnCameraConfig, ObserverCameraConfig, PlayerFovConfig, RtsCameraConfig, ShoulderCameraConfig, SideScrollCameraConfig, TopDownCameraConfig, TurntableCameraConfig, } from "./cameraConfig.js";
+export type { CameraFollowState, CameraKeyframe, CameraProjection, CameraRigKind, CameraWeaponView, CameraShakeConfig, ChaseCameraConfig, ChaseView, CinematicCameraConfig, FirstPersonCameraConfig, FirstPersonCollisionConfig, GameCameraConfig, InspectionCameraConfig, InspectionZoomAnchor, LockOnCameraConfig, ObserverCameraConfig, PlayerFovConfig, RtsCameraConfig, ShoulderCameraConfig, SideScrollCameraConfig, TopDownCameraConfig, TurntableCameraConfig, } from "./cameraConfig.js";
 export { CAMERA_FRUSTUM_DEFAULTS } from "./cameraConfig.js";
 /**
  * Mouse/touch pointer bindings for `defineGame({ pointer })`.
@@ -132,6 +132,16 @@ export interface ModelAnimationStates {
     walk: string;
     /** Clip name above `runSpeed`; omit to keep `walk` at any speed. */
     run?: string;
+    /** Clip while moving to the character's left; with `strafeRight` adds the lateral strafe blend, driven by the `direction` parameter. */
+    strafeLeft?: string;
+    /** Clip while moving to the character's right; with `strafeLeft` adds the lateral strafe blend. */
+    strafeRight?: string;
+    /** Clip while moving backwards; adds the backward blend, driven by the `facing` parameter. */
+    backward?: string;
+    /** Clip while turning on the spot; omit to pivot on `walk`, driven by the `turnRate` parameter. */
+    turn?: string;
+    /** Play every locomotion state as root motion: the rig holds in place and the blended travel comes out as `rootDelta` for the movement owner to consume. */
+    rootMotion?: boolean;
     /** Speed (world units/sec) above which the entity counts as moving. Default 0.5. */
     walkSpeed?: number;
     /** Speed above which `run` plays when provided. Default 6. */
@@ -250,9 +260,15 @@ export interface ModelConfig {
     material?: ModelMaterialOverride;
     /** `false` keeps this model's exported material params and skips the engine's default painted surface detail. Default true. */
     surfaceDetail?: boolean;
+    /**
+     * Per-model wind sway for foliage: trunk and standing geometry stay planted while the upper
+     * canopy drifts in the shared gust field. `strength` is metres of tip travel, `speed` the gust
+     * rate, `height` the world height over which sway ramps in (defaults to the model's own height).
+     * `false` or omitted keeps the model rigid. Compiles into each cloned material.
+     */
+    wind?: ModelWindConfig | false;
     /** Reusable authored surfaces available to this model's named slot assignments. */
-    materialAssets?: readonly MaterialAsset[];
-    /** Sparse per-slot assignments; unselected imported materials keep their original appearance. */
+    materialAssets?: readonly MaterialAsset[]; /** Sparse per-slot assignments; unselected imported materials keep their original appearance. */
     materialAssignments?: readonly MaterialAssignment[];
     /** Hide named visual subtrees on this instance before placement measurement. Exact runtime names or unique original imported names resolve without removing bones or changing the cached model; missing or ambiguous names warn and leave existing visibility unchanged. Malformed lists reject before model or texture allocation. Omit or pass [] to retain imported visibility. */
     hiddenNodes?: readonly string[];
@@ -281,6 +297,38 @@ export interface ModelConfig {
     parts?: readonly ModelPart[];
     /** Tuning for the procedural part-motion driver when any part carries a `role`; omit for defaults. */
     partMotion?: PartMotionParams;
+    /**
+     * Distance tiers for a rigged character: how far away it still poses its skeleton every frame, and
+     * from where a far one renders through the GPU crowd path instead. `false` keeps this model at full
+     * rate everywhere, which is what a player avatar or a character in a cutscene wants. Omit for no
+     * distance tiers (full rate) — see {@link ModelLodConfig}.
+     */
+    lod?: ModelLodConfig | false;
+}
+/**
+ * Distance tiers for one character model. Distances are metres from the camera; every field is data
+ * so a game can set its own thresholds per model and retune them without touching the engine.
+ */
+export interface ModelLodConfig {
+    /** Within this distance the rig poses every frame. Default 15. */
+    fullRateDistance?: number;
+    /** Within this distance the rig poses every other frame, carrying the accumulated time. Default 40. */
+    halfRateDistance?: number;
+    /** Beyond this distance a crowd-eligible rig renders through the GPU crowd path and updates no bones. Default 25. */
+    crowdDistance?: number;
+    /** Metres a character must come back inside `crowdDistance` before it returns to its own rig, so the swap cannot flicker at the boundary. Default 2. */
+    crowdHysteresis?: number;
+}
+/** Wind sway for a foliage model; see {@link ModelConfig.wind}. */
+export interface ModelWindConfig {
+    /** Tip travel in metres. Default 0.35. */
+    strength?: number;
+    /** Gust rate multiplier. Default 1. */
+    speed?: number;
+    /** World height over which sway ramps from the base to full tip travel, in metres. Defaults to the model's measured height. */
+    height?: number;
+    /** Wind heading as a two-axis direction; defaults to the engine's shared gust direction. */
+    direction?: readonly [number, number];
 }
 /** Bone names and limits for {@link ModelConfig.ik}. */
 export interface ModelIkConfig {
@@ -296,10 +344,30 @@ export interface ModelIkConfig {
     maxAdjust?: number;
     /** Tilt planted feet to the ground normal, `0..1`. Default `1`. */
     alignToGround?: number;
-    /** Turns this bone toward the camera. */
-    lookAt?: {
-        bone: string;
+    /** Turns this bone toward a target. */
+    lookAt?: ModelLookAtConfig;
+}
+/** {@link ModelIkConfig.lookAt}: the bone that turns, and what it turns toward. */
+export interface ModelLookAtConfig {
+    /** Bone turned toward the target; the head on a humanoid rig. */
+    bone: string;
+    /**
+     * What the bone turns toward: the camera (default), another entity's position, or a fixed world
+     * point. An entity target that is not spawned this frame keeps the last known direction.
+     */
+    target?: "camera" | {
+        entity: string;
+    } | {
+        point: readonly [number, number, number];
     };
+    /** Height above an entity target's origin to aim at; the entity's eye level. Default 1.5. */
+    entityEyeHeight?: number;
+    /** Yaw limit in radians; the head stops turning past it. Omitted means unconstrained. */
+    maxYaw?: number;
+    /** Pitch limit in radians. Omitted means unconstrained. */
+    maxPitch?: number;
+    /** How much of the solved turn reaches the bone, `0..1`. Default `1`. */
+    weight?: number;
 }
 export interface ObjectStyle {
     color?: string;

package/dist/game/saveSlotIndex.d.ts

@@ -0,0 +1,54 @@
+import type { GameSave, GameSaveDocument } from "./gameSave.js";
+import type { SaveSlotMeta, SaveSlots } from "./saveSlots.js";
+/**
+ * Bridging the versioned save document (`createGameSave`) to the save-select index (`createSaveSlots`):
+ * the document already carries `savedAt`, `time` and `playtime`, so a menu built on the index can show
+ * real saves instead of hand-maintained metadata.
+ */
+/** How one document becomes a menu slot. */
+export interface SaveSlotMetaOptions {
+    /** Player-facing name for the slot. Defaults to the slot id. */
+    nameOf?: (slot: string, document: GameSaveDocument) => string;
+    /**
+     * Extra display chips, merged over the playtime chip. The game decides which document fields matter
+     * (`chapter`, `location`, `level`, …); the index never interprets meta keys.
+     */
+    metaOf?: (slot: string, document: GameSaveDocument) => Record<string, string | number>;
+}
+/** "4h 12m" / "12m" / "< 1m" — the playtime chip every save menu wants. */
+export declare function formatSavePlaytime(seconds: number): string;
+/**
+ * Project one save document onto the index's display metadata: name, last-saved time and a playtime
+ * chip (plus any caller `metaOf` fields). Pure, so a menu can build its list from documents a host
+ * fetched for it.
+ *
+ * @capability save-slot-meta project a save document onto save-select display metadata
+ */
+export declare function saveSlotMeta(slot: string, document: GameSaveDocument, options?: SaveSlotMetaOptions): SaveSlotMeta;
+/** The source a slot list is refreshed from — a `GameSave`, or a narrower reader. */
+export interface SaveSlotSource {
+    slots(): Promise<string[]>;
+    peek(slot: string): Promise<GameSaveDocument | null>;
+}
+/** The result of a refresh: what the menu should show now. */
+export interface SaveSlotsRefresh {
+    /** Written slots in the order the save store indexes them. */
+    saved: string[];
+    /** Slot metadata for every written slot. */
+    filled: SaveSlotMeta[];
+    /** Written slots the index could not hold (id not in it and the index is full). */
+    skipped: string[];
+}
+/**
+ * Read every written slot's document and write the display metadata into a `SaveSlots` index — the
+ * glue between B5.3's save document and a save-select menu. Slots the index already knows that have
+ * no document are cleared, so a deleted save stops showing a stale Continue.
+ *
+ * @capability save-slot-index refresh a save-select index from the game's save documents
+ */
+export declare function refreshSaveSlots(source: SaveSlotSource, model: SaveSlots, options?: SaveSlotMetaOptions): Promise<SaveSlotsRefresh>;
+/**
+ * Adapt a {@link GameSave} as a {@link SaveSlotSource}. Kept separate so a host can supply its own
+ * reader (a cloud endpoint listing saves) with the same shape.
+ */
+export declare function gameSaveSlotSource(save: GameSave): SaveSlotSource;

package/dist/game/saveSlotIndex.js

@@ -0,0 +1,71 @@
+/** "4h 12m" / "12m" / "< 1m" — the playtime chip every save menu wants. */
+export function formatSavePlaytime(seconds) {
+    const total = Math.max(0, Math.floor(seconds));
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    if (hours > 0)
+        return `${hours}h ${minutes}m`;
+    if (minutes > 0)
+        return `${minutes}m`;
+    return "< 1m";
+}
+/**
+ * Project one save document onto the index's display metadata: name, last-saved time and a playtime
+ * chip (plus any caller `metaOf` fields). Pure, so a menu can build its list from documents a host
+ * fetched for it.
+ *
+ * @capability save-slot-meta project a save document onto save-select display metadata
+ */
+export function saveSlotMeta(slot, document, options = {}) {
+    return {
+        id: slot,
+        name: options.nameOf?.(slot, document) ?? slot,
+        empty: false,
+        savedAt: document.savedAt,
+        meta: {
+            playtime: formatSavePlaytime(document.playtime),
+            ...options.metaOf?.(slot, document),
+        },
+    };
+}
+/**
+ * Read every written slot's document and write the display metadata into a `SaveSlots` index — the
+ * glue between B5.3's save document and a save-select menu. Slots the index already knows that have
+ * no document are cleared, so a deleted save stops showing a stale Continue.
+ *
+ * @capability save-slot-index refresh a save-select index from the game's save documents
+ */
+export async function refreshSaveSlots(source, model, options = {}) {
+    const saved = await source.slots();
+    const filled = [];
+    const skipped = [];
+    for (const slot of saved) {
+        const document = await source.peek(slot);
+        if (document === null)
+            continue;
+        const meta = saveSlotMeta(slot, document, options);
+        try {
+            model.write(slot, { name: meta.name, meta: meta.meta, savedAt: meta.savedAt });
+        }
+        catch {
+            skipped.push(slot);
+            continue;
+        }
+        filled.push(meta);
+    }
+    for (const existing of model.list()) {
+        if (!existing.empty && !filled.some((meta) => meta.id === existing.id))
+            model.clear(existing.id);
+    }
+    return { saved, filled, skipped };
+}
+/**
+ * Adapt a {@link GameSave} as a {@link SaveSlotSource}. Kept separate so a host can supply its own
+ * reader (a cloud endpoint listing saves) with the same shape.
+ */
+export function gameSaveSlotSource(save) {
+    return {
+        slots: () => save.slots(),
+        peek: (slot) => save.peek(slot),
+    };
+}

package/dist/game/saveSlots.d.ts

@@ -29,6 +29,8 @@ export interface SaveSlotWrite {
     name?: string;
     /** Replacement free-string display fields. Omit to keep the existing `meta`. */
     meta?: Record<string, string | number>;
+    /** The save's own write time (ms) when the payload knows it; omit to use the index's clock. */
+    savedAt?: number;
 }
 /** How a {@link createSaveSlots} index is wired. */
 export interface SaveSlotsConfig {

package/dist/game/saveSlots.js

@@ -72,7 +72,7 @@ export function createSaveSlots(config = {}) {
             }
             const slot = slots[i];
             slot.empty = false;
-            slot.savedAt = now();
+            slot.savedAt = write?.savedAt ?? now();
             if (write?.name !== undefined)
                 slot.name = write.name;
             if (write?.meta !== undefined)

package/dist/game/saveStore.d.ts

@@ -92,6 +92,14 @@ export interface SaveStore<T> {
     save(): Promise<void>;
     /** Delete the active slot and reset `value()` to `initial`. */
     clear(): Promise<void>;
+    /**
+     * Read a stored slot without touching the live value, active slot or status — what a save-select
+     * menu shows. Returns `null` when the slot holds nothing.
+     */
+    peek(slot?: string): Promise<{
+        value: T;
+        savedAt: number;
+    } | null>;
     /** Flush any dirty state, switch to `slot`, and load it. */
     switchSlot(slot: string): Promise<T>;
     /** The slots this store has written (for a load/save menu). */

package/dist/game/saveStore.js

@@ -289,6 +289,22 @@ export function createSaveStore(config) {
             firstDirtyAt = null;
             return load();
         },
+        async peek(slot = currentSlot) {
+            try {
+                const raw = await backend.read(dataKey(slot));
+                if (raw === null)
+                    return null;
+                const parsed = deserialize(raw);
+                if (isEnvelope(parsed)) {
+                    return { value: decode(raw), savedAt: typeof parsed.savedAt === "number" ? parsed.savedAt : 0 };
+                }
+                return { value: decode(raw), savedAt: 0 };
+            }
+            catch (error) {
+                reportError(error);
+                return null;
+            }
+        },
         async slots() {
             try {
                 return await readSlots();