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(editor): profile the Play path (click → first frame)

yhh21992706c791
diff --git a/desktop/src/engine/PlayRealm.ts b/desktop/src/engine/PlayRealm.ts
index a53323d32..acb28a31b 100644
--- a/desktop/src/engine/PlayRealm.ts
+++ b/desktop/src/engine/PlayRealm.ts
@@ -22,6 +22,7 @@ import type { SubsystemStatus } from 'esengine';
import { LogStore } from '@/store/LogStore';
import { t } from '@/i18n';
import { playProtocolMismatch } from './playProtocol';
+import { bootProfiler } from './bootProfiler';
import type { PlayOutbound, PlayInbound, PlayPayload, PlaySnapshot, PlayStatsReply } from './playProtocol';
export type { PlayPayload, PlaySnapshot } from './playProtocol';
@@ -90,10 +91,14 @@ export class PlayRealmInstance {
this.payload = payload;
this.netPorts = netPorts ?? null;
this.set({ playing: true, ready: false, error: null });
+ // Time Play-click → first frame. Only the primary realm profiles (a
+ // multiplayer session's client realms would clobber the shared singleton).
+ if (this.id === 0) bootProfiler.begin('play (click → first frame)');
const frame = this.ensureIframe();
frame.style.visibility = 'hidden';
try {
const realm = await window.estella.project.preparePlayRealm();
+ if (this.id === 0) bootProfiler.mark('preparePlayRealm (stage + esbuild)');
if (!realm.ok) {
this.set({ error: realm.errors[0] ?? t('proj.playPrepareFailed') });
return;
@@ -205,6 +210,7 @@ export class PlayRealmInstance {
this.set({ error: mismatch });
break;
}
+ if (this.id === 0) bootProfiler.mark('iframe + host bundle load (→hello)');
if (this.payload) {
const ports = this.netPorts ?? undefined;
this.post({ type: 'estella:play:init', ...this.payload, netPorts: ports }, ports);
@@ -218,6 +224,13 @@ export class PlayRealmInstance {
LogStore.push(data.level ?? 'info', this.id === 0 ? 'Play' : `Play P${this.id + 1}`, data.line ?? '');
break;
case 'estella:play:ready':
+ if (this.id === 0) {
+ // Fold the realm's own boot sub-timing (bundle/wasm/scene) into the
+ // 'realm boot' phase, then close the Play profile.
+ if (data.phases) bootProfiler.detail('realm boot: wasm + scene (→ready)', data.phases);
+ bootProfiler.mark('realm boot: wasm + scene (→ready)');
+ bootProfiler.report();
+ }
this.set({ ready: true });
if (this.iframe) this.iframe.style.visibility = 'visible';
// Hand the running game keyboard focus so it's playable immediately — the
diff --git a/desktop/src/engine/bootProfiler.ts b/desktop/src/engine/bootProfiler.ts
index 2583f7983..051f8543b 100644
--- a/desktop/src/engine/bootProfiler.ts
+++ b/desktop/src/engine/bootProfiler.ts
@@ -38,15 +38,33 @@ class BootProfiler {
// the phase — so buffer it by name and attach when the phase lands.
private pendingDetails = new Map<string, Record<string, number>>();
+ private lastMarkAt = 0;
+
/** Open a fresh profile. A second begin() before report() discards the first. */
begin(label: string): void {
this.active = true;
this.label = label;
this.t0 = now();
+ this.lastMarkAt = 0;
this.phases = [];
this.pendingDetails.clear();
}
+ /**
+ * Record an event boundary — the phase is the gap since the previous mark (or
+ * begin). For event-driven sequences (e.g. Play: prepare → iframe hello →
+ * ready) where phase() can't wrap a single awaited call.
+ */
+ mark(name: string): void {
+ if (!this.active) return;
+ const at = now() - this.t0;
+ const phase: BootPhase = { name, ms: round1(at - this.lastMarkAt) };
+ const pending = this.pendingDetails.get(name);
+ if (pending) { phase.detail = pending; this.pendingDetails.delete(name); }
+ this.phases.push(phase);
+ this.lastMarkAt = at;
+ }
+
get isActive(): boolean {
return this.active;
}
diff --git a/desktop/src/engine/playProtocol.ts b/desktop/src/engine/playProtocol.ts
index 070077723..e83d9e564 100644
--- a/desktop/src/engine/playProtocol.ts
+++ b/desktop/src/engine/playProtocol.ts
@@ -105,7 +105,10 @@ export type PlayOutbound =
/** realm → editor. Discriminated by `type`. */
export type PlayInbound =
| { type: 'estella:play:hello'; protocolVersion: number }
- | { type: 'estella:play:ready' }
+ // `phases` (optional) carries the realm's own boot sub-timing (bundle import,
+ // wasm instantiate, scene+asset load) so the editor can fold it into the Play
+ // profile — the realm runs in a separate JS realm and can't share the profiler.
+ | { type: 'estella:play:ready'; phases?: Record<string, number> }
| { type: 'estella:play:error'; message: string }
| { type: 'estella:play:log'; level: PlayLogLevel; line: string }
| { type: 'estella:play:reply'; reqId: number; data: unknown };
diff --git a/desktop/src/playHost.ts b/desktop/src/playHost.ts
index 2d9d59d63..fdb49ba21 100644
--- a/desktop/src/playHost.ts
+++ b/desktop/src/playHost.ts
@@ -256,6 +256,10 @@ async function boot(msg: InitMessage): Promise<void> {
booted = true;
lastInit = msg;
try {
+ // Sub-phase timing reported back to the editor on `ready` — the realm runs in
+ // its own JS realm, so it can't write the editor's boot profiler directly.
+ const r1 = (n: number): number => Math.round(n * 10) / 10;
+ const tBundle = performance.now();
// Register the project's own components/systems FIRST (side-effect import; its
// `import 'esengine'` resolves through the import map to the shared instance).
// Absent (a project with no scripts) → builtin-only, which is fine.
@@ -264,9 +268,19 @@ async function boot(msg: InitMessage): Promise<void> {
} catch {
/* no project bundle — builtin components/systems only */
}
+ const tEngine = performance.now();
await ensureEngine();
+ const tRuntime = performance.now();
await buildAppAndRun(msg);
- post({ type: 'estella:play:ready' });
+ const tEnd = performance.now();
+ post({
+ type: 'estella:play:ready',
+ phases: {
+ bundleImport: r1(tEngine - tBundle),
+ engineInstantiate: r1(tRuntime - tEngine),
+ sceneAndAssets: r1(tEnd - tRuntime),
+ },
+ });
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
if (err === 'unwind' || message.includes('unwind')) {