@downdraft/engine 0.0.0 → 0.1.1

package/modules/devtools/src/types.ts

@@ -0,0 +1,290 @@
+// ============================================================================
+// DevTools type interfaces — contracts between the base inspector, games,
+// and the DevTools extension panels.
+// ============================================================================
+
+import type { GizmoMode } from "./index";
+
+/** Minimal renderer interface for data feeds (perf, GC, GPU, telemetry).
+ *  Used by DevToolsDataBridge — games that don't need the full scene inspector
+ *  can pass an adapter implementing only these methods. Only getFPS() is
+ *  required; all other methods are optional and accessed via optional chaining. */
+export interface IDevToolsDataRenderer {
+  getFPS(): number;
+  // All optional — null/undefined = "not available" in the panel
+  getGPUInfo?(): any;
+  getGPUErrors?(): any[];
+  clearGPUErrors?(): void;
+  getFrameTelemetry?(): any;
+  getGPUResourceTracker?(): { getStats(): any } | null;
+  getTelemetryCollector?(): { getPassTimings(): any[]; saveSnapshot(label: string): any; getSnapshots(): any[]; clearSnapshots(): void } | null;
+  getGPUProfiler?(): { getPassTimings(): any[] } | null;
+  getFrameGraph?(): any | null;
+  setDebugMode?(enabled: boolean): void;
+  getGCStats?(): any;
+  setGCConfig?(config: any): void;
+  forceMajorGC?(): void;
+}
+
+/** Full renderer interface for the scene inspector (extends data renderer).
+ *  Used by BaseSceneInspector — games that want the full 3D scene inspector
+ *  pass a renderer implementing all of these methods. */
+export interface IDevToolsRenderer extends IDevToolsDataRenderer {
+  // Gizmo
+  setGizmoPosition(pos: [number, number, number]): void;
+  setGizmoMode(mode: GizmoMode): void;
+  setGizmoVisible(visible: boolean): void;
+
+  // Models
+  uploadModel(nodeId: string, meshes: any[], materials?: any[]): void;
+  removeModel(nodeId: string): void;
+
+  // Player
+  getPlayerWorldPos(viewportIdx: number): { x: number; y: number; z: number } | null;
+
+  // Debug overlays (hitboxes are generic)
+  setShowHitboxes(show: boolean): void;
+  getShowHitboxes(): boolean;
+  setHitboxLineWidth(width: number): void;
+  getHitboxLineWidth(): number;
+  setDebugMode(enabled: boolean): void;
+
+  // GPU / telemetry (required for full inspector; optional on IDevToolsDataRenderer)
+  getGPUInfo(): any;
+  getGPUErrors(): any[];
+  clearGPUErrors(): void;
+  getFrameTelemetry(): any;
+  getGPUResourceTracker(): { getStats(): any } | null;
+  getTelemetryCollector(): { getPassTimings(): any[]; saveSnapshot(label: string): any; getSnapshots(): any[]; clearSnapshots(): void } | null;
+  getGPUProfiler(): { getPassTimings(): any[] } | null;
+  getFrameGraph(): any | null;
+}
+
+/** Asset resolution — games provide this to support model import/thumbnails. */
+export interface IAssetResolver {
+  getAvailableModels(): { path: string; name: string; format: string; url: string }[];
+  syncFetchArrayBuffer(url: string): ArrayBuffer | null;
+  findMTLForOBJ(filename: string, buffer: ArrayBuffer): ArrayBuffer | null;
+  findBinForGLTF(filename: string, buffer: ArrayBuffer): ArrayBuffer | null;
+  getTextureUrl(uri: string): string | null;
+}
+
+/** Optional debug overlay toggles — games that support chunk grid / velocity arrows implement this. */
+export interface IDebugOverlayProvider {
+  setShowChunkGrid(show: boolean): void;
+  getShowChunkGrid(): boolean;
+  setShowVelocityArrows(show: boolean): void;
+  getShowVelocityArrows(): boolean;
+}
+
+/** Optional sim/worker debug mode hook — games with a sim worker implement this. */
+export interface IDebugModeProvider {
+  setDebugMode(enabled: boolean): void;
+  /** Forward GC controller config to the sim worker. Optional. */
+  setGCConfig?(config: any): void;
+  /** Trigger a major GC on the sim worker. Optional. */
+  forceMajorGC?(): void;
+}
+
+/** Optional performance metrics provider — games with multi-process architectures implement this. */
+export interface IPerformanceMetricsProvider {
+  getPerformanceMetrics(): any;
+}
+
+/** Game-specific tab provider — games register custom DevTools tabs via this interface. */
+export interface IGameDevToolsProvider {
+  getTabs(): GameDevToolsTab[];
+}
+
+export interface GameDevToolsTab {
+  id: string;
+  label: string;
+  onActivate(container: HTMLElement): void;
+  onDeactivate(): void;
+}
+
+/**
+ * Game-specific DevTools panel extension.
+ * Games declare tabs with HTML content, CSS, and a JS script that runs
+ * in the DevTools panel context. The script receives DevToolsPanel helpers
+ * and returns lifecycle callbacks.
+ */
+export interface IDevToolsPanelExtension {
+  /** Unique id for this extension (e.g. "debug-info", "game-panel"). */
+  id: string;
+  /** Tab label shown in the tab bar. */
+  tabLabel: string;
+  /** Tab tooltip. */
+  tabTooltip?: string;
+  /** Order/priority for tab placement. Core tabs: 0-100, game tabs: 100+. Default: 100. */
+  order?: number;
+  /** __sceneInspector methods that must exist for this tab to be shown. */
+  requiredMethods?: string[];
+  /** HTML content for the panel body (inserted into a container div). */
+  html: string;
+  /** CSS to inject into the panel document. */
+  css?: string;
+  /**
+   * JS to eval in the panel context. Receives a DevToolsPanelHelpers object
+   * and returns { onActivate?, onDeactivate?, onRefresh?, onDestroy? }.
+   */
+  script?: string;
+}
+
+/**
+ * Game-specific overlay toggle for the overlays dropdown menu.
+ */
+export interface IDevToolsOverlayToggle {
+  /** Unique id (e.g. "chunk-grid", "vel-arrows"). */
+  id: string;
+  /** Label shown next to the checkbox. */
+  label: string;
+  /** __sceneInspector methods that must exist for this toggle to be shown. */
+  requiredMethods?: string[];
+  /**
+   * JS to eval in the panel context. Receives DevToolsPanelHelpers.
+   * Should set up a checkbox listener on #chk-{id} that calls callInspector.
+   */
+  script?: string;
+}
+
+// --- Debug Overlay Data Providers ---
+
+/** Provides entity data for the 2D debug overlay (chunk grid + velocity arrows). */
+export interface IDebugOverlayData {
+  getEntityCount(): number;
+  getEntityPosition(i: number): { x: number; y: number; z: number } | null;
+  getEntityVelocity(i: number): { x: number; y: number; z: number } | null;
+  getPlayerPosition(): { x: number; z: number } | null;
+  getChunkGridConfig(): { chunkSize: number; chunksVisible: number };
+}
+
+/** Provides camera state for debug overlays. */
+export interface IDebugCamera {
+  position: [number, number, number];
+  heading: number;
+  pitch: number;
+  fov: number;
+  aspect: number;
+  near: number;
+  far: number;
+}
+
+// --- Debug Raycast Providers ---
+
+/** Result of a raycast against entities. */
+export interface IRaycastResult {
+  entityIndex: number;
+  entityId: number;
+  entityType: number;
+  worldX: number;
+  worldY: number;
+  worldZ: number;
+  distance: number;
+  posX: number;
+  posY: number;
+  posZ: number;
+  scale: number;
+}
+
+/** Provides entity raycast queries for the debug ray visualizer. */
+export interface IRaycastProvider {
+  raycast(
+    ox: number, oy: number, oz: number,
+    dx: number, dy: number, dz: number,
+    maxDist: number,
+  ): IRaycastResult | null;
+}
+
+// --- Label Overlay Providers ---
+
+/** A single label entry for the HTML label overlay. */
+export interface ILabelEntry {
+  key: string;
+  text: string;
+  color: string;
+  x: number;
+  y: number;
+  z: number;
+}
+
+/** Provides label data for the HTML label overlay. */
+export interface ILabelProvider {
+  getLabels(): ILabelEntry[];
+}
+
+// --- Scene Sync Providers ---
+
+/** Entity snapshot for scene store sync. */
+export interface ISceneEntitySnapshot {
+  id: number;
+  type: number;
+  typeName: string;
+  position: [number, number, number];
+  rotation: [number, number, number, number];
+  scale: number;
+}
+
+/** Provides entity snapshots and player camera for scene sync + gizmo interaction. */
+export interface ISceneSyncProvider {
+  getEntitySnapshots(): ISceneEntitySnapshot[];
+  getPlayerCamera(): {
+    position: { x: number; y: number; z: number };
+    heading: number;
+    pitch: number;
+    cameraMode: number;
+  } | null;
+}
+
+// --- Asset Utility Providers ---
+
+/** Provides model/texture/bin URL maps for asset resolution. */
+export interface IAssetUrlMaps {
+  textureUrlMap: Map<string, string>;
+  mtlUrlMap: Map<string, string>;
+  binUrlMap: Map<string, string>;
+}
+
+/** Combined provider interface that games implement for game-specific devtools features. */
+export interface IGameDevToolsExtension {
+  assetResolver?: IAssetResolver;
+  debugOverlayProvider?: IDebugOverlayProvider;
+  debugModeProvider?: IDebugModeProvider;
+  performanceMetricsProvider?: IPerformanceMetricsProvider;
+  tabProvider?: IGameDevToolsProvider;
+}
+
+// --- Sim Stats & Controls ---
+
+/** Snapshot of simulation state for the DevTools "Sim" tab. */
+export interface ISimStats {
+  /** Sim ticks per second (worker-side, may differ from render FPS). */
+  fps: number;
+  /** Total tick count since sim start. */
+  tick: number;
+  /** Total frame count since sim start. */
+  frame: number;
+  /** Whether the sim is currently paused. */
+  paused: boolean;
+  /** Current speed multiplier (1.0 = normal). */
+  speed: number;
+  /** Game-specific extra rows (grid dims, entity count, player pos, etc.). */
+  extra?: Record<string, any>;
+}
+
+/**
+ * Provides sim stats and control methods for the DevTools "Sim" tab.
+ * Any sim-driven game (2D or 3D) can implement this; the reusable
+ * `createSimStatsPanelExtension()` factory renders the tab.
+ */
+export interface ISimStatsProvider {
+  getSimStats(): ISimStats;
+  pauseSim(): void;
+  resumeSim(): void;
+  /** Advance exactly one tick while paused. Optional. */
+  stepSim?(): void;
+  /** Set the sim speed multiplier (0 = paused-equivalent, 1 = normal). Optional. */
+  setSimSpeed?(speed: number): void;
+  /** Clear/reset the simulation state. Optional. */
+  clearSim?(): void;
+}

