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.

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.md
index 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 fre
a real renderer it is the dominant cost. `draws` is a column for exactly this reason — a
cost 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 not
It **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.mjs
index 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' });