@downdraft/engine 0.0.0 → 0.1.0

package/mcp/src/tools/audio.ts

@@ -0,0 +1,96 @@
+import type { EngineContext } from "../engine-context";
+import { createAudioListener, createAudioSource } from "../engine-context";
+import type { ToolRegistration } from "../types";
+import { errorResult, jsonResult } from "../types";
+
+export function createAudioTools(ctx: EngineContext): ToolRegistration[] {
+  const tools: ToolRegistration[] = [
+
+    {
+      def: {
+        name: "add_audio_source",
+        description: "Add an audio source to an entity with optional spatial positioning.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            entity: { type: "string", description: "Entity key" },
+            asset: { type: "string", description: "Audio asset path" },
+            spatial: { type: "boolean", description: "Whether this is a spatial (3D) source" },
+            volume: { type: "number", description: "Volume (0-1)" },
+            loop: { type: "boolean", description: "Loop the audio" },
+          },
+          required: ["entity", "asset"],
+        },
+      },
+      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 spatial = (params.spatial as boolean) ?? false;
+        const volume = (params.volume as number) ?? 1.0;
+        const loop = (params.loop as boolean) ?? false;
+
+        const sourceData = createAudioSource("-1", {
+          spatial,
+          volume,
+          loop,
+          autoPlay: false,
+        });
+
+        const cid = ctx.getComponentIdByName("AudioSource");
+        ctx.ecsWorld.addComponent(entity, cid, sourceData);
+        ctx.ecsWorld.flushCommands();
+
+        ctx.audioSources.set(entityKey, sourceData);
+
+        return jsonResult({
+          entity: entityKey,
+          asset: params.asset,
+          spatial,
+          volume,
+          loop,
+        });
+      },
+    },
+
+    {
+      def: {
+        name: "set_audio_listener",
+        description: "Set the audio listener to follow an entity or camera.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            entity: { type: "string", description: "Entity key to attach listener to" },
+            followCamera: { type: "boolean", description: "Follow the camera (default: true)" },
+          },
+        },
+      },
+      handler: (params) => {
+        const followCamera = (params.followCamera as boolean) ?? true;
+        const entityKey = params.entity as string | undefined;
+
+        if (entityKey) {
+          const entity = ctx.parseEntityKey(entityKey);
+          if (!entity || !ctx.isEntityAlive(entity)) {
+            return errorResult(`Entity ${entityKey} not found or dead`);
+          }
+
+          const listenerData = createAudioListener({ active: true });
+          const cid = ctx.getComponentIdByName("AudioListener");
+          ctx.ecsWorld.addComponent(entity, cid, listenerData);
+          ctx.ecsWorld.flushCommands();
+
+          ctx.audioListeners.set(entityKey, listenerData);
+        }
+
+        return jsonResult({ followCamera, entity: entityKey ?? null });
+      },
+    },
+
+  ];
+
+  return tools;
+}

package/mcp/src/tools/build.ts

