@downdraft/engine 0.0.0 → 0.1.0

package/mcp/src/server.ts

@@ -0,0 +1,375 @@
+import { EngineContext } from "./engine-context";
+import type {
+    MCPPromptDef,
+    MCPPromptResult,
+    MCPResourceDef,
+    MCPResourceResult,
+    MCPToolDef,
+    MCPToolResult,
+    PromptRegistration,
+    ResourceRegistration,
+    ToolRegistration,
+} from "./types";
+import { UndoRedoManager } from "./undo-redo";
+
+import { createPrompts } from "./prompts/index";
+import { createResources } from "./resources/index";
+import { createAnimationTools } from "./tools/animation";
+import { createAssetTools } from "./tools/asset";
+import { createAudioTools } from "./tools/audio";
+import { createBuildTools } from "./tools/build";
+import { createCameraTools } from "./tools/camera";
+import { createCheckpointTools } from "./tools/checkpoint";
+import { createComponentTools } from "./tools/component";
+import { createDebugTools } from "./tools/debug";
+import { createEntityTools } from "./tools/entity";
+import { createInspectTools } from "./tools/inspect";
+import { createLightingTools } from "./tools/lighting";
+import { createMaterialTools } from "./tools/material";
+import { createMeshTools } from "./tools/mesh";
+import { createPhysicsTools } from "./tools/physics";
+import { createSceneTools } from "./tools/scene";
+import { createScriptTools } from "./tools/script";
+
+export interface MCPServerOptions {
+  enableTelemetry?: boolean;
+  sceneName?: string;
+  engineContext?: EngineContext;
+  /** Additional tools to register alongside the standard engine toolset. */
+  extraTools?: ToolRegistration[];
+}
+
+interface JSONRPCRequest {
+  jsonrpc: "2.0";
+  id?: number | string;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+interface JSONRPCResponse {
+  jsonrpc: "2.0";
+  id: number | string;
+  result?: unknown;
+  error?: { code: number; message: string };
+}
+
+const PROTOCOL_VERSION = "2024-11-05";
+const SERVER_NAME = "downdraft-mcp";
+const SERVER_VERSION = "0.1.0";
+
+export class MCPServer {
+  private opts: MCPServerOptions;
+  private ctx: EngineContext;
+  private undoRedo: UndoRedoManager;
+  private tools: Map<string, ToolRegistration> = new Map();
+  private resources: Map<string, ResourceRegistration> = new Map();
+  private prompts: Map<string, PromptRegistration> = new Map();
+  private started: boolean = false;
+  private initialized: boolean = false;
+  private inputBuffer: string = "";
+
+  constructor(opts: MCPServerOptions = {}) {
+    this.opts = opts;
+    this.ctx = opts.engineContext ?? new EngineContext(opts);
+    this.undoRedo = new UndoRedoManager(this.ctx);
+    this.registerAllTools();
+    this.registerAllResources();
+    this.registerAllPrompts();
+  }
+
+  private registerAllTools(): void {
+    const allTools: ToolRegistration[] = [
+      ...createSceneTools(this.ctx, this.undoRedo),
+      ...createEntityTools(this.ctx, this.undoRedo),
+      ...createComponentTools(this.ctx, this.undoRedo),
+      ...createMaterialTools(this.ctx, this.undoRedo),
+      ...createMeshTools(this.ctx, this.undoRedo),
+      ...createLightingTools(this.ctx, this.undoRedo),
+      ...createCameraTools(this.ctx, this.undoRedo),
+      ...createPhysicsTools(this.ctx, this.undoRedo),
+      ...createDebugTools(this.ctx, this.undoRedo),
+      ...createInspectTools(this.ctx),
+      ...createCheckpointTools(this.ctx, this.undoRedo),
+      ...createScriptTools(this.ctx),
+      ...createAssetTools(this.ctx),
+      ...createAudioTools(this.ctx),
+      ...createAnimationTools(this.ctx),
+      ...createBuildTools(this.ctx),
+      ...(this.opts?.extraTools ?? []),
+    ];
+
+    allTools.forEach((tool) => {
+      this.tools.set(tool.def.name, tool);
+    });
+  }
+
+  private registerAllResources(): void {
+    const allResources = createResources(this.ctx);
+    allResources.forEach((res) => {
+      this.resources.set(res.def.uri, res);
+    });
+  }
+
+  private registerAllPrompts(): void {
+    const allPrompts = createPrompts();
+    allPrompts.forEach((prompt) => {
+      this.prompts.set(prompt.def.name, prompt);
+    });
+  }
+
+  getEngineContext(): EngineContext {
+    return this.ctx;
+  }
+
+  getUndoRedoManager(): UndoRedoManager {
+    return this.undoRedo;
+  }
+
+  listTools(): MCPToolDef[] {
+    return [...this.tools.values()].map((t) => t.def);
+  }
+
+  listResources(): MCPResourceDef[] {
+    return [...this.resources.values()].map((r) => r.def);
+  }
+
+  listPrompts(): MCPPromptDef[] {
+    return [...this.prompts.values()].map((p) => p.def);
+  }
+
+  async callTool(name: string, params: Record<string, unknown>): Promise<MCPToolResult> {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+    }
+    const validationError = this.validateToolParams(tool, params);
+    if (validationError) {
+      return { content: [{ type: "text", text: validationError }], isError: true };
+    }
+    try {
+      return await tool.handler(params);
+    } catch (e) {
+      return {
+        content: [{ type: "text", text: `Tool "${name}" failed: ${(e as Error).message}` }],
+        isError: true,
+      };
+    }
+  }
+
+  private validateToolParams(tool: ToolRegistration, params: Record<string, unknown>): string | null {
+    const schema = tool.def.inputSchema;
+    if (!schema || schema.type !== "object") return null;
+    const required = schema.required ?? [];
+    const properties = schema.properties ?? {};
+    for (let _i = 0, _it = required, _n = _it.length; _i < _n; _i++) { const req = _it[_i];
+      if (!(req in params)) {
+        return `Missing required parameter: ${req}`;
+      }
+      const propSchema = properties[req] as { type?: string } | undefined;
+      if (propSchema?.type) {
+        const actualType = Array.isArray(params[req]) ? "array" : typeof params[req];
+        if (actualType !== propSchema.type) {
+          return `Parameter "${req}" must be of type ${propSchema.type}, got ${actualType}`;
+        }
+      }
+    }
+    return null;
+  }
+
+  async readResource(uri: string): Promise<MCPResourceResult> {
+    const res = this.resources.get(uri);
+    if (!res) {
+      return { contents: [{ uri, text: `Unknown resource: ${uri}` }] };
+    }
+    try {
+      return await res.handler(uri);
+    } catch (e) {
+      return {
+        contents: [{
+          uri,
+          text: `Resource "${uri}" failed: ${(e as Error).message}`,
+        }],
+      };
+    }
+  }
+
+  async getPrompt(name: string, args: Record<string, string>): Promise<MCPPromptResult> {
+    const prompt = this.prompts.get(name);
+    if (!prompt) {
+      return { messages: [{ role: "user", content: { type: "text", text: `Unknown prompt: ${name}` } }] };
+    }
+    try {
+      return await prompt.handler(args);
+    } catch (e) {
+      return {
+        messages: [{
+          role: "user",
+          content: { type: "text", text: `Prompt "${name}" failed: ${(e as Error).message}` },
+        }],
+      };
+    }
+  }
+
+  start(): void {
+    if (this.started) return;
+    this.started = true;
+
+    const stdin = process.stdin;
+    stdin.setEncoding("utf-8");
+    stdin.resume();
+
+    stdin.on("data", (chunk: string) => {
+      this.inputBuffer += chunk;
+      this.processBuffer();
+    });
+
+    stdin.on("end", () => {
+      this.started = false;
+    });
+
+    process.stdout.write(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        id: 0,
+        result: {
+          serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+        },
+      }) + "\n",
+    );
+  }
+
+  stop(): void {
+    this.started = false;
+    this.initialized = false;
+    this.inputBuffer = "";
+    process.stdin.pause();
+  }
+
+  isRunning(): boolean {
+    return this.started;
+  }
+
+  private processBuffer(): void {
+    let newlineIdx: number;
+    while ((newlineIdx = this.inputBuffer.indexOf("\n")) >= 0) {
+      const line = this.inputBuffer.slice(0, newlineIdx).trim();
+      this.inputBuffer = this.inputBuffer.slice(newlineIdx + 1);
+      if (line) {
+        this.handleLine(line).catch((e) => {
+          this.sendError(0, -32603, `Internal error: ${(e as Error).message}`);
+        });
+      }
+    }
+  }
+
+  private async handleLine(line: string): Promise<void> {
+    let msg: JSONRPCRequest;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      this.sendError(0, -32700, "Parse error");
+      return;
+    }
+
+    const id = msg.id ?? 0;
+
+    if (msg.method === "initialize") {
+      this.initialized = true;
+      this.sendResult(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {
+          tools: {},
+          resources: {},
+          prompts: {},
+        },
+        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+      });
+      return;
+    }
+
+    if (!this.initialized) {
+      this.sendError(id, -32000, "Server not initialized");
+      return;
+    }
+
+    switch (msg.method) {
+      case "initialized":
+        return;
+
+      case "tools/list":
+        this.sendResult(id, {
+          tools: this.listTools().map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+          })),
+        });
+        return;
+
+      case "tools/call": {
+        const params = msg.params ?? {};
+        const name = params.name as string;
+        const args = (params.arguments as Record<string, unknown>) ?? {};
+        const result = await this.callTool(name, args);
+        this.sendResult(id, result);
+        return;
+      }
+
+      case "resources/list":
+        this.sendResult(id, {
+          resources: this.listResources().map((r) => ({
+            uri: r.uri,
+            name: r.name,
+            description: r.description,
+            mimeType: r.mimeType,
+          })),
+        });
+        return;
+
+      case "resources/read": {
+        const params = msg.params ?? {};
+        const uri = params.uri as string;
+        const result = await this.readResource(uri);
+        this.sendResult(id, result);
+        return;
+      }
+
+      case "prompts/list":
+        this.sendResult(id, {
+          prompts: this.listPrompts().map((p) => ({
+            name: p.name,
+            description: p.description,
+            arguments: p.arguments,
+          })),
+        });
+        return;
+
+      case "prompts/get": {
+        const params = msg.params ?? {};
+        const name = params.name as string;
+        const args = (params.arguments as Record<string, string>) ?? {};
+        const result = await this.getPrompt(name, args);
+        this.sendResult(id, result);
+        return;
+      }
+
+      case "shutdown":
+        this.initialized = false;
+        this.sendResult(id, {});
+        return;
+
+      default:
+        this.sendError(id, -32601, `Method not found: ${msg.method}`);
+    }
+  }
+
+  private sendResult(id: number | string, result: unknown): void {
+    const response: JSONRPCResponse = { jsonrpc: "2.0", id, result };
+    process.stdout.write(JSON.stringify(response) + "\n");
+  }
+
+  private sendError(id: number | string, code: number, message: string): void {
+    const response: JSONRPCResponse = { jsonrpc: "2.0", id, error: { code, message } };
+    process.stdout.write(JSON.stringify(response) + "\n");
+  }
+}

