@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/modules/editor/src/commands/selection.js

@@ -0,0 +1,71 @@
+// ============================================================================
+// Selection commands — selection is session state, not document content, so
+// these are non-mutating: they appear in the event log (agents can observe)
+// but never on the undo stack.
+// ============================================================================
+export function createSelectionCommands() {
+    return [
+        {
+            id: "selection.set",
+            title: "Set Selection",
+            mutating: false,
+            params: {
+                type: "object",
+                properties: { entities: { type: "array", items: { type: "string" } } },
+                required: ["entities"],
+            },
+            apply(ctx, params) {
+                const keys = params.entities.filter((k) => ctx.isAliveKey(k));
+                ctx.selection.set(keys);
+                return { value: { selected: ctx.selection.get() }, description: `Select ${keys.length} entities` };
+            },
+        },
+        {
+            id: "selection.add",
+            title: "Add to Selection",
+            mutating: false,
+            params: {
+                type: "object",
+                properties: { entity: { type: "string" } },
+                required: ["entity"],
+            },
+            apply(ctx, params) {
+                const key = params.entity;
+                if (ctx.isAliveKey(key))
+                    ctx.selection.add(key);
+                return { value: { selected: ctx.selection.get() } };
+            },
+        },
+        {
+            id: "selection.remove",
+            title: "Remove from Selection",
+            mutating: false,
+            params: {
+                type: "object",
+                properties: { entity: { type: "string" } },
+                required: ["entity"],
+            },
+            apply(ctx, params) {
+                ctx.selection.remove(params.entity);
+                return { value: { selected: ctx.selection.get() } };
+            },
+        },
+        {
+            id: "selection.clear",
+            title: "Clear Selection",
+            mutating: false,
+            apply(ctx) {
+                ctx.selection.clear();
+                return { value: { selected: [] } };
+            },
+        },
+        {
+            id: "selection.get",
+            title: "Get Selection",
+            mutating: false,
+            apply(ctx) {
+                return { value: { selected: ctx.selection.get(), primary: ctx.selection.primary() } };
+            },
+        },
+    ];
+}

package/dist/modules/editor/src/commands/transform.js

@@ -0,0 +1,88 @@
+// ============================================================================
+// Transform commands — `transform.set` is the workhorse for gizmo drags and
+// inspector vec3 edits. Writes into the entity's `transform` component
+// (position/rotation/scale), creating it with identity defaults when absent.
+// The component name is configurable via `ctx.transformComponent`.
+// ============================================================================
+import { sanitizeObject } from "@downdraft/engine";
+const IDENTITY = { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] };
+function readTransform(ctx, entityKey) {
+    const entity = ctx.parseEntity(entityKey);
+    if (!entity)
+        return { ...IDENTITY };
+    const cid = ctx.engine.getComponentIdByName(ctx.transformComponent);
+    const data = ctx.engine.ecsWorld.getComponent(entity, cid);
+    return data ? sanitizeObject({ ...data }) : { ...IDENTITY };
+}
+export function createTransformCommands() {
+    return [
+        {
+            id: "transform.set",
+            title: "Set Transform",
+            mutating: true,
+            params: {
+                type: "object",
+                properties: {
+                    entity: { type: "string" },
+                    position: { type: "array", items: { type: "number" }, description: "[x,y,z]" },
+                    rotation: { type: "array", items: { type: "number" }, description: "quaternion [x,y,z,w]" },
+                    scale: { type: "array", items: { type: "number" }, description: "[x,y,z]" },
+                },
+                required: ["entity"],
+            },
+            apply(ctx, params) {
+                const key = params.entity;
+                const entity = ctx.parseEntity(key);
+                if (!entity || !ctx.isAliveKey(key))
+                    throw new Error(`Entity ${key} not found or dead`);
+                const old = readTransform(ctx, key);
+                const next = { ...old };
+                const applied = [];
+                ["position", "rotation", "scale"].forEach((field) => {
+                    const v = params[field];
+                    if (v) {
+                        next[field] = [...v];
+                        applied.push(field);
+                    }
+                });
+                if (applied.length === 0)
+                    throw new Error("transform.set: nothing to set");
+                const cid = ctx.engine.getComponentIdByName(ctx.transformComponent);
+                const sanitized = sanitizeObject(next);
+                if (ctx.engine.ecsWorld.hasComponent(entity, cid)) {
+                    ctx.engine.ecsWorld.setComponent(entity, cid, sanitized);
+                }
+                else {
+                    ctx.engine.ecsWorld.addComponent(entity, cid, sanitized);
+                }
+                ctx.engine.ecsWorld.flushCommands();
+                ctx.document.markDirty({ kind: "data", entity: key });
+                ctx.adapter?.syncEntity?.(key);
+                // Inverse restores only the fields we changed.
+                const inverseChanges = {};
+                applied.forEach((f) => { inverseChanges[f] = old[f]; });
+                return {
+                    value: { entity: key, applied },
+                    inverse: [{ command: "component.set", params: { entity: key, component: ctx.transformComponent, changes: inverseChanges } }],
+                    description: `Transform ${key} (${applied.join(", ")})`,
+                };
+            },
+        },
+        {
+            id: "transform.get",
+            title: "Get Transform",
+            mutating: false,
+            params: {
+                type: "object",
+                properties: { entity: { type: "string" } },
+                required: ["entity"],
+            },
+            apply(ctx, params) {
+                const key = params.entity;
+                if (!ctx.isAliveKey(key))
+                    throw new Error(`Entity ${key} not found or dead`);
+                return { value: { entity: key, transform: readTransform(ctx, key) } };
+            },
+        },
+    ];
+}