@@ -0,0 +1,143 @@
+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();
+
+export function createBuildTools(ctx: EngineContext): ToolRegistration[] {
+  const tools: ToolRegistration[] = [
+
+    {
+      def: {
+        name: "build_game",
+        description: "Package the game for a target platform.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            target: {
+              type: "string",
+              enum: ["win", "mac", "linux", "android", "ios", "all"],
+              description: "Build target platform",
+            },
+            stage: {
+              type: "string",
+              enum: ["build", "package", "release"],
+              description: "Release stage: build (Vite only), package (package existing build), release (build+package+sign). Default: release.",
+            },
+            output: { type: "string", description: "Output directory" },
+            mode: {
+              type: "string",
+              enum: ["dev", "debug", "prod"],
+              description: "Build mode (default: prod)",
+            },
+          },
+          required: ["target"],
+        },
+      },
+      handler: (params) => {
+        const target = params.target as string;
+        const stage = (params.stage as string) ?? "release";
+        const mode = (params.mode as string) ?? "prod";
+        const output = (params.output as string) ?? `release`;
+
+        return jsonResult({
+          note: "Build system requires the CLI tool. Run 'draft release --stage=<stage> --target=<target>' from the project root.",
+          target,
+          stage,
+          mode,
+          output,
+        });
+      },
+    },
+
+    {
+      def: {
+        name: "validate_build",
+        description: "Validate that the project is ready for building (assets, scripts, scene integrity).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            target: {
+              type: "string",
+              enum: ["win", "mac", "linux"],
+              description: "Build target to validate against (default: linux)",
+            },
+          },
+        },
+      },
+      handler: (params) => {
+        const target = (params.target as string) ?? "linux";
+        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}"`);
+          }
+        }
+
+        if (ctx.lights.length === 0) {
+          issues.push("No lights in scene — build will produce a dark scene");
+        }
+
+        const scripts = ctx.scriptingSystem.getScriptNames();
+        if (scripts.length === 0) {
+          issues.push("No scripts loaded — game will have no logic");
+        }
+
+        const entityCount = ctx.ecsWorld.entityCount();
+        if (entityCount <= 1) {
+          issues.push("Scene is empty (only root entity)");
+        }
+
+        return jsonResult({
+          target,
+          valid: issues.length === 0,
+          issues,
+          issueCount: issues.length,
+          stats: {
+            entities: entityCount,
+            meshes: ctx.meshes.size,
+            materials: ctx.materialLibrary.list().length,
+            lights: ctx.lights.length,
+            scripts: scripts.length,
+          },
+        });
+      },
+    },
+
+    {
+      def: {
+        name: "export_scene",
+        description: "Export the current scene to a file.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "Output file path" },
+          },
+          required: ["path"],
+        },
+      },
+      handler: async (params) => {
+        const path = params.path as string;
+        try {
+          const safePath = confinePath(GAME_ROOT, path);
+          await ctx.saveSystem.saveToFile(ctx.ecsWorld, ctx.scene.name, safePath);
+          return jsonResult({ exported: true, path: safePath, scene: ctx.scene.name });
+        } catch (e) {
+          return errorResult(`Failed to export: ${(e as Error).message}`);
+        }
+      },
+    },
+
+  ];
+
+  return tools;
+}

package/mcp/src/tools/camera.ts