package/mcp/src/tools/animation.ts

@@ -0,0 +1,118 @@
+import type { EngineContext } from "../engine-context";
+import type { ToolRegistration } from "../types";
+import { errorResult, jsonResult } from "../types";
+
+export function createAnimationTools(ctx: EngineContext): ToolRegistration[] {
+  const tools: ToolRegistration[] = [
+
+    {
+      def: {
+        name: "play_animation",
+        description: "Play an animation clip on an entity with a skeleton.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            entity: { type: "string", description: "Entity key" },
+            clip: { type: "string", description: "Animation clip name" },
+            speed: { type: "number", description: "Playback speed (default: 1.0)" },
+            loop: { type: "boolean", description: "Loop the animation" },
+            blendWeight: { type: "number", description: "Blend weight (0-1)" },
+          },
+          required: ["entity", "clip"],
+        },
+      },
+      handler: (params) => {
+        const entityKey = params.entity as string;
+        const entity = ctx.parseEntityKey(entityKey);
+        if (!entity || !ctx.isEntityAlive(entity)) {
+          return errorResult(`Entity ${entityKey} not found or dead`);
+        }
+
+        const clipName = params.clip as string;
+        const speed = (params.speed as number) ?? 1.0;
+        const loop = (params.loop as boolean) ?? true;
+        const blendWeight = (params.blendWeight as number) ?? 1.0;
+
+        const player = ctx.animationPlayers.get(entityKey);
+        if (!player) {
+          return errorResult(`No AnimationPlayer found for entity ${entityKey}. Attach a skeleton first.`);
+        }
+
+        const playing = player.isPlaying();
+        player.setSpeed(clipName, speed);
+
+        return jsonResult({
+          entity: entityKey,
+          clip: clipName,
+          speed,
+          loop,
+          blendWeight,
+          wasAlreadyPlaying: playing,
+        });
+      },
+    },
+
+    {
+      def: {
+        name: "stop_animation",
+        description: "Stop a playing animation on an entity.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            entity: { type: "string", description: "Entity key" },
+            clip: { type: "string", description: "Animation clip name (optional, stops all if omitted)" },
+          },
+          required: ["entity"],
+        },
+      },
+      handler: (params) => {
+        const entityKey = params.entity as string;
+        const clipName = params.clip as string | undefined;
+
+        const player = ctx.animationPlayers.get(entityKey);
+        if (!player) {
+          return errorResult(`No AnimationPlayer found for entity ${entityKey}`);
+        }
+
+        player.stop();
+        return jsonResult({ entity: entityKey, stopped: true, clip: clipName ?? "all" });
+      },
+    },
+
+    {
+      def: {
+        name: "set_animation_state",
+        description: "Set the animation state machine to a named state.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            entity: { type: "string", description: "Entity key" },
+            state: { type: "string", description: "Target state name" },
+            crossfade: { type: "number", description: "Crossfade duration in seconds" },
+          },
+          required: ["entity", "state"],
+        },
+      },
+      handler: (params) => {
+        const entityKey = params.entity as string;
+        const stateName = params.state as string;
+        const crossfade = (params.crossfade as number) ?? 0.2;
+
+        const player = ctx.animationPlayers.get(entityKey);
+        if (!player) {
+          return errorResult(`No AnimationPlayer found for entity ${entityKey}`);
+        }
+
+        return jsonResult({
+          entity: entityKey,
+          state: stateName,
+          crossfade,
+          playing: player.isPlaying(),
+        });
+      },
+    },
+
+  ];
+
+  return tools;
+}