package/modules/devtools/src/worker-expose.ts

@@ -0,0 +1,67 @@
+// ============================================================================
+// Worker-side DevTools expose helper — adds the standard __devtools* RPC
+// methods to a worker's expose() API so the renderer can fetch the manifest
+// and forward commands.
+//
+// Data feeds are NOT served via RPC — they're written to the devtools SAB
+// by flushDataFeeds() (called from the sim loop). The renderer reads them
+// synchronously from the SAB. Only the manifest and commands use worker RPC.
+// ============================================================================
+
+import { exposeProfilingApi } from "@downdraft/engine/worker/instrumented-worker-host";
+import type { WorkerApi } from "@downdraft/engine/worker/rpc";
+import { _devtoolsImpl, devtools, type DevToolsManifest } from "./api";
+
+/**
+ * Wrap a worker API object with the standard devtools RPC methods.
+ * Call this inside the worker's expose() setup:
+ *
+ *   expose(exposeDevToolsApi({ init, pause, ... }));
+ */
+export function exposeDevToolsApi<T extends WorkerApi>(api: T): T & {
+  __devtoolsGetManifest(): DevToolsManifest;
+  __devtoolsCallCommand(name: string, args: any[]): any;
+  __devtoolsGetSAB(): SharedArrayBuffer | null;
+  __devtoolsEval(expr: string): Promise<{ result?: any; error?: string }>;
+} {
+  // Merge profiling RPC methods (attachProfilingSAB, addWarningRule, onWarning)
+  // with the devtools RPC methods.
+  return exposeProfilingApi({
+    ...api,
+    __devtoolsGetManifest: (): DevToolsManifest => {
+      return devtools.getManifest();
+    },
+    __devtoolsCallCommand: (name: string, args: any[]): any => {
+      return _devtoolsImpl.callCommand(name, args);
+    },
+    __devtoolsGetSAB: (): SharedArrayBuffer | null => {
+      return devtools.getSAB();
+    },
+    __devtoolsEval: async (expr: string): Promise<{ result?: any; error?: string }> => {
+      try {
+        // Evaluate the expression in the worker's global scope.
+        // Use indirect eval so it runs in the global scope (not closure).
+        // eslint-disable-next-line no-new-func
+        const fn = new Function("return (" + expr + ")");
+        const result = fn();
+        return { result };
+      } catch (err) {
+        return { error: String(err) };
+      }
+    },
+  });
+}
+
+/**
+ * Convenience: attach the devtools SAB to the worker-side registry and
+ * register it so the renderer can discover it via __devtoolsGetSAB().
+ *
+ * Games call this in their worker entry after allocating the devtools SAB:
+ *
+ *   const dtSAB = allocateDevToolsSAB();
+ *   attachDevToolsSAB(dtSAB);
+ *   // Pass dtSAB to the renderer via the init() RPC or a separate message.
+ */
+export function attachDevToolsSAB(sab: SharedArrayBuffer): void {
+  devtools.attachSAB(sab);
+}

