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
refactor(residency): the world partition has one author, and it is the runtime
esengine4b34d60e18ee
diff --git a/desktop b/desktopindex f4d069776..83cd2ab10 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit f4d069776d166cb0033996c844159d82ba03c940+Subproject commit 83cd2ab101d66bb23cc9e9ba942f378515ad1932diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex ff6cb257d..49c9156c7 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": 1811,+ "experimental": 1822,"deprecated": 3},- "total": 2015,+ "total": 2026,"subsystems": [{"id": "ecs",diff --git a/pipeline/src/world/componentRefs.ts b/pipeline/src/world/componentRefs.tsdeleted file mode 100644index de551d0cc..000000000--- a/pipeline/src/world/componentRefs.ts+++ /dev/null@@ -1,33 +0,0 @@-// SPDX-License-Identifier: Apache-2.0-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-/**- * @file componentRefs.ts- * @brief Which component fields hold entity references, asked of the engine- * rather than listed here.- *- * @details A table would answer for the components someone remembered. The- * registry answers for every one the engine has — builtins from the- * generated metadata and the TypeScript components alike — which is what- * the cross-cell reference check has to be complete over.- */--import { getComponentRegistry } from 'esengine/node';--let cached: Map<string, readonly string[]> | null = null;--/**- * The entity-valued fields of a component type; empty for most of them.- *- * A project's OWN components live in its script bundle, not in this registry, so- * a reference one holds goes unchecked at cook. The runtime is the backstop: an- * id it cannot resolve is cleared, never left pointing at another entity.- */-export function engineEntityFields(componentType: string): readonly string[] {- if (cached === null) {- cached = new Map();- for (const [name, def] of getComponentRegistry()) {- if (def.entityFields.length > 0) cached.set(name, def.entityFields);- }- }- return cached.get(componentType) ?? [];-}diff --git a/pipeline/src/world/cookWorld.ts b/pipeline/src/world/cookWorld.tsindex f8151cd0d..0a6afb857 100644--- a/pipeline/src/world/cookWorld.ts+++ b/pipeline/src/world/cookWorld.ts@@ -2,9 +2,13 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file cookWorld.ts- * @brief Turning a staged scene into a persistent scene plus cell documents.+ * @brief Writing a cut world to a package.*- * @details Runs over the COOKED payload rather than the project: by then every+ * @details The cut itself is `cutWorld`, which the editor's play realm also goes+ * through; what is here is the half only a build does — reading prefab+ * roots off disk, and putting the documents where the manifest says.+ *+ * Runs over the COOKED payload rather than the project: by then every* asset reference is in the form the runtime resolves, so a cell is the* same bytes the whole scene would have been, minus the places that are* somewhere else.@@ -12,14 +16,10 @@import { readFile, writeFile, mkdir } from 'node:fs/promises';import path from 'node:path';-import type { SceneData, WorldManifest } from 'esengine';-import { partitionWorld, type PrefabRoot } from './partitionWorld';-import { engineEntityFields } from './componentRefs';+import type { SceneData, PrefabRoot } from 'esengine';+import { cutWorld, worldManifestPath, registryEntityFields, WORLD_DIR } from 'esengine/node';import { readCachedAssetIndex, scanAssetDatabase, type AssetIndex } from '../assets/assetDb';-/** Where cooked world content goes, package-relative. */-const WORLD_DIR = 'world';-/** One streamed scene, as `game.config.json` names it. */export interface CookedWorld {scene: string;@@ -31,11 +31,6 @@ export interface CookWorldsResult {warnings: string[];}-/** A file name that survives a scene living in a subdirectory. */-function fileSafe(name: string): string {- return name.replace(/[^A-Za-z0-9_.-]/g, '_');-}-/*** Read the prefab an instance names, for the position an instance that does not* override it inherits. From the PROJECT rather than the payload: a prefab is@@ -129,46 +124,33 @@ export async function cookWorlds(}}- const partition = partitionWorld(document, scene.name, {- entityFieldsOf: engineEntityFields,+ const cut = cutWorld(document, scene.name, {+ entityFieldsOf: registryEntityFields(),resolvePrefab: (ref) => roots.get(ref) ?? null,});- if (partition === null) continue;- if (partition.errors.length > 0) {+ if (cut === null) continue;+ if (cut.errors.length > 0) {throw new Error(`scene "${scene.name}" cannot be cut into cells:\n`- + partition.errors.map((e) => ` ${e}`).join('\n'),+ + cut.errors.map((e) => ` ${e}`).join('\n'),);}- warnings.push(...partition.warnings.map((w) => `${scene.name}: ${w}`));+ warnings.push(...cut.warnings.map((w) => `${scene.name}: ${w}`));- const worldDir = path.join(payloadDir, WORLD_DIR);- await mkdir(worldDir, { recursive: true });- const manifest: WorldManifest = {- version: 1,- scene: scene.name,- cellSize: partition.cellSize,- persistentRefs: partition.persistentRefs,- cells: partition.cells.map((cell) => ({- name: cell.name,- path: `${WORLD_DIR}/${fileSafe(cell.name)}.json`,- x: cell.x, z: cell.z,- minX: cell.minX, minZ: cell.minZ, maxX: cell.maxX, maxZ: cell.maxZ,- entityCount: cell.entityCount,- rootCount: cell.rootCount,- })),- };- for (const cell of partition.cells) {+ await mkdir(path.join(payloadDir, WORLD_DIR), { recursive: true });+ for (const cell of cut.manifest.cells) {await writeFile(- path.join(worldDir, `${fileSafe(cell.name)}.json`),- JSON.stringify(cell.data) + '\n',+ path.join(payloadDir, cell.path),+ JSON.stringify(cut.documents.get(cell.name)) + '\n',);}- const manifestPath = `${WORLD_DIR}/${fileSafe(scene.name)}.world.json`;- await writeFile(path.join(payloadDir, manifestPath), JSON.stringify(manifest, null, 2) + '\n');+ const manifestPath = worldManifestPath(scene.name);+ await writeFile(+ path.join(payloadDir, manifestPath), JSON.stringify(cut.manifest, null, 2) + '\n',+ );// The staged scene becomes the PERSISTENT world. What a package boots is// then the thing residency never removes, and the places arrive later.- await writeFile(staged, JSON.stringify(partition.persistent) + '\n');+ await writeFile(staged, JSON.stringify(cut.persistent) + '\n');worlds.push({ scene: scene.name, manifest: manifestPath });}diff --git a/pipeline/tests/streamed-world-targets.test.ts b/pipeline/tests/streamed-world-targets.test.tsnew file mode 100644index 000000000..26366ec7a--- /dev/null+++ b/pipeline/tests/streamed-world-targets.test.ts@@ -0,0 +1,50 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file A target that cannot ship a cut world refuses the build.+ *+ * 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. The cut+ * itself is the runtime's, and pinned in sdk/tests/partition-world.test.ts.+ */+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';++const SIZE = 1000;++describe('targets that cannot ship a cut world', () => {+ it('is a decision the export makes, not a warning it prints', async () => {+ 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({+ version: 4, name: 'main',+ entities: [+ { id: 0, name: 'World', parent: null, children: [], visible: true,+ components: [{ type: 'StreamedWorld', data: { cellSize: SIZE } }] },+ { id: 1, name: 'RockA', parent: null, children: [], visible: true,+ components: [{ type: 'Transform', data: { position: { x: 500, y: 0, z: 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'),+ // Never reached: the refusal happens before anything is staged.+ sdkDistDir: path.join(project, 'sdk'),+ wasmDir: path.join(project, 'wasm'),+ })).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 f7fe252ba..69805f197 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 84 beta · 1650 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1661 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -2442,6 +2442,15 @@ name: stringtype: "customEvent"```+## CutWorld — interface @experimental+```+documents: Map<string, SceneData>+errors: readonly string[]+manifest: WorldManifest+persistent: SceneData+warnings: readonly string[]+```+## DARK_TOKENS — const @experimental```ThemeTokens@@ -5699,6 +5708,26 @@ static new (): ParticlePluginstatic prototype: ParticlePlugin```+## PartitionOptions — interface @experimental+```+entityFieldsOf: (componentType: string) => readonly string[]+resolvePrefab: ((ref: string) => PrefabRoot | null) | undefined+```++## PartitionedCell — interface @experimental+```+data: SceneData+entityCount: number+maxX: number+maxZ: number+minX: number+minZ: number+name: string+rootCount: number+x: number+z: number+```+## PathfindOptions — interface @experimental```clearance: number | undefined@@ -6488,6 +6517,12 @@ type: "property" | "component_added" | "component_replaced" | "component_removedvalue: unknown```+## PrefabRoot — interface @experimental+```+position: Vec3+rootId: string+```+## PrefabServer — class @beta```instantiate: (pathOrAddress: string, options?: { baseUrl?: string; parent?: Entity; overrides?: SpawnOverride[]; scene?: boolean; }) => Promise<InstantiatePrefabResult>@@ -10021,6 +10056,11 @@ y: numberMoveBasis```+## WORLD_DIR — const @experimental+```+"world"+```+## WangIndex — interface @experimental```byKey: Map<number, number>@@ -10215,6 +10255,16 @@ scene: stringversion: number```+## WorldPartition — interface @experimental+```+cellSize: number+cells: PartitionedCell[]+errors: string[]+persistent: SceneData+persistentRefs: number[]+warnings: string[]+```+## WorldPersistent — const @experimental```ComponentDef<{}>@@ -10752,6 +10802,11 @@ BtPlugin(x: number, z: number, cellSize: number): { x: number; z: number; }```+## cellDocumentPath — function @experimental+```+(cellName: string): string+```+## cellSquare — function @experimental```(cellX: number, cellZ: number, cellSize: number): { minX: number; minZ: number; maxX: number; maxZ: number; }@@ -11107,6 +11162,11 @@ Plugin(module: ESEngineModule, options?: CreateWebAppOptions): App```+## cutWorld — function @experimental+```+(scene: SceneData, sceneName: string, options: PartitionOptions): CutWorld | null+```+## dampFactor — function @experimental```(damping: number, dt: number): number@@ -12382,6 +12442,11 @@ NavPluginParticlePlugin```+## partitionWorld — function @experimental+```+(scene: SceneData, sceneName: string, options: PartitionOptions): WorldPartition | null+```+## pathToWorld — function @experimental```(grid: NavGrid, path: Cell[]): Vec3[]@@ -12702,6 +12767,11 @@ PrefabsPlugin(id: string, descriptor: SideModuleDescriptor): void```+## registryEntityFields — function @experimental+```+(): (componentType: string) => readonly string[]+```+## remapComponentEntityRefs — function @experimental```(components: ComponentData[], idMapping: Map<PrefabEntityId, number>): void@@ -13607,6 +13677,11 @@ VideoPlugin(axis: WorldAxis): Vec3```+## worldManifestPath — function @experimental+```+(sceneName: string): string+```+## worldResidencyPlugin — const @experimental```Plugindiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex a692db767..7810d083b 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 89 beta · 1669 experimental · 3 deprecated+Symbols: 113 public · 89 beta · 1680 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -2450,6 +2450,15 @@ name: stringtype: "customEvent"```+## CutWorld — interface @experimental+```+documents: Map<string, SceneData>+errors: readonly string[]+manifest: WorldManifest+persistent: SceneData+warnings: readonly string[]+```+## DARK_TOKENS — const @experimental```ThemeTokens@@ -5882,6 +5891,26 @@ static new (): ParticlePluginstatic prototype: ParticlePlugin```+## PartitionOptions — interface @experimental+```+entityFieldsOf: (componentType: string) => readonly string[]+resolvePrefab: ((ref: string) => PrefabRoot | null) | undefined+```++## PartitionedCell — interface @experimental+```+data: SceneData+entityCount: number+maxX: number+maxZ: number+minX: number+minZ: number+name: string+rootCount: number+x: number+z: number+```+## PathfindOptions — interface @experimental```clearance: number | undefined@@ -6671,6 +6700,12 @@ type: "property" | "component_added" | "component_replaced" | "component_removedvalue: unknown```+## PrefabRoot — interface @experimental+```+position: Vec3+rootId: string+```+## PrefabServer — class @beta```instantiate: (pathOrAddress: string, options?: { baseUrl?: string; parent?: Entity; overrides?: SpawnOverride[]; scene?: boolean; }) => Promise<InstantiatePrefabResult>@@ -10214,6 +10249,11 @@ y: numberMoveBasis```+## WORLD_DIR — const @experimental+```+"world"+```+## WangIndex — interface @experimental```byKey: Map<number, number>@@ -10408,6 +10448,16 @@ scene: stringversion: number```+## WorldPartition — interface @experimental+```+cellSize: number+cells: PartitionedCell[]+errors: string[]+persistent: SceneData+persistentRefs: number[]+warnings: string[]+```+## WorldPersistent — const @experimental```ComponentDef<{}>@@ -10960,6 +11010,11 @@ BtPlugin(x: number, z: number, cellSize: number): { x: number; z: number; }```+## cellDocumentPath — function @experimental+```+(cellName: string): string+```+## cellSquare — function @experimental```(cellX: number, cellZ: number, cellSize: number): { minX: number; minZ: number; maxX: number; maxZ: number; }@@ -11340,6 +11395,11 @@ Plugin(module: ESEngineModule, options?: CreateWebAppOptions): App```+## cutWorld — function @experimental+```+(scene: SceneData, sceneName: string, options: PartitionOptions): CutWorld | null+```+## dampFactor — function @experimental```(damping: number, dt: number): number@@ -12625,6 +12685,11 @@ NavPluginParticlePlugin```+## partitionWorld — function @experimental+```+(scene: SceneData, sceneName: string, options: PartitionOptions): WorldPartition | null+```+## pathToWorld — function @experimental```(grid: NavGrid, path: Cell[]): Vec3[]@@ -12945,6 +13010,11 @@ PrefabsPlugin(id: string, descriptor: SideModuleDescriptor): void```+## registryEntityFields — function @experimental+```+(): (componentType: string) => readonly string[]+```+## remapComponentEntityRefs — function @experimental```(components: ComponentData[], idMapping: Map<PrefabEntityId, number>): void@@ -13850,6 +13920,11 @@ VideoPlugin(axis: WorldAxis): Vec3```+## worldManifestPath — function @experimental+```+(sceneName: string): string+```+## worldResidencyPlugin — const @experimental```Plugindiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 36d054728..a848c1f6a 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 86 beta · 1649 experimental · 3 deprecated+Symbols: 113 public · 86 beta · 1660 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -2437,6 +2437,15 @@ name: stringtype: "customEvent"```+## CutWorld — interface @experimental+```+documents: Map<string, SceneData>+errors: readonly string[]+manifest: WorldManifest+persistent: SceneData+warnings: readonly string[]+```+## DARK_TOKENS — const @experimental```ThemeTokens@@ -5694,6 +5703,26 @@ static new (): ParticlePluginstatic prototype: ParticlePlugin```+## PartitionOptions — interface @experimental+```+entityFieldsOf: (componentType: string) => readonly string[]+resolvePrefab: ((ref: string) => PrefabRoot | null) | undefined+```++## PartitionedCell — interface @experimental+```+data: SceneData+entityCount: number+maxX: number+maxZ: number+minX: number+minZ: number+name: string+rootCount: number+x: number+z: number+```+## PathfindOptions — interface @experimental```clearance: number | undefined@@ -6483,6 +6512,12 @@ type: "property" | "component_added" | "component_replaced" | "component_removedvalue: unknown```+## PrefabRoot — interface @experimental+```+position: Vec3+rootId: string+```+## PrefabServer — class @beta```instantiate: (pathOrAddress: string, options?: { baseUrl?: string; parent?: Entity; overrides?: SpawnOverride[]; scene?: boolean; }) => Promise<InstantiatePrefabResult>@@ -10016,6 +10051,11 @@ y: numberMoveBasis```+## WORLD_DIR — const @experimental+```+"world"+```+## WangIndex — interface @experimental```byKey: Map<number, number>@@ -10210,6 +10250,16 @@ scene: stringversion: number```+## WorldPartition — interface @experimental+```+cellSize: number+cells: PartitionedCell[]+errors: string[]+persistent: SceneData+persistentRefs: number[]+warnings: string[]+```+## WorldPersistent — const @experimental```ComponentDef<{}>@@ -10747,6 +10797,11 @@ BtPlugin(x: number, z: number, cellSize: number): { x: number; z: number; }```+## cellDocumentPath — function @experimental+```+(cellName: string): string+```+## cellSquare — function @experimental```(cellX: number, cellZ: number, cellSize: number): { minX: number; minZ: number; maxX: number; maxZ: number; }@@ -11102,6 +11157,11 @@ Plugin(module: ESEngineModule, options?: CreateWebAppOptions): App```+## cutWorld — function @experimental+```+(scene: SceneData, sceneName: string, options: PartitionOptions): CutWorld | null+```+## dampFactor — function @experimental```(damping: number, dt: number): number@@ -12387,6 +12447,11 @@ NodePlatformAdapterParticlePlugin```+## partitionWorld — function @experimental+```+(scene: SceneData, sceneName: string, options: PartitionOptions): WorldPartition | null+```+## pathToWorld — function @experimental```(grid: NavGrid, path: Cell[]): Vec3[]@@ -12707,6 +12772,11 @@ PrefabsPlugin(id: string, descriptor: SideModuleDescriptor): void```+## registryEntityFields — function @experimental+```+(): (componentType: string) => readonly string[]+```+## remapComponentEntityRefs — function @experimental```(components: ComponentData[], idMapping: Map<PrefabEntityId, number>): void@@ -13612,6 +13682,11 @@ VideoPlugin(axis: WorldAxis): Vec3```+## worldManifestPath — function @experimental+```+(sceneName: string): string+```+## worldResidencyPlugin — const @experimental```Plugindiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 35482e1b6..ac5a3edbd 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 84 beta · 1671 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1682 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -2437,6 +2437,15 @@ name: stringtype: "customEvent"```+## CutWorld — interface @experimental+```+documents: Map<string, SceneData>+errors: readonly string[]+manifest: WorldManifest+persistent: SceneData+warnings: readonly string[]+```+## DARK_TOKENS — const @experimental```ThemeTokens@@ -5940,6 +5949,26 @@ static new (): ParticlePluginstatic prototype: ParticlePlugin```+## PartitionOptions — interface @experimental+```+entityFieldsOf: (componentType: string) => readonly string[]+resolvePrefab: ((ref: string) => PrefabRoot | null) | undefined+```++## PartitionedCell — interface @experimental+```+data: SceneData+entityCount: number+maxX: number+maxZ: number+minX: number+minZ: number+name: string+rootCount: number+x: number+z: number+```+## PathfindOptions — interface @experimental```clearance: number | undefined@@ -6729,6 +6758,12 @@ type: "property" | "component_added" | "component_replaced" | "component_removedvalue: unknown```+## PrefabRoot — interface @experimental+```+position: Vec3+rootId: string+```+## PrefabServer — class @beta```instantiate: (pathOrAddress: string, options?: { baseUrl?: string; parent?: Entity; overrides?: SpawnOverride[]; scene?: boolean; }) => Promise<InstantiatePrefabResult>@@ -10268,6 +10303,11 @@ y: numberMoveBasis```+## WORLD_DIR — const @experimental+```+"world"+```+## WangIndex — interface @experimental```byKey: Map<number, number>@@ -10462,6 +10502,16 @@ scene: stringversion: number```+## WorldPartition — interface @experimental+```+cellSize: number+cells: PartitionedCell[]+errors: string[]+persistent: SceneData+persistentRefs: number[]+warnings: string[]+```+## WorldPersistent — const @experimental```ComponentDef<{}>@@ -10999,6 +11049,11 @@ BtPlugin(x: number, z: number, cellSize: number): { x: number; z: number; }```+## cellDocumentPath — function @experimental+```+(cellName: string): string+```+## cellSquare — function @experimental```(cellX: number, cellZ: number, cellSize: number): { minX: number; minZ: number; maxX: number; maxZ: number; }@@ -11359,6 +11414,11 @@ Plugin(module: ESEngineModule, options?: CreateWebAppOptions): App```+## cutWorld — function @experimental+```+(scene: SceneData, sceneName: string, options: PartitionOptions): CutWorld | null+```+## dampFactor — function @experimental```(damping: number, dt: number): number@@ -12644,6 +12704,11 @@ NavPluginParticlePlugin```+## partitionWorld — function @experimental+```+(scene: SceneData, sceneName: string, options: PartitionOptions): WorldPartition | null+```+## pathToWorld — function @experimental```(grid: NavGrid, path: Cell[]): Vec3[]@@ -12964,6 +13029,11 @@ PrefabsPlugin(id: string, descriptor: SideModuleDescriptor): void```+## registryEntityFields — function @experimental+```+(): (componentType: string) => readonly string[]+```+## remapComponentEntityRefs — function @experimental```(components: ComponentData[], idMapping: Map<PrefabEntityId, number>): void@@ -13869,6 +13939,11 @@ VideoPlugin(axis: WorldAxis): Vec3```+## worldManifestPath — function @experimental+```+(sceneName: string): string+```+## worldResidencyPlugin — const @experimental```Plugindiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 60e7e9fc1..8041d0a6f 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 84 beta · 1661 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1672 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -2437,6 +2437,15 @@ name: stringtype: "customEvent"```+## CutWorld — interface @experimental+```+documents: Map<string, SceneData>+errors: readonly string[]+manifest: WorldManifest+persistent: SceneData+warnings: readonly string[]+```+## DARK_TOKENS — const @experimental```ThemeTokens@@ -5701,6 +5710,26 @@ static new (): ParticlePluginstatic prototype: ParticlePlugin```+## PartitionOptions — interface @experimental+```+entityFieldsOf: (componentType: string) => readonly string[]+resolvePrefab: ((ref: string) => PrefabRoot | null) | undefined+```++## PartitionedCell — interface @experimental+```+data: SceneData+entityCount: number+maxX: number+maxZ: number+minX: number+minZ: number+name: string+rootCount: number+x: number+z: number+```+## PathfindOptions — interface @experimental```clearance: number | undefined@@ -6490,6 +6519,12 @@ type: "property" | "component_added" | "component_replaced" | "component_removedvalue: unknown```+## PrefabRoot — interface @experimental+```+position: Vec3+rootId: string+```+## PrefabServer — class @beta```instantiate: (pathOrAddress: string, options?: { baseUrl?: string; parent?: Entity; overrides?: SpawnOverride[]; scene?: boolean; }) => Promise<InstantiatePrefabResult>@@ -10023,6 +10058,11 @@ y: numberMoveBasis```+## WORLD_DIR — const @experimental+```+"world"+```+## WangIndex — interface @experimental```byKey: Map<number, number>@@ -10238,6 +10278,16 @@ scene: stringversion: number```+## WorldPartition — interface @experimental+```+cellSize: number+cells: PartitionedCell[]+errors: string[]+persistent: SceneData+persistentRefs: number[]+warnings: string[]+```+## WorldPersistent — const @experimental```ComponentDef<{}>@@ -10775,6 +10825,11 @@ BtPlugin(x: number, z: number, cellSize: number): { x: number; z: number; }```+## cellDocumentPath — function @experimental+```+(cellName: string): string+```+## cellSquare — function @experimental```(cellX: number, cellZ: number, cellSize: number): { minX: number; minZ: number; maxX: number; maxZ: number; }@@ -11130,6 +11185,11 @@ Plugin(module: ESEngineModule, options?: CreateWebAppOptions): App```+## cutWorld — function @experimental+```+(scene: SceneData, sceneName: string, options: PartitionOptions): CutWorld | null+```+## dampFactor — function @experimental```(damping: number, dt: number): number@@ -12410,6 +12470,11 @@ NavPluginParticlePlugin```+## partitionWorld — function @experimental+```+(scene: SceneData, sceneName: string, options: PartitionOptions): WorldPartition | null+```+## pathToWorld — function @experimental```(grid: NavGrid, path: Cell[]): Vec3[]@@ -12730,6 +12795,11 @@ PrefabsPlugin(id: string, descriptor: SideModuleDescriptor): void```+## registryEntityFields — function @experimental+```+(): (componentType: string) => readonly string[]+```+## remapComponentEntityRefs — function @experimental```(components: ComponentData[], idMapping: Map<PrefabEntityId, number>): void@@ -13640,6 +13710,11 @@ MiniGameProfile(axis: WorldAxis): Vec3```+## worldManifestPath — function @experimental+```+(sceneName: string): string+```+## worldResidencyPlugin — const @experimental```Plugindiff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 6dee9e2e8..ff222dfb4 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -254,6 +254,12 @@ export {worldResidencyReport,persistentEntityRows,stableEntityId,+ partitionWorld,+ cutWorld,+ cellDocumentPath,+ worldManifestPath,+ registryEntityFields,+ WORLD_DIR,type StreamedWorldData,type WorldStreamingSourceData,type WorldCell,@@ -264,6 +270,11 @@ export {type WorldStreamHost,type WorldStreamerStatus,type WorldResidencyReport,+ type PartitionOptions,+ type PartitionedCell,+ type PrefabRoot,+ type WorldPartition,+ type CutWorld,} from './residency/index';export {diff --git a/sdk/src/residency/componentRefs.ts b/sdk/src/residency/componentRefs.tsnew file mode 100644index 000000000..612a2d677--- /dev/null+++ b/sdk/src/residency/componentRefs.ts@@ -0,0 +1,34 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file componentRefs.ts+ * @brief Which component fields hold entity references, asked of the engine+ * rather than listed here.+ *+ * @details A table would answer for the components someone remembered. The+ * registry answers for every one registered where the question is asked+ * — and that is not the same set on both sides: a cook loads the+ * engine's components, while a play realm has also drained the project's+ * own bundle. Play's reference check is therefore a SUPERSET of the+ * cook's, and a cross-cell reference held by a project component is+ * found in the editor first. The runtime is the backstop for whatever+ * neither saw: an id it cannot resolve is cleared, never left pointing+ * at another entity.+ */++import { getComponentRegistry } from '../ecs/component';++/**+ * A lookup over the registry as it stands right now.+ *+ * Taken as a snapshot rather than answered per call, because `getComponentRegistry`+ * composes a fresh map on every call and a partition asks this once per component+ * field of every entity in the world.+ */+export function registryEntityFields(): (componentType: string) => readonly string[] {+ const fields = new Map<string, readonly string[]>();+ for (const [name, def] of getComponentRegistry()) {+ if (def.entityFields.length > 0) fields.set(name, def.entityFields);+ }+ return (componentType) => fields.get(componentType) ?? [];+}diff --git a/sdk/src/residency/cutWorld.ts b/sdk/src/residency/cutWorld.tsnew file mode 100644index 000000000..67e132503--- /dev/null+++ b/sdk/src/residency/cutWorld.ts@@ -0,0 +1,94 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file cutWorld.ts+ * @brief One authored world, cut — the entry both hosts of a streamed world go+ * through.+ *+ * @details A cook writes the result to files and a play realm keeps it in memory,+ * and that is the ONLY difference between them: same partition, same+ * manifest, same cell names, same paths. Two hosts assembling their own+ * manifests is how a world comes to mean one thing in the editor and+ * another in the package — the failure this module exists to make+ * impossible, because there is nowhere left to disagree.+ */++import { partitionWorld, type PartitionOptions } from './partitionWorld';+import type { WorldCell, WorldManifest } from './cells';+import type { SceneData } from '../scene/scene';++/** Where cooked world content goes, package-relative. */+export const WORLD_DIR = 'world';++/** A file name that survives a scene living in a subdirectory. */+function fileSafe(name: string): string {+ return name.replace(/[^A-Za-z0-9_.-]/g, '_');+}++/**+ * Where a cell's document ships. A realm that delivers cells from memory never+ * fetches this, but it carries the same value: two manifests that differ in a+ * field one side ignores are still two manifests, and nothing would catch it.+ */+export function cellDocumentPath(cellName: string): string {+ return `${WORLD_DIR}/${fileSafe(cellName)}.json`;+}++/** Where a world's manifest ships, package-relative. */+export function worldManifestPath(sceneName: string): string {+ return `${WORLD_DIR}/${fileSafe(sceneName)}.world.json`;+}++/** An authored world, cut into what ships and what arrives. @experimental */+export interface CutWorld {+ /** What residency is told about the world — byte-identical on both hosts. */+ manifest: WorldManifest;+ /** The entry scene as it now boots: everything residency never removes. */+ persistent: SceneData;+ /** Cell name → its document, for a host that delivers cells from memory. */+ documents: Map<string, SceneData>;+ /**+ * Why this world cannot be cut. A hard reference across a residency boundary+ * is one: shipping it produces a handle that dangles the first time a player+ * walks away. Non-empty means refuse — in a build AND in Play, because a+ * world the editor agreed to run is one the author will ship.+ */+ errors: readonly string[];+ warnings: readonly string[];+}++/**+ * Cut `scene`, or answer null when it never declared itself a streamed world —+ * which is every scene that came before this and every small one that stays whole.+ */+export function cutWorld(+ scene: SceneData, sceneName: string, options: PartitionOptions,+): CutWorld | null {+ const partition = partitionWorld(scene, sceneName, options);+ if (partition === null) return null;++ const cells: WorldCell[] = partition.cells.map((cell) => ({+ name: cell.name,+ path: cellDocumentPath(cell.name),+ x: cell.x, z: cell.z,+ minX: cell.minX, minZ: cell.minZ, maxX: cell.maxX, maxZ: cell.maxZ,+ entityCount: cell.entityCount,+ rootCount: cell.rootCount,+ }));+ const documents = new Map<string, SceneData>();+ for (const cell of partition.cells) documents.set(cell.name, cell.data);++ return {+ manifest: {+ version: 1,+ scene: sceneName,+ cellSize: partition.cellSize,+ persistentRefs: partition.persistentRefs,+ cells,+ },+ persistent: partition.persistent,+ documents,+ errors: partition.errors,+ warnings: partition.warnings,+ };+}diff --git a/sdk/src/residency/index.ts b/sdk/src/residency/index.tsindex 189169be8..d96bc3214 100644--- a/sdk/src/residency/index.ts+++ b/sdk/src/residency/index.ts@@ -20,3 +20,11 @@ export {export { worldResidencyPlugin, worldResidencySystem } from './residencyPlugin';export { worldResidencyReport, type WorldResidencyReport } from './report';export { persistentEntityRows, stableEntityId } from './identity';+export {+ partitionWorld,+ type PartitionOptions, type PartitionedCell, type PrefabRoot, type WorldPartition,+} from './partitionWorld';+export {+ cutWorld, cellDocumentPath, worldManifestPath, WORLD_DIR, type CutWorld,+} from './cutWorld';+export { registryEntityFields } from './componentRefs';diff --git a/pipeline/src/world/partitionWorld.ts b/sdk/src/residency/partitionWorld.tssimilarity index 96%rename from pipeline/src/world/partitionWorld.tsrename to sdk/src/residency/partitionWorld.tsindex 790320b36..e8b682666 100644--- a/pipeline/src/world/partitionWorld.ts+++ b/sdk/src/residency/partitionWorld.ts@@ -4,7 +4,12 @@* @file partitionWorld.ts* @brief Cutting one authored world into a persistent scene plus cells.*- * @details Spatial partition is COOKED content. A packaged game that walked its+ * @details Lives in the runtime rather than the pipeline because a packaged build+ * is not the only host that has to cut a world: an editor Play session+ * cuts the unsaved document the same way, and two implementations of+ * "which cell is this in" is two worlds.+ *+ * The RESULT is still cooked content. A packaged game that walked its* whole world at boot to decide who lives where has already paid for the* world it was trying not to load.*@@ -19,10 +24,11 @@* fields hold entity references, and where a prefab's root sits.*/-import { isPrefabEntry, cellAt, cellSquare } from 'esengine';-import type {- SceneData, SceneEntityData, SceneComponentData, SceneEntry, PrefabInstanceEntry,-} from 'esengine';+import { isPrefabEntry } from '../scene/sceneEntry';+import { cellAt, cellSquare } from './cells';+import type { SceneData, SceneEntityData, SceneComponentData } from '../scene/scene';+import type { SceneEntry } from '../scene/sceneEntry';+import type { PrefabInstanceEntry } from '../prefab/sceneInstance';interface Vec3 { x: number; y: number; z: number }diff --git a/pipeline/tests/partition-world.test.ts b/sdk/tests/partition-world.test.tssimilarity index 81%rename from pipeline/tests/partition-world.test.tsrename to sdk/tests/partition-world.test.tsindex ff68a52a4..5a68b153d 100644--- a/pipeline/tests/partition-world.test.ts+++ b/sdk/tests/partition-world.test.ts@@ -10,11 +10,8 @@* 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';+import { partitionWorld, type PartitionOptions } from '../src/residency/partitionWorld';+import type { SceneData } from '../src/scene/scene';const SIZE = 1000;@@ -189,35 +186,3 @@ 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'),- // Never reached: the refusal happens before anything is staged.- sdkDistDir: path.join(project, 'sdk'),- wasmDir: path.join(project, 'wasm'),- })).rejects.toThrow(/cannot ship one/);- } finally {- await rm(project, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });- }- });-});diff --git a/pipeline/tests/world-partition-purity.test.ts b/sdk/tests/world-partition-purity.test.tssimilarity index 91%rename from pipeline/tests/world-partition-purity.test.tsrename to sdk/tests/world-partition-purity.test.tsindex a9cb41be1..76f946298 100644--- a/pipeline/tests/world-partition-purity.test.ts+++ b/sdk/tests/world-partition-purity.test.ts@@ -11,9 +11,9 @@* true, and on the input surviving the call unchanged.*/import { describe, it, expect } from 'vitest';-import { partitionWorld } from '../src/world/partitionWorld';-import { engineEntityFields } from '../src/world/componentRefs';-import type { SceneData } from 'esengine';+import { partitionWorld } from '../src/residency/partitionWorld';+import { registryEntityFields } from '../src/residency/componentRefs';+import type { SceneData } from '../src/scene/scene';const CELL = 100;@@ -32,7 +32,7 @@ function world(sentinelX: number): SceneData {} as unknown as SceneData;}-const opts = { entityFieldsOf: engineEntityFields };+const opts = { entityFieldsOf: registryEntityFields() };const cellOf = (p: ReturnType<typeof partitionWorld>, name: string): string | null =>p!.cells.find((c) =>(c.data.entities as unknown as Array<{ name?: string }>).some((e) => e.name === name))?.name ?? null;