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.

bench(residency): the compile is gone from first visibility, and it was the author

esengine5f8490aacc7a
diff --git a/bench/residency/README.md b/bench/residency/README.md
index b68fd34e7..b8ee6c36d 100644
--- a/bench/residency/README.md
+++ b/bench/residency/README.md
@@ -387,6 +387,8 @@ real measurement, which is the interesting part.
| ~~The later 9–15 ms spikes are the delayed arrival.~~ | They are `render.finalize`, a separate mechanism, and they carry no collect at all. | Scoping the spike frames rather than the window. |
| ~~GPU upload is not a cost this path has.~~ | GPU upload is not the author of the ARRIVAL frame. `render.finalize` — where `pool_.upload()` lives — is 9–15 ms elsewhere. | The same scoping; the first claim was true of one frame and stated of the path. |
| ~~The `costs()` probe was broken, so the old 3.5 ms arrival frames were a bad instrument's reading.~~ | The frame's wall time was always the driver's own clock around `step()`. The probe bug hid only the breakdown. | Reading what `f.ms` is actually measured by. |
+| ~~The first-visibility hitch is something a streaming design has to absorb.~~ | It was one cold shader-variant compile, and readiness moves it out of first visibility entirely. Streaming's own share was the publication transaction all along. | Production readiness disconnected: HIT first-visible 2.9 → 14.6 ms, one compile returns, BUDGET red. Reconnected: 0 compiles on every arm. |
+| ~~Readiness needs prefetch headroom to hide the compile, so a miss must pay it at first visibility.~~ | Publication itself owes the claim. A cell with no dwell readies inside the publication transaction, so first visibility is clean on the miss path too. | The `miss` arm: 0 compiles, first-visible 2.9 ms, publication 6.6 ms — unchanged from the disconnected control's 6.4 ms. |
## Streaming Delivery v1 — NOT frozen
@@ -432,6 +434,9 @@ share of the budget violation is the 6.4 ms, and the other half belongs to
shader-variant readiness. Both have to close before this freezes; they close
separately.
+**The shader half is now closed** — see below. Delivery's own 6.4 ms publication
+transaction is what remains, and it is the only thing still holding this open.
+
Deliberately still not built: velocity prediction, adaptive prefetch radius,
memory budget, priority scheduling. Each now has a number that would justify it.
None is the next thing to build.
@@ -445,17 +450,65 @@ realization, optimising a 2 ms one is choosing the second question. Both are
recorded here and left alone.
That cut is done, and it named the mechanism: one cold shader-variant compile.
-So the next one is **Shader Variant Readiness** — whether the variants
-already-prefetched content will need can be made ready before first visibility,
-rather than compiled at it. Not by precompiling everything: the question is
-whether the exact variant key is derivable at `prepared`, at `publish`, or only
-once a camera looks, because those three have different answers and only the
-first is free.
+The cut that followed it — **Shader Variant Readiness** — is complete, and the
+answer to "is the exact variant key derivable at `prepared`" turned out to be
+yes: a cell's own document names every requirement before a single entity of it
+exists.
+
+### Shader Variant Readiness — COMPLETE
+
+Three conclusions, each with a counterfactual behind it rather than a
+before-and-after:
+
+**Cold shader compilation was the author of the first-visibility mesh hitch.**
+Disconnecting production readiness brings the compile back and the hitch with
+it — HIT first-visible 2.9 → 14.6 ms, BLIND reveal 0.8 → 12.7 ms, one
+`programCompiles` in each, BUDGET red in both. Nothing else about the arrival
+changes.
+
+**Prepared cells satisfy shader-program readiness before publication, where the
+host has a renderer to satisfy it with.** `prepared` means every mandatory
+preparation obligation is paid, not just the assets; a host with no renderer
+satisfies the render one by not having it rather than by inventing a claim.
+Publication then re-derives the exact requirements and re-checks them against
+the claim's digest AND its program epoch, so a claim that was true when the cell
+was readied cannot publish a cell whose requirements moved or whose programs
+went cold.
+
+**The work moved into prefetch headroom, not into publication or first
+visibility.** Publication is 6.6–7.7 ms wired and 6.4–6.9 ms disconnected: the
+compile did not relocate there. First visibility is 0.8–2.9 ms with zero
+compiles on every arm.
+
+| arm | first-visible | publication | `programCompiles` | BUDGET |
+| --- | --- | --- | --- | --- |
+| hit | 2.9 ms | 7.7 ms | 0 | ✓ 1.92 / 8.33 ms |
+| miss | 2.9 ms | 6.6 ms | 0 | ✓ 1.88 / 8.33 ms |
+| blind → published | 3.6 ms | 7.1 ms | 0 | ✓ 2.95 / 8.33 ms |
+| blind → revealed | 0.8 ms | — | 0 | ✓ |
+| hit, readiness disconnected | **14.6 ms** | 6.9 ms | **1** | ✗ 13.63 / 8.33 ms |
+| blind → revealed, disconnected | **12.7 ms** | — | **1** | ✗ 11.58 / 8.33 ms |
+
+`blind → revealed` is the attribution: the cell is already published and
+invisible, so nothing but first visibility can be paying. It is 0.8 ms wired and
+12.7 ms disconnected, on the same content in the same frame.
+
+What this bench cannot say, and `verify-world-residency` says so where it makes
+the same measurement: `world-streaming-3d`'s cells share their variants with the
+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.
**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
-relocated is still a hitch.
+relocated is still a hitch. The numbers above are what makes that a settled
+question rather than a principle: publication did not move.
+
+**Next is not more readiness.** The `render.finalize` spikes of 9–15 ms are a
+separate mechanism that has been visible in every run here and has never been
+decomposed — they carry no collect, and they land outside every arrival window.
+That is the next cut.
### Instrumentation, and how it is kept honest
diff --git a/bench/residency/heavy.mjs b/bench/residency/heavy.mjs
index 690c8e47c..4a9783c52 100755
--- a/bench/residency/heavy.mjs
+++ b/bench/residency/heavy.mjs
@@ -245,7 +245,11 @@ function main() {
profile('arrival', 'Digit1')]],
];
- for (const [arm, steps] of arms) {
+ // `--arms hit,blind` narrows a remeasure to the question being asked. Each
+ // arm is its own Electron, so running the ones nobody is reading is minutes
+ // spent on a number nobody will look at.
+ const wanted = flag('arms', '').split(',').filter(Boolean);
+ for (const [arm, steps] of arms.filter(([a]) => wanted.length === 0 || wanted.includes(a))) {
const runs = drive(out, arm, steps);
for (const [as, { frames, delivery }] of runs) {
report(`${arm}${runs.size > 1 ? `/${as}` : ''}`, frames, delivery);
@@ -392,6 +396,15 @@ function report(arm, frames, delivery) {
}
}
+ // On every frame of the window, not only the expensive ones: a cheap first
+ // visibility is exactly where a compile is easiest to miss.
+ const compiledInRun = Math.max(0, ...frames.map((f) => f.compiles ?? 0));
+ const compiledInWindow = Math.max(0, ...window.map((f) => f.compiles ?? 0));
+ check(compiledInWindow === 0,
+ 'nothing was compiled on the frames the arrival is made of',
+ `peak render.mesh.programCompiles ${compiledInWindow} in the window,`
+ + ` ${compiledInRun} across the run`);
+
// Which clock brackets the publication transaction depends on where it runs:
// between frames the streamer's wall time does; inside the frame that spans
// the rest of it, and only the profiler's `scene` domain is left.
diff --git a/tools/launchers/residency-run.mjs b/tools/launchers/residency-run.mjs
index f3fd2dcb4..23dab23f9 100644
--- a/tools/launchers/residency-run.mjs
+++ b/tools/launchers/residency-run.mjs
@@ -331,6 +331,10 @@ async function main() {
+ (counters['render.text'] ?? 0) + (counters['render.shapes'] ?? 0)
+ (counters['render.particles'] ?? 0);
row.collect = costs.native['render.collect'] ?? 0;
+ // Every frame, not only the expensive ones: a cold compile is what
+ // makes a frame expensive, so recording it only there cannot answer
+ // whether a cheap arrival had one.
+ row.compiles = counters['render.mesh.programCompiles'] ?? 0;
row.domains = {};
for (const c of costs.systems) row.domains[c.domain] = (row.domains[c.domain] ?? 0) + c.ms;
for (const d of Object.keys(row.domains)) row.domains[d] = Math.round(row.domains[d] * 1000) / 1000;