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): 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.md
index 794b42b6f..325177ab2 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -10266,6 +10266,7 @@ manifest: WorldManifest | null
recordPhase: (name: string, phase: string, ms: number) => void
renderReadinessOf: (name: string) => RenderReadinessStamp | null
residencyOf: (name: string) => CellResidency
+restampsOf: (name: string) => number
status: () => WorldStreamerStatus
update: (sources: readonly ResidencySource[]) => void
static new (host: WorldStreamHost): WorldStreamer
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index be37b7284..b30f1bf4d 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -10459,6 +10459,7 @@ manifest: WorldManifest | null
recordPhase: (name: string, phase: string, ms: number) => void
renderReadinessOf: (name: string) => RenderReadinessStamp | null
residencyOf: (name: string) => CellResidency
+restampsOf: (name: string) => number
status: () => WorldStreamerStatus
update: (sources: readonly ResidencySource[]) => void
static new (host: WorldStreamHost): WorldStreamer
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index ba6480d10..f1b658775 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -10261,6 +10261,7 @@ manifest: WorldManifest | null
recordPhase: (name: string, phase: string, ms: number) => void
renderReadinessOf: (name: string) => RenderReadinessStamp | null
residencyOf: (name: string) => CellResidency
+restampsOf: (name: string) => number
status: () => WorldStreamerStatus
update: (sources: readonly ResidencySource[]) => void
static new (host: WorldStreamHost): WorldStreamer
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index cbbd42046..91e5cc204 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -10513,6 +10513,7 @@ manifest: WorldManifest | null
recordPhase: (name: string, phase: string, ms: number) => void
renderReadinessOf: (name: string) => RenderReadinessStamp | null
residencyOf: (name: string) => CellResidency
+restampsOf: (name: string) => number
status: () => WorldStreamerStatus
update: (sources: readonly ResidencySource[]) => void
static new (host: WorldStreamHost): WorldStreamer
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 24e97aba8..67fb9d60d 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -10289,6 +10289,7 @@ manifest: WorldManifest | null
recordPhase: (name: string, phase: string, ms: number) => void
renderReadinessOf: (name: string) => RenderReadinessStamp | null
residencyOf: (name: string) => CellResidency
+restampsOf: (name: string) => number
status: () => WorldStreamerStatus
update: (sources: readonly ResidencySource[]) => void
static new (host: WorldStreamHost): WorldStreamer
diff --git a/sdk/src/residency/WorldStreamer.ts b/sdk/src/residency/WorldStreamer.ts
index 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.ts
index 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)));