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.

test(residency): a claim from a dead epoch does not publish a cell

esengine5404c71ca3e0
diff --git a/bench/residency/readiness.mjs b/bench/residency/readiness.mjs
index db530743d..ffdc05085 100644
--- a/bench/residency/readiness.mjs
+++ b/bench/residency/readiness.mjs
@@ -129,9 +129,9 @@ function drive(name, options) {
const script = path.join(WORK, `${name}.json`);
writeFileSync(script, JSON.stringify([
{ do: 'step', frames: 30 },
- // Readied but NOT published, so the document pass asks first. After
- // publication the first collect has already built everything, and
- // "nothing left to compile" is true of any two warm calls.
+ // Prefetching now READIES the cell — preparation owes a claim — so the
+ // compile is already paid before either pass runs. What these two judge
+ // is whether document and entities agree about WHAT was needed.
{ do: 'arrive', as: 'primed', key: 'Digit2' },
{ do: 'prewarm', as: 'document', cell: CELL_NAME, from: 'document' },
{ do: 'arrive', as: 'published', key: 'Digit1' },
@@ -200,15 +200,12 @@ function main() {
check(doc.claimValid === 1,
`${name}: and the readying produced a claim — nothing moved underneath it`,
`claimValid=${doc.claimValid}`);
- // The entity pass runs second, so what it still builds is what the
- // document did not know about — and this is non-vacuous only if the
- // document pass built something at all.
- check(doc.compiles > 0,
- `${name}: the document pass is the one that pays, so this is a real test`,
- `${doc.compiles} compile(s) from the document`);
- check(live.compiles === 0,
- `${name}: and readying from the document left nothing for them to compile`,
- `${live.compiles} late compile(s)`);
+ // Non-vacuous through the digests above: a derivation producing nothing
+ // would not match the entity side, which reads a live world and cannot
+ // be empty.
+ check(doc.compiles === 0 && live.compiles === 0,
+ `${name}: preparation already paid, so neither pass has anything to build`,
+ `${doc.compiles} then ${live.compiles} compile(s)`);
check(doc.programEpoch === live.programEpoch,
`${name}: and both were taken under the same program epoch`,
`${doc.programEpoch} against ${live.programEpoch}`);
@@ -228,7 +225,7 @@ function main() {
'material: the material-owned path is enumerated, and the same both ways',
`${doc.materialAsks} against ${live.materialAsks} ask(s)`);
check(live.materialCompiles === 0,
- 'material: and its programs were built by the document pass',
+ 'material: and its programs were built before either pass ran',
`${live.materialCompiles} late material compile(s)`);
}
}
diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.ts
index fd53a7540..70255fce1 100644
--- a/pipeline/src/runtime/gameHost.ts
+++ b/pipeline/src/runtime/gameHost.ts
@@ -552,6 +552,43 @@ async function boot(): Promise<void> {
return {};
}
},
+ /**
+ * Take the GPU away, and read what the renderer says about itself after.
+ *
+ * Deliberately narrow: whether recovery is CORRECT is the renderer's own
+ * device-loss corpus to judge. What this exists for is the question only
+ * residency can answer — what an old readiness claim is worth afterwards.
+ */
+ device(): Record<string, number | boolean> {
+ const m = module as unknown as {
+ renderer_deviceGeneration?(): number;
+ renderer_programEpoch?(): number;
+ };
+ return {
+ generation: m.renderer_deviceGeneration?.() ?? -1,
+ programEpoch: m.renderer_programEpoch?.() ?? -1,
+ lost: gl ? gl.isContextLost() : false,
+ };
+ },
+ loseDevice(): boolean {
+ const ext = gl?.getExtension('WEBGL_lose_context') as
+ { loseContext(): void; restoreContext(): void } | null;
+ if (!ext) return false;
+ ext.loseContext();
+ // Standing in for the browser, which hands a context back on its own.
+ // The ENGINE's recovery is not driven here: AssetPlugin does that, and a
+ // harness that drove it would be testing its own driver.
+ setTimeout(() => ext.restoreContext(), 50);
+ return true;
+ },
+
+ /** The render-program claim a cell is holding, if any. Through the report,
+ * because residency has one author and this is not it. */
+ readiness(cell: string): Record<string, number> | null {
+ const claim = worldResidencyReport(app).renderClaims?.[cell];
+ return claim ? { ...claim } : null;
+ },
+
/**
* What residency did, and what the subsystems still hold.
*
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 325177ab2..0e31f5f4c 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -10239,6 +10239,7 @@ prefetchRequests: number
prepareCount: number
preparedCells: string[]
preparedWithRenderClaim: string[]
+renderClaims: Record<string, RenderReadinessStamp & { restamps: number; }>
residentCells: string[]
sourceCount: number
streamed: boolean
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index b30f1bf4d..f6e0b455a 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -10432,6 +10432,7 @@ prefetchRequests: number
prepareCount: number
preparedCells: string[]
preparedWithRenderClaim: string[]
+renderClaims: Record<string, RenderReadinessStamp & { restamps: number; }>
residentCells: string[]
sourceCount: number
streamed: boolean
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index f1b658775..f83a87df6 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -10234,6 +10234,7 @@ prefetchRequests: number
prepareCount: number
preparedCells: string[]
preparedWithRenderClaim: string[]
+renderClaims: Record<string, RenderReadinessStamp & { restamps: number; }>
residentCells: string[]
sourceCount: number
streamed: boolean
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 91e5cc204..1d36d294c 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -10486,6 +10486,7 @@ prefetchRequests: number
prepareCount: number
preparedCells: string[]
preparedWithRenderClaim: string[]
+renderClaims: Record<string, RenderReadinessStamp & { restamps: number; }>
residentCells: string[]
sourceCount: number
streamed: boolean
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 67fb9d60d..397fc98f6 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -10262,6 +10262,7 @@ prefetchRequests: number
prepareCount: number
preparedCells: string[]
preparedWithRenderClaim: string[]
+renderClaims: Record<string, RenderReadinessStamp & { restamps: number; }>
residentCells: string[]
sourceCount: number
streamed: boolean
diff --git a/sdk/src/residency/report.ts b/sdk/src/residency/report.ts
index 4adcfe21b..96f9991fd 100644
--- a/sdk/src/residency/report.ts
+++ b/sdk/src/residency/report.ts
@@ -17,6 +17,7 @@
import type { App } from '../app/app';
import { SceneManager } from '../scene/sceneManager';
import { WorldStreaming, type CellDelivery } from './WorldStreamer';
+import type { RenderReadinessStamp } from '../render/renderReadiness';
import { stableEntityId } from './identity';
import { renderableComponents } from '../ecs/component';
@@ -35,6 +36,9 @@ export interface WorldResidencyReport {
/** Of those, the ones holding a render-program claim. A prepared cell with
* none was readied by a host that has no renderer to ready. */
preparedWithRenderClaim: string[];
+ /** Each of those claims, and how often publication found one stale. Absent
+ * from the map = that cell holds none. */
+ renderClaims: Record<string, RenderReadinessStamp & { restamps: number }>;
loadingCells: string[];
unloadingCells: string[];
loadCount: number;
@@ -78,7 +82,7 @@ export interface WorldResidencyReport {
const EMPTY: WorldResidencyReport = {
streamed: false, cellCount: 0, sourceCount: 0,
desiredCells: [], prefetchCells: [], residentCells: [], preparedCells: [],
- preparedWithRenderClaim: [],
+ preparedWithRenderClaim: [], renderClaims: {},
loadingCells: [], unloadingCells: [],
loadCount: 0, unloadCount: 0, prepareCount: 0, cancelCount: 0,
prefetchRequests: 0, cancelledRefs: 0,
@@ -137,6 +141,11 @@ export function worldResidencyReport(app: App): WorldResidencyReport {
preparedCells: status.preparedCells,
preparedWithRenderClaim:
status.preparedCells.filter((c) => streamer.renderReadinessOf(c) !== null),
+ renderClaims: Object.fromEntries(
+ [...status.preparedCells, ...status.residentCells]
+ .map((c) => [c, streamer.renderReadinessOf(c)])
+ .filter((row): row is [string, RenderReadinessStamp] => row[1] !== null)
+ .map(([c, stamp]) => [c, { ...stamp, restamps: streamer.restampsOf(c) }])),
loadingCells: status.loadingCells,
unloadingCells: status.unloadingCells,
loadCount: status.loadCount,
diff --git a/tools/launchers/residency-run.mjs b/tools/launchers/residency-run.mjs
index 3bbf4582e..f3fd2dcb4 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}, {do:"stream",as,key,count}. Each read
+ * {do:"tap",key}, {do:"step",frames}, {do:"stream",as,key,count},
+ * {do:"loseDevice",as}, {do:"readiness",as,cell}, {do:"counters",as}. Each read
* prints one JSON line.
*/
import { app, BrowserWindow } from 'electron';
@@ -222,6 +223,45 @@ async function main() {
continue;
}
if (step.do === 'step') { await exec(holdScript([], step.frames ?? 30)); continue; }
+ if (step.do === 'loseDevice') {
+ // One action, then wait. Whether recovery is CORRECT belongs to the
+ // renderer's own device-loss corpus; what this exists for is what an old
+ // readiness claim is worth once recovery has finished.
+ const supported = await exec('window.__estellaCooked.loseDevice()');
+ if (!supported) { stop(); server.close(); return fail('no WEBGL_lose_context here', 2); }
+ const wanted = step.generation ?? 1;
+ let device = null;
+ for (let waited = 0; waited < (step.frames ?? 600); waited += 20) {
+ await exec(holdScript([], 20));
+ device = await exec('window.__estellaCooked.device()');
+ if (!device.lost && device.generation >= wanted) break;
+ }
+ console.log(`lostDevice ${step.as}: ${JSON.stringify(device)}`);
+ continue;
+ }
+ if (step.do === 'readiness') {
+ await settle();
+ const claim = await exec(
+ `window.__estellaCooked.readiness(${JSON.stringify(step.cell)})`);
+ const device = await exec('window.__estellaCooked.device()');
+ console.log(`readiness ${step.as}: ${JSON.stringify({ claim, device })}`);
+ continue;
+ }
+ if (step.do === 'counters') {
+ // The PEAK across the window, not the last frame's. A cold compile happens
+ // on one frame — the first one that shows the content — and a single
+ // reading taken after it reports the zero of every frame since.
+ const seen = {};
+ for (let i = 0; i < (step.frames ?? 1); i++) {
+ if (i > 0) await exec(holdScript([], 1));
+ const c = await exec('window.__estellaCooked.render()');
+ for (const [k, v] of Object.entries(c)) {
+ seen[k] = Math.max(seen[k] ?? 0, Number(v) || 0);
+ }
+ }
+ console.log(`counters ${step.as}: ${JSON.stringify(seen)}`);
+ continue;
+ }
if (step.do === 'watch') {
// Sample while it runs, so a claim about a source CROSSING a threshold can
// say it crossed. One reading at the end cannot: a source that never moved
diff --git a/tools/verify-world-residency.mjs b/tools/verify-world-residency.mjs
index 8ff2b9161..515cbe909 100644
--- a/tools/verify-world-residency.mjs
+++ b/tools/verify-world-residency.mjs
@@ -61,7 +61,8 @@ function drive(dir, name, steps) {
], { encoding: 'utf8', cwd: ROOT });
const readings = {};
for (const line of (r.stdout || '').split('\n')) {
- const at = Math.max(line.indexOf('reading '), line.indexOf('watching '));
+ const at = Math.max(...['reading ', 'watching ', 'lostDevice ', 'readiness ', 'counters ']
+ .map((p) => line.indexOf(p)));
if (at < 0) continue;
const label = line.slice(line.indexOf(' ', at) + 1, line.indexOf(':', at));
try {
@@ -345,6 +346,78 @@ function main() {
? `${Object.keys(stale.blown.combat.targets).length} targets, all whole`
: hurt.join(', '));
+ // ---- 5. A readiness claim across a device generation ----------------
+ //
+ // The epoch says readiness taken before a rebuild is worth nothing, and
+ // publication is where that debt comes due. All four facts are read.
+ const CELL_COMPILES = 'render.mesh.programCompiles';
+ const revalidate = drive(dir, 'readiness-across-loss', [
+ { do: 'step', frames: 30 },
+ // Engage the profiler before the interesting frames, not during them.
+ { do: 'counters', as: 'warmup' },
+ { do: 'readiness', as: 'beforeLoss', cell: C },
+ { do: 'loseDevice', as: 'lost' },
+ { do: 'readiness', as: 'afterLoss', cell: C },
+ // Demand C. Publication has to re-establish readiness before it can show
+ // anything, and the peak across the window is where a cold compile lands.
+ { do: 'tap', key: 'KeyL', frames: 1 },
+ { do: 'counters', as: 'atReveal', frames: 60 },
+ { do: 'readiness', as: 'afterPublish', cell: C },
+ { do: 'read', as: 'revealed' },
+ ]);
+
+ const preLoss = revalidate.beforeLoss;
+ const afterLoss = revalidate.afterLoss;
+ const afterPublish = revalidate.afterPublish;
+ claim(preLoss.claim !== null && preLoss.claim.restamps === 0,
+ 'a readied cell holds a claim before anything takes the device away',
+ `claim ${JSON.stringify(preLoss.claim)}`);
+ claim(afterLoss.device.generation > preLoss.device.generation,
+ 'losing the device and recovering advances the device generation',
+ `generation ${preLoss.device.generation} → ${afterLoss.device.generation}`);
+ claim(afterLoss.device.programEpoch > preLoss.device.programEpoch,
+ 'and the program epoch too, independently — the stock cache went cold',
+ `epoch ${preLoss.device.programEpoch} → ${afterLoss.device.programEpoch}`);
+ claim(afterLoss.claim !== null
+ && afterLoss.claim.programEpoch === preLoss.claim?.programEpoch,
+ 'the claim the cell is holding is now from a dead epoch, and it still holds it',
+ `still ${JSON.stringify(afterLoss.claim)}`);
+ claim(afterPublish.claim !== null
+ && afterPublish.claim.programEpoch === afterLoss.device.programEpoch
+ && afterPublish.claim.restamps === 1,
+ 'publishing it replaced the stale claim with one from the live epoch',
+ `claim ${JSON.stringify(afterPublish.claim)}`);
+ claim(resident(revalidate.revealed, C),
+ 'the cell published', `resident ${JSON.stringify(revalidate.revealed.streaming.residentCells)}`);
+ // Soundness, not attribution: this fixture's cells share variants with the one
+ // the player stands in, whose draws rebuild them after a loss regardless. A
+ // zero says no first frame met a cold program; who warmed it is readiness.mjs's.
+ claim((revalidate.atReveal[CELL_COMPILES] ?? 0) === 0,
+ 'and nothing compiled on the frames that first showed it',
+ `${CELL_COMPILES} peaked at ${revalidate.atReveal[CELL_COMPILES] ?? 0}`);
+
+ // The control arm. Without it, a publication that re-readies unconditionally
+ // passes everything above while paying the cost prefetching exists to avoid.
+ const quiet = drive(dir, 'readiness-no-loss', [
+ { do: 'step', frames: 30 },
+ { do: 'counters', as: 'warmup' },
+ { do: 'readiness', as: 'beforePublish', cell: C },
+ { do: 'tap', key: 'KeyL', frames: 1 },
+ { do: 'counters', as: 'atReveal', frames: 60 },
+ { do: 'readiness', as: 'afterPublish', cell: C },
+ { do: 'read', as: 'revealed' },
+ ]);
+ claim(quiet.afterPublish.claim !== null && quiet.afterPublish.claim.restamps === 0,
+ 'a dwell in which nothing moved publishes on the claim it was prepared with',
+ `restamps ${quiet.afterPublish.claim?.restamps}`);
+ claim(quiet.afterPublish.claim?.digestLo === quiet.beforePublish.claim?.digestLo
+ && quiet.afterPublish.claim?.programEpoch === quiet.beforePublish.claim?.programEpoch,
+ 'and the claim it publishes on is the same claim, not a fresh one',
+ `${JSON.stringify(quiet.beforePublish.claim)} → ${JSON.stringify(quiet.afterPublish.claim)}`);
+ claim((quiet.atReveal[CELL_COMPILES] ?? 0) === 0,
+ 'with nothing compiled at first sight either',
+ `${CELL_COMPILES} peaked at ${quiet.atReveal[CELL_COMPILES] ?? 0}`);
+
const failed = results.filter((r) => !r.ok).length;
console.log(`\nworld-residency: ${results.length - failed}/${results.length}`);
process.exit(failed === 0 ? 0 : 1);