@@ -0,0 +1,167 @@
+import type { EngineContext } from "../engine-context";
+import type { ToolRegistration } from "../types";
+import { errorResult, jsonResult } from "../types";
+import type { UndoRedoManager } from "../undo-redo";
+function toVec3(arr: [number, number, number]): [number, number, number] {
+  return [arr[0], arr[1], arr[2]];
+}
+
+export function createCameraTools(ctx: EngineContext, undoRedo: UndoRedoManager): ToolRegistration[] {
+  const tools: ToolRegistration[] = [
+
+    {
+      def: {
+        name: "set_camera",
+        description: "Position and aim the camera at a target.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            position: {
+              type: "array",
+              items: { type: "number" },
+              description: "Camera position [x, y, z]",
+            },
+            target: {
+              type: "array",
+              items: { type: "number" },
+              description: "Look-at target [x, y, z]",
+            },
+            fov: { type: "number", description: "Field of view in degrees" },
+            near: { type: "number", description: "Near plane" },
+            far: { type: "number", description: "Far plane" },
+          },
+        },
+      },
+      handler: (params) => {
+        const oldData = ctx.camera.getData();
+
+        if (params.position) {
+          const pos = params.position as [number, number, number];
+          ctx.camera.position = toVec3(pos);
+        }
+        if (params.target) {
+          const tgt = params.target as [number, number, number];
+          ctx.camera.target = toVec3(tgt);
+        }
+        if (params.fov !== undefined) {
+          ctx.camera.fov = (params.fov as number) * (Math.PI / 180);
+        }
+        if (params.near !== undefined) ctx.camera.near = params.near as number;
+        if (params.far !== undefined) ctx.camera.far = params.far as number;
+
+        ctx.camera.orbit(0, 0);
+
+        undoRedo.execute({
+          description: `set_camera`,
+          undo: () => {
+            ctx.camera.position = toVec3(oldData.position as [number, number, number]);
+            ctx.camera.target = toVec3(oldData.target as [number, number, number]);
+            ctx.camera.fov = oldData.fov;
+            ctx.camera.near = oldData.near;
+            ctx.camera.far = oldData.far;
+            ctx.camera.orbit(0, 0);
+          },
+          redo: () => {
+            if (params.position) {
+              const pos = params.position as [number, number, number];
+              ctx.camera.position = toVec3(pos);
+            }
+            if (params.target) {
+              const tgt = params.target as [number, number, number];
+              ctx.camera.target = toVec3(tgt);
+            }
+            if (params.fov !== undefined) ctx.camera.fov = (params.fov as number) * (Math.PI / 180);
+            if (params.near !== undefined) ctx.camera.near = params.near as number;
+            if (params.far !== undefined) ctx.camera.far = params.far as number;
+            ctx.camera.orbit(0, 0);
+          },
+        });
+
+        return jsonResult({
+          position: [ctx.camera.position[0], ctx.camera.position[1], ctx.camera.position[2]],
+          target: [ctx.camera.target[0], ctx.camera.target[1], ctx.camera.target[2]],
+          fov: ctx.camera.fov * (180 / Math.PI),
+          near: ctx.camera.near,
+          far: ctx.camera.far,
+        });
+      },
+    },
+
+    {
+      def: {
+        name: "set_camera_mode",
+        description: "Set camera mode (orbit, fps, cinematic, follow).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            mode: {
+              type: "string",
+              enum: ["orbit", "fps", "cinematic", "follow"],
+              description: "Camera mode",
+            },
+            followEntity: { type: "string", description: "Entity key to follow (for follow mode)" },
+          },
+          required: ["mode"],
+        },
+      },
+      handler: (params) => {
+        const mode = params.mode as string;
+        const followEntity = params.followEntity as string | undefined;
+
+        const prevFollow = ctx.cameraFollowEntity;
+
+        if (mode === "follow" && followEntity) {
+          const entity = ctx.parseEntityKey(followEntity);
+          if (!entity || !ctx.isEntityAlive(entity)) {
+            return errorResult(`Entity ${followEntity} not found or dead`);
+          }
+          ctx.cameraFollowEntity = entity;
+        } else {
+          ctx.cameraFollowEntity = null;
+        }
+
+        undoRedo.execute({
+          description: `set_camera_mode(${mode})`,
+          undo: () => {
+            ctx.cameraFollowEntity = prevFollow;
+          },
+          redo: () => {
+            if (mode === "follow" && followEntity) {
+              const entity = ctx.parseEntityKey(followEntity);
+              if (entity && ctx.isEntityAlive(entity)) {
+                ctx.cameraFollowEntity = entity;
+              }
+            } else {
+              ctx.cameraFollowEntity = null;
+            }
+          },
+        });
+
+        return jsonResult({ mode, followEntity: followEntity ?? null });
+      },
+    },
+
+    {
+      def: {
+        name: "get_camera_state",
+        description: "Get current camera position, target, and parameters.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      handler: () => {
+        const data = ctx.camera.getData();
+        const followKey = ctx.cameraFollowEntity ? ctx.getEntityKey(ctx.cameraFollowEntity) : null;
+        return jsonResult({
+          ...data,
+          fov: data.fov * (180 / Math.PI),
+          followEntity: followKey,
+        });
+      },
+    },
+
+  ];
+
+  return tools;
+}

package/mcp/src/tools/checkpoint.ts

