@downdraft/engine 0.0.0 → 0.1.0

package/mcp/src/tools/physics.ts

@@ -0,0 +1,266 @@
+import type { BodyType, ColliderShape, RealmTierConfig } from "@downdraft/engine";
+import { physicsBackendRegistry, PhysicsRealm, RealmTier } from "@downdraft/engine";
+import type { EngineContext } from "../engine-context";
+import type { ToolRegistration } from "../types";
+import { errorResult, jsonResult } from "../types";
+import type { UndoRedoManager } from "../undo-redo";
+
+export function createPhysicsTools(ctx: EngineContext, undoRedo: UndoRedoManager): ToolRegistration[] {
+  const tools: ToolRegistration[] = [
+
+    {
+      def: {
+        name: "create_physics_realm",
+        description: "Create an isolated physics realm (world).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Realm name" },
+            gravity: {
+              type: "array",
+              items: { type: "number" },
+              description: "Gravity vector [x, y, z]",
+            },
+          },
+          required: ["name"],
+        },
+      },
+      handler: (params) => {
+        const name = params.name as string;
+        const backend = physicsBackendRegistry.getDefault();
+        if (!backend) return errorResult("No physics backend registered");
+
+        const gravity = (params.gravity as [number, number, number]) ?? [0, -9.81, 0];
+        const tierConfig: RealmTierConfig = {
+          tickFrequency: 1,
+          solverIterations: 4,
+          promoteThreshold: 50,
+          demoteThreshold: 60,
+          demoteDwellTime: 1,
+        };
+        const realm = new PhysicsRealm(backend, {
+          name,
+          tier: RealmTier.Near,
+          gravity,
+          tierConfig,
+        });
+
+        ctx.physicsRealms.set(name, realm);
+
+        return jsonResult({ realm: name, id: realm.id, gravity });
+      },
+    },
+
+    {
+      def: {
+        name: "add_collider",
+        description: "Add a collider to an entity's physics body.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            entity: { type: "string", description: "Entity key" },
+            shape: {
+              type: "string",
+              enum: ["box", "sphere", "capsule"],
+              description: "Collider shape",
+            },
+            halfExtents: {
+              type: "array",
+              items: { type: "number" },
+              description: "Box half extents [x, y, z]",
+            },
+            radius: { type: "number", description: "Sphere/capsule radius" },
+            halfHeight: { type: "number", description: "Capsule half height" },
+            friction: { type: "number" },
+            restitution: { type: "number" },
+            realm: { type: "string", description: "Physics realm name (default: first)" },
+          },
+          required: ["entity", "shape"],
+        },
+      },
+      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 shapeType = params.shape as string;
+        let shape: ColliderShape;
+        if (shapeType === "box") {
+          const he = (params.halfExtents as [number, number, number]) ?? [0.5, 0.5, 0.5];
+          shape = { type: "box", halfExtents: he };
+        } else if (shapeType === "sphere") {
+          shape = { type: "sphere", radius: (params.radius as number) ?? 0.5 };
+        } else if (shapeType === "capsule") {
+          shape = { type: "capsule", halfHeight: (params.halfHeight as number) ?? 0.5, radius: (params.radius as number) ?? 0.3 };
+        } else {
+          return errorResult(`Unknown shape: ${shapeType}`);
+        }
+
+        const realmName = (params.realm as string) ?? ctx.physicsRealms.keys().next().value;
+        const realm = ctx.physicsRealms.get(realmName);
+        if (!realm) return errorResult(`Physics realm "${realmName}" not found`);
+
+        const handleKey = entityKey;
+        let handle = ctx.bodyHandles.get(handleKey);
+        if (!handle) {
+          handle = realm.createBody(
+            {
+              type: "dynamic",
+              position: [0, 0, 0],
+              rotation: [0, 0, 0, 1],
+            },
+            entity,
+          );
+          ctx.bodyHandles.set(handleKey, handle);
+        }
+
+        const colliderId = realm.addCollider(handle, {
+          shape,
+          friction: (params.friction as number) ?? 0.5,
+          restitution: (params.restitution as number) ?? 0.3,
+        });
+
+        return jsonResult({ entity: entityKey, shape: shapeType, colliderId, realm: realmName });
+      },
+    },
+
+    {
+      def: {
+        name: "set_body_type",
+        description: "Set the body type of an entity's physics body (static, dynamic, kinematic).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            entity: { type: "string", description: "Entity key" },
+            bodyType: {
+              type: "string",
+              enum: ["static", "dynamic", "kinematic"],
+              description: "Body type",
+            },
+          },
+          required: ["entity", "bodyType"],
+        },
+      },
+      handler: (params) => {
+        const entityKey = params.entity as string;
+        const handle = ctx.bodyHandles.get(entityKey);
+        if (!handle) return errorResult(`Entity ${entityKey} has no physics body`);
+
+        const bodyType = params.bodyType as BodyType;
+        const realm = ctx.physicsRealms.values().next().value;
+        if (!realm) return errorResult("No physics realm available");
+
+        realm.getBackend().setBodyType(handle, bodyType);
+
+        return jsonResult({ entity: entityKey, bodyType });
+      },
+    },
+
+    {
+      def: {
+        name: "apply_force",
+        description: "Apply a force or impulse to an entity's physics body.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            entity: { type: "string", description: "Entity key" },
+            force: {
+              type: "array",
+              items: { type: "number" },
+              description: "Force vector [x, y, z]",
+            },
+            type: {
+              type: "string",
+              enum: ["force", "impulse", "torque", "torqueImpulse"],
+              description: "Force type (default: force)",
+            },
+          },
+          required: ["entity", "force"],
+        },
+      },
+      handler: (params) => {
+        const entityKey = params.entity as string;
+        const handle = ctx.bodyHandles.get(entityKey);
+        if (!handle) return errorResult(`Entity ${entityKey} has no physics body`);
+
+        const force = params.force as [number, number, number];
+        const type = (params.type as string) ?? "force";
+        const realm = ctx.physicsRealms.values().next().value as PhysicsRealm | undefined;
+        if (!realm) return errorResult("No physics realm available");
+
+        const backend = realm.getBackend();
+        switch (type) {
+          case "force": backend.applyForce(handle, force); break;
+          case "impulse": backend.applyImpulse(handle, force); break;
+          case "torque": backend.applyTorque(handle, force); break;
+          case "torqueImpulse": backend.applyTorqueImpulse(handle, force); break;
+          default: return errorResult(`Unknown force type: ${type}`);
+        }
+
+        return jsonResult({ entity: entityKey, type, force });
+      },
+    },
+
+    {
+      def: {
+        name: "raycast",
+        description: "Cast a ray and return the first hit.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            origin: { type: "array", items: { type: "number" }, description: "Ray origin [x, y, z]" },
+            direction: { type: "array", items: { type: "number" }, description: "Ray direction [x, y, z]" },
+            maxDistance: { type: "number", description: "Max distance (default: 100)" },
+            realm: { type: "string", description: "Physics realm name" },
+          },
+          required: ["origin", "direction"],
+        },
+      },
+      handler: (params) => {
+        const origin = params.origin as [number, number, number];
+        const direction = params.direction as [number, number, number];
+        const maxDistance = (params.maxDistance as number) ?? 100;
+
+        const realmName = (params.realm as string) ?? ctx.physicsRealms.keys().next().value;
+        const realm = ctx.physicsRealms.get(realmName);
+        if (!realm) return errorResult(`Physics realm "${realmName}" not found`);
+
+        const result = realm.raycast(origin, direction, maxDistance);
+        if (!result) {
+          return jsonResult({ hit: false });
+        }
+
+        return jsonResult({
+          hit: true,
+          entity: ctx.getEntityKey(result.entity),
+          point: [...result.point],
+          normal: [...result.normal],
+          distance: result.distance,
+        });
+      },
+    },
+
+    {
+      def: {
+        name: "list_physics_realms",
+        description: "List all physics realms.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      handler: () => {
+        const realms = [...ctx.physicsRealms.entries()].map(([name, realm]) => ({
+          name,
+          id: realm.id,
+        }));
+        return jsonResult({ count: realms.length, realms });
+      },
+    },
+
+  ];
+
+  return tools;
+}

