@downdraft/engine 0.0.0 → 0.1.1

package/mcp/src/prompts/add-entity.ts

@@ -0,0 +1,42 @@
+import type { PromptRegistration } from "../types";
+
+export function createAddEntityPrompt(): PromptRegistration[] {
+  return [
+    {
+      def: {
+        name: "add-entity",
+        description: "Template for adding a new entity to the current scene",
+        arguments: [
+          { name: "entityType", description: "Type of entity (cube, sphere, plane, custom)", required: true },
+          { name: "position", description: "Position as 'x,y,z'" },
+          { name: "material", description: "Material type (pbr, unlit, etc.)" },
+        ],
+      },
+      handler: (args) => {
+        const entityType = args.entityType ?? "cube";
+        const position = args.position ?? "0,0,0";
+        const material = args.material ?? "pbr";
+
+        return {
+          messages: [
+            {
+              role: "user",
+              content: {
+                type: "text",
+                text: `Add a ${entityType} entity to the scene at position (${position}) with a ${material} material.
+
+Steps:
+1. Generate a procedural ${entityType} mesh (generate_procedural_mesh)
+2. Spawn an entity with a Transform component at position (${position}) (spawn_entity)
+3. Assign the mesh to the entity (assign_mesh)
+4. Create a ${material} material (create_material)
+5. Assign the material to the entity (assign_material)
+6. Verify with get_entity_state`,
+              },
+            },
+          ],
+        };
+      },
+    },
+  ];
+}

package/mcp/src/prompts/create-scene.ts

@@ -0,0 +1,44 @@
+import type { PromptRegistration } from "../types";
+
+export function createCreateScenePrompt(): PromptRegistration[] {
+  return [
+    {
+      def: {
+        name: "create-scene",
+        description: "Template for creating a new scene with entities, lighting, and camera",
+        arguments: [
+          { name: "sceneName", description: "Name of the scene to create", required: true },
+          { name: "description", description: "Description of what the scene should contain" },
+        ],
+      },
+      handler: (args) => {
+        const sceneName = args.sceneName ?? "my-scene";
+        const description = args.description ?? "a basic scene with lighting";
+
+        return {
+          messages: [
+            {
+              role: "user",
+              content: {
+                type: "text",
+                text: `Create a scene called "${sceneName}" that contains ${description}.
+
+Steps:
+1. Use create_scene to create a new scene named "${sceneName}"
+2. Generate procedural meshes as needed (generate_procedural_mesh)
+3. Spawn entities with Transform components (spawn_entity)
+4. Assign meshes to entities (assign_mesh)
+5. Create and assign materials (create_material, assign_material)
+6. Add lighting (add_light or set_sun_angle)
+7. Position the camera to frame the scene (set_camera)
+8. Create a checkpoint (create_checkpoint)
+
+Use the available MCP tools to accomplish each step.`,
+              },
+            },
+          ],
+        };
+      },
+    },
+  ];
+}

package/mcp/src/prompts/debug-frame.ts

@@ -0,0 +1,39 @@
+import type { PromptRegistration } from "../types";
+
+export function createDebugFramePrompt(): PromptRegistration[] {
+  return [
+    {
+      def: {
+        name: "debug-frame",
+        description: "Template for debugging why a frame is slow or rendering incorrectly",
+        arguments: [
+          { name: "symptom", description: "What's wrong (slow, black screen, flickering, etc.)", required: true },
+        ],
+      },
+      handler: (args) => {
+        const symptom = args.symptom ?? "the frame is slow";
+
+        return {
+          messages: [
+            {
+              role: "user",
+              content: {
+                type: "text",
+                text: `Debug why ${symptom}.
+
+Steps:
+1. Use profile_frame to get per-system timings and frame time
+2. Use get_performance_history to see frame time trends
+3. Use get_telemetry to check GC pauses, memory, and CPU per thread
+4. Use get_scene_tree to verify entity count is expected
+5. Use inspect_gpu to check buffer sizes and texture memory
+6. If a specific system is slow, use inspect_object to examine related entities
+7. Suggest optimizations based on findings`,
+              },
+            },
+          ],
+        };
+      },
+    },
+  ];
+}

package/mcp/src/prompts/index.ts

