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
chore(bench): the comments state the contract, not the story
yhhbe66e2829a89
diff --git a/bench/aot-native/frame-bench.mjs b/bench/aot-native/frame-bench.mjsindex b31fd41d5..c3ed8bdf9 100644--- a/bench/aot-native/frame-bench.mjs+++ b/bench/aot-native/frame-bench.mjs@@ -38,15 +38,10 @@ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '.const SYSTEMS = path.join(ROOT, 'bench', 'aot-frame', 'project', 'src', 'systems.ts');/**- * `--gate` turns the benchmark into a release criterion.- *- * The failure this road can have is SILENT: `AotDispatcher.run` returns whether it- * took the system, and false sends it back to the interpreter for that frame. That- * is deliberate — the no-cliff rule — so a regression that unbinds every system- * raises no error and changes no pixel. It only costs time, and nothing was- * measuring time. A same-machine ratio is what sees it: an engine that stopped- * dispatching reads ~1x, and no absolute millisecond ceiling has to be calibrated- * to a machine for that to be true.+ * `--gate` turns the benchmark into a release criterion, because this road's+ * failure is silent: a system that stops being dispatched to falls back to the+ * interpreter by design, raising no error and changing no pixel. A same-machine+ * ratio sees that where a millisecond ceiling cannot. See the README.*/const GATE = process.argv.includes('--gate');const ENTITIES = Number(process.env.BENCH_ENTITIES ?? (GATE ? 2000 : 5000));@@ -287,13 +282,9 @@ try {console.log(`\nno-JIT frame — QuickJS-ng in the native host, ${ENTITIES} entities, `+ `${FRAMES} frames after ${WARMUP}, best of ${REPS}\n`);-// `update` is not a column. On this host it only SCHEDULES the App tick — an async-// function returns at its first await — so the systems, and the render they drive,-// run in the microtask drain that follows. `tick` below is that drain.-// `draws` is a column because a BODY can move the render's cost. `heavy` writes-// `position.z` per entity, which breaks sprite batching into one draw each: its-// frame then carries ~5000 draw calls that have nothing to do with the system, and-// the ratio reads low for a reason no timing column can show.+// `tick` is the microtask drain, not the `update` call: that one only schedules an+// async tick. `draws` is a column because a body can move the render's cost —+// `heavy` writes `position.z`, which breaks sprite batching into one draw each.console.log('body build tick p50 cpu p50 frame p50 draws compiled?');for (const r of rows) {console.log(`${r.body.padEnd(9)} ${r.key.padEnd(13)} ${`${r.pump.p50.toFixed(3)} ms`.padStart(10)}`diff --git a/native/host/Bench.hpp b/native/host/Bench.hppindex 0b305d8cc..95ae30e68 100644--- a/native/host/Bench.hpp+++ b/native/host/Bench.hpp@@ -5,10 +5,10 @@* @brief What a frame COSTS on this host — the number AOT exists for, measured* where the constraint AOT exists for actually holds.* @details Every frame number this engine has ever published came from a host with- * a JIT: V8 on the desktop, Chromium on the phone (docs/REARCH_AOT.md- * §18). But `bench/aot-frame`'s own README says the number the road was- * built for is the no-JIT one, and the plan's proxy for it was a Mac- * running Bun/JavaScriptCore.+ * a JIT: V8 on the desktop, Chromium on the phone. As `bench/aot-frame`'s+ * own README puts it, the number the road was built for is the no-JIT+ * one — and the plan's way to get it was a Mac running+ * Bun/JavaScriptCore.** The proxy stopped being necessary the day this host learned to dispatch* to compiled systems. It embeds QuickJS-ng, which has no JIT — the samediff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cppindex bf7a57f47..60440a0e8 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp@@ -393,10 +393,9 @@ bool WebGPUDevice::surfaceBytesAreBGRA() const {/*** The fastest present mode this surface actually advertises.*- * Mailbox first: it drops finished frames instead of blocking, so the CPU is- * never made to wait and nothing tears. Immediate next — it tears, which is- * irrelevant to a measurement. Fifo if the surface offers neither, in which case- * the caller gets a throttled frame and the numbers say so.+ * Mailbox first: it drops finished frames rather than blocking the CPU, and does+ * not tear. Immediate tears, which a measurement does not care about. Fifo is the+ * fallback, and then the caller's frame is throttled.*/WGPUPresentMode WebGPUDevice::pickUncappedPresentMode() const {#if !defined(__EMSCRIPTEN__)diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hppindex 01ff310ce..533d8234c 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp@@ -277,18 +277,12 @@ public:void setSurfaceReadback(bool enabled) { surface_readback_ = enabled; }/**- * @brief Let the swapchain present as fast as it can, instead of waiting for- * the display. Must be set BEFORE the surface is configured.+ * @brief Present as fast as the surface allows instead of waiting for the+ * display. Set BEFORE the surface is configured; off by default.*- * Off by default, and a shipped game should leave it off: an uncapped- * swapchain burns a core to draw frames nobody sees. It exists for- * MEASUREMENT — under Fifo, `getCurrentTexture` blocks until an image frees,- * so every frame cheaper than the refresh interval reads as exactly the- * refresh interval and every frame dearer than it reads as a multiple. A cost- * quantised to the panel is not a cost.- *- * Best effort: the mode is taken from what the surface advertises (Mailbox,- * then Immediate), and a surface offering neither keeps Fifo.+ * For MEASUREMENT only: under Fifo every frame reads as the refresh interval+ * or a multiple of one, and a cost quantised to the panel is not a cost.+ * Best effort — Mailbox, then Immediate, then Fifo.*/void setPresentUncapped(bool enabled) { present_uncapped_ = enabled; }diff --git a/tools/releaseGate.mjs b/tools/releaseGate.mjsindex f52fe16f5..e9f138eb5 100644--- a/tools/releaseGate.mjs+++ b/tools/releaseGate.mjs@@ -105,15 +105,9 @@ export const CRITERIA = [{id: 'a-compiled-system-is-cheaper-where-there-is-no-jit',says: 'on a host with no JIT, a compiled system costs a fraction of the interpreted one',- // The reason this is a criterion and not a benchmark: the fallback is SILENT.- // `AotDispatcher.run` returns whether it took the system, and false sends it- // back to the interpreter for that frame — deliberately, so a project never- // hits a cliff. An engine that stopped dispatching therefore raises no error- // and changes no pixel; it only costs time. The desktop native host embeds- // QuickJS-ng, which has no JIT, so this measures the constraint iOS imposes on- // the machine that builds. A RATIO, not a millisecond ceiling: one number that- // has to be recalibrated per machine is a criterion that fails on the wrong- // machines and passes on the wrong code.+ // The fallback is SILENT: a system the dispatcher stops taking goes back to+ // the interpreter by design, raising no error and changing no pixel. The bar+ // is a same-machine RATIO — a millisecond ceiling is per machine.answeredBy: 'node bench/aot-native/frame-bench.mjs --gate',needs: ['bench/aot-native/frame-bench.mjs',