@@ -0,0 +1,100 @@
+import type { EngineContext } from "../engine-context";
+import type { ToolRegistration } from "../types";
+import { jsonResult, errorResult } from "../types";
+import type { UndoRedoManager } from "../undo-redo";
+
+export function createCheckpointTools(ctx: EngineContext, undoRedo: UndoRedoManager): ToolRegistration[] {
+  const tools: ToolRegistration[] = [
+
+    {
+      def: {
+        name: "create_checkpoint",
+        description: "Snapshot current scene state (entities, components, hierarchy, resources).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Checkpoint name" },
+          },
+          required: ["name"],
+        },
+      },
+      handler: (params) => {
+        const name = params.name as string;
+        if (!name) return errorResult("name is required");
+
+        const cp = ctx.checkpointManager.create(name, ctx.ecsWorld);
+        return jsonResult({
+          name: cp.name,
+          timestamp: cp.timestamp,
+          entityCount: cp.entities.length,
+        });
+      },
+    },
+
+    {
+      def: {
+        name: "restore_checkpoint",
+        description: "Roll back to a named checkpoint.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Checkpoint name" },
+          },
+          required: ["name"],
+        },
+      },
+      handler: (params) => {
+        const name = params.name as string;
+        const success = ctx.checkpointManager.restore(name, ctx.ecsWorld);
+        if (!success) return errorResult(`Checkpoint "${name}" not found`);
+
+        return jsonResult({ restored: true, name });
+      },
+    },
+
+    {
+      def: {
+        name: "list_checkpoints",
+        description: "List all available checkpoints with timestamps.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      handler: () => {
+        const checkpoints = ctx.checkpointManager.list().map((cp) => ({
+          name: cp.name,
+          timestamp: cp.timestamp,
+          entityCount: cp.entities.length,
+        }));
+        return jsonResult({ count: checkpoints.length, checkpoints });
+      },
+    },
+
+    {
+      def: {
+        name: "diff_checkpoints",
+        description: "Structured diff between two checkpoints (added/removed/changed entities).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            a: { type: "string", description: "First checkpoint name" },
+            b: { type: "string", description: "Second checkpoint name" },
+          },
+          required: ["a", "b"],
+        },
+      },
+      handler: (params) => {
+        const a = params.a as string;
+        const b = params.b as string;
+        const diff = ctx.checkpointManager.diff(a, b);
+        if (!diff) return errorResult(`One or both checkpoints not found: "${a}", "${b}"`);
+
+        return jsonResult({ a, b, ...diff });
+      },
+    },
+
+  ];
+
+  return tools;
+}

package/mcp/src/tools/component.ts

