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
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.mdxindex 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.jsonindex 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.tsindex 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 absolutediff --git a/pipeline/src/world/cookWorld.ts b/pipeline/src/world/cookWorld.tsindex 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.mjsindex 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.mjsindex 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,