@downdraft/engine 0.0.0 → 0.1.0

package/mcp/src/tools/inspect.ts

@@ -0,0 +1,210 @@
+import { getColumnValue } from "@downdraft/engine";
+import type { EngineContext } from "../engine-context";
+import type { ToolRegistration } from "../types";
+import { errorResult, jsonResult } from "../types";
+
+export function createInspectTools(ctx: EngineContext): ToolRegistration[] {
+  const tools: ToolRegistration[] = [
+
+    {
+      def: {
+        name: "inspect_object",
+        description: "Rich recursive inspection: traverse hierarchy, dump all components + nested values. Supports path queries like 'world/ship_cabin/chest'.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: {
+              type: "string",
+              description: "Hierarchy path (e.g. '0.0/5.0/12.0') or entity key (e.g. '5.0')",
+            },
+            maxDepth: { type: "number", description: "Max traversal depth (default: 10)" },
+          },
+          required: ["path"],
+        },
+      },
+      handler: (params) => {
+        const path = params.path as string;
+        const maxDepth = (params.maxDepth as number) ?? 10;
+
+        const parts = path.split("/").filter(Boolean);
+        if (parts.length === 0) return errorResult("Empty path");
+
+        let currentEntity = ctx.parseEntityKey(parts[0]);
+        if (!currentEntity) return errorResult(`Invalid entity key: ${parts[0]}`);
+        if (!ctx.isEntityAlive(currentEntity)) return errorResult(`Entity ${parts[0]} not found or dead`);
+
+        for (let i = 1; i < parts.length; i++) {
+          const children = ctx.hierarchy.getChildren(currentEntity);
+          const childKey = parts[i];
+          const child = children.find((c) => ctx.getEntityKey(c) === childKey);
+          if (!child) return errorResult(`Child ${childKey} not found under ${ctx.getEntityKey(currentEntity)}`);
+          currentEntity = child;
+        }
+
+        return jsonResult(inspectEntityRecursive(ctx, currentEntity, 0, maxDepth));
+      },
+    },
+
+    {
+      def: {
+        name: "query_entities",
+        description: "Find entities by component type, spatial region, hierarchy path, or property values.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            component: { type: "string", description: "Filter by component name" },
+            property: {
+              type: "object",
+              description: "Filter by property value {componentName: {field: value}}",
+              properties: {},
+            },
+            region: {
+              type: "object",
+              description: "Spatial region filter",
+              properties: {
+                min: { type: "array", items: { type: "number" } },
+                max: { type: "array", items: { type: "number" } },
+              },
+            },
+            limit: { type: "number", description: "Max results (default: 100)" },
+          },
+        },
+      },
+      handler: (params) => {
+        const limit = (params.limit as number) ?? 100;
+        const filterComponent = params.component as string | undefined;
+        const filterProperty = params.property as Record<string, Record<string, unknown>> | undefined;
+        const filterRegion = params.region as { min: [number, number, number]; max: [number, number, number] } | undefined;
+
+        const filterComponentId = filterComponent ? ctx.getComponentIdByName(filterComponent) : null;
+        const allEntities = ctx.getAllAliveEntities();
+        const results: Array<Record<string, unknown>> = [];
+
+        for (let i = 0; i < allEntities.length && results.length < limit; i++) {
+          const e = allEntities[i];
+
+          if (filterComponentId !== null && !ctx.ecsWorld.hasComponent(e, filterComponentId)) {
+            continue;
+          }
+
+          if (filterProperty) {
+            let matches = true;
+            for (const [compName, fields] of Object.entries(filterProperty)) {
+              const cid = ctx.getComponentIdByName(compName);
+              const data = ctx.ecsWorld.getComponent<Record<string, unknown>>(e, cid);
+              if (!data) { matches = false; break; }
+              for (const [field, value] of Object.entries(fields)) {
+                if (data[field] !== value) { matches = false; break; }
+              }
+              if (!matches) break;
+            }
+            if (!matches) continue;
+          }
+
+          if (filterRegion) {
+            const transformCid = ctx.getComponentIdByName("Transform");
+            const transform = ctx.ecsWorld.getComponent<{ pos: [number, number, number] }>(e, transformCid);
+            if (transform) {
+              const [x, y, z] = transform.pos;
+              const [minX, minY, minZ] = filterRegion.min;
+              const [maxX, maxY, maxZ] = filterRegion.max;
+              if (x < minX || x > maxX || y < minY || y > maxY || z < minZ || z > maxZ) {
+                continue;
+              }
+            }
+          }
+
+          const arch = ctx.ecsWorld.getArchetypeForEntity(e);
+          const compNames = arch ? [...arch.columns.keys()].map((id) => ctx.getComponentNameById(id)) : [];
+          results.push({
+            entity: ctx.getEntityKey(e),
+            components: compNames,
+          });
+        }
+
+        return jsonResult({ count: results.length, entities: results });
+      },
+    },
+
+    {
+      def: {
+        name: "get_scene_tree",
+        description: "Get the full scene hierarchy as a tree structure.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            root: { type: "string", description: "Root entity key (default: '0.0' = world root)" },
+            maxDepth: { type: "number", description: "Max depth (default: 20)" },
+          },
+        },
+      },
+      handler: (params) => {
+        const rootKey = (params.root as string) ?? "0.0";
+        const root = ctx.parseEntityKey(rootKey);
+        if (!root) return errorResult(`Invalid root key: ${rootKey}`);
+
+        const maxDepth = (params.maxDepth as number) ?? 20;
+        const tree = buildSceneTree(ctx, root, 0, maxDepth);
+        return jsonResult(tree);
+      },
+    },
+
+  ];
+
+  return tools;
+}
+
+function inspectEntityRecursive(ctx: EngineContext, entity: import("@downdraft/engine").Entity, depth: number, maxDepth: number): Record<string, unknown> {
+  const entityKey = ctx.getEntityKey(entity);
+  const arch = ctx.ecsWorld.getArchetypeForEntity(entity);
+
+  const components: Record<string, unknown> = {};
+  if (arch) {
+    for (const [cid, col] of arch.columns.entries()) {
+      const row = arch.entities.findIndex(
+        (e) => e.index === entity.index && e.generation === entity.generation,
+      );
+      if (row >= 0) {
+        components[ctx.getComponentNameById(cid)] = getColumnValue(col, row);
+      }
+    }
+  }
+
+  const children = ctx.hierarchy.getChildren(entity);
+  const childResults: Record<string, unknown>[] = [];
+
+  if (depth < maxDepth) {
+    for (let i = 0; i < children.length; i++) {
+      childResults.push(inspectEntityRecursive(ctx, children[i], depth + 1, maxDepth));
+    }
+  }
+
+  return {
+    entity: entityKey,
+    depth,
+    components,
+    childCount: children.length,
+    children: childResults,
+  };
+}
+
+function buildSceneTree(ctx: EngineContext, entity: import("@downdraft/engine").Entity, depth: number, maxDepth: number): Record<string, unknown> {
+  const entityKey = ctx.getEntityKey(entity);
+  const arch = ctx.ecsWorld.getArchetypeForEntity(entity);
+  const compNames = arch ? [...arch.columns.keys()].map((id) => ctx.getComponentNameById(id)) : [];
+
+  const children = ctx.hierarchy.getChildren(entity);
+  const childNodes: Record<string, unknown>[] = [];
+
+  if (depth < maxDepth) {
+    for (let i = 0; i < children.length; i++) {
+      childNodes.push(buildSceneTree(ctx, children[i], depth + 1, maxDepth));
+    }
+  }
+
+  return {
+    entity: entityKey,
+    components: compNames,
+    children: childNodes,
+  };
+}

