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.

refactor(residency): the world partition has one author, and it is the runtime

esengine4b34d60e18ee
diff --git a/desktop b/desktop
index f4d069776..83cd2ab10 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit f4d069776d166cb0033996c844159d82ba03c940
+Subproject commit 83cd2ab101d66bb23cc9e9ba942f378515ad1932
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 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.ts
deleted file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.md
index 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: string
type: "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 (): ParticlePlugin
static 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_removed
value: 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: number
MoveBasis
```
+## WORLD_DIR — const @experimental
+```
+"world"
+```
+
## WangIndex — interface @experimental
```
byKey: Map<number, number>
@@ -10215,6 +10255,16 @@ scene: string
version: 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 @@ NavPlugin
ParticlePlugin
```
+## 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
```
Plugin
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: string
type: "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 (): ParticlePlugin
static 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_removed
value: 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: number
MoveBasis
```
+## WORLD_DIR — const @experimental
+```
+"world"
+```
+
## WangIndex — interface @experimental
```
byKey: Map<number, number>
@@ -10408,6 +10448,16 @@ scene: string
version: 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 @@ NavPlugin
ParticlePlugin
```
+## 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
```
Plugin
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: string
type: "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 (): ParticlePlugin
static 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_removed
value: 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: number
MoveBasis
```
+## WORLD_DIR — const @experimental
+```
+"world"
+```
+
## WangIndex — interface @experimental
```
byKey: Map<number, number>
@@ -10210,6 +10250,16 @@ scene: string
version: 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 @@ NodePlatformAdapter
ParticlePlugin
```
+## 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
```
Plugin
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: string
type: "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 (): ParticlePlugin
static 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_removed
value: 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: number
MoveBasis
```
+## WORLD_DIR — const @experimental
+```
+"world"
+```
+
## WangIndex — interface @experimental
```
byKey: Map<number, number>
@@ -10462,6 +10502,16 @@ scene: string
version: 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 @@ NavPlugin
ParticlePlugin
```
+## 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
```
Plugin
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: string
type: "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 (): ParticlePlugin
static 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_removed
value: 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: number
MoveBasis
```
+## WORLD_DIR — const @experimental
+```
+"world"
+```
+
## WangIndex — interface @experimental
```
byKey: Map<number, number>
@@ -10238,6 +10278,16 @@ scene: string
version: 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 @@ NavPlugin
ParticlePlugin
```
+## 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
```
Plugin
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
similarity index 96%
rename from pipeline/src/world/partitionWorld.ts
rename to sdk/src/residency/partitionWorld.ts
index 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.ts
similarity index 81%
rename from pipeline/tests/partition-world.test.ts
rename to sdk/tests/partition-world.test.ts
index 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.ts
similarity index 91%
rename from pipeline/tests/world-partition-purity.test.ts
rename to sdk/tests/world-partition-purity.test.ts
index 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;