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(residency): the readying is a named preparation phase, not a residual
esengined730382e6f81
diff --git a/bench/residency/README.md b/bench/residency/README.mdindex b8ee6c36d..08eb9aade 100644--- a/bench/residency/README.md+++ b/bench/residency/README.md@@ -499,6 +499,46 @@ one the player stands in, so a zero there is soundness rather than attribution.Attribution lives here, on a fixture whose cell needs a variant nothing elsedoes — which is why disconnecting readiness changes this number and not that one.+#### Remeasured on the shipping build, 2026-09-07++The table above was taken with the readying UNNAMED — the one phase this campaign+created was the one phase preparation had no name for, so its 6 ms showed only as+a residual and "the work moved into prefetch headroom" could be argued only from+publication not growing. Named, `issue → prepared` closes from 68.4% to 98.7%.++Three arms, three runs each, on a wasm built the way the product ships it+(`ES_ENABLE_TEST_PROBES=OFF`, so `engine_prewarmMeshVariants` is not in the binary+and no arm here can reach it — every number below is the production path):++| arm | readying | publication | first-visible | `programCompiles` | BUDGET |+| --- | --- | --- | --- | --- | --- |+| miss | 6.4–7.4 ms | 6.8–9.1 ms | 2.5–3.6 ms | 0 | ✓ 1.2–2.8 / 8.33 ms |+| hit | 6.5–6.9 ms | 7.4–7.6 ms | 3.0–3.2 ms | 0 | ✓ 2.0–2.4 / 8.33 ms |+| blind → published | 6.7–7.3 ms | 6.7–6.9 ms | 2.4–2.8 ms | 0 | ✓ 1.7–2.1 / 8.33 ms |+| blind → revealed | — | — | 0.9–2.9 ms | 0 | ✓ −0.2–1.8 / 8.33 ms |++`programCompiles` is zero in the arrival window AND across the whole run, on every+arm. The arrival frame's `collect` is 0.20 ms against a 0.10–0.20 ms steady state,+so first visibility does nothing a warm frame does not. `blind → published` draws+0 → 0: when it is revealed there is no other visible content that could have warmed+the cache for it.++The readying is timed around the CALL rather than the settle. It is synchronous+work behind an async signature, and waiting on the promise measures how busy the+thread was afterwards instead: on the miss arm that reported 52.5 ms for the same+6 ms of compile, and closed the accounting by absorbing the queue into a phase.++Two things this remeasure does not settle, both older than it:++- `hit`'s publication is witnessed by one instrument. The cross-check reads the+ frame profiler's `scene` domain, which carries 0.1 ms there against 7.5 ms of+ named phases, so the hit arm exits non-zero on that check and on that check+ alone. Publication on a hit lands in the residency system's own timer, not in+ `scene`; the witness has not been moved.+- `miss`'s `issue → prepared` is latency, not CPU, and varies 22–65 ms with what+ the fetch and the frame queue do. The named phases account for it when nothing+ stalls; a stalled run leaves the stall unnamed, which is what it is.+**Do not optimise `MeshPlugin::collect`.** It is where the lazy compile is calledfrom and nothing more; the evidence clears it. Moving 6 ms from the first visibleframe into the publication transaction would not be a fix either — a hitchdiff --git a/bench/residency/heavy.mjs b/bench/residency/heavy.mjsindex 4a9783c52..9a83c78fa 100755--- a/bench/residency/heavy.mjs+++ b/bench/residency/heavy.mjs@@ -666,7 +666,7 @@ function printTree(nodes, indent) {}/** Which half of delivery owns a root phase — the split prefetch turns on. */-const PREPARATION = new Set(['fetch', 'prefab', 'assets', 'discover', 'subsystems']);+const PREPARATION = new Set(['fetch', 'prefab', 'assets', 'discover', 'subsystems', 'readying']);const pct = (part, whole) => (whole > 0 ? `${((part / whole) * 100).toFixed(1)}%` : '—');diff --git a/sdk/src/residency/WorldStreamer.ts b/sdk/src/residency/WorldStreamer.tsindex f6376795a..1a81639ff 100644--- a/sdk/src/residency/WorldStreamer.ts+++ b/sdk/src/residency/WorldStreamer.ts@@ -479,10 +479,16 @@ export class WorldStreamer {private askReadiness_(name: string, ready: NonNullable<WorldStreamHost['readyRenderPrograms']>,): Promise<RenderReadiness> {+ // Timed around the CALL, not the settle: the readying is synchronous work+ // behind an async signature, so waiting on the promise measures how busy+ // the thread was afterwards — 6 ms of compile read as 52 on a busy arrival.+ const began = performance.now();try {return Promise.resolve(ready.call(this.host_, name));} catch (err) {return Promise.reject(err);+ } finally {+ this.recordPhase(name, 'readying', performance.now() - began);}}diff --git a/sdk/tests/world-residency.test.ts b/sdk/tests/world-residency.test.tsindex 90e71081b..95dff434a 100644--- a/sdk/tests/world-residency.test.ts+++ b/sdk/tests/world-residency.test.ts@@ -5,7 +5,7 @@* about it. The decision is pure and is held to on its own; the streamer* is held to the moves it issues, against a host that records them.*/-import { describe, it, expect } from 'vitest';+import { describe, it, expect, vi } from 'vitest';import {desiredResidency, distanceToCell, type WorldCell, type ResidencySource,} from '../src/residency/cells';@@ -219,6 +219,45 @@ describe('WorldStreamer', () => {expect(s.residencyOf('c_0_0')).toBe('preparing');});+ // The phase prefetch exists to hide: unnamed, it was 6 ms of preparation+ // nothing could account for. What it cost is the work, not the wait — a+ // promise nobody settles still readied.+ it('names what the readying cost, as the work rather than the wait', async () => {+ let clock = 0;+ const now = vi.spyOn(performance, 'now').mockImplementation(() => clock);+ try {+ const base = recordingHost(() => claim);+ const host: WorldStreamHost = {+ ...base.host,+ readyRenderPrograms() {+ clock += 7;+ return new Promise<RenderReadiness>(() => { /* never settles */ });+ },+ };+ const s = new WorldStreamer(host);+ s.loadManifest(manifest(cell(0, 0)));+ s.update([nearby()]);+ await flush();+ // Still owed — the claim never came back — and the cost is named.+ expect(s.residencyOf('c_0_0')).toBe('preparing');+ expect(s.delivery()['c_0_0']?.phases.readying).toBeCloseTo(7, 6);+ } finally {+ now.mockRestore();+ }+ });++ // No renderer is no obligation, so there is no phase — an absent cost and+ // a zero one are the same only if nothing was ever owed.+ it('names no readying where there was no renderer to ready', async () => {+ const { host } = recordingHost();+ const s = new WorldStreamer(host);+ s.loadManifest(manifest(cell(0, 0)));+ s.update([nearby()]);+ await flush();+ expect(s.residencyOf('c_0_0')).toBe('prepared');+ expect(s.delivery()['c_0_0']?.phases.readying).toBeUndefined();+ });+it('an unpaid claim is a debt the next progression retries', async () => {let answer: RenderReadiness = { applicable: true, stamp: null };const { host, calls } = recordingHost(() => answer);