package/mcp/src/tools/lighting.ts

@@ -0,0 +1,263 @@
+import type { DirectionalLight, Light } from "@downdraft/engine";
+import type { EngineContext } from "../engine-context";
+import { LightType, createDirectionalLight, createPointLight } 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]): Float32Array {
+  return new Float32Array(arr);
+}
+
+export function createLightingTools(ctx: EngineContext, undoRedo: UndoRedoManager): ToolRegistration[] {
+  const tools: ToolRegistration[] = [
+
+    {
+      def: {
+        name: "add_light",
+        description: "Add a light to the scene (directional, point, or spot).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            type: {
+              type: "string",
+              enum: ["directional", "point", "spot"],
+              description: "Light type",
+            },
+            direction: {
+              type: "array",
+              items: { type: "number" },
+              description: "Direction (for directional/spot)",
+            },
+            position: {
+              type: "array",
+              items: { type: "number" },
+              description: "Position (for point/spot)",
+            },
+            color: {
+              type: "array",
+              items: { type: "number" },
+              description: "RGB color [0-1]",
+            },
+            intensity: { type: "number", description: "Light intensity" },
+            range: { type: "number", description: "Range (for point/spot)" },
+            castShadows: { type: "boolean", description: "Cast shadows (directional)" },
+          },
+          required: ["type"],
+        },
+      },
+      handler: (params) => {
+        const type = params.type as string;
+        const color = (params.color as [number, number, number]) ?? [1, 1, 1];
+        const intensity = (params.intensity as number) ?? 1.0;
+
+        let light: Light;
+
+        if (type === "directional") {
+          const dir = (params.direction as [number, number, number]) ?? [0.5, 0.8, 0.3];
+          light = createDirectionalLight(
+            toVec3(dir),
+            toVec3(color),
+            intensity,
+            (params.castShadows as boolean) ?? true,
+          );
+        } else if (type === "point") {
+          const pos = (params.position as [number, number, number]) ?? [0, 5, 0];
+          light = createPointLight(toVec3(pos), toVec3(color), intensity, (params.range as number) ?? 20);
+        } else if (type === "spot") {
+          const pos = (params.position as [number, number, number]) ?? [0, 5, 0];
+          const dir = (params.direction as [number, number, number]) ?? [0, -1, 0];
+          light = {
+            type: LightType.Spot,
+            position: toVec3(pos),
+            direction: toVec3(dir),
+            color: toVec3(color),
+            intensity,
+            range: (params.range as number) ?? 20,
+            innerConeAngle: 0.5,
+            outerConeAngle: 0.8,
+          } as unknown as Light;
+        } else {
+          return errorResult(`Unknown light type: ${type}`);
+        }
+
+        const index = ctx.lights.length;
+        ctx.lights.push(light);
+
+        undoRedo.execute({
+          description: `add_light("${type}", #${index})`,
+          undo: () => { ctx.lights.splice(index, 1); },
+          redo: () => { ctx.lights.push(light); },
+        });
+
+        return jsonResult({ lightIndex: index, type, intensity, color });
+      },
+    },
+
+    {
+      def: {
+        name: "set_sun_angle",
+        description: "Quickly set the sun (directional light) angle by elevation and azimuth.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            elevation: { type: "number", description: "Sun elevation in degrees (0=horizon, 90=zenith)" },
+            azimuth: { type: "number", description: "Sun azimuth in degrees (0=north, 90=east)" },
+            intensity: { type: "number", description: "Sun intensity" },
+          },
+          required: ["elevation", "azimuth"],
+        },
+      },
+      handler: (params) => {
+        const elevation = (params.elevation as number) * Math.PI / 180;
+        const azimuth = (params.azimuth as number) * Math.PI / 180;
+        const intensity = (params.intensity as number) ?? 3.0;
+
+        const dir: [number, number, number] = [
+          Math.cos(elevation) * Math.sin(azimuth),
+          Math.sin(elevation),
+          Math.cos(elevation) * Math.cos(azimuth),
+        ];
+        const dirVec = toVec3(dir);
+
+        const existingDir = ctx.lights.findIndex((l) => l.type === LightType.Directional);
+
+        if (existingDir >= 0) {
+          const oldLight = ctx.lights[existingDir] as DirectionalLight;
+          const newLight = createDirectionalLight(dirVec, oldLight.color, intensity, oldLight.castShadows);
+          ctx.lights[existingDir] = newLight;
+
+          undoRedo.execute({
+            description: `set_sun_angle(${params.elevation}°, ${params.azimuth}°)`,
+            undo: () => { ctx.lights[existingDir] = oldLight; },
+            redo: () => { ctx.lights[existingDir] = createDirectionalLight(dirVec, oldLight.color, intensity, oldLight.castShadows); },
+          });
+        } else {
+          const light = createDirectionalLight(dirVec, toVec3([1, 1, 0.95]), intensity, true);
+          ctx.lights.push(light);
+
+          undoRedo.execute({
+            description: `set_sun_angle(${params.elevation}°, ${params.azimuth}°)`,
+            undo: () => { ctx.lights.pop(); },
+            redo: () => { ctx.lights.push(light); },
+          });
+        }
+
+        return jsonResult({
+          elevation: params.elevation,
+          azimuth: params.azimuth,
+          direction: dir,
+          intensity,
+        });
+      },
+    },
+
+    {
+      def: {
+        name: "remove_light",
+        description: "Remove a light by index.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            index: { type: "number", description: "Light index" },
+          },
+          required: ["index"],
+        },
+      },
+      handler: (params) => {
+        const index = params.index as number;
+        if (index < 0 || index >= ctx.lights.length) {
+          return errorResult(`Light index ${index} out of range (0-${ctx.lights.length - 1})`);
+        }
+
+        const removed = ctx.lights.splice(index, 1)[0];
+
+        undoRedo.execute({
+          description: `remove_light(#${index})`,
+          undo: () => { ctx.lights.splice(index, 0, removed); },
+          redo: () => { ctx.lights.splice(index, 1); },
+        });
+
+        return jsonResult({ removed: true, index, type: removed.type });
+      },
+    },
+
+    {
+      def: {
+        name: "list_lights",
+        description: "List all lights in the scene.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      handler: () => {
+        const lights = ctx.lights.map((l, i) => ({
+          index: i,
+          type: l.type,
+          intensity: l.intensity,
+          color: [...("color" in l ? l.color : ("skyColor" in l ? l.skyColor : [0, 0, 0]))],
+          ...(l.type === LightType.Directional ? { direction: [...l.direction], castShadows: l.castShadows, shadowMapSize: l.shadowMapSize, shadowBias: l.shadowBias } : {}),
+          ...(l.type === LightType.Point ? { position: [...l.position], range: l.range } : {}),
+          ...(l.type === LightType.Spot ? { position: [...l.position], direction: [...l.direction], range: l.range } : {}),
+        }));
+        return jsonResult({ count: lights.length, lights });
+      },
+    },
+
+    {
+      def: {
+        name: "configure_shadows",
+        description: "Configure shadow mapping for a directional light (resolution, bias, cascade).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            lightIndex: { type: "number", description: "Directional light index (default: 0)" },
+            shadowMapSize: { type: "number", description: "Shadow map resolution (256, 512, 1024, 2048, 4096)" },
+            shadowBias: { type: "number", description: "Shadow bias to reduce acne/peter-panning" },
+            castShadows: { type: "boolean", description: "Enable or disable shadows" },
+          },
+        },
+      },
+      handler: (params) => {
+        const lightIndex = (params.lightIndex as number) ?? 0;
+        const light = ctx.lights[lightIndex];
+        if (!light) return errorResult(`Light index ${lightIndex} out of range`);
+        if (light.type !== LightType.Directional) return errorResult(`Light ${lightIndex} is not directional`);
+
+        const dirLight = light as DirectionalLight;
+        const oldMapSize = dirLight.shadowMapSize;
+        const oldBias = dirLight.shadowBias;
+        const oldCast = dirLight.castShadows;
+
+        if (params.shadowMapSize !== undefined) dirLight.shadowMapSize = params.shadowMapSize as number;
+        if (params.shadowBias !== undefined) dirLight.shadowBias = params.shadowBias as number;
+        if (params.castShadows !== undefined) dirLight.castShadows = params.castShadows as boolean;
+
+        undoRedo.execute({
+          description: `configure_shadows(#${lightIndex})`,
+          undo: () => {
+            dirLight.shadowMapSize = oldMapSize;
+            dirLight.shadowBias = oldBias;
+            dirLight.castShadows = oldCast;
+          },
+          redo: () => {
+            if (params.shadowMapSize !== undefined) dirLight.shadowMapSize = params.shadowMapSize as number;
+            if (params.shadowBias !== undefined) dirLight.shadowBias = params.shadowBias as number;
+            if (params.castShadows !== undefined) dirLight.castShadows = params.castShadows as boolean;
+          },
+        });
+
+        return jsonResult({
+          lightIndex,
+          shadowMapSize: dirLight.shadowMapSize,
+          shadowBias: dirLight.shadowBias,
+          castShadows: dirLight.castShadows,
+        });
+      },
+    },
+
+  ];
+
+  return tools;
+}