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): the installed editor ships its MCP server - any AI tool connects
yhh5fd411237bba
diff --git a/desktop/README.md b/desktop/README.mdindex 2fd2a31b0..01cc1f9eb 100644--- a/desktop/README.md+++ b/desktop/README.md@@ -68,8 +68,10 @@ public/ wasm runtime, bundled SDK, example projects (served at web root- **Runtime** — the SDK + `esengine.wasm` boot into a `<canvas>` in `Viewport`; theeditor drives the world through `EditorControlSurface` (also exposed to headless- automation and AI agents over an MCP server: `pnpm editor:mcp`, see- `scripts/editor-mcp.mjs`; mutating tools need `ESTELLA_MCP_ALLOW_WRITES=1`).+ automation and AI agents over an MCP server: `pnpm editor:mcp` for the fixtures+ host, `pnpm editor:mcp -- --editor` to drive the real app — projects, entity+ creation, play, export. Mutating tools need `ESTELLA_MCP_ALLOW_WRITES=1`; the+ installed editor ships the server bundled — see the "AI Agents (MCP)" guide).- **Scenes & assets** — `ProjectStore` opens a project from disk and the Electron mainprocess watches it (`fs` + `chokidar`); the `ContentBrowser` browses and creates assets.- **Inspector** — `Details` is generated from the engine's reflection metadata:diff --git a/desktop/electron-builder.yml b/desktop/electron-builder.ymlindex 33effac94..e0c259c73 100644--- a/desktop/electron-builder.yml+++ b/desktop/electron-builder.yml@@ -26,6 +26,9 @@ files:asarUnpack:- "**/node_modules/{esbuild,@esbuild}/**"- dist-electron/hosts/**+ # The MCP front: an MCP client runs this with plain node (node cannot read+ # inside an asar), which spawns/attaches the editor as the MCP host.+ - dist-electron/mcp/**- "**/node_modules/esengine/dist/**"- dist/wasm/**- dist/wasm-wechat/**diff --git a/desktop/package.json b/desktop/package.jsonindex 59c5471dc..6526f4943 100644--- a/desktop/package.json+++ b/desktop/package.json@@ -9,7 +9,7 @@"main": "dist-electron/main.js","scripts": {"dev": "vite",- "build": "tsc --noEmit && vite build",+ "build": "tsc --noEmit && vite build && node scripts/bundle-mcp.mjs","dist": "vite build && electron-builder","dist:dir": "vite build && electron-builder --dir","preview": "vite preview",diff --git a/desktop/scripts/bundle-mcp.mjs b/desktop/scripts/bundle-mcp.mjsnew file mode 100644index 000000000..ea2b0cffd--- /dev/null+++ b/desktop/scripts/bundle-mcp.mjs@@ -0,0 +1,32 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file bundle-mcp.mjs — bundle the MCP front into one self-contained file the+ * INSTALLED editor ships (dist-electron/mcp/editor-mcp.mjs, asar-unpacked+ * so plain node can run it). This is how any MCP client reaches an+ * installed Estella: `node <resources>/app.asar.unpacked/dist-electron/+ * mcp/editor-mcp.mjs --editor`. The editor stays the single distribution+ * channel — no npm package to keep in sync.+ */+import { build } from 'esbuild';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const HERE = path.dirname(fileURLToPath(import.meta.url));++await build({+ entryPoints: [path.join(HERE, 'editor-mcp.mjs')],+ outfile: path.join(HERE, '..', 'dist-electron', 'mcp', 'editor-mcp.mjs'),+ bundle: true,+ platform: 'node',+ format: 'esm',+ // Only the dev repo resolves electron (lazy createRequire); the installed+ // flow spawns the editor exe instead, so leave the specifier external.+ external: ['electron'],+ // CJS deps inside the ESM bundle may call require() at runtime.+ banner: {+ js: "import { createRequire as __bundleRequire } from 'node:module'; const require = __bundleRequire(import.meta.url);",+ },+ logLevel: 'warning',+});+console.log('[bundle-mcp] dist-electron/mcp/editor-mcp.mjs written');diff --git a/desktop/scripts/editor-mcp-editor-e2e.mjs b/desktop/scripts/editor-mcp-editor-e2e.mjsindex dadef79e5..26d29dbbf 100644--- a/desktop/scripts/editor-mcp-editor-e2e.mjs+++ b/desktop/scripts/editor-mcp-editor-e2e.mjs@@ -28,7 +28,10 @@ await cp(EXAMPLE, project, {filter: (src) => !/[/\\](\.esengine|node_modules|dist)([/\\]|$)/.test(src),});-const child = spawn(process.execPath, ['scripts/editor-mcp.mjs', '--editor'], {+// ESTELLA_E2E_FRONT points at an alternate front (e.g. the shipped bundle,+// dist-electron/mcp/editor-mcp.mjs) to prove distribution artifacts end to end.+const front = process.env.ESTELLA_E2E_FRONT ?? 'scripts/editor-mcp.mjs';+const child = spawn(process.execPath, [front, '--editor'], {cwd: DESKTOP,stdio: ['pipe', 'pipe', 'pipe'],env: { ...process.env, ESTELLA_MCP_ALLOW_WRITES: '1' },diff --git a/desktop/scripts/editor-mcp.mjs b/desktop/scripts/editor-mcp.mjsindex 82bfcb633..70c9f2ca1 100644--- a/desktop/scripts/editor-mcp.mjs+++ b/desktop/scripts/editor-mcp.mjs@@ -7,9 +7,13 @@* 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)+ * (default) spawn the headless render host (fixtures; scene tools only;+ * dev repo only)* --editor spawn the REAL editor app with --mcp — the full game-making- * surface: projects, assets, entity templates, play, export+ * surface: projects, assets, entity templates, play, export.+ * In the dev repo this is `electron .`; from the installed+ * editor (this file ships bundled under app.asar.unpacked)+ * the exe is auto-detected, or pass --editor-exe <path>.* --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@@ -24,7 +28,7 @@*/import { spawn } from 'node:child_process';import { randomBytes } from 'node:crypto';-import { readFileSync } from 'node:fs';+import { existsSync, readFileSync } from 'node:fs';import path from 'node:path';import { createRequire } from 'node:module';import { fileURLToPath } from 'node:url';@@ -39,22 +43,63 @@ import {import { TOOLS, RESOURCES, listTools, runTool } from './editor-mcp-tools.mjs';const HERE = path.dirname(fileURLToPath(import.meta.url));-const DESKTOP = path.resolve(HERE, '..');+// The desktop package root, for dev spawns (`electron .`). This file runs from+// scripts/ in the repo but from dist-electron/mcp/ as the shipped bundle, so+// walk up to the nearest package.json instead of assuming one level.+const DESKTOP = (() => {+ let dir = HERE;+ for (let i = 0; i < 4; i++) {+ dir = path.dirname(dir);+ if (existsSync(path.join(dir, 'package.json'))) return dir;+ }+ return path.resolve(HERE, '..');+})();const ALLOW_WRITES = process.env.ESTELLA_MCP_ALLOW_WRITES === '1';const log = (...a) => process.stderr.write(`[editor-mcp] ${a.join(' ')}\n`);const argv = process.argv.slice(2);-const MODE = argv.includes('--editor') ? 'editor' : argv.includes('--attach') ? 'attach' : 'headless';+const MODE = argv.includes('--editor') || argv.includes('--editor-exe')+ ? 'editor'+ : argv.includes('--attach') ? 'attach' : 'headless';+// When this file ships inside the installed editor it lives under+// resources/app.asar.unpacked/dist-electron/mcp/ — four levels below the install+// root (three on macOS, where the exe sits in Contents/MacOS instead).+const PACKAGED = /app\.asar\.unpacked/.test(HERE);++const argValue = (flag) => {+ const i = argv.indexOf(flag);+ const v = i >= 0 ? argv[i + 1] : undefined;+ return v && !v.startsWith('--') ? v : undefined;+};++/** The installed editor executable, derived from this bundle's unpacked path. */+function installedEditorExe() {+ const resources = path.resolve(HERE, '..', '..', '..'); // …/resources+ if (process.platform === 'darwin') return path.resolve(resources, '..', 'MacOS', 'Estella Editor');+ return path.resolve(resources, '..', process.platform === 'win32' ? 'estella-editor.exe' : 'estella-editor');+}-/** Spawn an Electron host (headless fixtures or the real editor app with --mcp)+/** Spawn an Estella host (headless fixtures, dev editor, or installed editor)* 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,+ const editorExe = argValue('--editor-exe') ?? (PACKAGED && mode === 'editor' ? installedEditorExe() : undefined);+ let command;+ let args;+ if (editorExe) {+ command = editorExe;+ args = ['--mcp'];+ } else if (PACKAGED) {+ log('FATAL: the headless host is dev-repo only — use --editor (or --attach) with the installed editor');+ process.exit(1);+ } else {+ // 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).+ command = createRequire(import.meta.url)('electron');+ args = mode === 'editor' ? ['.', '--mcp'] : [path.join(HERE, 'editor-mcp-host.mjs')];+ }+ const host = spawn(command, args, {+ // An installed exe needs no cwd (and the repo layout may not exist there).+ cwd: editorExe ? undefined : DESKTOP,stdio: ['ignore', 'pipe', 'pipe'],env: {...process.env,diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 02476fcf5..68ae81fb4 100644--- a/docs/astro/astro.config.mjs+++ b/docs/astro/astro.config.mjs@@ -109,6 +109,7 @@ export default defineConfig({{ label: 'Building & Exporting', translations: { 'zh-CN': '构建与导出' }, slug: 'guides/build-export' },{ label: 'WeChat MiniGame', translations: { 'zh-CN': '微信小游戏' }, slug: 'guides/wechat' },{ label: 'Networking', translations: { 'zh-CN': '联网' }, slug: 'guides/networking' },+ { label: 'AI Agents (MCP)', translations: { 'zh-CN': 'AI 代理 (MCP)' }, slug: 'guides/mcp' },],},{diff --git a/docs/astro/src/content/docs/guides/mcp.mdx b/docs/astro/src/content/docs/guides/mcp.mdxnew file mode 100644index 000000000..d3a6f8142--- /dev/null+++ b/docs/astro/src/content/docs/guides/mcp.mdx@@ -0,0 +1,107 @@+---+title: AI Agents (MCP)+description: The Estella editor is an MCP server — connect Claude Code, Cursor, or any MCP-capable AI tool and let it open projects, build scenes, edit components, run play mode, take screenshots, and export builds.+---++import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';++The Estella editor speaks the **Model Context Protocol (MCP)**. Any MCP-capable AI+tool — Claude Code, Cursor, or your own agent — can drive the real editor: open or+create projects, open scenes, spawn entities from the same Create-menu catalog you+use, edit component fields, verify the result in the live engine World, enter play+mode, take screenshots to *see* what it built, and export the finished game — the+exact pipelines the UI uses, forty tools in all.++<Aside type="tip">+Everything an agent does goes through the editor's own command surface — creates+are undoable, play mode never dirties the edit scene, and saves are the toolbar+Save. You can watch it work in the editor window, and take over at any time.+</Aside>++## Connecting an AI tool++The MCP server is a small node script that ships inside the editor. It talks MCP+over stdio to your AI tool and drives an editor instance for you (spawning one, or+attaching to one that's already open).++Its path inside an installed editor:++- **Windows** — `%LOCALAPPDATA%\Programs\@estellaeditor\resources\app.asar.unpacked\dist-electron\mcp\editor-mcp.mjs`+- **macOS** — `/Applications/Estella Editor.app/Contents/Resources/app.asar.unpacked/dist-electron/mcp/editor-mcp.mjs`++<Tabs>+<TabItem label="Claude Code">++```sh+claude mcp add estella --env ESTELLA_MCP_ALLOW_WRITES=1 -- \+ node "<path-to>/editor-mcp.mjs" --editor+```++</TabItem>+<TabItem label="Any MCP client">++```json+{+ "mcpServers": {+ "estella": {+ "command": "node",+ "args": ["<path-to>/editor-mcp.mjs", "--editor"],+ "env": { "ESTELLA_MCP_ALLOW_WRITES": "1" }+ }+ }+}+```++</TabItem>+</Tabs>++`--editor` launches the installed editor with the MCP endpoint enabled. Node.js 20++must be on your PATH.++<Aside type="caution">+Without `ESTELLA_MCP_ALLOW_WRITES=1` the agent can only **observe** — every+mutating tool (creating entities, editing fields, saving, exporting) is hidden and+refused. Grant writes deliberately.+</Aside>++## Driving the editor you're looking at++To let an agent work inside an editor session you already have open, start the+editor with the endpoint enabled and point the server at its discovery file:++<Steps>++1. Launch the editor with `--mcp` (from a terminal: `estella-editor --mcp`). It+ writes a discovery file `mcp-endpoint.json` into the editor's user-data folder+ (Windows: `%APPDATA%\Estella Editor\`; the exact path is printed on startup).++2. Configure your AI tool with `--attach` instead of `--editor`:++ ```json+ "args": ["<path-to>/editor-mcp.mjs", "--attach", "<path-to>/mcp-endpoint.json"]+ ```++3. The agent now drives the same window you see — selections, edits, play mode and+ all — while you watch and intervene.++</Steps>++## What the agent can do++| Area | Tools (excerpt) |+| --- | --- |+| Observe | `get_scene_tree`, `get_inspector`, `get_stats`, `capture_viewport` (PNG), `screenshot` (whole window, includes play), `world_component` (live-World probe) |+| Edit scenes | `create_entity` (the Create-menu catalog via `list_entity_templates`), `set_field`, `set_entity_xy`, `set_parent`, `duplicate_entity`, `undo` / `redo` |+| Projects & assets | `create_project` / `open_project`, `open_scene`, `save_scene`, `create_scene_file`, `create_asset`, `import_assets` |+| Run & ship | `toggle_play` + `get_play_state`, `export_game` (web / desktop / wechat / playable) |++A typical agent loop: `open_project` → `open_scene` → `list_entity_templates` →+`create_entity` → `set_field` → `screenshot` to check its work → `save_scene` →+`toggle_play` → `screenshot` again → `export_game`.++## From the repository (contributors)++In a source checkout, `pnpm --filter @estella/editor editor:mcp` serves the same+registry against a headless fixtures host (scene tools only), `editor:mcp -- --editor`+boots the dev editor, and two e2e suites (`editor:mcp:e2e`,+`editor:mcp:editor-e2e`) prove the full loop.diff --git a/docs/astro/src/content/docs/zh-cn/guides/mcp.mdx b/docs/astro/src/content/docs/zh-cn/guides/mcp.mdxnew file mode 100644index 000000000..7cb71e022--- /dev/null+++ b/docs/astro/src/content/docs/zh-cn/guides/mcp.mdx@@ -0,0 +1,101 @@+---+title: AI 代理 (MCP)+description: Estella 编辑器本身就是一个 MCP 服务器——接入 Claude Code、Cursor 或任何支持 MCP 的 AI 工具,让它打开项目、搭建场景、编辑组件、运行 Play 模式、截图验证并导出成品。+---++import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';++Estella 编辑器支持 **Model Context Protocol (MCP)**。任何支持 MCP 的 AI 工具——+Claude Code、Cursor,或你自己写的代理——都能驱动真实的编辑器:打开或创建项目、+打开场景、用与你相同的"创建"菜单目录生成实体、编辑组件字段、在活的引擎 World+里验证结果、进入 Play 模式、截图*亲眼看到*它搭出来的东西,并把成品游戏导出+——走的都是 UI 自己的管线,共 40 个工具。++<Aside type="tip">+代理做的每件事都经过编辑器自己的命令面——创建可撤销、Play 模式不会弄脏编辑+场景、保存就是工具栏的保存。你可以在编辑器窗口里看着它干活,随时接手。+</Aside>++## 接入 AI 工具++MCP 服务器是随编辑器一起分发的一个小 node 脚本。它对你的 AI 工具讲 stdio MCP,+并为你驱动一个编辑器实例(拉起新的,或挂到已打开的那个上)。++它在安装版编辑器里的路径:++- **Windows** — `%LOCALAPPDATA%\Programs\@estellaeditor\resources\app.asar.unpacked\dist-electron\mcp\editor-mcp.mjs`+- **macOS** — `/Applications/Estella Editor.app/Contents/Resources/app.asar.unpacked/dist-electron/mcp/editor-mcp.mjs`++<Tabs>+<TabItem label="Claude Code">++```sh+claude mcp add estella --env ESTELLA_MCP_ALLOW_WRITES=1 -- \+ node "<path-to>/editor-mcp.mjs" --editor+```++</TabItem>+<TabItem label="任意 MCP 客户端">++```json+{+ "mcpServers": {+ "estella": {+ "command": "node",+ "args": ["<path-to>/editor-mcp.mjs", "--editor"],+ "env": { "ESTELLA_MCP_ALLOW_WRITES": "1" }+ }+ }+}+```++</TabItem>+</Tabs>++`--editor` 会以启用 MCP 端点的方式启动安装版编辑器。PATH 里需要 Node.js 20+。++<Aside type="caution">+不设 `ESTELLA_MCP_ALLOW_WRITES=1` 时代理只能**观察**——所有会产生修改的工具+(创建实体、改字段、保存、导出)都被隐藏并拒绝。写权限请有意识地授予。+</Aside>++## 驱动你正看着的编辑器++想让代理在你已经打开的编辑器会话里干活:以启用端点的方式启动编辑器,把服务器+指向它的发现文件即可:++<Steps>++1. 用 `--mcp` 启动编辑器(终端里:`estella-editor --mcp`)。它会在编辑器的+ user-data 目录写一个发现文件 `mcp-endpoint.json`(Windows:+ `%APPDATA%\Estella Editor\`;确切路径启动时会打印出来)。++2. AI 工具的配置里用 `--attach` 代替 `--editor`:++ ```json+ "args": ["<path-to>/editor-mcp.mjs", "--attach", "<path-to>/mcp-endpoint.json"]+ ```++3. 代理现在驱动的就是你眼前的这个窗口——选择、编辑、Play 全部同步——你可以+ 一边看一边随时介入。++</Steps>++## 代理能做什么++| 领域 | 工具(节选) |+| --- | --- |+| 观察 | `get_scene_tree`、`get_inspector`、`get_stats`、`capture_viewport`(PNG)、`screenshot`(整窗截图,含 Play 画面)、`world_component`(活 World 探针) |+| 编辑场景 | `create_entity`(配合 `list_entity_templates` 的创建目录)、`set_field`、`set_entity_xy`、`set_parent`、`duplicate_entity`、`undo` / `redo` |+| 项目与资产 | `create_project` / `open_project`、`open_scene`、`save_scene`、`create_scene_file`、`create_asset`、`import_assets` |+| 运行与发布 | `toggle_play` + `get_play_state`、`export_game`(web / desktop / wechat / playable) |++典型的代理循环:`open_project` → `open_scene` → `list_entity_templates` →+`create_entity` → `set_field` → `screenshot` 检查成果 → `save_scene` →+`toggle_play` → 再次 `screenshot` → `export_game`。++## 从源码仓库使用(贡献者)++源码仓库里,`pnpm --filter @estella/editor editor:mcp` 用无头夹具宿主提供同一套+注册表(仅场景工具),`editor:mcp -- --editor` 拉起开发版编辑器;两套 e2e+(`editor:mcp:e2e`、`editor:mcp:editor-e2e`)验证完整闭环。