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
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.mjsnew file mode 100644index 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.tsindex 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 thediff --git a/desktop/src/engine/PlayRealm.ts b/desktop/src/engine/PlayRealm.tsindex 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.tsindex 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.tsxindex 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.tsindex 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.mdindex e0f31d37b..c8d1919e5 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -524,6 +524,7 @@ setTargetFrameRate: (fps: number) => voidsideModules: SideModuleHost | nullspineInitPromise: Promise<unknown> | undefinedstepFrame: () => void+stepFrames: (frames?: number, dt?: number) => Promise<void>subsystems: SubsystemRegistrytick: (delta: number) => Promise<void>waitForPhysics: () => Promise<void>diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 6afa6184b..0ca8e559c 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -524,6 +524,7 @@ setTargetFrameRate: (fps: number) => voidsideModules: SideModuleHost | nullspineInitPromise: Promise<unknown> | undefinedstepFrame: () => void+stepFrames: (frames?: number, dt?: number) => Promise<void>subsystems: SubsystemRegistrytick: (delta: number) => Promise<void>waitForPhysics: () => Promise<void>diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 341533bae..dfed16f4e 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -519,6 +519,7 @@ setTargetFrameRate: (fps: number) => voidsideModules: SideModuleHost | nullspineInitPromise: Promise<unknown> | undefinedstepFrame: () => void+stepFrames: (frames?: number, dt?: number) => Promise<void>subsystems: SubsystemRegistrytick: (delta: number) => Promise<void>waitForPhysics: () => Promise<void>diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 0b0ee2335..8448145cc 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -519,6 +519,7 @@ setTargetFrameRate: (fps: number) => voidsideModules: SideModuleHost | nullspineInitPromise: Promise<unknown> | undefinedstepFrame: () => void+stepFrames: (frames?: number, dt?: number) => Promise<void>subsystems: SubsystemRegistrytick: (delta: number) => Promise<void>waitForPhysics: () => Promise<void>diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 2307efabc..f55ca6243 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -519,6 +519,7 @@ setTargetFrameRate: (fps: number) => voidsideModules: SideModuleHost | nullspineInitPromise: Promise<unknown> | undefinedstepFrame: () => void+stepFrames: (frames?: number, dt?: number) => Promise<void>subsystems: SubsystemRegistrytick: (delta: number) => Promise<void>waitForPhysics: () => Promise<void>diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 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.tsindex 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);+ });+});