package/dist/modules/editor/src/ddscene.js

@@ -0,0 +1,189 @@
+// ============================================================================
+// .ddscene — the editor's scene document format + SceneLoader.
+//
+// JSON, versioned, component-name-keyed (stable across code changes —
+// numeric component ids are NOT persisted). Entity file ids are stable
+// strings ("e_3") so parent references survive respawn.
+//
+//   serializeDocument(doc)              → DdSceneFile
+//   deserializeIntoDocument(doc, file)  → { warnings, idMap }
+//   instantiateScene(file, deps)        → spawn-only engine API for games
+//   diffScenes(a, b)                    → structural diff for agents/CI
+//
+// Format is intentionally close to `SerializedScene` (core/scene/scene.ts)
+// but persists component *names* and adds names/hierarchy/environment —
+// `SerializedScene` is a runtime checkpoint, `.ddscene` is an authored doc.
+// ============================================================================
+import { getColumnValue, getComponentId, getComponentName, isRegisteredComponentName, sanitizeObject, } from "@downdraft/engine";
+export const DDSCENE_FORMAT = "ddscene";
+export const DDSCENE_VERSION = 1;
+// ── Serialize ──
+export function serializeDocument(doc, scene, hierarchy) {
+    const entities = [];
+    const fileIds = new Map(); // entity key → file id
+    for (const entity of doc.entities()) {
+        fileIds.set(doc.key(entity), `e_${entity.index}`);
+    }
+    for (const entity of doc.entities()) {
+        const key = doc.key(entity);
+        const arch = doc.world.getArchetypeForEntity(entity);
+        const components = {};
+        if (arch) {
+            const row = arch.entities.findIndex((e) => e.index === entity.index && e.generation === entity.generation);
+            if (row >= 0) {
+                for (const [cid, col] of arch.columns.entries()) {
+                    const data = getColumnValue(col, row);
+                    if (data !== undefined && data !== null) {
+                        components[getComponentName(cid)] = sanitizeObject(data);
+                    }
+                }
+            }
+        }
+        const parent = hierarchy.getParent(entity);
+        const entry = {
+            id: fileIds.get(key),
+            components,
+        };
+        const displayName = doc.entityName(key);
+        if (displayName)
+            entry.name = displayName;
+        if (parent) {
+            const parentFileId = fileIds.get(doc.key(parent));
+            if (parentFileId)
+                entry.parent = parentFileId;
+        }
+        entities.push(entry);
+    }
+    return {
+        format: DDSCENE_FORMAT,
+        version: DDSCENE_VERSION,
+        name: doc.name,
+        entities,
+        meta: {
+            engineVersion: "0.1.0",
+            savedAt: new Date().toISOString(),
+        },
+    };
+}
+// ── Deserialize ──
+export function deserializeIntoDocument(doc, scene, world, hierarchy, file) {
+    const warnings = [];
+    const idMap = new Map();
+    if (file.format !== DDSCENE_FORMAT) {
+        throw new Error(`Not a .ddscene document (format="${file.format}")`);
+    }
+    if (file.version > DDSCENE_VERSION) {
+        throw new Error(`.ddscene version ${file.version} is newer than this engine supports (${DDSCENE_VERSION})`);
+    }
+    // Clear the current document contents.
+    for (const entity of doc.entities()) {
+        world.despawn(entity);
+        scene.removeEntity(entity);
+    }
+    world.flushCommands();
+    doc.resetMeta(file.name);
+    // Pass 1: spawn entities + components.
+    const spawned = new Map(); // fileId → Entity
+    file.entities.forEach((entry) => {
+        const components = new Map();
+        for (const [compName, data] of Object.entries(entry.components ?? {})) {
+            if (!isRegisteredComponentName(compName)) {
+                warnings.push(`entity "${entry.id}": unknown component "${compName}" — skipped`);
+                continue;
+            }
+            components.set(getComponentId(compName), sanitizeObject({ ...data }));
+        }
+        const entity = world.spawn(components);
+        scene.trackEntity(entity);
+        spawned.set(entry.id, entity);
+        const key = `${entity.index}.${entity.generation}`;
+        idMap.set(entry.id, key);
+        if (entry.name)
+            doc.setEntityName(key, entry.name);
+    });
+    world.flushCommands();
+    // Pass 2: restore hierarchy (prefab refs resolve in Phase 3 — entries with
+    // `prefab` still spawn their own entity shell for now).
+    file.entities.forEach((entry) => {
+        if (!entry.parent)
+            return;
+        const child = spawned.get(entry.id);
+        const parent = spawned.get(entry.parent);
+        if (child && parent) {
+            hierarchy.setParent(child, parent);
+        }
+        else {
+            warnings.push(`entity "${entry.id}": parent "${entry.parent}" not found — orphaned`);
+        }
+    });
+    doc.markClean();
+    return { warnings, idMap };
+}
+/**
+ * `SceneLoader` — the runtime consumption half. Games call this to spawn a
+ * `.ddscene` into their own World/Hierarchy. Returns the fileId→Entity map
+ * so games can resolve authored references.
+ */
+export function instantiateScene(file, deps) {
+    const warnings = [];
+    const idMap = new Map();
+    const spawned = new Map();
+    if (file.format !== DDSCENE_FORMAT) {
+        throw new Error(`Not a .ddscene document (format="${file.format}")`);
+    }
+    file.entities.forEach((entry) => {
+        const components = new Map();
+        for (const [compName, data] of Object.entries(entry.components ?? {})) {
+            if (!isRegisteredComponentName(compName)) {
+                warnings.push(`entity "${entry.id}": unknown component "${compName}" — skipped`);
+                continue;
+            }
+            components.set(getComponentId(compName), sanitizeObject({ ...data }));
+        }
+        const entity = deps.world.spawn(components);
+        deps.scene?.trackEntity(entity);
+        spawned.set(entry.id, entity);
+        idMap.set(entry.id, `${entity.index}.${entity.generation}`);
+    });
+    deps.world.flushCommands();
+    file.entities.forEach((entry) => {
+        if (!entry.parent || !deps.hierarchy)
+            return;
+        const child = spawned.get(entry.id);
+        const parent = spawned.get(entry.parent);
+        if (child && parent)
+            deps.hierarchy.setParent(child, parent);
+    });
+    return { warnings, idMap, entities: spawned };
+}
+/** Structural diff between two serialized scenes (entity id + JSON-equal
+ *  component data). Used by `editor_diff` and by tests verifying round-trips. */
+export function diffScenes(a, b) {
+    const aMap = new Map(a.entities.map((e) => [e.id, e]));
+    const bMap = new Map(b.entities.map((e) => [e.id, e]));
+    const diff = { added: [], removed: [], changed: [] };
+    bMap.forEach((ent, id) => {
+        const prev = aMap.get(id);
+        if (!prev) {
+            diff.added.push(id);
+            return;
+        }
+        if (JSON.stringify(prev.components) !== JSON.stringify(ent.components)
+            || prev.parent !== ent.parent
+            || prev.name !== ent.name) {
+            diff.changed.push(id);
+        }
+    });
+    aMap.forEach((_, id) => {
+        if (!bMap.has(id))
+            diff.removed.push(id);
+    });
+    return diff;
+}
+export function parseDdScene(text) {
+    const data = JSON.parse(text);
+    if (data.format !== DDSCENE_FORMAT) {
+        throw new Error(`Not a .ddscene document (format="${data.format}")`);
+    }
+    return data;
+}

