@downdraft/engine 0.0.0 → 0.1.0

package/app/src/index.ts

@@ -0,0 +1,10 @@
+// ============================================================================
+// @downdraft/engine/app — root re-exports for the host SDK
+// ============================================================================
+//
+// This barrel re-exports the high-level config surface. Entry points:
+//   - @downdraft/engine/app/renderer — the typed `downdraft` HostAPI accessor
+//     + game bootstrap (live; runtime-agnostic)
+//   - @downdraft/engine/app/shared   — host contract types (HostAPI)
+
+export type { Host, HostOsr } from "./renderer/index";

package/app/src/renderer/bootstrap.ts

@@ -0,0 +1,271 @@
+// ============================================================================
+// bootstrapGame() — framework-orchestrated renderer bootstrap
+//
+// Centralizes the common bootstrap sequence shared by all games (both
+// sim-worker and renderer-only topologies):
+//   1. Get the render surface
+//   2. Create + init renderer
+//   3. Wire DevTools (if provided)
+//   4. Start the render loop immediately (don't block on autosave)
+//   5. Feature log (renderer process)
+//   6. FPS polling (if onFpsUpdate provided)
+//   7. Display info wiring (if onDisplayInfo provided)
+//   8. Autosave load with 5s timeout + interval (if autosave provided,
+//      skip in deterministic mode)
+//   9. MCP setup (if provided)
+//  10. Hot-reload dispose (if provided)
+//  11. Deterministic callbacks (if onDeterministic provided)
+//
+// `startGame()` wraps this and adds sim worker spawn, SAB capture, event
+// routing, engine library auto-wiring, and save store initialization. Games
+// that need full control can call `bootstrapGame()` directly.
+// ============================================================================
+
+import { encodeFeatureLogLine, isDevMode, type RenderSurface } from "@downdraft/engine";
+import { createLogger } from "@downdraft/engine/util/logger";
+import { collectRendererFeatureLog } from "./feature-log";
+import { downdraft, getSurface } from "./index";
+
+const log = createLogger("info");
+
+export interface BootstrapAutosaveOptions {
+  /** Load saved state. Returns null if no save exists. */
+  load: () => Promise<any | null>;
+  /** Save current state. */
+  save: () => Promise<void>;
+  /** Autosave interval in milliseconds. Default: 3000. */
+  intervalMs?: number;
+  /** Called after a save is loaded successfully. */
+  onLoad?: (data: any) => Promise<void> | void;
+}
+
+export interface BootstrapDevToolsOptions {
+  /**
+   * Factory that creates the sim stats provider from the renderer.
+   * Called after the renderer is initialized.
+   */
+  createSimStatsProvider?: (renderer: any) => any;
+  /** DevTools panels (game-specific). Can be a factory or static array. */
+  panels?: any[] | ((renderer: any) => any[]);
+  /** Whether to enable scene inspector. Default: false. */
+  sceneInspector?: boolean;
+  /** Custom scene-inspector bridge class (extends BaseSceneInspector).
+   *  Forwarded to initDevTools — implies sceneInspector. */
+  bridgeClass?: new () => any;
+  /** Worker hosts to sync devtools manifests from (evaluated after
+   *  renderer init — a factory runs when the game's sim worker is already
+   *  started, e.g. by an overridden onInit). */
+  workerHosts?: any[] | ((renderer: any) => any[]);
+  /**
+   * Enable the profiling system (ProfilingSAB + ProfilingBridge + built-in views).
+   * When true, a ProfilingBridge is created and the ProfilingSAB is shared
+   * with all workers + devtools views. Pass `{ sharedSAB }` to attach a
+   * pre-allocated buffer. Default: false.
+   */
+  profiling?: boolean | { sharedSAB?: { sab: SharedArrayBuffer; layout: unknown } };
+}
+
+export interface BootstrapGameOptions {
+  // --- Surface ---
+  /** Surface layer index. Default: 0 — the only layer on native hosts. */
+  canvasLayer?: number;
+
+  // --- Renderer ---
+  /** Factory that creates the renderer from the render surface. */
+  createRenderer: (surface: RenderSurface) => any;
+  /** Called after renderer creation to initialize it. Should return false on failure. */
+  initRenderer?: (renderer: any) => Promise<boolean> | boolean;
+  /** Called after renderer init to let the game wire the renderer to its store. */
+  onRendererInit?: (renderer: any) => Promise<void> | void;
+
+  // --- DevTools ---
+  /** If provided, wires DevTools via initDevTools(). */
+  devtools?: BootstrapDevToolsOptions;
+
+  // --- Autosave ---
+  /** If provided, sets up autosave load + interval. Skipped in deterministic mode. */
+  autosave?: BootstrapAutosaveOptions;
+
+  // --- MCP ---
+  /** Called to register MCP tools (after renderer is started). */
+  mcp?: () => void | Promise<void>;
+
+  // --- Display info ---
+  /** Called with the display refresh rate when available. */
+  onDisplayInfo?: (refreshRate: number) => void;
+
+  // --- Hot reload ---
+  /** Called on Vite hot-reload dispose to clean up resources. */
+  onHotReloadDispose?: () => Promise<void> | void;
+
+  // --- Deterministic mode overrides ---
+  /** Called in deterministic mode to apply overrides (e.g. skip title screen). */
+  onDeterministic?: (renderer: any) => void;
+
+  // --- FPS polling ---
+  /** Called periodically with the current render FPS. Default interval: 500ms. */
+  onFpsUpdate?: (fps: number) => void;
+  /** FPS polling interval in milliseconds. Default: 500. */
+  fpsPollIntervalMs?: number;
+
+  // --- Feature log ---
+  /** Optional getter for active plugin names (e.g. () => gameWorld.moduleHost.listModules()).
+   *  Populates the `plug` field of the renderer feature log line. */
+  getActiveModules?: () => string[];
+}
+
+/**
+ * Bootstrap a game with the standard sequence.
+ *
+ * This orchestrator centralizes the common bootstrap pattern shared by all
+ * games (both sim-worker and renderer-only topologies), eliminating ~1200
+ * lines of duplicated boilerplate and closing the deterministic-mode variance
+ * gap (all gates are centralized here).
+ *
+ * `startGame()` wraps this and adds sim worker spawn, SAB capture, event
+ * routing, engine library auto-wiring, and save store initialization. Games
+ * that need full control can call `bootstrapGame()` directly. Games that need
+ * partial composition can use the individual hooks from `./hooks.ts` instead.
+ */
+export async function bootstrapGame(opts: BootstrapGameOptions): Promise<void> {
+  const canvasLayer = opts.canvasLayer ?? 0;
+  const deterministic = downdraft?.deterministic === true;
+
+  // 1. Get the render surface
+  const surface = getSurface(canvasLayer);
+
+  // 3. Create + init renderer
+  const renderer = opts.createRenderer(surface);
+  if (opts.initRenderer) {
+    const ok = await opts.initRenderer(renderer);
+    if (!ok) {
+      log.error("bootstrapGame", "Renderer init failed");
+      return;
+    }
+  }
+
+  // 4. Wire DevTools (if provided) — runs BEFORE onRendererInit so that
+  //    games can access the ProfilingBridge + __sceneInspector API in onReady.
+  if (opts.devtools) {
+    const { initDevTools } = await import("@downdraft/engine/modules/devtools");
+    const simStatsProvider = opts.devtools.createSimStatsProvider?.(renderer);
+    const panels = typeof opts.devtools.panels === "function"
+      ? opts.devtools.panels(renderer)
+      : opts.devtools.panels ?? [];
+    const workerHosts = typeof opts.devtools.workerHosts === "function"
+      ? opts.devtools.workerHosts(renderer)
+      : opts.devtools.workerHosts;
+    await initDevTools(renderer, {
+      simStatsProvider,
+      panels,
+      sceneInspector: opts.devtools.sceneInspector,
+      bridgeClass: opts.devtools.bridgeClass,
+      workerHosts,
+      profiling: opts.devtools.profiling as any,
+    });
+  }
+
+  // 4b. onRendererInit — library setup, sim start, game-specific wiring (onReady).
+  //     DevTools is already wired, so games can access __sceneInspector +
+  //     the ProfilingBridge from their onReady hook.
+  if (opts.onRendererInit) {
+    await opts.onRendererInit(renderer);
+  }
+
+  // 5. Start the render loop immediately — don't let a hung autosave load
+  //    (e.g. IndexedDB locked by another process) block the canvas from rendering.
+  if (typeof renderer.start === "function") {
+    renderer.start();
+  }
+
+  // 6. Feature log (renderer process) — collect + emit the `dd-render|...`
+  //    startup line. Synchronous; reads WebGPU adapter/features/limits,
+  //    navigator, SAB/COOP-COEP, and active plugins (if getActiveModules
+  //    provided). The main-process `dd-main|...` line is emitted separately
+  //    from app.ts; both are fetched together via getCombinedFeatureLog()
+  //    for the DevTools copy button and MCP get_features tool.
+  const isDev = !!(downdraft?.isDev) || isDevMode;
+  const renderFeatureLog = collectRendererFeatureLog({
+    renderer,
+    isDev,
+    deterministic,
+    getActiveModules: opts.getActiveModules,
+  });
+  log.info("bootstrapGame", encodeFeatureLogLine(renderFeatureLog));
+
+  // 7. FPS polling (if onFpsUpdate provided)
+  if (opts.onFpsUpdate) {
+    const fpsInterval = opts.fpsPollIntervalMs ?? 500;
+    setInterval(() => {
+      if (typeof renderer.getFPS === "function") {
+        opts.onFpsUpdate!(renderer.getFPS());
+      }
+    }, fpsInterval);
+  }
+
+  // 8. Display info wiring (if onDisplayInfo provided)
+  if (opts.onDisplayInfo && downdraft?.isAvailable) {
+    downdraft.getDisplayInfo().then((info) => {
+      if (info.refreshRate > 0) {
+        opts.onDisplayInfo!(info.refreshRate);
+      }
+    }).catch(() => { /* ignore */ });
+    downdraft.onDisplayInfo((info: any) => {
+      if (info?.refreshRate > 0) {
+        opts.onDisplayInfo!(info.refreshRate);
+      }
+    });
+  }
+
+  // 9. Autosave load + interval (skip in deterministic mode).
+  //    The load has a 5s timeout so a locked IndexedDB doesn't block the
+  //    autosave interval setup. The interval guards against overlapping
+  //    saves — if a save takes longer than the interval (e.g. the worker is
+  //    busy or OPFS is slow), the tick is skipped instead of piling up
+  //    concurrent saves that can corrupt OPFS data or hang on file locks.
+  if (opts.autosave && !deterministic) {
+    const autosaveOpts = opts.autosave;
+    const intervalMs = autosaveOpts.intervalMs ?? 3000;
+
+    try {
+      const saved = await Promise.race([
+        autosaveOpts.load(),
+        new Promise<null>((r) => setTimeout(() => r(null), 5000)),
+      ]);
+      if (saved && autosaveOpts.onLoad) {
+        await autosaveOpts.onLoad(saved);
+      }
+    } catch (e) {
+      log.warn("bootstrapGame", `Autosave load failed: ${e}`);
+    }
+
+    let saveInProgress = false;
+    setInterval(async () => {
+      if (saveInProgress) return;
+      saveInProgress = true;
+      try {
+        await autosaveOpts.save();
+      } catch (e) {
+        log.warn("bootstrapGame", `Autosave save failed: ${e}`);
+      } finally {
+        saveInProgress = false;
+      }
+    }, intervalMs);
+  }
+
+  // 10. MCP setup (if provided)
+  if (opts.mcp) {
+    await opts.mcp();
+  }
+
+  // 11. Hot-reload dispose (if provided)
+  if (opts.onHotReloadDispose) {
+    const { dispose } = await import("./hooks");
+    dispose(opts.onHotReloadDispose);
+  }
+
+  // 12. Deterministic callbacks (if onDeterministic provided)
+  if (deterministic && opts.onDeterministic) {
+    opts.onDeterministic(renderer);
+  }
+}

