@downdraft/engine 0.0.0 → 0.1.1

package/app/src/renderer/mcp-harness.ts

@@ -0,0 +1,144 @@
+// ============================================================================
+// createMcpHarness() — factory for renderer-side MCP automation harnesses.
+//
+// Centralizes the MCP request-handling boilerplate shared by games
+// that have MCP automation:
+//   - initialize / tools/list / tools/call / shutdown method dispatch
+//   - downdraft.onMcpRequest wiring
+//   - Error handling + logging
+//
+// Games provide only their tool definitions + handlers.
+// ============================================================================
+
+import { createLogger } from "@downdraft/engine/util/logger";
+import type { McpRequest, McpResponse } from "../shared/types";
+import { downdraft } from "./index";
+
+const log = createLogger();
+
+export interface McpToolDef {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export interface McpToolRegistration {
+  def: McpToolDef;
+  handler: (params: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+
+export type { McpRequest, McpResponse } from "../shared/types";
+
+export interface McpHarnessOptions {
+  /** Server name reported in the initialize response. */
+  serverName: string;
+  /** Server version reported in the initialize response. */
+  serverVersion?: string;
+  /** Tool definitions + handlers. */
+  tools: McpToolRegistration[];
+}
+
+/**
+ * Create and register an MCP automation harness.
+ *
+ * Wires `downdraft.onMcpRequest` to handle the standard MCP protocol
+ * (initialize, tools/list, tools/call, shutdown) and dispatches tool calls
+ * to the provided handlers.
+ *
+ * If no host bridge is installed (e.g. running standalone in a browser),
+ * this is a no-op.
+ *
+ * @example
+ * createMcpHarness({
+ *   serverName: "downdraft-mygame-automation",
+ *   tools: [
+ *     {
+ *       def: { name: "capture_screenshot", description: "...", inputSchema: {...} },
+ *       handler: async (params) => { ... },
+ *     },
+ *   ],
+ * });
+ */
+export function createMcpHarness(opts: McpHarnessOptions): void {
+  const { serverName, serverVersion = "0.1.0", tools } = opts;
+
+  const handleRequest = async (req: McpRequest): Promise<McpResponse> => {
+    const { id, method, params = {} } = req;
+    try {
+      if (method === "initialize") {
+        return {
+          id,
+          result: {
+            protocolVersion: "2024-11-05",
+            capabilities: { tools: {}, resources: {}, prompts: {} },
+            serverInfo: { name: serverName, version: serverVersion },
+          },
+        };
+      }
+      if (method === "tools/list") {
+        return {
+          id,
+          result: {
+            tools: tools.map((t) => ({
+              name: t.def.name,
+              description: t.def.description,
+              inputSchema: t.def.inputSchema,
+            })),
+          },
+        };
+      }
+      if (method === "tools/call") {
+        const name = params.name as string;
+        const args = (params.arguments as Record<string, unknown>) ?? {};
+        const tool = tools.find((t) => t.def.name === name);
+        if (!tool) {
+          return { id, error: { code: -32602, message: `Unknown tool: ${name}` } };
+        }
+        const result = await tool.handler(args);
+        return { id, result: result as unknown };
+      }
+      if (method === "shutdown") {
+        return { id, result: {} };
+      }
+      return { id, error: { code: -32601, message: `Method not found: ${method}` } };
+    } catch (e) {
+      return { id, error: { code: -32603, message: (e as Error).message } };
+    }
+  };
+
+  if (!downdraft?.isAvailable || typeof downdraft.onMcpRequest !== "function") {
+    log.warn("MCP", "Host bridge or onMcpRequest not available; automation harness disabled");
+    return;
+  }
+
+  downdraft.onMcpRequest(async (request) => handleRequest(request as McpRequest));
+  log.info("MCP", `${serverName} registered; tools: ${tools.map((t) => t.def.name).join(", ")}`);
+}
+
+// ── Shared MCP tool helpers ──────────────────────────────────────────────────
+// These utilities are used by multiple games' MCP automation harnesses.
+// Games import them instead of duplicating the implementation.
+
+/** Convert a Blob to a base64 string (without the data: prefix). */
+export function blobToBase64(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onloadend = () => {
+      const result = reader.result as string;
+      const base64 = result.split(",")[1];
+      resolve(base64 ?? "");
+    };
+    reader.onerror = reject;
+    reader.readAsDataURL(blob);
+  });
+}
+
+/** MCP result helper: wrap data as a JSON content array. */
+export function jsonResult(data: unknown): { content: Array<{ type: string; text: string }> } {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+
+/** MCP result helper: wrap an error message. */
+export function errorResult(message: string): { content: Array<{ type: string; text: string }> } {
+  return { content: [{ type: "text", text: JSON.stringify({ error: message }, null, 2) }] };
+}

package/app/src/renderer/save-store-factory.ts

@@ -0,0 +1,239 @@
+// ============================================================================
+// Save Store Factory — creates the appropriate ISaveStore based on
+// environment capabilities and game configuration.
+// ============================================================================
+//
+// Mode selection:
+//   "inline"  — OpfsSaveStore runs inside the sim worker (caller is responsible
+//               for creating it there). The factory returns null here; the
+//               sim worker creates the store directly.
+//   "worker"  — Spawns a dedicated save Web Worker with OpfsSaveStore inside.
+//               Returns a SaveWorkerProxy. (Browser builds only — the native
+//               host has no OPFS.)
+//   "host"    — The host's own save store (`downdraft.saveStore`). On native
+//               this is HostSaveStore over HostServices → FileSaveStore: real
+//               SaveState in, real SaveResult/LoadResult out, no JSON
+//               boundary. The default when a host bridge is installed.
+//   "auto"    — Picks "host" when the host exposes a typed save store, else
+//               "worker" if OPFS is available. (On native there is no OPFS
+//               and no process boundary, so no fallback flip can produce a
+//               divergent save location.)
+//
+// The factory is called from the renderer after the sim worker is initialized.
+
+import type { ISaveStore, LoadOptions, LoadResult, SaveGenerationInfo, SaveOptions, SaveResult, SaveSlotInfo, SaveState, SaveWarning } from "@downdraft/engine";
+import { OpfsSaveStore, SaveWorkerProxy, type OpfsSaveStoreOptions } from "@downdraft/engine/libraries/persistence/browser";
+
+export type SaveStoreMode = "inline" | "worker" | "host" | "auto";
+
+/**
+ * The subset of the host bridge needed for save operations. `saveStore` is
+ * the typed native path; the `saveGameState`/`loadGameState` JSON-string
+ * methods are the last-resort generic fallback.
+ */
+export interface SaveBridge {
+  saveStore?: ISaveStore;
+  saveGameState(slotName: string, stateJson: string, opts?: SaveOptions): Promise<boolean>;
+  loadGameState(slotName: string, opts?: unknown): Promise<string | null>;
+  listSaveSlots(): Promise<SaveSlotInfo[]>;
+  deleteGameState(slotName: string): Promise<boolean>;
+  listSaveGenerations?(slotName: string): Promise<SaveGenerationInfo[]>;
+  deleteSaveGeneration?(slotName: string, gen: number): Promise<boolean>;
+  setThumbnail?(slotName: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+  getThumbnail?(slotName: string): Promise<ArrayBuffer | null>;
+  setSaveProperties?(slotName: string, props: Record<string, unknown>): Promise<void>;
+  getSaveProperties?(slotName: string): Promise<Record<string, unknown>>;
+}
+
+export interface CreateSaveStoreOptions {
+  /** Mode selection. Default: "auto". */
+  mode?: SaveStoreMode;
+  /** Options for the OpfsSaveStore (used in inline and worker modes). */
+  opfsOptions: OpfsSaveStoreOptions;
+  /** The host bridge. Required for "host" mode; preferred in "auto". */
+  bridge?: SaveBridge | null;
+  /** Worker URL for dedicated worker mode. Defaults to the library's save-worker.ts. */
+  workerUrl?: URL;
+}
+
+/** Result of createSaveStore: the store (null in "inline" mode) + the mode that
+ *  was actually resolved. Callers should use `mode` to label their save mode
+ *  rather than guessing from the store type. */
+export interface CreateSaveStoreResult {
+  store: ISaveStore | null;
+  mode: SaveStoreMode;
+}
+
+/**
+ * Check if OPFS is available in the current environment.
+ */
+export function isOpfsAvailable(): boolean {
+  const nav = globalThis as unknown as { navigator?: { storage?: { getDirectory?: unknown } } };
+  return typeof nav.navigator?.storage?.getDirectory === "function";
+}
+
+/**
+ * Create the appropriate ISaveStore based on the mode and environment.
+ *
+ * - "inline": Returns null. The caller should create an OpfsSaveStore inside
+ *   the sim worker directly (the worker has the serialized state and can
+ *   write to OPFS without crossing worker boundaries).
+ * - "worker": Spawns a dedicated save worker with OpfsSaveStore. Returns
+ *   a SaveWorkerProxy. The caller must call init() on it.
+ * - "host": Returns the host's save store (native HostSaveStore →
+ *   FileSaveStore on disk). Stable across sessions; not origin-scoped.
+ * - "auto": Picks "host" when the bridge exposes a typed save store, else
+ *   "worker" when OPFS is available.
+ *
+ * Returns `{ store, mode }` where `mode` is the backend that was actually
+ * selected (which may differ from the requested mode in "auto" fallback).
+ */
+export async function createSaveStore(opts: CreateSaveStoreOptions): Promise<CreateSaveStoreResult> {
+  const mode = opts.mode ?? "auto";
+
+  switch (mode) {
+    case "inline":
+      // The caller creates the OpfsSaveStore inside the sim worker.
+      // Return null to signal that the sim worker handles saves directly.
+      return { store: null, mode: "inline" };
+
+    case "worker": {
+      if (!isOpfsAvailable()) {
+        throw new Error("OPFS is not available — cannot use 'worker' mode. Use 'auto' or 'inline' mode.");
+      }
+      const proxy = new SaveWorkerProxy({
+        storeOptions: opts.opfsOptions,
+        workerUrl: opts.workerUrl,
+      });
+      await proxy.init();
+      return { store: proxy, mode: "worker" };
+    }
+
+    case "host": {
+      if (!opts.bridge?.saveStore) {
+        throw new Error("No host save store on the bridge — 'host' mode requires a native host (downdraft.saveStore)");
+      }
+      return { store: opts.bridge.saveStore, mode: "host" };
+    }
+
+    case "auto": {
+      // Native-first: when the host exposes a typed save store, use it.
+      // There is no OPFS and no process boundary on native.
+      if (opts.bridge?.saveStore) {
+        return { store: opts.bridge.saveStore, mode: "host" };
+      }
+      if (isOpfsAvailable()) {
+        // Try dedicated worker mode, with a 5s init timeout — the worker
+        // spawn can hang in some environments (e.g. when Vite's worker URL
+        // resolution fails in dev mode).
+        const proxy = new SaveWorkerProxy({
+          storeOptions: opts.opfsOptions,
+          workerUrl: opts.workerUrl,
+        });
+        await Promise.race([
+          proxy.init(),
+          new Promise<never>((_, reject) =>
+            setTimeout(() => reject(new Error("SaveWorkerProxy init timeout (5s)")), 5000),
+          ),
+        ]);
+        return { store: proxy, mode: "worker" };
+      }
+      // Last resort: the bridge's JSON save methods. On native this only
+      // happens in headless/test hosts with no appId (the stub bridge) —
+      // saves no-op but callers get a well-formed store. In a browser with
+      // a real bridge this preserves the pre-migration fallback behavior.
+      if (opts.bridge) {
+        return { store: new BridgeJsonSaveStore(opts.bridge), mode: "host" };
+      }
+      throw new Error("No save backend available in 'auto' mode — no host save store, no OPFS, no bridge");
+    }
+
+    default:
+      throw new Error(`Unknown save store mode: ${mode}`);
+  }
+}
+
+/**
+ * ISaveStore over the bridge's JSON-string save methods — the last-resort
+ * "auto" backend for headless hosts (stub bridge) and environments without
+ * a typed store or OPFS. The wire format is the components
+ * map (what host `saveGame`/`loadGame` handlers parse/return); SaveResult
+ * metadata is unavailable across the JSON boundary.
+ */
+export class BridgeJsonSaveStore implements ISaveStore {
+  private warningCallbacks = new Set<(w: SaveWarning) => void>();
+
+  constructor(private bridge: SaveBridge) {}
+
+  async save(slot: string, state: SaveState, opts?: SaveOptions): Promise<SaveResult> {
+    try {
+      const success = await this.bridge.saveGameState(slot, JSON.stringify(state.components), opts);
+      return { success, bytes: 0 };
+    } catch {
+      return { success: false, bytes: 0 };
+    }
+  }
+
+  async load(slot: string, opts?: LoadOptions): Promise<LoadResult> {
+    try {
+      const result = await this.bridge.loadGameState(slot, opts);
+      if (!result) return { state: null };
+      const components = JSON.parse(result);
+      return {
+        state: {
+          components,
+          meta: { engineVersion: "", timestamp: 0, entityCount: 0, playerCount: 0 },
+        },
+      };
+    } catch {
+      return { state: null };
+    }
+  }
+
+  listSaves(): Promise<SaveSlotInfo[]> {
+    return this.bridge.listSaveSlots();
+  }
+
+  async listGenerations(slot: string): Promise<SaveGenerationInfo[]> {
+    return this.bridge.listSaveGenerations?.(slot) ?? [];
+  }
+
+  deleteSave(slot: string): Promise<boolean> {
+    return this.bridge.deleteGameState(slot);
+  }
+
+  async deleteGeneration(slot: string, gen: number): Promise<boolean> {
+    return this.bridge.deleteSaveGeneration?.(slot, gen) ?? false;
+  }
+
+  async setThumbnail(slot: string, data: ArrayBuffer | Uint8Array): Promise<void> {
+    await this.bridge.setThumbnail?.(slot, data);
+  }
+
+  async getThumbnail(slot: string): Promise<ArrayBuffer | null> {
+    return (await this.bridge.getThumbnail?.(slot)) ?? null;
+  }
+
+  async setProperties(slot: string, props: Record<string, unknown>): Promise<void> {
+    await this.bridge.setSaveProperties?.(slot, props);
+  }
+
+  async getProperties(slot: string): Promise<Record<string, unknown>> {
+    return (await this.bridge.getSaveProperties?.(slot)) ?? {};
+  }
+
+  onWarning(cb: (w: SaveWarning) => void): () => void {
+    this.warningCallbacks.add(cb);
+    return () => { this.warningCallbacks.delete(cb); };
+  }
+}
+
+/**
+ * Create an OpfsSaveStore directly (for inline mode where the store runs
+ * inside the sim worker). This is a convenience wrapper that calls init().
+ */
+export async function createInlineSaveStore(opts: OpfsSaveStoreOptions): Promise<OpfsSaveStore> {
+  const store = new OpfsSaveStore(opts);
+  await store.init();
+  return store;
+}

package/app/src/renderer/sim-bridge.ts

@@ -0,0 +1,183 @@
+// ============================================================================
+// createSimBridge — shared renderer-side facade over the sim worker + app bridge.
+//
+// Generalized from to-the-ocean's sim-bridge.ts. The reusable kernel is the
+// three-mode save/load orchestration:
+//   - "inline": the sim worker owns its save store (e.g. OPFS) — just RPC.
+//   - "worker": worker serializes to stateJson, renderer writes it to a
+//     dedicated ISaveStore, grafting in renderer metadata.
+//   - "host": worker serializes to stateJson, renderer writes it to the
+//     host's typed save store (downdraft.saveStore — HostSaveStore on
+//     native). The JSON-string bridge methods are only a fallback when the
+//     host exposes no typed store.
+//
+// Game-specific command verbs (respawnPlayer, setWeather, sendCommand, ...)
+// stay in the game's own bridge — extend this object:
+//   return { ...createSimBridge(deps), respawnPlayer: (id) => worker.respawnPlayer(id) };
+// ============================================================================
+
+import type { IRendererStateProvider, ISaveStore, LoadOptions, SaveMeta, SaveOptions, SaveState } from "@downdraft/engine";
+import { downdraft, type Host } from "./index";
+
+/** Minimal worker surface needed by the bridge (pause/resume/save/load). */
+export interface SimBridgeWorker {
+  save(
+    slotName: string,
+    opts?: SaveOptions,
+  ): Promise<{ slotName?: string; stateJson?: string; success?: boolean; gen?: number; meta?: SaveMeta } | null | undefined>;
+  load(slotName: string, stateJson?: string, opts?: LoadOptions): Promise<boolean>;
+  pause(): void;
+  resume(): void;
+}
+
+export interface SimBridgeDeps {
+  worker: SimBridgeWorker;
+  /** Optional renderer meta provider — grafted into saves as components.renderer. */
+  renderer?: IRendererStateProvider | null;
+  /** App bridge — defaults to the window.downdraft singleton (or its stub). */
+  downdraft?: Host | null;
+  /** Optional save store (OPFS worker proxy or the host's typed store). When provided, saves bypass the JSON bridge methods. */
+  saveStore?: ISaveStore | null;
+  /** Save mode: "inline" (worker has OPFS store), "worker" (dedicated save store), "host" (host save store / bridge). Default: "host". */
+  saveMode?: "inline" | "worker" | "host";
+}
+
+/** Generic sim bridge — save/load + pause/resume + app window controls. */
+export interface SimBridge {
+  saveGame(slotName: string, opts?: SaveOptions): Promise<boolean>;
+  loadGame(slotName: string): Promise<boolean>;
+  pauseGame(): void;
+  resumeGame(): void;
+  quit(): void;
+  toggleDevtools(): void;
+  toggleFullscreen(): void;
+  /** Reload the page to restart the sim. */
+  resetGame(): void;
+}
+
+export function createSimBridge(deps: SimBridgeDeps): SimBridge {
+  const { worker, renderer, saveStore, saveMode = "host" } = deps;
+  // Resolve the app bridge lazily — callers may omit it (defaults to the
+  // window.downdraft singleton / stub from this package's index).
+  const bridge = () => deps.downdraft ?? downdraft;
+
+  return {
+    async saveGame(slotName: string, opts?: SaveOptions): Promise<boolean> {
+      const mergedOpts: SaveOptions = { ...opts };
+
+      // Typed save store path (dedicated OPFS worker proxy or the host's
+      // HostSaveStore): serialize in the sim worker, then write to the store.
+      if ((saveMode === "worker" || saveMode === "host") && saveStore) {
+        const result = await worker.save(slotName, mergedOpts);
+        if (!result?.stateJson) return false;
+        const components = JSON.parse(result.stateJson);
+        if (renderer?.serializeRendererMeta) {
+          components.renderer = { v: 1, data: renderer.serializeRendererMeta() };
+        }
+        const state: SaveState = {
+          components,
+          meta: {
+            engineVersion: (mergedOpts.properties?.engineVersion as string) ?? "0.1.0",
+            timestamp: Date.now() / 1000,
+            entityCount: 0,
+            playerCount: 0,
+            // Real SaveMeta computed by the worker's save.meta() hook wins.
+            ...result.meta,
+          },
+        };
+        const saveResult = await saveStore.save(slotName, state, mergedOpts);
+        return saveResult.success;
+      }
+
+      // Inline mode: worker has its own OpfsSaveStore, just pass opts.
+      if (saveMode === "inline") {
+        const result = await worker.save(slotName, mergedOpts);
+        return result?.success ?? false;
+      }
+
+      // Host fallback when no typed store is installed: worker returns
+      // stateJson, send via the bridge's legacy JSON methods.
+      const result = await worker.save(slotName, mergedOpts);
+      if (result?.stateJson) {
+        const dd = bridge();
+        if (dd.saveGameState) {
+          const components = JSON.parse(result.stateJson);
+          if (renderer?.serializeRendererMeta) {
+            components.renderer = { v: 1, data: renderer.serializeRendererMeta() };
+          }
+          return dd.saveGameState(slotName, JSON.stringify(components), mergedOpts);
+        }
+      }
+      return false;
+    },
+
+    async loadGame(slotName: string): Promise<boolean> {
+      // Typed save store: load from it directly.
+      if ((saveMode === "worker" || saveMode === "host") && saveStore) {
+        const loadResult = await saveStore.load(slotName);
+        if (!loadResult.state) return false;
+        const stateJson = JSON.stringify(loadResult.state.components);
+        const ok = await worker.load(slotName, stateJson);
+        if (ok && renderer?.restoreRendererMeta) {
+          try {
+            const components = JSON.parse(stateJson);
+            if (components.renderer?.data) {
+              renderer.restoreRendererMeta(components.renderer.data);
+            }
+          } catch { /* ignore */ }
+        }
+        return ok;
+      }
+
+      // Inline mode: worker loads from its own OPFS store.
+      if (saveMode === "inline") {
+        return worker.load(slotName);
+      }
+
+      // Host fallback: load through the bridge's legacy JSON methods.
+      const dd = bridge();
+      if (!dd.loadGameState) return false;
+      const stateJson = await dd.loadGameState(slotName);
+      if (!stateJson) return false;
+      const loaded = await worker.load(slotName, stateJson);
+      if (loaded) {
+        try {
+          const components = JSON.parse(stateJson);
+          if (components.renderer?.data) {
+            renderer?.restoreRendererMeta?.(components.renderer.data);
+          }
+        } catch {
+          // ignore parse errors
+        }
+      }
+      return loaded;
+    },
+
+    pauseGame(): void {
+      worker.pause();
+    },
+
+    resumeGame(): void {
+      worker.resume();
+    },
+
+    quit(): void {
+      void bridge().quit();
+    },
+
+    toggleDevtools(): void {
+      bridge().toggleDevtools();
+    },
+
+    toggleFullscreen(): void {
+      bridge().toggleFullscreen();
+    },
+
+    resetGame(): void {
+      // Host-owned restart on native (detached self-respawn); DOM hosts
+      // reload the page.
+      if (bridge().requestRestart?.("game reset")) return;
+      window.location.reload();
+    },
+  };
+}