@downdraft/engine 0.0.0 → 0.1.0

package/core/src/save/game-save-system.ts

@@ -0,0 +1,161 @@
+// ============================================================================
+// createGameSaveSystem — batteries-included save lifecycle facade.
+//
+// createGridSaveSystem covers the store CRUD; games still hand-rolled the
+// same lifecycle on top in main.tsx:
+//   - module-scope `let autosaveInterval` + setInterval(autosave, 3000)
+//   - loadAutosave()-on-start → renderer.loadSave(...) with try/catch
+//   - cleanup in onDispose
+//   - save/load/delete/list wrappers that snapshot via the renderer
+//
+// This facade ties the grid system + autosave interval + snapshot/restore
+// contract into one object. Games keep their schema mapping (buildState /
+// buildBlobs / parseEntry) — everything else is engine-owned.
+//
+// Usage:
+//   const saves = createGameSaveSystem({
+//     createStore: () => createDefaultSaveStore(ENGINE_VERSION),
+//     autosaveSlot: "autosave",
+//     buildState, buildBlobs, parseEntry, extractListMeta,
+//     snapshot: () => renderer.snapshotGrids(),
+//     restore: (e) => renderer.loadSave(e.grids, e.fields, e.gridW, e.gridH),
+//     deterministic: ctx.deterministic,
+//   });
+//   // in onReady:
+//   await saves.start();      // restores autosave, starts the interval
+//   // on hot-reload:
+//   saves.stop();
+// ============================================================================
+
+import { createLogger } from "../util/logger";
+import { createGridSaveSystem, type GridSaveSystem, type GridSaveSystemOptions } from "./grid-save-system";
+
+const log = createLogger();
+
+export interface GameSaveSystemOptions<Meta, Entry> extends GridSaveSystemOptions<Meta, Entry> {
+  /**
+   * Capture the current game state for an autosave tick. Return null to skip
+   * this tick (e.g. renderer not ready yet). May be async.
+   * Required to enable the autosave interval; without it, `start()` only
+   * restores the autosave.
+   */
+  snapshot?: () => Meta | null | Promise<Meta | null>;
+  /**
+   * Apply a loaded entry to the game (autosave restore + loadAndRestore).
+   * If omitted, `start()` still loads the autosave and reports whether one
+   * existed, and `loadAndRestore` returns the entry for the caller to apply.
+   */
+  restore?: (entry: Entry) => void | Promise<void>;
+  /** Autosave interval in ms. Default: 3000. */
+  intervalMs?: number;
+  /** Skip the autosave interval + autosave writes entirely (test mode). */
+  deterministic?: boolean;
+  /** Called on autosave errors. Default: logs a warning via the engine logger. */
+  onError?: (err: unknown) => void;
+  /**
+   * Post-process entries returned by `loadGame`/`loadAndRestore` with slot
+   * metadata — games whose `parseEntry` produces bare grid/state data use
+   * this to stamp the slot id, display name, savedAt timestamp, and JPEG
+   * thumbnail without re-fetching properties themselves (previously a ~15
+   * line copy-pasted `loadGame` wrapper in every game).
+   * Mutate `entry` in place or return a replacement.
+   */
+  enrichEntry?: (entry: Entry, meta: {
+    id: string;
+    props: Record<string, unknown>;
+    thumbnail: Blob | null;
+  }) => Entry | void | Promise<Entry | void>;
+}
+
+export interface GameSaveSystem<Meta, Entry> extends GridSaveSystem<Meta, Entry> {
+  /**
+   * Restore the autosave (via `restore`, if provided), then start the
+   * autosave interval (when `snapshot` is provided and not deterministic).
+   * Returns the restored entry, or null when no autosave exists.
+   */
+  start(): Promise<Entry | null>;
+  /** Stop the autosave interval. */
+  stop(): void;
+  /** Whether the autosave interval is running. */
+  readonly running: boolean;
+  /**
+   * Load a named save and apply it via `restore`. Returns the entry (already
+   * applied), or null when the slot is missing/invalid.
+   */
+  loadAndRestore(id: string): Promise<Entry | null>;
+}
+
+export function createGameSaveSystem<Meta, Entry>(
+  opts: GameSaveSystemOptions<Meta, Entry>,
+): GameSaveSystem<Meta, Entry> {
+  const system: GridSaveSystem<Meta, Entry> = createGridSaveSystem(opts);
+  const intervalMs = opts.intervalMs ?? 3000;
+  const onError = opts.onError ?? ((e) => log.warn("save", `autosave failed: ${e}`));
+  let interval: ReturnType<typeof setInterval> | null = null;
+
+  const maybeEnrich = async (id: string, entry: Entry | null): Promise<Entry | null> => {
+    if (entry === null || !opts.enrichEntry) return entry;
+    const store = await system.getStore();
+    const [thumbBuf, props] = await Promise.all([
+      store.getThumbnail(id),
+      store.getProperties(id),
+    ]);
+    const meta = {
+      id,
+      props,
+      thumbnail: thumbBuf ? new Blob([thumbBuf], { type: "image/jpeg" }) : null,
+    };
+    return (await opts.enrichEntry(entry, meta)) ?? entry;
+  };
+
+  const tick = async () => {
+    try {
+      const meta = await opts.snapshot?.();
+      if (meta !== null && meta !== undefined) await system.autosave(meta);
+    } catch (e) {
+      onError(e);
+    }
+  };
+
+  return {
+    ...system,
+
+    async start(): Promise<Entry | null> {
+      let restored: Entry | null = null;
+      if (!opts.deterministic) {
+        try {
+          restored = await system.loadAutosave();
+          if (restored !== null) await opts.restore?.(restored);
+        } catch (e) {
+          // No autosave / corrupt autosave is normal on first run.
+          onError(e);
+        }
+        if (opts.snapshot && !interval) {
+          interval = setInterval(() => { void tick(); }, intervalMs);
+        }
+      }
+      return restored;
+    },
+
+    stop(): void {
+      if (interval) {
+        clearInterval(interval);
+        interval = null;
+      }
+    },
+
+    get running(): boolean {
+      return interval !== null;
+    },
+
+    async loadGame(id: string): Promise<Entry | null> {
+      return maybeEnrich(id, await system.loadGame(id));
+    },
+
+    async loadAndRestore(id: string): Promise<Entry | null> {
+      const entry = await maybeEnrich(id, await system.loadGame(id));
+      if (entry !== null) await opts.restore?.(entry);
+      return entry;
+    },
+  };
+}

