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
// 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, type PrefabRoot } 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,
...(partition.plane === 'xy' ? { plane: 'xy' as const } : {}),
persistentRefs: partition.persistentRefs,
cells,
},
persistent: partition.persistent,
documents,
errors: partition.errors,
warnings: partition.warnings,
};
}
/** The shape of a `.esprefab` this reads — only the root's placement. */
interface PrefabDocument {
rootEntityId?: string;
entities?: Array<{
prefabEntityId?: string;
components?: Array<{ type: string; data: Record<string, unknown> }>;
}>;
}
/** Where a prefab asset's root sits, from its document. Null if it has no root. */
export function prefabRootOf(document: unknown): PrefabRoot | null {
const prefab = document as PrefabDocument | null;
if (prefab === null || typeof prefab !== 'object') return null;
const rootId = prefab.rootEntityId ?? '0';
const root = (prefab.entities ?? []).find((e) => e.prefabEntityId === rootId);
if (!root) return null;
const at = (root.components?.find((c) => c.type === 'Transform')?.data.position ?? {}) as
Partial<{ x: number; y: number; z: number }>;
return { rootId, position: { x: at.x ?? 0, y: at.y ?? 0, z: at.z ?? 0 } };
}
/**
* Read every prefab `scene` instances, and answer where each one's root sits.
*
* A synchronous lookup, resolved up front, because the partition is pure and one
* that could await inside it would not be. Both hosts come through here; they
* differ only in how the bytes are fetched.
*/
export async function resolvePrefabRoots(
scene: SceneData, read: (ref: string) => Promise<unknown | null>,
): Promise<(ref: string) => PrefabRoot | null> {
const roots = new Map<string, PrefabRoot | null>();
for (const entry of (scene.entities ?? []) as unknown as Array<{ prefab?: string }>) {
if (typeof entry.prefab !== 'string' || roots.has(entry.prefab)) continue;
roots.set(entry.prefab, prefabRootOf(await read(entry.prefab).catch(() => null)));
}
return (ref) => roots.get(ref) ?? null;
}