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): first dogfood friction batch - MCP contracts + template hygiene

yhh53ecb99aba5a
diff --git a/desktop/electron-builder.yml b/desktop/electron-builder.yml
index e0c259c73..6c73c1aae 100644
--- a/desktop/electron-builder.yml
+++ b/desktop/electron-builder.yml
@@ -60,6 +60,14 @@ extraResources:
- "!**/dist/**"
win:
target: nsis
+# Assisted (non-oneClick) installer: electron-builder derives the oneClick
+# install dir from the SANITIZED PACKAGE NAME (@estella/editor -> a literal
+# `@estellaeditor` folder under LocalAppData\Programs — issue #3100); the
+# assisted flow uses productName ("Estella Editor") and lets the user pick.
+nsis:
+ oneClick: false
+ perMachine: false
+ allowToChangeInstallationDirectory: true
mac:
# arm64 only: a universal build would merge an x64 slice, but pnpm 10 installs just
# the host-arch esbuild native binary, so the x64 slice would ship a broken esbuild
diff --git a/desktop/scripts/editor-mcp-editor-e2e.mjs b/desktop/scripts/editor-mcp-editor-e2e.mjs
index 26d29dbbf..f02a65987 100644
--- a/desktop/scripts/editor-mcp-editor-e2e.mjs
+++ b/desktop/scripts/editor-mcp-editor-e2e.mjs
@@ -90,14 +90,11 @@ try {
await call('open_project', { root: project }, 120_000);
console.log('open_project OK');
+ // No polling: open_scene's contract is "resolved = adopted", so the very next
+ // tree read must already be populated (this line is the contract's regression
+ // guard — do not add a retry loop here).
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));
- }
+ const tree = JSON.parse((await call('get_scene_tree')).text);
if (!Array.isArray(tree) || tree.length === 0) await fail('scene tree empty after open_scene');
console.log(`open_scene OK — ${tree.length} roots`);
diff --git a/desktop/scripts/editor-mcp-tools.mjs b/desktop/scripts/editor-mcp-tools.mjs
index ee166f324..2b5aa71cb 100644
--- a/desktop/scripts/editor-mcp-tools.mjs
+++ b/desktop/scripts/editor-mcp-tools.mjs
@@ -134,7 +134,7 @@ export const TOOLS = [
// 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.',
+ 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,
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.',
@@ -142,11 +142,12 @@ export const TOOLS = [
['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.',
+ description: 'Open a project by absolute root path and enter the editor. Resolves once the initial scene is loaded and readable — 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; })` },
+ js: (i) => `window.__estellaEditor.open(${JSON.stringify(i.root)})
+ .then((ok) => { window.__estellaEditor.enterEditor(); return window.__estellaEditor.sceneReady().then(() => ok); })` },
{ name: 'open_scene',
- description: 'Open a scene by project-relative path (e.g. assets/scenes/main.esscene) in the editor.',
+ description: 'Open a scene by project-relative path (e.g. assets/scenes/main.esscene) in the editor. Resolves once the scene is adopted — get_scene_tree is immediately valid.',
schema: obj({ path: { type: 'string' } }, ['path']),
method: 'openScene', args: (i) => [i.path], root: 'editor' },
{ name: 'save_scene', write: true,
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index 3a18b2ded..8bd0cfd0e 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -83,7 +83,26 @@ if (new URLSearchParams(location.search).has('automation')) {
(window as unknown as { __estellaEditor?: unknown }).__estellaEditor = {
open: (root: string) => ProjectStore.open(root),
enterEditor: () => useEditorStore.getState().enterEditor(),
- openScene: (rel: string) => ProjectStore.openScene(rel),
+ /** Resolves once the scene is ADOPTED and readable (drivers must not need
+ * their own get_scene_tree polling): waits out the model-version bump the
+ * adopt performs, racing the engine boot on a freshly opened project. */
+ openScene: async (rel: string) => {
+ const v0 = EditorControlSurface.worldVersion();
+ await ProjectStore.openScene(rel);
+ const t0 = Date.now();
+ while (EditorControlSurface.worldVersion() === v0 && Date.now() - t0 < 30_000) {
+ await new Promise((r) => setTimeout(r, 100));
+ }
+ },
+ /** Resolves once the project's initial scene is in the tree (call after
+ * open + enterEditor; the boot pipeline loads the last-opened scene). */
+ sceneReady: async (timeoutMs = 30_000) => {
+ const t0 = Date.now();
+ while (EditorControlSurface.getSceneTree().length === 0 && Date.now() - t0 < timeoutMs) {
+ await new Promise((r) => setTimeout(r, 100));
+ }
+ return EditorControlSurface.getSceneTree().length > 0;
+ },
selectAsset: (path: string | null) => useSelection.getState().selectAsset(path),
play: () => useEditorStore.getState().togglePlay(),
playState: () => PlayRealm.getSnapshot(),
diff --git a/desktop/templates/blank/.gitignore b/desktop/templates/blank/.gitignore
index 359472ac2..b4fb62542 100644
--- a/desktop/templates/blank/.gitignore
+++ b/desktop/templates/blank/.gitignore
@@ -4,4 +4,7 @@ dist/
.idea/
.DS_Store
Thumbs.db
-.esengine/cache/
+
+# Editor-managed staging: the sdk types mirror and play-realm build are
+# regenerated every time the editor opens the project.
+.esengine/