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
feat(editor): MCP grows the game-making axis - the live editor is a host
yhh2d76bbb6c2fc
diff --git a/desktop/electron/main.ts b/desktop/electron/main.tsindex f19e75997..945c8c2cf 100644--- a/desktop/electron/main.ts+++ b/desktop/electron/main.ts@@ -33,6 +33,7 @@ import { httpContentType } from './mimeTypes';import { buildPlayRealm } from './buildPlayRealm';import { syncSdkTypes } from './syncSdkTypes';import { installCrashCapture, logsDir } from './resilience';+import { mcpMode, startMcpEndpoint } from './mcpEndpoint';import { checkForUpdate } from './updateCheck';import { resolveLayout, resolveScripts } from '../src/project/format';import type { WorkspaceState } from '../src/project/format';@@ -353,8 +354,10 @@ function createWindow() {// Screenshot/visual-regression mode (ESTELLA_SHOT=out.png): open ?automation=1 so// the renderer hook is live, then drive the launcher→editor flow and capturePage.+ // MCP mode (--mcp) rides the same renderer hook — the exec endpoint drives+ // window.__estellaEditor instead of the screenshot flow.const shotOut = process.env.ESTELLA_SHOT;- const automation = shotOut ? '?automation=1' : '';+ const automation = shotOut || mcpMode() ? '?automation=1' : '';if (VITE_DEV_SERVER_URL) {win.loadURL(VITE_DEV_SERVER_URL + automation);@@ -367,6 +370,7 @@ function createWindow() {}if (shotOut) void runScreenshot(win, shotOut);+ if (mcpMode()) void startMcpEndpoint(() => win);// Unsaved-changes quit guard: prompt before closing a window with a dirty scene.// `sceneDirty` is pushed from the renderer (app:dirty); `quitting` lets the chosendiff --git a/desktop/electron/mcpEndpoint.ts b/desktop/electron/mcpEndpoint.tsnew file mode 100644index 000000000..77af6a6f9--- /dev/null+++ b/desktop/electron/mcpEndpoint.ts@@ -0,0 +1,88 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file mcpEndpoint.ts — the live editor's MCP exec endpoint (`--mcp` mode).+ *+ * Starts the shared loopback /exec seam against the REAL editor window, so the+ * MCP front (scripts/editor-mcp.mjs --editor / --attach) can drive the full app:+ * scene calls resolve on `window.__estellaEditor.surface` (the same+ * EditorControlSurface the UI uses), editor-level calls (project open, scenes,+ * play, entity templates) on `window.__estellaEditor`, renderer-code snippets run+ * verbatim, and `op: screenshot` captures the composited window main-side — the+ * only way to see into the play realm's OOPIF.+ *+ * The token comes from the spawning front (ESTELLA_MCP_TOKEN) or is generated for+ * a user-launched editor; either way the endpoint is advertised in a discovery+ * file under userData (mcp-endpoint.json) that `--attach` reads, and a+ * `MCP_HOST_READY {"port":N}` line on stdout for the spawn flow.+ */+import { app, BrowserWindow } from 'electron';+import { randomBytes } from 'node:crypto';+import { writeFileSync, rmSync } from 'node:fs';+import path from 'node:path';+// 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';++const log = (...a: unknown[]) => process.stderr.write(`[editor-mcp-endpoint] ${a.join(' ')}\n`);++/** True when this editor process should expose the MCP exec endpoint. */+export function mcpMode(): boolean {+ return process.argv.includes('--mcp') || process.env.ESTELLA_MCP === '1';+}++/**+ * Start the endpoint against the editor window. `getWin` re-resolves per call so+ * a recreated window keeps working. Idempotent-ish: call once after the first+ * window exists.+ */+export async function startMcpEndpoint(getWin: () => BrowserWindow | null): Promise<void> {+ const token = process.env.ESTELLA_MCP_TOKEN || randomBytes(24).toString('hex');++ const exec = async (code: string) => {+ const win = getWin();+ if (!win) throw new Error('no editor window');+ // A call can arrive before the renderer finished booting (the endpoint comes+ // up with the window) — wait out the initial load instead of failing it.+ if (win.webContents.isLoading()) {+ await new Promise<void>((resolve) => win.webContents.once('did-finish-load', () => resolve()));+ }+ return win.webContents.executeJavaScript(code, true);+ };++ const server = await createExecEndpoint({+ token,+ run: async ({ method, args, root, js, op }: {+ method?: string; args?: unknown[]; root?: string; js?: string; op?: string;+ }) => {+ if (op === 'screenshot') {+ const win = getWin();+ if (!win) throw new Error('no editor window');+ const image = await win.webContents.capturePage();+ return image.toPNG().toString('base64');+ }+ if (js) return exec(js);+ const target = root === 'editor' ? 'window.__estellaEditor' : 'window.__estellaEditor.surface';+ return exec(`${target}.${method}(${(args ?? [])+ .map((a) => (a === undefined ? 'undefined' : JSON.stringify(a)))+ .join(',')})`);+ },+ });++ const port = (server.address() as { port: number }).port;++ // Advertise for --attach; the token in the file is what authorizes a local+ // client, so the file lives in userData (per-user, not world-readable temp).+ const discovery = path.join(app.getPath('userData'), 'mcp-endpoint.json');+ try {+ writeFileSync(discovery, JSON.stringify({ port, token, pid: process.pid }) + '\n');+ app.on('will-quit', () => { try { rmSync(discovery); } catch { /* already gone */ } });+ } catch (e) {+ log('could not write discovery file:', String(e));+ }++ // The spawn flow (editor-mcp.mjs --editor) reads this exact line.+ process.stdout.write(`MCP_HOST_READY ${JSON.stringify({ port })}\n`);+ log(`exec endpoint on 127.0.0.1:${port} (discovery: ${discovery})`);+}diff --git a/desktop/package.json b/desktop/package.jsonindex 35dcc57a3..59c5471dc 100644--- a/desktop/package.json+++ b/desktop/package.json@@ -20,6 +20,7 @@"editor:mcp": "node scripts/editor-mcp.mjs","editor:mcp:build": "vite build && node scripts/editor-mcp.mjs","editor:mcp:e2e": "vite build && node scripts/editor-mcp-e2e.mjs",+ "editor:mcp:editor-e2e": "vite build && node scripts/editor-mcp-editor-e2e.mjs","editor:shot": "vite build && electron .","verify:render:spine": "vite build && ESTELLA_VERIFY_SCENE=/scenes/spine-test.esscene ESTELLA_VERIFY_MANIFEST=/scenes/spine-test.textures.json electron scripts/headless-verify.mjs","verify:render:particles": "vite build && ESTELLA_VERIFY_PLAY=1 ESTELLA_VERIFY_SCENE=/scenes/particle-demo.esscene ESTELLA_VERIFY_MANIFEST=/scenes/particle-demo.textures.json ESTELLA_VERIFY_STEPS=90 electron scripts/headless-verify.mjs",diff --git a/desktop/scripts/editor-mcp-editor-e2e.mjs b/desktop/scripts/editor-mcp-editor-e2e.mjsnew file mode 100644index 000000000..dadef79e5--- /dev/null+++ b/desktop/scripts/editor-mcp-editor-e2e.mjs@@ -0,0 +1,153 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file editor-mcp-editor-e2e.mjs — end-to-end smoke for the EDITOR-host MCP mode.+ *+ * Spawns editor-mcp.mjs --editor (the real editor app with --mcp) against a TEMP+ * COPY of the platformer example and drives the full game-making loop over MCP:+ * open project → open scene → entity-template catalog → create entity → edit a+ * field → verify it reached the live World → screenshot → save → play → stop.+ * Run from desktop/ after a dist build: node scripts/editor-mcp-editor-e2e.mjs+ * (ESTELLA_E2E_EXPORT=1 additionally runs a web export to the temp dir.)+ */+import { spawn } from 'node:child_process';+import { cp, mkdtemp, rm, stat } from 'node:fs/promises';+import os from 'node:os';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const DESKTOP = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const EXAMPLE = path.resolve(DESKTOP, '..', 'examples', 'platformer');++// Stage the example as a disposable project (transients filtered like the+// packaged templates are).+const tmpRoot = await mkdtemp(path.join(os.tmpdir(), 'estella-mcp-e2e-'));+const project = path.join(tmpRoot, 'platformer');+await cp(EXAMPLE, project, {+ recursive: true,+ filter: (src) => !/[/\\](\.esengine|node_modules|dist)([/\\]|$)/.test(src),+});++const child = spawn(process.execPath, ['scripts/editor-mcp.mjs', '--editor'], {+ cwd: DESKTOP,+ stdio: ['pipe', 'pipe', 'pipe'],+ env: { ...process.env, ESTELLA_MCP_ALLOW_WRITES: '1' },+});++let buf = '';+const waiters = new Map();+child.stdout.on('data', (d) => {+ buf += d.toString();+ let nl;+ while ((nl = buf.indexOf('\n')) >= 0) {+ const line = buf.slice(0, nl).trim();+ buf = buf.slice(nl + 1);+ if (!line) continue;+ let msg;+ try { msg = JSON.parse(line); } catch { continue; } // skip stray non-JSON stdout+ if (msg.id != null && waiters.has(msg.id)) { waiters.get(msg.id)(msg); waiters.delete(msg.id); }+ }+});+child.stderr.on('data', (d) => process.stderr.write(d));++const send = (msg) => child.stdin.write(JSON.stringify(msg) + '\n');+let nextId = 0;+const rpc = (method, params, timeoutMs = 60_000) => new Promise((resolve, reject) => {+ const id = ++nextId;+ const t = setTimeout(() => reject(new Error(`timeout waiting for ${method}`)), timeoutMs);+ waiters.set(id, (m) => { clearTimeout(t); resolve(m); });+ send({ jsonrpc: '2.0', id, method, params });+});+const call = async (name, args, timeoutMs) => {+ const res = await rpc('tools/call', { name, arguments: args ?? {} }, timeoutMs);+ if (res.result?.isError) throw new Error(`${name}: ${res.result?.content?.[0]?.text}`);+ return res.result?.content?.[0];+};+const cleanup = async () => {+ child.kill();+ await new Promise((r) => setTimeout(r, 500));+ await rm(tmpRoot, { recursive: true, force: true }).catch(() => {});+};+const fail = async (m) => { console.log('EDITOR-E2E FAIL:', m); await cleanup(); process.exit(1); };++try {+ const init = await rpc('initialize', {+ protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'editor-e2e', version: '0' },+ }, 180_000);+ if (!init.result?.serverInfo) await fail('no serverInfo in initialize');+ send({ jsonrpc: '2.0', method: 'notifications/initialized' });+ console.log('initialize OK');++ const list = await rpc('tools/list', {});+ const names = (list.result?.tools ?? []).map((t) => t.name);+ for (const need of ['open_project', 'open_scene', 'list_entity_templates', 'create_entity', 'save_scene', 'screenshot', 'export_game'])+ if (!names.includes(need)) await fail(`tools/list missing ${need}`);+ console.log(`tools/list OK — ${names.length} tools`);++ await call('open_project', { root: project }, 120_000);+ console.log('open_project OK');++ await call('open_scene', { path: 'assets/scenes/main.esscene' }, 60_000);+ // The openScene promise resolves ahead of the model spawn — poll the tree the+ // way the shot-automation flow does.+ let tree = [];+ for (let i = 0; i < 30 && tree.length === 0; i++) {+ tree = JSON.parse((await call('get_scene_tree')).text) ?? [];+ if (tree.length === 0) await new Promise((r) => setTimeout(r, 1000));+ }+ if (!Array.isArray(tree) || tree.length === 0) await fail('scene tree empty after open_scene');+ console.log(`open_scene OK — ${tree.length} roots`);++ const templates = JSON.parse((await call('list_entity_templates')).text);+ if (!templates.some((t) => t.id === 'anchor:Sprite')) await fail('anchor:Sprite missing from entity templates');+ console.log(`list_entity_templates OK — ${templates.length} templates`);++ const before = JSON.parse((await call('get_stats')).text).entities;+ const created = Number((await call('create_entity', { template: 'anchor:Sprite', x: 64, y: 96 })).text);+ const after = JSON.parse((await call('get_stats')).text).entities;+ if (!Number.isFinite(created) || after <= before) await fail(`create_entity did not spawn (${before} -> ${after})`);+ console.log(`create_entity OK — id ${created} (${before} -> ${after} entities)`);++ await call('set_field', { entity: created, component: 'Transform', key: 'position', type: 'vec3', value: [64, 96, 0] });+ const live = JSON.parse((await call('world_component', { id: created, component: 'Transform' })).text);+ if (!live) await fail('world_component returned null — edit did not reach the World');+ console.log('set_field + world_component OK — edit reached the live World');++ const shot = await call('screenshot');+ if (shot.type !== 'image' || (shot.data?.length ?? 0) < 100) await fail('screenshot not a PNG image block');+ console.log(`screenshot OK — ${shot.data.length} base64 chars`);++ const scenePath = path.join(project, 'assets', 'scenes', 'main.esscene');+ const mtimeBefore = (await stat(scenePath)).mtimeMs;+ await call('save_scene', {}, 60_000);+ const mtimeAfter = (await stat(scenePath)).mtimeMs;+ if (mtimeAfter <= mtimeBefore) await fail('save_scene did not rewrite the scene file');+ console.log('save_scene OK — scene file rewritten');++ await call('toggle_play', {}, 60_000);+ let play = null;+ for (let i = 0; i < 60; i++) {+ play = JSON.parse((await call('get_play_state')).text);+ if (play.ready || play.error) break;+ await new Promise((r) => setTimeout(r, 1000));+ }+ if (!play?.ready) await fail(`play realm never became ready (${JSON.stringify(play)})`);+ const playShot = await call('screenshot');+ if (playShot.type !== 'image') await fail('screenshot during play failed');+ await call('toggle_play', {}, 60_000);+ console.log('play OK — realm ready, screenshot captured, stopped');++ if (process.env.ESTELLA_E2E_EXPORT === '1') {+ const outDir = path.join(tmpRoot, 'export-web');+ const result = JSON.parse((await call('export_game', { platform: 'web', outDir }, 300_000)).text);+ const index = await stat(path.join(outDir, 'index.html')).catch(() => null);+ if (!index) await fail(`export_game produced no index.html (${JSON.stringify(result).slice(0, 200)})`);+ console.log('export_game OK — web export written');+ }++ console.log('\nEDITOR-E2E PASS — MCP drives the real editor end-to-end (project → scene → entity → save → play)');+ await cleanup();+ process.exit(0);+} catch (e) {+ await fail(String(e?.message ?? e));+}diff --git a/desktop/scripts/editor-mcp-host.mjs b/desktop/scripts/editor-mcp-host.mjsindex d9bb91a3f..09f448442 100644--- a/desktop/scripts/editor-mcp-host.mjs+++ b/desktop/scripts/editor-mcp-host.mjs@@ -22,6 +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';const DIST = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'dist');const TOKEN = process.env.ESTELLA_MCP_TOKEN;@@ -59,13 +60,6 @@ function serveDist() {return new Promise((resolve) => server.listen(0, '127.0.0.1', () => resolve(server)));}-const readBody = (req) => new Promise((resolve, reject) => {- const chunks = [];- req.on('data', (c) => chunks.push(c));- req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));- req.on('error', reject);-});-// Keep the process alive on the hidden window (this is a long-running host).app.on('window-all-closed', () => {});@@ -84,26 +78,25 @@ app.whenReady().then(async () => {// The exec endpoint: marshal a surface call ({method, args}) or a renderer-code// snippet ({js}) into the headless renderer. `undefined` args become the JS- // `undefined` literal so the surface's default parameters apply.- const exec = http.createServer(async (req, res) => {- const reply = (code, body) => {- res.writeHead(code, { 'content-type': 'application/json' });- res.end(JSON.stringify(body));- };- if (req.method !== 'POST' || req.url !== '/exec') return reply(404, { ok: false, error: 'not found' });- if (req.headers['x-estella-mcp-token'] !== TOKEN) return reply(403, { ok: false, error: 'bad token' });- try {- const { method, args, js } = JSON.parse(await readBody(req));+ // `undefined` literal so the surface's default parameters apply. Editor-only+ // tools (root: 'editor' — project/asset/play operations) have no meaning in a+ // fixtures host; fail them with the pointer to the right host.+ const exec = await createExecEndpoint({+ token: TOKEN,+ run: async ({ method, args, root, js, op }) => {+ if (op === 'screenshot') {+ const image = await win.webContents.capturePage();+ return image.toPNG().toString('base64');+ }+ if (root === 'editor') {+ throw new Error(`${method} needs the live editor host — connect through editor-mcp.mjs --editor (or --attach)`);+ }const code = js ?? `window.__estellaHeadless.api.${method}(${(args ?? []).map((a) => (a === undefined ? 'undefined' : JSON.stringify(a))).join(',')})`;- const result = await win.webContents.executeJavaScript(code, true);- reply(200, { ok: true, hasResult: result !== undefined, result: result === undefined ? null : result });- } catch (e) {- reply(200, { ok: false, error: String((e && e.message) || e) });- }+ return win.webContents.executeJavaScript(code, true);+ },});- await new Promise((resolve) => exec.listen(0, '127.0.0.1', resolve));// The front reads this line to learn the port; everything else goes to stderr.process.stdout.write(`MCP_HOST_READY ${JSON.stringify({ port: exec.address().port })}\n`);diff --git a/desktop/scripts/editor-mcp-tools.mjs b/desktop/scripts/editor-mcp-tools.mjsindex f4592c359..ee166f324 100644--- a/desktop/scripts/editor-mcp-tools.mjs+++ b/desktop/scripts/editor-mcp-tools.mjs@@ -11,22 +11,28 @@* entry (editor-mcp.mjs) supplies the executeJavaScript driver and the* MCP SDK wiring. See docs/REARCH_EDITOR_ARCH.md §11.*- * Two tool shapes:- * - method tools: `{ method, args(input) }` → driver(method, args) — a surface call.+ * Tool shapes:+ * - method tools: `{ method, args(input) }` → driver(method, args, root) — a+ * surface call; `root: 'editor'` targets `window.__estellaEditor` (project /+ * asset / play doors of the LIVE editor host) instead of the scene surface.* - renderer-code tools: `{ js(input) }` → driver.js(code) — for routines that- * need the renderer's DOM (canvas PNG encode); still surface-only underneath.+ * need the renderer's DOM (canvas PNG encode, window.estella bridge calls).+ * - main-process ops: `{ op }` → driver.op(op) — host-side routines like the+ * composited-window screenshot (the only way to see the play realm's OOPIF).*- * 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.+ * 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.*/const obj = (properties, required = []) => ({ type: 'object', properties, required });// 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).const CAPTURE_PNG_JS = `(() => {- const c = window.__estellaHeadless.api.captureViewport();+ const c = (window.__estellaHeadless?.api ?? window.__estellaEditor.surface).captureViewport();const { rgba, width, height } = c;const cv = document.createElement('canvas'); cv.width = width; cv.height = height;const ctx = cv.getContext('2d');@@ -123,6 +129,84 @@ export const TOOLS = [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: () => [] },++ // — 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+ // `editor-mcp.mjs --editor`. —+ { name: 'list_project_templates',+ description: 'New-project templates the editor ships (blank starter + sample projects). Use a returned dir with create_project.',+ schema: obj({}), js: () => `window.estella.templates.list()` },+ { name: 'create_project', write: true,+ 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']),+ js: (i) => `window.estella.project.createFromTemplate(${JSON.stringify(i.templateDir)}, ${JSON.stringify(i.location)}, ${JSON.stringify(i.name)})` },+ { name: 'open_project',+ description: 'Open a project by absolute root path and enter the editor. Call before any scene/asset work on the editor host.',+ schema: obj({ root: { type: 'string' } }, ['root']),+ js: (i) => `window.__estellaEditor.open(${JSON.stringify(i.root)}).then((ok) => { window.__estellaEditor.enterEditor(); return ok; })` },+ { name: 'open_scene',+ description: 'Open a scene by project-relative path (e.g. assets/scenes/main.esscene) in the editor.',+ schema: obj({ path: { type: 'string' } }, ['path']),+ method: 'openScene', args: (i) => [i.path], root: 'editor' },+ { name: 'save_scene', write: true,+ description: 'Save the open scene to disk (the toolbar Save).',+ schema: obj({}), method: 'save', args: () => [], root: 'editor' },+ { name: 'create_scene_file', write: true,+ description: 'Create a blank scene FILE under a project-relative directory (does not switch to it); returns its path.',+ schema: obj({ destDir: { type: 'string' } }, ['destDir']),+ method: 'createSceneFile', args: (i) => [i.destDir], root: 'editor' },+ { name: 'create_asset', write: true,+ description: 'Create a text asset file under a project-relative directory with the given content (types the editor knows: scene, inputmap, locale, fsm, bt, timeline, animclip, tileset, material, shader, prefab...). Returns its project-relative path.',+ schema: obj({+ destDir: { type: 'string' }, baseName: { type: 'string' },+ content: { type: 'string' }, type: { type: 'string' },+ }, ['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)})` },+ { name: 'import_assets', write: true,+ description: 'Import external files (absolute paths: textures, audio, fonts, spine, tilemaps...) into a project-relative directory. Returns { imported, skipped }.',+ 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)})` },+ { 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,+ 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'] },+ x: { type: 'number' }, y: { type: 'number' },+ }, ['template']),+ method: 'createEntity',+ args: (i) => [i.template, { parent: i.parent ?? null, x: i.x, y: i.y }], root: 'editor' },+ { name: 'toggle_play',+ description: 'Toggle play mode in the editor (check get_play_state first; play runs the game in an isolated realm and never dirties the edit scene).',+ schema: obj({}), method: 'play', args: () => [], root: 'editor' },+ { name: 'get_play_state',+ description: 'The play realm state: { playing, ready, error }.',+ schema: obj({}), method: 'playState', args: () => [], root: 'editor' },+ { 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: 'world_component',+ description: "A LIVE World component's data for a source entity, resolved by component name — verifies an edit actually reached the engine.",+ schema: obj({ id: { type: 'number' }, component: { type: 'string' } }, ['id', 'component']),+ method: 'worldComp', args: (i) => [i.id, i.component], root: 'editor' },+ { name: 'run_editor_command', write: true,+ 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,+ 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' },+ minify: { type: 'boolean' }, compressTextures: { type: 'boolean' },+ compressAudio: { type: 'boolean' }, atlasTextures: { type: 'boolean' },+ }, ['platform']),+ js: (i) => `window.estella.project.exportGame(${JSON.stringify({+ platform: i.platform, outDir: i.outDir, minify: i.minify,+ compressTextures: i.compressTextures, compressAudio: i.compressAudio, atlasTextures: i.atlasTextures,+ })})` },];/** MCP resources — read-only surface views an MCP client can subscribe to. */@@ -164,9 +248,10 @@ function validate(schema, raw) {/*** Validate `rawInput`, invoke the surface via the driver, and wrap the result as- * an MCP CallToolResult. Method tools call `driver(method, args)`; renderer-code- * tools call `driver.js(code)`. A gated write without permission, a validation- * failure, or a driver throw becomes an `isError` result rather than a crash.+ * an MCP CallToolResult. Method tools call `driver(method, args, root)`;+ * renderer-code tools call `driver.js(code)`; main-process ops call+ * `driver.op(op)`. A gated write without permission, a validation failure, or a+ * driver throw becomes an `isError` result rather than a crash.*/export async function runTool(tool, driver, rawInput, allowWrites = true) {try {@@ -174,13 +259,18 @@ export async function runTool(tool, driver, rawInput, allowWrites = true) {throw new Error(`tool ${tool.name} mutates the scene — start the server with ESTELLA_MCP_ALLOW_WRITES=1`);}const input = validate(tool.schema, rawInput);- if (tool.js) {- const data = await driver.js(tool.js(input));+ if (tool.op) {+ const data = await driver.op(tool.op, input);return tool.image? { content: [{ type: 'image', data, mimeType: 'image/png' }] }: { content: [{ type: 'text', text: String(data) }] };}- const result = await driver(tool.method, tool.args(input));+ if (tool.js) {+ const data = await driver.js(tool.js(input));+ if (tool.image) return { content: [{ type: 'image', data, mimeType: 'image/png' }] };+ return { content: [{ type: 'text', text: data === undefined ? 'ok' : JSON.stringify(data) }] };+ }+ const result = await driver(tool.method, tool.args(input), tool.root);return { content: [{ type: 'text', text: result === undefined ? 'ok' : JSON.stringify(result) }] };} catch (err) {return { content: [{ type: 'text', text: `error: ${err?.message ?? String(err)}` }], isError: true };diff --git a/desktop/scripts/editor-mcp.mjs b/desktop/scripts/editor-mcp.mjsindex be88fe570..82bfcb633 100644--- a/desktop/scripts/editor-mcp.mjs+++ b/desktop/scripts/editor-mcp.mjs@@ -3,10 +3,16 @@/*** @file editor-mcp.mjs — the editor MCP server (stdio front, plain node).*- * An MCP client (an AI agent) spawns this with node; it spawns the Electron half- * (editor-mcp-host.mjs — the proven headless render host publishing- * EditorControlSurface) and serves the MCP tool registry (editor-mcp-tools.mjs)- * over stdio, forwarding each call to the host's loopback /exec endpoint.+ * 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,+ * forwarding each call to the host's loopback /exec endpoint. Three host modes:+ *+ * (default) spawn the headless render host (fixtures; scene tools only)+ * --editor spawn the REAL editor app with --mcp — the full game-making+ * surface: projects, assets, entity templates, play, export+ * --attach <file> connect to an already-running editor's endpoint via its+ * discovery file (<userData>/mcp-endpoint.json) — drive the+ * editor the user is looking at** Split on purpose: an Electron main process never receives piped stdin on* Windows, so the MCP protocol must live in a plain-node process. The surface@@ -18,6 +24,7 @@*/import { spawn } from 'node:child_process';import { randomBytes } from 'node:crypto';+import { readFileSync } from 'node:fs';import path from 'node:path';import { createRequire } from 'node:module';import { fileURLToPath } from 'node:url';@@ -32,49 +39,76 @@ import {import { TOOLS, RESOURCES, listTools, runTool } from './editor-mcp-tools.mjs';const HERE = path.dirname(fileURLToPath(import.meta.url));+const DESKTOP = path.resolve(HERE, '..');const ALLOW_WRITES = process.env.ESTELLA_MCP_ALLOW_WRITES === '1';const log = (...a) => process.stderr.write(`[editor-mcp] ${a.join(' ')}\n`);-// Under plain node the electron package's export IS the binary path — works on-// every platform (the .bin/ shim is a sh script Windows cannot spawn).-const electron = createRequire(import.meta.url)('electron');-const token = randomBytes(24).toString('hex');+const argv = process.argv.slice(2);+const MODE = argv.includes('--editor') ? 'editor' : argv.includes('--attach') ? 'attach' : 'headless';-const host = spawn(electron, [path.join(HERE, 'editor-mcp-host.mjs')], {- stdio: ['ignore', 'pipe', 'pipe'],- env: {- ...process.env,- ESTELLA_MCP_TOKEN: token,- ESTELLA_MCP_PARENT_PID: String(process.pid),- },-});-host.stderr.on('data', (d) => process.stderr.write(d));-host.on('exit', (code) => {- log(`host exited (${code}) — shutting down`);- process.exit(code === 0 ? 0 : 1);-});-const killHost = () => { try { host.kill(); } catch { /* already gone */ } };-process.on('exit', killHost);-process.stdin.on('close', () => { killHost(); process.exit(0); });+/** Spawn an Electron host (headless fixtures or the real editor app with --mcp)+ * and resolve its /exec endpoint from the MCP_HOST_READY stdout line. */+function spawnHost(mode, token) {+ // Under plain node the electron package's export IS the binary path — works on+ // every platform (the .bin/ shim is a sh script Windows cannot spawn).+ const electron = createRequire(import.meta.url)('electron');+ const args = mode === 'editor' ? ['.', '--mcp'] : [path.join(HERE, 'editor-mcp-host.mjs')];+ const host = spawn(electron, args, {+ cwd: DESKTOP,+ stdio: ['ignore', 'pipe', 'pipe'],+ env: {+ ...process.env,+ ESTELLA_MCP_TOKEN: token,+ ESTELLA_MCP_PARENT_PID: String(process.pid),+ },+ });+ host.stderr.on('data', (d) => process.stderr.write(d));+ host.on('exit', (code) => {+ log(`host exited (${code}) — shutting down`);+ process.exit(code === 0 ? 0 : 1);+ });+ const killHost = () => { try { host.kill(); } catch { /* already gone */ } };+ process.on('exit', killHost);-// Wait for the host's readiness line to learn the /exec port.-const port = await new Promise((resolve, reject) => {- let buf = '';- const timer = setTimeout(() => reject(new Error('host did not become ready in 120s')), 120_000);- host.stdout.on('data', (d) => {- buf += d.toString();- const m = /^MCP_HOST_READY (\{.*\})$/m.exec(buf);- if (m) {- clearTimeout(timer);- resolve(JSON.parse(m[1]).port);- }+ return new Promise((resolve, reject) => {+ let buf = '';+ const timer = setTimeout(() => reject(new Error('host did not become ready in 120s')), 120_000);+ host.stdout.on('data', (d) => {+ buf += d.toString();+ const m = /^MCP_HOST_READY (\{.*\})$/m.exec(buf);+ if (m) {+ clearTimeout(timer);+ resolve(JSON.parse(m[1]).port);+ }+ });});-}).catch((e) => {- log('FATAL', e.message);- killHost();- process.exit(1);-});-log(`host ready on 127.0.0.1:${port} (writes ${ALLOW_WRITES ? 'ENABLED' : 'disabled'})`);+}++let port;+let token;+if (MODE === 'attach') {+ // Connect to a running editor via its discovery file (written in --mcp mode).+ const fileArg = argv[argv.indexOf('--attach') + 1];+ const discovery = fileArg && !fileArg.startsWith('--') ? fileArg : process.env.ESTELLA_MCP_DISCOVERY;+ if (!discovery) {+ log('FATAL: --attach needs the discovery file path (<userData>/mcp-endpoint.json) or ESTELLA_MCP_DISCOVERY');+ process.exit(1);+ }+ try {+ ({ port, token } = JSON.parse(readFileSync(discovery, 'utf8')));+ } catch (e) {+ log(`FATAL: cannot read discovery file ${discovery}: ${e.message}`);+ process.exit(1);+ }+} else {+ token = randomBytes(24).toString('hex');+ port = await spawnHost(MODE, token).catch((e) => {+ log('FATAL', e.message);+ process.exit(1);+ });+}+process.stdin.on('close', () => process.exit(0));+log(`${MODE} host ready on 127.0.0.1:${port} (writes ${ALLOW_WRITES ? 'ENABLED' : 'disabled'})`);async function post(body) {const res = await fetch(`http://127.0.0.1:${port}/exec`, {@@ -87,9 +121,11 @@ async function post(body) {return out.hasResult ? out.result : undefined;}-// The registry's driver: surface method calls + renderer-code snippets.-const driver = (method, args) => post({ method, args });+// The registry's driver: surface/editor method calls, renderer-code snippets,+// and main-process ops.+const driver = (method, args, root) => post({ method, args, root });driver.js = (js) => post({ js });+driver.op = (op, input) => post({ op, ...input });const mcp = new Server({ name: 'estella-editor', version: '0.2.0' },diff --git a/desktop/scripts/mcp-exec-endpoint.mjs b/desktop/scripts/mcp-exec-endpoint.mjsnew file mode 100644index 000000000..617afd305--- /dev/null+++ b/desktop/scripts/mcp-exec-endpoint.mjs@@ -0,0 +1,46 @@+// 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.+ *+ * 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 }`).+ * The MCP protocol layer lives in the plain-node front (editor-mcp.mjs); hosts —+ * the headless render host and the live editor app — differ only in how they+ * resolve a payload to a result, which they supply as `run(payload)`.+ *+ * Plain .mjs so both host flavors can use it: the headless host imports it+ * directly, the editor main process bundles it through esbuild.+ */+import http from 'node:http';++const readBody = (req) => new Promise((resolve, reject) => {+ const chunks = [];+ req.on('data', (c) => chunks.push(c));+ req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));+ req.on('error', reject);+});++/**+ * Start the endpoint. `run(payload)` executes one call (payload is the parsed+ * request body — `{method, args, root?}`, `{js}`, or `{op, ...}`) and may return+ * any JSON-able value (undefined = void). Returns the http.Server, already+ * listening; read `.address().port`.+ */+export function createExecEndpoint({ token, run }) {+ const server = http.createServer(async (req, res) => {+ const reply = (code, body) => {+ res.writeHead(code, { 'content-type': 'application/json' });+ res.end(JSON.stringify(body));+ };+ if (req.method !== 'POST' || req.url !== '/exec') return reply(404, { ok: false, error: 'not found' });+ if (req.headers['x-estella-mcp-token'] !== token) return reply(403, { ok: false, error: 'bad token' });+ try {+ const result = await run(JSON.parse(await readBody(req)));+ reply(200, { ok: true, hasResult: result !== undefined, result: result === undefined ? null : result });+ } catch (e) {+ reply(200, { ok: false, error: String((e && e.message) || e) });+ }+ });+ return new Promise((resolve) => server.listen(0, '127.0.0.1', () => resolve(server)));+}diff --git a/desktop/src/main.tsx b/desktop/src/main.tsxindex 9ade71201..3a18b2ded 100644--- a/desktop/src/main.tsx+++ b/desktop/src/main.tsx@@ -46,6 +46,7 @@ import { EngineHost } from './engine/EngineHost';import { Particle, getComponent } from 'esengine';import { applyFxPreview, initFxPreviewEditRestart } from './engine/fxPreview';import { commands } from './commands/registry';+import { ENTITY_SOURCES, sourceById, createFromSource } from './engine/entitySources';import { ViewportController } from './engine/ViewportController';import { PerfMonitor } from './engine/PerfMonitor';import { LogStore } from './store/LogStore';@@ -100,6 +101,21 @@ if (new URLSearchParams(location.search).has('automation')) {},/** Dispatch any registered editor command by id (the UI's own channel). */runCommand: (id: string) => commands.run(id),+ /** Save the open scene to disk (the toolbar Save, awaitable). */+ save: () => ProjectStore.save(),+ /** Create a blank scene FILE under `destDir` (Content Browser "New Scene"). */+ createSceneFile: (destDir: string) => ProjectStore.createSceneFile(destDir),+ /** The Create-popover catalog: every ready-made entity the editor can spawn. */+ listEntityTemplates: () => ENTITY_SOURCES.map(({ id, label, category }) => ({ id, label, category })),+ /** Spawn a ready-made entity through the one create pipeline (menu/DnD parity). */+ createEntity: async (sourceId: string, opts?: { parent?: number | null; x?: number; y?: number }) => {+ const source = sourceById(sourceId);+ if (!source) throw new Error(`unknown entity template: ${sourceId} (see listEntityTemplates)`);+ return createFromSource(source, {+ parent: opts?.parent ?? null,+ position: opts?.x != null && opts?.y != null ? { x: opts.x, y: opts.y } : undefined,+ });+ },/** Double-click-open an asset by project path (FSM/BT/tileset/clip editors…). */openAsset: (path: string) => {const name = path.split('/').pop() ?? path;diff --git a/desktop/tests/editor-mcp-tools.test.ts b/desktop/tests/editor-mcp-tools.test.tsindex 32d259360..bd323c85d 100644--- a/desktop/tests/editor-mcp-tools.test.ts+++ b/desktop/tests/editor-mcp-tools.test.ts@@ -8,10 +8,11 @@ import { TOOLS, RESOURCES, runTool, listTools } from '../scripts/editor-mcp-tool// surface method. These cover the pure dispatch layer (no Electron) — the Electron entry// only supplies the executeJavaScript driver.describe('editor MCP tool registry', () => {- it('every tool has a unique name and either a surface method or renderer code', () => {+ it('every tool has a unique name and a surface method, renderer code, or host op', () => {const names = new Set<string>();- for (const t of TOOLS as Array<{ name: string; method?: string; args?: unknown; js?: unknown }>) {+ for (const t of TOOLS as Array<{ name: string; method?: string; args?: unknown; js?: unknown; op?: unknown }>) {if (t.js) expect(typeof t.js).toBe('function');+ else if (t.op) expect(typeof t.op).toBe('string');else {expect(typeof t.method).toBe('string');expect(typeof t.args).toBe('function');@@ -22,13 +23,34 @@ describe('editor MCP tool registry', () => {expect(TOOLS.length).toBeGreaterThan(10);});+ it('editor-root tools pass their root through to the driver', async () => {+ const driver = vi.fn(async () => 3);+ const createEntity = TOOLS.find((t: { name: string }) => t.name === 'create_entity');+ const res = await runTool(createEntity, driver, { template: 'anchor:Sprite', x: 10, y: 20 });+ expect(driver).toHaveBeenCalledWith(+ 'createEntity',+ ['anchor:Sprite', { parent: null, x: 10, y: 20 }],+ 'editor',+ );+ expect(res.content[0].text).toBe('3');+ });++ it('an op tool routes through driver.op and wraps as an image', async () => {+ const driver = vi.fn() as unknown as { op: ReturnType<typeof vi.fn> } & ((...a: unknown[]) => unknown);+ driver.op = vi.fn(async () => 'cGpn');+ const shot = TOOLS.find((t: { name: string }) => t.name === 'screenshot');+ const res = await runTool(shot, driver, {});+ expect(driver.op).toHaveBeenCalledWith('screenshot', {});+ expect(res.content[0]).toEqual({ type: 'image', data: 'cGpn', mimeType: 'image/png' });+ });+it('runTool validates input and calls the driver with (method, args)', async () => {const driver = vi.fn(async () => 42);const setField = TOOLS.find((t: { name: string }) => t.name === 'set_field');const res = await runTool(setField, driver, {entity: 1, component: 'Transform', key: 'position.x', type: 'float', value: 5,});- expect(driver).toHaveBeenCalledWith('setField', [1, 'Transform', 'position.x', 'float', 5]);+ expect(driver).toHaveBeenCalledWith('setField', [1, 'Transform', 'position.x', 'float', 5], undefined);expect(res.content[0].text).toBe('42');expect(res.isError).toBeFalsy();});