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.

bench(aot): a rendered frame is asked what half of it is script

yhhaf52e9fa7cf5
diff --git a/bench/aot-stage0/README.md b/bench/aot-stage0/README.md
index 70aaa5182..7ff8f5cb4 100644
--- a/bench/aot-stage0/README.md
+++ b/bench/aot-stage0/README.md
@@ -121,11 +121,54 @@ headless 帧里 `rest` 只有 0.04 ms,因为渲染器根本不在。拿它乘 St
**结论的形状:渲染器的 C++ 得占到无 JIT 帧的一半以上,AOT 才会掉到 2× 以下。**
无 JIT 下 TS 那半边还会再涨 ~12 倍而 C++ 不变,`c` 只会更小。
-### 还欠一次测量
+---
+
+## `frame-share-rendered.mjs` —— `c` 的实测值
+
+上面那个跑 headless,看不见渲染器。这个驱动 pixel-gate 的 render host:真 WebGL2 上下文、
+`scale-sprites` 场景、9801 个精灵,读 SDK 自己的 `ProfileRecorder`
+(它把每系统 TS ms 和引擎 C++ `ES_PROFILE_SCOPE` ms 配在一起)。
+
+```sh
+node bench/aot-stage0/frame-share-rendered.mjs
+```
+
+**没有新埋点。** `ProfileRecorder.start()` 本来就同时打开两侧——它的注释写着为什么:
+只开一侧「看起来像一个不花钱的引擎,而不是一个没被量的引擎」。缺的是 render host 上的
+一扇门,不是一个 harness。
+
+| | ms/帧 |
+|---|---|
+| TS 系统 | 1.30(56.5%) |
+| C++ scope | 1.00(**c = 43.5%**) |
+| GPU | 4.07(设备的,编译脚本碰不到) |
+
+`render.collect` 0.74 / `.finalize` 0.31 / `.graph` 0.04 / `.submit` 0.01。
+
+### 不要用 Stage 0 的 396× 去乘整个 TS
+
+第一版这么干了,打印出 231×。**那是错的**:396× 是在组件字节上的数值循环量的(AOT 最好情形),
+而这里 94% 的 TS 是 `RenderSystem` —— draw 提交和过桥调用,不是算术。改用两个实测输入:
+
+- `K` = QuickJS/V8 在真实 SDK 代码上 = **12×**
+- 无 JIT 帧 = `K·TS + C++` = **16.6 ms CPU**,其中 TS 占 94%
+
+| 编译后的 TS | 帧加速 |
+|---|---|
+| 只追平 JIT(下界) | **7.2×** |
+| 跑到原生速度(上界) | **16.0×** |
+
+### 两个与 AOT 无关的发现
+
+1. **`RenderSystem` 占 CPU 帧的 53%。** 一帧里最烫的是脚本,而且不是游戏代码,
+ 是 SDK 自己的 draw 提交。
+2. **无 JIT 下这一帧要 16.6 ms CPU**,正好是 60fps 预算。原生宿主在 9801 精灵上已经贴边跑。
+
+### 路上修的两个「报零」bug
-**真实带渲染的一帧里,渲染器的 C++ 花多少。** wasm 构建已经在记
-(`render.collect` / `.submit` / `.graph` / `.finalize`,走 `ES_PROFILE_SCOPE`)。
+- `es_profile_now_ms()` 在非 Emscripten 下 `return 0.0` —— 那四个 render scope 在
+ 桌面 / Android / iOS 上**从来就是 0**。已修成 `std::chrono::steady_clock`。
+- `nativeScopes` 是 `{name, ms}[]` 不是 Record,按 Record 读会得到安静的 `(none recorded)`,
+ 报出 `c = 0%`。
-**原生构建之前记不了** —— `es_profile_now_ms()` 在非 Emscripten 下 `return 0.0`,
-所以那四个 scope 在桌面 / Android / iOS 上**从来就是 0**。没人发现,是因为一个报 0 的
-profiler 看起来就像一个在报「这帧很快」的 profiler。已修(`std::chrono::steady_clock`)。
+两个是同一类错误:**一个报零的测量,看起来像一个好消息。**
diff --git a/bench/aot-stage0/frame-share-rendered.mjs b/bench/aot-stage0/frame-share-rendered.mjs
new file mode 100644
index 000000000..dec362126
--- /dev/null
+++ b/bench/aot-stage0/frame-share-rendered.mjs
@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file frame-share-rendered.mjs
+ * @brief `c` — the C++ share of a REAL rendered frame (docs/REARCH_AOT.md §14).
+ *
+ * @details frame-share.mjs runs headless, so the renderer is missing and the TS
+ * share it reports is an upper bound. This drives the pixel-gate host
+ * instead — a real WebGL2/WebGPU context, a real scene, 9801 sprites —
+ * and reads the SDK's own ProfileRecorder, which pairs per-system TS ms
+ * with the engine's C++ ES_PROFILE_SCOPE ms.
+ *
+ * No new instrumentation: ProfileRecorder.start() already engages both
+ * sides. What was missing was a door on the render host, not a harness.
+ *
+ * What it still is NOT: wasm under V8, not native under QuickJS. So the
+ * C++ half is SLOWER here than native and the TS half is FASTER than an
+ * interpreter — both biases inflate `c`, which makes the number a
+ * conservative (pessimistic) input to the Amdahl table.
+ *
+ * node bench/aot-stage0/frame-share-rendered.mjs
+ */
+import { spawnSync } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, '..', '..');
+const RUNNER = join(ROOT, 'tools', 'render-host', 'run.mjs');
+
+// The sprite-scale-cost gate's scene: one fixture sprite copied onto a 99x99
+// grid. A real rendered frame at an entity count a game would recognise.
+const SCENE_ENV = {
+ ESTELLA_VERIFY_SCENE: '/scenes/scale-sprites.esscene',
+ ESTELLA_VERIFY_W: '256',
+ ESTELLA_VERIFY_H: '256',
+ ESTELLA_VERIFY_STEPS: '30',
+ ESTELLA_VERIFY_SCALE: '{"copies":9801,"cols":99,"spacing":[6,6]}',
+ ESTELLA_VERIFY_PLAY: '1',
+ ESTELLA_VERIFY_PROFILE: process.env.BENCH_FRAMES ?? '90',
+};
+
+const STAGE0_INTERP_FACTOR = 396;
+
+const sum = (xs) => xs.reduce((a, b) => a + b, 0);
+const median = (xs) => {
+ const s = [...xs].sort((a, b) => a - b);
+ return s.length ? s[Math.floor(s.length / 2)] : 0;
+};
+const ms = (x) => x.toFixed(4);
+
+function run(cmd, args, env) {
+ return spawnSync(cmd, args, {
+ cwd: ROOT, encoding: 'utf8', shell: process.platform === 'win32',
+ env: { ...process.env, ...env }, maxBuffer: 64 * 1024 * 1024,
+ });
+}
+
+console.log('building the render host (it bundles sdk/dist, not sdk/src)…');
+const built = run('node', ['tools/render-host/build.mjs'], {});
+if (built.status !== 0) {
+ console.error((built.stderr || built.stdout || '').slice(-2000));
+ process.exit(1);
+}
+
+console.log('driving electron with a real GL context, 9801 sprites…');
+const r = run('pnpm', ['exec', 'electron', RUNNER], SCENE_ENV);
+const out = `${r.stdout ?? ''}${r.stderr ?? ''}`;
+const drive = /^DRIVE_RESULT (\{.*\})$/m.exec(out);
+if (!drive) {
+ console.error(out.slice(-3000));
+ console.error('\nno DRIVE_RESULT — the run did not reach its verdict.');
+ process.exit(1);
+}
+
+const result = JSON.parse(drive[1]);
+const frames = result.profile?.frames ?? [];
+if (!frames.length) {
+ console.error('DRIVE_RESULT carried no profile frames. ESTELLA_VERIFY_PROFILE not honoured?');
+ process.exit(1);
+}
+
+// Per frame: TS is every system's ms; C++ is every engine scope's ms. GPU time is
+// neither — it is the device's, and compiling script does not touch it.
+const tsPer = [];
+const cppPer = [];
+const systemTotals = new Map();
+const scopeTotals = new Map();
+for (const f of frames) {
+ const ts = sum((f.systems ?? []).map((s) => s.ms));
+ const cpp = sum((f.nativeScopes ?? []).map((s) => s.ms));
+ tsPer.push(ts);
+ cppPer.push(cpp);
+ for (const s of f.systems ?? []) systemTotals.set(s.name, (systemTotals.get(s.name) ?? 0) + s.ms);
+ for (const s of f.nativeScopes ?? []) scopeTotals.set(s.name, (scopeTotals.get(s.name) ?? 0) + s.ms);
+}
+
+const n = frames.length;
+const ts = median(tsPer);
+const cpp = median(cppPer);
+const cpu = ts + cpp;
+const c = cpu > 0 ? cpp / cpu : 0;
+// nativeScopes and systems are both ScopeCost[]/SystemCost[] — {name, ms} — not
+// Records. Reading either as a Record yields string concatenation and a silent
+// "(none recorded)", which is how the first run of this reported c = 0%.
+const gpu = median(frames.map((f) => (typeof f.gpuMs === 'number' ? f.gpuMs : -1)));
+
+console.log('\n' + '='.repeat(70));
+console.log('Estella AOT — `c` from a rendered frame (REARCH_AOT.md §14)');
+console.log(` frames : ${n} recorded, ${result.entityCount} entities, ${result.drawCalls} draw call(s)`);
+console.log(` runtime : wasm under V8 — see the header for which way that biases c`);
+console.log('='.repeat(70));
+
+const show = (title, totals) => {
+ console.log(`\n ${title}`);
+ const rows = [...totals.entries()].map(([k, v]) => [k, v / n]).filter(([, v]) => v > 0)
+ .sort((a, b) => b[1] - a[1]).slice(0, 10);
+ if (!rows.length) { console.log(' (none recorded)'); return; }
+ for (const [k, v] of rows) console.log(` ${k.padEnd(42)} ${ms(v).padStart(10)} ms`);
+};
+show('TypeScript systems', systemTotals);
+show('engine C++ scopes (ES_PROFILE_SCOPE)', scopeTotals);
+
+console.log('\n ' + '-'.repeat(66));
+console.log(` TS ${ms(ts).padStart(10)} ms ${(100 * (1 - c)).toFixed(1)}%`);
+console.log(` C++ ${ms(cpp).padStart(10)} ms ${(100 * c).toFixed(1)}% <- c`);
+console.log(` CPU ${ms(cpu).padStart(10)} ms`);
+console.log(` GPU ${ms(gpu).padStart(10)} ms (the device's; compiling script does not touch it)`);
+
+// Two MEASURED inputs, not the Stage 0 factor: 396x came from a numeric loop
+// over component bytes (AOT's best case) and 94% of the TS here is RenderSystem,
+// which is draw submission. K is QuickJS/V8 on real SDK code, per frame-share.mjs.
+const K = 12;
+const NATIVE_OVER_V8 = STAGE0_INTERP_FACTOR / K; // ~33x on the Stage 0 loop
+
+const njFrame = K * ts + cpp;
+const floorFrame = ts + cpp; // compiled TS merely matches V8
+const ceilFrame = ts / NATIVE_OVER_V8 + cpp; // compiled TS runs native
+const floorX = njFrame / floorFrame;
+const ceilX = njFrame / ceilFrame;
+
+console.log('\n carried to the native host (TS interpreted, C++ compiled)');
+console.log(' ' + '-'.repeat(66));
+console.log(` c measured here (wasm + jit) ............. ${(100 * c).toFixed(1)}%`);
+console.log(` K = QuickJS/V8 on real SDK code ......... ${K}x (measured)`);
+console.log(` a no-JIT frame would be ................. ${ms(njFrame)} ms CPU`);
+console.log(` of which TS ........................... ${(100 * K * ts / njFrame).toFixed(1)}%`);
+console.log('');
+console.log(` compiled TS merely matches a JIT ........ ${floorX.toFixed(1)}x <- floor`);
+console.log(` compiled TS runs at native speed ........ ${ceilX.toFixed(1)}x <- ceiling`);
+console.log(`
+ gate (REARCH_AOT §13.4): >= 3x opens Stage 1 -> ${floorX >= 3 ? 'OPEN' : 'HOLD'}`);
+
+// The frame's hottest thing is TypeScript, and it is not a game system.
+const hottest = [...systemTotals.entries()].sort((a, b) => b[1] - a[1])[0];
+if (hottest) {
+ const hm = hottest[1] / n;
+ console.log('\n the finding that does not depend on AOT at all');
+ console.log(' ' + '-'.repeat(66));
+ console.log(` ${hottest[0]} is ${ms(hm)} ms — ${(100 * hm / ts).toFixed(0)}% of the TS and`);
+ console.log(` ${(100 * hm / cpu).toFixed(0)}% of the CPU frame. The hottest thing in a rendered frame is`);
+ console.log(' script, and it is the SDK own draw submission, not game code.');
+}
+console.log('='.repeat(70));
diff --git a/tools/render-host/host.ts b/tools/render-host/host.ts
index 344398c3b..641ef7e9d 100644
--- a/tools/render-host/host.ts
+++ b/tools/render-host/host.ts
@@ -23,6 +23,7 @@ import {
finishDeviceRecovery, getContextLossGuardInfo, decodeImagePixels, captureFramePixels,
RenderTexture, Camera, Sprite,
EditorView, EditorGrid, installEditorGrid, editorViewHalfHeight, setEditorViewHalfHeight,
+ ProfileRecorder,
} from 'esengine';
import type { App, SceneData, SceneEntityData, PrefabData, RenderSurfaceSource } from 'esengine';
import type { ESEngineModule } from 'esengine/wasm';
@@ -43,6 +44,7 @@ const randomSeed = seedParam !== null && Number.isFinite(Number(seedParam)) ? Nu
const depthLayers = Number(params.get('depthLayers')) || undefined;
let app: App | null = null;
+let profiler: ProfileRecorder | null = null;
let module: ESEngineModule | null = null;
let canvas: HTMLCanvasElement | null = null;
// A driver addresses entities by the id the SCENE FILE gives them, not by the
@@ -422,6 +424,24 @@ const api = {
}
},
+ /** Records whole frames — TS system ms beside the engine's own C++ scope ms,
+ * which is the only pairing that says what SHARE of a frame is script.
+ * ProfileRecorder.start() engages both sides; engaging one reads as an
+ * engine that costs nothing rather than one that was not measured. */
+ startProfile(): void {
+ if (!app) throw new Error('startProfile: no app — load a scene first');
+ profiler ??= new ProfileRecorder(app);
+ profiler.start();
+ },
+
+ /** The frames recorded since startProfile, then stops recording. */
+ takeProfile(): unknown {
+ if (!profiler) return { frames: [] };
+ const capture = profiler.take();
+ profiler.stop();
+ return capture;
+ },
+
/** Runs the gameplay systems the authoring mode freezes. */
setRunMode(playing: boolean): boolean {
setEditorMode(!playing);
diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjs
index 9d1f4f443..17d7e0a0e 100644
--- a/tools/render-host/run.mjs
+++ b/tools/render-host/run.mjs
@@ -28,6 +28,7 @@
* ESTELLA_VERIFY_COUNTERS_MAX counters the frame must stay UNDER — a budget (JSON)
* ESTELLA_VERIFY_SCALE copy the scene's content onto a grid (JSON), for a cost gate
* ESTELLA_VERIFY_OUTPUT_TRANSFORM the frame's output curve ("aces")
+ * ESTELLA_VERIFY_PROFILE record N further frames and report the TS/C++ cost split
* ESTELLA_VERIFY_TIMEOUT_MS how long this run may take before it reports one
*/
import { app, BrowserWindow } from 'electron';
@@ -295,6 +296,17 @@ app.whenReady().then(async () => {
await exec(`window.__estellaHeadless.api.step(${STEPS}, 1 / 60)`);
}
+ // ESTELLA_VERIFY_PROFILE = N: record N more frames through the SDK's own
+ // ProfileRecorder — TS system ms beside the engine's C++ scope ms. Recorded
+ // AFTER the steps above, so scene load is not charged to a frame.
+ let profile = null;
+ if (process.env.ESTELLA_VERIFY_PROFILE) {
+ const n = Number(process.env.ESTELLA_VERIFY_PROFILE) || 60;
+ await exec('window.__estellaHeadless.api.startProfile()');
+ await exec(`window.__estellaHeadless.api.step(${n}, 1 / 60)`);
+ profile = await exec('window.__estellaHeadless.api.takeProfile()');
+ }
+
// Loads an .esmesh through the asset layer and points the scene's meshes at
// it, replacing their inline geometry. The fixture holds the SAME vertices,
// so the assertions stand: a file drawing what the scene draws is the claim.
@@ -699,7 +711,7 @@ app.whenReady().then(async () => {
};
`);
}
- finish({ ok: true, entityCount, drawCalls, draws, counters, capture, expect, resize, preview, meshPreview, grid, deviceLoss, meshResident, meshAsset, meshMaterial, meshPrefab, setField, pick, cameraTarget }, server);
+ finish({ ok: true, entityCount, drawCalls, draws, counters, profile, capture, expect, resize, preview, meshPreview, grid, deviceLoss, meshResident, meshAsset, meshMaterial, meshPrefab, setField, pick, cameraTarget }, server);
} catch (e) {
finish({ ok: false, error: String((e && e.stack) || e) }, server);
}