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 place is readied before it is asked for, and only publication makes it exist
esengine1d19aa169d6b
diff --git a/examples/world-streaming-3d/assets/scenes/main.esscene b/examples/world-streaming-3d/assets/scenes/main.essceneindex cb7ff7887..d6d85c389 100644--- a/examples/world-streaming-3d/assets/scenes/main.esscene+++ b/examples/world-streaming-3d/assets/scenes/main.esscene@@ -140,7 +140,8 @@"data": {"loadRadius": 250,"unloadRadius": 450,- "enabled": true+ "enabled": true,+ "prefetchRadius": 900}},{@@ -312,7 +313,8 @@"data": {"loadRadius": 250,"unloadRadius": 450,- "enabled": false+ "enabled": false,+ "prefetchRadius": 900}},{@@ -343,7 +345,8 @@"data": {"loadRadius": 250,"unloadRadius": 450,- "enabled": false+ "enabled": false,+ "prefetchRadius": 900}},{diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.tsindex 5daadc141..f37661583 100644--- a/pipeline/src/export/exportGame.ts+++ b/pipeline/src/export/exportGame.ts@@ -511,21 +511,25 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>// Cutting a world is part of the common cook below, which the three pipelines// that follow do not reach. Shipping an unstreamed world to them is a real// difference in what the package IS, so it is said rather than discovered.+ // The three pipelines below return before the common cook that cuts a world,+ // so shipping one to them builds fine and delivers the whole thing — a+ // declaration the runtime never receives. Refused rather than warned about.const streamed = await streamedScenes(opts.root, scenes);- const withStreamingNote = (result: ExportGameResult): ExportGameResult =>- (streamed.length === 0 ? result : {- ...result,- warnings: [...result.warnings,- `${streamed.join(', ')} declares a streamed world and this target ships it whole`- + ' — world cells are cooked for web, desktop, android and ios only'],- });+ const refuseStreamedWorld = (target: string): never => {+ throw new Error(+ `${streamed.join(', ')} declares a streamed world, and ${target} cannot ship one: `+ + 'world cells are cooked for web, desktop, android and ios. Export one of those, '+ + 'or remove StreamedWorld to ship this target with the world loaded whole.',+ );+ };// A platform the editor does not ship: the project supplied an export profile// (.esengine/platforms/<id>.mjs, loaded by the main process since it carries// functions). It rides the same vendor-neutral mini-game pipeline WeChat does// — that pipeline taking a profile is exactly what makes this possible.if (opts.miniGameProfile) {- return withStreamingNote(await exportMiniGame(opts.miniGameProfile, {+ if (streamed.length > 0) refuseStreamedWorld('a mini-game package');+ return await exportMiniGame(opts.miniGameProfile, {root: opts.root,entryScene: opts.entryScene,scenes,@@ -545,12 +549,13 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>compressAudio: opts.compressAudio,atlasTextures: opts.atlasTextures,onProgress: opts.onProgress,- }));+ });}// WeChat has no import maps + a different module/asset model → its own pipeline.if (platform === 'wechat') {- return withStreamingNote(await exportWeChat({+ if (streamed.length > 0) refuseStreamedWorld('the WeChat package');+ return await exportWeChat({root: opts.root,entryScene: opts.entryScene,scenes,@@ -570,12 +575,13 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>compressAudio: opts.compressAudio,atlasTextures: opts.atlasTextures,onProgress: opts.onProgress,- }));+ });}// Playable ads are a single inlined HTML (SINGLE_FILE glue + base64 assets).if (platform === 'playable') {- return withStreamingNote(await exportPlayable({+ if (streamed.length > 0) refuseStreamedWorld('a playable ad (one inlined file)');+ return await exportPlayable({root: opts.root,entryScene: opts.entryScene,scriptsEntry: opts.scriptsEntry,@@ -590,7 +596,7 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>runtime,adProfile: opts.playableAdProfile,onProgress: opts.onProgress,- }));+ });}// path.resolve, not isAbsolute-or-join: on Windows `/Users/me/out` IS absolutediff --git a/pipeline/tests/partition-world.test.ts b/pipeline/tests/partition-world.test.tsindex 9ebe6e54a..58d68946d 100644--- a/pipeline/tests/partition-world.test.ts+++ b/pipeline/tests/partition-world.test.ts@@ -10,6 +10,9 @@* the first time a player walks away.*/import { describe, it, expect } from 'vitest';+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import path from 'node:path';import type { SceneData } from 'esengine';import { partitionWorld, type PartitionOptions } from '../src/world/partitionWorld';@@ -186,3 +189,32 @@ describe('partitionWorld', () => {expect(partition.errors.join('\n')).toContain('no positive cellSize');});});++describe('targets that cannot ship a cut world', () => {+ it('is a decision the export makes, not a warning it prints', async () => {+ // The shape this refuses is the one the whole feature exists against: a+ // build that succeeds while the thing it declared quietly does not ship.+ const { exportGame } = await import('../src/export/exportGame');+ const project = await mkdtemp(path.join(tmpdir(), 'streamed-'));+ try {+ await mkdir(path.join(project, 'assets', 'scenes'), { recursive: true });+ await writeFile(path.join(project, 'assets', 'scenes', 'main.esscene'),+ JSON.stringify(scene(+ entity(0, 'World', null, { components: [declaration] }),+ entity(1, 'RockA', [500, 0, 500]),+ )));+ await writeFile(path.join(project, 'project.esproject'), JSON.stringify({+ formatVersion: '1', name: 'Streamed', defaultScene: 'assets/scenes/main.esscene',+ }));+ await expect(exportGame({+ root: project,+ entryScene: 'assets/scenes/main.esscene',+ outDir: path.join(project, 'out'),+ platform: 'playable',+ gameHostEntry: path.join(project, 'host.ts'),+ })).rejects.toThrow(/cannot ship one/);+ } finally {+ await rm(project, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });+ }+ });+});diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 39a1f9680..60c92f3c7 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1963,7 +1963,7 @@ y: number## CellResidency — type @experimental```-'unloaded' | 'loading' | 'resident' | 'unloading'+'unloaded' | 'preparing' | 'prepared' | 'publishing' | 'resident' | 'unloading'```## Census — interface @experimental@@ -6927,6 +6927,7 @@ static prototype: ResMutInstance<any>## ResidencyDecision — interface @experimental```+prefetch: string[]target: string[]toLoad: string[]toUnload: string[]@@ -6935,6 +6936,7 @@ toUnload: string[]## ResidencySource — interface @experimental```loadRadius: number+prefetchRadius: numberunloadRadius: numberx: numberz: number@@ -7265,10 +7267,12 @@ type: string```cleanup: ((ctx: SceneContext) => void) | undefineddata: SceneData | undefined+discardPrepared: (() => number) | undefinedexternalEntities: (() => ReadonlyMap<number, Entity>) | undefinedname: stringonPhase: ((phase: string, ms: number) => void) | undefinedpath: string | undefined+prepare: (() => Promise<void>) | undefinedsetup: ((ctx: SceneContext) => void | Promise<void>) | undefinedsystems: { schedule: Schedule; system: SystemDef; }[] | undefined```@@ -7344,6 +7348,7 @@ ResourceDef<SceneManagerState>```@internal assetScopeFor: (name: string) => AssetScope | nullbringToTop: (name: string) => void+discardPrepared: (name: string) => numbergetActive: () => string | nullgetActiveScenes: () => string[]getInitial: () => string | null@@ -7359,6 +7364,7 @@ isTransitioning: () => booleanload: (name: string, onProgress?: SceneLoadProgressCallback) => Promise<SceneContext>loadAdditive: (name: string, onProgress?: SceneLoadProgressCallback) => Promise<SceneContext>pause: (name: string) => void+prepare: (name: string) => Promise<void>register: (config: SceneConfig) => voidreload: (options?: TransitionOptions) => Promise<void>reset: () => void@@ -10097,16 +10103,24 @@ top: number```assetRefsByCell: Record<string, number>authoredCellEntityCounts: Record<string, number>+cancelCount: number+cancelledRefs: numbercellCount: numbercellEntityCounts: Record<string, number>cellRenderCounts: Record<string, number>cellRows: Record<string, { id: number; entity: number; }[]>delivery: Record<string, { phases: Record<string, number>; deliveryMs: number; }>desiredCells: string[]+lastDemandToResidentMs: numberloadCount: numberloadingCells: string[]persistentEntities: numberpersistentHandles: number[]+prefetchCells: string[]+prefetchHits: number+prefetchMisses: number+prepareCount: number+preparedCells: string[]residentCells: string[]sourceCount: numberstreamed: boolean@@ -10116,8 +10130,10 @@ unloadingCells: string[]## WorldStreamHost — interface @experimental```+discardPrepared: (name: string) => numberisLoaded: (name: string) => booleanloadAdditive: (name: string) => Promise<unknown>+prepare: (name: string) => Promise<void>register: (config: SceneConfig) => voidunload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>```@@ -10138,10 +10154,18 @@ static prototype: WorldStreamer## WorldStreamerStatus — interface @experimental```+cancelCount: number+cancelledRefs: numbercellCount: numberdesiredCells: string[]+lastDemandToResidentMs: numberloadCount: numberloadingCells: string[]+prefetchCells: string[]+prefetchHits: number+prefetchMisses: number+prepareCount: number+preparedCells: string[]residentCells: string[]sourceCount: numberunloadCount: number@@ -10162,6 +10186,7 @@ ComponentDef<WorldStreamingSourceData>```enabled: booleanloadRadius: number+prefetchRadius: numberunloadRadius: number```diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 6dd65b443..9f4fe8aec 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1963,7 +1963,7 @@ y: number## CellResidency — type @experimental```-'unloaded' | 'loading' | 'resident' | 'unloading'+'unloaded' | 'preparing' | 'prepared' | 'publishing' | 'resident' | 'unloading'```## Census — interface @experimental@@ -7120,6 +7120,7 @@ static prototype: ResMutInstance<any>## ResidencyDecision — interface @experimental```+prefetch: string[]target: string[]toLoad: string[]toUnload: string[]@@ -7128,6 +7129,7 @@ toUnload: string[]## ResidencySource — interface @experimental```loadRadius: number+prefetchRadius: numberunloadRadius: numberx: numberz: number@@ -7458,10 +7460,12 @@ type: string```cleanup: ((ctx: SceneContext) => void) | undefineddata: SceneData | undefined+discardPrepared: (() => number) | undefinedexternalEntities: (() => ReadonlyMap<number, Entity>) | undefinedname: stringonPhase: ((phase: string, ms: number) => void) | undefinedpath: string | undefined+prepare: (() => Promise<void>) | undefinedsetup: ((ctx: SceneContext) => void | Promise<void>) | undefinedsystems: { schedule: Schedule; system: SystemDef; }[] | undefined```@@ -7537,6 +7541,7 @@ ResourceDef<SceneManagerState>```@internal assetScopeFor: (name: string) => AssetScope | nullbringToTop: (name: string) => void+discardPrepared: (name: string) => numbergetActive: () => string | nullgetActiveScenes: () => string[]getInitial: () => string | null@@ -7552,6 +7557,7 @@ isTransitioning: () => booleanload: (name: string, onProgress?: SceneLoadProgressCallback) => Promise<SceneContext>loadAdditive: (name: string, onProgress?: SceneLoadProgressCallback) => Promise<SceneContext>pause: (name: string) => void+prepare: (name: string) => Promise<void>register: (config: SceneConfig) => voidreload: (options?: TransitionOptions) => Promise<void>reset: () => void@@ -10290,16 +10296,24 @@ top: number```assetRefsByCell: Record<string, number>authoredCellEntityCounts: Record<string, number>+cancelCount: number+cancelledRefs: numbercellCount: numbercellEntityCounts: Record<string, number>cellRenderCounts: Record<string, number>cellRows: Record<string, { id: number; entity: number; }[]>delivery: Record<string, { phases: Record<string, number>; deliveryMs: number; }>desiredCells: string[]+lastDemandToResidentMs: numberloadCount: numberloadingCells: string[]persistentEntities: numberpersistentHandles: number[]+prefetchCells: string[]+prefetchHits: number+prefetchMisses: number+prepareCount: number+preparedCells: string[]residentCells: string[]sourceCount: numberstreamed: boolean@@ -10309,8 +10323,10 @@ unloadingCells: string[]## WorldStreamHost — interface @experimental```+discardPrepared: (name: string) => numberisLoaded: (name: string) => booleanloadAdditive: (name: string) => Promise<unknown>+prepare: (name: string) => Promise<void>register: (config: SceneConfig) => voidunload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>```@@ -10331,10 +10347,18 @@ static prototype: WorldStreamer## WorldStreamerStatus — interface @experimental```+cancelCount: number+cancelledRefs: numbercellCount: numberdesiredCells: string[]+lastDemandToResidentMs: numberloadCount: numberloadingCells: string[]+prefetchCells: string[]+prefetchHits: number+prefetchMisses: number+prepareCount: number+preparedCells: string[]residentCells: string[]sourceCount: numberunloadCount: number@@ -10355,6 +10379,7 @@ ComponentDef<WorldStreamingSourceData>```enabled: booleanloadRadius: number+prefetchRadius: numberunloadRadius: number```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex e5472f44b..2ca5fe5e8 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1958,7 +1958,7 @@ y: number## CellResidency — type @experimental```-'unloaded' | 'loading' | 'resident' | 'unloading'+'unloaded' | 'preparing' | 'prepared' | 'publishing' | 'resident' | 'unloading'```## Census — interface @experimental@@ -6922,6 +6922,7 @@ static prototype: ResMutInstance<any>## ResidencyDecision — interface @experimental```+prefetch: string[]target: string[]toLoad: string[]toUnload: string[]@@ -6930,6 +6931,7 @@ toUnload: string[]## ResidencySource — interface @experimental```loadRadius: number+prefetchRadius: numberunloadRadius: numberx: numberz: number@@ -7260,10 +7262,12 @@ type: string```cleanup: ((ctx: SceneContext) => void) | undefineddata: SceneData | undefined+discardPrepared: (() => number) | undefinedexternalEntities: (() => ReadonlyMap<number, Entity>) | undefinedname: stringonPhase: ((phase: string, ms: number) => void) | undefinedpath: string | undefined+prepare: (() => Promise<void>) | undefinedsetup: ((ctx: SceneContext) => void | Promise<void>) | undefinedsystems: { schedule: Schedule; system: SystemDef; }[] | undefined```@@ -7339,6 +7343,7 @@ ResourceDef<SceneManagerState>```@internal assetScopeFor: (name: string) => AssetScope | nullbringToTop: (name: string) => void+discardPrepared: (name: string) => numbergetActive: () => string | nullgetActiveScenes: () => string[]getInitial: () => string | null@@ -7354,6 +7359,7 @@ isTransitioning: () => booleanload: (name: string, onProgress?: SceneLoadProgressCallback) => Promise<SceneContext>loadAdditive: (name: string, onProgress?: SceneLoadProgressCallback) => Promise<SceneContext>pause: (name: string) => void+prepare: (name: string) => Promise<void>register: (config: SceneConfig) => voidreload: (options?: TransitionOptions) => Promise<void>reset: () => void@@ -10092,16 +10098,24 @@ top: number```assetRefsByCell: Record<string, number>authoredCellEntityCounts: Record<string, number>+cancelCount: number+cancelledRefs: numbercellCount: numbercellEntityCounts: Record<string, number>cellRenderCounts: Record<string, number>cellRows: Record<string, { id: number; entity: number; }[]>delivery: Record<string, { phases: Record<string, number>; deliveryMs: number; }>desiredCells: string[]+lastDemandToResidentMs: numberloadCount: numberloadingCells: string[]persistentEntities: numberpersistentHandles: number[]+prefetchCells: string[]+prefetchHits: number+prefetchMisses: number+prepareCount: number+preparedCells: string[]residentCells: string[]sourceCount: numberstreamed: boolean@@ -10111,8 +10125,10 @@ unloadingCells: string[]## WorldStreamHost — interface @experimental```+discardPrepared: (name: string) => numberisLoaded: (name: string) => booleanloadAdditive: (name: string) => Promise<unknown>+prepare: (name: string) => Promise<void>register: (config: SceneConfig) => voidunload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>```@@ -10133,10 +10149,18 @@ static prototype: WorldStreamer## WorldStreamerStatus — interface @experimental```+cancelCount: number+cancelledRefs: numbercellCount: numberdesiredCells: string[]+lastDemandToResidentMs: numberloadCount: numberloadingCells: string[]+prefetchCells: string[]+prefetchHits: number+prefetchMisses: number+prepareCount: number+preparedCells: string[]residentCells: string[]sourceCount: numberunloadCount: number@@ -10157,6 +10181,7 @@ ComponentDef<WorldStreamingSourceData>```enabled: booleanloadRadius: number+prefetchRadius: numberunloadRadius: number```diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 894c6f4e1..ea120fe0a 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1958,7 +1958,7 @@ y: number## CellResidency — type @experimental```-'unloaded' | 'loading' | 'resident' | 'unloading'+'unloaded' | 'preparing' | 'prepared' | 'publishing' | 'resident' | 'unloading'```## Census — interface @experimental@@ -7168,6 +7168,7 @@ static prototype: ResMutInstance<any>## ResidencyDecision — interface @experimental```+prefetch: string[]target: string[]toLoad: string[]toUnload: string[]@@ -7176,6 +7177,7 @@ toUnload: string[]## ResidencySource — interface @experimental```loadRadius: number+prefetchRadius: numberunloadRadius: numberx: numberz: number@@ -7506,10 +7508,12 @@ type: string```cleanup: ((ctx: SceneContext) => void) | undefineddata: SceneData | undefined+discardPrepared: (() => number) | undefinedexternalEntities: (() => ReadonlyMap<number, Entity>) | undefinedname: stringonPhase: ((phase: string, ms: number) => void) | undefinedpath: string | undefined+prepare: (() => Promise<void>) | undefinedsetup: ((ctx: SceneContext) => void | Promise<void>) | undefinedsystems: { schedule: Schedule; system: SystemDef; }[] | undefined```@@ -7585,6 +7589,7 @@ ResourceDef<SceneManagerState>```@internal assetScopeFor: (name: string) => AssetScope | nullbringToTop: (name: string) => void+discardPrepared: (name: string) => numbergetActive: () => string | nullgetActiveScenes: () => string[]getInitial: () => string | null@@ -7600,6 +7605,7 @@ isTransitioning: () => booleanload: (name: string, onProgress?: SceneLoadProgressCallback) => Promise<SceneContext>loadAdditive: (name: string, onProgress?: SceneLoadProgressCallback) => Promise<SceneContext>pause: (name: string) => void+prepare: (name: string) => Promise<void>register: (config: SceneConfig) => voidreload: (options?: TransitionOptions) => Promise<void>reset: () => void@@ -10344,16 +10350,24 @@ top: number```assetRefsByCell: Record<string, number>authoredCellEntityCounts: Record<string, number>+cancelCount: number+cancelledRefs: numbercellCount: numbercellEntityCounts: Record<string, number>cellRenderCounts: Record<string, number>cellRows: Record<string, { id: number; entity: number; }[]>delivery: Record<string, { phases: Record<string, number>; deliveryMs: number; }>desiredCells: string[]+lastDemandToResidentMs: numberloadCount: numberloadingCells: string[]persistentEntities: numberpersistentHandles: number[]+prefetchCells: string[]+prefetchHits: number+prefetchMisses: number+prepareCount: number+preparedCells: string[]residentCells: string[]sourceCount: numberstreamed: boolean@@ -10363,8 +10377,10 @@ unloadingCells: string[]## WorldStreamHost — interface @experimental```+discardPrepared: (name: string) => numberisLoaded: (name: string) => booleanloadAdditive: (name: string) => Promise<unknown>+prepare: (name: string) => Promise<void>register: (config: SceneConfig) => voidunload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>```@@ -10385,10 +10401,18 @@ static prototype: WorldStreamer## WorldStreamerStatus — interface @experimental```+cancelCount: number+cancelledRefs: numbercellCount: numberdesiredCells: string[]+lastDemandToResidentMs: numberloadCount: numberloadingCells: string[]+prefetchCells: string[]+prefetchHits: number+prefetchMisses: number+prepareCount: number+preparedCells: string[]residentCells: string[]sourceCount: numberunloadCount: number@@ -10409,6 +10433,7 @@ ComponentDef<WorldStreamingSourceData>```enabled: booleanloadRadius: number+prefetchRadius: numberunloadRadius: number```diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 76a3a5200..65a17ae9e 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1958,7 +1958,7 @@ y: number## CellResidency — type @experimental```-'unloaded' | 'loading' | 'resident' | 'unloading'+'unloaded' | 'preparing' | 'prepared' | 'publishing' | 'resident' | 'unloading'```## Census — interface @experimental@@ -6929,6 +6929,7 @@ static prototype: ResMutInstance<any>## ResidencyDecision — interface @experimental```+prefetch: string[]target: string[]toLoad: string[]toUnload: string[]@@ -6937,6 +6938,7 @@ toUnload: string[]## ResidencySource — interface @experimental```loadRadius: number+prefetchRadius: numberunloadRadius: numberx: numberz: number@@ -7267,10 +7269,12 @@ type: string```cleanup: ((ctx: SceneContext) => void) | undefineddata: SceneData | undefined+discardPrepared: (() => number) | undefinedexternalEntities: (() => ReadonlyMap<number, Entity>) | undefinedname: stringonPhase: ((phase: string, ms: number) => void) | undefinedpath: string | undefined+prepare: (() => Promise<void>) | undefinedsetup: ((ctx: SceneContext) => void | Promise<void>) | undefinedsystems: { schedule: Schedule; system: SystemDef; }[] | undefined```@@ -7346,6 +7350,7 @@ ResourceDef<SceneManagerState>```@internal assetScopeFor: (name: string) => AssetScope | nullbringToTop: (name: string) => void+discardPrepared: (name: string) => numbergetActive: () => string | nullgetActiveScenes: () => string[]getInitial: () => string | null@@ -7361,6 +7366,7 @@ isTransitioning: () => booleanload: (name: string, onProgress?: SceneLoadProgressCallback) => Promise<SceneContext>loadAdditive: (name: string, onProgress?: SceneLoadProgressCallback) => Promise<SceneContext>pause: (name: string) => void+prepare: (name: string) => Promise<void>register: (config: SceneConfig) => voidreload: (options?: TransitionOptions) => Promise<void>reset: () => void@@ -10120,16 +10126,24 @@ top: number```assetRefsByCell: Record<string, number>authoredCellEntityCounts: Record<string, number>+cancelCount: number+cancelledRefs: numbercellCount: numbercellEntityCounts: Record<string, number>cellRenderCounts: Record<string, number>cellRows: Record<string, { id: number; entity: number; }[]>delivery: Record<string, { phases: Record<string, number>; deliveryMs: number; }>desiredCells: string[]+lastDemandToResidentMs: numberloadCount: numberloadingCells: string[]persistentEntities: numberpersistentHandles: number[]+prefetchCells: string[]+prefetchHits: number+prefetchMisses: number+prepareCount: number+preparedCells: string[]residentCells: string[]sourceCount: numberstreamed: boolean@@ -10139,8 +10153,10 @@ unloadingCells: string[]## WorldStreamHost — interface @experimental```+discardPrepared: (name: string) => numberisLoaded: (name: string) => booleanloadAdditive: (name: string) => Promise<unknown>+prepare: (name: string) => Promise<void>register: (config: SceneConfig) => voidunload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>```@@ -10161,10 +10177,18 @@ static prototype: WorldStreamer## WorldStreamerStatus — interface @experimental```+cancelCount: number+cancelledRefs: numbercellCount: numberdesiredCells: string[]+lastDemandToResidentMs: numberloadCount: numberloadingCells: string[]+prefetchCells: string[]+prefetchHits: number+prefetchMisses: number+prepareCount: number+preparedCells: string[]residentCells: string[]sourceCount: numberunloadCount: number@@ -10185,6 +10209,7 @@ ComponentDef<WorldStreamingSourceData>```enabled: booleanloadRadius: number+prefetchRadius: numberunloadRadius: number```diff --git a/sdk/src/residency/WorldStreamer.ts b/sdk/src/residency/WorldStreamer.tsindex 3fd29c8b9..3ebc65f3c 100644--- a/sdk/src/residency/WorldStreamer.ts+++ b/sdk/src/residency/WorldStreamer.ts@@ -22,8 +22,17 @@ import type { SceneConfig } from '../scene/sceneManager';import { defineResource } from '../ecs/resource';import { log } from '../util/logger';-/** Where a cell is in its lifetime. @experimental */-export type CellResidency = 'unloaded' | 'loading' | 'resident' | 'unloading';+/**+ * Where a cell is in its lifetime.+ *+ * `prepared` is the one worth naming: fetched, decoded, its assets acquired, and+ * carrying not one runtime entity. Nothing in the world can observe it, because+ * there is nothing there to observe.+ *+ * @experimental+ */+export type CellResidency =+ 'unloaded' | 'preparing' | 'prepared' | 'publishing' | 'resident' | 'unloading';/*** The slice of `SceneManager` the streamer drives. `SceneManagerState` satisfies@@ -33,6 +42,8 @@ export type CellResidency = 'unloaded' | 'loading' | 'resident' | 'unloading';*/export interface WorldStreamHost {register(config: SceneConfig): void;+ prepare(name: string): Promise<void>;+ discardPrepared(name: string): number;loadAdditive(name: string): Promise<unknown>;unload(name: string, options?: { keepPersistent?: boolean }): Promise<void>;isLoaded(name: string): boolean;@@ -44,12 +55,29 @@ export interface WorldStreamerStatus {sourceCount: number;/** Cells that should exist right now, load radius unioned with the kept band. */desiredCells: string[];+ /** Cells worth readying: what any source is close enough to speculate about. */+ prefetchCells: string[];residentCells: string[];+ /** Ready and holding nothing the world can see. */+ preparedCells: string[];loadingCells: string[];unloadingCells: string[];/** Cells brought in since boot, and cells taken out. Churn is the difference. */loadCount: number;unloadCount: number;+ /** Preparations begun, and preparations thrown away unpublished. */+ prepareCount: number;+ cancelCount: number;+ /** Acquisitions given back by discarding readiness — not by unloading. */+ cancelledRefs: number;+ /**+ * Publications that had a prepared cell waiting, and publications that had to+ * do the preparing themselves. The second is a player arriving early.+ */+ prefetchHits: number;+ prefetchMisses: number;+ /** Demanded to resident, milliseconds — what a prefetch hit is worth. */+ lastDemandToResidentMs: number;}interface CellState {@@ -57,12 +85,18 @@ interface CellState {residency: CellResidency;/** What the last reconciliation asked for; the async completions re-read it. */desired: boolean;+ /** Whether any source is close enough to speculate about it. */+ speculated: boolean;/** Where this cell's last load spent its time, phase by phase. */phases: Record<string, number>;/** When the load was issued, so `delivery` is measured and not guessed. */issuedAt: number;/** Issue to resident, in wall time. Most of it is not the engine working. */delivery: number;+ /** When it became demanded, so the latency a player feels can be measured. */+ demandedAt: number;+ /** Whether the preparation now running was begun because it was ALREADY wanted. */+ preparedUnderDemand: boolean;}export class WorldStreamer {@@ -73,6 +107,12 @@ export class WorldStreamer {private sourceCount_ = 0;private loadCount_ = 0;private unloadCount_ = 0;+ private prepareCount_ = 0;+ private cancelCount_ = 0;+ private cancelledRefs_ = 0;+ private prefetchHits_ = 0;+ private prefetchMisses_ = 0;+ private lastDemandToResident_ = 0;constructor(host: WorldStreamHost) {this.host_ = host;@@ -91,8 +131,9 @@ export class WorldStreamer {for (const cell of manifest.cells) {this.host_.register(sceneConfig?.(cell) ?? { name: cell.name, path: cell.path });this.cells_.set(cell.name, {- cell, residency: 'unloaded', desired: false,+ cell, residency: 'unloaded', desired: false, speculated: false,phases: {}, issuedAt: 0, delivery: 0,+ demandedAt: 0, preparedUnderDemand: false,});}}@@ -138,18 +179,35 @@ export class WorldStreamer {if (this.cells_.size === 0) return;const resident = new Set<string>();for (const [name, state] of this.cells_) {- // Loading counts as resident so the decision does not ask twice, and+ // Publishing counts as resident so the decision does not ask twice, and// unloading does not, so a source that came back re-issues the load.- if (state.residency === 'resident' || state.residency === 'loading') resident.add(name);+ if (state.residency === 'resident' || state.residency === 'publishing') resident.add(name);}const cells: WorldCell[] = [];for (const state of this.cells_.values()) cells.push(state.cell);const decision = desiredResidency(cells, sources, resident);const target = new Set(decision.target);- for (const [name, state] of this.cells_) state.desired = target.has(name);+ const speculated = new Set(decision.prefetch);+ const now = performance.now();+ for (const [name, state] of this.cells_) {+ const wanted = target.has(name);+ // The moment demand begins, so what a prefetch hit is worth can be+ // measured rather than asserted.+ if (wanted && !state.desired) state.demandedAt = now;+ state.desired = wanted;+ state.speculated = speculated.has(name);+ }+ // Demanded first and nearest first: a place a player is walking into+ // outranks one they might. Then speculation, then what nobody needs.for (const name of decision.toLoad) this.step_(name);+ for (const name of decision.prefetch) if (!target.has(name)) this.step_(name);for (const name of decision.toUnload) this.step_(name);+ for (const [name, state] of this.cells_) {+ if (state.residency === 'prepared' && !state.desired && !state.speculated) {+ this.step_(name);+ }+ }}/** Everything goes; the cells stay registered. For a world being torn down. */@@ -162,20 +220,30 @@ export class WorldStreamer {status(): WorldStreamerStatus {const desiredCells: string[] = [];+ const prefetchCells: string[] = [];const residentCells: string[] = [];+ const preparedCells: string[] = [];const loadingCells: string[] = [];const unloadingCells: string[] = [];for (const [name, state] of this.cells_) {if (state.desired) desiredCells.push(name);+ if (state.speculated) prefetchCells.push(name);if (state.residency === 'resident') residentCells.push(name);- else if (state.residency === 'loading') loadingCells.push(name);- else if (state.residency === 'unloading') unloadingCells.push(name);+ else if (state.residency === 'prepared') preparedCells.push(name);+ else if (state.residency === 'preparing' || state.residency === 'publishing') {+ loadingCells.push(name);+ } else if (state.residency === 'unloading') unloadingCells.push(name);}return {cellCount: this.cells_.size,sourceCount: this.sourceCount_,- desiredCells, residentCells, loadingCells, unloadingCells,+ desiredCells, prefetchCells, residentCells, preparedCells,+ loadingCells, unloadingCells,loadCount: this.loadCount_, unloadCount: this.unloadCount_,+ prepareCount: this.prepareCount_, cancelCount: this.cancelCount_,+ cancelledRefs: this.cancelledRefs_,+ prefetchHits: this.prefetchHits_, prefetchMisses: this.prefetchMisses_,+ lastDemandToResidentMs: this.lastDemandToResident_,};}@@ -188,20 +256,57 @@ export class WorldStreamer {private step_(name: string): void {const state = this.cells_.get(name);if (!state) return;- if (state.residency === 'loading' || state.residency === 'unloading') return;- if (state.desired && state.residency === 'unloaded') this.beginLoad_(name, state);- else if (!state.desired && state.residency === 'resident') this.beginUnload_(name, state);+ if (state.residency === 'preparing' || state.residency === 'publishing'+ || state.residency === 'unloading') return;+ if (state.residency === 'unloaded' && (state.desired || state.speculated)) {+ this.beginPrepare_(name, state);+ } else if (state.residency === 'prepared' && state.desired) {+ this.beginLoad_(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+ // happens to be ready.+ this.cancelledRefs_ += this.host_.discardPrepared(name);+ state.residency = 'unloaded';+ this.cancelCount_++;+ } else if (state.residency === 'resident' && !state.desired) {+ this.beginUnload_(name, state);+ }}- private beginLoad_(name: string, state: CellState): void {- state.residency = 'loading';+ private beginPrepare_(name: string, state: CellState): void {+ state.residency = 'preparing';state.phases = {};state.issuedAt = performance.now();+ state.preparedUnderDemand = state.desired;+ this.prepareCount_++;+ Promise.resolve(this.host_.prepare(name)).then(+ () => {+ state.residency = 'prepared';+ // What finished was begun against a world that has moved. Whether+ // this cell is still wanted — or wanted now when it was not — is+ // asked again here rather than assumed from when it started.+ this.step_(name);+ },+ (err) => {+ state.residency = 'unloaded';+ log.error('residency', `cell "${name}" did not prepare`, err);+ },+ );+ }++ private beginLoad_(name: string, state: CellState): void {+ state.residency = 'publishing';+ if (state.preparedUnderDemand) this.prefetchMisses_++;+ else this.prefetchHits_++;this.loadCount_++;Promise.resolve(this.host_.loadAdditive(name)).then(() => {state.residency = 'resident';state.delivery = performance.now() - state.issuedAt;+ if (state.demandedAt > 0) {+ this.lastDemandToResident_ = performance.now() - state.demandedAt;+ }this.step_(name);},(err) => {diff --git a/sdk/src/residency/cells.ts b/sdk/src/residency/cells.tsindex b5ccf8da1..77a90cde9 100644--- a/sdk/src/residency/cells.ts+++ b/sdk/src/residency/cells.ts@@ -58,12 +58,21 @@ export interface ResidencySource {z: number;loadRadius: number;unloadRadius: number;+ /** How early this source is worth preparing for. Never below `loadRadius`. */+ prefetchRadius: number;}-/** What residency should be, and the two moves that get there. @experimental */+/** What residency should be, and the moves that get there. @experimental */export interface ResidencyDecision {/** Every cell that should exist after this tick, in manifest order. */target: string[];+ /**+ * Cells worth PREPARING: near enough that a source may soon want them. A+ * superset of the demanded ones in the ordinary case, but not by rule — a+ * cell held by hysteresis can sit past every prefetch radius.+ */+ prefetch: string[];+ /** Demanded and not resident, nearest first: what to publish. */toLoad: string[];toUnload: string[];}@@ -94,26 +103,36 @@ export function desiredResidency(resident: ReadonlySet<string>,): ResidencyDecision {const target: string[] = [];- const toLoad: string[] = [];+ const prefetch: string[] = [];const toUnload: string[] = [];+ /** Demanded-and-absent cells with how far the nearest source is. */+ const pending: Array<{ name: string; distance: number }> = [];for (const cell of cells) {let wanted = false;let kept = false;+ let speculated = false;+ let nearest = Infinity;for (const source of sources) {const distance = distanceToCell(cell, source.x, source.z);- if (distance <= source.loadRadius) { wanted = true; break; }+ if (distance < nearest) nearest = distance;+ if (distance <= source.loadRadius) wanted = true;// An authored band that is not a band is not one the streamer invents:// the wider of the two is the only reading under which a resident cell// cannot be dropped by the same distance that just asked for it.- if (distance <= Math.max(source.loadRadius, source.unloadRadius)) kept = true;+ else if (distance <= Math.max(source.loadRadius, source.unloadRadius)) kept = true;+ if (distance <= Math.max(source.loadRadius, source.prefetchRadius)) speculated = true;}+ if (speculated) prefetch.push(cell.name);const isResident = resident.has(cell.name);if (wanted || (kept && isResident)) {target.push(cell.name);- if (!isResident) toLoad.push(cell.name);+ if (!isResident) pending.push({ name: cell.name, distance: nearest });} else if (isResident) {toUnload.push(cell.name);}}- return { target, toLoad, toUnload };+ // Nearest first, and stable: two cells a source is equally far from keep the+ // order the cook wrote them in rather than one the sort invented.+ pending.sort((a, b) => a.distance - b.distance);+ return { target, prefetch, toLoad: pending.map((p) => p.name), toUnload };}diff --git a/sdk/src/residency/components.ts b/sdk/src/residency/components.tsindex 48198c764..16412829a 100644--- a/sdk/src/residency/components.ts+++ b/sdk/src/residency/components.ts@@ -56,6 +56,13 @@ export const WorldPersistent: ComponentDef<{}> = defineTag('WorldPersistent');/** The fields of the `WorldStreamingSource` component. @experimental */export interface WorldStreamingSourceData {+ /**+ * Cells this close are PREPARED — fetched, decoded, their assets acquired —+ * without being brought into the world. Speculation, never authority: a+ * prepared cell a source turns away from is thrown away, not published.+ * Clamped up to `loadRadius`.+ */+ prefetchRadius: number;/** Cells whose nearest edge is within this distance are asked for. */loadRadius: number;/**@@ -79,9 +86,10 @@ export interface WorldStreamingSourceData {export const WorldStreamingSource: ComponentDef<WorldStreamingSourceData> =defineComponent<WorldStreamingSourceData>('WorldStreamingSource',- { loadRadius: 2000, unloadRadius: 3000, enabled: true },+ { prefetchRadius: 3000, loadRadius: 2000, unloadRadius: 3000, enabled: true },{fields: {+ prefetchRadius: { min: 0, unit: 'wu', tooltip: 'Cells this close are prepared, not shown.' },loadRadius: { min: 0, unit: 'wu', tooltip: 'Cells this close are brought in.' },unloadRadius: { min: 0, unit: 'wu', tooltip: 'Resident cells are kept until past this.' },},diff --git a/sdk/src/residency/report.ts b/sdk/src/residency/report.tsindex 4524f3245..79a763632 100644--- a/sdk/src/residency/report.ts+++ b/sdk/src/residency/report.ts@@ -27,11 +27,22 @@ export interface WorldResidencyReport {cellCount: number;sourceCount: number;desiredCells: string[];+ /** Cells any source is close enough to speculate about. */+ prefetchCells: string[];residentCells: string[];+ /** Ready, owning assets, and holding nothing the world can see. */+ preparedCells: string[];loadingCells: string[];unloadingCells: string[];loadCount: number;unloadCount: number;+ prepareCount: number;+ cancelCount: number;+ /** Acquisitions given back by discarding readiness — not by unloading. */+ cancelledRefs: number;+ prefetchHits: number;+ prefetchMisses: number;+ lastDemandToResidentMs: number;/** Live entities each resident cell owns. Absent from the map = not resident. */cellEntityCounts: Record<string, number>;/** Of those, how many draw anything. */@@ -60,8 +71,10 @@ export interface WorldResidencyReport {const EMPTY: WorldResidencyReport = {streamed: false, cellCount: 0, sourceCount: 0,- desiredCells: [], residentCells: [], loadingCells: [], unloadingCells: [],- loadCount: 0, unloadCount: 0,+ desiredCells: [], prefetchCells: [], residentCells: [], preparedCells: [],+ loadingCells: [], unloadingCells: [],+ loadCount: 0, unloadCount: 0, prepareCount: 0, cancelCount: 0, cancelledRefs: 0,+ prefetchHits: 0, prefetchMisses: 0, lastDemandToResidentMs: 0,cellEntityCounts: {}, cellRenderCounts: {}, assetRefsByCell: {},authoredCellEntityCounts: {}, cellRows: {},persistentEntities: 0, persistentHandles: [], delivery: {},@@ -111,11 +124,19 @@ export function worldResidencyReport(app: App): WorldResidencyReport {cellCount: status.cellCount,sourceCount: status.sourceCount,desiredCells: status.desiredCells,+ prefetchCells: status.prefetchCells,residentCells: status.residentCells,+ preparedCells: status.preparedCells,loadingCells: status.loadingCells,unloadingCells: status.unloadingCells,loadCount: status.loadCount,unloadCount: status.unloadCount,+ prepareCount: status.prepareCount,+ cancelCount: status.cancelCount,+ cancelledRefs: status.cancelledRefs,+ prefetchHits: status.prefetchHits,+ prefetchMisses: status.prefetchMisses,+ lastDemandToResidentMs: status.lastDemandToResidentMs,cellEntityCounts, cellRenderCounts, assetRefsByCell, authoredCellEntityCounts,cellRows,persistentEntities: persistent.length,diff --git a/sdk/src/residency/residencyPlugin.ts b/sdk/src/residency/residencyPlugin.tsindex 46d9f8193..233ce0f2f 100644--- a/sdk/src/residency/residencyPlugin.ts+++ b/sdk/src/residency/residencyPlugin.ts@@ -42,6 +42,7 @@ export const worldResidencySystem = defineSystem(z: at.z ?? 0,loadRadius: source.loadRadius,unloadRadius: source.unloadRadius,+ prefetchRadius: source.prefetchRadius,});}streamer.update(sources);diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.tsindex 1acb4a189..cdf2530f8 100644--- a/sdk/src/runtime/runtimeLoader.ts+++ b/sdk/src/runtime/runtimeLoader.ts@@ -48,6 +48,7 @@ import { log } from '../util/logger';import type { AotManifest } from '../ecs/aot/AotSystems';import { type RuntimeAssetSource, type TextureParams } from './runtimeAssets';import { loadSpineAssets, applySpineEntities, type SpineAssetInfo } from '../spine/loadSpineScene';+import type { SceneAssetResult } from '../asset/Assets';import { DragonBonesPlugin } from '../dragonbones/DragonBonesPlugin';import type { DragonBonesManager } from '../dragonbones/DragonBonesManager';import { loadDragonBonesAssets, applyDragonBonesEntities, type DragonBonesAssetInfo } from '../dragonbones/loadDragonBonesScene';@@ -301,7 +302,40 @@ export function sceneUsesPhysics(sceneData: SceneData): boolean {return false;}-export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promise<void> {+/**+ * A cell's load, done as far as it can go without the world seeing anything.+ *+ * Preparation may speculate about future residency and may own data and assets;+ * only publication may create runtime entities. That is the whole contract, and+ * it is what makes "prepared" impossible to observe: there is nothing to see.+ *+ * @experimental+ */+export interface PreparedRuntimeScene {+ readonly name: string | undefined;+ /** What publication still needs; nothing here is in the world. */+ readonly options: LoadRuntimeSceneOptions;+ readonly sceneData: SceneData;+ readonly assetResult: SceneAssetResult;+ readonly spineManager: SpineManager | null;+ readonly spineAssetInfo: Map<string, SpineAssetInfo>;+ readonly dragonBonesManager: DragonBonesManager | null;+ readonly dragonBonesAssetInfo: Map<string, DragonBonesAssetInfo>;+ readonly discovered: ReturnType<typeof discoverSceneAssets>;+}++/**+ * Everything a scene load can do before the world can tell: fetch, expand,+ * acquire, install the subsystems it needs. Creates no entities.+ *+ * The receipts are OWNED by what this returns — publishing moves them to the+ * scene, discarding gives them back. Never both, never acquired twice.+ *+ * @experimental+ */+export async function prepareRuntimeScene(+ options: LoadRuntimeSceneOptions,+): Promise<PreparedRuntimeScene> {const { app, module, source, physicsConfig, physicsEnabled, uiTheme, uiThemeOverrides, sceneName } = options;const onPhase = options.onPhase;const timed = async <T>(phase: string, run: () => Promise<T> | T): Promise<T> => {@@ -500,6 +534,44 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis// The one place a packaged scene's entities come into being. `externalEntities`// is what lets a streamed cell name the persistent world: without it a cross// document reference resolves to nothing, quietly.++ return {+ name: sceneName, options, sceneData, assetResult,+ spineManager, spineAssetInfo, dragonBonesManager, dragonBonesAssetInfo, discovered,+ };+}+++/**+ * Bring a prepared scene into the world.+ *+ * The publication boundary: before this returns no system has seen a single one+ * of the cell's entities, because none of them existed. Nothing downstream has+ * to learn to ignore a half-arrived cell.+ *+ * @experimental+ */+export async function publishRuntimeScene(+ prepared: PreparedRuntimeScene,+ // Resolved HERE and not at preparation: between the two the target may have+ // gone, the world may have switched, a generation may have moved. A prepared+ // scene holding a runtime handle would be holding a guess.+ now?: { externalEntities?: ReadonlyMap<number, Entity> },+): Promise<void> {+ const { sceneData, assetResult, spineManager, spineAssetInfo,+ dragonBonesManager, dragonBonesAssetInfo, discovered } = prepared;+ const options = now?.externalEntities+ ? { ...prepared.options, externalEntities: now.externalEntities }+ : prepared.options;+ const { app, module, uiTheme, uiThemeOverrides, sceneName } = options;+ const onPhase = options.onPhase;+ const timed = async <T>(phase: string, run: () => Promise<T> | T): Promise<T> => {+ if (!onPhase) return run();+ const began = performance.now();+ try { return await run(); } finally { onPhase(phase, performance.now() - began); }+ };+ void discovered;+const entityMap = await timed('spawn',() => loadSceneData(app.world, sceneData, options.externalEntities));// Which document row each entity came from, when someone is keeping track@@ -545,6 +617,15 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis}}+/**+ * Prepare a scene and publish it. What every caller outside residency wants, and+ * the shape the two halves are defined against.+ */+export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promise<void> {+ await publishRuntimeScene(await prepareRuntimeScene(options));+}++export function createRuntimeSceneConfig(name: string,sceneData: SceneData | undefined,@@ -554,27 +635,41 @@ export function createRuntimeSceneConfig(// Built first and closed over, so whoever sets `externalEntities` / `onPhase`// on the CONFIG is honoured here too: declared in one place and read in// another, a cell's reference to the persistent world resolved to nothing.+ // Held by the config, which IS the per-scene object: a prepared cell has one+ // place to live and one owner to release it.+ let prepared: PreparedRuntimeScene | null = null;+ const readied = async (): Promise<PreparedRuntimeScene> => {+ let data = sceneData;+ if (!data) {+ // Lazy scene: fetched by path through the per-App runtime Assets, so+ // the data arrives via the realm's own backend — http on web, wx fs+ // on WeChat — and only when something asks for the scene.+ if (!scenePath) throw new Error(`scene "${name}" registered with neither data nor path`);+ const began = performance.now();+ data = await options.app.getResource(AssetsResource).fetchJson<SceneData>(scenePath);+ config.onPhase?.('fetch', performance.now() - began);+ }+ return prepareRuntimeScene({+ ...options, sceneData: data, sceneName: name, onPhase: config.onPhase,+ });+ };const config: SceneConfig = {name,+ async prepare() {+ if (prepared === null) prepared = await readied();+ },+ discardPrepared() {+ // Speculation is not authority: what nobody asked for is given back,+ // receipts included, rather than published because it was ready.+ const owed = prepared?.assetResult.scope.size ?? 0;+ prepared?.assetResult.scope.releaseAll();+ prepared = null;+ return owed;+ },async setup() {- let data = sceneData;- if (!data) {- // Lazy scene: fetch by path through the per-App runtime Assets- // (installed by initRuntime before any scene loads), so the data- // arrives via the realm's backend/resolver — http on web, wx fs- // on WeChat — only when the game actually switches to it.- if (!scenePath) throw new Error(`scene "${name}" registered with neither data nor path`);- const began = performance.now();- data = await options.app.getResource(AssetsResource).fetchJson<SceneData>(scenePath);- config.onPhase?.('fetch', performance.now() - began);- }- await loadRuntimeScene({- ...options,- sceneData: data,- sceneName: name,- externalEntities: config.externalEntities?.(),- onPhase: config.onPhase,- });+ const ready = prepared ?? await readied();+ prepared = null;+ await publishRuntimeScene(ready, { externalEntities: config.externalEntities?.() });},};return config;diff --git a/sdk/src/scene/sceneManager.ts b/sdk/src/scene/sceneManager.tsindex 479066148..48cd48417 100644--- a/sdk/src/scene/sceneManager.ts+++ b/sdk/src/scene/sceneManager.ts@@ -59,6 +59,13 @@ export interface SceneConfig {externalEntities?: () => ReadonlyMap<number, Entity>;/** Where this scene's load spent its time. See {@link SceneLoadOptions.onPhase}. */onPhase?: (phase: string, ms: number) => void;+ /**+ * Do everything this scene's load can do without the world seeing anything —+ * fetch, decode, acquire. Creates no entities; `load` publishes what it left.+ */+ prepare?: () => Promise<void>;+ /** Throw away what `prepare` readied, answering how many receipts came back. */+ discardPrepared?: () => number;}/**@@ -398,6 +405,24 @@ export class SceneManagerState {return this.loadScene_(name, 'additive', onProgress);}+ /**+ * Ready `name` without bringing it up. A no-op for a scene that declares no+ * preparation, and for one already loaded — there is nothing left to hide.+ */+ async prepare(name: string): Promise<void> {+ if (this.scenes_.has(name)) return;+ await this.configs_.get(name)?.prepare?.();+ }++ /**+ * Give back what {@link prepare} readied, answering how many acquisitions+ * came back with it. Zero for a scene that readied nothing.+ */+ discardPrepared(name: string): number {+ if (this.scenes_.has(name)) return 0;+ return this.configs_.get(name)?.discardPrepared?.() ?? 0;+ }+/*** The one load path. `mode` is the only difference between the two doors —* which is why they were two copies, and why the fix for re-loading a SLEPTdiff --git a/sdk/tests/world-residency.test.ts b/sdk/tests/world-residency.test.tsindex 6cd3e4a25..7aa07f581 100644--- a/sdk/tests/world-residency.test.ts+++ b/sdk/tests/world-residency.test.ts@@ -26,8 +26,9 @@ function cell(x: number, z: number, size = 100): WorldCell {};}-const source = (x: number, z: number, load: number, unload: number): ResidencySource =>- ({ x, z, loadRadius: load, unloadRadius: unload });+const source = (+ x: number, z: number, load: number, unload: number, prefetch = load,+): ResidencySource => ({ x, z, loadRadius: load, unloadRadius: unload, prefetchRadius: prefetch });describe('desiredResidency', () => {it('asks for the cell a source stands in', () => {@@ -81,6 +82,42 @@ describe('desiredResidency', () => {expect(desiredResidency(cells, [left], resident).toUnload).toEqual(['c_0_0']);});+ it('prepares further out than it publishes, and does not publish what it prepared', () => {+ const cells = [cell(0, 0), cell(3, 0)];+ // c_3_0 starts 300 past this source; inside prefetch, outside load.+ const d = desiredResidency(cells, [source(0, 50, 100, 150, 400)], new Set());+ expect(d.prefetch).toEqual(['c_0_0', 'c_3_0']);+ expect(d.target).toEqual(['c_0_0']);+ expect(d.toLoad).toEqual(['c_0_0']);+ });++ it('unions what the sources prepare, the same way it unions what they demand', () => {+ const cells = [cell(0, 0), cell(5, 0)];+ const here = source(50, 50, 10, 20, 60);+ const there = source(550, 50, 10, 20, 60);+ expect(desiredResidency(cells, [here, there], new Set()).prefetch)+ .toEqual(['c_0_0', 'c_5_0']);+ expect(desiredResidency(cells, [there, here], new Set()).prefetch)+ .toEqual(['c_0_0', 'c_5_0']);+ });++ it('never prepares less far than it demands, whatever the author wrote', () => {+ // The wider of the two is what preparation uses. OUTSIDE the cell on+ // purpose: a source standing in one is zero away, and zero is within+ // every radius including the one under test.+ const d = desiredResidency([cell(0, 0)], [source(150, 50, 100, 150, 0)], new Set());+ expect(d.target).toEqual(['c_0_0']);+ expect(d.prefetch).toEqual(['c_0_0']);+ });++ it('publishes the nearest demanded cell first', () => {+ const cells = [cell(3, 0), cell(1, 0), cell(2, 0)];+ // Standing left of all three: c_1_0 is nearest, c_3_0 furthest, and the+ // manifest deliberately lists them out of order.+ const d = desiredResidency(cells, [source(0, 300, 5000, 6000)], new Set());+ expect(d.toLoad).toEqual(['c_1_0', 'c_2_0', 'c_3_0']);+ });+it('partitions on XZ only — a source overhead still holds the ground', () => {// Y is not in the sample at all: a cell is a vertical column, so a source// on a tower's roof keeps the floors below it resident.@@ -91,11 +128,24 @@ describe('desiredResidency', () => {function recordingHost() {const loaded = new Set<string>();+ const readied = new Set<string>();const calls: string[] = [];const pending: Array<() => void> = [];let deferred = false;const host: WorldStreamHost = {register(config) { calls.push(`register:${config.name}`); },+ prepare(name) {+ calls.push(`prepare:${name}`);+ const settle = (): void => { readied.add(name); };+ if (!deferred) { settle(); return Promise.resolve(); }+ return new Promise((resolve) => pending.push(() => { settle(); resolve(); }));+ },+ discardPrepared(name) {+ calls.push(`discard:${name}`);+ // Two receipts per readied cell, so "gave them back" is a number and+ // not the absence of a complaint.+ return readied.delete(name) ? 2 : 0;+ },loadAdditive(name) {calls.push(`load:${name}`);const settle = (): void => { loaded.add(name); };@@ -111,7 +161,7 @@ function recordingHost() {isLoaded: (name) => loaded.has(name),};return {- host, loaded, calls,+ host, loaded, readied, calls,defer(on: boolean) { deferred = on; },settle() { const queued = pending.splice(0); for (const run of queued) run(); },};@@ -160,7 +210,7 @@ describe('WorldStreamer', () => {expect(status.residentCells).toEqual(['c_0_0']);});- it('asks once while a load is in flight, and finishes what the source undid', async () => {+ it('asks once while a preparation is in flight, and drops what the source undid', async () => {const { host, calls, settle, defer } = recordingHost();defer(true);const streamer = new WorldStreamer(host);@@ -168,24 +218,25 @@ describe('WorldStreamer', () => {streamer.update([source(50, 50, 10, 20)]);streamer.update([source(50, 50, 10, 20)]);- expect(calls.filter((c) => c === 'load:c_0_0')).toHaveLength(1);+ expect(calls.filter((c) => c === 'prepare:c_0_0')).toHaveLength(1);- // The source leaves while the load is still in flight. The unload cannot- // be issued yet — but it must not be forgotten, or the cell stays resident- // with nothing asking for it.+ // The source leaves while the preparation is still in flight. What+ // finishes was begun against a world that has moved, so it is asked again+ // — and the answer now is that nobody wants it.streamer.update([source(9999, 9999, 10, 20)]);- expect(calls.filter((c) => c.startsWith('unload:'))).toHaveLength(0);- settle();- await flush();settle();await flush();+ expect(calls).toContain('discard:c_0_0');+ expect(calls.filter((c) => c.startsWith('load:'))).toHaveLength(0);expect(streamer.residencyOf('c_0_0')).toBe('unloaded');});- it('counts a cell that failed to load as absent, so it can be asked for again', async () => {+ it('counts a cell that failed to prepare as absent, so it can be asked for again', async () => {const failing: WorldStreamHost = {register() {},- loadAdditive: () => Promise.reject(new Error('no')),+ prepare: () => Promise.reject(new Error('no')),+ discardPrepared() {},+ loadAdditive: () => Promise.resolve({}),unload: () => Promise.resolve(),isLoaded: () => false,};@@ -195,6 +246,61 @@ describe('WorldStreamer', () => {await flush();expect(streamer.residencyOf('c_0_0')).toBe('unloaded');});++ it('readies a speculated cell and does not publish it', async () => {+ const { host, loaded, readied } = recordingHost();+ const streamer = new WorldStreamer(host);+ streamer.loadManifest(manifest(cell(3, 0)));+ // Inside prefetch, outside load: prepared, and nothing in the world.+ streamer.update([source(0, 50, 100, 150, 400)]);+ await flush();+ expect(streamer.residencyOf('c_3_0')).toBe('prepared');+ expect(readied.has('c_3_0')).toBe(true);+ expect(loaded.has('c_3_0')).toBe(false);+ expect(streamer.status().residentCells).toEqual([]);+ });++ it('publishes what it prepared once demand arrives, and calls that a hit', async () => {+ const { host, loaded } = recordingHost();+ const streamer = new WorldStreamer(host);+ streamer.loadManifest(manifest(cell(3, 0)));+ streamer.update([source(0, 50, 100, 150, 400)]);+ await flush();+ streamer.update([source(280, 50, 100, 150, 400)]);+ await flush();+ expect(loaded.has('c_3_0')).toBe(true);+ const status = streamer.status();+ expect(status.prefetchHits).toBe(1);+ expect(status.prefetchMisses).toBe(0);+ });++ it('calls it a miss when demand arrived before anything was ready', async () => {+ const { host } = recordingHost();+ const streamer = new WorldStreamer(host);+ streamer.loadManifest(manifest(cell(0, 0)));+ streamer.update([source(50, 50, 10, 20)]);+ await flush();+ expect(streamer.status().prefetchMisses).toBe(1);+ expect(streamer.status().prefetchHits).toBe(0);+ });++ it('throws away what a source turned away from, rather than publishing it', async () => {+ const { host, calls, loaded } = recordingHost();+ const streamer = new WorldStreamer(host);+ streamer.loadManifest(manifest(cell(3, 0)));+ streamer.update([source(0, 50, 100, 150, 400)]);+ await flush();+ expect(streamer.residencyOf('c_3_0')).toBe('prepared');+ streamer.update([source(-9999, 50, 100, 150, 400)]);+ await flush();+ expect(calls).toContain('discard:c_3_0');+ expect(loaded.has('c_3_0')).toBe(false);+ expect(streamer.residencyOf('c_3_0')).toBe('unloaded');+ expect(streamer.status().cancelCount).toBe(1);+ // What it acquired came back with it. A discard that forgot the receipts+ // would leak a cell's worth of assets per turn a player takes.+ expect(streamer.status().cancelledRefs).toBe(2);+ });});describe('a handle that no longer names its entity', () => {diff --git a/tools/verify-world-residency.mjs b/tools/verify-world-residency.mjsindex bd1ab8d94..0df4e6dea 100644--- a/tools/verify-world-residency.mjs+++ b/tools/verify-world-residency.mjs@@ -110,6 +110,11 @@ function main() {{ do: 'read', as: 'beaconBack' },{ do: 'tap', key: 'KeyJ', frames: 30 },{ do: 'read', as: 'beaconBlown' },+ // Nobody walked in this launch, so the places the player never reached+ // are still merely READY — which is the only state a discard can be+ // asked about.+ { do: 'tap', key: 'KeyK', frames: 30 },+ { do: 'read', as: 'nobodyAsking' },]);const initial = start.initial;@@ -123,6 +128,18 @@ function main() {&& (initial.streaming.cellRenderCounts[C] ?? 0) === 0,'a cell nobody needs has no entities, no renderers and nothing to probe');+ // ---- Prepared is not resident, and nothing can tell it is there ------+ claim(initial.streaming.preparedCells.includes(B)+ && initial.streaming.preparedCells.includes(C)+ && !initial.streaming.residentCells.includes(B),+ 'places the player may soon want are readied without being brought in',+ `prepared ${JSON.stringify(initial.streaming.preparedCells)}`);+ claim(initial.at.Enemy === undefined && initial.at.Wall === undefined+ && initial.streaming.hunters === 0 && initial.streaming.navAgents === 0+ && entities(initial, B) === undefined,+ 'and nothing they hold is in the world — no entity, no body, no hunter',+ `${initial.streaming.physicsBodies} bodies, ${initial.streaming.hunters} hunter(s)`);+// ---- 6. Two sources are unioned --------------------------------------const scoutOn = start.scoutOn;claim(scoutOn.streaming.sourceCount === 2 && resident(scoutOn, A) && resident(scoutOn, C),@@ -167,6 +184,20 @@ function main() {`beacon at ${start.beaconBlown.combat.targets.Beacon.health}, `+ `canary at ${start.beaconBlown.combat.targets.Canary.health}`);+ // ---- Readiness is not a claim on the world ---------------------------+ const asking = start.nobodyAsking;+ claim(!asking.streaming.preparedCells.includes(B) && !asking.streaming.preparedCells.includes(C)+ && asking.streaming.cancelCount >= 2,+ 'what was merely readied is thrown away when nobody is near it, not published',+ `${asking.streaming.cancelCount} discarded of ${asking.streaming.prepareCount} prepared,`+ + ` still ready ${JSON.stringify(asking.streaming.preparedCells)}`);+ claim(asking.streaming.cancelledRefs > 0,+ 'and the assets it had acquired come back with it',+ `${asking.streaming.cancelledRefs} acquisition(s) returned`);+ claim(asking.at.Enemy === undefined && asking.at.Wall === undefined+ && asking.at.Arch === undefined,+ 'and none of it was published on the way out');+// ---- 2/3/4/7/8. The journey ------------------------------------------const trip = drive(dir, 'journey', [{ do: 'step', frames: 30 },@@ -190,6 +221,12 @@ function main() {claim(atB.ai.found && (atB.ai.visible || atB.ai.hasTarget),'which then notices the player it was not told about',`visible=${atB.ai.visible} hasTarget=${atB.ai.hasTarget}`);+ // The point of readying it early: what the player waited through is the+ // publication, not the fetching and decoding.+ claim(atB.streaming.prefetchHits > 0,+ 'and it was published from something already readied, not fetched on arrival',+ `${atB.streaming.prefetchHits} hit(s), ${atB.streaming.prefetchMisses} miss(es),`+ + ` demand→resident ${atB.streaming.lastDemandToResidentMs.toFixed(1)}ms`);const atC = trip.atC;claim(!resident(atC, B) && entities(atC, B) === undefined && atC.at.Enemy === undefined