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(profiler): an agent reads a capture off disk, and the holes in what one carries are closed
yhhed26cb49e283
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8a9877cd5..b99bea14a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -148,6 +148,26 @@ published separately; it ships inside the editor.observer fires after the frame, and is a broadcast rather than a slot, so agame's own budget alarm can watch beside the recorder instead of replacing it.+- **An agent can read a capture off disk, not just the running frame.**+ `profile_capture` reads a recorded `.esprof` and answers with exactly what+ `profile_frames` answers, so a capture from a device gets *analysed* rather+ than merely looked at — which is what a recorder is for. The projection behind+ both is one pure function over a summary, so the live realm and a file cannot+ describe the same frames differently.++- **The worst frame, broken down on its own.** A report was averages and a+ `worstFrameMs` with nothing behind it — but the averages describe the frames+ that were fine, and a stutter is one frame. `worstFrame` now carries that+ frame's own domains. On a synthetic capture the mean reads 0.04ms and the+ worst reads 0.58ms; only one of those numbers is the reason anybody is looking.++- **Memory was a field nothing filled.** `CapturedFrame.memory` shipped in the+ capture format, the editor's writer never set it and the recorder set a third+ of it, so the memory graph of an imported capture was empty and no reader+ could tell "not recorded" from "no memory used". Frame samples carry their own+ heaps now, the recorder records all three, and both the panel and the report+ say `—` / `-1` where a source recorded nothing rather than showing a zero.+- **One derivation, three readers.** `buildFrameProfile` is a pure function overplain per-frame data, so the live view, a pinned frame and a recorded sessioncannot each round their own way to a different answer. The editor's owndiff --git a/desktop/shared/toolCatalog.mjs b/desktop/shared/toolCatalog.mjsindex 07bd01e6e..fc2a00963 100644--- a/desktop/shared/toolCatalog.mjs+++ b/desktop/shared/toolCatalog.mjs@@ -225,6 +225,14 @@ export const TOOLS = [+ 'Works in both realms: it profiles the running game while playing, the editor scene otherwise (see `realm`).',schema: obj({ ms: { type: 'number' }, topSystems: { type: 'number' } }),method: 'profileFrames', args: (i) => [i.ms ?? 1000, i.topSystems ?? 12] },+ { name: 'profile_capture',+ description: 'Read a recorded `.esprof` capture by project-relative path and answer with the SAME breakdown profile_frames gives — '+ + 'this is how a capture recorded on a device gets analysed rather than merely looked at. A game records one with `ProfileRecorder` and drops the file in the project. '+ + '`origin` says which file and what it came from (device label, platform). `worstFrame` is the worst frame in the capture broken down on its own, which is what a '+ + 'stutter actually is — the averages describe the frames that were fine. Throws, naming the reason, when the file is not a capture (not JSON, no version, frames that '+ + 'are not frames, a version newer than this editor reads).',+ schema: obj({ path: { type: 'string' }, topSystems: { type: 'number' } }, ['path']),+ method: 'profileCaptureFile', args: (i) => [i.path, i.topSystems ?? 12] },{ name: 'get_subsystems',description: 'Lifecycle + liveness of every engine subsystem (physics, audio, …): phase and activity.',schema: obj({}), method: 'getSubsystems', args: () => [] },diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.tsindex 43dcd4cbe..8b75ac4be 100644--- a/desktop/src/engine/EditorControlSurface.ts+++ b/desktop/src/engine/EditorControlSurface.ts@@ -30,8 +30,9 @@ import { EngineHost } from './EngineHost';import { isRequiredEmpty, componentByName, userSchema, coerceEnumInput, componentAuthorability, inspectorFields, modelAddableComponentEntries } from './schema';import { ViewportController } from './ViewportController';import { PerfMonitor, type PerfSnapshot, type FrameSample } from './PerfMonitor';-import type { ProfileCapture } from 'esengine';-import type { ProfileReport } from './profileReport';+import { parseProfileCapture, summarizeCapture, frameProfileOf } from 'esengine';+import type { ProfileCapture, CapturedFrame } from 'esengine';+import { profileReportOf, type ProfileReport } from './profileReport';import type { SceneCommandsImpl, EditorTransaction } from './SceneCommands';import type { SceneQueryImpl, EntityInfo } from './SceneQuery';import type { SceneModelImpl } from './SceneModel';@@ -39,17 +40,24 @@ import type { EditorHistoryImpl, HistoryMark } from './EditorHistory';import type { ReconcilerImpl } from './Reconciler';import type { SelectionStore } from '@/store/selectionStore';-const r2 = (n: number): number => Math.round(n * 100) / 100;--const BREAK_PREFIX = 'batch.break.';+/** Averaged over the frames that recorded each heap — absent is not zero. */+function meanMemory(frames: readonly CapturedFrame[]): { wasmBytes?: number; jsHeapBytes?: number; vramBytes?: number } {+ const mean = (pick: (f: CapturedFrame) => number | undefined): number | undefined => {+ const seen = frames.map(pick).filter((v): v is number => typeof v === 'number' && v > 0);+ return seen.length ? seen.reduce((a, b) => a + b, 0) / seen.length : undefined;+ };+ return {+ wasmBytes: mean((f) => f.memory?.wasmBytes),+ jsHeapBytes: mean((f) => f.memory?.jsHeapBytes),+ vramBytes: mean((f) => f.memory?.vramBytes),+ };+}-/** The `batch.break.*` counters as reason → draws, by their bare reason name. */-function batchBreaks(counters: Record<string, number>): Record<string, number> {- const out: Record<string, number> = {};- for (const key in counters) {- if (key.startsWith(BREAK_PREFIX)) out[key.slice(BREAK_PREFIX.length)] = r2(counters[key]);- }- return out;+/** A project-relative text read, through the door the path sandbox guards. */+function readProjectText(path: string): Promise<string> {+ const fs = (window as unknown as { estella?: { fs?: { read?(p: string): Promise<string> } } }).estella?.fs;+ if (!fs?.read) throw new Error('no project file access in this host');+ return fs.read(path);}/** A captured viewport frame: raw RGBA pixels (GL order: bottom-up rows). */@@ -950,57 +958,38 @@ export class EditorControlSurfaceImpl {*/async profileFrames(ms = 1000, topSystems = 12): Promise<ProfileReport> {const w = await PerfMonitor.captureWindow(Math.min(5000, Math.max(100, ms)));- const systems = w.mean.domains- .flatMap((d) => d.children.map((s) => ({ domain: d.id, node: s })))- .sort((a, b) => b.node.ms - a.node.ms);- const shown = systems.slice(0, topSystems);- return {- realm: w.realm,+ return profileReportOf(w, {+ origin: `live:${w.realm}`,windowMs: w.windowMs,- frames: w.frames,stalled: w.stalled,- budgetMs: w.budgetMs,- fps: w.fps,- p50: w.p50, p95: w.p95, p99: w.p99,- longFrames: w.longFrames,- worstFrameMs: w.worstFrameMs,- frame: {- totalMs: r2(w.mean.frameMs),- cpuMs: r2(w.mean.cpuMs),- waitMs: r2(w.mean.waitMs),- idleMs: r2(w.mean.idleMs),- gpuMs: w.mean.gpuMs >= 0 ? r2(w.mean.gpuMs) : -1,- },- // A plugin that is installed and costs nothing is not an answer to "where- // did the time go", and there are two dozen of them. Counted, not hidden.- domains: w.mean.domains.filter((d) => r2(d.ms) > 0).map((d) => ({ domain: d.id, ms: r2(d.ms) })),- freeDomains: w.mean.domains.filter((d) => r2(d.ms) === 0).length,- render: {- drawCalls: r2(w.drawCalls),- mergedAway: r2(w.counters['batch.merged'] ?? 0),- triangles: Math.round(w.triangles),- entities: Math.round(w.entities),- breaks: batchBreaks(w.counters),- },- systems: shown.map(({ domain, node }) => ({- name: node.label,- domain,- ms: r2(node.ms),- ...(node.query- ? {- query: {- calls: r2(node.query.calls),- scanned: Math.round(node.query.scanned),- filtered: Math.round(node.query.filtered),- },- }- : {}),- scopes: node.children- .filter((c) => c.ms >= 0.05)- .map((c) => ({ name: c.label, ms: r2(c.ms), kind: c.kind })),- })),- omittedSystems: systems.length - shown.length,- };+ worst: w.worstFrameProfile,+ memory: w.memory,+ topSystems,+ });+ }++ /**+ * The same answer, read off a recorded `.esprof` instead of the running frame —+ * how a capture from a device gets analysed rather than merely looked at.+ * Refuses with the reason when the file is not a capture.+ */+ async profileCaptureFile(path: string, topSystems = 12): Promise<ProfileReport> {+ const text = await readProjectText(path);+ const parsed = parseProfileCapture(text);+ if ('error' in parsed) throw new Error(`${path}: ${parsed.error}`);+ const capture = parsed.capture;+ if (capture.frames.length === 0) throw new Error(`${path}: the capture has no frames`);+ const summary = summarizeCapture(capture);+ const worst = capture.frames.find((f) => f.id === summary.worstFrameId) ?? null;+ const src = capture.source;+ return profileReportOf(summary, {+ origin: [path, src.label, src.platform, src.realm].filter(Boolean).join(' · '),+ windowMs: capture.frames.reduce((a, f) => a + f.dtMs, 0),+ stalled: false,+ worst: worst ? frameProfileOf(worst) : null,+ memory: meanMemory(capture.frames),+ topSystems,+ });}/** The current profiler snapshot: frame timing, stat-unit segments, per-systemdiff --git a/desktop/src/engine/PerfMonitor.ts b/desktop/src/engine/PerfMonitor.tsindex b6d6ef511..d571b3d3d 100644--- a/desktop/src/engine/PerfMonitor.ts+++ b/desktop/src/engine/PerfMonitor.ts@@ -68,6 +68,11 @@ export interface EngineFrame {vramBytes: number;}+/** Chrome only; 0 where the engine cannot see the JS heap. */+function jsHeapBytes(): number {+ return (performance as Performance & { memory?: { usedJSHeapSize: number } }).memory?.usedJSHeapSize ?? 0;+}+/** The engine's C++ scopes as the profile model's native scopes. */function nativeScopesOf(cppScopes: Record<string, number>): ScopeCost[] {return Object.entries(cppScopes).map(([name, ms]) => ({ name, ms, system: '', remainder: 'work' as const }));@@ -112,6 +117,9 @@ export interface FrameSample {drawCalls: number;triangles: number;entities: number;+ /** This frame's heaps. Per frame rather than per window, so a capture written+ * from a sample carries what the memory graph shows. */+ memory: { wasmBytes: number; jsHeapBytes: number; vramBytes: number };}export interface FrameLongTask {@@ -178,6 +186,8 @@ export interface ProfileWindow extends CaptureSummary {/** No frame ran in the window: nothing is animating, or the window is hidden. */stalled: boolean;worstFrameProfile: FrameProfile | null;+ /** Averaged per frame over the window. */+ memory: { wasmBytes: number; jsHeapBytes: number; vramBytes: number };}/** One captured frame in the portable vocabulary — what a `.esprof` holds. */@@ -193,12 +203,20 @@ export function capturedFrameOf(s: FrameSample): CapturedFrame {drawCalls: s.drawCalls,triangles: s.triangles,entities: s.entities,+ memory: s.memory,// Absent from anything a shipped game records; kept here because profiling// the editor is a real thing the editor's own profiler is asked to do.editor: { ms: s.editorMs, phases: s.editorPhases },};}+function meanOver(frames: readonly CapturedFrame[], pick: (f: CapturedFrame) => number): number {+ if (frames.length === 0) return 0;+ let total = 0;+ for (const f of frames) total += pick(f);+ return total / frames.length;+}+const LONG_FRAME_MS = 24; // missed a 60Hz frameconst HITCH_MS = 50; // auto-freeze threshold — a real hitch (below 20fps)const WINDOW_MS = 500;@@ -386,6 +404,11 @@ class PerfMonitorImpl {// or the editor is in the background). Said, not implied by zeroes.stalled: frames.length === 0,worstFrameProfile: worst ? frameProfileOf(worst) : null,+ memory: {+ wasmBytes: meanOver(frames, (f) => f.memory?.wasmBytes ?? 0),+ jsHeapBytes: meanOver(frames, (f) => f.memory?.jsHeapBytes ?? 0),+ vramBytes: meanOver(frames, (f) => f.memory?.vramBytes ?? 0),+ },};}@@ -521,6 +544,11 @@ class PerfMonitorImpl {drawCalls: this.counters.drawCalls,triangles: this.counters.triangles,entities: this.counters.entities,+ memory: {+ wasmBytes: this.mem.wasmBytes,+ jsHeapBytes: jsHeapBytes(),+ vramBytes: this.mem.vramBytes,+ },};// The wait is the tree's, so the windowed unit bar and the pinned tree can// never disagree about how much of this frame was work.diff --git a/desktop/src/engine/profileReport.ts b/desktop/src/engine/profileReport.tsindex 59646bc6a..aa9a2ab8f 100644--- a/desktop/src/engine/profileReport.ts+++ b/desktop/src/engine/profileReport.ts@@ -4,6 +4,11 @@* @file profileReport.ts — the profile as an agent reads it: ranked, and honest* about what it left out.*/+import type { CaptureSummary, FrameProfile, ProfileNode } from 'esengine';++const r2 = (n: number): number => Math.round(n * 100) / 100;++const BREAK_PREFIX = 'batch.break.';export interface ProfileReportQuery {calls: number;@@ -21,7 +26,8 @@ export interface ProfileReportSystem {}export interface ProfileReport {- realm: 'edit' | 'play';+ /** Where the numbers came from: a live realm, or a capture's own source. */+ origin: string;windowMs: number;frames: number;/** No frame ran: nothing is animating, or the editor window is in the background. */@@ -33,7 +39,12 @@ export interface ProfileReport {p99: number;longFrames: number;worstFrameMs: number;- /** Per frame over the window. `totalMs = cpuMs + waitMs + idleMs`; gpu is parallel. */+ /**+ * The worst frame's own breakdown, which is what a stutter actually is — the+ * averages above describe the frames that were fine.+ */+ worstFrame: { ms: number; domains: Array<{ domain: string; ms: number }> } | null;+ /** Per frame. `totalMs = cpuMs + waitMs + idleMs`; gpu is a parallel track. */frame: { totalMs: number; cpuMs: number; waitMs: number; idleMs: number; gpuMs: number };domains: Array<{ domain: string; ms: number }>;/** Domains that cost nothing this window — installed and idle. */@@ -51,8 +62,107 @@ export interface ProfileReport {entities: number;breaks: Record<string, number>;};+ /** Averaged per frame. -1 where the source did not record that heap. */+ memory: { wasmMB: number; jsHeapMB: number; vramMB: number };/** Costliest systems over the window, per frame. */systems: ProfileReportSystem[];/** Systems ranked below the cut. Zero means the list above is all of them. */omittedSystems: number;}++/** The `batch.break.*` counters as reason → draws, by their bare reason name. */+function batchBreaks(counters: Record<string, number>): Record<string, number> {+ const out: Record<string, number> = {};+ for (const key in counters) {+ if (key.startsWith(BREAK_PREFIX)) out[key.slice(BREAK_PREFIX.length)] = r2(counters[key]);+ }+ return out;+}++function domainRows(profile: FrameProfile): Array<{ domain: string; ms: number }> {+ return profile.domains.filter((d) => r2(d.ms) > 0).map((d) => ({ domain: d.id, ms: r2(d.ms) }));+}++function systemRows(profile: FrameProfile): Array<{ domain: string; node: ProfileNode }> {+ return profile.domains+ .flatMap((d) => d.children.map((node) => ({ domain: d.id, node })))+ .sort((a, b) => b.node.ms - a.node.ms);+}++const MB = 1 / (1024 * 1024);+const mb = (bytes: number | undefined): number => (bytes && bytes > 0 ? r2(bytes * MB) : -1);++export interface ProfileReportContext {+ origin: string;+ windowMs: number;+ stalled: boolean;+ worst: FrameProfile | null;+ /** Averaged bytes per frame, where the source recorded them. */+ memory?: { wasmBytes?: number; jsHeapBytes?: number; vramBytes?: number };+ topSystems?: number;+}++/**+ * Project a summary into the reply an agent gets. Pure, and shared by the live+ * window and an imported capture, so "where did the time go" reads the same+ * whether it was asked of this editor or of a file recorded on a phone.+ */+export function profileReportOf(summary: CaptureSummary, ctx: ProfileReportContext): ProfileReport {+ const systems = systemRows(summary.mean);+ const shown = systems.slice(0, ctx.topSystems ?? 12);+ return {+ origin: ctx.origin,+ windowMs: ctx.windowMs,+ frames: summary.frames,+ stalled: ctx.stalled,+ budgetMs: r2(summary.budgetMs),+ fps: summary.fps,+ p50: r2(summary.p50),+ p95: r2(summary.p95),+ p99: r2(summary.p99),+ longFrames: summary.longFrames,+ worstFrameMs: r2(summary.worstFrameMs),+ worstFrame: ctx.worst ? { ms: r2(ctx.worst.frameMs), domains: domainRows(ctx.worst) } : null,+ frame: {+ totalMs: r2(summary.mean.frameMs),+ cpuMs: r2(summary.mean.cpuMs),+ waitMs: r2(summary.mean.waitMs),+ idleMs: r2(summary.mean.idleMs),+ gpuMs: summary.mean.gpuMs >= 0 ? r2(summary.mean.gpuMs) : -1,+ },+ // A plugin that is installed and costs nothing is not an answer to "where+ // did the time go", and there are two dozen of them. Counted, not hidden.+ domains: domainRows(summary.mean),+ freeDomains: summary.mean.domains.filter((d) => r2(d.ms) === 0).length,+ render: {+ drawCalls: r2(summary.drawCalls),+ mergedAway: r2(summary.counters['batch.merged'] ?? 0),+ triangles: Math.round(summary.triangles),+ entities: Math.round(summary.entities),+ breaks: batchBreaks(summary.counters),+ },+ memory: {+ wasmMB: mb(ctx.memory?.wasmBytes),+ jsHeapMB: mb(ctx.memory?.jsHeapBytes),+ vramMB: mb(ctx.memory?.vramBytes),+ },+ systems: shown.map(({ domain, node }) => ({+ name: node.label,+ domain,+ ms: r2(node.ms),+ ...(node.query+ ? {+ query: {+ calls: r2(node.query.calls),+ scanned: Math.round(node.query.scanned),+ filtered: Math.round(node.query.filtered),+ },+ }+ : {}),+ scopes: node.children+ .filter((c) => c.ms >= 0.05)+ .map((c) => ({ name: c.label, ms: r2(c.ms), kind: c.kind })),+ })),+ omittedSystems: systems.length - shown.length,+ };+}diff --git a/desktop/src/panels/ProfilerPanel.tsx b/desktop/src/panels/ProfilerPanel.tsxindex 0f9bca578..659614133 100644--- a/desktop/src/panels/ProfilerPanel.tsx+++ b/desktop/src/panels/ProfilerPanel.tsx@@ -247,6 +247,18 @@ function TreeRow({ node, frameMs, depth }: { node: ProfileNode; frameMs: number;);}+const MB = 1 / (1024 * 1024);++type MemKey = 'wasmBytes' | 'jsHeapBytes' | 'vramBytes';++/** A frame's heap, or the capture's mean of it. `—` where nothing recorded it. */+function mbOf(frame: CapturedFrame | null, capture: ProfileCapture, key: MemKey): string {+ const bytes = frame+ ? frame.memory?.[key] ?? 0+ : capture.frames.reduce((a, f) => a + (f.memory?.[key] ?? 0), 0) / (capture.frames.length || 1);+ return bytes > 0 ? (bytes * MB).toFixed(1) : '—';+}+/*** A capture off disk, rendered by the same rows the live realm uses. Where it* came from is stated rather than implied: a file recorded on someone's phone@@ -330,6 +342,20 @@ function CaptureView({ loaded, frame, onPick, onClose }: {</div></section>+ <section className="prof-sec">+ <h4>{t('prof.groupMemory')}</h4>+ <MemGraph hist={capture.frames.map((f) => ({+ wasm: (f.memory?.wasmBytes ?? 0) * MB,+ js: (f.memory?.jsHeapBytes ?? 0) * MB,+ vram: (f.memory?.vramBytes ?? 0) * MB,+ }))} />+ <div className="prof-stat-grid">+ <div><span style={{ color: 'var(--warn)' }}>wasm</span><b>{mbOf(frame, capture, 'wasmBytes')}<i>MB</i></b></div>+ <div><span style={{ color: 'var(--star)' }}>{t('prof.jsHeap')}</span><b>{mbOf(frame, capture, 'jsHeapBytes')}<i>MB</i></b></div>+ <div><span style={{ color: GPU_COLOR }}>vram</span><b>{mbOf(frame, capture, 'vramBytes')}<i>MB</i></b></div>+ </div>+ </section>+<section className="prof-sec"><h4>{t('prof.groupCounters')}</h4>{Object.entries<number>(frame?.counters ?? summary.counters)diff --git a/desktop/tests/perf-monitor.test.ts b/desktop/tests/perf-monitor.test.tsindex 41d2b5dc9..7dc7aadab 100644--- a/desktop/tests/perf-monitor.test.ts+++ b/desktop/tests/perf-monitor.test.ts@@ -48,6 +48,7 @@ describe('profileOf', () => {engineMs: 0, editorMs: 0, presentWaitMs: 0, gpuMs: -1,editorPhases: {}, enginePhases: {}, cppScopes: {}, gpuScopes: {},costs: null, counters: {}, drawCalls: 0, triangles: 0, entities: 0,+ memory: { wasmBytes: 16 * 1024 * 1024, jsHeapBytes: 8 * 1024 * 1024, vramBytes: 4 * 1024 * 1024 },...over,});diff --git a/desktop/tests/profile-capture-roundtrip.test.ts b/desktop/tests/profile-capture-roundtrip.test.tsindex 057149bad..c7b7d231d 100644--- a/desktop/tests/profile-capture-roundtrip.test.ts+++ b/desktop/tests/profile-capture-roundtrip.test.ts@@ -34,6 +34,7 @@ const sample = (over: Partial<FrameSample> = {}): FrameSample => ({drawCalls: 6,triangles: 120,entities: 50,+ memory: { wasmBytes: 16 * 1024 * 1024, jsHeapBytes: 8 * 1024 * 1024, vramBytes: 4 * 1024 * 1024 },...over,});diff --git a/sdk/src/app/profileRecorder.ts b/sdk/src/app/profileRecorder.tsindex 98958d69d..5acf01ffe 100644--- a/sdk/src/app/profileRecorder.ts+++ b/sdk/src/app/profileRecorder.ts@@ -24,6 +24,12 @@ export interface ProfileRecorderOptions {const DEFAULT_MAX_FRAMES = 1800;+/** Chrome only; 0 where the runtime does not expose its heap. */+function jsHeapBytes(): number {+ if (typeof performance === 'undefined') return 0;+ return (performance as Performance & { memory?: { usedJSHeapSize: number } }).memory?.usedJSHeapSize ?? 0;+}+function parseScopes(json: string | undefined): Record<string, number> {if (!json) return {};try {@@ -125,7 +131,11 @@ export class ProfileRecorder {drawCalls: render.drawCalls,triangles: render.triangles,entities: this.app_.getEntityCount(),- memory: { wasmBytes: m?.HEAPU8?.byteLength ?? 0 },+ memory: {+ wasmBytes: m?.HEAPU8?.byteLength ?? 0,+ jsHeapBytes: jsHeapBytes(),+ vramBytes: m?.renderer_getTextureBytes?.() ?? 0,+ },};this.frames_.push(frame);const cap = this.options_.maxFrames ?? DEFAULT_MAX_FRAMES;