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.

perf(residency): what a streamed world costs to hold, and how big the hitch is

esengine21c4e2bcf32a
diff --git a/bench/residency/README.md b/bench/residency/README.md
new file mode 100644
index 000000000..49931abc9
--- /dev/null
+++ b/bench/residency/README.md
@@ -0,0 +1,44 @@
+# World residency at scale — what a streamed world costs to hold
+
+`node bench/residency/run.mjs` generates a 10×10 world of 600-unit cells with 20
+colliding props each, packages it, and drives the real thing: cells arrive over
+the network into the same scene lifecycle a game uses, so every number here
+includes what a player would actually wait through.
+
+Three residencies come from one source, chosen by radius — its own cell, its 3×3
+neighbourhood, its 5×5 — and the game turns the knob, not the driver.
+
+## Measured 2026-09-05 (M-series Mac, WebGL2, 640×360, 300 frames per level)
+
+```
+ level cells entities renderers bodies refs hold/frame arrive leave
+ 1 1 20 20 20 1 0.13 ms 28.91 ms 3.64 ms
+ 9 9 180 180 180 9 0.27 ms 37.65 ms 3.34 ms
+ 25 25 500 500 500 25 0.54 ms 35.69 ms 4.83 ms
+```
+
+**`arrive` is the hitch, and it is the number this exists to publish.** Bringing a
+place in costs tens of milliseconds — fetching the cell document, spawning its
+entities, handing its bodies to the physics world and acquiring its assets — and
+this version does none of that on a budget. Twenty-five cells arrive in about the
+same wall time as one because the loads are issued together and overlap; what
+does not overlap is the spawning, which is why 25 is not 25× of 1 either.
+
+**Leaving is cheap and flat**: 3–5 ms to destroy a cell's entities, drop its
+bodies and give back its receipts, whether that is one cell or twenty-five.
+
+**Holding is linear in content and not in cells**: 0.13 → 0.27 → 0.54 ms a frame
+across 20 → 180 → 500 props. That is the props being drawn and simulated; the
+count of cells does not appear in it.
+
+**Deciding does not show up at all.** The same world cut into 100 cells and into
+4, with nothing resident in either, differ by 6.3 µs a frame — below what this
+harness can separate from noise. Residency reconsiders every cell against every
+source each frame and, at a hundred cells, that is free.
+
+## What the numbers do not include
+
+There is no priority, no prefetch and no budget yet, so a large cell arriving is
+a hitch of its full size. `arrive` is measured over localhost: a real CDN adds
+its own latency on top of the spawning cost, and only the spawning half of these
+numbers is the engine's.
diff --git a/bench/residency/run.mjs b/bench/residency/run.mjs
index be0d5c2c2..61e3c5ccd 100755
--- a/bench/residency/run.mjs
+++ b/bench/residency/run.mjs
@@ -62,6 +62,12 @@ function project(dir, columns) {
data: { mesh: 'builtin:cube', lit: true, opaque: true, cullBackfaces: true,
color: { r, g, b, a: 1 } },
});
+ // Props collide, so what a cell costs to instantiate includes the bodies it
+ // hands to the physics world — the half a renderer count cannot show.
+ const solid = () => ([
+ { type: 'RigidBody3D', data: { bodyType: 0 } },
+ { type: 'BoxCollider3D', data: { halfExtents: { x: 25, y: 25, z: 25 }, friction: 0.6 } },
+ ]);
const push = (id, name, components, parent = null) =>
entities.push({ id, name, parent, children: [], visible: true, components });
@@ -89,7 +95,8 @@ function project(dir, columns) {
for (let n = 0; n < PROPS; n++) {
const x = cx * CELL + 40 + (n % 5) * 120;
const z = cz * CELL + 40 + Math.floor(n / 5) * 120;
- push(id++, `P_${cx}_${cz}_${n}`, [transform(x, 30, z, 0.5), box(0.6, 0.55, 0.45)]);
+ push(id++, `P_${cx}_${cz}_${n}`,
+ [transform(x, 30, z, 0.5), box(0.6, 0.55, 0.45), ...solid()]);
}
}
}
@@ -209,9 +216,14 @@ function main() {
// Nothing resident in either, so what differs is 96 cells' worth of deciding.
const wideIdle = held.idle.msPerFrame;
const narrowIdle = scan.idle.msPerFrame;
- console.log(`\n deciding: ${ms(wideIdle)}/frame over 100 cells vs ${ms(narrowIdle)} over 4`
- + ` → ${((wideIdle - narrowIdle) / 96 * 1000).toFixed(1)} µs per 100 cells scanned`);
- console.log(` (nothing is resident in either, so the difference is the scan and not the content)\n`);
+ const perCell = (wideIdle - narrowIdle) / 96 * 1000;
+ console.log(`\n deciding: ${ms(wideIdle)}/frame over 100 cells vs ${ms(narrowIdle)} over 4`);
+ // A difference at or below zero is the measurement's floor, not a saving —
+ // saying "-0.2 µs" would be reporting noise as a result.
+ console.log(perCell > 0.5
+ ? ` → ${perCell.toFixed(1)} µs per 100 cells scanned\n`
+ : ` → the scan over 96 more cells is below what this can measure`
+ + ` (the two differ by ${((wideIdle - narrowIdle) * 1000).toFixed(1)} µs a frame)\n`);
}
main();
diff --git a/tools/launchers/residency-run.mjs b/tools/launchers/residency-run.mjs
index 58bda5d0d..8a24c59ba 100644
--- a/tools/launchers/residency-run.mjs
+++ b/tools/launchers/residency-run.mjs
@@ -134,12 +134,15 @@ async function main() {
await win.loadURL(`http://127.0.0.1:${server.address().port}/?headless`);
const exec = (js) => win.webContents.executeJavaScript(js);
+ // Readiness is "a scene is up", not "a named entity is there": the handle
+ // appears before the first scene has spawned anything, and a name belongs to
+ // whichever world is being driven.
let ready = false;
for (let i = 0; i < 300 && !ready; i++) {
ready = await exec(`(() => {
const c = window.__estellaCooked;
if (!c || !c.streaming) return false;
- return !!c.probe(['Player']).at.Player;
+ return !!c.probe([]).scene;
})()`).catch(() => false);
if (!ready) await new Promise((r) => setTimeout(r, 100));
}
@@ -163,7 +166,9 @@ async function main() {
if (!s.streamed) return true;
if (s.loadingCells.length === 0 && s.unloadingCells.length === 0) return true;
await exec(holdScript([], 2));
- await new Promise((r) => setTimeout(r, 20));
+ // Tight at first: how long an arrival takes is a number worth measuring,
+ // and a poll that sleeps 20 ms can only ever report multiples of 20 ms.
+ if (i > 40) await new Promise((r) => setTimeout(r, 20));
}
console.log(' ! residency never settled');
return false;