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
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.mjsindex 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.tsindex 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.mdindex 325177ab2..0e31f5f4c 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -10239,6 +10239,7 @@ prefetchRequests: numberprepareCount: numberpreparedCells: string[]preparedWithRenderClaim: string[]+renderClaims: Record<string, RenderReadinessStamp & { restamps: number; }>residentCells: string[]sourceCount: numberstreamed: booleandiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex b30f1bf4d..f6e0b455a 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -10432,6 +10432,7 @@ prefetchRequests: numberprepareCount: numberpreparedCells: string[]preparedWithRenderClaim: string[]+renderClaims: Record<string, RenderReadinessStamp & { restamps: number; }>residentCells: string[]sourceCount: numberstreamed: booleandiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex f1b658775..f83a87df6 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -10234,6 +10234,7 @@ prefetchRequests: numberprepareCount: numberpreparedCells: string[]preparedWithRenderClaim: string[]+renderClaims: Record<string, RenderReadinessStamp & { restamps: number; }>residentCells: string[]sourceCount: numberstreamed: booleandiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 91e5cc204..1d36d294c 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -10486,6 +10486,7 @@ prefetchRequests: numberprepareCount: numberpreparedCells: string[]preparedWithRenderClaim: string[]+renderClaims: Record<string, RenderReadinessStamp & { restamps: number; }>residentCells: string[]sourceCount: numberstreamed: booleandiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 67fb9d60d..397fc98f6 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -10262,6 +10262,7 @@ prefetchRequests: numberprepareCount: numberpreparedCells: string[]preparedWithRenderClaim: string[]+renderClaims: Record<string, RenderReadinessStamp & { restamps: number; }>residentCells: string[]sourceCount: numberstreamed: booleandiff --git a/sdk/src/residency/report.ts b/sdk/src/residency/report.tsindex 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.mjsindex 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 moveddiff --git a/tools/verify-world-residency.mjs b/tools/verify-world-residency.mjsindex 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);