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
fix(editor): entering play says whether the realm came up
yhhae2cf737371c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 theeditor imports on its own to read a project's component schemas. The 3D starter shippeddiff --git a/desktop/electron/surfaceDriver.ts b/desktop/electron/surfaceDriver.tsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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 prefixdiff --git a/desktop/scripts/editor-checks/soak.mjs b/desktop/scripts/editor-checks/soak.mjsindex 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.texturesdiff --git a/desktop/scripts/editor-checks/starter-3d.mjs b/desktop/scripts/editor-checks/starter-3d.mjsindex 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.mjsindex 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.tsxindex 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