@@ -0,0 +1,12 @@
+import type { PromptRegistration } from "../types";
+import { createCreateScenePrompt } from "./create-scene";
+import { createAddEntityPrompt } from "./add-entity";
+import { createDebugFramePrompt } from "./debug-frame";
+
+export function createPrompts(): PromptRegistration[] {
+  return [
+    ...createCreateScenePrompt(),
+    ...createAddEntityPrompt(),
+    ...createDebugFramePrompt(),
+  ];
+}

package/mcp/src/resources/asset-list.ts

@@ -0,0 +1,32 @@
+import type { EngineContext } from "../engine-context";
+import type { ResourceRegistration, MCPResourceResult } from "../types";
+
+function resourceJSON(uri: string, data: unknown): MCPResourceResult {
+  return {
+    contents: [{
+      uri,
+      mimeType: "application/json",
+      text: JSON.stringify(data, null, 2),
+    }],
+  };
+}
+
+export function createAssetListResource(ctx: EngineContext): ResourceRegistration[] {
+  return [
+    {
+      def: {
+        uri: "downdraft://asset-list",
+        name: "Asset Inventory",
+        description: "All loaded assets",
+        mimeType: "application/json",
+      },
+      handler: (uri) => {
+        return resourceJSON(uri, {
+          assets: ctx.assetManager.list(),
+          meshes: [...ctx.meshes.keys()],
+          materials: ctx.materialLibrary.list().map((m) => m.name),
+        });
+      },
+    },
+  ];
+}

package/mcp/src/resources/checkpoint-list.ts

@@ -0,0 +1,33 @@
+import type { EngineContext } from "../engine-context";
+import type { ResourceRegistration, MCPResourceResult } from "../types";
+
+function resourceJSON(uri: string, data: unknown): MCPResourceResult {
+  return {
+    contents: [{
+      uri,
+      mimeType: "application/json",
+      text: JSON.stringify(data, null, 2),
+    }],
+  };
+}
+
+export function createCheckpointListResource(ctx: EngineContext): ResourceRegistration[] {
+  return [
+    {
+      def: {
+        uri: "downdraft://checkpoint-list",
+        name: "Checkpoint List",
+        description: "Available checkpoints + undo/redo history",
+        mimeType: "application/json",
+      },
+      handler: (uri) => {
+        const checkpoints = ctx.checkpointManager.list().map((cp) => ({
+          name: cp.name,
+          timestamp: cp.timestamp,
+          entityCount: cp.entities.length,
+        }));
+        return resourceJSON(uri, { checkpoints });
+      },
+    },
+  ];
+}

package/mcp/src/resources/entity-state.ts

@@ -0,0 +1,55 @@
+import { getColumnValue } from "@downdraft/engine";
+import type { EngineContext } from "../engine-context";
+import type { MCPResourceResult, ResourceRegistration } from "../types";
+
+function resourceJSON(uri: string, data: unknown): MCPResourceResult {
+  return {
+    contents: [{
+      uri,
+      mimeType: "application/json",
+      text: JSON.stringify(data, null, 2),
+    }],
+  };
+}
+
+export function createEntityStateResource(ctx: EngineContext): ResourceRegistration[] {
+  return [
+    {
+      def: {
+        uri: "downdraft://entity-state",
+        name: "Entity State",
+        description: "Entity component dump (all entities, all components)",
+        mimeType: "application/json",
+      },
+      handler: (uri) => {
+        const entities = ctx.getAllAliveEntities();
+        const dump: Record<string, unknown> = {};
+
+        entities.forEach((e) => {
+          const key = ctx.getEntityKey(e);
+          const arch = ctx.ecsWorld.getArchetypeForEntity(e);
+          const components: Record<string, unknown> = {};
+
+          if (arch) {
+            for (const [cid, col] of arch.columns.entries()) {
+              const row = arch.entities.findIndex(
+                (en) => en.index === e.index && en.generation === e.generation,
+              );
+              if (row >= 0) {
+                components[ctx.getComponentNameById(cid)] = getColumnValue(col, row);
+              }
+            }
+          }
+
+          dump[key] = {
+            components,
+            mesh: ctx.entityMeshes.get(key) ?? null,
+            material: ctx.entityMaterials.get(key) ?? null,
+          };
+        });
+
+        return resourceJSON(uri, dump);
+      },
+    },
+  ];
+}

package/mcp/src/resources/gpu-info.ts

