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.

chore(residency): the subsystem takes a verdict, and the targets that ship a world whole say so

esengineee9bc1011f73
diff --git a/docs/astro/src/content/docs/zh-cn/world/streaming.mdx b/docs/astro/src/content/docs/zh-cn/world/streaming.mdx
index 10fc4a1e0..9a5f3f4e3 100644
--- a/docs/astro/src/content/docs/zh-cn/world/streaming.mdx
+++ b/docs/astro/src/content/docs/zh-cn/world/streaming.mdx
@@ -37,7 +37,7 @@ world.insert(sun, WorldPersistent, {});
residency 到底能不能移除它。
</Aside>
-## 请求"地方存在":流送源
+## 请求地方存在:流送源
一个格子之所以存在,是因为有**源**靠近它:
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index af8a4d01c..526196719 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 91,
- "experimental": 1766,
+ "experimental": 1790,
"deprecated": 3
},
- "total": 1970,
+ "total": 1994,
"subsystems": [
{
"id": "ecs",
@@ -130,6 +130,21 @@
"transitionTo"
]
},
+ {
+ "id": "residency",
+ "title": "World residency — streaming a world by cells",
+ "titleZh": "世界 residency —— 按格子流送世界",
+ "tier": "experimental",
+ "why": "one shape of world proven end to end: a square XZ grid cut at cook time, loaded synchronously. What a game asks for is settled; what a big one needs after it — priority, budget, a level of detail for what is absent — is not",
+ "whyZh": "端到端证明的只有一种世界形状:cook 时切出的方形 XZ 网格,同步加载。一个游戏怎么提要求已经定了;大世界在它之后还需要的东西——优先级、预算、缺席内容的细节层次——还没有",
+ "entry": [
+ "StreamedWorld",
+ "WorldPersistent",
+ "WorldStreamingSource",
+ "WorldStreamer",
+ "worldResidencyReport"
+ ]
+ },
{
"id": "prefab",
"title": "Prefabs",
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index f9a78618a..5daadc141 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -25,7 +25,7 @@ import { writeFile, readFile, mkdir, cp, readdir, rm } from 'node:fs/promises';
import { existsSync } from 'node:fs';
import path from 'node:path';
import { cookAssets, loadAssetGroups, type CookManifest } from '../assets/cookAssets';
-import { cookWorlds } from '../world/cookWorld';
+import { cookWorlds, streamedScenes } from '../world/cookWorld';
import { buildAddressableManifest } from '../assets/addressableManifest';
import { activeRemoteRoot } from '../../../sdk/src/asset/assetGroups';
import type { PackagedGameConfig } from 'esengine';
@@ -508,12 +508,24 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
const progress = opts.onProgress ?? (() => {});
const scenes = await discoverProjectScenes(opts.root, opts.entryScene, opts.scenesDir, opts.excludeScenes);
+ // 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.
+ 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'],
+ });
+
// 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 exportMiniGame(opts.miniGameProfile, {
+ return withStreamingNote(await exportMiniGame(opts.miniGameProfile, {
root: opts.root,
entryScene: opts.entryScene,
scenes,
@@ -533,12 +545,12 @@ 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 exportWeChat({
+ return withStreamingNote(await exportWeChat({
root: opts.root,
entryScene: opts.entryScene,
scenes,
@@ -558,12 +570,12 @@ 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 exportPlayable({
+ return withStreamingNote(await exportPlayable({
root: opts.root,
entryScene: opts.entryScene,
scriptsEntry: opts.scriptsEntry,
@@ -578,7 +590,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/src/world/cookWorld.ts b/pipeline/src/world/cookWorld.ts
index 04a97f161..f8151cd0d 100644
--- a/pipeline/src/world/cookWorld.ts
+++ b/pipeline/src/world/cookWorld.ts
@@ -67,6 +67,26 @@ function prefabResolver(root: string, index: AssetIndex): (ref: string) => Promi
};
}
+/**
+ * Which of `scenes` declare themselves streamed worlds.
+ *
+ * By the text, not by parsing: the answer decides whether a whole engine's
+ * component registry gets loaded, and most scenes are not worlds.
+ */
+export async function streamedScenes(
+ root: string, scenes: ReadonlyArray<{ name: string; path: string }>,
+): Promise<string[]> {
+ const declared: string[] = [];
+ for (const scene of scenes) {
+ try {
+ if ((await readFile(path.join(root, scene.path), 'utf8')).includes('"StreamedWorld"')) {
+ declared.push(scene.name);
+ }
+ } catch { /* not a file this target has */ }
+ }
+ return declared;
+}
+
/**
* Cut every staged scene that declares itself streamed.
*
diff --git a/tools/apiSubsystems.mjs b/tools/apiSubsystems.mjs
index b91dabac7..e481fb798 100644
--- a/tools/apiSubsystems.mjs
+++ b/tools/apiSubsystems.mjs
@@ -116,6 +116,16 @@ export const SUBSYSTEMS = [
whyZh: '只有一个被认证的项目在驱动场景,而 SceneManagerState 有 26 个签名',
entry: ['SceneManager', 'SceneManagerState', 'SceneConfig', 'SceneContext', 'transitionTo'],
},
+ {
+ id: 'residency',
+ title: 'World residency — streaming a world by cells',
+ titleZh: '世界 residency —— 按格子流送世界',
+ source: ['residency'],
+ tier: 'experimental',
+ why: 'one shape of world proven end to end: a square XZ grid cut at cook time, loaded synchronously. What a game asks for is settled; what a big one needs after it — priority, budget, a level of detail for what is absent — is not',
+ whyZh: '端到端证明的只有一种世界形状:cook 时切出的方形 XZ 网格,同步加载。一个游戏怎么提要求已经定了;大世界在它之后还需要的东西——优先级、预算、缺席内容的细节层次——还没有',
+ entry: ['StreamedWorld', 'WorldPersistent', 'WorldStreamingSource', 'WorldStreamer', 'worldResidencyReport'],
+ },
{
id: 'prefab',
title: 'Prefabs',
diff --git a/tools/lib/apiEvidence.mjs b/tools/lib/apiEvidence.mjs
index c42e46621..e7254edaf 100644
--- a/tools/lib/apiEvidence.mjs
+++ b/tools/lib/apiEvidence.mjs
@@ -133,7 +133,6 @@ export const BLIND = {
CommandsInstance: RECEIVED,
EntityCommands: RECEIVED,
EventReaderInstance: RECEIVED,
- EventWriterInstance: RECEIVED,
QueryInstance: RECEIVED,
RemovedQueryInstance: RECEIVED,
ResMutInstance: RECEIVED,