Skip to content

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.

fix(editor): restore the surface driver the MCP endpoint imports

esenginebf0cbc49cc84
diff --git a/desktop/electron/surfaceDriver.ts b/desktop/electron/surfaceDriver.ts
new file mode 100644
index 000000000..ba3bca4a1
--- /dev/null
+++ b/desktop/electron/surfaceDriver.ts
@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @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
+ * 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 renderer
+ * cannot — the composited window, and the play realm's out-of-process frame.
+ *
+ * Deliberately transport-free. The loopback /exec endpoint wraps this
+ * (mcpEndpoint.ts owns the token, discovery file and ready line), and anything
+ * else in main that wants to drive the editor calls the same object directly —
+ * so an in-process caller and a remote MCP client cannot drift apart.
+ */
+import type { BrowserWindow } from 'electron';
+
+/** What the tool registry calls: a surface/editor method, plus the two escape
+ * hatches it also knows about (`js` renderer code, `op` main-process routines). */
+export interface SurfaceDriver {
+ (method: string, args?: readonly unknown[], root?: string): Promise<unknown>;
+ js(code: string): Promise<unknown>;
+ op(op: string, input?: { code?: string; frame?: number }): Promise<unknown>;
+}
+
+/**
+ * executeJavaScript rejects a thrown error with an opaque "Script failed to
+ * execute". Wrap the expression so the real message crosses the boundary — a
+ * surface error like `component "X" is not on entity 5` IS the caller's
+ * feedback, not a debugging detail.
+ */
+const carryError = (expr: string): string =>
+ `(async () => { try { return { v: await (${expr}) }; } catch (e) { return { __estellaExecError: (e && e.message) || String(e) }; } })()`;
+
+function unwrap(res: unknown): unknown {
+ const r = res as { v?: unknown; __estellaExecError?: string } | null;
+ if (r && typeof r === 'object' && r.__estellaExecError !== undefined) throw new Error(r.__estellaExecError);
+ return r?.v;
+}
+
+/** JSON-encode a call's arguments, keeping `undefined` as the literal so the
+ * target method's own default parameters apply. */
+const encodeArgs = (args: readonly unknown[]): string =>
+ args.map((a) => (a === undefined ? 'undefined' : JSON.stringify(a))).join(',');
+
+/**
+ * A driver bound to the editor window. `getWin` re-resolves per call, so a
+ * recreated window keeps working and a driver built before the window exists
+ * is still valid.
+ */
+export function createSurfaceDriver(getWin: () => BrowserWindow | null): SurfaceDriver {
+ const requireWin = (): BrowserWindow => {
+ const win = getWin();
+ if (!win) throw new Error('no editor window');
+ return win;
+ };
+
+ const exec = async (code: string): Promise<unknown> => {
+ const win = requireWin();
+ // 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 unwrap(await win.webContents.executeJavaScript(carryError(code), true));
+ };
+
+ const driver = ((method: string, args: readonly unknown[] = [], root?: string) => {
+ const target = root === 'editor' ? 'window.__estellaEditor' : 'window.__estellaEditor.surface';
+ return exec(`${target}.${method}(${encodeArgs(args)})`);
+ }) as SurfaceDriver;
+
+ driver.js = exec;
+
+ driver.op = async (op, input = {}) => {
+ switch (op) {
+ case 'screenshot': {
+ // The composited window, not the viewport canvas: this is the only way to
+ // see the play realm, which renders in its own frame.
+ const image = await requireWin().webContents.capturePage();
+ return image.toPNG().toString('base64');
+ }
+ case 'play_probe': {
+ // The play realm is an estella:// OOPIF — only a main-process frame eval
+ // reaches it (window.__estellaPlay is the probe the realm publishes).
+ const frames = requireWin().webContents.mainFrame.frames.filter((f) => f.url.startsWith('estella://'));
+ const at = input.frame ?? 0;
+ const frame = frames[at];
+ if (!frame) {
+ throw new Error(`no play realm at index ${at} (${frames.length} running — enter play first)`);
+ }
+ return unwrap(await frame.executeJavaScript(carryError(input.code ?? 'true')));
+ }
+ default:
+ throw new Error(`unknown main-process op: ${op}`);
+ }
+ };
+
+ return driver;
+}