package/app/src/renderer/downdraft-base.css

@@ -0,0 +1,93 @@
+/* ============================================================================
+ * downdraft-base.css — framework-provided canvas/DOM stacking rules
+ *
+ * Games import this from "@downdraft/engine/app/renderer/downdraft-base.css" to get
+ * correct z-index ordering between WebGPU canvases and React DOM overlays.
+ * Games can override colors and fonts in their own CSS; the stacking rules
+ * here should not be overridden.
+ * ========================================================================== */
+
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+html,
+body {
+  width: 100%;
+  height: 100vh;
+  overflow: hidden;
+  background: #000;
+  color: #fff;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+/* Canvas layers — stacked bottom-to-top by data-dd-layer index.
+ * The framework generates <canvas data-dd-layer="0">, <canvas data-dd-layer="1">, etc.
+ * Lower layer indices render behind higher ones. */
+canvas[data-dd-layer] {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100vw;
+  height: 100vh;
+  display: block;
+  image-rendering: pixelated;
+  pointer-events: auto;
+}
+
+/* Overlay canvas layers (layer 1+) — above the game canvas (z 0), below the
+ * DOM overlay (z 100). Default pointer-events: none so clicks pass through
+ * to the game canvas. The @downdraft/engine/libraries/pixi-ui host re-enables
+ * pointer-events when the worker signals interactive mode. */
+canvas[data-dd-layer="1"],
+canvas[data-dd-layer="2"],
+canvas[data-dd-layer="3"],
+canvas[data-dd-layer="4"],
+canvas[data-dd-layer="5"] {
+  z-index: 50;
+  pointer-events: none;
+  image-rendering: auto; /* UI overlays should not be pixelated */
+}
+
+/* DOM overlay layers — stacked above all canvases.
+ * The framework generates <div data-dd-overlay="0">, <div data-dd-overlay="1">, etc.
+ * Overlays are above canvases by default; pointer-events: none lets clicks
+ * pass through to the canvas. Individual HUD elements re-enable pointer-events. */
+div[data-dd-overlay] {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100vw;
+  height: 100vh;
+  pointer-events: none;
+  background: transparent;
+  z-index: 100;
+}
+
+/* The legacy #root and .game-canvas selectors are kept for backward
+ * compatibility with games that haven't migrated to data-dd-layer yet. */
+.game-canvas {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100vw;
+  height: 100vh;
+  display: block;
+  image-rendering: pixelated;
+  z-index: 0;
+}
+
+#root {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+  background: transparent;
+  z-index: 100;
+}

