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
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.mdindex 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 itsbodies 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 everysource 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 animatforty imported props at three levels of detail, two hundred physics bodies, 249entities — and reads two instruments rather than a stopwatch: the per-cell PHASESof 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.mjsnew file mode 100644index 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.mjsindex 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