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): entering play says whether the realm came up

yhhae2cf737371c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1fed27202..36164862c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -270,6 +270,24 @@ published separately; it ships inside the editor.
### Fixed
+- **Entering play answers whether the realm came up.** `set_play` resolves both when the
+ realm settles and when it gives up waiting for it, and the two answers were the same
+ object — so a caller told nothing went on to probe a realm that was not there and waited
+ out its OWN timeout instead. What CI then reported was `timeout tools/call play_probe`:
+ a boot that never happened, named as whichever call drew the short straw. The door says
+ which of the two it is now, and the driver every editor check goes through asks before
+ it probes, so a realm that never came up fails by name.
+
+ Four checks had each grown a poll of their own against exactly this, with a different
+ bound each; they share the driver's now. `starter-3d`, the one that had none, was the
+ one that lost the run. It also settles the character in FRAMES rather than in seconds
+ of wall-clock — the realm's loop is throttled while the editor window is unfocused, so
+ what a sleep buys is a fact about the machine.
+
+ Evals into the play realm wait out a load in progress the way evals into the editor
+ window already did. It is one helper now rather than a guard on one door and none on
+ the door beside it.
+
- **The 3D starter is a complete project again.** A manifest that names no `scripts`
entry gets the defaults, and one of those is `src/components.ts` — the module the
editor imports on its own to read a project's component schemas. The 3D starter shipped
diff --git a/desktop/electron/surfaceDriver.ts b/desktop/electron/surfaceDriver.ts
index deec71eb0..89138895e 100644
--- a/desktop/electron/surfaceDriver.ts
+++ b/desktop/electron/surfaceDriver.ts
@@ -16,7 +16,7 @@
* 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';
+import type { BrowserWindow, WebFrameMain } from 'electron';
import { scriptDiagnostics, lookupScriptSymbol, searchScriptSymbols, isScriptPath } from './scriptService';
import { searchInRoot, writeInRoot } from './projectFs';
@@ -253,11 +253,27 @@ export function createSurfaceDriver(
if (!root) throw new Error('no project open');
return root;
};
+ /**
+ * Wait out a load in progress — a call can arrive before the renderer booted.
+ *
+ * Polled, never event-awaited: isLoading() covers SUBFRAMES (the play realm is
+ * an iframe) where did-finish-load fires for the main frame alone, so awaiting
+ * the event parks forever. Bounded: executeJavaScript's own error beats silence.
+ */
+ const settleLoad = async (win: BrowserWindow): Promise<void> => {
+ for (let waited = 0; win.webContents.isLoading() && waited < 10_000; waited += 50) {
+ await new Promise((r) => setTimeout(r, 50));
+ }
+ };
+
/** The play realm's frame. It is an estella:// OOPIF, so a main-process eval
* is the only thing that reaches it; `frame` picks one in a multiplayer
- * preview (0 = the host). */
- const playFrame = (input: Record<string, unknown>) => {
- const frames = requireWin().webContents.mainFrame.frames.filter((f) => f.url.startsWith('estella://'));
+ * preview (0 = the host). Awaited: a realm still loading is one the frame list
+ * already carries and no eval into it would return from. */
+ const playFrame = async (input: Record<string, unknown>): Promise<WebFrameMain> => {
+ const win = requireWin();
+ await settleLoad(win);
+ const frames = win.webContents.mainFrame.frames.filter((f) => f.url.startsWith('estella://'));
const at = Number(input.frame ?? 0);
const frame = frames[at];
if (!frame) {
@@ -266,19 +282,13 @@ export function createSurfaceDriver(
return frame;
};
+ /** Run code in the play realm, once the realm is a thing that can run it. */
+ const playExec = async (input: Record<string, unknown>, code: string): Promise<unknown> =>
+ unwrap(await (await playFrame(input)).executeJavaScript(code));
+
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.
- // Polled, never event-awaited: isLoading() covers SUBFRAMES (the play realm
- // prewarms in an iframe seconds after a project opens), but did-finish-load
- // fires only for the main frame — a call that awaited the event during a
- // subframe load parked forever, timing out whichever automation call drew
- // the short straw. Bounded: a page that never settles still gets the call,
- // and executeJavaScript's own error is a better answer than silence.
- for (let waited = 0; win.webContents.isLoading() && waited < 10_000; waited += 50) {
- await new Promise((r) => setTimeout(r, 50));
- }
+ await settleLoad(win);
return unwrap(await win.webContents.executeJavaScript(carryError(code), true));
};
@@ -305,11 +315,8 @@ export function createSurfaceDriver(
}
return cropToGame(image, rect).toPNG().toString('base64');
}
- case 'play_probe': {
- return unwrap(await playFrame(input).executeJavaScript(
- carryError(String(input.code ?? 'true'), PROBE_SCOPE),
- ));
- }
+ case 'play_probe':
+ return playExec(input, carryError(String(input.code ?? 'true'), PROBE_SCOPE));
// The NAMED reads. Same realm, but the expression is OURS — no arbitrary
// code, nothing to confirm. `kind` is a closed set, so a caller reaches
// only what the realm published.
@@ -319,15 +326,14 @@ export function createSurfaceDriver(
throw new Error(`no play query "${kind}" (it answers: ${[...PLAY_QUERIES].join(', ')})`);
}
const arg = JSON.stringify(input.arg ?? null);
- return unwrap(await playFrame(input).executeJavaScript(
- carryError(`window.__estellaPlay.${kind}(...(${arg} === null ? [] : [${arg}]))`, PROBE_SCOPE),
+ return playExec(input, carryError(
+ `window.__estellaPlay.${kind}(...(${arg} === null ? [] : [${arg}]))`, PROBE_SCOPE,
));
}
case 'play_input': {
// Same realm as play_probe, and like play_query the code is OURS — a
// caller cannot mistype the facade and get silence. Everything routes
// through `__estellaPlay.input`, the platform binding's own callbacks.
- const frame = playFrame(input);
const { kind } = input as { kind?: string };
const x = Number(input.x ?? 0), y = Number(input.y ?? 0);
const button = Number(input.button ?? 0);
@@ -355,9 +361,9 @@ export function createSurfaceDriver(
// Clicking a NAMED element answers with where it went, so it is not one
// of the fire-and-forget spellings above.
if (kind === 'ui') {
- return unwrap(await frame.executeJavaScript(carryError(
+ return playExec(input, carryError(
`window.__estellaPlay.clickUi(${JSON.stringify(String(input.target ?? ''))})`,
- )));
+ ));
}
if (!call) {
throw new Error(
@@ -365,7 +371,7 @@ export function createSurfaceDriver(
+ 'key_down, key_up, tap, gamepad, gamepad_release, ui',
);
}
- return unwrap(await frame.executeJavaScript(carryError(
+ return playExec(input, carryError(
`(async () => { const p = window.__estellaPlay; if (!p || !p.input) `
+ `throw new Error('this play realm publishes no input door — it predates play_input'); `
+ `const i = p.input; const f = (n) => (p.step ? p.step(n) : undefined); await f(1); `
@@ -373,7 +379,7 @@ export function createSurfaceDriver(
// realm older than the one that started answering, keep 'ok'.
+ `const r = await (async () => { ${call} })(); `
+ `return r === undefined ? 'ok' : r; })()`,
- )));
+ ));
}
// — What the TypeScript compiler knows. Main-process because the language
// service lives here (scriptService.ts), reading the project off disk. —
diff --git a/desktop/scripts/editor-checks/physics3d-debug-draw.mjs b/desktop/scripts/editor-checks/physics3d-debug-draw.mjs
index 96962bbba..377bcca85 100644
--- a/desktop/scripts/editor-checks/physics3d-debug-draw.mjs
+++ b/desktop/scripts/editor-checks/physics3d-debug-draw.mjs
@@ -84,14 +84,7 @@ export async function run(ed) {
const check = checker();
await ed.open(root, 'assets/scenes/main.esscene');
- await ed.call('set_play', { state: 'playing' }, 120000);
-
- let ready = false;
- for (let i = 0; i < 40 && !ready; i++) {
- ready = (await ed.json('get_play_state', {}))?.ready === true;
- if (!ready) await ed.sleep(500);
- }
- if (!check(ready, 'the play realm never reported ready')) return check.failures;
+ await ed.play();
await ed.call('play_probe', { code: 'await step(3); return true;' }, 60000);
await ed.sleep(600);
diff --git a/desktop/scripts/editor-checks/physics3d-joint.mjs b/desktop/scripts/editor-checks/physics3d-joint.mjs
index 716579cae..e6c9a3aba 100644
--- a/desktop/scripts/editor-checks/physics3d-joint.mjs
+++ b/desktop/scripts/editor-checks/physics3d-joint.mjs
@@ -60,14 +60,7 @@ export async function run(ed) {
const check = checker();
await ed.open(root, 'assets/scenes/main.esscene');
- await ed.call('set_play', { state: 'playing' }, 120000);
-
- let ready = false;
- for (let i = 0; i < 40 && !ready; i++) {
- ready = (await ed.json('get_play_state', {}))?.ready === true;
- if (!ready) await ed.sleep(500);
- }
- if (!check(ready, 'the play realm never reported ready')) return check.failures;
+ await ed.play();
const bob = async () => (await ed.json('play_probe', {
code: 'const e = find("HingeJoint3D")[0];'
diff --git a/desktop/scripts/editor-checks/physics3d-play.mjs b/desktop/scripts/editor-checks/physics3d-play.mjs
index 0ed1926c8..802bc950a 100644
--- a/desktop/scripts/editor-checks/physics3d-play.mjs
+++ b/desktop/scripts/editor-checks/physics3d-play.mjs
@@ -52,14 +52,7 @@ export async function run(ed) {
const check = checker();
await ed.open(root, 'assets/scenes/main.esscene');
- await ed.call('set_play', { state: 'playing' }, 120000);
-
- let ready = false;
- for (let i = 0; i < 40 && !ready; i++) {
- ready = (await ed.json('get_play_state', {}))?.ready === true;
- if (!ready) await ed.sleep(500);
- }
- if (!check(ready, 'the play realm never reported ready')) return check.failures;
+ await ed.play();
const hero = async () => (await ed.json('play_probe', {
code: 'const c = find("CharacterController3D")[0];'
diff --git a/desktop/scripts/editor-checks/play-stepping.mjs b/desktop/scripts/editor-checks/play-stepping.mjs
index 3bdd83c8d..65ee96047 100644
--- a/desktop/scripts/editor-checks/play-stepping.mjs
+++ b/desktop/scripts/editor-checks/play-stepping.mjs
@@ -35,15 +35,8 @@ export async function run(ed) {
const check = checker();
await ed.open(root, 'assets/scenes/main.esscene');
- await ed.call('set_play', { state: 'playing' }, 120000);
-
// Ready before stepping: a realm still booting has no app to advance.
- let ready = false;
- for (let i = 0; i < 40 && !ready; i++) {
- ready = (await ed.json('get_play_state', {}))?.ready === true;
- if (!ready) await ed.sleep(500);
- }
- if (!check(ready, 'the play realm never reported ready')) return check.failures;
+ await ed.play();
const clock = async () => (await ed.json('play_probe', {
code: 'return resource("Time")', // bare, no window.__estellaPlay prefix
diff --git a/desktop/scripts/editor-checks/soak.mjs b/desktop/scripts/editor-checks/soak.mjs
index 59e2df5c0..d51150109 100644
--- a/desktop/scripts/editor-checks/soak.mjs
+++ b/desktop/scripts/editor-checks/soak.mjs
@@ -59,22 +59,16 @@ export async function run(ed) {
const samples = [];
for (let cycle = 0; cycle < CYCLES; cycle++) {
- await ed.call('set_play', { state: 'playing' }, 120000);
- let ready = false;
- for (let i = 0; i < 40 && !ready; i++) {
- ready = (await ed.json('get_play_state', {}))?.ready === true;
- if (!ready) await ed.sleep(250);
+ // Which cycle it was is the whole point here — a realm that comes up nine
+ // times and not the tenth is the leak this check exists to catch.
+ try {
+ await ed.play();
+ await ed.call('step', { frames: 10, dt: 1 / 60 }, 60000);
+ await ed.play('stopped');
+ } catch (err) {
+ check(false, `cycle ${cycle}: ${err.message}`);
+ return check.failures;
}
- if (!check(ready, `cycle ${cycle}: the play realm never reported ready`)) return check.failures;
- await ed.call('step', { frames: 10, dt: 1 / 60 }, 60000);
-
- await ed.call('set_play', { state: 'stopped' }, 120000);
- let stopped = false;
- for (let i = 0; i < 40 && !stopped; i++) {
- stopped = (await ed.json('get_play_state', {}))?.playing === false;
- if (!stopped) await ed.sleep(250);
- }
- if (!check(stopped, `cycle ${cycle}: play never stopped`)) return check.failures;
// A rescan every cycle: the path that releases a GL texture before uploading
// its replacement. Whether it re-uploaded is not assumed — render.gl.textures
diff --git a/desktop/scripts/editor-checks/starter-3d.mjs b/desktop/scripts/editor-checks/starter-3d.mjs
index b94722dd3..876c84258 100644
--- a/desktop/scripts/editor-checks/starter-3d.mjs
+++ b/desktop/scripts/editor-checks/starter-3d.mjs
@@ -38,8 +38,11 @@ export async function run(ed) {
await ed.call('run_editor_command', { id: 'mode.scene' }, 30000);
await ed.sleep(800);
- await ed.call('set_play', { state: 'play' }, 180000);
- await ed.sleep(2500);
+ await ed.play('playing', 180000);
+ // Settled in FRAMES, not in wall-clock: the realm's loop is throttled while the
+ // editor window is unfocused, so what a sleep buys is a question about the
+ // machine rather than about the character.
+ await ed.call('step', { frames: 120, dt: 1 / 60 }, 60000);
const at = async () => ed.json('play_probe', { code: PROBE }, 60000);
const rest = await at();
@@ -90,6 +93,6 @@ export async function run(ed) {
`walking left the character at y = ${moved.p.y.toFixed(1)} rather than on the ground at ${stand}`,
);
- await ed.call('set_play', { state: 'stop' }, 60000);
+ await ed.play('stopped', 60000);
return check.failures;
}
diff --git a/desktop/scripts/lib/editorDriver.mjs b/desktop/scripts/lib/editorDriver.mjs
index 7b0d8932b..970773876 100644
--- a/desktop/scripts/lib/editorDriver.mjs
+++ b/desktop/scripts/lib/editorDriver.mjs
@@ -197,6 +197,27 @@ export async function withEditor(body, opts = {}) {
if (scene) await call('open_scene', { path: scene }, 120000);
await sleep(2000);
},
+ /**
+ * Enter (or leave) play and answer with the state the realm REACHED.
+ *
+ * `set_play` resolves when the realm settles AND when it gives up on it, and
+ * those read alike from outside: a check that takes the second for the first
+ * probes a realm that is not there. Here a realm that never came up fails by name.
+ */
+ play: async (state = 'playing', ms = 120000) => {
+ const up = (s) => (state === 'stopped' ? s?.playing === false : s?.ready === true);
+ const reached = await editor.json('set_play', { state }, ms);
+ let last = reached;
+ for (let i = 0; i < 40 && !up(last); i++) {
+ await sleep(500);
+ last = await editor.json('get_play_state', {});
+ }
+ if (!up(last)) {
+ throw new Error(`the play realm never reported ${state === 'stopped' ? 'stopped' : 'ready'}`
+ + ` — set_play answered ${JSON.stringify(reached)}`);
+ }
+ return last;
+ },
};
try {
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index b1b3ec965..741c00d42 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -307,28 +307,34 @@ function buildEditorAutomation(): unknown {
*/
setPlay: async (state: 'playing' | 'paused' | 'stopped') => {
const now = () => PlayRealm.getSnapshot();
- const settle = async (done: () => boolean) => {
+ // Says whether it GOT there, as `play` above does: told nothing, a caller
+ // probes a realm that is not there and waits out ITS timeout, which names
+ // whichever call drew the short straw rather than the boot that failed.
+ const settle = async (done: () => boolean): Promise<boolean> => {
const deadline = Date.now() + 60_000;
while (!done() && !now().error && Date.now() < deadline) {
await new Promise((r) => setTimeout(r, 100));
}
+ return done();
};
+ const answer = (ok: boolean, missed: string) =>
+ (ok ? now() : { ...now(), note: `the realm did not ${missed} within 60s` });
// Awaited like the other direction. Reading the state straight after the
// toggle answered `playing: true` to someone who had just asked for it to
// stop, which is a lie they then act on.
if (state === 'stopped') {
if (now().playing) useEditorStore.getState().togglePlay();
- await settle(() => !now().playing);
- return now();
+ return answer(await settle(() => !now().playing), 'stop');
}
+ let up = true;
if (!now().playing) {
useEditorStore.getState().togglePlay();
- await settle(() => now().playing && now().ready);
+ up = await settle(() => now().playing && now().ready);
}
// Paused LAST, so it applies to a realm that is up rather than to one
// still booting, which would come up running.
PlayRealm.setPaused(state === 'paused');
- return now();
+ return answer(up, 'come up');
},
/**
* How fast the running game's clock advances: 1 is normal, 0.25 quarter