package/app/src/renderer/feature-log.ts

@@ -0,0 +1,200 @@
+// ============================================================================
+// Renderer feature log — collects WebGPU/adapter/display/module data
+// ============================================================================
+//
+// Synchronous collector for the render-side fields of the feature log, plus
+// a combined accessor that fetches the host log via `downdraft.getFeatureLog`
+// for the DevTools copy button and the MCP `get_features` tool. On the
+// single-process native runtime the two halves merge into one `dd-host|...`
+// line; multi-process hosts keep `dd-main|...` + `dd-render|...`.
+
+import { ENGINE_VERSION, condenseText, encodeFeatureLogJSON, encodeFeatureLogLine, encodeFeatureLogLines, encodeFeatures, getHostCapabilities, type FeatureLogData } from "@downdraft/engine";
+import { downdraft } from "./index";
+import type { McpToolRegistration } from "./mcp-harness";
+
+export interface RendererFeatureLogOptions {
+  /** Renderer with getGPUInfo() / getAdapterInfo() (GameRenderer or similar). */
+  renderer: any;
+  /** Engine version (defaults to ENGINE_VERSION from @downdraft/engine). */
+  engineVersion?: string;
+  isDev: boolean;
+  deterministic: boolean;
+  /** Optional getter for active plugin names (e.g. () => gameWorld.moduleHost.listModules()). */
+  getActiveModules?: () => string[];
+}
+
+let cachedRendererFeatureLog: FeatureLogData | null = null;
+
+/**
+ * Collect the renderer-process feature log data. Synchronous; reads WebGPU
+ * adapter/features/limits via renderer.getGPUInfo(), navigator props, and
+ * crossOriginIsolated. Display refresh rate is best-effort from a cached
+ * downdraft.getDisplayInfo() result if already resolved; otherwise `disp` is
+ * omitted (additive schema tolerates absence).
+ */
+export function collectRendererFeatureLog(opts: RendererFeatureLogOptions): FeatureLogData {
+  const { renderer, isDev, deterministic, getActiveModules } = opts;
+  const v = opts.engineVersion ?? ENGINE_VERSION;
+
+  const data: FeatureLogData = {
+    sv: 1,
+    scope: "render",
+    v,
+    mode: deterministic ? "deterministic" : isDev ? "dev" : "packaged",
+  };
+
+  // --- WebGPU adapter / features / limits / canvas format ---
+  try {
+    const gpuInfo = renderer?.getGPUInfo?.() ?? null;
+    if (gpuInfo) {
+      const adapter = gpuInfo.adapter;
+      const fmt = gpuInfo.canvasFormat ?? "";
+      // Encode features as short codes if the device exposes them.
+      let featCodes = "";
+      try {
+        const feats = renderer?.getDevice?.()?.features ?? null;
+        if (feats && typeof feats[Symbol.iterator] === "function") {
+          featCodes = encodeFeatures(Array.from(feats) as string[]);
+        }
+      } catch { /* features unavailable */ }
+
+      // Key limits as compact k=v pairs.
+      const L = gpuInfo.deviceLimits ?? {};
+      const limParts: string[] = [];
+      if (L.maxTextureDimension2D) limParts.push(`2d=${L.maxTextureDimension2D}`);
+      if (L.maxTextureDimension3D) limParts.push(`3d=${L.maxTextureDimension3D}`);
+      if (L.maxBufferSize) limParts.push(`buf=${L.maxBufferSize}`);
+      if (L.maxBindGroups) limParts.push(`bind=${L.maxBindGroups}`);
+      if (L.maxSamplersPerShaderStage) limParts.push(`samp=${L.maxSamplersPerShaderStage}`);
+
+      const wgpuParts: string[] = [];
+      if (adapter?.vendor) wgpuParts.push(`vendor=${condenseText(adapter.vendor, 16)}`);
+      if (adapter?.architecture) wgpuParts.push(`arch=${condenseText(adapter.architecture, 24)}`);
+      if (adapter?.device) wgpuParts.push(`dev=${condenseText(adapter.device, 32)}`);
+      if (fmt) wgpuParts.push(`fmt=${fmt}`);
+      if (featCodes) wgpuParts.push(`feat=${featCodes}`);
+      if (limParts.length > 0) wgpuParts.push(`lim=${limParts.join(",")}`);
+      if (wgpuParts.length > 0) data.wgpu = wgpuParts.join(";");
+    }
+  } catch { /* getGPUInfo unavailable */ }
+
+  // --- navigator CPU / memory ---
+  try {
+    const nav: any = (globalThis as any).navigator;
+    if (nav?.hardwareConcurrency) data.cpuCores = nav.hardwareConcurrency;
+    // deviceMemory is non-standard (Chrome only); optional.
+    if (nav?.deviceMemory) data.mem = `${nav.deviceMemory}G`;
+  } catch { /* navigator unavailable */ }
+
+  // --- SharedArrayBuffer + crossOriginIsolated (browser isolation only —
+  // there is no origin model on the native host) ---
+  try {
+    data.sab = typeof SharedArrayBuffer !== "undefined" ? 1 : 0;
+  } catch {
+    data.sab = 0;
+  }
+  if (getHostCapabilities().hasDom) {
+    try {
+      data.coi = (self as any).crossOriginIsolated ? 1 : 0;
+    } catch {
+      data.coi = 0;
+    }
+  }
+
+  // --- Worker load status (best-effort; na = not checked) ---
+  data.wk = "na";
+
+  // --- Active plugins ---
+  if (getActiveModules) {
+    try {
+      const plugins = getActiveModules();
+      if (plugins && plugins.length > 0) {
+        data.plug = plugins.join(",");
+      }
+    } catch { /* plugin list unavailable */ }
+  }
+
+  cachedRendererFeatureLog = data;
+  return data;
+}
+
+/** Return the most recently collected renderer feature log, or null. */
+export function getRendererFeatureLog(): FeatureLogData | null {
+  return cachedRendererFeatureLog;
+}
+
+/** Combined feature log result: merged host line + structured payload. */
+export interface CombinedFeatureLog {
+  /** Single-process merged log (native). Null on multi-process hosts. */
+  host: FeatureLogData | null;
+  main: FeatureLogData | null;
+  render: FeatureLogData | null;
+  /** Pasteable string — `dd-host|...` on native, `dd-main|...` + `dd-render|...` elsewhere. */
+  line: string;
+  /** Minified JSON of `{ host }` or `{ main, render }` for tooling. */
+  json: string;
+}
+
+/**
+ * Fetch the host's feature log and merge with the cached render-side log.
+ * Used by the DevTools copy button and the MCP `get_features` tool.
+ * On the native host both halves describe the same process — the result is
+ * a single `dd-host` scope. Browser/multi-process hosts keep the split.
+ */
+export async function getCombinedFeatureLog(): Promise<CombinedFeatureLog> {
+  let hostLog: FeatureLogData | null = null;
+  try {
+    hostLog = downdraft?.isAvailable ? await downdraft.getFeatureLog() : null;
+  } catch { /* host log unavailable */ }
+  const render = cachedRendererFeatureLog;
+  if (hostLog?.scope === "host" || getHostCapabilities().runtime === "native") {
+    // Single process — merge render fields (wgpu/disp/sab/wk/plug) into the
+    // host line. Host fields win on overlap (v, mode, cpuCores).
+    const host: FeatureLogData | null = hostLog || render
+      ? { ...(render ?? {}), ...(hostLog ?? {}), scope: "host" } as FeatureLogData
+      : null;
+    return {
+      host,
+      main: null,
+      render: null,
+      line: host ? encodeFeatureLogLine(host) : "",
+      json: JSON.stringify({ host }),
+    };
+  }
+  return {
+    host: null,
+    main: hostLog,
+    render,
+    line: encodeFeatureLogLines(hostLog, render),
+    json: JSON.stringify({ main: hostLog, render }),
+  };
+}
+
+/**
+ * MCP tool definition for `get_features`. Returns the combined feature log
+ * (both lines + structured payload). Add to a game's MCP harness tools array.
+ */
+export function createFeatureLogMcpTool(): McpToolRegistration {
+  return {
+    def: {
+      name: "get_features",
+      description:
+        "Return the engine feature log: a terse, versioned, pipe-delimited diagnostic string " +
+        "(dd-host|... on the single-process native host) plus the structured { host } payload. " +
+        "Use this to inspect the running environment (OS, CPU, GPU, WebGPU features/limits, " +
+        "runtime versions, active plugins, SAB/COOP-COEP status).",
+      inputSchema: {
+        type: "object",
+        properties: {},
+      },
+    },
+    handler: async () => {
+      const combined = await getCombinedFeatureLog();
+      // Return the structured payload; the harness wraps it as JSON text.
+      return combined;
+    },
+  };
+}
+
+/** Re-export encodeFeatureLogJSON for callers that want the structured form. */
+export { encodeFeatureLogJSON };