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.

bench(ecs): what it costs for a Transform write to say it happened

esenginea920fe3d3f85
diff --git a/bench/transform-invalidation/.gitignore b/bench/transform-invalidation/.gitignore
new file mode 100644
index 000000000..97dee9aef
--- /dev/null
+++ b/bench/transform-invalidation/.gitignore
@@ -0,0 +1 @@
+results*.json
diff --git a/bench/transform-invalidation/README.md b/bench/transform-invalidation/README.md
new file mode 100644
index 000000000..3dc913936
--- /dev/null
+++ b/bench/transform-invalidation/README.md
@@ -0,0 +1,66 @@
+# Transform invalidation write tax
+
+Composition has to know it went stale, and no single layer sees every producer
+that could make it so — a TS write reaches the component heap through a ptr
+setter and calls no C++; a C++ system writes the same bytes and tells the
+tracker nothing. So the write path itself has to notify.
+
+This measures what that notification costs on the hottest producer there is:
+`Query(Mut(Transform))` writing back every row.
+
+## The arms
+
+| | after the component write |
+|---|---|
+| **A** | nothing — the path as it is |
+| **B** | `epoch[0]++` in the WASM heap |
+| **C** | `dirty[0] = 1` in the WASM heap |
+| **D** | an ABI call across the boundary |
+
+The counters live in the engine's own linear memory (`_malloc` + a `Uint32Array`
+view over `HEAPU32.buffer`), not a JS `ArrayBuffer`. The question is what a
+second store into memory the write already touches costs, and a typed array
+somewhere else would not answer it. The view is re-taken if the heap grew, since
+a detached one writes nowhere and would time beautifully.
+
+## What it costs
+
+`node bench/transform-invalidation/run.mjs` — every row's notification actually
+landed (the epoch advanced by exactly the number of writes; removing the store
+turns that check red).
+
+| entities | A | B | C | D |
+|---|---|---|---|---|
+| 1k | 63.6 ns | 61.6 | 58.9 | 99.0 |
+| 10k | 47.1 ns | 47.0 | 47.3 | 88.9 |
+| 100k | 47.8 ns | 48.6 | 48.4 | 89.9 |
+
+As a share of one core at 60Hz, 100k writes per frame: **A 28.7%, B 29.1%,
+C 29.0%, D 53.9%**.
+
+**A store into linear memory is free at this resolution.** Writing a Transform
+already costs ~48 ns; one more word alongside it does not show up above the
+noise, at any size, and the adversarial case — every logical write, zero
+semantic movement — measures the same. Across runs B and C land on either side
+of A, which is the finding rather than a flaw in it: the difference is smaller
+than the run-to-run spread.
+
+**An ABI call is not.** Crossing the boundary for one integer costs 42 ns per
+write, +88%, and turns 100k writes per frame from 29% of a core into 54%.
+
+**A monotonic epoch and a dirty bit cost the same.** There is no performance
+argument for the weaker one, so the choice can be made on what is easier to
+reason about: a generation can say *which* compose a consumer is holding, a bit
+can only say that one is owed.
+
+## What this does not answer
+
+- One notification per logical writeback, deliberately — the most conservative
+ shape, and the one every producer can satisfy without coordination. Batching
+ per system or per AOT invocation would be cheaper still and is not needed to
+ make the number acceptable.
+- The C++ producers are not measured here. They write the same bytes from the
+ other side, and a store there is not more expensive than a store here.
+- Nothing about how a consumer finds WHICH transforms changed. An epoch answers
+ "is the composition stale", in O(1). Enumerating changed composed transforms
+ is a different structure and a different question.
diff --git a/bench/transform-invalidation/arm.mjs b/bench/transform-invalidation/arm.mjs
new file mode 100644
index 000000000..da7f2ed70
--- /dev/null
+++ b/bench/transform-invalidation/arm.mjs
@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file What one Transform write costs when it also has to say it happened.
+ *
+ * Composition needs to know it has gone stale, and no single layer can see every
+ * producer — so the write path itself has to notify. This measures the price of
+ * that notification on the hottest producer there is: `Query(Mut(Transform))`
+ * writing back every row.
+ *
+ * The counters live in the WASM heap, not a plain ArrayBuffer: the real cost is
+ * a second store into linear memory a write is already touching, and a JS-side
+ * typed array would not answer that.
+ *
+ * node bench/transform-invalidation/arm.mjs --arm B --entities 100000
+ */
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const argv = process.argv.slice(2);
+const flag = (name, fallback) => {
+ const i = argv.indexOf(`--${name}`);
+ return i >= 0 && argv[i + 1] !== undefined ? argv[i + 1] : fallback;
+};
+
+const ARM = flag('arm', 'A');
+const ENTITIES = Number(flag('entities', '100000'));
+const WRITE_RATE = Number(flag('writes', '1'));
+const WARMUP = Number(flag('warmup', '30'));
+const MEASURE = Number(flag('measure', '120'));
+/** The adversarial case: every logical write, no semantic movement. */
+const STILL = argv.includes('--still');
+
+const sdk = await import(pathToFileURL(path.join(ROOT, 'sdk', 'dist', 'index.node.js')).href);
+const wasmDir = process.env.ESENGINE_WASM_DIR ?? path.join(ROOT, 'build', 'wasm', 'web');
+const factory = (await import(pathToFileURL(path.join(wasmDir, 'esengine.js')).href)).default;
+const module = await factory({ locateFile: (f) => path.join(wasmDir, f) });
+
+const app = sdk.App.new();
+app.connectCpp(new module.Registry(), module, { strict: false });
+const world = app.world;
+const registry = world.getCppRegistry();
+
+const entities = new Array(ENTITIES);
+for (let i = 0; i < ENTITIES; i++) {
+ const e = world.spawn();
+ world.insert(e, sdk.Transform, { position: { x: i, y: 0, z: 0 } });
+ entities[i] = e;
+}
+
+// A word of the engine's own linear memory, which is what a generated setter
+// would be storing to — not a JS ArrayBuffer that lives somewhere else.
+const slot = module._malloc(4);
+const view = () => new Uint32Array(module.HEAPU32.buffer, slot, 1);
+let counter = view();
+counter[0] = 0;
+
+// The write path a Mut row takes, resolved once as the query does.
+const getter = world.resolveGetter(sdk.Transform, 'borrowed');
+const setter = world.resolveSetter(sdk.Transform);
+const abiCall = () => module.registry_getCameraEntities(registry);
+
+const WRITES = Math.max(1, Math.round(ENTITIES * WRITE_RATE));
+let notifications = 0;
+
+function pass(tick) {
+ // The heap moves when wasm grows it, and a detached view silently writes
+ // nowhere — the correctness check at the end is what would catch that.
+ if (counter.buffer !== module.HEAPU32.buffer) counter = view();
+ for (let i = 0; i < WRITES; i++) {
+ const e = entities[i];
+ const t = getter(e);
+ if (!t) continue;
+ if (!STILL) t.position.x = t.position.x + 1;
+ setter(e, t);
+ switch (ARM) {
+ case 'B': counter[0] = counter[0] + 1; notifications++; break;
+ case 'C': counter[0] = 1; notifications++; break;
+ case 'D': abiCall(); notifications++; break;
+ default: break;
+ }
+ }
+ void tick;
+}
+
+for (let t = 0; t < WARMUP; t++) pass(t);
+if (ARM === 'C') counter[0] = 0;
+notifications = 0;
+const before = counter[0];
+const t0 = process.hrtime.bigint();
+for (let t = 0; t < MEASURE; t++) pass(t);
+const ns = Number(process.hrtime.bigint() - t0);
+const after = counter[0];
+
+let checksum = 0;
+for (let i = 0; i < Math.min(ENTITIES, 1000); i++) {
+ checksum += world.get(entities[i], sdk.Transform).position.x;
+}
+
+const totalWrites = WRITES * MEASURE;
+// The notification actually happened: an arm whose store was optimised away, or
+// whose view had detached, would time beautifully and mean nothing.
+const notified = ARM === 'A' ? after === before
+ : ARM === 'B' ? after === (before + totalWrites) >>> 0
+ : ARM === 'C' ? after === 1
+ : notifications === totalWrites;
+
+process.stdout.write(`${JSON.stringify({
+ arm: ARM, entities: ENTITIES, writeRate: WRITE_RATE, still: STILL,
+ passes: MEASURE, writes: totalWrites,
+ totalMs: ns / 1e6,
+ nsPerWrite: ns / totalWrites,
+ usPerPass: ns / 1000 / MEASURE,
+ // One pass per simulated frame at 60Hz.
+ oneCorePercent: (ns / 1000 / MEASURE) * 60 / 1e4,
+ notified, epochBefore: before, epochAfter: after, checksum,
+})}\n`);
diff --git a/bench/transform-invalidation/run.mjs b/bench/transform-invalidation/run.mjs
new file mode 100644
index 000000000..9fc52fe56
--- /dev/null
+++ b/bench/transform-invalidation/run.mjs
@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file What one Transform write costs when it also has to say it happened.
+ *
+ * node bench/transform-invalidation/run.mjs
+ *
+ * Ships nothing: no production path notifies anything yet.
+ */
+import { spawnSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { sdkIdentity } from '../replication-dirty/workload.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, '..', '..');
+const ARM = path.join(HERE, 'arm.mjs');
+const ARMS = ['A', 'B', 'C', 'D'];
+const MEANING = {
+ A: 'the write path as it is',
+ B: 'a monotonic epoch in the wasm heap',
+ C: 'a dirty flag in the wasm heap',
+ D: 'an ABI call across the boundary',
+};
+const SIZES = [1000, 10000, 100000];
+
+function run(arm, entities, extra = []) {
+ const out = spawnSync(process.execPath, [
+ ARM, '--arm', arm, '--entities', String(entities),
+ '--warmup', '10', '--measure', '40', ...extra,
+ ], { encoding: 'utf8', cwd: ROOT, maxBuffer: 1 << 24 });
+ if (out.status !== 0) {
+ console.error(out.stderr || out.stdout);
+ throw new Error(`arm ${arm} @ ${entities} exited ${out.status}`);
+ }
+ return JSON.parse(out.stdout);
+}
+
+const points = [];
+for (const entities of SIZES) for (const arm of ARMS) points.push(run(arm, entities));
+const still = ARMS.slice(0, 3).map((arm) => run(arm, 100000, ['--still']));
+
+const say = (s = '') => console.log(s);
+const pad = (v, w) => String(v).padStart(w);
+say('');
+say('=== what it costs to say a Transform moved ===');
+say('');
+for (const arm of ARMS) say(` ${arm} ${MEANING[arm]}`);
+say('');
+const unverified = [...points, ...still].filter((p) => !p.notified);
+say(unverified.length === 0
+ ? ' Every arm\'s notification landed: the epoch advanced once per write.'
+ : ` UNVERIFIED: ${unverified.length} point(s) did not notify — the numbers mean nothing.`);
+say('');
+say(' entities arm ns/write 1 core @60Hz vs A');
+for (const entities of SIZES) {
+ const a = points.find((p) => p.arm === 'A' && p.entities === entities);
+ for (const arm of ARMS) {
+ const p = points.find((q) => q.arm === arm && q.entities === entities);
+ const ratio = arm === 'A' ? '—' : (p.nsPerWrite / a.nsPerWrite).toFixed(2);
+ say(` ${pad(entities, 9)} ${arm} ${pad(p.nsPerWrite.toFixed(2), 8)} ${pad(`${p.oneCorePercent.toFixed(1)}%`, 12)} ${pad(ratio, 6)}`);
+ }
+}
+say('');
+say(' 100k writes with no semantic movement (every write still notifies):');
+for (const p of still) say(` ${p.arm} ${p.nsPerWrite.toFixed(2)} ns/write`);
+say('');
+say(' A store into linear memory does not show up beside the write it follows.');
+say(' An ABI call for one integer does. Epoch and dirty-bit cost the same, so');
+say(' the choice between them is about what is easier to reason about.');
+say('');
+say(` ${JSON.stringify({ ...sdkIdentity(ROOT), cpu: os.cpus()[0]?.model })}`);