package/dist/modules/editor/src/document.js

@@ -0,0 +1,96 @@
+// ============================================================================
+// EditorDocument — the design-world document the editor edits.
+//
+// Wraps the EngineContext's Scene/World/Hierarchy plus editor-owned metadata
+// (display names, file path, dirty state). Commands mutate the world through
+// this document; the `.ddscene` serializer (ddscene.ts) round-trips it to
+// disk.
+//
+// Display names are document metadata, not a component — games are free to
+// have their own "name" component; the editor's name is authoring chrome.
+// ============================================================================
+import { isAlive } from "@downdraft/engine";
+export class EditorDocument {
+    name;
+    filePath = null;
+    scene;
+    names = new Map();
+    dirty = false;
+    version = 0;
+    listeners = new Set();
+    constructor(scene, name) {
+        this.scene = scene;
+        this.name = name ?? scene.name;
+    }
+    get world() {
+        return this.scene.world;
+    }
+    get entityCount() {
+        return this.scene.getEntityCount();
+    }
+    key(entity) {
+        return `${entity.index}.${entity.generation}`;
+    }
+    parse(key) {
+        const parts = key.split(".");
+        if (parts.length !== 2)
+            return null;
+        const index = parseInt(parts[0], 10);
+        const generation = parseInt(parts[1], 10);
+        if (Number.isNaN(index) || Number.isNaN(generation))
+            return null;
+        return { index, generation };
+    }
+    isAliveKey(key) {
+        const e = this.parse(key);
+        return e !== null && isAlive(this.world.entities, e);
+    }
+    /** All live entities tracked by the document's scene. */
+    entities() {
+        return this.scene.getEntities();
+    }
+    entityKeys() {
+        return this.entities().map((e) => this.key(e));
+    }
+    entityName(key) {
+        return this.names.get(key);
+    }
+    setEntityName(key, name) {
+        if (name === undefined || name === "")
+            this.names.delete(key);
+        else
+            this.names.set(key, name);
+    }
+    /** Display label: authored name if present, else `Entity <key>`. */
+    label(key) {
+        return this.names.get(key) ?? `Entity ${key}`;
+    }
+    /** Reset all editor metadata (called when a new doc is loaded in place). */
+    resetMeta(name) {
+        this.names.clear();
+        this.name = name;
+        this.filePath = null;
+        this.dirty = false;
+        this.version++;
+    }
+    isDirty() {
+        return this.dirty;
+    }
+    getVersion() {
+        return this.version;
+    }
+    markDirty(change) {
+        this.dirty = true;
+        this.version++;
+        this.listeners.forEach((fn) => fn(change));
+    }
+    markClean() {
+        this.dirty = false;
+        this.version++;
+        this.listeners.forEach((fn) => fn({ kind: "file" }));
+    }
+    onChange(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+}

package/dist/modules/editor/src/editor-context.js

@@ -0,0 +1,115 @@
+// ============================================================================
+// EditorContext — the editor's backend object.
+//
+// Composes an `EngineContext` (the standalone editing world from
+// `@downdraft/engine/mcp`: World + Scene + GameWorld + Hierarchy +
+// AssetManager + MaterialLibrary + CheckpointManager + SaveSystem +
+// UndoRedoManager) with editor session state: the `EditorDocument`,
+// `SelectionModel`, `EditorCommandRegistry`, and filesystem access.
+//
+// Design-document mode (Phase 0–5): the EngineContext is standalone — the
+// editor owns a private World/Scene on the main thread and the game's
+// renderer maps entities to visuals via an `EditorSceneAdapter`.
+// Live-sim mode (Phase 6) swaps in `EngineContext.fromGame()` backed by the
+// game's world — the command layer above doesn't change.
+// ============================================================================
+import { EngineContext } from "@downdraft/engine/mcp";
+import { EditorCommandRegistry } from "./commands/registry.js";
+import { EditorDocument } from "./document.js";
+import { SelectionModel } from "./selection.js";
+export function createNodeFs() {
+    return {
+        async readText(path) {
+            const fs = await import("node:fs/promises");
+            return fs.readFile(path, "utf8");
+        },
+        async writeText(path, text) {
+            const fs = await import("node:fs/promises");
+            await fs.writeFile(path, text, "utf8");
+        },
+        async exists(path) {
+            const fs = await import("node:fs/promises");
+            try {
+                await fs.access(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+export class EditorContext {
+    engine;
+    document;
+    selection;
+    commands;
+    fs;
+    adapter;
+    /**
+     * Entity key produced by the most recent `entity.restore` — lets
+     * `hierarchy.setParentToRestore` in the same undo batch re-parent
+     * children to the restored (new) key. Internal; not for public use.
+     */
+    lastRestoredKey = null;
+    /**
+     * Entity keys are physical ("index.generation") — despawn frees the slot
+     * and respawn yields a different key. `entity.restore` registers an
+     * alias oldKey→newKey here so journaled inverses and params carrying a
+     * stale key keep resolving (redo after an undo-remove relies on this).
+     */
+    keyAliases = new Map();
+    /** Component name the transform commands read/write. Games with a
+     *  differently-named transform component can override via module config. */
+    transformComponent = "transform";
+    constructor(opts = {}) {
+        this.engine = opts.engine ?? new EngineContext({ sceneName: opts.sceneName ?? "editor-scene" });
+        this.document = new EditorDocument(this.engine.scene, opts.sceneName ?? this.engine.scene.name);
+        this.selection = new SelectionModel();
+        this.commands = new EditorCommandRegistry(this);
+        this.fs = opts.fs === undefined ? createNodeFs() : opts.fs;
+        this.adapter = opts.adapter ?? null;
+        // Document dirty tracking: any applied mutating command dirties the doc
+        // unless it opts out via `marksDirty: false` — file-state commands
+        // (scene.save/open/new) call markClean themselves, and auto-dirtying
+        // after dispatch would stomp the clean flag.
+        this.commands.onDispatched((entry) => {
+            const cmd = this.commands.get(entry.command);
+            if (cmd?.mutating && cmd.marksDirty !== false) {
+                this.document.markDirty({ kind: "data", entity: entry.params["entity"] });
+            }
+        });
+    }
+    // ── Entity helpers (delegate to engine + document) ──
+    key(entity) {
+        return this.document.key(entity);
+    }
+    /** Follow the restore-alias chain for a possibly stale entity key. */
+    resolveKey(key) {
+        let k = key;
+        const seen = new Set();
+        while (this.keyAliases.has(k) && !seen.has(k)) {
+            seen.add(k);
+            k = this.keyAliases.get(k);
+        }
+        return k;
+    }
+    /** Record that oldKey now refers to newKey (entity restored under a new id). */
+    registerKeyAlias(oldKey, newKey) {
+        if (oldKey !== newKey)
+            this.keyAliases.set(oldKey, newKey);
+    }
+    clearKeyAliases() {
+        this.keyAliases.clear();
+    }
+    parseEntity(key) {
+        return this.document.parse(this.resolveKey(key));
+    }
+    isAliveKey(key) {
+        return this.document.isAliveKey(this.resolveKey(key));
+    }
+    dispose() {
+        // No timers/subscriptions held yet — placeholder for adapter teardown,
+        // autosave timers, and the UI shell.
+    }
+}

package/dist/modules/editor/src/index.js

@@ -0,0 +1,11 @@
+// @downdraft/engine/modules/editor — public API
+export { createEditorModule, EditorModuleTok } from "./module.js";
+export { createNodeFs, EditorContext } from "./editor-context.js";
+export { EditorDocument } from "./document.js";
+export { SelectionModel } from "./selection.js";
+export { EditorCommandError, EditorCommandRegistry } from "./commands/registry.js";
+export { registerDefaultCommands } from "./commands/index.js";
+export { DEFAULT_LAYOUT, EditorShell } from "./shell.js";
+export { EditorViewport } from "./viewport.js";
+export { DDSCENE_FORMAT, DDSCENE_VERSION, deserializeIntoDocument, diffScenes, instantiateScene, parseDdScene, serializeDocument } from "./ddscene.js";
+export { createEditorMcpTools, editorMcpTools, getEditorContext } from "./mcp.js";

package/dist/modules/editor/src/mcp.js

@@ -0,0 +1,91 @@
+// ============================================================================
+// Editor MCP surface — auto-generated `editor_*` tools.
+//
+// Every registered EditorCommand becomes an MCP tool (`entity.spawn` →
+// `editor_entity_spawn`) with its params schema verbatim. Agents get the
+// exact same command semantics as UI clicks — plus meta tools for journal
+// inspection, diffing, and state queries.
+//
+// Games wire these into their harness:
+//   mcp: () => createMcpHarness({ tools: createStandardAutomationTools({
+//     ..., extraTools: createEditorMcpTools(ctx.editor) }) })
+// or standalone: the tools are plain McpToolRegistration objects.
+// ============================================================================
+import { errorResult, jsonResult } from "@downdraft/engine/app/renderer";
+function toolNameFor(commandId) {
+    // "entity.spawn" → "editor_entity_spawn"; "editor.undo" → "editor_undo"
+    // (don't double the prefix for ids already namespaced).
+    return commandId.replaceAll(".", "_").replace(/^(?!editor_)/, "editor_");
+}
+export function createEditorMcpTools(editor) {
+    const tools = [];
+    for (const cmd of editor.commands.list()) {
+        const toolName = toolNameFor(cmd.id);
+        tools.push({
+            def: {
+                name: toolName,
+                description: `[editor] ${cmd.title} — ${cmd.mutating ? "mutates the document (undoable)" : "read-only / session"}.`,
+                inputSchema: (cmd.params ?? { type: "object", properties: {} }),
+            },
+            handler: async (params) => {
+                try {
+                    const value = await editor.commands.dispatch(cmd.id, params, "mcp");
+                    return jsonResult(value);
+                }
+                catch (e) {
+                    return errorResult(e instanceof Error ? e.message : String(e));
+                }
+            },
+        });
+    }
+    // Journal + introspection tools that aren't commands themselves.
+    tools.push({
+        def: {
+            name: "editor_commands",
+            description: "[editor] List all registered editor commands (id, title, mutating, params schema).",
+            inputSchema: { type: "object", properties: {} },
+        },
+        handler: () => jsonResult({
+            commands: editor.commands.list().map((c) => ({
+                id: c.id,
+                title: c.title,
+                mutating: c.mutating,
+                params: c.params ?? null,
+                mcpTool: toolNameFor(c.id),
+            })),
+        }),
+    }, {
+        def: {
+            name: "editor_journal",
+            description: "[editor] Command journal: undoable stack + recent event log (all dispatched commands).",
+            inputSchema: {
+                type: "object",
+                properties: { limit: { type: "number", description: "Max event-log entries (default 50)" } },
+            },
+        },
+        handler: (params) => jsonResult({
+            undo: editor.commands.getJournal().map((e) => `${e.seq}: ${e.description}`),
+            redo: editor.commands.getRedoStack().map((e) => `${e.seq}: ${e.description}`),
+            events: editor.commands.getEventLog(params?.limit ?? 50).map((e) => ({
+                seq: e.seq,
+                command: e.command,
+                source: e.source,
+                description: e.description,
+                params: e.params,
+            })),
+        }),
+    });
+    return tools;
+}
+/** Reach the live editor context from a game's `mcp:` hook — the module
+ *  stashes itself on `globalThis.__downdraftEditor` (parity with the
+ *  devtools `window.__sceneInspector` convention). */
+export function getEditorContext() {
+    return globalThis.__downdraftEditor ?? null;
+}
+/** Convenience: tools for the live editor, or [] when the editor module
+ *  isn't registered. Use inside `extraTools`. */
+export function editorMcpTools() {
+    const editor = getEditorContext();
+    return editor ? createEditorMcpTools(editor) : [];
+}