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(project): a missing remembered scene no longer bricks the project

yhh2fa4fee84813
diff --git a/desktop/scripts/editor-mcp-tools.mjs b/desktop/scripts/editor-mcp-tools.mjs
index 585d2361e..5d3beb439 100644
--- a/desktop/scripts/editor-mcp-tools.mjs
+++ b/desktop/scripts/editor-mcp-tools.mjs
@@ -171,10 +171,9 @@ 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. Resolves once the initial scene is loaded and readable — call before any scene/asset work on the editor host.',
+ description: 'Open a project by absolute root path and enter the editor. Resolves TRUE once the initial scene is loaded and readable — call before any scene/asset work on the editor host. Throws, naming the step that failed, if the project cannot be opened or no scene loads; it never reports a failure as a plain false, because a caller that keeps going against a project that never opened just collects "no project open" from every later tool.',
schema: obj({ root: { type: 'string' } }, ['root']),
- js: (i) => `window.__estellaEditor.open(${JSON.stringify(i.root)})
- .then((ok) => { window.__estellaEditor.enterEditor(); return window.__estellaEditor.sceneReady().then(() => ok); })` },
+ js: (i) => `window.__estellaEditor.open(${JSON.stringify(i.root)})` },
{ name: 'open_scene',
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. '
+ '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.',
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index a4188460c..7b8afcc6d 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -92,7 +92,38 @@ initFxPreviewEditRestart();
// editor never carries it; mirrors the headless render host's `window.__estellaHeadless`.
if (new URLSearchParams(location.search).has('automation')) {
(window as unknown as { __estellaEditor?: unknown }).__estellaEditor = {
- open: (root: string) => ProjectStore.open(root),
+ /**
+ * The whole launcher → editor → scene-ready sequence, or a throw saying
+ * which step failed.
+ *
+ * It used to be the three calls below, chained by the tool definition, with
+ * the boolean from the open DISCARDED: a project that failed to open still
+ * got `enterEditor()`, so the shell left the launcher with nothing loaded,
+ * the driver waited out the scene timeout, and every later call answered
+ * "no project open" — with the reason only ever shown as a toast nobody was
+ * looking at. Sequencing belongs next to the code that knows the order.
+ */
+ open: async (root: string) => {
+ if (!(await ProjectStore.open(root))) {
+ throw new Error(
+ `could not open the project at ${root} — it is still closed. `
+ + 'The editor logged the reason (check the Output Log); a bad path and an '
+ + 'unreadable project manifest are the usual ones.',
+ );
+ }
+ useEditorStore.getState().enterEditor();
+ const t0 = Date.now();
+ while (EditorControlSurface.getSceneTree().length === 0 && Date.now() - t0 < 30_000) {
+ await new Promise((r) => setTimeout(r, 100));
+ }
+ if (EditorControlSurface.getSceneTree().length === 0) {
+ throw new Error(
+ `the project at ${root} opened but no scene loaded — it may have none yet. `
+ + 'Name one with open_scene, or create one with create_scene_file.',
+ );
+ }
+ return true;
+ },
enterEditor: () => useEditorStore.getState().enterEditor(),
/** 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
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index d56781aeb..362f5412d 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -461,6 +461,46 @@ class ProjectStoreImpl {
useEditorMode.setState({ orientation: resolveOrientation(opened.manifest) });
}
+ /**
+ * The first of `candidates` that is actually there, plus its contents.
+ *
+ * Tried in order, then any `.esscene` sitting in the project's scenes folder —
+ * a project that still has scenes should open on one of them rather than on the
+ * name it happens to remember. The asset registry is not built yet at this
+ * point, so the folder is read directly. Undefined entries are skipped; the
+ * same path is not read twice.
+ */
+ private async firstReadableScene(
+ candidates: Array<string | undefined>,
+ ): Promise<{ rel: string; text: string } | null> {
+ const tried = new Set<string>();
+ const dir = this.state?.layout.scenes;
+ let inFolder: string[] = [];
+ if (dir) {
+ try {
+ inFolder = (await window.estella.fs.readDir(dir))
+ .filter((e) => !e.isDir && e.name.endsWith('.esscene'))
+ .map((e) => `${dir}/${e.name}`);
+ } catch {
+ // No scenes folder is a legitimate shape; the candidates still apply.
+ }
+ }
+ for (const rel of [...candidates, ...inFolder]) {
+ if (!rel || tried.has(rel)) continue;
+ tried.add(rel);
+ try {
+ const text = await window.estella.fs.read(rel);
+ if (rel !== candidates[0] && candidates[0]) {
+ console.warn(`[project] "${candidates[0]}" is missing — opened "${rel}" instead.`);
+ }
+ return { rel, text };
+ } catch {
+ // Not there (or unreadable): try the next candidate.
+ }
+ }
+ return null;
+ }
+
/** Load the project's last-opened scene (or `<scenes>/main.esscene`) into the world. */
async loadCurrentScene(): Promise<void> {
const st = this.state;
@@ -468,9 +508,24 @@ class ProjectStoreImpl {
// Project-level render config (WYSIWYG in the edit viewport). Applied here —
// the one path that runs both on project open and once the engine is ready.
Renderer.setYSortLayers(this.ySortMask());
- const rel =
- st.workspace.lastOpenedScene ?? st.defaultScene ?? `${st.layout.scenes}/main.esscene`;
- const text = await window.estella.fs.read(rel);
+ const found = await this.firstReadableScene([
+ st.workspace.lastOpenedScene,
+ st.defaultScene,
+ `${st.layout.scenes}/main.esscene`,
+ ]);
+ // A project whose remembered scene is gone still opens. It was fatal: the
+ // read threw, the open failed, and the editor stayed on the launcher behind
+ // a toast — so deleting a scene file outside the editor bricked the project
+ // until someone knew to hand-edit .esengine/workspace.json.
+ if (!found) {
+ console.warn(
+ '[project] no scene could be loaded — the remembered scene is missing and ' +
+ 'no fallback exists. The project is open with an empty world; open a scene ' +
+ 'from the Content Browser.',
+ );
+ return;
+ }
+ const { rel, text } = found;
const raw = JSON.parse(text) as SceneData;
const retired = stripRetiredComponents(raw);
if (retired.length > 0) {