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
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.mdnew file mode 100644index 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.mjsindex 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.mjsindex 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;