package/core/src/save/grid-save-system.ts

@@ -0,0 +1,158 @@
+// ============================================================================
+// createGridSaveSystem — generic save-system factory for grid-based games.
+//
+// Eliminates the duplicated getStore() singleton + save/load/list/delete/
+// autosave/loadAutosave boilerplate that was copy-pasted across grid-based games.
+//
+// The factory owns:
+//   - Lazy ISaveStore singleton (via the game-provided createStore function)
+//   - saveGame: named slot + thumbnail + properties
+//   - loadGame: parse state + blobs into game-specific entry
+//   - listSaves: list all slots except autosave, with thumbnails
+//   - deleteSave: delete a named slot
+//   - autosave: save to the autosave slot
+//   - loadAutosave: load from the autosave slot
+//
+// Games provide:
+//   - createStore: () => Promise<ISaveStore> (typically createDefaultSaveStore)
+//   - autosaveSlot: string ("autosave", "world", etc.)
+//   - buildState: (meta) => SaveState
+//   - buildBlobs: (meta) => Record<string, ArrayBuffer>
+//   - parseEntry: (state, blobs) => Entry | null
+//   - extractListMeta?: (state) => Record<string, unknown> (for listSaves extra fields)
+// ============================================================================
+
+import type { ISaveStore, SaveState } from "./persist-types";
+
+export interface SaveListEntry {
+  id: string;
+  name: string;
+  timestamp: number;
+  thumbnailUrl: string;
+  [key: string]: unknown;
+}
+
+export interface GridSaveSystemOptions<Meta, Entry> {
+  /** Creates the ISaveStore singleton (game provides this, typically createDefaultSaveStore). */
+  createStore: () => Promise<ISaveStore>;
+  /** Slot name for autosave (e.g. "autosave", "world"). */
+  autosaveSlot: string;
+  /** Build SaveState from game meta. */
+  buildState: (meta: Meta) => SaveState;
+  /** Build blobs record from game meta (typed arrays → ArrayBuffers). */
+  buildBlobs: (meta: Meta) => Record<string, ArrayBuffer>;
+  /** Parse a loaded SaveState + blobs into a game-specific entry. Return null if invalid. */
+  parseEntry: (state: SaveState, blobs: Record<string, ArrayBuffer> | null) => Entry | null;
+  /**
+   * Extract list metadata from a loaded state for listSaves().
+   * If not provided, listSaves() returns only id/name/timestamp/thumbnailUrl.
+   */
+  extractListMeta?: (state: SaveState) => Record<string, unknown>;
+}
+
+export interface GridSaveSystem<Meta, Entry> {
+  /** Save to a named slot with thumbnail. Returns the generated id + timestamp. */
+  saveGame(name: string, thumbnail: ArrayBuffer | null, meta: Meta): Promise<{ id: string; timestamp: number }>;
+  /** Load from a named slot. Returns null if no save or invalid. */
+  loadGame(id: string): Promise<Entry | null>;
+  /** List all saves (excluding the autosave slot). */
+  listSaves(): Promise<SaveListEntry[]>;
+  /** Delete a save slot. */
+  deleteSave(id: string): Promise<void>;
+  /** Save to the autosave slot. */
+  autosave(meta: Meta): Promise<void>;
+  /** Load from the autosave slot. */
+  loadAutosave(): Promise<Entry | null>;
+  /** Get the underlying ISaveStore (for advanced use). */
+  getStore(): Promise<ISaveStore>;
+}
+
+export function createGridSaveSystem<Meta, Entry>(
+  opts: GridSaveSystemOptions<Meta, Entry>,
+): GridSaveSystem<Meta, Entry> {
+  let storePromise: Promise<ISaveStore> | null = null;
+
+  function getStore(): Promise<ISaveStore> {
+    if (!storePromise) {
+      storePromise = opts.createStore();
+    }
+    return storePromise;
+  }
+
+  return {
+    async saveGame(name: string, thumbnail: ArrayBuffer | null, meta: Meta): Promise<{ id: string; timestamp: number }> {
+      const store = await getStore();
+      const id = `save-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      const state = opts.buildState(meta);
+      await store.save(id, state, {
+        thumbnail: thumbnail ? new Uint8Array(thumbnail) : undefined,
+        properties: { name, savedAt: Date.now() },
+        blobs: opts.buildBlobs(meta),
+      });
+      return { id, timestamp: Date.now() };
+    },
+
+    async loadGame(id: string): Promise<Entry | null> {
+      const store = await getStore();
+      const result = await store.load(id);
+      if (!result.state) return null;
+      return opts.parseEntry(result.state, result.blobs ?? null);
+    },
+
+    async listSaves(): Promise<SaveListEntry[]> {
+      const store = await getStore();
+      const slots = await store.listSaves();
+      return Promise.all(
+        slots
+          .filter((s) => s.slot !== opts.autosaveSlot)
+          .map(async (s) => {
+            const thumbBuf = await store.getThumbnail(s.slot);
+            const thumbnailUrl = thumbBuf
+              ? URL.createObjectURL(new Blob([thumbBuf], { type: "image/jpeg" }))
+              : "";
+            const props = await store.getProperties(s.slot);
+            const base: SaveListEntry = {
+              id: s.slot,
+              name: (props.name as string) ?? "Save",
+              timestamp: (props.savedAt as number) ?? s.timestamp * 1000,
+              thumbnailUrl,
+            };
+            // Merge game-specific list metadata if the game provided the callback.
+            if (opts.extractListMeta) {
+              // Load the state to extract list metadata (e.g. gridW, gridH).
+              // This is a lightweight load — the state header is small.
+              const result = await store.load(s.slot, { includeBlobs: false });
+              if (result.state) {
+                const extra = opts.extractListMeta(result.state);
+                Object.assign(base, extra);
+              }
+            }
+            return base;
+          }),
+      );
+    },
+
+    async deleteSave(id: string): Promise<void> {
+      const store = await getStore();
+      await store.deleteSave(id);
+    },
+
+    async autosave(meta: Meta): Promise<void> {
+      const store = await getStore();
+      const state = opts.buildState(meta);
+      await store.save(opts.autosaveSlot, state, {
+        properties: { name: "Autosave", savedAt: Date.now() },
+        blobs: opts.buildBlobs(meta),
+      });
+    },
+
+    async loadAutosave(): Promise<Entry | null> {
+      const store = await getStore();
+      const result = await store.load(opts.autosaveSlot);
+      if (!result.state) return null;
+      return opts.parseEntry(result.state, result.blobs ?? null);
+    },
+
+    getStore,
+  };
+}

package/core/src/save/migrate.ts

@@ -0,0 +1,44 @@
+import type { World } from "../ecs/world";
+import { SchemaRegistry } from "./schema";
+import { Serializer, type SaveData } from "./serializer";
+
+export class SaveSystem {
+  private serializer: Serializer;
+  private schemaRegistry: SchemaRegistry;
+
+  constructor() {
+    this.serializer = new Serializer();
+    this.schemaRegistry = new SchemaRegistry();
+  }
+
+  getSchemaRegistry(): SchemaRegistry {
+    return this.schemaRegistry;
+  }
+
+  save(world: World, sceneName: string): SaveData {
+    return this.serializer.serialize(world, sceneName);
+  }
+
+  load(data: SaveData, world: World): void {
+    this.serializer.deserialize(data, world, this.schemaRegistry);
+  }
+
+  async saveToFile(world: World, sceneName: string, path: string): Promise<number> {
+    const data = this.save(world, sceneName);
+    const json = this.serializer.toJSON(data);
+    // Lazy node:fs import — this module is reachable from the browser-side
+    // barrel, so node builtins must not be evaluated at import time.
+    await (await import("node:fs")).promises.writeFile(path, json);
+    return json.length;
+  }
+
+  async loadFromFile(path: string, world: World): Promise<void> {
+    const json = await (await import("node:fs")).promises.readFile(path, "utf-8");
+    const data = this.serializer.fromJSON(json);
+    this.load(data, world);
+  }
+
+  registerMigration(fromVersion: number, fn: (data: unknown) => unknown): void {
+    this.schemaRegistry.registerMigration(fromVersion, fn);
+  }
+}

package/core/src/save/migration-registry.ts

@@ -0,0 +1,94 @@
+// ============================================================================
+// Migration Registry — per-component schema versioning with chain walking
+// ============================================================================
+
+import { createLogger } from "../util/logger";
+import type { ComponentMigration, IMigrationRegistry } from "./persist-types";
+
+const log = createLogger();
+
+interface ComponentEntry {
+  currentVersion: number;
+  migrations: Map<number, ComponentMigration>; // keyed by fromVersion
+}
+
+export class MigrationRegistryImpl implements IMigrationRegistry {
+  private components: Map<string, ComponentEntry> = new Map();
+
+  setCurrentVersion(component: string, version: number): void {
+    let entry = this.components.get(component);
+    if (!entry) {
+      entry = { currentVersion: version, migrations: new Map() };
+      this.components.set(component, entry);
+    } else {
+      entry.currentVersion = version;
+    }
+  }
+
+  getLatestVersion(component: string): number {
+    return this.components.get(component)?.currentVersion ?? 1;
+  }
+
+  register(component: string, migration: ComponentMigration): void {
+    let entry = this.components.get(component);
+    if (!entry) {
+      entry = { currentVersion: migration.toVersion, migrations: new Map() };
+      this.components.set(component, entry);
+    }
+    if (migration.toVersion > entry.currentVersion) {
+      entry.currentVersion = migration.toVersion;
+    }
+    entry.migrations.set(migration.fromVersion, migration);
+  }
+
+  migrate(
+    component: string,
+    data: unknown,
+    fromVersion: number,
+  ): { data: unknown; version: number } | null {
+    const entry = this.components.get(component);
+    if (!entry) {
+      if (fromVersion === 1) return { data, version: 1 };
+      log.warn("MigrationRegistry", `Unknown component "${component}" with version ${fromVersion}`);
+      return null;
+    }
+
+    if (fromVersion === entry.currentVersion) {
+      return { data, version: entry.currentVersion };
+    }
+
+    if (fromVersion > entry.currentVersion) {
+      log.warn(
+        "MigrationRegistry",
+        `Component "${component}" save version ${fromVersion} > current ${entry.currentVersion} — forward incompatible`,
+      );
+      return null;
+    }
+
+    let current = data;
+    let version = fromVersion;
+
+    while (version < entry.currentVersion) {
+      const step = entry.migrations.get(version);
+      if (!step) {
+        log.warn(
+          "MigrationRegistry",
+          `Missing migration for "${component}" v${version}→v${version + 1} — marking as abandoned`,
+        );
+        return null;
+      }
+      try {
+        current = step.migrate(current);
+        version = step.toVersion;
+      } catch (e) {
+        log.warn(
+          "MigrationRegistry",
+          `Migration failed for "${component}" v${version}→v${step.toVersion}: ${e}`,
+        );
+        return null;
+      }
+    }
+
+    return { data: current, version: entry.currentVersion };
+  }
+}

package/core/src/save/persist-types.ts

@@ -0,0 +1,208 @@
+// ============================================================================
+// Persistence Types — interfaces for the versioned save/load system
+// ============================================================================
+
+// --- Component Section ---
+// Each top-level key in a save body is a component section with its own
+// schema version and data payload.
+
+export interface ComponentSection {
+  /** Schema version of this component's data */
+  v: number;
+  /** The component data payload */
+  data: unknown;
+}
+
+// --- Save State ---
+// The structured payload that gets serialized to the binary save format.
+// Games populate this via ISimulation.serializeState() + IRendererStateProvider.
+
+export interface SaveState {
+  /** Per-component sections, each with its own schema version */
+  components: Record<string, ComponentSection>;
+  /** Metadata for the save header */
+  meta: SaveMeta;
+}
+
+export interface SaveMeta {
+  /** Engine/game semver that produced this save */
+  engineVersion: string;
+  /** Unix epoch seconds */
+  timestamp: number;
+  /** Number of entities in the save */
+  entityCount: number;
+  /** Number of players in the save */
+  playerCount: number;
+}
+
+// --- Save File Info (from header/meta only, no decompression needed) ---
+
+export interface SaveSlotInfo {
+  slot: string;
+  timestamp: number;
+  entityCount: number;
+  playerCount: number;
+  engineVersion: string;
+  /** File size in bytes (total across all generations for OPFS, single file for FileSaveStore) */
+  fileSize: number;
+  /** Current generation number (OPFS stores; 1 for FileSaveStore) */
+  currentGen: number;
+  /** Number of available generations (OPFS stores; 1 for FileSaveStore) */
+  generationCount: number;
+  /** Whether a thumbnail is stored for this slot */
+  hasThumbnail: boolean;
+  /** Slot-level properties (game mode, playtime, world name, etc.) */
+  properties?: Record<string, unknown>;
+}
+
+// --- Generation Info ---
+// Describes a single snapshot within a slot's generation history.
+
+export interface SaveGenerationInfo {
+  gen: number;
+  timestamp: number;
+  engineVersion: string;
+  entityCount: number;
+  playerCount: number;
+  /** Compressed body size in bytes */
+  bodySize: number;
+  /** Number of binary blobs stored with this generation */
+  blobCount: number;
+}
+
+// --- Save Options ---
+// Passed to ISaveStore.save() to control generation retention and attach
+// thumbnails, properties, and binary blobs.
+
+export interface SaveOptions {
+  /** Max generations to retain per slot. Older gens are pruned. Default: 3. */
+  maxGenerations?: number;
+  /** Thumbnail image data (PNG/WebP bytes). Stored as a separate file. */
+  thumbnail?: ArrayBuffer | Uint8Array;
+  /** Arbitrary slot-level properties (game mode, playtime, world name, etc.) */
+  properties?: Record<string, unknown>;
+  /** Binary blobs from the serializer (typed arrays keyed by blobRef). */
+  blobs?: Record<string, ArrayBuffer>;
+}
+
+// --- Load Options ---
+
+export interface LoadOptions {
+  /** Load a specific generation instead of current. Default: current. */
+  gen?: number;
+  /** Whether to include binary blobs in the result. Default: true. */
+  includeBlobs?: boolean;
+}
+
+// --- Save Result ---
+
+export interface SaveResult {
+  success: boolean;
+  bytes: number;
+  /** Generation number that was written */
+  gen?: number;
+  warning?: SaveWarning;
+}
+
+// --- Warnings ---
+
+export type SaveWarningKind =
+  | "corruption"
+  | "migration_failed"
+  | "forward_incompatible"
+  | "backup_loaded"
+  | "no_saves_found"
+  | "abandoned_data";
+
+export interface SaveWarning {
+  kind: SaveWarningKind;
+  slot: string;
+  message: string;
+  /** Component that failed migration, if applicable */
+  component?: string;
+  /** Abandoned data that could not be migrated (read-only) */
+  abandonedData?: unknown;
+}
+
+// --- Load Result ---
+
+export interface LoadResult {
+  state: SaveState | null;
+  /** Binary blobs keyed by blobRef (only present if includeBlobs was true) */
+  blobs?: Record<string, ArrayBuffer>;
+  /** Generation number that was loaded */
+  gen?: number;
+  warning?: SaveWarning;
+}
+
+// --- Migration System ---
+
+export interface ComponentMigration {
+  fromVersion: number;
+  toVersion: number;
+  migrate(data: unknown): unknown;
+}
+
+export interface IMigrationRegistry {
+  register(component: string, migration: ComponentMigration): void;
+  /**
+   * Migrate a component's data from its saved version to the current version.
+   * Returns the migrated data and final version, or null if migration is
+   * impossible (missing step in the chain).
+   */
+  migrate(
+    component: string,
+    data: unknown,
+    fromVersion: number,
+  ): { data: unknown; version: number } | null;
+  /** Get the latest registered version for a component */
+  getLatestVersion(component: string): number;
+  /** Register the current version for a component (used as migration target) */
+  setCurrentVersion(component: string, version: number): void;
+}
+
+// --- Save Store Interface ---
+// The unified interface for all save backends (OPFS, File, host bridge).
+// save() and load() accept optional options for generation control, blobs,
+// thumbnails, and properties. Backends that don't support a feature degrade
+// gracefully (e.g. FileSaveStore returns generationCount: 1).
+
+export interface ISaveStore {
+  save(slot: string, state: SaveState, opts?: SaveOptions): Promise<SaveResult>;
+  load(slot: string, opts?: LoadOptions): Promise<LoadResult>;
+  listSaves(): Promise<SaveSlotInfo[]>;
+  /** List all generations for a slot (newest first). */
+  listGenerations(slot: string): Promise<SaveGenerationInfo[]>;
+  deleteSave(slot: string): Promise<boolean>;
+  /** Delete a specific generation from a slot. Returns false if not supported. */
+  deleteGeneration(slot: string, gen: number): Promise<boolean>;
+  /** Set the thumbnail image for a slot (PNG/WebP bytes). */
+  setThumbnail(slot: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+  /** Get the thumbnail image for a slot, or null if none. */
+  getThumbnail(slot: string): Promise<ArrayBuffer | null>;
+  /** Set slot-level properties (merged with existing). */
+  setProperties(slot: string, props: Record<string, unknown>): Promise<void>;
+  /** Get slot-level properties, or empty object if none. */
+  getProperties(slot: string): Promise<Record<string, unknown>>;
+  onWarning(cb: (warning: SaveWarning) => void): () => void;
+}
+
+// --- Renderer State Provider ---
+// Games implement this to provide lightweight renderer metadata for saves.
+
+export interface IRendererStateProvider {
+  serializeRendererMeta(): Record<string, unknown>;
+  restoreRendererMeta(meta: Record<string, unknown>): void;
+}
+
+// --- Save State Builder ---
+// Helper for games to construct a SaveState from sim + renderer state.
+
+export interface SaveStateBuilder {
+  /** Set a component section with its schema version */
+  setComponent(name: string, version: number, data: unknown): void;
+  /** Set metadata */
+  setMeta(meta: SaveMeta): void;
+  /** Build the final SaveState */
+  build(): SaveState;
+}