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.

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.mjs
index 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.hpp
index 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 same
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
index 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.hpp
index 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.mjs
index 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',