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.

probe(net): the ceiling on regional invalidation is the grid, not the token

esengine8d66ec4f8d23
diff --git a/bench/interest-regional/README.md b/bench/interest-regional/README.md
new file mode 100644
index 000000000..54121bec3
--- /dev/null
+++ b/bench/interest-regional/README.md
@@ -0,0 +1,100 @@
+# Does one entity moving have to invalidate every connection?
+
+N3e made the sample in which NOTHING moved free — 3,863 µs to 17 at 100k × 32.
+What it did not touch is the sample in which something moved *somewhere else*:
+there is one spatial generation, so a single write re-proves all C views.
+
+This asks what it would cost to invalidate only the connections whose answer
+could have changed — and, first, whether there is anything there to win.
+
+```
+node bench/interest-regional/probe.mjs --scenario near
+```
+
+## Three shapes over one truth
+
+Every arm decides only **whether** to call `prepared.query`, never what it
+answers. The truth is the shipped `radiusInterestProvider`.
+
+| | how it decides |
+|---|---|
+| **G** | one global generation — what ships. Anything moves, everyone re-queries. |
+| **A** | fingerprint the cells this connection's radius covers; unchanged ⇒ skip |
+| **B** | reverse cell → connections; a mutation marks its watchers, the query reads one flag |
+
+**A's token is over the whole support region, not the anchor's cell.** A radius
+answer depends on every bucket it can reach: an entity moving in a neighbouring
+cell changes it while the anchor's own cell stands still. The keys are hashed as
+well as the revisions, so an anchor that crossed into a new cell cannot keep a
+token minted for the cells it left.
+
+## The answer: the ceiling is the grid, not the token
+
+`cell = radius` (the provider's own), so at 100k entities and 1% visibility the
+world is about 350 cells and a footprint is 9 of them. **1% movement is 1,000
+movers — about three per cell.**
+
+| scenario | distinct cells touched / world | G recomputes | **A recomputes** | G µs | A µs | B µs | A tax | B tax |
+|---|---|---|---|---|---|---|---|---|
+| scattered — 1% moves uniformly | **434 / 374** | 32 | **32.0** | 2,336 | 2,392 | 2,429 | 70 | 180 |
+| clustered connections | 434 / 374 | 32 | **32.0** | 1,563 | 1,585 | 1,683 | 47 | 143 |
+| every anchor moves | **43 / 35** | 32 | **32.0** | 2,327 | 2,371 | 2,480 | 57 | 146 |
+| movement far from anchors | 40 / 32 | 32 | 31.0 | 2,544 | 2,475 | 2,533 | 70 | 152 |
+| crossing a cell boundary | 460 / 1008 | 32 | **10.2** | 3,116 | 864 | 911 | 79 | 100 |
+| movement next to one anchor | **26 / 342** | 32 | **5.4** | 3,024 | **429** | 411 | 67 | 46 |
+
+- **Uniform movement touches the whole grid, so no token over that grid can be
+ quiet.** 434 distinct cells against a 374-cell world: not "most of it", all of
+ it and then the ones that came and went. This is a property of the cell size,
+ not of how the token is computed, and the grid is frozen.
+- **A connection's own anchor moving invalidates that connection**, always and
+ correctly. So in a game where every player moves every tick, recomputes are
+ `C` whatever the scheme — the floor is not reachable from here.
+- **The win is real where movement is concentrated**: 26 cells of 342 touched
+ gives 5.4 of 32 connections re-proved, and 3,024 µs → 429. That is the shape
+ of NPC or physics traffic in a region nobody is standing in.
+
+## B is strictly dominated
+
+**A and B produce the identical recompute count in every scenario** — they are
+the same predicate computed two ways. B then pays 2–3× the maintenance for it
+(143–180 µs against 47–79), because it re-registers footprints and walks
+watchers where A hashes 27 map reads at query time.
+
+So the reverse cell → connection index is not worth maintaining. The question
+this probe existed to answer — *is scanning a few dozen cell revisions already
+close enough to free* — comes out **yes**: A's tax is 47–79 µs per sample for
+32 connections × 27 cells, about **2 µs per connection against a 73 µs query**.
+
+## What this means for shipping it
+
+A costs ~3% of a query and can save 86% of one. It never loses much and
+sometimes wins sevenfold — but the scenarios a 32-player game actually runs
+(everyone moves) are exactly the ones where it wins nothing.
+
+**So this is not the next cut on its own.** It is worth doing when there is a
+workload with many connections and localized movement — an MMO shard, or a game
+whose NPCs outnumber its players — and the shape to build then is A.
+
+## The two ways this goes wrong, kept apart
+
+The probe audits every arm against an independent full rebuild on the last
+samples, and **refuses to report a single number if any arm's set differs**
+(exit 1). That separates the two failures the counts alone would confuse:
+
+| sabotage | what reddens |
+|---|---|
+| the regional token written as the global generation | `near`: A recomputes 5.4 → **32**. The audit stays green — nothing went stale, the optimisation just stopped working. |
+| the footprint narrowed to the anchor's own cell | the audit: `arm A, connection 2, sample 25: missing 4200931`, exit 1. Counts look *better*; the answer is wrong. |
+
+## What this does not cover
+
+- One anchor per connection and a uniform grid world. `distinct cells touched`
+ is the number everything turns on, and it is a property of how players and
+ movement are arranged.
+- The arms are timed in a **rotating order**. Fixed at G,A,B this first reported
+ A and B 40% faster than G on samples where all three recomputed the identical
+ 32 views — the last arm was reading caches the first two warmed.
+- The probe maintains its own cell revisions from the mutations it makes; a
+ production version would maintain them where the provider already consumes the
+ composition delta. What is measured is the decision, not that plumbing.
diff --git a/bench/interest-regional/probe.mjs b/bench/interest-regional/probe.mjs
new file mode 100644
index 000000000..bf684067f
--- /dev/null
+++ b/bench/interest-regional/probe.mjs
@@ -0,0 +1,319 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Whether one entity moving has to invalidate every connection.
+ *
+ * N3e made the sample in which NOTHING moved free. What it did not touch is the
+ * sample in which something moved somewhere else: there is one spatial
+ * generation, so a single write re-proves all C views. This asks what it would
+ * cost to only invalidate the connections whose answer could have changed.
+ *
+ * Three shapes over one truth, and the truth is the shipped provider — every arm
+ * decides only WHETHER to call `prepared.query`, never what it answers:
+ *
+ * G one global generation — what ships. Anything moves, everyone re-queries.
+ * A query-footprint fingerprint. Before querying, walk the cells this
+ * connection's radius covers and combine their revisions; unchanged means
+ * the entity traversal is skipped.
+ * B reverse cell -> connections. A mutation marks the connections registered
+ * on that cell; the query reads one per-connection flag.
+ *
+ * The question A exists to answer is whether scanning a few dozen cell
+ * revisions is already close enough to free that B's second reverse index is
+ * not worth maintaining.
+ *
+ * node bench/interest-regional/probe.mjs --scenario near
+ */
+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 ENTITIES = Number(flag('entities', '100000'));
+const CONNECTIONS = Number(flag('connections', '32'));
+const VISIBLE = Number(flag('visible', '0.01'));
+const MOVEMENT = Number(flag('movement', '0.01'));
+/** 1 = anchors spread over the whole map, small = packed into a corner. */
+const CLUSTER = Number(flag('cluster', '1'));
+const SCENARIO = flag('scenario', 'scattered');
+const WARMUP = Number(flag('warmup', '8'));
+const MEASURE = Number(flag('measure', '40'));
+/** Full-rebuild agreement is O(C x E) and is the point of the probe, not its
+ * cost — it runs on a few samples, not all of them. */
+const AUDIT = Number(flag('audit', '4'));
+
+const { loadSdk, sdkIdentity } = await import(pathToFileURL(
+ path.join(ROOT, 'bench/replication-interest/workload.mjs')).href);
+const sdk = await loadSdk(ROOT);
+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 engine = await factory({ locateFile: (f) => path.join(wasmDir, f) });
+
+const app = sdk.App.new();
+app.connectCpp(new engine.Registry(), engine, { strict: false });
+const world = app.world;
+
+const side = Math.ceil(Math.sqrt(ENTITIES));
+const RADIUS = VISIBLE >= 1 ? side * 2 : Math.sqrt((VISIBLE * ENTITIES) / Math.PI);
+/** The provider's own cell size, reproduced: the footprint IS its 3x3x3 scan. */
+const CELL = Math.max(RADIUS, Number.EPSILON);
+const cellOf = (x, y, z) => `${Math.floor(x / CELL)},${Math.floor(y / CELL)},${Math.floor(z / CELL)}`;
+
+const entities = new Array(ENTITIES);
+const at = new Array(ENTITIES);
+for (let i = 0; i < ENTITIES; i++) {
+ const e = world.spawn();
+ const p = { x: i % side, y: Math.floor(i / side), z: 0 };
+ world.insert(e, sdk.Transform, { position: p });
+ entities[i] = e;
+ at[i] = p;
+}
+
+/** One anchor per connection. Index into `entities`, so a moved anchor moves. */
+const anchorIdx = new Map();
+const span = Math.max(1, Math.floor(ENTITIES * CLUSTER));
+const stride = Math.max(1, Math.floor(span / CONNECTIONS));
+for (let c = 0; c < CONNECTIONS; c++) anchorIdx.set(c + 1, (c * stride) % ENTITIES);
+
+world.ensureTransformsComposed();
+const provider = sdk.radiusInterestProvider(RADIUS);
+let prepared = provider.prepare({
+ world, entities, entityCount: ENTITIES, entered: entities, left: [], rechecked: [],
+});
+
+/** An independent full rebuild — the only thing that can say an arm went stale. */
+function freshVisible(idx) {
+ const a = at[idx];
+ const out = new Set();
+ const r2 = RADIUS * RADIUS;
+ for (let i = 0; i < ENTITIES; i++) {
+ const p = at[i];
+ const dx = p.x - a.x, dy = p.y - a.y, dz = p.z - a.z;
+ if (dx * dx + dy * dy + dz * dz <= r2) out.add(entities[i]);
+ }
+ return out;
+}
+
+// ── the regional bookkeeping the provider does not have ──────────────────────
+/** cell key -> how many times anything in it moved, entered or left. */
+const cellRev = new Map();
+const revOf = (k) => cellRev.get(k) ?? 0;
+let placelessRev = 0;
+let bump = 0;
+/** Distinct cells a sample touches, against how many the world has. This is the
+ * whole ceiling: once a sample touches most of the grid, no footprint over that
+ * grid can be quiet, however the token is computed. */
+let touchedThisSample = new Set();
+let distinctTouched = 0;
+function touchCell(k) { cellRev.set(k, revOf(k) + 1); bump++; touchedThisSample.add(k); }
+
+/** The cells one connection's radius can reach: the provider's own 3x3x3. */
+function footprint(idx) {
+ const a = at[idx];
+ const cx = Math.floor(a.x / CELL), cy = Math.floor(a.y / CELL), cz = Math.floor(a.z / CELL);
+ const out = [];
+ for (let dx = -1; dx <= 1; dx++)
+ for (let dy = -1; dy <= 1; dy++)
+ for (let dz = -1; dz <= 1; dz++) out.push(`${cx + dx},${cy + dy},${cz + dz}`);
+ return out;
+}
+
+/**
+ * A token over the whole support region, not over the anchor's cell. The keys
+ * are in it as well as the revisions: an anchor that crossed into a new cell has
+ * a different footprint, and the cells it left could then go unwatched.
+ */
+function fingerprint(cells) {
+ let h = 0x811c9dc5 ^ placelessRev;
+ for (const k of cells) {
+ for (let i = 0; i < k.length; i++) h = Math.imul(h ^ k.charCodeAt(i), 0x01000193);
+ h = Math.imul(h ^ revOf(k), 0x01000193);
+ }
+ return h >>> 0;
+}
+
+// ── arms ────────────────────────────────────────────────────────────────────
+const arms = {
+ G: { recomputes: 0, queryNs: 0n, taxNs: 0n, held: new Map(), token: new Map() },
+ A: { recomputes: 0, queryNs: 0n, taxNs: 0n, held: new Map(), token: new Map() },
+ B: { recomputes: 0, queryNs: 0n, taxNs: 0n, held: new Map(), token: new Map() },
+};
+let globalGen = 0;
+
+/** B's reverse index: cell -> connections whose footprint covers it. */
+const watchers = new Map();
+const watchedBy = new Map();
+const dirtyConns = new Set();
+function registerB(c, cells) {
+ for (const k of watchedBy.get(c) ?? []) watchers.get(k)?.delete(c);
+ watchedBy.set(c, cells);
+ for (const k of cells) {
+ let s = watchers.get(k);
+ if (!s) { s = new Set(); watchers.set(k, s); }
+ s.add(c);
+ }
+}
+for (const [c, idx] of anchorIdx) registerB(c, footprint(idx));
+
+function query(c, idx) {
+ return prepared.query({ connectionId: c, owned: [entities[idx]] });
+}
+
+// ── one sample's world change ───────────────────────────────────────────────
+function mutate(tick) {
+ touchedThisSample = new Set();
+ const moved = Math.round(ENTITIES * MOVEMENT);
+ const anchors = [...anchorIdx.values()];
+ const near = anchors[tick % anchors.length];
+ for (let k = 0; k < moved; k++) {
+ let i;
+ if (SCENARIO === 'far') {
+ // Deterministically far from every anchor: the midpoint between two.
+ const a = anchors[k % anchors.length], b = anchors[(k + 1) % anchors.length];
+ i = ((a + b) >> 1) % ENTITIES;
+ if (anchorIdx.size && anchors.includes(i)) i = (i + 7919) % ENTITIES;
+ } else if (SCENARIO === 'near') {
+ i = (near + 1 + k) % ENTITIES;
+ } else if (SCENARIO === 'anchor') {
+ i = anchors[k % anchors.length];
+ } else {
+ i = (tick * 7919 + k * 7919) % ENTITIES;
+ }
+ const p = at[i];
+ const before = cellOf(p.x, p.y, p.z);
+ // 'boundary' walks entities across a cell edge every sample; the others
+ // jitter within one, which still changes distances.
+ const step = SCENARIO === 'boundary' ? CELL : ((tick + k) % 3) - 1;
+ p.x += step;
+ world.update(entities[i], sdk.Transform, (t) => { t.position.x = p.x; });
+ const after = cellOf(p.x, p.y, p.z);
+ touchCell(before);
+ if (after !== before) touchCell(after);
+ }
+ return moved;
+}
+
+function sample(tick, timed) {
+ mutate(tick);
+ // After the world changed and before anybody is asked: a mark that ran
+ // first would hand B the PREVIOUS sample's mutations and the audit would
+ // catch it a sample later as stale visibility.
+ distinctTouched += touchedThisSample.size;
+ const marked = markB();
+ if (timed) arms.B.taxNs += marked;
+ world.ensureTransformsComposed();
+ prepared = provider.prepare({
+ world, entities, entityCount: ENTITIES, entered: [], left: [], rechecked: [],
+ });
+ globalGen++;
+
+ // Rotated per sample: all three arms call the same `prepared.query`, so a
+ // fixed order lets the last one read caches the first two warmed — it
+ // reported A and B 40% faster on samples where all three did equal work.
+ const order = ['G', 'A', 'B'];
+ for (let r = 0; r < tick % order.length; r++) order.push(order.shift());
+
+ for (const [c, idx] of anchorIdx) {
+ for (const name of order) step[name](c, idx, timed);
+ }
+ dirtyConns.clear();
+}
+
+/** One arm's decision for one connection. Only WHETHER to query differs. */
+const step = {
+ G(c, idx, timed) {
+ const a = arms.G;
+ if (a.token.get(c) === globalGen) return;
+ const t0 = process.hrtime.bigint();
+ a.held.set(c, query(c, idx));
+ if (timed) a.queryNs += process.hrtime.bigint() - t0;
+ a.recomputes++;
+ a.token.set(c, globalGen);
+ },
+ A(c, idx, timed) {
+ const a = arms.A;
+ const t0 = process.hrtime.bigint();
+ const fp = fingerprint(footprint(idx));
+ if (timed) a.taxNs += process.hrtime.bigint() - t0;
+ if (a.token.get(c) === fp) return;
+ const t1 = process.hrtime.bigint();
+ a.held.set(c, query(c, idx));
+ if (timed) a.queryNs += process.hrtime.bigint() - t1;
+ a.recomputes++;
+ a.token.set(c, fp);
+ },
+ B(c, idx, timed) {
+ const a = arms.B;
+ if (!dirtyConns.has(c) && a.token.has(c)) return;
+ const t1 = process.hrtime.bigint();
+ a.held.set(c, query(c, idx));
+ if (timed) a.queryNs += process.hrtime.bigint() - t1;
+ a.recomputes++;
+ a.token.set(c, 1);
+ const t2 = process.hrtime.bigint();
+ registerB(c, footprint(idx));
+ if (timed) a.taxNs += process.hrtime.bigint() - t2;
+ },
+};
+
+/** B's maintenance: a cell that moved marks everyone watching it. Charged to B. */
+function markB() {
+ const t0 = process.hrtime.bigint();
+ for (const [k, rev] of cellRev) {
+ if (rev === lastSeenRev.get(k)) continue;
+ lastSeenRev.set(k, rev);
+ for (const c of watchers.get(k) ?? []) dirtyConns.add(c);
+ }
+ return process.hrtime.bigint() - t0;
+}
+const lastSeenRev = new Map();
+
+function audit(tick) {
+ for (const [c, idx] of anchorIdx) {
+ const want = freshVisible(idx);
+ for (const name of ['G', 'A', 'B']) {
+ const got = arms[name].held.get(c);
+ if (!got) { fail(name, c, tick, 'never answered'); return; }
+ if (got.size !== want.size) {
+ fail(name, c, tick, `holds ${got.size} where a rebuild says ${want.size}`); return;
+ }
+ for (const e of want) if (!got.has(e)) { fail(name, c, tick, `missing ${e}`); return; }
+ }
+ }
+}
+function fail(name, c, tick, why) {
+ process.stderr.write(`arm ${name}, connection ${c}, sample ${tick}: ${why}\n`);
+ process.exit(1);
+}
+
+for (let t = 0; t < WARMUP; t++) sample(t, false);
+for (const a of Object.values(arms)) { a.recomputes = 0; a.queryNs = 0n; a.taxNs = 0n; }
+bump = 0;
+
+for (let t = 0; t < MEASURE; t++) {
+ sample(WARMUP + t, true);
+ if (t >= MEASURE - AUDIT) audit(WARMUP + t);
+}
+
+const per = (v) => Number(v) / 1000 / MEASURE;
+process.stdout.write(`${JSON.stringify({
+ scenario: SCENARIO, entities: ENTITIES, connections: CONNECTIONS,
+ visible: VISIBLE, movement: MOVEMENT, cluster: CLUSTER, samples: MEASURE,
+ cellRevBumpsPerSample: bump / MEASURE,
+ distinctCellsTouchedPerSample: distinctTouched / MEASURE,
+ cellsInWorld: cellRev.size,
+ footprintCells: 27,
+ arms: Object.fromEntries(Object.entries(arms).map(([k, a]) => [k, {
+ recomputesPerSample: a.recomputes / MEASURE,
+ recomputesPerConnection: a.recomputes / MEASURE / CONNECTIONS,
+ queryUsPerSample: per(a.queryNs),
+ taxUsPerSample: per(a.taxNs),
+ totalUsPerSample: per(a.queryNs + a.taxNs),
+ }])),
+ ...sdkIdentity(ROOT),
+})}\n`);