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(residency): the readying is a named preparation phase, not a residual

esengined730382e6f81
diff --git a/bench/residency/README.md b/bench/residency/README.md
index 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 else
does — 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 called
from and nothing more; the evidence clears it. Moving 6 ms from the first visible
frame into the publication transaction would not be a fix either — a hitch
diff --git a/bench/residency/heavy.mjs b/bench/residency/heavy.mjs
index 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.ts
index 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.ts
index 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);