package/mcp/src/tools/asset.ts

@@ -0,0 +1,161 @@
+import type { ImportOptions } from "@downdraft/engine";
+import { AssetImporter, confinePath, GLBLoader } from "@downdraft/engine";
+import type { EngineContext } from "../engine-context";
+import type { ToolRegistration } from "../types";
+import { errorResult, jsonResult } from "../types";
+
+/** Base directory used for path confinement. Falls back to cwd. */
+const GAME_ROOT = process.cwd();
+
+export function createAssetTools(ctx: EngineContext): ToolRegistration[] {
+  const tools: ToolRegistration[] = [
+
+    {
+      def: {
+        name: "import_texture",
+        description: "Import and convert a texture file to engine format.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "Path to texture file (PNG, WebP, KTX2)" },
+            format: { type: "string", description: "Target format (default: auto-detect)" },
+          },
+          required: ["path"],
+        },
+      },
+      handler: async (params) => {
+        const path = params.path as string;
+        try {
+          const safePath = confinePath(GAME_ROOT, path);
+          const data = await ctx.assetManager.load(safePath);
+          return jsonResult({ imported: true, path: safePath, type: typeof data });
+        } catch (e) {
+          return errorResult(`Failed to import texture: ${(e as Error).message}`);
+        }
+      },
+    },
+
+    {
+      def: {
+        name: "convert_asset",
+        description: "Convert a 3D model asset (GLB/GLTF) to engine format with optional options.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "Path to source asset file (GLB, GLTF)" },
+            format: {
+              type: "string",
+              enum: ["gltf", "glb"],
+              description: "Target format (default: glb)",
+            },
+            generateNormals: { type: "boolean", description: "Generate normals if missing" },
+            generateTangents: { type: "boolean", description: "Generate tangents if missing" },
+            flipY: { type: "boolean", description: "Flip Y axis (default: true)" },
+            scale: { type: "number", description: "Scale factor" },
+          },
+          required: ["path"],
+        },
+      },
+      handler: async (params) => {
+        const path = params.path as string;
+        const format = (params.format as "gltf" | "glb") ?? "glb";
+
+        const options: ImportOptions = {
+          format,
+          generateNormals: params.generateNormals as boolean | undefined,
+          generateTangents: params.generateTangents as boolean | undefined,
+          flipY: params.flipY as boolean | undefined,
+          scale: params.scale as number | undefined,
+        };
+
+        try {
+          const safePath = confinePath(GAME_ROOT, path);
+          const { promises: fs } = await import("node:fs");
+          const buf = await fs.readFile(safePath);
+          const fileData = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+          const ext = safePath.split(".").pop()?.toLowerCase() ?? "";
+
+          const loader = new GLBLoader();
+          const importer = new AssetImporter(loader);
+
+          let result;
+          if (ext === "glb") {
+            result = await importer.importGLB(fileData, options);
+          } else if (ext === "gltf") {
+            const json = JSON.parse(new TextDecoder().decode(fileData));
+            result = await importer.importGLTF(json);
+          } else {
+            return errorResult(`Unsupported format: ${ext}. Use GLB or GLTF.`);
+          }
+
+          return jsonResult({
+            converted: true,
+            path: safePath,
+            format,
+            warnings: result.warnings,
+            nodeCount: result.document.nodes?.length ?? 0,
+            meshCount: result.document.meshes?.length ?? 0,
+          });
+        } catch (e) {
+          return errorResult(`Failed to convert asset: ${(e as Error).message}`);
+        }
+      },
+    },
+
+    {
+      def: {
+        name: "list_assets",
+        description: "List all loaded assets.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            filter: { type: "string", description: "Filter by extension or name substring" },
+          },
+        },
+      },
+      handler: (params) => {
+        let assets = ctx.assetManager.list();
+        const filter = params.filter as string | undefined;
+        if (filter) {
+          assets = assets.filter((a) => a.includes(filter));
+        }
+        return jsonResult({ count: assets.length, assets });
+      },
+    },
+
+    {
+      def: {
+        name: "validate_project",
+        description: "Check for missing assets, broken references, and invalid configurations.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      handler: () => {
+        const issues: string[] = [];
+
+        for (const [entityKey, meshName] of ctx.entityMeshes.entries()) {
+          if (!ctx.meshes.has(meshName)) {
+            issues.push(`Entity ${entityKey} references missing mesh "${meshName}"`);
+          }
+        }
+
+        for (const [entityKey, materialName] of ctx.entityMaterials.entries()) {
+          if (!ctx.materialLibrary.get(materialName)) {
+            issues.push(`Entity ${entityKey} references missing material "${materialName}"`);
+          }
+        }
+
+        return jsonResult({
+          valid: issues.length === 0,
+          issues,
+          issueCount: issues.length,
+        });
+      },
+    },
+
+  ];
+
+  return tools;
+}