package/modules/devtools/src/worker-sync.ts

@@ -0,0 +1,137 @@
+// ============================================================================
+// Renderer-side worker manifest sync — fetches the devtools manifest from
+// one or more sim workers via worker RPC, then wires the worker-registered panels,
+// data feeds, and commands into the renderer-side __sceneInspector API.
+//
+// Data feeds from workers are read from the devtools SAB (zero-copy).
+// Commands are forwarded via worker RPC.
+// Panel declarations are merged into the global registry.
+// ============================================================================
+
+import { createLogger } from "@downdraft/engine/util/logger";
+import { _devtoolsImpl, devtools, type DevToolsManifest } from "./api";
+import type { IDevToolsPanelExtension } from "./types";
+
+const log = createLogger("info");
+
+/** Minimal worker proxy interface for devtools RPC. */
+export interface DevToolsWorkerProxy {
+  __devtoolsGetManifest(): Promise<DevToolsManifest>;
+  __devtoolsCallCommand(name: string, args: any[]): Promise<any>;
+  __devtoolsGetSAB(): Promise<SharedArrayBuffer | null>;
+}
+
+export interface WorkerSyncEntry {
+  /** A prefix for namespacing (e.g. "sim", "backdrop"). Empty = no prefix. */
+  prefix: string;
+  /** The worker proxy (from wrap<T>). */
+  proxy: DevToolsWorkerProxy;
+  /** The devtools SAB shared with this worker (if known). */
+  sab?: SharedArrayBuffer | null;
+}
+
+/**
+ * Sync manifests from one or more workers into the renderer-side devtools
+ * registry. Called once during initDevTools(). Returns a function to
+ * re-sync on hot-reload.
+ */
+export async function syncWorkerManifests(
+  entries: WorkerSyncEntry[],
+): Promise<() => Promise<void>> {
+  for (let _i = 0, _it = entries, _n = _it.length; _i < _n; _i++) { const entry = _it[_i];
+    await syncOneWorker(entry);
+  }
+
+  // Return a re-sync function for hot-reload
+  return async () => {
+    for (let _i = 0, _it = entries, _n = _it.length; _i < _n; _i++) { const entry = _it[_i];
+      await syncOneWorker(entry);
+    }
+  };
+}
+
+async function syncOneWorker(entry: WorkerSyncEntry): Promise<void> {
+  const { prefix, proxy } = entry;
+
+  let manifest: DevToolsManifest;
+  try {
+    manifest = await proxy.__devtoolsGetManifest();
+  } catch (e) {
+    log.warn("devtools", `Failed to fetch manifest from worker "${prefix}": ${e}`);
+    return;
+  }
+
+  // Fetch the devtools SAB from the worker (allocated and attached there)
+  let sab: SharedArrayBuffer | null = entry.sab ?? null;
+  if (!sab) {
+    try {
+      sab = await proxy.__devtoolsGetSAB();
+    } catch {
+      // Worker may not have a devtools SAB (older workers)
+    }
+  }
+
+  // Register panels (namespaced by prefix to avoid collisions)
+  manifest.panels.forEach((panel) => {
+    const namespaced: IDevToolsPanelExtension = prefix
+      ? { ...panel, id: `${prefix}:${panel.id}` }
+      : panel;
+    devtools.registerPanel(namespaced);
+  });
+
+  // Register data feed readers — these read from the SAB synchronously
+  // We register them as main-realm data feeds that read from the worker SAB
+  if (sab) {
+    manifest.dataFeeds.forEach((feed) => {
+      const feedIndex = feed.feedIndex;
+      const readName = prefix ? `${prefix}:${feed.name}` : feed.name;
+      // Register a main-realm data feed that reads from the worker's SAB
+      _devtoolsImpl.registerDataFeed(readName, () => {
+        return readDataFeedFromSAB(sab, feedIndex);
+      }, 0); // writeRateHz=0 means "read on demand" (no polling needed)
+    });
+
+    // Register SAB stat readers
+    manifest.sabStats.forEach((stat) => {
+      const statName = prefix ? `${prefix}:${stat.name}` : stat.name;
+      _devtoolsImpl.registerSABStat(statName, stat.offset, stat.type);
+    });
+  }
+
+  // Register command forwarders — these call the worker via RPC
+  manifest.commands.forEach((cmdName) => {
+    const namespacedCmd = prefix ? `${prefix}:${cmdName}` : cmdName;
+    _devtoolsImpl.registerCommand(namespacedCmd, (...args: any[]) => {
+      // Fire-and-forget (commands return void in the panel context)
+      proxy.__devtoolsCallCommand(cmdName, args).catch((e) => {
+        log.warn("devtools", `Worker command "${cmdName}" failed: ${e}`);
+      });
+    });
+  });
+}
+
+/**
+ * Read a data feed value from a devtools SAB.
+ * The SAB layout is the standard one from computeDevToolsSABLayout().
+ */
+function readDataFeedFromSAB(sab: SharedArrayBuffer, feedIndex: number): any {
+  const u32 = new Uint32Array(sab);
+  const u8 = new Uint8Array(sab);
+
+  // Layout: header (8 bytes) + feed entries
+  // Each feed entry: [lengthBytes: u32][JSON blob...]
+  const feedEntryBytes = 4 + 4096; // DEVTOOLS_SAB_FEED_HEADER_BYTES + DEVTOOLS_SAB_DEFAULT_FEED_BLOB_BYTES
+  const entryByteOffset = 8 + feedIndex * feedEntryBytes;
+  const lengthBytes = u32[entryByteOffset / 4];
+
+  if (lengthBytes === 0 || lengthBytes === 0xFFFFFFFF) return null;
+
+  const blobOffset = entryByteOffset + 4;
+  const jsonBytes = u8.subarray(blobOffset, blobOffset + lengthBytes);
+  try {
+    const json = new TextDecoder().decode(jsonBytes);
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}

package/modules/editor/src/commands/component.ts

@@ -0,0 +1,156 @@
+// ============================================================================
+// Component commands — add / set (merge-patch) / remove / inspect.
+//
+// `component.set` merges `changes` into existing data and inverses with the
+// captured old data — the workhorse behind inspector edits and gizmo drags.
+// ============================================================================
+
+import { sanitizeObject } from "@downdraft/engine";
+
+import type { EditorContext } from "../editor-context";
+import type { EditorCommand } from "./registry";
+
+function readComponent(ctx: EditorContext, entityKey: string, componentName: string): Record<string, unknown> | null {
+  const entity = ctx.parseEntity(entityKey);
+  if (!entity) return null;
+  const cid = ctx.engine.getComponentIdByName(componentName);
+  const data = ctx.engine.ecsWorld.getComponent<Record<string, unknown>>(entity, cid);
+  return data ? (sanitizeObject({ ...data }) as Record<string, unknown>) : null;
+}
+
+export function createComponentCommands(): EditorCommand[] {
+  return [
+    {
+      id: "component.add",
+      title: "Add Component",
+      mutating: true,
+      params: {
+        type: "object",
+        properties: {
+          entity: { type: "string" },
+          component: { type: "string" },
+          data: { type: "object", description: "Initial component data" },
+        },
+        required: ["entity", "component"],
+      },
+      apply(ctx, params) {
+        const key = params.entity as string;
+        const entity = ctx.parseEntity(key);
+        if (!entity || !ctx.isAliveKey(key)) throw new Error(`Entity ${key} not found or dead`);
+        const name = params.component as string;
+        const cid = ctx.engine.getComponentIdByName(name);
+        if (ctx.engine.ecsWorld.hasComponent(entity, cid)) {
+          throw new Error(`Entity ${key} already has component "${name}"`);
+        }
+        const data = sanitizeObject({ ...(params.data as Record<string, unknown> | undefined) });
+        ctx.engine.ecsWorld.addComponent(entity, cid, data);
+        ctx.engine.ecsWorld.flushCommands();
+        ctx.document.markDirty({ kind: "data", entity: key });
+        ctx.adapter?.syncEntity?.(key);
+        return {
+          value: { entity: key, component: name },
+          inverse: [{ command: "component.remove", params: { entity: key, component: name } }],
+          description: `Add ${name} to ${key}`,
+        };
+      },
+    },
+
+    {
+      id: "component.set",
+      title: "Set Component Data",
+      mutating: true,
+      params: {
+        type: "object",
+        properties: {
+          entity: { type: "string" },
+          component: { type: "string" },
+          changes: { type: "object", description: "Partial data merged into the component" },
+        },
+        required: ["entity", "component", "changes"],
+      },
+      apply(ctx, params) {
+        const key = params.entity as string;
+        const name = params.component as string;
+        const entity = ctx.parseEntity(key);
+        if (!entity || !ctx.isAliveKey(key)) throw new Error(`Entity ${key} not found or dead`);
+
+        const oldData = readComponent(ctx, key, name);
+        if (oldData === null) throw new Error(`Entity ${key} has no component "${name}"`);
+
+        const changes = sanitizeObject({ ...(params.changes as Record<string, unknown>) });
+        const newData = sanitizeObject({ ...oldData, ...changes });
+        const cid = ctx.engine.getComponentIdByName(name);
+        ctx.engine.ecsWorld.setComponent(entity, cid, newData);
+        ctx.engine.ecsWorld.flushCommands();
+        ctx.document.markDirty({ kind: "data", entity: key });
+        ctx.adapter?.syncEntity?.(key);
+        return {
+          value: { entity: key, component: name, updated: Object.keys(changes) },
+          inverse: [{ command: "component.set", params: { entity: key, component: name, changes: oldData } }],
+          description: `Set ${name} on ${key}`,
+        };
+      },
+    },
+
+    {
+      id: "component.remove",
+      title: "Remove Component",
+      mutating: true,
+      params: {
+        type: "object",
+        properties: {
+          entity: { type: "string" },
+          component: { type: "string" },
+        },
+        required: ["entity", "component"],
+      },
+      apply(ctx, params) {
+        const key = params.entity as string;
+        const name = params.component as string;
+        const entity = ctx.parseEntity(key);
+        if (!entity || !ctx.isAliveKey(key)) throw new Error(`Entity ${key} not found or dead`);
+        const oldData = readComponent(ctx, key, name);
+        if (oldData === null) throw new Error(`Entity ${key} has no component "${name}"`);
+
+        const cid = ctx.engine.getComponentIdByName(name);
+        ctx.engine.ecsWorld.removeComponent(entity, cid);
+        ctx.engine.ecsWorld.flushCommands();
+        ctx.document.markDirty({ kind: "data", entity: key });
+        ctx.adapter?.syncEntity?.(key);
+        return {
+          value: { entity: key, component: name, removed: true },
+          inverse: [{ command: "component.add", params: { entity: key, component: name, data: oldData } }],
+          description: `Remove ${name} from ${key}`,
+        };
+      },
+    },
+
+    {
+      id: "component.list",
+      title: "List Components on Entity",
+      mutating: false,
+      params: {
+        type: "object",
+        properties: { entity: { type: "string" } },
+        required: ["entity"],
+      },
+      apply(ctx, params) {
+        const key = params.entity as string;
+        const entity = ctx.parseEntity(key);
+        if (!entity || !ctx.isAliveKey(key)) throw new Error(`Entity ${key} not found or dead`);
+        const arch = ctx.engine.ecsWorld.getArchetypeForEntity(entity);
+        const components: Record<string, unknown> = {};
+        if (arch) {
+          const row = arch.entities.findIndex((e) => e.index === entity.index && e.generation === entity.generation);
+          if (row >= 0) {
+            for (const [cid] of arch.columns.entries()) {
+              components[ctx.engine.getComponentNameById(cid)] =
+                sanitizeObject(ctx.engine.ecsWorld.getComponent(entity, cid) ?? {});
+            }
+          }
+        }
+        return { value: { entity: key, components } };
+      },
+    },
+  ];
+}