package/mcp/src/tools/scene.ts

@@ -0,0 +1,153 @@
+import { confinePath } from "@downdraft/engine";
+import type { EngineContext } from "../engine-context";
+import type { ToolRegistration } from "../types";
+import { errorResult, jsonResult, textResult } from "../types";
+import type { UndoRedoManager } from "../undo-redo";
+
+/** Base directory used for path confinement. Falls back to cwd. */
+const GAME_ROOT = process.cwd();
+
+export function createSceneTools(ctx: EngineContext, undoRedo: UndoRedoManager): ToolRegistration[] {
+  const tools: ToolRegistration[] = [
+
+    {
+      def: {
+        name: "create_scene",
+        description: "Create a new scene with the given name. Unloads the current scene and activates the new one.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Scene name" },
+          },
+          required: ["name"],
+        },
+      },
+      handler: async (params) => {
+        const name = params.name as string;
+        if (!name) return errorResult("name is required");
+
+        const oldName = ctx.scene.name;
+        const oldScene = ctx.world.sceneManager.get(oldName) ?? ctx.scene;
+        const oldData = oldScene.serialize();
+
+        // Unload current scene via scene manager
+        ctx.world.sceneManager.unload(oldName);
+
+        // Create, load, and activate new scene
+        const newScene = ctx.world.sceneManager.create(name);
+        await newScene.load();
+        ctx.world.sceneManager.activate(name);
+        ctx.scene = newScene;
+
+        undoRedo.execute({
+          description: `create_scene("${name}")`,
+          undo: () => {
+            ctx.world.sceneManager.unload(name);
+            oldScene.deserialize(oldData);
+            ctx.world.sceneManager.activate(oldName);
+            ctx.scene = oldScene;
+          },
+          redo: () => {
+            ctx.world.sceneManager.unload(oldName);
+            ctx.world.sceneManager.activate(name);
+            ctx.scene = newScene;
+          },
+        });
+
+        return jsonResult({ scene: name, entityCount: 0 });
+      },
+    },
+
+    {
+      def: {
+        name: "load_scene",
+        description: "Load a scene from a JSON save file path.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "Path to the save file" },
+          },
+          required: ["path"],
+        },
+      },
+      handler: async (params) => {
+        const path = params.path as string;
+        if (!path) return errorResult("path is required");
+
+        try {
+          const safePath = confinePath(GAME_ROOT, path);
+          await ctx.saveSystem.loadFromFile(safePath, ctx.ecsWorld);
+          return jsonResult({ loaded: true, path: safePath, entityCount: ctx.ecsWorld.entityCount() });
+        } catch (e) {
+          return errorResult(`Failed to load scene: ${(e as Error).message}`);
+        }
+      },
+    },
+
+    {
+      def: {
+        name: "save_scene",
+        description: "Save the current scene to a JSON file.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "Output file path" },
+          },
+          required: ["path"],
+        },
+      },
+      handler: async (params) => {
+        const path = params.path as string;
+        if (!path) return errorResult("path is required");
+
+        try {
+          const safePath = confinePath(GAME_ROOT, path);
+          await ctx.saveSystem.saveToFile(ctx.ecsWorld, ctx.scene.name, safePath);
+          return jsonResult({ saved: true, path: safePath, scene: ctx.scene.name });
+        } catch (e) {
+          return errorResult(`Failed to save scene: ${(e as Error).message}`);
+        }
+      },
+    },
+
+    {
+      def: {
+        name: "get_scene_info",
+        description: "Get information about the current scene.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      handler: () => {
+        return jsonResult({
+          name: ctx.scene.name,
+          entityCount: ctx.ecsWorld.entityCount(),
+          tick: ctx.ecsWorld.tick,
+          materials: ctx.materialLibrary.list().map((m) => m.name),
+          meshes: [...ctx.meshes.keys()],
+          lights: ctx.lights.length,
+          resources: [...ctx.ecsWorld.resources.keys()],
+        });
+      },
+    },
+
+    {
+      def: {
+        name: "export_scene",
+        description: "Export the current scene as a JSON string (without writing to file).",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      handler: () => {
+        const data = ctx.saveSystem.save(ctx.ecsWorld, ctx.scene.name);
+        return textResult(JSON.stringify(data, null, 2));
+      },
+    },
+
+  ];
+
+  return tools;
+}

