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
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.mdindex 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.mjsnew file mode 100644index 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.tsindex 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)) ? Nuconst 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.mjsindex 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);}