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.

feat(play): step advances the game that is running, not the world that isn't

yhh0772bb56e9df
diff --git a/desktop/scripts/editor-checks/play-stepping.mjs b/desktop/scripts/editor-checks/play-stepping.mjs
new file mode 100644
index 000000000..c2f6da0ff
--- /dev/null
+++ b/desktop/scripts/editor-checks/play-stepping.mjs
@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file play-stepping — a driver can make the running game advance, and see it.
+ *
+ * The game runs in its own frame on the browser's rAF clock, which is throttled to
+ * roughly one frame a second whenever the editor window is not the focused one — and
+ * it never is, for anything driving the editor from outside. So a driver that pressed
+ * Play and then read the same component twice got the same answer twice, concluded the
+ * game was frozen, and went looking for a reason. `step` existed and advanced the EDIT
+ * World, which holds no gameplay: the verb was right and it went to the wrong world.
+ *
+ * What that cost is on the record. One dogfood run spent 75 of its 158 tool calls
+ * probing, found `app.runFrame_` by enumerating prototypes, drove the game through
+ * that private method, ran out of tool rounds, and delivered a Breakout that is GAME
+ * OVER within half a second — with every component reporting exactly the value it
+ * should have.
+ *
+ * So: press Play, step, and check the world moved by the amount asked for.
+ */
+import path from 'node:path';
+import { cp } from 'node:fs/promises';
+import { makeProject, checker, DESKTOP } from '../lib/editorDriver.mjs';
+
+const EXAMPLE = path.resolve(DESKTOP, '..', 'examples', 'sprite-rendering');
+
+export const name = 'play-stepping';
+export const describes = 'step advances the RUNNING game deterministically, and the probe can see it';
+
+export async function run(ed) {
+ // The example's own systems animate every frame, so "did time pass" is visible in
+ // the world rather than only on the clock.
+ const root = await makeProject({});
+ await cp(EXAMPLE, root, { recursive: true });
+ const check = checker();
+
+ await ed.open(root, 'assets/scenes/main.esscene');
+ await ed.call('toggle_play', {}, 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;
+
+ const clock = async () => (await ed.json('play_probe', {
+ code: 'return resource("Time")', // bare, no window.__estellaPlay prefix
+ }, 60000)) ?? {};
+
+ const before = await clock();
+ if (!check(typeof before.frameCount === 'number', `the probe scope has no bare resource(): ${JSON.stringify(before)}`)) {
+ return check.failures;
+ }
+
+ const stepped = await ed.json('step', { frames: 30, dt: 1 / 60 }, 60000);
+ check(stepped?.world === 'play', `step reported world=${JSON.stringify(stepped?.world)} — it stepped the wrong one`);
+
+ const after = await clock();
+ const advanced = (after.frameCount ?? 0) - (before.frameCount ?? 0);
+ // At least the 30 asked for: the throttled loop may also land a frame of its own,
+ // and pinning it EXACTLY would fail on a machine that happened to be focused.
+ check(advanced >= 30, `30 frames of step moved the clock by ${advanced}`);
+ check(
+ (after.elapsed ?? 0) - (before.elapsed ?? 0) >= 30 / 60 - 1e-6,
+ `elapsed moved by ${(after.elapsed ?? 0) - (before.elapsed ?? 0)}s, not the 0.5s asked for`,
+ );
+
+ // The other half of the loop: what a player would see.
+ const shot = await ed.screenshot('play-stepping');
+ check(shot.w > 0 && shot.h > 0, 'the window did not capture');
+
+ return check.failures;
+}
diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.ts
index 8009ec230..b1b61f844 100644
--- a/desktop/src/engine/EditorControlSurface.ts
+++ b/desktop/src/engine/EditorControlSurface.ts
@@ -279,6 +279,18 @@ export function coerceFieldValue(
}
}
+/**
+ * The running game, as much of it as {@link EditorControlSurfaceImpl.step} needs.
+ *
+ * An interface rather than an import: the play realm is an editor-only thing (an
+ * OOPIF and a postMessage channel), and this surface is also the headless host's.
+ * The editor installs one; the headless host does not have one to install.
+ */
+export interface LiveGamePort {
+ running(): boolean;
+ step(frames: number, dt: number): Promise<unknown>;
+}
+
/** The session parts the surface needs (the EditorSession satisfies this). */
export interface SurfaceSession {
model: SceneModelImpl;
@@ -335,13 +347,32 @@ export class EditorControlSurfaceImpl {
}
/**
- * Advance the engine by exactly `frames` fixed-delta ticks — no rAF, no
- * wall-clock — so a subsequent capture is reproducible. Use after loadScene /
- * setRunMode and before captureViewport. Drives the engine directly, so it
- * belongs to a host that does NOT run app.run()'s loop (the headless host).
+ * Advance whatever is RUNNING by exactly `frames` fixed-delta ticks — no rAF, no
+ * wall-clock — so what happens next is reproducible and what you capture is settled.
+ *
+ * "Whatever is running" is the point. There are two worlds here: the edit World this
+ * surface owns, and the play realm, which is where the project's game scripts
+ * actually live. A driver that pressed Play and then called this got the edit World —
+ * a world with no gameplay in it — so nothing moved, and the game (throttled to about
+ * a frame a second by an unfocused window) looked frozen. One dogfood run answered
+ * that by hunting down `app.runFrame_` and stepping the realm through a private
+ * method. The verb was right; it just went to the wrong world.
*/
- async step(frames = 1, dt = 1 / 60): Promise<void> {
+ async step(frames = 1, dt = 1 / 60): Promise<{ world: 'play' | 'edit'; frames: number; dt: number }> {
+ if (this.liveGame?.running()) {
+ await this.liveGame.step(frames, dt);
+ return { world: 'play', frames, dt };
+ }
for (let i = 0; i < frames; i++) await EngineHost.tick(dt);
+ return { world: 'edit', frames, dt };
+ }
+
+ /** The running game, when the host has one. Installed by the editor; the headless
+ * host leaves it null and {@link step} keeps driving the edit World. */
+ private liveGame: LiveGamePort | null = null;
+
+ setLiveGame(port: LiveGamePort | null): void {
+ this.liveGame = port;
}
/** Project render config: bitmask of layers (0..31) that y-sort within the
diff --git a/desktop/src/engine/PlayRealm.ts b/desktop/src/engine/PlayRealm.ts
index edd428bf0..47476f02f 100644
--- a/desktop/src/engine/PlayRealm.ts
+++ b/desktop/src/engine/PlayRealm.ts
@@ -24,7 +24,7 @@ import { t } from '@/i18n';
import { playProtocolMismatch } from './playProtocol';
import { bootProfiler } from './bootProfiler';
import { projectReplacing } from '@/project/projectReplacing';
-import type { PlayOutbound, PlayInbound, PlayPayload, PlaySnapshot, PlayStatsReply } from './playProtocol';
+import type { PlayOutbound, PlayInbound, PlayPayload, PlaySnapshot, PlayStatsReply, PlayStepReply } from './playProtocol';
export type { PlayPayload, PlaySnapshot } from './playProtocol';
@@ -316,6 +316,26 @@ export class PlayRealmInstance {
});
}
+ /**
+ * Advance the RUNNING game by `frames` frames of `dt` seconds, deterministically.
+ * Null if no realm is running.
+ *
+ * The realm's own loop is wall-clock and browser-scheduled: with the editor window
+ * unfocused — which it is, for anything driving the editor from outside — it is
+ * throttled to roughly a frame a second, so "wait and look again" shows a game that
+ * never moves. This is the door that makes the next N frames happen on purpose.
+ * Generous timeout: 600 frames of gameplay is real work, not a query.
+ */
+ step(frames = 1, dt = 1 / 60): Promise<PlayStepReply | null> {
+ if (!this.iframe?.contentWindow || !this.store.getState().ready) return Promise.resolve(null);
+ const reqId = ++this.reqSeq;
+ return new Promise((resolve) => {
+ this.pending.set(reqId, (data) => resolve((data as PlayStepReply) ?? null));
+ this.post({ type: 'estella:play:query', kind: 'step', reqId, frames, dt });
+ setTimeout(() => { if (this.pending.delete(reqId)) resolve(null); }, 30000);
+ });
+ }
+
/** The running game's frame telemetry (phases/systems/counters) for the editor
* profiler's engine segment while playing. Null if not ready. */
stats(): Promise<PlayStatsReply | null> {
diff --git a/desktop/src/engine/playProtocol.ts b/desktop/src/engine/playProtocol.ts
index e2fd4d5a4..9bfd1e1f0 100644
--- a/desktop/src/engine/playProtocol.ts
+++ b/desktop/src/engine/playProtocol.ts
@@ -103,7 +103,16 @@ export interface PlaySnapshot {
selected: SceneData['entities'][number] | null;
}
-export type PlayQueryKind = 'snapshot' | 'subsystems' | 'stats';
+export type PlayQueryKind = 'snapshot' | 'subsystems' | 'stats' | 'step';
+
+/** What `query { kind: 'step' }` answers with: the clock AFTER the advance, so a
+ * caller can tell frames that ran from a request that reached no app. */
+export interface PlayStepReply {
+ frames: number;
+ dt: number;
+ frameCount: number;
+ elapsed: number;
+}
/** The running game's frame telemetry — reply payload of `query { kind: 'stats' }`.
* Feeds the editor profiler's engine segment while playing (PerfMonitor). */
@@ -133,7 +142,12 @@ export type PlayOutbound =
| { type: 'estella:play:setPaused'; paused: boolean }
| { type: 'estella:play:reload' }
// `withTree: false` = detail-only snapshot (skip the O(entities) tree walk).
- | { type: 'estella:play:query'; kind: PlayQueryKind; reqId: number; selectedId?: number | null; withTree?: boolean }
+ | {
+ type: 'estella:play:query'; kind: PlayQueryKind; reqId: number;
+ selectedId?: number | null; withTree?: boolean;
+ // `step` only: how far to advance, and with what fixed delta.
+ frames?: number; dt?: number;
+ }
| { type: 'estella:play:setField'; entityId: number; comp: string; key: string; value: unknown };
/** realm → editor. Discriminated by `type`. */
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index 660b094da..e2b08ef4e 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -90,6 +90,13 @@ applySettings();
initFsWatch();
initBackgroundThrottle();
+// Teach the control surface about the play realm, so `step` advances the game when
+// one is running instead of the edit World, which holds no gameplay. The surface is
+// shared with the headless host, which has no realm — hence a port, installed here.
+EditorControlSurface.setLiveGame({
+ running: () => PlayRealm.getSnapshot().playing,
+ step: (frames, dt) => PlayRealm.step(frames, dt),
+});
// Load the open project's editor plugins (and unload them when it closes).
initPlugins();
@@ -230,7 +237,21 @@ function buildEditorAutomation(): unknown {
* got back was `"GomokuState" has no field "currentPlayer" (fields: )`: an
* empty field list, phrased as if the field name were wrong. */
refreshSchemas: () => ProjectStore.refreshUserSchemas(),
- play: () => useEditorStore.getState().togglePlay(),
+ /** Enter/leave Play. Answers with the realm state rather than "ok": a caller that
+ * just started a game needs to know it is a REALM now — an unfocused editor
+ * window throttles it to about a frame a second, so nothing observed by waiting
+ * is worth anything, and `step` is what advances it. */
+ play: () => {
+ useEditorStore.getState().togglePlay();
+ const state = PlayRealm.getSnapshot();
+ return state.playing
+ ? {
+ ...state,
+ note: 'the game runs in its own frame, throttled while the editor window is not focused — '
+ + 'use step to advance it deterministically, screenshot to see it, and play_input to drive it',
+ }
+ : state;
+ },
playState: () => PlayRealm.getSnapshot(),
/** Player count for the next Play (1 = single, 2-4 = listen server + clients). */
setPlayPlayers: (n: number) => useEditorStore.getState().setPlayPlayers(n),
diff --git a/desktop/src/playHost.ts b/desktop/src/playHost.ts
index 6f4075968..b17fd9c68 100644
--- a/desktop/src/playHost.ts
+++ b/desktop/src/playHost.ts
@@ -317,6 +317,49 @@ async function buildAppAndRun(msg: InitMessage): Promise<void> {
}
return { total: out.length, entities: out };
},
+ /**
+ * ONE entity's component data, honestly — null when it does not have it.
+ *
+ * `getComponent(name)` then `world.tryGet(entity, def)` is the two-step every
+ * probe was opening with, re-typed each time; a Breakout dogfood spent
+ * seventy-five probes and most of them carried that preamble. It is the same
+ * pair of calls, named once.
+ */
+ get: (entity: number, name: string) => {
+ const def = getComponent(name);
+ if (!def) return { error: `no component named "${name}" is registered in this realm` };
+ return app!.world.tryGet(entity as never, def) ?? null;
+ },
+ /**
+ * Write fields of one entity's component — for SETTING UP the situation you want
+ * to observe (put the ball above the paddle, then step).
+ *
+ * Through `insert`, because the object `get` hands back is a COPY for several
+ * component kinds: assigning to it changes what you are holding and nothing else,
+ * which is a probe that reports success and moves nothing.
+ */
+ set: (entity: number, name: string, patch: Record<string, unknown>) => {
+ const def = getComponent(name);
+ if (!def) return { error: `no component named "${name}" is registered in this realm` };
+ const current = app!.world.tryGet(entity as never, def);
+ if (current === null || current === undefined) {
+ return { error: `entity ${entity} has no ${name}` };
+ }
+ app!.world.insert(entity as never, def, { ...(current as object), ...patch } as never);
+ return app!.world.tryGet(entity as never, def) ?? null;
+ },
+ /**
+ * Advance the game exactly `frames` frames of `dt` seconds and answer with the
+ * clock afterwards — the loop is wall-clock and the editor window is usually not
+ * the focused one, which throttles it to about a frame a second. Two probes taken
+ * a second apart therefore read identical, and a game that is running fine looks
+ * frozen.
+ */
+ step: async (frames = 1, dt = 1 / 60) => {
+ await app!.stepFrames(Math.max(1, Math.min(600, Math.floor(frames))), dt);
+ const time = app!.getResourceByName('Time') as { frameCount?: number; elapsed?: number } | undefined;
+ return { frames, dt, frameCount: time?.frameCount ?? 0, elapsed: time?.elapsed ?? 0 };
+ },
/** What `find` can be asked about: the component names this realm knows. */
componentNames: () => app!.world.getAllEntities()
.flatMap((e) => app!.world.getComponentTypes(e as never))
@@ -664,6 +707,25 @@ window.addEventListener('message', (e: MessageEvent) => {
} else if (data.kind === 'subsystems') {
// The running game's module health (for the editor's Modules indicator).
post({ type: 'estella:play:reply', reqId: data.reqId, data: app ? app.subsystems.getStatuses() : [] });
+ } else if (data.kind === 'step') {
+ // Deterministic advance — see __estellaPlay.step. The reply carries the clock
+ // so a caller can tell the frames actually ran from a request that no-oped.
+ const { reqId } = data;
+ void (async () => {
+ if (!app) {
+ post({ type: 'estella:play:reply', reqId, data: null });
+ return;
+ }
+ const frames = Math.max(1, Math.min(600, Math.floor(data.frames ?? 1)));
+ const dt = data.dt ?? 1 / 60;
+ await app.stepFrames(frames, dt);
+ const time = app.getResourceByName('Time') as { frameCount?: number; elapsed?: number } | undefined;
+ post({
+ type: 'estella:play:reply',
+ reqId,
+ data: { frames, dt, frameCount: time?.frameCount ?? 0, elapsed: time?.elapsed ?? 0 },
+ });
+ })();
}
break;
case 'estella:play:setField':
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index e0f31d37b..c8d1919e5 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -524,6 +524,7 @@ setTargetFrameRate: (fps: number) => void
sideModules: SideModuleHost | null
spineInitPromise: Promise<unknown> | undefined
stepFrame: () => void
+stepFrames: (frames?: number, dt?: number) => Promise<void>
subsystems: SubsystemRegistry
tick: (delta: number) => Promise<void>
waitForPhysics: () => Promise<void>
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 6afa6184b..0ca8e559c 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -524,6 +524,7 @@ setTargetFrameRate: (fps: number) => void
sideModules: SideModuleHost | null
spineInitPromise: Promise<unknown> | undefined
stepFrame: () => void
+stepFrames: (frames?: number, dt?: number) => Promise<void>
subsystems: SubsystemRegistry
tick: (delta: number) => Promise<void>
waitForPhysics: () => Promise<void>
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 341533bae..dfed16f4e 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -519,6 +519,7 @@ setTargetFrameRate: (fps: number) => void
sideModules: SideModuleHost | null
spineInitPromise: Promise<unknown> | undefined
stepFrame: () => void
+stepFrames: (frames?: number, dt?: number) => Promise<void>
subsystems: SubsystemRegistry
tick: (delta: number) => Promise<void>
waitForPhysics: () => Promise<void>
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 0b0ee2335..8448145cc 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -519,6 +519,7 @@ setTargetFrameRate: (fps: number) => void
sideModules: SideModuleHost | null
spineInitPromise: Promise<unknown> | undefined
stepFrame: () => void
+stepFrames: (frames?: number, dt?: number) => Promise<void>
subsystems: SubsystemRegistry
tick: (delta: number) => Promise<void>
waitForPhysics: () => Promise<void>
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 2307efabc..f55ca6243 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -519,6 +519,7 @@ setTargetFrameRate: (fps: number) => void
sideModules: SideModuleHost | null
spineInitPromise: Promise<unknown> | undefined
stepFrame: () => void
+stepFrames: (frames?: number, dt?: number) => Promise<void>
subsystems: SubsystemRegistry
tick: (delta: number) => Promise<void>
waitForPhysics: () => Promise<void>
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index 4f130b3e8..f84f99f97 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -728,6 +728,41 @@ export class App {
await this.runFrame_(delta);
}
+ /**
+ * Advance exactly `frames` frames of exactly `dt` seconds, with the rAF loop held
+ * off for the duration — "let the game run a bit", made reproducible.
+ *
+ * The loop it replaces is wall-clock and browser-scheduled: a backgrounded tab is
+ * throttled to about one frame a second, so an observer that steps by waiting sees
+ * a frozen game and concludes the game is broken. Worse, there was no other door —
+ * a driver that needed the next 30 frames of simulation had to reach for
+ * `runFrame_`, and reaching for a private method is a thing that keeps working
+ * until the day it doesn't.
+ *
+ * A PAUSED app still steps here: advancing frame by frame is exactly what stepping
+ * a paused game means. The pause (and the loop) are restored afterwards, with the
+ * clock re-based so the first resumed frame is not handed the whole excursion as
+ * its delta.
+ */
+ async stepFrames(frames = 1, dt = 1 / 60): Promise<void> {
+ const wasRunning = this.running_;
+ const wasPaused = this.user_paused_;
+ // The in-flight rAF callback returns without rescheduling, so nothing else
+ // ticks the world while this runs.
+ this.running_ = false;
+ this.user_paused_ = false;
+ try {
+ for (let i = 0; i < frames; i++) await this.tick(dt);
+ } finally {
+ this.user_paused_ = wasPaused;
+ if (wasRunning) {
+ this.lastTime_ = platformNow();
+ this.running_ = true;
+ void this.mainLoop();
+ }
+ }
+ }
+
async run(): Promise<void> {
if (this.running_) {
return;
diff --git a/sdk/tests/app-tick.test.ts b/sdk/tests/app-tick.test.ts
index 471023b10..45b0eeaad 100644
--- a/sdk/tests/app-tick.test.ts
+++ b/sdk/tests/app-tick.test.ts
@@ -103,3 +103,45 @@ describe('App.tick()', () => {
expect(capturedValue).toBe(42);
});
});
+
+describe('App.stepFrames()', () => {
+ // The rAF loop is wall-clock and the browser throttles it in a background tab
+ // to about a frame a second, so "wait and look again" cannot observe a game.
+ // This is the door that advances one on purpose; before it existed the only
+ // way through was App's private runFrame_, which a dogfood run duly found.
+ it('runs exactly the frames asked for, at exactly the delta asked for', async () => {
+ const app = App.new();
+ let frames = 0;
+ app.addSystemToSchedule(Schedule.Update, defineSystem(
+ [], () => { frames++; }, { name: 'Count' },
+ ));
+
+ await app.stepFrames(30, 1 / 60);
+
+ expect(frames).toBe(30);
+ const time = app.getResource(Time);
+ expect(time.frameCount).toBe(30);
+ expect(time.delta).toBeCloseTo(1 / 60);
+ expect(time.elapsed).toBeCloseTo(0.5);
+ });
+
+ it('steps a PAUSED app — that is what stepping a paused game means — and leaves it paused', async () => {
+ const app = App.new();
+ let frames = 0;
+ app.addSystemToSchedule(Schedule.Update, defineSystem(
+ [], () => { frames++; }, { name: 'Count' },
+ ));
+ app.setPaused(true);
+
+ await app.stepFrames(3);
+
+ expect(frames).toBe(3);
+ expect(app.isPaused()).toBe(true);
+ });
+
+ it('defaults to one frame', async () => {
+ const app = App.new();
+ await app.stepFrames();
+ expect(app.getResource(Time).frameCount).toBe(1);
+ });
+});