package/mcp/src/tools/script.ts

@@ -0,0 +1,122 @@
+import { confinePath } 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();
+
+/** Strip absolute filesystem paths from error messages to avoid leaking implementation details. */
+function sanitizeErrorMessage(msg: string): string {
+  return msg.replace(GAME_ROOT, "<game-root>").replace(/\/[^\s"']+/g, (match) => {
+    if (match.startsWith("/<game-root>")) return match;
+    return "<path>";
+  });
+}
+
+export function createScriptTools(ctx: EngineContext): ToolRegistration[] {
+  const tools: ToolRegistration[] = [
+
+    {
+      def: {
+        name: "create_script",
+        description: "Create a TypeScript game logic script file.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Script name" },
+            code: { type: "string", description: "TypeScript source code" },
+          },
+          required: ["name", "code"],
+        },
+      },
+      handler: async (params) => {
+        const name = params.name as string;
+        const code = params.code as string;
+        if (!name || !code) return errorResult("name and code are required");
+        if (name.includes("..")) return errorResult("Script name must not contain '..'");
+
+        const path = `scripts/${name}.ts`;
+        try {
+          const safePath = confinePath(GAME_ROOT, path);
+          const { promises: fs } = await import("node:fs");
+          await fs.writeFile(safePath, code);
+          return jsonResult({ created: true, name, path });
+        } catch (e) {
+          return errorResult(`Failed to write script: ${sanitizeErrorMessage((e as Error).message)}`);
+        }
+      },
+    },
+
+    {
+      def: {
+        name: "attach_script",
+        description: "Attach (load) a script to the running game.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Script name" },
+            path: { type: "string", description: "Script file path (default: scripts/{name}.ts)" },
+          },
+          required: ["name"],
+        },
+      },
+      handler: async (params) => {
+        const name = params.name as string;
+        const path = (params.path as string) ?? `scripts/${name}.ts`;
+
+        try {
+          const safePath = confinePath(GAME_ROOT, path);
+          await ctx.scriptingSystem.load(name, safePath);
+          return jsonResult({ attached: true, name, path: safePath });
+        } catch (e) {
+          return errorResult(`Failed to attach script: ${sanitizeErrorMessage((e as Error).message)}`);
+        }
+      },
+    },
+
+    {
+      def: {
+        name: "hot_reload_script",
+        description: "Hot-reload a script (dispose old, load new).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Script name" },
+            path: { type: "string", description: "Script file path" },
+          },
+          required: ["name"],
+        },
+      },
+      handler: async (params) => {
+        const name = params.name as string;
+        const path = (params.path as string) ?? `scripts/${name}.ts`;
+
+        try {
+          const safePath = confinePath(GAME_ROOT, path);
+          await ctx.scriptingSystem.hotReload(name, safePath);
+          return jsonResult({ hotReloaded: true, name, path: safePath });
+        } catch (e) {
+          return errorResult(`Failed to hot-reload script: ${sanitizeErrorMessage((e as Error).message)}`);
+        }
+      },
+    },
+
+    {
+      def: {
+        name: "list_scripts",
+        description: "List all loaded scripts.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      handler: () => {
+        return jsonResult({ scripts: ctx.scriptingSystem.getScriptNames() });
+      },
+    },
+
+  ];
+
+  return tools;
+}

