@downdraft/engine 0.0.0 → 0.1.0

package/core/src/worker/crash-recovery.ts

@@ -0,0 +1,201 @@
+import type { World } from "../ecs/world";
+import type { SaveData, Serializer } from "../save/serializer";
+import type { CheckpointData, CheckpointManager } from "../scene/checkpoint";
+import { createLogger } from "../util/logger";
+export interface SimWorkerLike {
+  restart(): Promise<void>;
+  isAlive(): boolean;
+}
+
+const log = createLogger();
+
+export interface CrashRecoveryConfig {
+  checkpointIntervalMs: number;
+  maxCheckpoints: number;
+  autoRestore: boolean;
+  checkpointPrefix: string;
+}
+
+export const DEFAULT_RECOVERY_CONFIG: CrashRecoveryConfig = {
+  checkpointIntervalMs: 5000,
+  maxCheckpoints: 10,
+  autoRestore: true,
+  checkpointPrefix: "auto",
+};
+
+export interface RecoveryState {
+  lastCheckpointTime: number;
+  checkpointCount: number;
+  crashCount: number;
+  lastRestoredCheckpoint: string | null;
+  isRecovering: boolean;
+}
+
+export class CrashRecoveryManager {
+  private supervisor: SimWorkerLike;
+  private checkpointManager: CheckpointManager;
+  private world: World;
+  private serializer: Serializer;
+  private config: CrashRecoveryConfig;
+  private state: RecoveryState;
+  private dbWorker: { execute: (cmd: unknown) => Promise<unknown> } | null = null;
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+  private onCheckpoint: ((name: string) => void) | null = null;
+  private onRecovery: ((checkpointName: string) => void) | null = null;
+
+  constructor(
+    supervisor: SimWorkerLike,
+    checkpointManager: CheckpointManager,
+    world: World,
+    serializer: Serializer,
+    config?: Partial<CrashRecoveryConfig>,
+  ) {
+    this.supervisor = supervisor;
+    this.checkpointManager = checkpointManager;
+    this.world = world;
+    this.serializer = serializer;
+    this.config = { ...DEFAULT_RECOVERY_CONFIG, ...config };
+    this.state = {
+      lastCheckpointTime: 0,
+      checkpointCount: 0,
+      crashCount: 0,
+      lastRestoredCheckpoint: null,
+      isRecovering: false,
+    };
+  }
+
+  setDBWorker(worker: { execute: (cmd: unknown) => Promise<unknown> }): void {
+    this.dbWorker = worker;
+  }
+
+  setOnCheckpoint(fn: (name: string) => void): void {
+    this.onCheckpoint = fn;
+  }
+
+  setOnRecovery(fn: (checkpointName: string) => void): void {
+    this.onRecovery = fn;
+  }
+
+  start(): void {
+    if (this.intervalId) return;
+    this.intervalId = setInterval(() => this.createCheckpoint(), this.config.checkpointIntervalMs);
+  }
+
+  stop(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+  }
+
+  private checkpointSeq = 0;
+
+  createCheckpoint(): string {
+    const name = `${this.config.checkpointPrefix}_${Date.now()}_${this.checkpointSeq++}`;
+    const cp = this.checkpointManager.create(name, this.world);
+    this.state.lastCheckpointTime = Date.now();
+    this.state.checkpointCount++;
+
+    if (this.dbWorker) {
+      const saveData = this.serializer.serialize(this.world, name);
+      this.dbWorker.execute({
+        op: "checkpoint",
+        key: name,
+        data: saveData,
+      }).catch((err) => {
+        log.error("CrashRecovery", `Failed to persist checkpoint: ${err}`);
+      });
+    }
+
+    if (this.onCheckpoint) this.onCheckpoint(name);
+    return name;
+  }
+
+  async recoverFromCrash(): Promise<boolean> {
+    if (this.state.isRecovering) return false;
+    this.state.isRecovering = true;
+    this.state.crashCount++;
+
+    try {
+      let checkpointName: string | null = null;
+
+      if (this.dbWorker) {
+        const result = await this.dbWorker.execute({
+          op: "restore",
+          key: this.config.checkpointPrefix,
+        });
+        if (result && typeof result === "object" && "scene" in result) {
+          const saveData = result as SaveData;
+          checkpointName = saveData.scene.name;
+          this.serializer.deserialize(saveData, this.world, {
+            migrate: (_data: unknown, _from: number) => _data,
+            getCurrentVersion: () => 1,
+            hasMigration: () => false,
+            registerMigration: () => {},
+          } as unknown as import("../save/schema").SchemaRegistry);
+        }
+      }
+
+      if (!checkpointName) {
+        const checkpoints = this.checkpointManager.list();
+        if (checkpoints.length === 0) {
+          this.state.isRecovering = false;
+          return false;
+        }
+        const latest = checkpoints[checkpoints.length - 1];
+        checkpointName = latest.name;
+        this.checkpointManager.restore(checkpointName, this.world);
+      }
+
+      this.state.lastRestoredCheckpoint = checkpointName;
+      if (this.onRecovery) this.onRecovery(checkpointName);
+      this.state.isRecovering = false;
+      return true;
+    } catch (err) {
+      log.error("CrashRecovery", `Recovery failed: ${err}`);
+      this.state.isRecovering = false;
+      return false;
+    }
+  }
+
+  getState(): RecoveryState {
+    return this.state;
+  }
+
+  getConfig(): CrashRecoveryConfig {
+    return { ...this.config };
+  }
+
+  setConfig(config: Partial<CrashRecoveryConfig>): void {
+    this.config = { ...this.config, ...config };
+    if (this.intervalId) {
+      this.stop();
+      this.start();
+    }
+  }
+
+  listCheckpoints(): CheckpointData[] {
+    return this.checkpointManager.list();
+  }
+
+  restoreCheckpoint(name: string): boolean {
+    return this.checkpointManager.restore(name, this.world);
+  }
+
+  clearCheckpoints(): void {
+    for (const cp of this.checkpointManager.list()) {
+      if (this.dbWorker) {
+        this.dbWorker.execute({
+          op: "delete",
+          key: cp.name,
+        }).catch(() => {});
+      }
+    }
+  }
+
+  dispose(): void {
+    this.stop();
+    this.onCheckpoint = null;
+    this.onRecovery = null;
+  }
+}

