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 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.esscene
index 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.ts
index 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 absolute
diff --git a/pipeline/tests/partition-world.test.ts b/pipeline/tests/partition-world.test.ts
index 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.md
index 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: number
unloadRadius: number
x: number
z: number
@@ -7265,10 +7267,12 @@ type: string
```
cleanup: ((ctx: SceneContext) => void) | undefined
data: SceneData | undefined
+discardPrepared: (() => number) | undefined
externalEntities: (() => ReadonlyMap<number, Entity>) | undefined
name: string
onPhase: ((phase: string, ms: number) => void) | undefined
path: string | undefined
+prepare: (() => Promise<void>) | undefined
setup: ((ctx: SceneContext) => void | Promise<void>) | undefined
systems: { schedule: Schedule; system: SystemDef; }[] | undefined
```
@@ -7344,6 +7348,7 @@ ResourceDef<SceneManagerState>
```
@internal assetScopeFor: (name: string) => AssetScope | null
bringToTop: (name: string) => void
+discardPrepared: (name: string) => number
getActive: () => string | null
getActiveScenes: () => string[]
getInitial: () => string | null
@@ -7359,6 +7364,7 @@ isTransitioning: () => boolean
load: (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) => void
reload: (options?: TransitionOptions) => Promise<void>
reset: () => void
@@ -10097,16 +10103,24 @@ top: number
```
assetRefsByCell: Record<string, number>
authoredCellEntityCounts: Record<string, number>
+cancelCount: number
+cancelledRefs: number
cellCount: number
cellEntityCounts: 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: number
loadCount: number
loadingCells: string[]
persistentEntities: number
persistentHandles: number[]
+prefetchCells: string[]
+prefetchHits: number
+prefetchMisses: number
+prepareCount: number
+preparedCells: string[]
residentCells: string[]
sourceCount: number
streamed: boolean
@@ -10116,8 +10130,10 @@ unloadingCells: string[]
## WorldStreamHost — interface @experimental
```
+discardPrepared: (name: string) => number
isLoaded: (name: string) => boolean
loadAdditive: (name: string) => Promise<unknown>
+prepare: (name: string) => Promise<void>
register: (config: SceneConfig) => void
unload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>
```
@@ -10138,10 +10154,18 @@ static prototype: WorldStreamer
## WorldStreamerStatus — interface @experimental
```
+cancelCount: number
+cancelledRefs: number
cellCount: number
desiredCells: string[]
+lastDemandToResidentMs: number
loadCount: number
loadingCells: string[]
+prefetchCells: string[]
+prefetchHits: number
+prefetchMisses: number
+prepareCount: number
+preparedCells: string[]
residentCells: string[]
sourceCount: number
unloadCount: number
@@ -10162,6 +10186,7 @@ ComponentDef<WorldStreamingSourceData>
```
enabled: boolean
loadRadius: number
+prefetchRadius: number
unloadRadius: number
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: number
unloadRadius: number
x: number
z: number
@@ -7458,10 +7460,12 @@ type: string
```
cleanup: ((ctx: SceneContext) => void) | undefined
data: SceneData | undefined
+discardPrepared: (() => number) | undefined
externalEntities: (() => ReadonlyMap<number, Entity>) | undefined
name: string
onPhase: ((phase: string, ms: number) => void) | undefined
path: string | undefined
+prepare: (() => Promise<void>) | undefined
setup: ((ctx: SceneContext) => void | Promise<void>) | undefined
systems: { schedule: Schedule; system: SystemDef; }[] | undefined
```
@@ -7537,6 +7541,7 @@ ResourceDef<SceneManagerState>
```
@internal assetScopeFor: (name: string) => AssetScope | null
bringToTop: (name: string) => void
+discardPrepared: (name: string) => number
getActive: () => string | null
getActiveScenes: () => string[]
getInitial: () => string | null
@@ -7552,6 +7557,7 @@ isTransitioning: () => boolean
load: (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) => void
reload: (options?: TransitionOptions) => Promise<void>
reset: () => void
@@ -10290,16 +10296,24 @@ top: number
```
assetRefsByCell: Record<string, number>
authoredCellEntityCounts: Record<string, number>
+cancelCount: number
+cancelledRefs: number
cellCount: number
cellEntityCounts: 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: number
loadCount: number
loadingCells: string[]
persistentEntities: number
persistentHandles: number[]
+prefetchCells: string[]
+prefetchHits: number
+prefetchMisses: number
+prepareCount: number
+preparedCells: string[]
residentCells: string[]
sourceCount: number
streamed: boolean
@@ -10309,8 +10323,10 @@ unloadingCells: string[]
## WorldStreamHost — interface @experimental
```
+discardPrepared: (name: string) => number
isLoaded: (name: string) => boolean
loadAdditive: (name: string) => Promise<unknown>
+prepare: (name: string) => Promise<void>
register: (config: SceneConfig) => void
unload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>
```
@@ -10331,10 +10347,18 @@ static prototype: WorldStreamer
## WorldStreamerStatus — interface @experimental
```
+cancelCount: number
+cancelledRefs: number
cellCount: number
desiredCells: string[]
+lastDemandToResidentMs: number
loadCount: number
loadingCells: string[]
+prefetchCells: string[]
+prefetchHits: number
+prefetchMisses: number
+prepareCount: number
+preparedCells: string[]
residentCells: string[]
sourceCount: number
unloadCount: number
@@ -10355,6 +10379,7 @@ ComponentDef<WorldStreamingSourceData>
```
enabled: boolean
loadRadius: number
+prefetchRadius: number
unloadRadius: number
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: number
unloadRadius: number
x: number
z: number
@@ -7260,10 +7262,12 @@ type: string
```
cleanup: ((ctx: SceneContext) => void) | undefined
data: SceneData | undefined
+discardPrepared: (() => number) | undefined
externalEntities: (() => ReadonlyMap<number, Entity>) | undefined
name: string
onPhase: ((phase: string, ms: number) => void) | undefined
path: string | undefined
+prepare: (() => Promise<void>) | undefined
setup: ((ctx: SceneContext) => void | Promise<void>) | undefined
systems: { schedule: Schedule; system: SystemDef; }[] | undefined
```
@@ -7339,6 +7343,7 @@ ResourceDef<SceneManagerState>
```
@internal assetScopeFor: (name: string) => AssetScope | null
bringToTop: (name: string) => void
+discardPrepared: (name: string) => number
getActive: () => string | null
getActiveScenes: () => string[]
getInitial: () => string | null
@@ -7354,6 +7359,7 @@ isTransitioning: () => boolean
load: (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) => void
reload: (options?: TransitionOptions) => Promise<void>
reset: () => void
@@ -10092,16 +10098,24 @@ top: number
```
assetRefsByCell: Record<string, number>
authoredCellEntityCounts: Record<string, number>
+cancelCount: number
+cancelledRefs: number
cellCount: number
cellEntityCounts: 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: number
loadCount: number
loadingCells: string[]
persistentEntities: number
persistentHandles: number[]
+prefetchCells: string[]
+prefetchHits: number
+prefetchMisses: number
+prepareCount: number
+preparedCells: string[]
residentCells: string[]
sourceCount: number
streamed: boolean
@@ -10111,8 +10125,10 @@ unloadingCells: string[]
## WorldStreamHost — interface @experimental
```
+discardPrepared: (name: string) => number
isLoaded: (name: string) => boolean
loadAdditive: (name: string) => Promise<unknown>
+prepare: (name: string) => Promise<void>
register: (config: SceneConfig) => void
unload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>
```
@@ -10133,10 +10149,18 @@ static prototype: WorldStreamer
## WorldStreamerStatus — interface @experimental
```
+cancelCount: number
+cancelledRefs: number
cellCount: number
desiredCells: string[]
+lastDemandToResidentMs: number
loadCount: number
loadingCells: string[]
+prefetchCells: string[]
+prefetchHits: number
+prefetchMisses: number
+prepareCount: number
+preparedCells: string[]
residentCells: string[]
sourceCount: number
unloadCount: number
@@ -10157,6 +10181,7 @@ ComponentDef<WorldStreamingSourceData>
```
enabled: boolean
loadRadius: number
+prefetchRadius: number
unloadRadius: number
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: number
unloadRadius: number
x: number
z: number
@@ -7506,10 +7508,12 @@ type: string
```
cleanup: ((ctx: SceneContext) => void) | undefined
data: SceneData | undefined
+discardPrepared: (() => number) | undefined
externalEntities: (() => ReadonlyMap<number, Entity>) | undefined
name: string
onPhase: ((phase: string, ms: number) => void) | undefined
path: string | undefined
+prepare: (() => Promise<void>) | undefined
setup: ((ctx: SceneContext) => void | Promise<void>) | undefined
systems: { schedule: Schedule; system: SystemDef; }[] | undefined
```
@@ -7585,6 +7589,7 @@ ResourceDef<SceneManagerState>
```
@internal assetScopeFor: (name: string) => AssetScope | null
bringToTop: (name: string) => void
+discardPrepared: (name: string) => number
getActive: () => string | null
getActiveScenes: () => string[]
getInitial: () => string | null
@@ -7600,6 +7605,7 @@ isTransitioning: () => boolean
load: (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) => void
reload: (options?: TransitionOptions) => Promise<void>
reset: () => void
@@ -10344,16 +10350,24 @@ top: number
```
assetRefsByCell: Record<string, number>
authoredCellEntityCounts: Record<string, number>
+cancelCount: number
+cancelledRefs: number
cellCount: number
cellEntityCounts: 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: number
loadCount: number
loadingCells: string[]
persistentEntities: number
persistentHandles: number[]
+prefetchCells: string[]
+prefetchHits: number
+prefetchMisses: number
+prepareCount: number
+preparedCells: string[]
residentCells: string[]
sourceCount: number
streamed: boolean
@@ -10363,8 +10377,10 @@ unloadingCells: string[]
## WorldStreamHost — interface @experimental
```
+discardPrepared: (name: string) => number
isLoaded: (name: string) => boolean
loadAdditive: (name: string) => Promise<unknown>
+prepare: (name: string) => Promise<void>
register: (config: SceneConfig) => void
unload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>
```
@@ -10385,10 +10401,18 @@ static prototype: WorldStreamer
## WorldStreamerStatus — interface @experimental
```
+cancelCount: number
+cancelledRefs: number
cellCount: number
desiredCells: string[]
+lastDemandToResidentMs: number
loadCount: number
loadingCells: string[]
+prefetchCells: string[]
+prefetchHits: number
+prefetchMisses: number
+prepareCount: number
+preparedCells: string[]
residentCells: string[]
sourceCount: number
unloadCount: number
@@ -10409,6 +10433,7 @@ ComponentDef<WorldStreamingSourceData>
```
enabled: boolean
loadRadius: number
+prefetchRadius: number
unloadRadius: number
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: number
unloadRadius: number
x: number
z: number
@@ -7267,10 +7269,12 @@ type: string
```
cleanup: ((ctx: SceneContext) => void) | undefined
data: SceneData | undefined
+discardPrepared: (() => number) | undefined
externalEntities: (() => ReadonlyMap<number, Entity>) | undefined
name: string
onPhase: ((phase: string, ms: number) => void) | undefined
path: string | undefined
+prepare: (() => Promise<void>) | undefined
setup: ((ctx: SceneContext) => void | Promise<void>) | undefined
systems: { schedule: Schedule; system: SystemDef; }[] | undefined
```
@@ -7346,6 +7350,7 @@ ResourceDef<SceneManagerState>
```
@internal assetScopeFor: (name: string) => AssetScope | null
bringToTop: (name: string) => void
+discardPrepared: (name: string) => number
getActive: () => string | null
getActiveScenes: () => string[]
getInitial: () => string | null
@@ -7361,6 +7366,7 @@ isTransitioning: () => boolean
load: (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) => void
reload: (options?: TransitionOptions) => Promise<void>
reset: () => void
@@ -10120,16 +10126,24 @@ top: number
```
assetRefsByCell: Record<string, number>
authoredCellEntityCounts: Record<string, number>
+cancelCount: number
+cancelledRefs: number
cellCount: number
cellEntityCounts: 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: number
loadCount: number
loadingCells: string[]
persistentEntities: number
persistentHandles: number[]
+prefetchCells: string[]
+prefetchHits: number
+prefetchMisses: number
+prepareCount: number
+preparedCells: string[]
residentCells: string[]
sourceCount: number
streamed: boolean
@@ -10139,8 +10153,10 @@ unloadingCells: string[]
## WorldStreamHost — interface @experimental
```
+discardPrepared: (name: string) => number
isLoaded: (name: string) => boolean
loadAdditive: (name: string) => Promise<unknown>
+prepare: (name: string) => Promise<void>
register: (config: SceneConfig) => void
unload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>
```
@@ -10161,10 +10177,18 @@ static prototype: WorldStreamer
## WorldStreamerStatus — interface @experimental
```
+cancelCount: number
+cancelledRefs: number
cellCount: number
desiredCells: string[]
+lastDemandToResidentMs: number
loadCount: number
loadingCells: string[]
+prefetchCells: string[]
+prefetchHits: number
+prefetchMisses: number
+prepareCount: number
+preparedCells: string[]
residentCells: string[]
sourceCount: number
unloadCount: number
@@ -10185,6 +10209,7 @@ ComponentDef<WorldStreamingSourceData>
```
enabled: boolean
loadRadius: number
+prefetchRadius: number
unloadRadius: number
```
diff --git a/sdk/src/residency/WorldStreamer.ts b/sdk/src/residency/WorldStreamer.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 SLEPT
diff --git a/sdk/tests/world-residency.test.ts b/sdk/tests/world-residency.test.ts
index 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.mjs
index 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