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): a claim that was true is not a claim that is true now
esengine745fd8585bd4
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 794b42b6f..325177ab2 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -10266,6 +10266,7 @@ manifest: WorldManifest | nullrecordPhase: (name: string, phase: string, ms: number) => voidrenderReadinessOf: (name: string) => RenderReadinessStamp | nullresidencyOf: (name: string) => CellResidency+restampsOf: (name: string) => numberstatus: () => WorldStreamerStatusupdate: (sources: readonly ResidencySource[]) => voidstatic new (host: WorldStreamHost): WorldStreamerdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex be37b7284..b30f1bf4d 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -10459,6 +10459,7 @@ manifest: WorldManifest | nullrecordPhase: (name: string, phase: string, ms: number) => voidrenderReadinessOf: (name: string) => RenderReadinessStamp | nullresidencyOf: (name: string) => CellResidency+restampsOf: (name: string) => numberstatus: () => WorldStreamerStatusupdate: (sources: readonly ResidencySource[]) => voidstatic new (host: WorldStreamHost): WorldStreamerdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex ba6480d10..f1b658775 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -10261,6 +10261,7 @@ manifest: WorldManifest | nullrecordPhase: (name: string, phase: string, ms: number) => voidrenderReadinessOf: (name: string) => RenderReadinessStamp | nullresidencyOf: (name: string) => CellResidency+restampsOf: (name: string) => numberstatus: () => WorldStreamerStatusupdate: (sources: readonly ResidencySource[]) => voidstatic new (host: WorldStreamHost): WorldStreamerdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex cbbd42046..91e5cc204 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -10513,6 +10513,7 @@ manifest: WorldManifest | nullrecordPhase: (name: string, phase: string, ms: number) => voidrenderReadinessOf: (name: string) => RenderReadinessStamp | nullresidencyOf: (name: string) => CellResidency+restampsOf: (name: string) => numberstatus: () => WorldStreamerStatusupdate: (sources: readonly ResidencySource[]) => voidstatic new (host: WorldStreamHost): WorldStreamerdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 24e97aba8..67fb9d60d 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -10289,6 +10289,7 @@ manifest: WorldManifest | nullrecordPhase: (name: string, phase: string, ms: number) => voidrenderReadinessOf: (name: string) => RenderReadinessStamp | nullresidencyOf: (name: string) => CellResidency+restampsOf: (name: string) => numberstatus: () => WorldStreamerStatusupdate: (sources: readonly ResidencySource[]) => voidstatic new (host: WorldStreamHost): WorldStreamerdiff --git a/sdk/src/residency/WorldStreamer.ts b/sdk/src/residency/WorldStreamer.tsindex 996bfc752..f6376795a 100644--- a/sdk/src/residency/WorldStreamer.ts+++ b/sdk/src/residency/WorldStreamer.ts@@ -19,7 +19,9 @@import { desiredResidency, type ResidencySource, type WorldCell, type WorldManifest } from './cells';import type { SceneConfig } from '../scene/sceneManager';-import type { RenderReadiness, RenderReadinessStamp } from '../render/renderReadiness';+import {+ sameReadiness, type RenderReadiness, type RenderReadinessStamp,+} from '../render/renderReadiness';import { defineResource } from '../ecs/resource';import { log } from '../util/logger';@@ -105,6 +107,9 @@ interface CellState {renderReadiness: RenderReadinessStamp | null;/** Whether a readying attempt is in flight, so a retry does not stack. */readinessInFlight: boolean;+ /** How often publication found the claim stale and replaced it. Zero over a+ * dwell in which nothing moved is the whole point of preparing early. */+ restamps: number;/** What the last reconciliation asked for; the async completions re-read it. */desired: boolean;/** Whether any source is close enough to speculate about it. */@@ -183,6 +188,7 @@ export class WorldStreamer {this.cells_.set(cell.name, {cell, residency: 'unloaded', desired: false, speculated: false,assetsReady: false, renderReadiness: null, readinessInFlight: false,+ restamps: 0,phases: {}, issuedAt: 0, delivery: 0,demandedAt: 0, preparedAt: 0, publishedAt: 0,prepareMs: 0, publishMs: 0, demandToResidentMs: 0, dwellMs: 0, outcome: '',@@ -211,6 +217,18 @@ export class WorldStreamer {return this.cells_.get(name)?.renderReadiness ?? null;}+ /**+ * How often publication found this cell's claim stale and made a new one.+ *+ * Zero across a dwell where nothing moved: readying again for content that+ * did not change is the cost prefetching exists to avoid paying twice.+ *+ * @experimental+ */+ restampsOf(name: string): number {+ return this.cells_.get(name)?.restamps ?? 0;+ }+/*** Where a cell's load spent its time.*@@ -370,7 +388,7 @@ export class WorldStreamer {if (state.residency === 'unloaded' && (state.desired || state.speculated)) {this.beginPrepare_(name, state);} else if (state.residency === 'prepared' && state.desired) {- this.beginLoad_(name, state);+ this.publishWhenReady_(name, state);} else if (state.residency === 'prepared' && !state.speculated) {// Speculation is not authority. A cell nobody is near any more goes// back, receipts included, rather than being published because it@@ -430,7 +448,7 @@ export class WorldStreamer {if (!ready) { this.markPrepared_(name, state); return; }state.readinessInFlight = true;- Promise.resolve(ready.call(this.host_, name)).then(+ this.askReadiness_(name, ready).then((outcome) => {state.readinessInFlight = false;// Not applicable is an answer, not a claim: a host with no@@ -451,6 +469,23 @@ export class WorldStreamer {);}+ /**+ * Ask the host to ready a cell's programs, as a promise either way.+ *+ * A host that throws SYNCHRONOUSLY would otherwise unwind through the+ * progression and leave the streamer mid-step. A failed readying is an+ * outcome this handles, not one it propagates.+ */+ private askReadiness_(+ name: string, ready: NonNullable<WorldStreamHost['readyRenderPrograms']>,+ ): Promise<RenderReadiness> {+ try {+ return Promise.resolve(ready.call(this.host_, name));+ } catch (err) {+ return Promise.reject(err);+ }+ }+/** Every obligation is satisfied: only now is the cell prepared. */private markPrepared_(name: string, state: CellState): void {state.residency = 'prepared';@@ -462,6 +497,48 @@ export class WorldStreamer {this.step_(name);}+ /**+ * The obligation publication has, which is not the one preparation had.+ *+ * A claim about THEN, so requirements are derived AGAIN rather than inferred+ * from what looks like it moved. A stale one blocks this publication without+ * sending the cell backwards; an unpayable debt leaves it prepared.+ */+ private publishWhenReady_(name: string, state: CellState): void {+ const ready = this.host_.readyRenderPrograms;+ // No claim to keep fresh: the obligation did not apply when this cell was+ // prepared, and nothing since then has given it a renderer.+ if (!ready || !state.renderReadiness) { this.beginLoad_(name, state); return; }+ if (state.readinessInFlight) return;++ state.readinessInFlight = true;+ this.askReadiness_(name, ready).then(+ (outcome) => {+ state.readinessInFlight = false;+ if (!outcome.applicable) { this.beginLoad_(name, state); return; }+ if (!outcome.stamp) {+ // Publication created a debt of its own — the readying was+ // refused, most likely by a device that moved underneath it.+ log.warn('residency',+ `cell "${name}" cannot publish: its programs are not ready`);+ return;+ }+ // Compared, not merely overwritten: re-readying is idempotent so+ // both paths publish, but comparing BOTH halves is what keeps+ // either half from silently coming undone.+ if (!sameReadiness(state.renderReadiness!, outcome.stamp)) {+ state.renderReadiness = outcome.stamp;+ state.restamps++;+ }+ this.beginLoad_(name, state);+ },+ (err) => {+ state.readinessInFlight = false;+ log.error('residency', `cell "${name}" could not re-ready its programs`, err);+ },+ );+ }+private beginLoad_(name: string, state: CellState): void {state.residency = 'publishing';state.publishedAt = performance.now();diff --git a/sdk/tests/world-residency.test.ts b/sdk/tests/world-residency.test.tsindex 67f07eaf2..90e71081b 100644--- a/sdk/tests/world-residency.test.ts+++ b/sdk/tests/world-residency.test.ts@@ -273,6 +273,128 @@ describe('WorldStreamer', () => {});});+ // Entering prepared with a true claim is not publishing with one that is still+ // true. Requirements change and programs go cold, and each is caught on its+ // own: a gate seeing only "something differs" stays green with one side cut.+ describe('publication re-checks the claim it was prepared with', () => {+ const stamp = (digestLo: number, programEpoch: number): RenderReadiness =>+ ({ applicable: true, stamp: { digestLo, digestHi: 0, programEpoch } });+ /** Speculated first, then demanded: a dwell is what makes a claim age. */+ const far = () => source(250, 50, 10, 20, 200);+ const near = () => source(50, 50, 10, 20, 200);++ async function preparedThenDemanded(answer: () => RenderReadiness) {+ const rec = recordingHost(answer);+ const s = new WorldStreamer(rec.host);+ s.loadManifest(manifest(cell(0, 0)));+ s.update([far()]);+ await flush();+ expect(s.residencyOf('c_0_0')).toBe('prepared');+ return { s, ...rec };+ }++ it('a claim that is still true publishes without readying again', async () => {+ let answer = stamp(7, 3);+ const { s, calls } = await preparedThenDemanded(() => answer);+ const readiedAtPrepare = calls.filter((c) => c === 'ready:c_0_0').length;++ s.update([near()]);+ await flush();+ expect(s.residencyOf('c_0_0')).toBe('resident');+ // One revalidation, and it found nothing to do: the derivation is the+ // cost of asking, and it compiled nothing because nothing changed.+ expect(calls.filter((c) => c === 'ready:c_0_0'))+ .toHaveLength(readiedAtPrepare + 1);+ expect(s.renderReadinessOf('c_0_0'))+ .toEqual({ digestLo: 7, digestHi: 0, programEpoch: 3 });+ // Nothing was restamped, which is what "the claim held" means.+ expect(s.restampsOf('c_0_0')).toBe(0);+ });++ it('a requirement that changed during the dwell is re-readied before publishing',+ async () => {+ let answer = stamp(7, 3);+ const { s } = await preparedThenDemanded(() => answer);+ // Same epoch: only WHAT is needed moved. An environment map arriving+ // flips a variant without any program going cold.+ answer = stamp(99, 3);++ s.update([near()]);+ await flush();+ expect(s.residencyOf('c_0_0')).toBe('resident');+ expect(s.renderReadinessOf('c_0_0'))+ .toEqual({ digestLo: 99, digestHi: 0, programEpoch: 3 });+ // The DIGEST half caught it: a comparison blind to requirements+ // would have published on the claim it was prepared with.+ expect(s.restampsOf('c_0_0')).toBe(1);+ });++ it('a program cache emptied during the dwell is re-readied before publishing',+ async () => {+ let answer = stamp(7, 3);+ const { s } = await preparedThenDemanded(() => answer);+ // Same digest: the content needs exactly what it needed, and the+ // programs that covered it are gone. This is the device-loss shape.+ answer = stamp(7, 8);++ s.update([near()]);+ await flush();+ expect(s.residencyOf('c_0_0')).toBe('resident');+ expect(s.renderReadinessOf('c_0_0'))+ .toEqual({ digestLo: 7, digestHi: 0, programEpoch: 8 });+ // The EPOCH half caught it, independently of the digest one.+ expect(s.restampsOf('c_0_0')).toBe(1);+ });++ it('a re-readying that makes no claim blocks publication, and stays owed',+ async () => {+ let answer = stamp(7, 3);+ const { s, loaded } = await preparedThenDemanded(() => answer);+ // The device went away again mid-readying: claimValid = 0.+ answer = { applicable: true, stamp: null };++ s.update([near()]);+ await flush();+ expect(loaded.has('c_0_0')).toBe(false);+ // Not sent backwards: it satisfied everything preparation asks, and+ // still does. What it cannot do is publish.+ expect(s.residencyOf('c_0_0')).toBe('prepared');++ answer = stamp(7, 9);+ s.update([near()]);+ await flush();+ expect(s.residencyOf('c_0_0')).toBe('resident');+ expect(s.renderReadinessOf('c_0_0'))+ .toEqual({ digestLo: 7, digestHi: 0, programEpoch: 9 });+ });++ it('a re-readying that throws blocks publication too', async () => {+ let answer: () => RenderReadiness = () => stamp(7, 3);+ const { s, loaded } = await preparedThenDemanded(() => answer());+ answer = () => { throw new Error('device went away'); };++ s.update([near()]);+ await flush();+ expect(loaded.has('c_0_0')).toBe(false);+ expect(s.residencyOf('c_0_0')).toBe('prepared');+ });++ it('a host with no renderer publishes without any of this', async () => {+ const { host, calls } = recordingHost(() => ({ applicable: false }));+ const s = new WorldStreamer(host);+ s.loadManifest(manifest(cell(0, 0)));+ s.update([far()]);+ await flush();+ const readiedAtPrepare = calls.filter((c) => c === 'ready:c_0_0').length;++ s.update([near()]);+ await flush();+ expect(s.residencyOf('c_0_0')).toBe('resident');+ // Nothing to keep fresh, so publication asks nobody anything.+ expect(calls.filter((c) => c === 'ready:c_0_0')).toHaveLength(readiedAtPrepare);+ });+ });+it('registers every cell as a scene the game itself never names', async () => {const { host, calls } = recordingHost();new WorldStreamer(host).loadManifest(manifest(cell(0, 0), cell(1, 0)));