package/mcp/src/types.ts

@@ -0,0 +1,92 @@
+export interface MCPToolDef {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: "object";
+    properties: Record<string, MCPPropertySchema>;
+    required?: string[];
+  };
+}
+
+export interface MCPPropertySchema {
+  type: "string" | "number" | "boolean" | "array" | "object";
+  description?: string;
+  enum?: string[];
+  items?: MCPPropertySchema;
+  properties?: Record<string, MCPPropertySchema>;
+  required?: string[];
+  default?: unknown;
+}
+
+export interface MCPResourceDef {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType?: string;
+}
+
+export interface MCPPromptDef {
+  name: string;
+  description: string;
+  arguments?: Array<{
+    name: string;
+    description: string;
+    required?: boolean;
+  }>;
+}
+
+export interface MCPToolResult {
+  content: Array<
+    | { type: "text"; text: string }
+    | { type: "image"; data: string; mimeType: string }
+    | { type: "resource"; resource: { uri: string; mimeType?: string; text?: string } }
+  >;
+  isError?: boolean;
+}
+
+export interface MCPResourceResult {
+  contents: Array<{
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    blob?: string;
+  }>;
+}
+
+export interface MCPPromptResult {
+  messages: Array<{
+    role: "user" | "assistant" | "system";
+    content: { type: "text"; text: string };
+  }>;
+}
+
+export type ToolHandler = (params: Record<string, unknown>) => Promise<MCPToolResult> | MCPToolResult;
+export type ResourceHandler = (uri: string) => Promise<MCPResourceResult> | MCPResourceResult;
+export type PromptHandler = (args: Record<string, string>) => Promise<MCPPromptResult> | MCPPromptResult;
+
+export interface ToolRegistration {
+  def: MCPToolDef;
+  handler: ToolHandler;
+}
+
+export interface ResourceRegistration {
+  def: MCPResourceDef;
+  handler: ResourceHandler;
+}
+
+export interface PromptRegistration {
+  def: MCPPromptDef;
+  handler: PromptHandler;
+}
+
+export function textResult(text: string, isError: boolean = false): MCPToolResult {
+  return { content: [{ type: "text", text }], isError };
+}
+
+export function jsonResult(data: unknown, isError: boolean = false): MCPToolResult {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }], isError };
+}
+
+export function errorResult(message: string): MCPToolResult {
+  return { content: [{ type: "text", text: message }], isError: true };
+}