@@ -0,0 +1,103 @@
+import type { EngineContext } from "../engine-context";
+import type { MCPResourceResult, ResourceRegistration } from "../types";
+
+function resourceJSON(uri: string, data: unknown): MCPResourceResult {
+  return {
+    contents: [{
+      uri,
+      mimeType: "application/json",
+      text: JSON.stringify(data, null, 2),
+    }],
+  };
+}
+
+async function queryNvidiaSmi(): Promise<Record<string, unknown> | null> {
+  try {
+    const { execSync } = await import("child_process");
+    const gpuQuery = "utilization.gpu,memory.used,memory.total,temperature.gpu,power.draw,clocks.sm,clocks.mem,name,driver_version";
+    const output = execSync(
+      `nvidia-smi --query-gpu=${gpuQuery} --format=csv,noheader,nounits`,
+      { timeout: 3000, encoding: "utf-8" },
+    ).trim();
+
+    const labels = gpuQuery.split(",");
+    const gpus = output.split("\n").map((line) => {
+      const vals = line.trim().split(",").map((v) => v.trim());
+      const obj: Record<string, unknown> = {};
+      for (let i = 0; i < labels.length && i < vals.length; i++) {
+        const num = parseFloat(vals[i]);
+        obj[labels[i]] = isNaN(num) ? vals[i] : num;
+      }
+      return obj;
+    });
+
+    return { gpus, source: "nvidia-smi" };
+  } catch {
+    return null;
+  }
+}
+
+async function queryNvidiaSmiProcesses(): Promise<Array<Record<string, unknown>> | null> {
+  try {
+    const { execSync } = await import("child_process");
+    const output = execSync(
+      "nvidia-smi --query-compute-apps=pid,process_name,used_memory --format=csv,noheader,nounits",
+      { timeout: 3000, encoding: "utf-8" },
+    ).trim();
+
+    if (!output) return [];
+    const procs = output.split("\n").map((line) => {
+      const vals = line.trim().split(",").map((v) => v.trim());
+      return {
+        pid: parseInt(vals[0]) || 0,
+        processName: vals[1] || "",
+        usedMemoryMB: parseFloat(vals[2]) || 0,
+      };
+    });
+    return procs;
+  } catch {
+    return null;
+  }
+}
+
+async function queryHostGpuInfo(): Promise<Record<string, unknown> | null> {
+  try {
+    const bridge = (globalThis as { downdraft?: { getGpuInfo?: () => Promise<Record<string, unknown> | null> } }).downdraft;
+    if (typeof bridge?.getGpuInfo === "function") {
+      return await bridge.getGpuInfo();
+    }
+  } catch {
+    // No host bridge installed
+  }
+  return null;
+}
+
+export function createGPUInfoResource(ctx: EngineContext): ResourceRegistration[] {
+  return [
+    {
+      def: {
+        uri: "downdraft://gpu-info",
+        name: "GPU Info",
+        description: "Real-time GPU system metrics: utilization, VRAM, temperature, power, clocks, per-process VRAM, host GPU info, and engine resource counts",
+        mimeType: "application/json",
+      },
+      handler: async (uri) => {
+        const nvidia = await queryNvidiaSmi();
+        const processes = await queryNvidiaSmiProcesses();
+        const hostGPU = await queryHostGpuInfo();
+
+        return resourceJSON(uri, {
+          nvidiaSmi: nvidia,
+          hostGPU: hostGPU,
+          processes: processes,
+          engineResources: {
+            meshes: ctx.meshes.size,
+            materials: ctx.materialLibrary.list().length,
+          },
+          timestamp: Date.now(),
+          note: "For live WebGPU adapter info, device limits, resource tracking, and GPU errors, use the DevTools GPU tab or SceneInspector API (getGPUInfo, getGPUErrors, getFrameTelemetry, getGPUResourceStats).",
+        });
+      },
+    },
+  ];
+}

package/mcp/src/resources/index.ts