package/core/src/worker/entity-sim-worker-host.ts

@@ -0,0 +1,190 @@
+// ============================================================================
+// EntitySimWorkerHost — shared skeleton for entity-sim worker hosts.
+//
+// Entity games (to-the-ocean, andrews-sandbox) manage a long-lived sim worker
+// that owns a full entity simulation. Their host classes re-implemented the
+// same skeleton on top of the raw RPC layer:
+//   - sim + input SAB allocation (allocateSimBuffer / allocateInputBuffer)
+//   - extra SABs (water, boats, ...) forwarded to the worker's init RPC
+//   - config-driven start(config) → spawnWorker → init(buffers, config)
+//   - save/load/initSaveStore/restoreFromState null-safe RPC wrappers
+//   - sendCommand fire-and-forget
+//   - hotReload() via HotReloadPipeline (dev cache-bust worker URL)
+//   - getDevToolsProxy() for devtools manifest sync
+//
+// This base class centralizes that. Subclasses provide:
+//   - spawnWorker(cacheBust?): MUST contain the inline
+//     `new Worker(new URL("./xxx-worker.ts", import.meta.url), { type: "module" })`
+//     pattern (Vite static analysis — see base-worker-host.ts). When
+//     `cacheBust` is set (dev hot reload), append `?t=<cacheBust>` to the URL.
+//   - buildWorkerConfig(): optional — map the host config to the worker's
+//     init config argument. Default: identity.
+//
+// The init RPC is invoked as:
+//   init(simBuffer, inputBuffer, ...extraBufferValues, workerConfig)
+// where extraBufferValues are Object.values(extraBuffers) in insertion order.
+// Games whose worker init takes a different shape override onInit().
+// ============================================================================
+
+import { isDevMode } from "../platform/runtime";
+import { allocateInputBuffer, allocateSimBuffer } from "../sab/sim-channel";
+import { HotReloadPipeline } from "../sim/hot-reload-pipeline";
+import type { IHotReloadable } from "../sim/types";
+import type { WorkerApi } from "./rpc";
+import { SimWorkerHost, type SimWorkerSaveApi } from "./sim-worker-host";
+
+/** Minimal worker-side API the entity sim host relies on. */
+export interface EntitySimApi extends WorkerApi, SimWorkerSaveApi {
+  init(
+    simBuffer: SharedArrayBuffer,
+    inputBuffer: SharedArrayBuffer,
+    ...rest: any[]
+  ): Promise<void>;
+  pause(): Promise<void>;
+  resume(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+export interface EntitySimHostOptions {
+  /** Pre-allocated sim SAB (default: allocateSimBuffer()). */
+  simBuffer?: SharedArrayBuffer;
+  /** Pre-allocated input SAB (default: allocateInputBuffer()). */
+  inputBuffer?: SharedArrayBuffer;
+  /** Extra SABs forwarded to init() between inputBuffer and the config arg. */
+  extraBuffers?: Record<string, SharedArrayBuffer>;
+}
+
+export abstract class EntitySimWorkerHost<
+    TApi extends EntitySimApi,
+    TConfig,
+  >
+  extends SimWorkerHost<TApi>
+  implements IHotReloadable
+{
+  protected readonly inputBuffer: SharedArrayBuffer;
+  protected readonly extraBuffers: Record<string, SharedArrayBuffer>;
+  private simConfig: TConfig | null = null;
+  private cacheBust: number | undefined;
+  private pipeline: HotReloadPipeline | null = null;
+  private ddSessionSim: {
+    label: string;
+    host: any;
+    hotReload: (preserve: boolean) => Promise<void>;
+    save: () => Promise<string | null>;
+    restore: (json: string) => Promise<void>;
+    stop: () => Promise<void>;
+  } | null = null;
+
+  constructor(opts?: EntitySimHostOptions) {
+    super(opts?.simBuffer ?? allocateSimBuffer());
+    this.inputBuffer = opts?.inputBuffer ?? allocateInputBuffer();
+    this.extraBuffers = opts?.extraBuffers ?? {};
+
+    // Native dev shell: register for transparent sim hot-swap + session
+    // state save/restore. The registry lives on globalThis.__ddSession
+    // (installed by @downdraft/platform-native's dev runtime) — outside the
+    // shell this is absent and registration is a no-op. Deliberately global-
+    // keyed so engine core never imports platform-native.
+    const session = (globalThis as any).__ddSession;
+    if (session?.registerSim) {
+      this.ddSessionSim = {
+        label: this.constructor.name,
+        host: this,
+        hotReload: (preserve: boolean) => this.hotReload(this.simConfig as TConfig, preserve),
+        save: async () => (await this.save("hot-reload"))?.stateJson ?? null,
+        restore: (json: string) => this.restoreFromState(json),
+        stop: () => this.stop(),
+      };
+      session.registerSim(this.ddSessionSim);
+    }
+  }
+
+  override getInputBuffer(): SharedArrayBuffer {
+    return this.inputBuffer;
+  }
+
+  /** Extra SABs exposed to the renderer (e.g. via GameContext.extraBuffers). */
+  getExtraBuffers(): Record<string, SharedArrayBuffer> {
+    return this.extraBuffers;
+  }
+
+  /** Look up a single extra SAB by name. */
+  getExtraBuffer(name: string): SharedArrayBuffer | undefined {
+    return this.extraBuffers[name];
+  }
+
+  /**
+   * Spawn the worker with the given config. In dev mode the worker URL is
+   * cache-busted so Vite re-serves the (possibly hot-reloaded) module.
+   */
+  async start(config?: TConfig): Promise<void> {
+    this.simConfig = config ?? null;
+    this.cacheBust = isDevMode ? Date.now() : undefined;
+    await super.start();
+    // Entity sim workers don't emit "ready" themselves — the host marks
+    // ready + dispatches the event after the init RPC resolves.
+    this.onEvent("ready", {});
+    // Session restart restore: after a dev-shell session restart, pending
+    // hot-reload state (saved before teardown) is pushed onto the fresh
+    // worker here — before the game sees "ready"-driven work.
+    if (this.ddSessionSim) {
+      try {
+        await (globalThis as any).__ddSession?.notifySimStarted?.(this.ddSessionSim);
+      } catch { /* restore is best-effort */ }
+    }
+  }
+
+  /**
+   * BaseWorkerHost hook — delegates to spawnWorker so the subclass can apply
+   * the cache-bust param. Subclasses implement spawnWorker(), not this.
+   */
+  protected override createWorker(): Worker {
+    return this.spawnWorker(this.cacheBust);
+  }
+
+  /**
+   * MUST return `new Worker(new URL("./xxx-worker.ts", import.meta.url), { type: "module" })`.
+   * The URL must be inline (not a variable) for Vite's worker bundling to work
+   * in production. When `cacheBust` is set, build the URL in a variable and
+   * append `?t=<cacheBust>` — dev-only path, so the non-literal form is fine.
+   */
+  protected abstract spawnWorker(cacheBust?: number): Worker;
+
+  /**
+   * Default init RPC: init(simBuffer, inputBuffer, ...extraBuffers, config).
+   * Override for workers with a different init signature.
+   */
+  protected override async onInit(): Promise<void> {
+    const cfg = this.buildWorkerConfig(this.simConfig as TConfig);
+    await this.getProxy()!.proxy.init(
+      this.getSimBuffer(),
+      this.inputBuffer,
+      ...Object.values(this.extraBuffers),
+      cfg,
+    );
+  }
+
+  /** Map the host config to the worker's init config argument. Default: identity. */
+  protected buildWorkerConfig(config: TConfig): unknown {
+    return config;
+  }
+
+  // --- Hot reload ---
+
+  /** Save → stop → spawn fresh worker → restore. Dev-mode only. */
+  async hotReload(config: TConfig, preserveState: boolean): Promise<void> {
+    if (!isDevMode) return;
+    this.pipeline ??= new HotReloadPipeline(this);
+    await this.pipeline.hotReload(config, preserveState);
+  }
+
+  // --- DevTools ---
+
+  /**
+   * Returns the worker's RPC proxy for devtools manifest sync
+   * (exposeDevToolsApi adds __devtoolsGetManifest etc. to the api type).
+   */
+  getDevToolsProxy(): TApi | null {
+    return this.getProxy()?.proxy ?? null;
+  }
+}

package/core/src/worker/instrumented-worker-host.ts

@@ -0,0 +1,171 @@
+// ============================================================================
+// InstrumentedWorkerHost — extends BaseWorkerHost to allocate/share the global
+// ProfilingSAB and ensure the prelude runs before the user's onInit.
+//
+// Overrides beforeInit() to call `__profilingAttach(sab, config)` on the
+// worker proxy, guaranteeing the SAB is attached + prototypes patched +
+// warning engine + event-loop monitor initialized before any user code runs.
+//
+// Also provides exposeProfilingApi() — a helper that merges the
+// __profilingAttach / __profilingAddRule / __profilingOnWarning RPC methods
+// into a worker's expose() API (alongside exposeDevToolsApi).
+// ============================================================================
+
+import type { ProfilingSABLayout, RuntimeKind } from "../profiling/profiling-sab";
+import type { WarningRule } from "../profiling/warnings";
+import { createLogger } from "../util/logger";
+import { BaseWorkerHost } from "./base-worker-host";
+import type { WorkerApi } from "./rpc";
+
+const log = createLogger();
+
+export interface InstrumentedWorkerHostOptions {
+  /** The global ProfilingSAB shared with all workers. */
+  profilingSAB: SharedArrayBuffer;
+  /** The SAB layout (computed once by the renderer). */
+  profilingLayout: ProfilingSABLayout;
+  /** Worker tag string (e.g. "sim", "save", "plugin:foo"). */
+  workerTag: string;
+  /** Runtime kind: 0=JS, 1=QuickJS, 2=WASM. Default: 0 (JS). */
+  runtime?: RuntimeKind;
+  /** Patch OPFS prototypes. Default: true. */
+  opfs?: boolean;
+  /** Patch IndexedDB prototypes. Default: true. */
+  idb?: boolean;
+  /** Register default warning rules. Default: true. */
+  defaultWarningRules?: boolean;
+}
+
+/**
+ * BaseWorkerHost subclass that auto-attaches the ProfilingSAB before onInit.
+ *
+ * Games can either extend this class directly, or use the static `wrap()`
+ * method to instrument an existing BaseWorkerHost subclass.
+ */
+export abstract class InstrumentedWorkerHost<TApi extends WorkerApi> extends BaseWorkerHost<TApi> {
+  protected profilingOpts: InstrumentedWorkerHostOptions;
+
+  constructor(sab: SharedArrayBuffer, profilingOpts: InstrumentedWorkerHostOptions) {
+    super(sab);
+    this.profilingOpts = profilingOpts;
+  }
+
+  /**
+   * Override beforeInit() to call __profilingAttach before onInit().
+   * The worker's expose() must include the profiling RPC methods
+   * (via exposeProfilingApi()).
+   */
+  protected async beforeInit(): Promise<void> {
+    await this.attachProfiling();
+  }
+
+  /**
+   * Call the worker's __profilingAttach RPC to attach the SAB + patch
+   * prototypes + initialize the warning engine + event-loop monitor.
+   */
+  protected async attachProfiling(): Promise<void> {
+    const proxy = this.getProxy();
+    if (!proxy) return;
+    const opts = this.profilingOpts;
+    try {
+      await (proxy.proxy as any).__profilingAttach(
+        opts.profilingSAB,
+        {
+          workerTag: opts.workerTag,
+          runtime: opts.runtime ?? 0,
+          opfs: opts.opfs ?? true,
+          idb: opts.idb ?? true,
+          defaultWarningRules: opts.defaultWarningRules ?? true,
+          layout: {
+            maxSlots: opts.profilingLayout.maxSlots,
+            iopsRingCap: opts.profilingLayout.iopsRingCap,
+            warningRingCap: opts.profilingLayout.warningRingCap,
+            stringTableCap: opts.profilingLayout.stringTableCap,
+          },
+        },
+      );
+    } catch (err) {
+      log.warn("InstrumentedWorkerHost", `__profilingAttach failed for "${opts.workerTag}": ${err}`);
+    }
+  }
+
+  /**
+   * Forward a warning rule to this worker's warning engine.
+   */
+  async addWarningRule(rule: WarningRule): Promise<void> {
+    const proxy = this.getProxy();
+    if (!proxy) return;
+    try {
+      await (proxy.proxy as any).__profilingAddRule(rule);
+    } catch (err) {
+      log.warn("InstrumentedWorkerHost", `__profilingAddRule failed: ${err}`);
+    }
+  }
+
+  /**
+   * Subscribe to warnings from this worker. The callback is called on the
+   * main thread when the worker fires a warning.
+   */
+  async onWarning(cb: (record: any, ctx: any) => void): Promise<() => void> {
+    const proxy = this.getProxy();
+    if (!proxy) return () => {};
+    try {
+      const unsub = proxy.onEvents((kind: string, data: any) => {
+        if (kind === "__profilingWarning") {
+          cb(data.record, data.ctx);
+        }
+      });
+      await (proxy.proxy as any).__profilingOnWarning();
+      return unsub;
+    } catch (err) {
+      log.warn("InstrumentedWorkerHost", `__profilingOnWarning failed: ${err}`);
+      return () => {};
+    }
+  }
+}
+
+// ─── exposeProfilingApi — worker-side helper ────────────────────────────────
+
+/**
+ * Merge the standard profiling RPC methods into a worker's expose() API.
+ * Call this inside the worker's expose() setup:
+ *
+ *   expose(exposeProfilingApi(exposeDevToolsApi({ init, pause, ... })));
+ *
+ * The prelude must be imported at the top of the worker entry for these
+ * methods to work (they delegate to the prelude's attachProfilingSAB etc.).
+ */
+export function exposeProfilingApi<T extends WorkerApi>(api: T): T & {
+  __profilingAttach(sab: SharedArrayBuffer, config: any): Promise<{ slotIndex: number; success: boolean }>;
+  __profilingAddRule(rule: WarningRule): void;
+  __profilingOnWarning(): void;
+} {
+  // Lazy-import the prelude functions to avoid pulling them into the main realm
+  let prelude: any = null;
+  const getPrelude = async () => {
+    if (!prelude) {
+      prelude = await import("../profiling/worker-prelude");
+    }
+    return prelude;
+  };
+
+  return {
+    ...api,
+    __profilingAttach: async (sab: SharedArrayBuffer, config: any) => {
+      const p = await getPrelude();
+      return p.attachProfilingSAB(sab, config);
+    },
+    __profilingAddRule: async (rule: WarningRule) => {
+      const p = await getPrelude();
+      p.addWarningRule(rule);
+    },
+    __profilingOnWarning: async () => {
+      const p = await getPrelude();
+      const { exposeEvents } = await import("./rpc");
+      const emitter = exposeEvents();
+      p.onWarning((record: any, ctx: any) => {
+        emitter.emit("__profilingWarning", { record, ctx });
+      });
+    },
+  };
+}