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.

feat(bench): does the place get ready before it is wanted, and a falsifier

esengine1aacdbaa394c
diff --git a/bench/residency/README.md b/bench/residency/README.md
index a20cfb6a8..9472799b5 100644
--- a/bench/residency/README.md
+++ b/bench/residency/README.md
@@ -1,14 +1,21 @@
-# World residency at scale — what a streamed world costs to hold
+# World residency at scale — what a streamed world costs to hold, and to deliver
-`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 benches over one subject. `run.mjs` asks what holding a streamed world
+costs. `heavy.mjs` asks whether any single arrival is too big to swallow.
+`prefetch.mjs` asks the question those two left behind: **does the place get
+ready before the player wants it?**
-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.
+All three drive the real thing — cells arrive over the network into the same
+scene lifecycle a game uses — so every number includes what a player would
+actually wait through.
-## Measured 2026-09-05 (M-series Mac, WebGL2, 640×360, 300 frames per level)
+## Holding — `node bench/residency/run.mjs`
+
+Generates a 10×10 world of 600-unit cells with 20 colliding props each and takes
+three residencies from one source, chosen by radius: its own cell, its 3×3
+neighbourhood, its 5×5. 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
@@ -17,12 +24,9 @@ neighbourhood, its 5×5 — and the game turns the knob, not the driver.
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.
+**`arrive` is wall time around a settle poll, not a hitch.** It is how long the
+driver waited for residency to finish, and the frames underneath it are cheap —
+see the heavy cell below for what an arrival actually costs the main thread.
**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.
@@ -36,13 +40,6 @@ count of cells does not appear in it.
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.
-
## The heavy cell — is there an arrival nobody can split?
`node bench/residency/heavy.mjs` builds ONE deliberately heavy cell out of the
@@ -50,32 +47,161 @@ third-person sample's own imported assets — a skinned character with an animat
forty imported props at three levels of detail, two hundred physics bodies, 249
entities — and reads two instruments rather than a stopwatch: the per-cell PHASES
of the load, which run between frames and land on no system timer, and the
-per-frame cost of the frames it arrives on.
+per-frame, per-system cost of the frames it arrives on.
-### Measured 2026-09-05 (M-series Mac, WebGL2, 640×360, cold)
+The phases split by which HALF of delivery owns them, and that split is the whole
+point:
+
+| half | phases | when it can run |
+| --- | --- | --- |
+| **preparation** | `fetch`, `prefab`, `assets` | any time before demand — this is what prefetch hides |
+| **publication** | `spawn` | at the door, however early the readying happened |
+
+### Measured 2026-09-05 (M-series Mac, WebGL2, 640×360, cold, two runs)
```
-preparation (between frames, each phase atomic on the main thread):
- spawn 7.00 ms ← the largest atomic phase there is
- assets 6.20 ms
- fetch 4.70 ms
- delivery 19.00 ms issue → resident
+preparation (hideable) fetch 2.9 – 3.3 ms
+ assets 4.6 – 7.4 ms
+ = total 7.9 – 10.3 ms
+
+publication (always paid) spawn 5.9 – 6.4 ms
-the frame it arrives on: 3.50 ms
+delivery, issue → resident 15.2 – 17.3 ms
+
+the frame it arrives on 2.8 – 8.4 ms
+ on the expensive run, by system: RenderSystem 6.2, System_2 0.9,
+ AnimatorSystem 0.8, NavAgentSystem 0.2
```
**There is no unsplittable main-thread phase worth budgeting.** The largest is
-7 ms of ECS materialization for 249 entities including 200 bodies, and the frame
-the cell lands on costs 3.5 ms. A scheduler that sliced this would be buying
-complexity against a cost that is already inside a frame.
-
-**What IS worth hiding is the 19 ms of delivery.** Nineteen milliseconds is a
-player walking into a place that is not there yet for a dozen frames — and every
-part of it (fetch, asset acquisition, spawning) can happen before they arrive.
-That is the case for prefetch, and it is a latency argument, not a hitch one.
-
-One thing this cannot say: the arrival frame's 3.5 ms is a total, not a split
-between physics registration, render registration and animation. The per-system
-breakdown the driver asks for comes back empty here — the frame costs are
-engaged but not filled by the time the profile reads them. The verdict does not
-rest on it: a 3.5 ms frame cannot hide a 15 ms phase.
+about 6 ms of ECS materialization for 249 entities including 200 bodies, and the
+frame the cell lands on costs 2.8–8.4 ms — the spread is whether the render side's
+registration and upload land on that frame or the next. A scheduler that sliced
+this would be buying complexity against a cost already inside a frame.
+
+**What IS worth hiding is the ~8–10 ms of preparation**, and unlike the arrival
+frame it is not bounded by anything: it is fetch and decode, so it grows with the
+CDN, the content, and how busy the main thread already is. That is the case for
+prefetch, and it is a latency argument, not a hitch one.
+
+## Prefetch effectiveness — did it get ready in time?
+
+`node bench/residency/prefetch.mjs` builds a corridor of 16 identical cells
+(40 imported props + 160 bodies each) and drives it three times, cold each time,
+with the source moving itself so the harness never decides when demand arrives:
+
+| scenario | what it does | what it should find |
+| --- | --- | --- |
+| **approach** | walks in at 600 wu/s | the cell already `prepared` |
+| **teleport** | appears in a cell nobody was near | nothing ready; pays preparation itself |
+| **no-prefetch** | the same walk, `prefetchRadius` cut to `loadRadius` | nothing ready — the bench's own falsifier |
+
+A hit is decided **the instant a cell first enters the desired set**, by what
+demand finds there. A preparation still in flight is a *miss*, however it ends:
+"it was prepared by the time we published it" is true of every cell that ever
+loads, and the player waited for it either way.
+
+### Measured 2026-09-05 (M-series Mac, WebGL2, 640×360; load 200 / prefetch 1200 / unload 1300 wu)
+
+Three runs. The counts below were **identical in all three**; the milliseconds
+move about ±30%, which is what wall time on a shared machine does.
+
+```
+ scenario requested hits misses cancelled still ready hit rate
+ approach 11 9 0 0 2 100%
+ teleport 10 0 6 8 2 0%
+ no-prefetch 0 0 9 0 0 0%
+
+ scenario arrivals loadRadius→resident prepared dwell preparation publication
+ p50 p95 p50 p95 (median) (median)
+ approach 9 2.9 5.1 878.5 2297.3 2.4 2.9
+ teleport 6 6.3 18.2 — — 3.4 3.4
+ no-prefetch 9 5.1 53.6 — — 2.3 2.8
+```
+
+**A hit costs publication and nothing else.** 2.9 ms at p50 against 2.9 ms of
+measured publication — the fetching and decoding are simply not in the number,
+and the approach run's slowest arrival (5.1 ms) is still under the teleport run's
+median.
+
+**A miss carries the preparation into the wait, and the tail is where it hurts.**
+Both miss scenarios reach a p95 of 18–54 ms against the approach's 5.1, and the
+worst arrival is always a late one — preparation is measured as *latency*, since
+it awaits network and decode across frames, so it degrades as the corridor fills
+up and those frames get busier. Prefetch does not care: it stays at 2.9 ms from
+the first cell to the ninth.
+
+**The cleanest pairing is the one cold cell.** Every run boots with an empty
+cache, so `cell_0_0` is the only cell whose assets nothing had acquired yet — the
+same content, the same fetch, the same decode in all three runs:
+
+```
+ approach preparation 15.1 ms hidden behind a dwell of 471 ms → the player waited 5.1 ms
+ teleport preparation 12.8 ms paid at the door → the player waited 18.2 ms
+ no-prefetch preparation 14.5 ms paid at the door → the player waited 20.4 ms
+```
+
+Same cell, same content, same publication. The only difference is whether
+preparation happened before demand.
+
+### The falsifier, and what it is worth
+
+`no-prefetch` is not a separate feature path — it is the same walk with
+speculation reaching no further than demand. It collapses from 9 hits to 0. If it
+ever does not, the approach row was never measuring prefetch, and this bench
+should be believed about nothing.
+
+### What the dwell says
+
+`prepared dwell` is how long readiness sat before anything wanted it: 0.9 s at
+p50, 2.3 s at p95, against a preparation that takes 2–17 ms. Readiness waits
+**two to three orders of magnitude longer than it took to produce**, and two
+speculations were still unclaimed when the walk ended. The radius is generous,
+and the teleport run's 8 cancellations are what generosity costs when a source
+does something unexpected.
+
+That is the data a later cut would use to argue for velocity prediction, an
+adaptive radius, or a memory budget. **None of them are being built now** — the
+hit rate is 100% on the motion prefetch exists for, and the waste is bounded by
+the radius.
+
+Two caveats on reading these numbers. The dwell is harness wall time, and this
+harness steps frames as fast as it can rather than at 60 Hz, so it understates
+the game-time lead — which by construction is `(1200 − 200) / 600 = 1.67 s` of
+walking. And the corridor's 16 cells share three rock meshes, so only the first
+cell of a run pays a real `assets` phase; the rest are fetch-and-spawn. The
+cold-cell block above is where a whole preparation is on show.
+
+### An authoring rule the measurement forced
+
+`prefetchRadius` must not exceed `unloadRadius`. The streamer knows how far a
+source is and never which way it is going, so a cell that leaves the unload band
+while still inside the prefetch radius is speculated about again the instant it
+goes — walking away from a place fetches it a second time. Held to in
+`sdk/tests/world-residency.test.ts`, both directions.
+
+## Streaming Delivery v1 — frozen
+
+What the three benches together establish:
+
+- **Residency** decides what should exist, and deciding is free (6.3 µs per 100
+ cells, below the noise floor).
+- **Delivery** readies content before demand, and it works: 100% hit rate on
+ ordinary movement, 0% when speculation is disabled, and a hit costs publication
+ alone.
+- **Publication** is the only cost demand cannot escape: ~6 ms of spawn for a
+ 249-entity cell, landing on a 2.8–8.4 ms frame. Nothing here needs a budget
+ scheduler.
+- **Cancellation** gives back what speculation acquired, receipts included.
+
+Not in v1, deliberately: velocity prediction, adaptive prefetch radius, memory
+budget, priority scheduling. Each of them now has a number that would justify it,
+and none of them has one yet.
+
+### Instrumentation
+
+The earlier note here said the per-system breakdown of an arrival frame "comes
+back empty". That was the driver's probe and not the profiler: `costs()` called
+`enableStats()` on every read, which swapped the maps the frame had just filled,
+so the engine reported costing nothing. Engaging once fixed it, and the
+breakdowns above are real. No profiler lifecycle was changed.
diff --git a/bench/residency/prefetch.mjs b/bench/residency/prefetch.mjs
new file mode 100644
index 000000000..737e202c3
--- /dev/null
+++ b/bench/residency/prefetch.mjs
@@ -0,0 +1,383 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file bench/residency/prefetch.mjs — did the place get ready before it was wanted?
+ *
+ * The heavy-cell profile settled what an arrival COSTS and found nothing worth a
+ * budget scheduler. That moved the question: what delivery claims now is not
+ * that publication got cheaper but that fetching and decoding happen before the
+ * player needs the place. So the number that decides whether it works is not a
+ * duration at all — it is how often demand finds readiness already there.
+ *
+ * Two runs over the same corridor of identical cells, cold each time:
+ *
+ * approach a source walks in, so speculation has the lead time it was
+ * designed for → demand should find the cell PREPARED
+ * teleport a source appears in a cell it was never near
+ * → demand finds nothing, and pays the
+ * preparation itself
+ *
+ * and a third that is this bench's own falsifier: the same walk with prefetch
+ * turned down to the load radius. If the approach row does not collapse into the
+ * teleport row, the approach row was never measuring prefetch.
+ *
+ * node bench/residency/prefetch.mjs
+ * node bench/residency/prefetch.mjs --props 60 --bodies 240 heavier cells
+ */
+import { spawnSync } from 'node:child_process';
+import { rmSync, mkdirSync, writeFileSync, cpSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { runElectron } from '../../tools/lib/electronRun.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const WORK = path.join(ROOT, '.golden', 'bench-prefetch');
+const LAUNCHER = path.join(ROOT, 'tools', 'launchers', 'residency-run.mjs');
+const SAMPLE = path.join(ROOT, 'examples', 'third-person-3d', 'assets', 'models');
+
+const flag = (name, fallback) => {
+ const at = process.argv.indexOf(`--${name}`);
+ return at >= 0 && process.argv[at + 1] ? process.argv[at + 1] : fallback;
+};
+
+const CELL = 600;
+const COLUMNS = 16;
+const PROPS = Number(flag('props', '40'));
+const BODIES = Number(flag('bodies', '160'));
+
+/**
+ * The radii every scenario runs at.
+ *
+ * `unload` is deliberately NOT below `prefetch`: a cell given up while still
+ * inside the prefetch radius is speculated about again the moment it goes, and
+ * the walk would be measuring its own churn.
+ */
+const LOAD = 200;
+const PREFETCH = 1200;
+const UNLOAD = 1300;
+const SPEED = 600;
+
+/** Where a teleporting source lands: cell centres far enough apart that the next
+ * one was never inside the prefetch radius of the last. */
+const STOPS = [0, 3, 6, 9, 12, 15].map((c) => c * CELL + CELL / 2);
+
+function project(dir) {
+ rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+ mkdirSync(path.join(dir, 'assets', 'scenes'), { recursive: true });
+ mkdirSync(path.join(dir, 'src'), { recursive: true });
+ // The sample's own imported products: a cell's preparation is only worth
+ // hiding if it is decoding real meshes and materials.
+ cpSync(SAMPLE, path.join(dir, 'assets', 'models'), { recursive: true });
+
+ const entities = [];
+ const transform = (x, y, z, s = 1) => ({
+ type: 'Transform',
+ data: { position: { x, y, z }, scale: { x: s, y: s, z: s } },
+ });
+ const solid = (h) => ([
+ { type: 'RigidBody3D', data: { bodyType: 0 } },
+ { type: 'BoxCollider3D', data: { halfExtents: { x: h, y: h, z: h }, friction: 0.6 } },
+ ]);
+ const push = (id, name, components, parent = null) =>
+ entities.push({ id, name, parent, children: [], visible: true, components });
+
+ push(0, 'World', [transform(0, 0, 0),
+ { type: 'StreamedWorld', data: { cellSize: CELL } }]);
+ push(1, 'Camera', [transform(0, 1200, 1800),
+ { type: 'Camera', data: { projectionType: 0, fov: 55, nearPlane: 10, farPlane: 20000,
+ isActive: true, priority: 0 } },
+ { type: 'WorldPersistent', data: {} }]);
+ push(2, 'Sun', [{ type: 'Transform', data: { position: { x: 0, y: 0, z: 0 },
+ rotation: { w: 0.834, x: -0.521, y: 0.182, z: 0 } } },
+ { type: 'Light', data: { type: 1, intensity: 1.05, enabled: true,
+ color: { r: 1, g: 0.96, b: 0.9, a: 1 } } },
+ { type: 'WorldPersistent', data: {} }]);
+ // Parked a whole prefetch radius short of the first cell, so the run begins
+ // with nothing speculated about and the first arrival is a real one.
+ push(3, 'Source', [transform(-(PREFETCH + 200), 60, CELL / 2),
+ { type: 'WorldStreamingSource',
+ data: { prefetchRadius: 0, loadRadius: 0, unloadRadius: 0, enabled: false } },
+ { type: 'WorldPersistent', data: {} }]);
+
+ const LEVELS = ['rock-lod0', 'rock-lod1', 'rock-lod2'];
+ let id = 100;
+ for (let cx = 0; cx < COLUMNS; cx++) {
+ // Identical cell to cell, so "the same content arrived" is a fact about
+ // the fixture and not a hope about the cook.
+ for (let n = 0; n < PROPS; n++) {
+ push(id++, `Rock_${cx}_${n}`, [
+ transform(cx * CELL + 20 + (n % 8) * 22, 30, 20 + Math.floor(n / 8) * 22, 1),
+ { type: 'MeshRenderer', data: { mesh: `assets/models/${LEVELS[n % 3]}.esmesh`,
+ lit: true, opaque: true, color: { r: 0.5, g: 0.5, b: 0.45, a: 1 } } },
+ { type: 'LODGroup', data: { lod1: 'assets/models/rock-lod1.esmesh',
+ lod2: 'assets/models/rock-lod2.esmesh',
+ lod1Size: 0.25, lod2Size: 0.11, cullSize: 0.02, hysteresis: 0.1 } }]);
+ }
+ for (let n = 0; n < BODIES; n++) {
+ push(id++, `Body_${cx}_${n}`, [
+ transform(cx * CELL + 10 + (n % 20) * 9, 30, 300 + Math.floor(n / 20) * 9, 0.2),
+ { type: 'MeshRenderer', data: { mesh: 'builtin:cube', lit: true, opaque: true,
+ cullBackfaces: true, color: { r: 0.6, g: 0.55, b: 0.45, a: 1 } } },
+ ...solid(10)]);
+ }
+ }
+
+ writeFileSync(path.join(dir, 'assets', 'scenes', 'main.esscene'),
+ JSON.stringify({ version: 4, name: 'main', entities }, null, 1) + '\n');
+ writeFileSync(path.join(dir, 'assets', 'scenes', 'main.esscene.meta'),
+ JSON.stringify({ uuid: randomUUID(), version: '2.0', type: 'scene', importer: {} }) + '\n');
+ writeFileSync(path.join(dir, 'project.esproject'), JSON.stringify({
+ formatVersion: '1', name: 'Prefetch Bench', description: 'A corridor of identical cells.',
+ tag: '3D', version: '0.1.0', defaultScene: 'assets/scenes/main.esscene',
+ designResolution: { width: 640, height: 360 }, spineVersion: 'none',
+ }, null, 2) + '\n');
+ // The source moves itself, at a fixed step, because the driver may not: a
+ // harness that placed the source would be choosing when demand arrives, and
+ // that is the entire quantity under measurement.
+ writeFileSync(path.join(dir, 'src', 'main.ts'), `
+import { addSystemToSchedule, Schedule, defineSystem, GetWorld, Res, Input, Transform, WorldStreamingSource } from 'esengine';
+import type { World, InputState } from 'esengine';
+
+const STEP = ${SPEED} / 60;
+const STOPS = ${JSON.stringify(STOPS)};
+const DWELL = 90;
+
+let mode: '' | 'walk' | 'teleport' = '';
+let ran = 0;
+
+const driveSystem = defineSystem(
+ [Res(Input), GetWorld()],
+ (input: InputState, world: World) => {
+ const source = world.findEntityByName('Source');
+ if (source === null) return;
+ const begin = (next: 'walk' | 'teleport', prefetch: number) => {
+ if (mode !== '') return;
+ mode = next;
+ ran = 0;
+ world.update(source, WorldStreamingSource, (s) => {
+ s.prefetchRadius = prefetch;
+ s.loadRadius = ${LOAD};
+ s.unloadRadius = ${UNLOAD};
+ s.enabled = true;
+ });
+ };
+ if (input.isKeyPressed('Digit1')) begin('walk', ${PREFETCH});
+ if (input.isKeyPressed('Digit2')) begin('teleport', ${PREFETCH});
+ // Speculation reaching no further than demand: the same walk with
+ // nothing able to run ahead of it.
+ if (input.isKeyPressed('Digit3')) begin('walk', ${LOAD});
+ if (mode === 'walk') {
+ world.update(source, Transform, (t) => { t.position.x += STEP; });
+ } else if (mode === 'teleport') {
+ const stop = STOPS[Math.min(Math.floor(ran / DWELL), STOPS.length - 1)];
+ world.update(source, Transform, (t) => { t.position.x = stop; });
+ }
+ if (mode !== '') ran++;
+ },
+ { name: 'PrefetchDriveSystem' },
+);
+addSystemToSchedule(Schedule.Update, driveSystem);
+`);
+ writeFileSync(path.join(dir, 'tsconfig.json'), JSON.stringify({
+ compilerOptions: {
+ target: 'ES2020', module: 'ESNext', moduleResolution: 'bundler', strict: true,
+ esModuleInterop: true, skipLibCheck: true, noEmit: true,
+ paths: { esengine: ['./.esengine/sdk/index.d.ts'] },
+ },
+ include: ['src/**/*'],
+ }, null, 2) + '\n');
+ return dir;
+}
+
+/** Frames enough to walk the corridor's first seven cells, and to make every stop. */
+const WALK_FRAMES = Math.ceil(((COLUMNS / 2) * CELL + PREFETCH + 200) / SPEED * 60);
+const STOP_FRAMES = STOPS.length * 90 + 60;
+
+function drive(dir, name, steps) {
+ const script = path.join(WORK, `${name}.json`);
+ writeFileSync(script, JSON.stringify(steps, null, 2));
+ // A fresh Electron per scenario: the launcher clears the HTTP cache at boot,
+ // so each run pays for its own fetching. Two scenarios in one process would
+ // hand the second a warmed cache and call the difference prefetch.
+ const run = runElectron([LAUNCHER, '--dir', dir, '--script', script, '--w', '640', '--h', '360'],
+ { encoding: 'utf8', cwd: ROOT });
+ for (const line of (run.stdout || '').split('\n')) {
+ const at = line.indexOf('stream ');
+ if (at < 0) continue;
+ try { return JSON.parse(line.slice(line.indexOf('{', at))); } catch { /* partial line */ }
+ }
+ console.error(`✗ ${name}: nothing was measured — ${(run.stdout || run.stderr || '').slice(-600)}`);
+ process.exit(2);
+}
+
+const percentile = (values, p) => {
+ if (values.length === 0) return NaN;
+ const sorted = [...values].sort((a, b) => a - b);
+ return sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
+};
+const ms = (v) => (Number.isNaN(v) ? '—' : `${v.toFixed(1)}`);
+
+/** The arrivals a scenario produced, one row per cell that was actually asked for. */
+function arrivals(streaming) {
+ const rows = [];
+ for (const [cell, d] of Object.entries(streaming.delivery ?? {})) {
+ if (d.outcome === '' || d.demandToResidentMs <= 0) continue;
+ rows.push({
+ cell,
+ outcome: d.outcome,
+ latency: d.demandToResidentMs,
+ prepare: d.prepareMs,
+ publish: d.publishMs,
+ dwell: d.dwellMs,
+ fetch: d.phases?.fetch ?? 0,
+ assets: d.phases?.assets ?? 0,
+ spawn: d.phases?.spawn ?? 0,
+ });
+ }
+ // In corridor order, so the first (cold) arrival is visibly the first.
+ return rows.sort((a, b) => Number(a.cell.match(/\d+/g).at(-2)) - Number(b.cell.match(/\d+/g).at(-2)));
+}
+
+function summarise(streaming) {
+ const rows = arrivals(streaming);
+ const latency = rows.map((r) => r.latency);
+ const hits = rows.filter((r) => r.outcome === 'hit');
+ const asked = streaming.prefetchHits + streaming.prefetchMisses;
+ return {
+ rows,
+ requested: streaming.prefetchRequests,
+ stillReady: streaming.preparedCells.length,
+ hits: streaming.prefetchHits,
+ misses: streaming.prefetchMisses,
+ cancelled: streaming.cancelCount,
+ hitRate: asked === 0 ? NaN : streaming.prefetchHits / asked,
+ latency50: percentile(latency, 0.5),
+ latency95: percentile(latency, 0.95),
+ dwell50: percentile(hits.map((r) => r.dwell), 0.5),
+ dwell95: percentile(hits.map((r) => r.dwell), 0.95),
+ prepare: percentile(rows.map((r) => r.prepare), 0.5),
+ publish: percentile(rows.map((r) => r.publish), 0.5),
+ fetch: percentile(rows.map((r) => r.fetch), 0.5),
+ assets: percentile(rows.map((r) => r.assets), 0.5),
+ spawn: percentile(rows.map((r) => r.spawn), 0.5),
+ };
+}
+
+function main() {
+ if (!existsSync(SAMPLE)) {
+ console.error(`✗ the sample's imported assets are not here: ${SAMPLE}`);
+ process.exit(2);
+ }
+ rmSync(WORK, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+ mkdirSync(WORK, { recursive: true });
+ const src = project(path.join(WORK, 'src'));
+ const out = path.join(WORK, 'web');
+ const built = spawnSync(process.execPath, [
+ path.join(ROOT, 'pipeline', 'bin', 'estella.mjs'), 'export', src,
+ '--platform', 'web', '--out', out,
+ ], { encoding: 'utf8', cwd: ROOT });
+ if (built.status !== 0) {
+ console.error(`✗ the corridor did not package:\n${(built.stderr || built.stdout || '').slice(-900)}`);
+ process.exit(2);
+ }
+
+ const scenarios = [
+ ['approach', { do: 'stream', as: 'approach', key: 'Digit1', count: WALK_FRAMES }],
+ ['teleport', { do: 'stream', as: 'teleport', key: 'Digit2', count: STOP_FRAMES }],
+ ['no-prefetch', { do: 'stream', as: 'noPrefetch', key: 'Digit3', count: WALK_FRAMES }],
+ ];
+ const measured = new Map();
+ for (const [name, step] of scenarios) {
+ measured.set(name, summarise(drive(out, name, [{ do: 'step', frames: 30 }, step])));
+ }
+
+ console.log(`\nprefetch effectiveness — ${COLUMNS} identical cells, `
+ + `${PROPS} imported props + ${BODIES} bodies each, cell ${CELL} wu`);
+ console.log(` load ${LOAD} / prefetch ${PREFETCH} / unload ${UNLOAD} wu, walking ${SPEED} wu/s\n`);
+
+ console.log(' scenario requested hits misses cancelled still ready hit rate');
+ for (const [name, s] of measured) {
+ console.log(` ${name.padEnd(13)} ${String(s.requested).padStart(9)}`
+ + ` ${String(s.hits).padStart(4)} ${String(s.misses).padStart(6)}`
+ + ` ${String(s.cancelled).padStart(9)} ${String(s.stillReady).padStart(11)}`
+ + ` ${(Number.isNaN(s.hitRate) ? '—' : `${(s.hitRate * 100).toFixed(0)}%`).padStart(8)}`);
+ }
+ console.log(' (a speculation is requested once, then hit, cancelled, or still waiting.)');
+
+ console.log(`\n what the player waits through, milliseconds`
+ + ` (dwell is wall time; the designed lead is`
+ + ` ${((PREFETCH - LOAD) / SPEED).toFixed(2)} s of walking):`);
+ console.log(' scenario arrivals loadRadius→resident prepared dwell preparation publication');
+ console.log(' p50 p95 p50 p95 (median) (median)');
+ for (const [name, s] of measured) {
+ console.log(` ${name.padEnd(13)} ${String(s.rows.length).padStart(8)}`
+ + ` ${ms(s.latency50).padStart(9)} ${ms(s.latency95).padStart(7)}`
+ + ` ${ms(s.dwell50).padStart(9)} ${ms(s.dwell95).padStart(7)}`
+ + ` ${ms(s.prepare).padStart(11)} ${ms(s.publish).padStart(11)}`);
+ }
+
+ console.log('\n and where a preparation goes (median): '
+ + [...measured].map(([name, s]) =>
+ `${name} fetch ${ms(s.fetch)} + assets ${ms(s.assets)} → spawn ${ms(s.spawn)}`).join('\n'
+ + ' '));
+
+ console.log('\n every arrival, in corridor order:');
+ for (const [name, s] of measured) {
+ console.log(` ${name}`);
+ for (const r of s.rows) {
+ console.log(` ${r.cell.padEnd(12)} ${r.outcome.padEnd(5)}`
+ + ` demand→resident ${ms(r.latency).padStart(6)}`
+ + ` prepare ${ms(r.prepare).padStart(6)} publish ${ms(r.publish).padStart(6)}`
+ + ` dwell ${ms(r.dwell).padStart(7)}`);
+ }
+ }
+
+ // The corridor's cells share their rock meshes, so only the first one of a
+ // cold run pays a real `assets` phase — which makes this row the one place
+ // a whole preparation is on show.
+ const cold = (name) => measured.get(name).rows.find((r) => r.cell.endsWith('cell_0_0'));
+ console.log('\n the one cold cell each run pays for — same content, same fetch, same assets:');
+ for (const name of ['approach', 'teleport', 'no-prefetch']) {
+ const r = cold(name);
+ if (!r) continue;
+ console.log(` ${name.padEnd(13)} preparation ${ms(r.prepare).padStart(6)} ms`
+ + ` ${r.outcome === 'hit' ? 'hidden behind a dwell of ' + ms(r.dwell) + ' ms' : 'paid at the door'}`
+ + ` → the player waited ${ms(r.latency)} ms`);
+ }
+
+ const approach = measured.get('approach');
+ const teleport = measured.get('teleport');
+ const sabotage = measured.get('no-prefetch');
+ const checks = [
+ [approach.hits > 0 && approach.hitRate >= 0.8,
+ 'walking in finds the place already prepared',
+ `${approach.hits}/${approach.hits + approach.misses} arrivals hit`],
+ [teleport.misses > 0 && teleport.hits === 0,
+ 'appearing in a place nobody was near finds nothing ready',
+ `${teleport.misses} miss(es), ${teleport.hits} hit(s)`],
+ [approach.latency50 < teleport.latency50,
+ 'and a hit is the shorter wait of the two',
+ `${ms(approach.latency50)} ms vs ${ms(teleport.latency50)} ms at p50`],
+ [approach.latency50 <= approach.publish * 1.6 + 1,
+ 'a hit costs about what publishing costs, and no preparation',
+ `${ms(approach.latency50)} ms against ${ms(approach.publish)} ms of publication`],
+ [teleport.latency50 >= teleport.prepare + teleport.publish * 0.8,
+ 'a miss carries the preparation into the wait',
+ `${ms(teleport.latency50)} ms against ${ms(teleport.prepare)} + ${ms(teleport.publish)} ms`],
+ [sabotage.hits === 0,
+ 'and with speculation reaching no further than demand, the same walk hits nothing',
+ `${sabotage.hits} hit(s), ${sabotage.misses} miss(es)`],
+ ];
+ console.log('');
+ let failed = 0;
+ for (const [ok, claim, detail] of checks) {
+ if (!ok) failed++;
+ console.log(` ${ok ? '✓' : '✗'} ${claim}${detail ? ` — ${detail}` : ''}`);
+ }
+ console.log('');
+ process.exit(failed === 0 ? 0 : 1);
+}
+
+main();
diff --git a/tools/launchers/residency-run.mjs b/tools/launchers/residency-run.mjs
index b89406fea..a21c55f6d 100644
--- a/tools/launchers/residency-run.mjs
+++ b/tools/launchers/residency-run.mjs
@@ -19,7 +19,8 @@
* --log <regex> also print console lines matching this
*
* A script is a list of steps: {do:"read",as}, {do:"walkTo",x,z},
- * {do:"tap",key}, {do:"step",frames}. Each read prints one JSON line.
+ * {do:"tap",key}, {do:"step",frames}, {do:"stream",as,key,count}. Each read
+ * prints one JSON line.
*/
import { app, BrowserWindow } from 'electron';
import http from 'node:http';
@@ -280,6 +281,31 @@ async function main() {
console.log(`delivery ${step.as}: ${JSON.stringify(delivery)}`);
continue;
}
+ if (step.do === 'stream') {
+ // One frame at a time with a macrotask turn between them: `step(n)` drains
+ // only MICROtasks, and a cell arrives over the network, so a held key
+ // profiles a walk whose loads never land.
+ await exec(`(async () => {
+ const target = document.querySelector('canvas') ?? window;
+ const send = (type, code) => {
+ const e = new KeyboardEvent(type, { code, key: code, bubbles: true, cancelable: true });
+ target.dispatchEvent(e);
+ if (target !== window) window.dispatchEvent(new KeyboardEvent(type, { code, key: code, bubbles: true }));
+ };
+ ${step.key ? `send('keydown', ${JSON.stringify(step.key)});` : ''}
+ for (let i = 0; i < ${step.count ?? 300}; i++) {
+ await window.__estellaCooked.step(1, 1 / 60);
+ ${step.key ? `if (i === 0) send('keyup', ${JSON.stringify(step.key)});` : ''}
+ await new Promise((settle) => setTimeout(settle, 0));
+ }
+ return true;
+ })()`);
+ // Settled after, not during: a cell still in flight when the frames run out
+ // has no delivery to report, and reading it then would publish a zero.
+ await settle();
+ console.log(`stream ${step.as}: ${JSON.stringify(await exec('window.__estellaCooked.streaming()'))}`);
+ continue;
+ }
if (step.do === 'time') {
// Wall time for a batch of engine frames, with the clock already handed
// over: what a held world costs per frame, rather than what the runner had