@@ -0,0 +1,57 @@
+import type { EngineContext } from "../engine-context";
+import type { ResourceRegistration, MCPResourceResult } from "../types";
+import { createSceneTreeResource } from "./scene-tree";
+import { createEntityStateResource } from "./entity-state";
+import { createPerformanceResource } from "./performance";
+import { createGPUInfoResource } from "./gpu-info";
+import { createAssetListResource } from "./asset-list";
+import { createCheckpointListResource } from "./checkpoint-list";
+
+function resourceJSON(uri: string, data: unknown): MCPResourceResult {
+  return {
+    contents: [{
+      uri,
+      mimeType: "application/json",
+      text: JSON.stringify(data, null, 2),
+    }],
+  };
+}
+
+export function createResources(ctx: EngineContext): ResourceRegistration[] {
+  return [
+    ...createSceneTreeResource(ctx),
+    ...createEntityStateResource(ctx),
+    ...createPerformanceResource(ctx),
+    ...createGPUInfoResource(ctx),
+    ...createAssetListResource(ctx),
+    ...createCheckpointListResource(ctx),
+
+    {
+      def: {
+        uri: "downdraft://crash-events",
+        name: "Crash Events",
+        description: "Sim-worker crash events and recovery status",
+        mimeType: "application/json",
+      },
+      handler: (uri) => {
+        return resourceJSON(uri, {
+          crashes: [],
+          recoveryState: "idle",
+          note: "No crash events recorded. Crash recovery requires a running sim worker.",
+        });
+      },
+    },
+
+    {
+      def: {
+        uri: "downdraft://telemetry",
+        name: "Telemetry",
+        description: "Per-thread GC, memory, CPU metrics",
+        mimeType: "application/json",
+      },
+      handler: (uri) => {
+        return resourceJSON(uri, ctx.telemetryReporter.getMCPFormat());
+      },
+    },
+  ];
+}

package/mcp/src/resources/performance.ts

@@ -0,0 +1,37 @@
+import type { EngineContext } from "../engine-context";
+import type { ResourceRegistration, MCPResourceResult } from "../types";
+
+function resourceJSON(uri: string, data: unknown): MCPResourceResult {
+  return {
+    contents: [{
+      uri,
+      mimeType: "application/json",
+      text: JSON.stringify(data, null, 2),
+    }],
+  };
+}
+
+export function createPerformanceResource(ctx: EngineContext): ResourceRegistration[] {
+  return [
+    {
+      def: {
+        uri: "downdraft://performance",
+        name: "Performance Metrics",
+        description: "Frame timings, system timings, and entity count",
+        mimeType: "application/json",
+      },
+      handler: (uri) => {
+        const snap = ctx.telemetryReporter.getSnapshot();
+        return resourceJSON(uri, {
+          tick: ctx.ecsWorld.tick,
+          entityCount: ctx.ecsWorld.entityCount(),
+          frameTime: snap.averageFrameTime,
+          p95FrameTime: snap.p95FrameTime,
+          p99FrameTime: snap.p99FrameTime,
+          systemTimings: snap.systemTimings,
+          frameTimeHistory: snap.frameTimes,
+        });
+      },
+    },
+  ];
+}

package/mcp/src/resources/scene-tree.ts

@@ -0,0 +1,43 @@
+import type { EngineContext } from "../engine-context";
+import type { MCPResourceResult, ResourceRegistration } from "../types";
+
+function resourceJSON(uri: string, data: unknown): MCPResourceResult {
+  return {
+    contents: [{
+      uri,
+      mimeType: "application/json",
+      text: JSON.stringify(data, null, 2),
+    }],
+  };
+}
+
+export function createSceneTreeResource(ctx: EngineContext): ResourceRegistration[] {
+  return [
+    {
+      def: {
+        uri: "downdraft://scene-tree",
+        name: "Scene Tree",
+        description: "Live scene hierarchy (parent/child tree)",
+        mimeType: "application/json",
+      },
+      handler: (uri) => {
+        const entities = ctx.getAllAliveEntities();
+        const tree: Array<{ entity: string; parent: string; children: string[]; components: string[] }> = [];
+
+        entities.forEach((e) => {
+          const arch = ctx.ecsWorld.getArchetypeForEntity(e);
+          const compNames = arch ? [...arch.columns.keys()].map((id) => ctx.getComponentNameById(id)) : [];
+          const parent = ctx.hierarchy.getParent(e);
+          tree.push({
+            entity: ctx.getEntityKey(e),
+            parent: parent ? ctx.getEntityKey(parent) : "root",
+            children: ctx.hierarchy.getChildren(e).map((c) => ctx.getEntityKey(c)),
+            components: compNames,
+          });
+        });
+
+        return resourceJSON(uri, { scene: ctx.scene.name, entities: tree });
+      },
+    },
+  ];
+}