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(bench): what a compiled system costs, and where that cost goes
yhhe189187240c1
diff --git a/bench/aot-native/README.md b/bench/aot-native/README.mdindex 01099d8ec..9c96146e7 100644--- a/bench/aot-native/README.md+++ b/bench/aot-native/README.md@@ -96,6 +96,66 @@ was written for a headless harness where nothing renders and the z-write was frea real renderer it is the dominant cost. `draws` is a column for exactly this reason — acost that lands somewhere the report cannot see reads as the system's.+## What a compiled system costs, and where that cost goes++The table above cannot resolve the compiled column: at 5,000 entities the whole+compiled frame is 1.7 ms and the idle floor is 1.5 ms, so the system is 0.09 ms+against an idle-to-idle spread of about 0.11 ms. **Raising the entity count does not+help** — the floor is mostly the sprite render, and that scales with the count too.+`BENCH_SPRITES=0` is what resolves it: it removes the render from the floor without+touching the system.++With the floor gone, at 20,000 entities:++| body | interpreted | **compiled** | what the body is |+|---|---|---|---|+| thin | 9819 ns/entity | **20 ns** | three multiply-adds |+| heavy | 10497 ns/entity | **21 ns** | four substeps, four `sqrt`, branches |+| script | 2422 ns/entity | **20 ns** | three multiply-adds, script component |++**Three bodies and two component kinds all land on 20–21 ns.** A body of four square+roots is indistinguishable from three multiply-adds, which means what a compiled+system costs is not its code. That is the same shape the wasm road had at 27.5+ns/entity before its row table stopped being rebuilt every frame, after which thin+went to 2.1 ns and heavy became visibly dearer at 9.4.++### The cost is proportional to the WORLD, not to what the system matches++`BENCH_BYSTANDERS` spawns entities carrying only a `Transform`, so no body's query+can ever match them. That separates world size from matched-set size:++| world | matching | compiled system | interpreted (control) |+|---|---|---|---|+| 5,000 | 5,000 | **0.114 ms** | 49.34 ms |+| 50,000 | **the same 5,000** | **0.333 ms** | 51.17 ms |++The same 5,000 entities are moved either way, and it costs **2.9x more** in the+larger world — about **4.9 ns per frame for every entity the system will never+touch**. The interpreted column is the control: it barely moves, because the SDK's+query narrows to the matched set. Only the compiled path grows.++**Size the contrast against the noise, not against intuition.** The first run of+this used 15,000 bystanders — a 4x world — which puts the expected effect at about+0.2 ms against an idle-to-idle spread of 0.11 ms. It came out *backwards*, the+larger world reading cheaper, which is the shape a measurement has when it is+reading its own noise. Nothing about it looked wrong; the table simply said+something impossible, and that is the only reason it was caught.++`native/host/bindings/AotBindings.cpp` builds the candidate list from+`forEachEntity` — every live entity, per compiled system, per frame — and+`AotHost::packCall` then resolves every component of every candidate and rolls back+the ones that do not match. Absence is the row filter, which is sound and is what+lets a host bind a system it has no types for; what it costs had not been measured.+Read as a budget: a 20,000-entity game whose compiled system matches 200 entities+spends about 96% of that system's time on entities it does not touch, and a second+compiled system scans the whole world again.++Both terms have a known fix and neither is a compiler change. Narrowing the+candidates needs the pools' sizes, which the same generator that emits+`AotComponents.generated.*` could emit. Reusing the row table across frames needs+an authority for "nothing moved", and `Registry::layoutEpoch()` already is one —+this host is in the same process as it, where the web road needed a binding.+## What this is and is notIt **is** the shipped iOS/Android interpreter, on a desktop CPU. QuickJS-ng is what@@ -143,5 +203,7 @@ different deltas, move different distances, and have no differential between the| `BENCH_REPS` | 3 | processes per configuration; the fastest is kept || `BENCH_BODIES` | `thin` | any of `thin`, `thick`, `heavy`, `script` || `BENCH_IDLE` | off | also run the scene with no body, so a system's own cost can be read off it |+| `BENCH_SPRITES` | on | `0` drops the `Sprite`, which is most of the idle floor — needed to resolve a compiled system at all |+| `BENCH_BYSTANDERS` | 0 | extra entities with only a `Transform`, which no query matches: they grow the world without growing the matched set || `BENCH_MIN_RATIO` | 5 | `--gate` only: the ratio a fallback cannot pass || `BENCH_KEEP` | off | keep the exported apps for poking at |diff --git a/bench/aot-native/frame-bench.mjs b/bench/aot-native/frame-bench.mjsindex c3ed8bdf9..088520864 100644--- a/bench/aot-native/frame-bench.mjs+++ b/bench/aot-native/frame-bench.mjs@@ -55,6 +55,19 @@ const MIN_RATIO = Number(process.env.BENCH_MIN_RATIO ?? 5);/** An idle run of the same scene, so a body's OWN cost can be read off the frame. */const IDLE = process.env.BENCH_IDLE === '1';const KEEP = process.env.BENCH_KEEP === '1';+/**+ * Whether the entities carry a `Sprite`. On by default, so the frame is a real+ * one. Turn it off to resolve a COMPILED system: the sprite render is most of the+ * idle floor, and it scales with the entity count, so raising that count alone+ * never lifts a cheap system clear of it.+ */+const SPRITES = process.env.BENCH_SPRITES !== '0';+/**+ * Entities carrying only a `Transform`, so no body's query can ever match them.+ * They separate the size of the WORLD from the size of the matched set, which is+ * the only way to see a dispatcher that scans one to find the other.+ */+const BYSTANDERS = Number(process.env.BENCH_BYSTANDERS ?? 0);/** Which component each body moves, and how to read a position off it. */const BODY = {@@ -120,6 +133,7 @@ import { Mover, Pos, thinSystem, thickSystem, heavySystem, scriptSystem } from '// Generated by bench/aot-native/frame-bench.mjs — an entity count is a parameter.const ENTITIES = ${ENTITIES};+const BYSTANDERS = ${BYSTANDERS};const CHECKSUM_AT = ${WARMUP + FRAMES};/** The generator bench/aot-frame uses, so both benchmarks lay out one scene. */@@ -139,8 +153,13 @@ const setupSystem = defineSystem([Commands()], (cmds) => {cmds.spawn().insert(Transform, { position: { x: (rand() - 0.5) * 2000, y: (rand() - 0.5) * 2000, z: 0 } }).insert(Mover, { dx: rand() - 0.5, dy: rand() - 0.5, speed: 40 + rand() * 80, boost: rand() < 0.5 ? 1 : 0 })- .insert(Pos, { x: 0, y: 0, z: 0 })- .insert(Sprite, { size: { x: 4, y: 4 }, color: { r: 1, g: 1, b: 1, a: 1 } });+ .insert(Pos, { x: 0, y: 0, z: 0 })${SPRITES+ ? "\n .insert(Sprite, { size: { x: 4, y: 4 }, color: { r: 1, g: 1, b: 1, a: 1 } })" : ''};+ }+ // No Mover, so no body's query can match them: they grow the world without+ // growing the matched set.+ for (let i = 0; i < BYSTANDERS; i++) {+ cmds.spawn().insert(Transform, { position: { x: 0, y: 0, z: 0 } });}}, { name: 'BenchSetup' });