A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
refactor(editor): one tool catalog, and tiers drawn where undo stops working
esengine830394652c03
diff --git a/desktop/electron/mcpEndpoint.ts b/desktop/electron/mcpEndpoint.tsindex ad780bf3a..74f860da2 100644--- a/desktop/electron/mcpEndpoint.ts+++ b/desktop/electron/mcpEndpoint.ts@@ -39,7 +39,7 @@ import type { Server } from 'node:http';// Plain .mjs, shared with the headless host (scripts/editor-mcp-host.mjs) —// esbuild bundles it into the main bundle.// @ts-expect-error untyped shared module-import { createExecEndpoint } from '../scripts/mcp-exec-endpoint.mjs';+import { createExecEndpoint } from '../shared/execEndpoint.mjs';import { createSurfaceDriver } from './surfaceDriver';const log = (...a: unknown[]) => process.stderr.write(`[editor-mcp-endpoint] ${a.join(' ')}\n`);diff --git a/desktop/electron/surfaceDriver.ts b/desktop/electron/surfaceDriver.tsindex ba3bca4a1..6fb18a5aa 100644--- a/desktop/electron/surfaceDriver.ts+++ b/desktop/electron/surfaceDriver.ts@@ -3,9 +3,9 @@/*** @file surfaceDriver.ts — main-side calls INTO the live editor window.*- * The tool registry (scripts/editor-mcp-tools.mjs) dispatches through an- * injected `driver`, and this is the one that targets the real editor app:- * surface calls resolve on `window.__estellaEditor.surface` (the same+ * The tool catalog (shared/toolCatalog.mjs) dispatches through an injected+ * `driver`, and this is the one that targets the real editor app: surface+ * calls resolve on `window.__estellaEditor.surface` (the same* EditorControlSurface the UI uses), `root: 'editor'` calls on* `window.__estellaEditor` (project / asset / play doors), renderer-code* snippets run verbatim, and the two main-process ops reach what the rendererdiff --git a/desktop/scripts/editor-mcp-host.mjs b/desktop/scripts/editor-mcp-host.mjsindex aa55b6c5c..9932d8b37 100644--- a/desktop/scripts/editor-mcp-host.mjs+++ b/desktop/scripts/editor-mcp-host.mjs@@ -22,7 +22,7 @@ import http from 'node:http';import { readFile } from 'node:fs/promises';import path from 'node:path';import { fileURLToPath } from 'node:url';-import { createExecEndpoint } from './mcp-exec-endpoint.mjs';+import { createExecEndpoint } from '../shared/execEndpoint.mjs';import { onRendererConsole } from './rendererConsole.mjs';const DIST = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'dist');diff --git a/desktop/scripts/editor-mcp.mjs b/desktop/scripts/editor-mcp.mjsindex d6fe4779b..a9979eaa7 100644--- a/desktop/scripts/editor-mcp.mjs+++ b/desktop/scripts/editor-mcp.mjs@@ -4,7 +4,7 @@* @file editor-mcp.mjs — the editor MCP server (stdio front, plain node).** An MCP client (an AI agent) spawns this with node; it stands up an Estella- * host and serves the MCP tool registry (editor-mcp-tools.mjs) over stdio,+ * host and serves the shared tool catalog (shared/toolCatalog.mjs) over stdio,* forwarding each call to the host's loopback /exec endpoint. Three host modes:** (default) spawn the headless render host (fixtures; scene tools only;@@ -47,7 +47,7 @@ import {ListResourcesRequestSchema,ReadResourceRequestSchema,} from '@modelcontextprotocol/sdk/types.js';-import { TOOLS, RESOURCES, listTools, runTool } from './editor-mcp-tools.mjs';+import { TOOLS, RESOURCES, listTools, runTool } from '../shared/toolCatalog.mjs';const HERE = path.dirname(fileURLToPath(import.meta.url));// The desktop package root, for dev spawns (`electron .`). This file runs fromdiff --git a/desktop/scripts/mcp-exec-endpoint.mjs b/desktop/shared/execEndpoint.mjssimilarity index 96%rename from desktop/scripts/mcp-exec-endpoint.mjsrename to desktop/shared/execEndpoint.mjsindex 617afd305..0fa008aa8 100644--- a/desktop/scripts/mcp-exec-endpoint.mjs+++ b/desktop/shared/execEndpoint.mjs@@ -1,7 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * @file mcp-exec-endpoint.mjs — the loopback /exec seam every MCP host shares.+ * @file execEndpoint.mjs — the loopback /exec seam every MCP host shares.** One tiny HTTP server on 127.0.0.1: POST /exec with the host token executes one* marshalled call and returns `{ ok, hasResult, result }` (or `{ ok:false, error }`).diff --git a/desktop/scripts/editor-mcp-tools.mjs b/desktop/shared/toolCatalog.mjssimilarity index 89%rename from desktop/scripts/editor-mcp-tools.mjsrename to desktop/shared/toolCatalog.mjsindex d997e21be..a4ec63c5b 100644--- a/desktop/scripts/editor-mcp-tools.mjs+++ b/desktop/shared/toolCatalog.mjs@@ -1,15 +1,20 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * @file editor-mcp-tools.mjs- * The editor MCP tool registry — the ONE catalog every MCP entry serves.- * Each tool maps 1:1 to an EditorControlSurface method, so the MCP server- * adds NO new editor truth — it is a transport over the surface (exactly- * what EditorControlSurface.ts:7-9 anticipated). Kept dependency-free- * (JSON-Schema + light manual validation, no zod import) so the dispatch- * unit-tests without Electron and resolves under vite/vitest; the Electron- * entry (editor-mcp.mjs) supplies the executeJavaScript driver and the- * MCP SDK wiring. See docs/REARCH_EDITOR_ARCH.md §11.+ * @file toolCatalog.mjs+ * The editor's tool registry — the ONE catalog every agent front serves:+ * the MCP stdio front, the headless fixtures host, and the editor's own+ * built-in agent. Each tool maps 1:1 to an EditorControlSurface method, so+ * no front adds editor truth — each is a transport over the surface+ * (exactly what EditorControlSurface.ts:7-9 anticipated).+ *+ * Lives in shared/ rather than scripts/ because three processes import it,+ * and stays plain .mjs because one of them is plain node: `node+ * scripts/editor-mcp.mjs` is a documented dev entry, and the shipped+ * integration point is the esbuild bundle of that same file. Kept+ * dependency-free (JSON-Schema + light manual validation, no zod import)+ * so the dispatch unit-tests without Electron and resolves under+ * vite/vitest. See docs/REARCH_EDITOR_ARCH.md §11.** Tool shapes:* - method tools: `{ method, args(input) }` → driver(method, args, root) — a@@ -21,13 +26,37 @@* composited-window screenshot (the only way to see the play realm's OOPIF).** Editor-host tools fail with a pointer when called on the headless fixtures- * host. Mutating tools carry `write: true` and are hidden + refused unless the- * host enables writes (ESTELLA_MCP_ALLOW_WRITES=1) — an agent can observe by- * default but cannot silently rewrite a scene or a project.+ * host.+ *+ * Every tool declares an `effect`, and the tiers are drawn where UNDO STOPS+ * WORKING — which is what makes them actionable rather than decorative:+ *+ * read observes only. Never gated, never confirmed.+ * undoable mutates the document through EditorHistory. A built-in agent+ * runs these freely: the turn is bracketed by a history+ * checkpoint, so one Undo is the whole approval mechanism.+ * irreversible escapes the undo stack — writes a file, rewrites a project,+ * builds an export, or dispatches an arbitrary command. A+ * built-in agent must get explicit confirmation; undo cannot+ * rescue the user afterwards.+ *+ * A remote MCP client has no one to confirm with, so it keeps the coarser door+ * it always had: anything past `read` is hidden AND refused unless the host sets+ * ESTELLA_MCP_ALLOW_WRITES=1. An agent can observe by default but cannot+ * silently rewrite a scene or a project.*/const obj = (properties, required = []) => ({ type: 'object', properties, required });+/** Whether `tool` mutates anything — the remote gate's question. Absent `effect`+ * reads as 'read', so a tool that declares nothing is treated as harmless only+ * when it genuinely is; every mutating entry below states its tier. */+export const mutates = (tool) => (tool.effect ?? 'read') !== 'read';++/** Whether `tool` is past what an undo can revert — the in-editor agent's+ * confirmation gate. */+export const irreversible = (tool) => tool.effect === 'irreversible';+// Render the viewport to a base64 PNG. Runs in the renderer (needs document):// captureViewport returns bottom-up GL rows, so flip Y into a 2D canvas first.// Resolves the surface on either host (headless fixtures / live editor).@@ -69,20 +98,20 @@ export const TOOLS = [{ name: 'serialize_scene',description: 'The full lossless scene JSON (the model truth).',schema: obj({}), method: 'serializeScene', args: () => [] },- { name: 'add_entity', write: true,+ { name: 'add_entity', effect: 'undoable',description: 'Create a new empty entity (with a Transform); returns its id.',schema: obj({}), method: 'addEntity', args: () => [] },- { name: 'delete_entity', write: true,+ { name: 'delete_entity', effect: 'undoable',description: 'Delete an entity.',schema: obj({ id: { type: 'number' } }, ['id']), method: 'deleteEntity', args: (i) => [i.id] },- { name: 'duplicate_entity', write: true,+ { name: 'duplicate_entity', effect: 'undoable',description: 'Duplicate an entity (subtree); returns the new id.',schema: obj({ id: { type: 'number' } }, ['id']), method: 'duplicateEntity', args: (i) => [i.id] },- { name: 'rename_entity', write: true,+ { name: 'rename_entity', effect: 'undoable',description: 'Rename an entity.',schema: obj({ id: { type: 'number' }, name: { type: 'string' } }, ['id', 'name']),method: 'renameEntity', args: (i) => [i.id, i.name] },- { name: 'set_field', write: true,+ { name: 'set_field', effect: 'undoable',description: 'Set a component field (undoable). The field\'s DECLARED inspector type wins (see get_inspector: number, bool, string, vec2, vec3, angle, color, enum, select, flags, gradient, curve, dimension, asset) — `type` is advisory. Vecs take [x, y(, z)] number arrays, colors "#rrggbbaa" hex or {r,g,b,a} 0..1, assets a project-relative path or @uuid ref. '+ '`key` may name one MEMBER of a structural field — "position.x" / "position.z" (vec2/vec3), "gap.y", "padding.left" (sides), "width.value" / "width.unit" (dimension) — which reads and writes back the rest, so one number does not cost a read-modify-write. '+ 'Unknown components/fields and malformed values are errors, never silent writes.',@@ -96,11 +125,11 @@ export const TOOLS = [value: { type: ['number', 'string', 'boolean', 'array', 'object', 'null'] },}, ['entity', 'component', 'key', 'type', 'value']),method: 'setField', args: (i) => [i.entity, i.component, i.key, i.type, i.value] },- { name: 'add_component', write: true,+ { name: 'add_component', effect: 'undoable',description: 'Add a component to an entity by schema name (what the Details "Add Component" button does; see get_inspector for current components). Undoable.',schema: obj({ entity: { type: 'number' }, component: { type: 'string' } }, ['entity', 'component']),method: 'addComponent', args: (i) => [i.entity, i.component] },- { name: 'remove_component', write: true,+ { name: 'remove_component', effect: 'undoable',description: 'Remove a component from an entity by schema name. Undoable.',schema: obj({ entity: { type: 'number' }, component: { type: 'string' } }, ['entity', 'component']),method: 'removeComponent', args: (i) => [i.entity, i.component] },@@ -108,17 +137,17 @@ export const TOOLS = [description: "An entity's authored event wires: rows of { event, action, arg?, params?, target?, guard?, once?, enabled? } — the data form of \"when this button is clicked, run that action\".",schema: obj({ entity: { type: 'number' } }, ['entity']),method: 'getEventBindings', args: (i) => [i.entity] },- { name: 'set_event_bindings', write: true,+ { name: 'set_event_bindings', effect: 'undoable',description: 'Replace an entity\'s authored event wires in ONE undo step (an empty list unwires it). This is how a button gets behaviour without code: `[{"event":"click","action":"panel.open","params":{"prefab":"assets/prefabs/Shop.esprefab"}}]`. '+ '`action` is any name in the action registry — the engine\'s built-ins (property.set, ui.setVisible, fsm.fire…) or one the project registered — and `target` names another entity to run it on (nearest-first from this one). '+ 'EventBinding has no Add Component entry; this is its door.',schema: obj({ entity: { type: 'number' }, rows: { type: 'object', description: 'array of wire rows' } }, ['entity', 'rows']),method: 'setEventBindings', args: (i) => [i.entity, i.rows] },- { name: 'set_entity_xy', write: true,+ { name: 'set_entity_xy', effect: 'undoable',description: 'Move an entity to a world position (x, y) — converts to parent-local under the hood (undoable).',schema: obj({ id: { type: 'number' }, x: { type: 'number' }, y: { type: 'number' } }, ['id', 'x', 'y']),method: 'setEntityXY', args: (i) => [i.id, i.x, i.y] },- { name: 'set_parent', write: true,+ { name: 'set_parent', effect: 'undoable',description: 'Re-parent an entity in the transform hierarchy (parent=null → scene root).',schema: obj({ id: { type: 'number' }, parent: { type: ['number', 'null'] } }, ['id', 'parent']),method: 'setParent', args: (i) => [i.id, i.parent] },@@ -149,7 +178,7 @@ export const TOOLS = [+ 'In the LIVE editor the canvas is laid out by its panel, so the next layout pass re-derives this from the panel size; to size the live viewport, use set_panel_size instead.',schema: obj({ width: { type: 'number' }, height: { type: 'number' } }, ['width', 'height']),method: 'resizeViewport', args: (i) => [i.width, i.height] },- { name: 'set_panel_size', write: true,+ { name: 'set_panel_size',description: "Resize a docked panel (id: viewport, log, outliner, details, content...) — the live editor's real sizing door. The viewport canvas follows layout, so this is how you give the LIVE viewport a chosen size before a screenshot.",schema: obj({id: { type: 'string' }, width: { type: 'number' }, height: { type: 'number' },@@ -167,8 +196,8 @@ export const TOOLS = [{ name: 'get_subsystems',description: 'Lifecycle + liveness of every engine subsystem (physics, audio, …): phase and activity.',schema: obj({}), method: 'getSubsystems', args: () => [] },- { name: 'undo', write: true, description: 'Undo the last edit.', schema: obj({}), method: 'undo', args: () => [] },- { name: 'redo', write: true, description: 'Redo the last undone edit.', schema: obj({}), method: 'redo', args: () => [] },+ { name: 'undo', effect: 'undoable', description: 'Undo the last edit.', schema: obj({}), method: 'undo', args: () => [] },+ { name: 'redo', effect: 'undoable', description: 'Redo the last undone edit.', schema: obj({}), method: 'redo', args: () => [] },// — Editor-host tools (root: 'editor'): the project/asset/play doors of the LIVE// editor app. On the headless fixtures host these fail with a pointer to@@ -176,7 +205,7 @@ export const TOOLS = [{ name: 'list_project_templates',description: "New-project templates the editor ships. Each entry: { name, dir, kind: 'starter' | 'example', description?, tag? } — the blank starter has kind 'starter'. Use an entry's dir with create_project.",schema: obj({}), js: () => `window.estella.templates.list()` },- { name: 'create_project', write: true,+ { name: 'create_project', effect: 'irreversible',description: 'Create a new project from a template directory (see list_project_templates) at <location>/<name>; returns the new project root. Follow with open_project.',schema: obj({ templateDir: { type: 'string' }, location: { type: 'string' }, name: { type: 'string' } },['templateDir', 'location', 'name']),@@ -190,7 +219,7 @@ export const TOOLS = [+ 'REFUSES while the open scene has unsaved changes (opening reloads from disk, so anything just authored would be gone): save_scene first, or pass discardChanges to throw the edits away on purpose.',schema: obj({ path: { type: 'string' }, discardChanges: { type: 'boolean' } }, ['path']),method: 'openScene', args: (i) => [i.path, i.discardChanges === true], root: 'editor' },- { name: 'save_scene', write: true,+ { name: 'save_scene', effect: 'irreversible',description: 'Save the open DOCUMENT to disk (the toolbar Save) — the scene, or, in Prefab Mode, the prefab being edited (see get_document).',schema: obj({}), method: 'save', args: () => [], root: 'editor' },{ name: 'open_asset',@@ -211,25 +240,25 @@ export const TOOLS = [description: 'Open the prefab an INSTANCE came from, in Prefab Mode (the Outliner\'s "Edit Prefab") — no ref→path lookup needed. Same refusals as open_asset.',schema: obj({ entity: { type: 'number' }, discardChanges: { type: 'boolean' } }, ['entity']),js: (i) => `window.__estellaEditor.editPrefab(${Number(i.entity)}, ${i.discardChanges === true})` },- { name: 'apply_prefab', write: true,+ { name: 'apply_prefab', effect: 'irreversible',description: 'Push an instance\'s overrides back into its prefab asset (the Outliner\'s "Apply to Prefab") — the base for EVERY instance is rewritten, and this instance\'s overrides clear. '+ 'Property, name, visibility and component overrides plus structural add/remove. `confirm` must be true: a person is shown an itemized diff first, so a driver says it out loud instead (get_inspector marks the overridden fields).',schema: obj({ entity: { type: 'number' }, confirm: { type: 'boolean' } }, ['entity', 'confirm']),js: (i) => `window.__estellaEditor.applyPrefab(${Number(i.entity)}, ${i.confirm === true})` },- { name: 'revert_prefab', write: true,+ { name: 'revert_prefab', effect: 'undoable',description: 'Discard an instance\'s overrides and re-sync it to its prefab (the Outliner\'s "Revert to Prefab"), keeping its placement. Returns the fresh instance root\'s id — the old ids are gone (it is a delete + re-instantiate).',schema: obj({ entity: { type: 'number' } }, ['entity']),js: (i) => `window.__estellaEditor.revertPrefab(${Number(i.entity)})` },- { name: 'unpack_prefab', write: true,+ { name: 'unpack_prefab', effect: 'undoable',description: 'Detach an instance (the Outliner\'s "Unpack Prefab"): its entities become ordinary scene entities and lose every prefab link, so later prefab edits no longer reach them. Undoable.',schema: obj({ entity: { type: 'number' } }, ['entity']),js: (i) => `window.__estellaEditor.unpackPrefab(${Number(i.entity)})` },- { name: 'create_prefab_variant', write: true,+ { name: 'create_prefab_variant', effect: 'irreversible',description: 'Save a new `.esprefab` that INHERITS the instance\'s prefab and bakes in its current overrides (the Outliner\'s "Create Variant" — a prefab of a prefab), then re-link the instance to the variant. '+ 'Written beside the base as "<base> Variant.esprefab"; returns the re-linked root\'s id. Deletions are not representable in a variant and are skipped.',schema: obj({ entity: { type: 'number' } }, ['entity']),js: (i) => `window.__estellaEditor.createPrefabVariant(${Number(i.entity)})` },- { name: 'create_scene_file', write: true,+ { name: 'create_scene_file', effect: 'irreversible',description: 'Create a blank scene FILE under a project-relative directory (does not switch to it); returns its path, immediately referenceable (the registry refresh happens before this resolves). '+ '`name` names it (the `.esscene` extension is added if absent); without one it is `scene.esscene`, which collides the moment you make a second.',schema: obj({@@ -238,7 +267,7 @@ export const TOOLS = [}, ['destDir']),js: (i) => `window.__estellaEditor.createSceneFile(${JSON.stringify(i.destDir)}, ${JSON.stringify(i.name ?? null)}, ${JSON.stringify({ overwrite: i.overwrite === true })}).then((p) => window.__estellaEditor.refreshAssets().then(() => p))` },- { name: 'create_prefab_from_entity', write: true,+ { name: 'create_prefab_from_entity', effect: 'irreversible',description: 'Extract an entity and its subtree into a `.esprefab` asset under assets/prefabs/ (the Outliner\'s Create Prefab), named after the entity; returns its `@uuid:` ref. '+ 'This is what makes a subtree REUSABLE: afterwards `list_entity_templates` offers it as `prefab:<path>`, and creating with that template makes a real INSTANCE — the scene stores a delta, not a copy, so editing the prefab updates every instance. '+ 'Without it a driver can build the same panel chrome into twenty scenes but never share it. Refs pointing OUT of the subtree cannot live in a standalone prefab and are cleared.',@@ -248,7 +277,7 @@ export const TOOLS = [}, ['entity']),js: (i) => `window.__estellaEditor.createPrefabFromEntity(${Number(i.entity)}, ${JSON.stringify({ replace: i.replace === true })}).then((ref) => { if (!ref) throw new Error('could not create a prefab from entity ${Number(i.entity)} — it may not exist'); return ref; })` },- { name: 'create_asset', write: true,+ { name: 'create_asset', effect: 'irreversible',description: 'Create a text asset file under a project-relative directory with the given content. `type` is the meta vocabulary: scene, prefab, shader, material, animclip (.esanim), animation (.estimeline), tileset, statemachine (.esfsm), behaviortree (.esbt), locale, inputmap, tilemap (.tmj). A bare baseName gets the type\'s canonical extension appended. Returns the project-relative path, immediately referenceable (the registry refresh happens before this resolves).',schema: obj({destDir: { type: 'string' }, baseName: { type: 'string' },@@ -256,13 +285,13 @@ export const TOOLS = [}, ['destDir', 'baseName', 'content', 'type']),js: (i) => `window.estella.project.createAsset(${JSON.stringify(i.destDir)}, ${JSON.stringify(i.baseName)}, ${JSON.stringify(i.content)}, ${JSON.stringify(i.type)}).then((p) => window.__estellaEditor.refreshAssets().then(() => p))` },- { name: 'import_assets', write: true,+ { name: 'import_assets', effect: 'irreversible',description: 'Import files into the asset registry (textures, audio, fonts, spine, tilemaps...). External absolute paths are copied into project-relative destDir; paths already INSIDE the project are registered in place (no copy, no rename). Returns { imported, skipped }; imported paths are immediately referenceable (the registry refresh happens before this resolves).',schema: obj({ destDir: { type: 'string' }, sources: { type: 'object', description: 'array of absolute file paths' } },['destDir', 'sources']),js: (i) => `window.estella.project.importFiles(${JSON.stringify(i.destDir)}, ${JSON.stringify(i.sources)}).then((r) => window.__estellaEditor.refreshAssets().then(() => r))` },- { name: 'apply_scene_ops', write: true,+ { name: 'apply_scene_ops', effect: 'undoable',description: 'Author a whole subtree in ONE undoable batch — the tool to build scenes with (set_field one field per call does not scale past a few dozen nodes). '+ '`ops` is an array executed in order, atomically: a throw anywhere rolls the WHOLE batch back. Op shapes: '+ '{op:"create", ref?, name?, parent?, template?, components?, fields?, x?, y?} — `template` is an entity-template id (list_entity_templates, e.g. "ui-image"), '@@ -284,7 +313,7 @@ export const TOOLS = [.then((text) => window.__estellaEditor.applyOps(JSON.parse(text), ${JSON.stringify(i.label ?? null)}))`: null),method: 'applyOps', args: (i) => [i.ops, i.label], root: 'editor' },- { name: 'refresh_assets', write: true,+ { name: 'refresh_assets',description: 'Re-scan the project into the asset registry. The editor watches the filesystem, but a batch written from outside (a converter copying twenty sprites in) can outrun the watcher — and until the scan lands those files have no `.meta`, so `set_import_settings` and any @uuid ref to them fail. Cheap and idempotent; call it after writing assets by hand.',schema: obj({}),js: () => 'window.__estellaEditor.refreshAssets().then(() => true)' },@@ -299,7 +328,7 @@ export const TOOLS = [description: "An asset's .meta import settings, layered over its type's defaults — the Import Settings panel's data. Returns { type, settings }.",schema: obj({ path: { type: 'string' } }, ['path']),method: 'getImportSettings', args: (i) => [i.path], root: 'editor' },- { name: 'set_import_settings', write: true,+ { name: 'set_import_settings', effect: 'irreversible',description: 'Patch an asset\'s .meta import settings and persist. Keys are DOTTED paths into the importer block, matching the inspector field keys — a texture\'s 9-slice border is '+ '{"sliceBorder.left":12,"sliceBorder.right":12,"sliceBorder.top":12,"sliceBorder.bottom":12}; filter/wrap are {"filterMode":"nearest","wrapMode":"clamp"}. '+ 'These live in IMPORT, not on a component: a UIVisual set to NineSlice takes its border from texture metadata, so this is what makes frames and buttons stretch correctly. '@@ -310,7 +339,7 @@ export const TOOLS = [description: 'Read a text file by project-relative path — game scripts (src/*.ts), project.esproject, .meta files, any project text. Complements get_inspector: scenes are model state, behaviour is code.',schema: obj({ path: { type: 'string' } }, ['path']),js: (i) => `window.estella.fs.read(${JSON.stringify(i.path)})` },- { name: 'write_project_file', write: true,+ { name: 'write_project_file', effect: 'irreversible',description: 'Write a text file by project-relative path, CREATING or OVERWRITING it. This is how game scripts (src/*.ts) are authored — create_asset only makes .meta-carrying asset types and refuses to overwrite (it uniquifies to "name 2"). '+ 'Writing project sources does not itself rebuild them; the editor picks the change up through its file watcher.',schema: obj({ path: { type: 'string' }, content: { type: 'string' } }, ['path', 'content']),@@ -319,14 +348,14 @@ export const TOOLS = [description: 'Project-relative paths of every file under a project-relative directory (recursive). Use for source trees (src/) where list_assets — which only knows registered assets — sees nothing.',schema: obj({ dir: { type: 'string' } }, ['dir']),js: (i) => `window.estella.fs.listFiles(${JSON.stringify(i.dir)})` },- { name: 'set_project_physics', write: true,+ { name: 'set_project_physics', effect: 'irreversible',description: 'Patch the project physics feature (Project Settings → Physics), e.g. { "enabled": true }. Persists to the manifest; Play and exports boot it.',schema: obj({ patch: { type: 'object' } }, ['patch']),method: 'setPhysics', args: (i) => [i.patch], root: 'editor' },{ name: 'list_entity_templates',description: "The Create-popover catalog: every ready-made entity the editor can spawn (id, label, category). Use an id with create_entity.",schema: obj({}), method: 'listEntityTemplates', args: () => [], root: 'editor' },- { name: 'create_entity', write: true,+ { name: 'create_entity', effect: 'undoable',description: 'Spawn a ready-made entity from a template id (see list_entity_templates) through the same pipeline as the Create menu; returns the new entity id. Optional world position and parent.',schema: obj({template: { type: 'string' }, parent: { type: ['number', 'null'] },@@ -345,7 +374,7 @@ export const TOOLS = [{ name: 'screenshot',description: 'Capture the composited editor window as a PNG (includes the play realm iframe — use this to SEE gameplay; capture_viewport only sees the edit viewport).',schema: obj({}), op: 'screenshot', image: true },- { name: 'play_probe', write: true,+ { name: 'play_probe', effect: 'irreversible',description: "Evaluate JS inside the RUNNING play realm and return the result — the gameplay probe. window.__estellaPlay = { app, getComponent } for state reads; to drive gameplay input, dispatch KeyboardEvents on DOCUMENT (the engine listens there, not on window): document.dispatchEvent(new KeyboardEvent('keydown', {code:'ArrowRight'})). frame picks the realm in multiplayer previews (0 = host).",schema: obj({ code: { type: 'string' }, frame: { type: 'number' } }, ['code']),op: 'play_probe' },@@ -361,11 +390,11 @@ export const TOOLS = [description: "Reveal a dock panel by id (viewport, log, sequencer, profiler, audiomixer...) — useful before a screenshot.",schema: obj({ id: { type: 'string' } }, ['id']),method: 'reveal', args: (i) => [i.id], root: 'editor' },- { name: 'run_editor_command', write: true,+ { name: 'run_editor_command', effect: 'irreversible',description: 'Dispatch any registered editor command by id (the UI\'s own channel) — the escape hatch for operations without a dedicated tool.',schema: obj({ id: { type: 'string' } }, ['id']),method: 'runCommand', args: (i) => [i.id], root: 'editor' },- { name: 'export_game', write: true,+ { name: 'export_game', effect: 'irreversible',description: 'Build + export the open project. platform: web | desktop | wechat | playable. Returns the export result (outDir, files...).',schema: obj({platform: { type: 'string' }, outDir: { type: 'string' },@@ -387,7 +416,7 @@ export const RESOURCES = [/** The MCP `tools/list` payload — name, description, JSON-Schema inputSchema.* Without `allowWrites`, mutating tools are omitted entirely (not just refused). */export function listTools(allowWrites = false) {- return TOOLS.filter((t) => !t.write || allowWrites)+ return TOOLS.filter((t) => !mutates(t) || allowWrites).map((t) => ({ name: t.name, description: t.description, inputSchema: t.schema }));}@@ -425,7 +454,7 @@ function validate(schema, raw) {*/export async function runTool(tool, driver, rawInput, allowWrites = true) {try {- if (tool.write && !allowWrites) {+ if (mutates(tool) && !allowWrites) {throw new Error(`tool ${tool.name} mutates the scene — start the server with ESTELLA_MCP_ALLOW_WRITES=1`);}const input = validate(tool.schema, rawInput);diff --git a/desktop/tests/editor-mcp-tools.test.ts b/desktop/tests/editor-mcp-tools.test.tsindex 09ddaf8e5..af59cf191 100644--- a/desktop/tests/editor-mcp-tools.test.ts+++ b/desktop/tests/editor-mcp-tools.test.ts@@ -2,11 +2,13 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { describe, it, expect, vi } from 'vitest';// @ts-expect-error — plain-.mjs tool registry shared with the Electron MCP entry.-import { TOOLS, RESOURCES, runTool, listTools } from '../scripts/editor-mcp-tools.mjs';+import { TOOLS, RESOURCES, runTool, listTools, mutates, irreversible } from '../shared/toolCatalog.mjs';// The editor MCP server is a transport over EditorControlSurface: each tool maps to one// surface method. These cover the pure dispatch layer (no Electron) — the Electron entry// only supplies the executeJavaScript driver.+const toolNamed = (name: string) => TOOLS.find((t: { name: string }) => t.name === name);+describe('editor MCP tool registry', () => {it('every tool has a unique name and a surface method, renderer code, or host op', () => {const names = new Set<string>();@@ -87,6 +89,26 @@ describe('editor MCP tool registry', () => {}});+ // The tiers are only worth having if they are exhaustive and honest, so assert+ // both halves: nothing declares a tier the gates do not understand, and every+ // tool that reaches the FILESYSTEM is on the side undo cannot rescue.+ it('every tool declares a tier the gates understand', () => {+ for (const t of TOOLS as Array<{ name: string; effect?: string }>) {+ expect(['read', 'undoable', 'irreversible', undefined]).toContain(t.effect);+ }+ });++ it('anything that touches disk or an external target is irreversible', () => {+ const onDisk = ['save_scene', 'write_project_file', 'create_asset', 'create_scene_file',+ 'import_assets', 'set_import_settings', 'set_project_physics', 'create_project',+ 'create_prefab_from_entity', 'export_game'];+ for (const name of onDisk) expect(irreversible(toolNamed(name))).toBe(true);+ // The arbitrary-code doors belong here too: their effect is whatever the+ // caller wrote, which no undo step can be assumed to cover.+ expect(irreversible(toolNamed('run_editor_command'))).toBe(true);+ expect(irreversible(toolNamed('play_probe'))).toBe(true);+ });+it('listTools without write permission omits mutating tools but keeps reads', () => {const readOnly = listTools(false).map((t: { name: string }) => t.name);expect(readOnly).toContain('get_scene_tree');@@ -128,7 +150,7 @@ describe('editor MCP tool registry', () => {it('apply_scene_ops is a write tool and rejects a non-array program', async () => {const driver = vi.fn();const apply = TOOLS.find((t: { name: string }) => t.name === 'apply_scene_ops');- expect(apply.write).toBe(true);+ expect(mutates(apply)).toBe(true);const res = await runTool(apply, driver, { ops: 'create everything' });expect(res.isError).toBe(true);expect(driver).not.toHaveBeenCalled();@@ -217,7 +239,6 @@ describe('open_scene guards unsaved work', () => {});describe('the prefab-mode doors', () => {- const tool = (name: string) => TOOLS.find((t: { name: string }) => t.name === name);const jsDriver = () => {const js = vi.fn().mockResolvedValue(undefined);return Object.assign(vi.fn(), { js });@@ -225,41 +246,51 @@ describe('the prefab-mode doors', () => {it('open_asset carries the path and the discard flag, refusing by default', async () => {const driver = jsDriver();- await runTool(tool('open_asset'), driver, { path: 'assets/prefabs/Panel.esprefab' });+ await runTool(toolNamed('open_asset'), driver, { path: 'assets/prefabs/Panel.esprefab' });expect(driver.js).toHaveBeenCalledWith(expect.stringContaining('openAsset("assets/prefabs/Panel.esprefab", false)'));driver.js.mockClear();- await runTool(tool('open_asset'), driver, { path: 'assets/prefabs/Panel.esprefab', discardChanges: true });+ await runTool(toolNamed('open_asset'), driver, { path: 'assets/prefabs/Panel.esprefab', discardChanges: true });expect(driver.js).toHaveBeenCalledWith(expect.stringContaining(', true)'));});it('apply_prefab cannot be called without saying confirm out loud', async () => {const driver = jsDriver();// `confirm` is required by the schema: an omission never reaches the editor.- const res = await runTool(tool('apply_prefab'), driver, { entity: 7 });+ const res = await runTool(toolNamed('apply_prefab'), driver, { entity: 7 });expect(res.isError).toBe(true);expect(driver.js).not.toHaveBeenCalled();// Present but false still reaches the editor, which refuses there (one place// owns the rule) — what must not happen is a silent apply.- await runTool(tool('apply_prefab'), driver, { entity: 7, confirm: false });+ await runTool(toolNamed('apply_prefab'), driver, { entity: 7, confirm: false });expect(driver.js).toHaveBeenCalledWith(expect.stringContaining('applyPrefab(7, false)'));});it('every prefab door that rewrites an asset or the scene is write-gated', () => {for (const name of ['apply_prefab', 'revert_prefab', 'unpack_prefab', 'create_prefab_variant']) {- expect(tool(name).write).toBe(true);+ expect(mutates(toolNamed(name))).toBe(true);}// Reading the document and leaving Prefab Mode write nothing.- expect(tool('get_document').write).toBeUndefined();- expect(tool('exit_prefab_mode').write).toBeUndefined();+ expect(mutates(toolNamed('get_document'))).toBe(false);+ expect(mutates(toolNamed('exit_prefab_mode'))).toBe(false);+ });++ // The tier is what an in-editor agent gates on, so it has to survive the split+ // that matters: rewriting the PREFAB ASSET reaches every instance and outlives+ // undo, while re-syncing or detaching THIS instance is an ordinary scene edit.+ it('separates the prefab doors that outlive undo from the ones that do not', () => {+ expect(toolNamed('apply_prefab').effect).toBe('irreversible');+ expect(toolNamed('create_prefab_variant').effect).toBe('irreversible');+ expect(toolNamed('revert_prefab').effect).toBe('undoable');+ expect(toolNamed('unpack_prefab').effect).toBe('undoable');});it('surfaces the "not an instance" refusal instead of a silent no-op', async () => {const driver = Object.assign(vi.fn(), {js: vi.fn().mockRejectedValue(new Error('entity 3 is not part of a prefab instance')),});- const res = await runTool(tool('unpack_prefab'), driver, { entity: 3 });+ const res = await runTool(toolNamed('unpack_prefab'), driver, { entity: 3 });expect(res.isError).toBe(true);expect(res.content[0].text).toMatch(/not part of a prefab instance/);});diff --git a/desktop/tests/mcp-endpoint.test.ts b/desktop/tests/mcp-endpoint.test.tsindex 7be6f415d..8f2835950 100644--- a/desktop/tests/mcp-endpoint.test.ts+++ b/desktop/tests/mcp-endpoint.test.ts@@ -31,7 +31,7 @@ vi.mock('electron', () => ({// The loopback seam itself is covered by its own host tests; here it stands in as// "a listener that bound (or didn't)", which is all this file's logic turns on.-vi.mock('../scripts/mcp-exec-endpoint.mjs', () => ({+vi.mock('../shared/execEndpoint.mjs', () => ({createExecEndpoint: async (opts: { token: string }) => {created(opts.token);if (bindError) throw bindError;