@@ -0,0 +1,199 @@
+import type { EngineContext } from "../engine-context";
+import type { ToolRegistration } from "../types";
+import { jsonResult, errorResult } from "../types";
+import type { UndoRedoManager } from "../undo-redo";
+
+export function createComponentTools(ctx: EngineContext, undoRedo: UndoRedoManager): ToolRegistration[] {
+  const tools: ToolRegistration[] = [
+
+    {
+      def: {
+        name: "add_component",
+        description: "Add a component to an entity with the given data.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            entity: { type: "string", description: "Entity key (e.g. '5.0')" },
+            component: { type: "string", description: "Component name" },
+            data: {
+              type: "object",
+              description: "Component data fields",
+              properties: {},
+            },
+          },
+          required: ["entity", "component", "data"],
+        },
+      },
+      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 componentName = params.component as string;
+        const componentId = ctx.getComponentIdByName(componentName);
+        const data = params.data as Record<string, unknown>;
+
+        const hadComponent = ctx.ecsWorld.hasComponent(entity, componentId);
+        const oldData = hadComponent
+          ? ctx.ecsWorld.getComponent<Record<string, unknown>>(entity, componentId)
+          : null;
+
+        ctx.ecsWorld.addComponent(entity, componentId, data);
+        ctx.ecsWorld.flushCommands();
+
+        undoRedo.execute({
+          description: `add_component(${entityKey}, ${componentName})`,
+          undo: () => {
+            if (ctx.isEntityAlive(entity)) {
+              if (hadComponent && oldData) {
+                ctx.ecsWorld.addComponent(entity, componentId, oldData);
+              } else {
+                ctx.ecsWorld.removeComponent(entity, componentId);
+              }
+              ctx.ecsWorld.flushCommands();
+            }
+          },
+          redo: () => {
+            if (ctx.isEntityAlive(entity)) {
+              ctx.ecsWorld.addComponent(entity, componentId, data);
+              ctx.ecsWorld.flushCommands();
+            }
+          },
+        });
+
+        return jsonResult({ entity: entityKey, component: componentName, added: true });
+      },
+    },
+
+    {
+      def: {
+        name: "remove_component",
+        description: "Remove a component from an entity.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            entity: { type: "string", description: "Entity key" },
+            component: { type: "string", description: "Component name" },
+          },
+          required: ["entity", "component"],
+        },
+      },
+      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 componentName = params.component as string;
+        const componentId = ctx.getComponentIdByName(componentName);
+
+        if (!ctx.ecsWorld.hasComponent(entity, componentId)) {
+          return errorResult(`Entity ${entityKey} has no component "${componentName}"`);
+        }
+
+        const oldData = ctx.ecsWorld.getComponent<Record<string, unknown>>(entity, componentId);
+
+        ctx.ecsWorld.removeComponent(entity, componentId);
+        ctx.ecsWorld.flushCommands();
+
+        undoRedo.execute({
+          description: `remove_component(${entityKey}, ${componentName})`,
+          undo: () => {
+            if (ctx.isEntityAlive(entity) && oldData) {
+              ctx.ecsWorld.addComponent(entity, componentId, oldData);
+              ctx.ecsWorld.flushCommands();
+            }
+          },
+          redo: () => {
+            if (ctx.isEntityAlive(entity)) {
+              ctx.ecsWorld.removeComponent(entity, componentId);
+              ctx.ecsWorld.flushCommands();
+            }
+          },
+        });
+
+        return jsonResult({ entity: entityKey, component: componentName, removed: true });
+      },
+    },
+
+    {
+      def: {
+        name: "inspect_component",
+        description: "Deep dump of a single component on an entity, showing all fields and values.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            entity: { type: "string", description: "Entity key" },
+            component: { type: "string", description: "Component name" },
+          },
+          required: ["entity", "component"],
+        },
+      },
+      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 componentName = params.component as string;
+        const componentId = ctx.getComponentIdByName(componentName);
+
+        const data = ctx.ecsWorld.getComponent<Record<string, unknown>>(entity, componentId);
+        if (!data) {
+          return errorResult(`Entity ${entityKey} has no component "${componentName}"`);
+        }
+
+        const fields: Record<string, { type: string; value: unknown }> = {};
+        for (const [key, value] of Object.entries(data)) {
+          let typeStr: string = typeof value;
+          if (Array.isArray(value)) typeStr = "array";
+          else if (value instanceof Float32Array) typeStr = "Float32Array";
+          else if (value instanceof Uint32Array) typeStr = "Uint32Array";
+          else if (value === null) typeStr = "null";
+
+          fields[key] = { type: typeStr, value };
+        }
+
+        return jsonResult({
+          entity: entityKey,
+          component: componentName,
+          componentId,
+          fields,
+        });
+      },
+    },
+
+    {
+      def: {
+        name: "list_components",
+        description: "List all registered component names.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      handler: () => {
+        const entities = ctx.getAllAliveEntities();
+        const componentNames = new Set<string>();
+
+        entities.forEach((e) => {
+          const arch = ctx.ecsWorld.getArchetypeForEntity(e);
+          if (arch) {
+            for (const cid of arch.columns.keys()) {
+              componentNames.add(ctx.getComponentNameById(cid));
+            }
+          }
+        });
+
+        return jsonResult({ components: [...componentNames] });
+      },
+    },
+
+  ];
+
+  return tools;
+}