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
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/.gitignorenew file mode 100644index 000000000..97dee9aef--- /dev/null+++ b/bench/transform-invalidation/.gitignore@@ -0,0 +1 @@+results*.jsondiff --git a/bench/transform-invalidation/README.md b/bench/transform-invalidation/README.mdnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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 })}`);