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
fix(runtime): a cell's reference into the persistent world reaches it in a package
esengine027ef7f8539f
diff --git a/examples/world-streaming-3d/assets/scenes/main.esscene b/examples/world-streaming-3d/assets/scenes/main.essceneindex 3ce332d3a..cb7ff7887 100644--- a/examples/world-streaming-3d/assets/scenes/main.esscene+++ b/examples/world-streaming-3d/assets/scenes/main.esscene@@ -699,6 +699,15 @@"current": 100,"max": 100}+ },+ {+ "type": "ParticleEmitter",+ "data": {+ "maxParticles": 8,+ "emissionRate": 0,+ "playing": false,+ "subEmitter": 9+ }}]},@@ -747,6 +756,60 @@}}]+ },+ {+ "id": 9,+ "name": "Sparks",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 60,+ "z": -400+ }+ }+ },+ {+ "type": "ParticleEmitter",+ "data": {+ "maxParticles": 8,+ "emissionRate": 0,+ "playing": false+ }+ },+ {+ "type": "WorldPersistent",+ "data": {}+ }+ ]+ },+ {+ "id": 10,+ "name": "RefProbe",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 60,+ "z": -600+ }+ }+ },+ {+ "type": "WorldPersistent",+ "data": {}+ }+ ]}]}diff --git a/examples/world-streaming-3d/src/main.ts b/examples/world-streaming-3d/src/main.tsindex f5e79f9a8..73c008933 100644--- a/examples/world-streaming-3d/src/main.ts+++ b/examples/world-streaming-3d/src/main.ts@@ -3,7 +3,7 @@// gone. Residency itself is declared, and nothing below loads or unloads.import {addSystemToSchedule, Schedule, defineSystem, GetWorld, Res, EventWriter, Time,- Input, Damage, Transform, WorldStreamingSource,+ Input, Damage, Transform, WorldStreamingSource, ParticleEmitter,} from 'esengine';import type { World, InputState, TimeData, EventWriterInstance, DamagePayload } from 'esengine';@@ -74,6 +74,28 @@ const staleBlowSystem = defineSystem({ name: 'StaleBlowSystem' },);+/**+ * Does the reference a cell holds into the persistent world actually name it?+ *+ * Only the game can ask: the value is a runtime handle by the time anything+ * reads it, and one that resolved to nothing looks like one never authored.+ */+const crossRefSystem = defineSystem(+ [GetWorld()],+ (world: World) => {+ const probe = world.findEntityByName('RefProbe');+ const holder = world.findEntityByName('ArchTop');+ if (probe === null) return;+ const answer = holder === null || !world.has(holder, ParticleEmitter)+ ? 0+ : (world.get(holder, ParticleEmitter).subEmitter === world.findEntityByName('Sparks')+ ? 1000 : -1000);+ world.update(probe, Transform, (t) => { t.position.x = answer; });+ },+ { name: 'CrossRefSystem' },+);+addSystemToSchedule(Schedule.Update, sourceKeysSystem);+addSystemToSchedule(Schedule.Update, crossRefSystem);addSystemToSchedule(Schedule.Update, bobberSystem);addSystemToSchedule(Schedule.Update, staleBlowSystem);diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.tsindex 9ca34f060..2105864c1 100644--- a/pipeline/src/runtime/gameHost.ts+++ b/pipeline/src/runtime/gameHost.ts@@ -468,6 +468,22 @@ async function boot(): Promise<void> {entities: app.world.entityCount(),};},+ /**+ * What the LAST frame cost, by system.+ *+ * The other half of a cell's arrival: the load runs between frames and+ * shows on no system timer, while registering what it spawned happens+ * inside systems on the frames after. Engaging the stats fills this.+ */+ costs(top = 8): Array<{ name: string; ms: number }> {+ app.enableStats();+ const costs = app.getFrameCosts();+ if (!costs) return [];+ return [...costs.systems]+ .map((s) => ({ name: s.name, ms: s.ms }))+ .sort((a, b) => b.ms - a.ms)+ .slice(0, top);+ },/** Drive a hot update against a served (CDN) manifest: fetch + diff + apply.* Rebinding the visuals is the game's job (via Assets.onInvalidate); a* driver settles frames after this before re-capturing. */diff --git a/sdk/src/residency/WorldStreamer.ts b/sdk/src/residency/WorldStreamer.tsindex 91bd0531c..3fd29c8b9 100644--- a/sdk/src/residency/WorldStreamer.ts+++ b/sdk/src/residency/WorldStreamer.ts@@ -57,6 +57,12 @@ interface CellState {residency: CellResidency;/** What the last reconciliation asked for; the async completions re-read it. */desired: boolean;+ /** Where this cell's last load spent its time, phase by phase. */+ phases: Record<string, number>;+ /** When the load was issued, so `delivery` is measured and not guessed. */+ issuedAt: number;+ /** Issue to resident, in wall time. Most of it is not the engine working. */+ delivery: number;}export class WorldStreamer {@@ -84,7 +90,10 @@ export class WorldStreamer {this.cells_.clear();for (const cell of manifest.cells) {this.host_.register(sceneConfig?.(cell) ?? { name: cell.name, path: cell.path });- this.cells_.set(cell.name, { cell, residency: 'unloaded', desired: false });+ this.cells_.set(cell.name, {+ cell, residency: 'unloaded', desired: false,+ phases: {}, issuedAt: 0, delivery: 0,+ });}}@@ -96,6 +105,27 @@ export class WorldStreamer {return this.cells_.get(name)?.residency ?? 'unloaded';}+ /**+ * Where a cell's load spent its time.+ *+ * Most of a load runs BETWEEN frames — off every system timer there is — so a+ * profiler watching the frame loop sees the cost and cannot name it.+ */+ recordPhase(name: string, phase: string, ms: number): void {+ const state = this.cells_.get(name);+ if (state) state.phases[phase] = (state.phases[phase] ?? 0) + ms;+ }++ /** Per cell: the phases of its last load, and issue-to-resident wall time. */+ delivery(): Record<string, { phases: Record<string, number>; deliveryMs: number }> {+ const out: Record<string, { phases: Record<string, number>; deliveryMs: number }> = {};+ for (const [name, state] of this.cells_) {+ if (state.delivery === 0 && Object.keys(state.phases).length === 0) continue;+ out[name] = { phases: { ...state.phases }, deliveryMs: state.delivery };+ }+ return out;+ }+/*** Reconcile residency against where the sources are.*@@ -165,9 +195,15 @@ export class WorldStreamer {private beginLoad_(name: string, state: CellState): void {state.residency = 'loading';+ state.phases = {};+ state.issuedAt = performance.now();this.loadCount_++;Promise.resolve(this.host_.loadAdditive(name)).then(- () => { state.residency = 'resident'; this.step_(name); },+ () => {+ state.residency = 'resident';+ state.delivery = performance.now() - state.issuedAt;+ this.step_(name);+ },(err) => {// A cell that failed to come up owns nothing (the scene load is a// transaction), so it goes back to being absent and may be askeddiff --git a/sdk/src/residency/report.ts b/sdk/src/residency/report.tsindex 8ecbb2f4a..4524f3245 100644--- a/sdk/src/residency/report.ts+++ b/sdk/src/residency/report.ts@@ -50,6 +50,12 @@ export interface WorldResidencyReport {persistentEntities: number;/** Their handles. Unchanged for the life of the world — that is the claim. */persistentHandles: number[];+ /**+ * Per cell: where its last load spent its time, and issue-to-resident wall+ * time. The phases run between frames, which is why no frame profiler holds+ * them and why a total is not a hitch.+ */+ delivery: Record<string, { phases: Record<string, number>; deliveryMs: number }>;}const EMPTY: WorldResidencyReport = {@@ -58,7 +64,7 @@ const EMPTY: WorldResidencyReport = {loadCount: 0, unloadCount: 0,cellEntityCounts: {}, cellRenderCounts: {}, assetRefsByCell: {},authoredCellEntityCounts: {}, cellRows: {},- persistentEntities: 0, persistentHandles: [],+ persistentEntities: 0, persistentHandles: [], delivery: {},};/**@@ -114,5 +120,6 @@ export function worldResidencyReport(app: App): WorldResidencyReport {cellRows,persistentEntities: persistent.length,persistentHandles: persistent,+ delivery: streamer.delivery(),};}diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.tsindex f30b7f916..1945812fc 100644--- a/sdk/src/runtime/runtimeLoader.ts+++ b/sdk/src/runtime/runtimeLoader.ts@@ -9,6 +9,7 @@ import { SceneOwner } from '../ecs/component';import { loadSceneData, updateCameraAspectRatio, sceneHasPrefabEntries, expandScenePrefabs, type SceneData } from '../scene/scene';import { recordSceneOrigins, enableSceneOrigins } from '../scene/sceneOrigins';import { defineResource } from '../ecs/resource';+import type { Entity } from '../types';import type { PrefabData } from '../prefab/types';import { switchTheme, resolveThemeTokens, type ThemeOverrides } from '../ui';import { discoverSceneAssets } from '../asset/discoverAssets';@@ -185,6 +186,11 @@ function applyTextureMetadata(// =============================================================================export interface LoadRuntimeSceneOptions {+ /** Authored ids this scene may reference in ANOTHER document — the persistent+ * rows a streamed cell names. See {@link SceneLoadOptions.externalEntities}. */+ externalEntities?: ReadonlyMap<number, Entity>;+ /** Where this load spent its time. See {@link SceneLoadOptions.onPhase}. */+ onPhase?: (phase: string, ms: number) => void;app: App;/** The wasm module, or null on a native host — the engine core is arm64 there,* so there is no Module to reach through. */@@ -297,6 +303,12 @@ export function sceneUsesPhysics(sceneData: SceneData): boolean {export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promise<void> {const { app, module, source, physicsConfig, physicsEnabled, uiTheme, uiThemeOverrides, sceneName } = options;+ const onPhase = options.onPhase;+ const timed = async <T>(phase: string, run: () => Promise<T> | T): Promise<T> => {+ if (!onPhase) return run();+ const began = performance.now();+ try { return await run(); } finally { onPhase(phase, performance.now() - began); }+ };// The SpineManager is owned by SpinePlugin (built from the realm's// app.sideModules host); read it from there so every realm — play / playable /@@ -314,14 +326,14 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promisconst runtimeAssets = ensureRuntimeAssets(app, module, source);let sceneData = options.sceneData;if (sceneHasPrefabEntries(sceneData)) {- sceneData = await expandScenePrefabs(sceneData, async (ref) => {+ sceneData = await timed('prefab', () => expandScenePrefabs(sceneData, async (ref) => {try {return ((await runtimeAssets.loadPrefab(ref))?.data as PrefabData) ?? null;} catch (e) {log.warn('scene', `Failed to load prefab "${ref}": ${e instanceof Error ? e.message : String(e)}`);return null;}- });+ }));}// Spine pairs (raw refs) for the two-phase spine load+apply below; every@@ -484,7 +496,11 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis}}- const entityMap = loadSceneData(app.world, sceneData);+ // The one place a packaged scene's entities come into being. `externalEntities`+ // is what lets a streamed cell name the persistent world: without it a cross+ // document reference resolves to nothing, quietly.+ const entityMap = await timed('spawn',+ () => loadSceneData(app.world, sceneData, options.externalEntities));// Which document row each entity came from, when someone is keeping track// (an editor inspecting its own running game). No-op otherwise.recordSceneOrigins(app, entityMap);@@ -534,7 +550,10 @@ export function createRuntimeSceneConfig(options: Omit<LoadRuntimeSceneOptions, 'sceneData' | 'sceneName'>,scenePath?: string,): SceneConfig {- return {+ // Built first and closed over, so whoever sets `externalEntities` / `onPhase`+ // on the CONFIG is honoured here too: declared in one place and read in+ // another, a cell's reference to the persistent world resolved to nothing.+ const config: SceneConfig = {name,async setup() {let data = sceneData;@@ -544,11 +563,20 @@ export function createRuntimeSceneConfig(// arrives via the realm's backend/resolver — http on web, wx fs// on WeChat — only when the game actually switches to it.if (!scenePath) throw new Error(`scene "${name}" registered with neither data nor path`);+ const began = performance.now();data = await options.app.getResource(AssetsResource).fetchJson<SceneData>(scenePath);+ config.onPhase?.('fetch', performance.now() - began);}- await loadRuntimeScene({ ...options, sceneData: data, sceneName: name });+ await loadRuntimeScene({+ ...options,+ sceneData: data,+ sceneName: name,+ externalEntities: config.externalEntities?.(),+ onPhase: config.onPhase,+ });},};+ return config;}export interface RuntimeInitConfig {@@ -707,10 +735,16 @@ export async function initRuntime(config: RuntimeInitConfig): Promise<void> {// A cell loads the way every other scene in this build does, and resolves// the persistent rows the cook said it names — freshly each time, because// the entities behind those rows are only the ones alive right now.- app.getResource(WorldStreaming).loadManifest(world, (cell) => ({- ...createRuntimeSceneConfig(cell.name, undefined, sceneOpts, cell.path),- externalEntities: () => persistentEntityRows(app, world),- }));+ const streamer = app.getResource(WorldStreaming);+ streamer.loadManifest(world, (cell) => {+ // Set ON the config, not spread into a copy of it: the setup that+ // loads the cell closes over the object this returns, so a copy+ // carries the fields somewhere nothing reads them.+ const config = createRuntimeSceneConfig(cell.name, undefined, sceneOpts, cell.path);+ config.externalEntities = () => persistentEntityRows(app, world);+ config.onPhase = (phase, ms) => streamer.recordPhase(cell.name, phase, ms);+ return config;+ });}if (aspectRatio !== undefined) {diff --git a/sdk/src/scene/scene.ts b/sdk/src/scene/scene.tsindex 89caf50ea..a3c0ff400 100644--- a/sdk/src/scene/scene.ts+++ b/sdk/src/scene/scene.ts@@ -114,6 +114,12 @@ export interface SceneLoadOptions {* outside the document resolves to nothing, which is what it always did.*/externalEntities?: ReadonlyMap<number, Entity>;+ /**+ * Where a load's time went, phase by phase. Most of it runs between frames —+ * off every system timer there is — so a profiler watching the frame loop+ * sees the cost and cannot say what it was.+ */+ onPhase?: (phase: string, ms: number) => void;}export class MissingAssetsError extends Error {@@ -498,9 +504,11 @@ function spawnAndLoadEntities(return entityMap;}-export function loadSceneData(world: World, sceneData: SceneData): Map<number, Entity> {+export function loadSceneData(+ world: World, sceneData: SceneData, external?: ReadonlyMap<number, Entity>,+): Map<number, Entity> {const { data } = migrateSceneData(sceneData);- return spawnAndLoadEntities(world, data);+ return spawnAndLoadEntities(world, data, external);}/**@@ -525,6 +533,12 @@ export async function loadSceneWithAssets(sceneData: SceneData,options?: SceneLoadOptions): Promise<Map<number, Entity>> {+ const onPhase = options?.onPhase;+ const timed = async <T>(phase: string, run: () => Promise<T> | T): Promise<T> => {+ if (!onPhase) return run();+ const began = performance.now();+ try { return await run(); } finally { onPhase(phase, performance.now() - began); }+ };// Expand prefab-instance entries first (via the same flattenPrefab core the// editor uses) so migration + asset resolution + spawn all operate on plain// entities — this is how a saved prefab scene achieves play == ship. The@@ -532,7 +546,7 @@ export async function loadSceneWithAssets(let scene = sceneData;if (options?.assets && sceneHasPrefabEntries(scene)) {const assets = options.assets;- scene = await expandScenePrefabs(scene, async (ref) => {+ scene = await timed('prefab', () => expandScenePrefabs(scene, async (ref) => {try {const r = await assets.loadPrefab(ref);return (r?.data as PrefabData) ?? null;@@ -540,14 +554,14 @@ export async function loadSceneWithAssets(log.warn('scene', `Failed to load prefab "${ref}": ${e}`);return null;}- });+ }));}// Migrate up-front to a private copy; asset resolution + spawn all operate// on it, so the caller's SceneData is never mutated.const { data } = migrateSceneData(scene);if (options?.assets) {const assets = options.assets;- const result = await assets.preloadSceneAssets(data, options.onProgress);+ const result = await timed('assets', () => assets.preloadSceneAssets(data, options.onProgress));if (options.onMissingAssets) {options.onMissingAssets(result.missing);}@@ -566,7 +580,7 @@ export async function loadSceneWithAssets(}}}- return spawnAndLoadEntities(world, data, options?.externalEntities);+ return timed('spawn', () => spawnAndLoadEntities(world, data, options?.externalEntities));}function applyTextureMetadata(sceneData: SceneData, textureHandles: Map<string, number>): void {diff --git a/sdk/src/scene/sceneManager.ts b/sdk/src/scene/sceneManager.tsindex d8cf17778..479066148 100644--- a/sdk/src/scene/sceneManager.ts+++ b/sdk/src/scene/sceneManager.ts@@ -57,6 +57,8 @@ export interface SceneConfig {* has a document boundary to cross.*/externalEntities?: () => ReadonlyMap<number, Entity>;+ /** Where this scene's load spent its time. See {@link SceneLoadOptions.onPhase}. */+ onPhase?: (phase: string, ms: number) => void;}/**@@ -441,6 +443,7 @@ export class SceneManagerState {const loadPromise = (async (): Promise<SceneContext> => {let sceneData = config.data;if (!sceneData && config.path) {+ const began = performance.now();const assetServer = this.app_.hasResource(Assets)? this.app_.getResource(Assets): null;@@ -450,6 +453,7 @@ export class SceneManagerState {const response = await fetch(config.path);sceneData = await response.json() as SceneData;}+ config.onPhase?.('fetch', performance.now() - began);}await this.loadSceneData_(instance, name, config, sceneData, onProgress);@@ -676,6 +680,7 @@ export class SceneManagerState {const loadOptions: SceneLoadOptions = { collectAssets };if (onProgress) loadOptions.onProgress = onProgress;if (config.externalEntities) loadOptions.externalEntities = config.externalEntities();+ if (config.onPhase) loadOptions.onPhase = config.onPhase;if (this.app_.hasResource(Assets)) {loadOptions.assets = this.app_.getResource(Assets);}diff --git a/tools/launchers/residency-run.mjs b/tools/launchers/residency-run.mjsindex 96fa15e45..577f910e2 100644--- a/tools/launchers/residency-run.mjs+++ b/tools/launchers/residency-run.mjs@@ -47,7 +47,7 @@ const LOG = flag('log', '');const logRe = LOG ? new RegExp(LOG, 'i') : null;/** Everything a read asks the game about, in one round trip. */-const NAMES = ['Player', 'Enemy', 'RockA', 'Wall', 'Arch', 'ArchTop', 'Beacon', 'Canary', 'Scout', 'Bobber'];+const NAMES = ['Player', 'Enemy', 'RockA', 'Wall', 'Arch', 'ArchTop', 'Beacon', 'Canary', 'Scout', 'Bobber', 'RefProbe', 'Sparks'];const MIME = {'.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript',@@ -257,8 +257,12 @@ async function main() {const ms = Math.round((performance.now() - began) * 1000) / 1000;${step.key ? `if (i === 0) send('keyup', ${JSON.stringify(step.key)});` : ''}const s = window.__estellaCooked.streaming();- out.push({ ms, resident: s.residentCells.length, loading: s.loadingCells.length,- entities: s.entities, bodies: s.physicsBodies, physicsUp: s.physicsUp });+ const row = { ms, resident: s.residentCells.length, loading: s.loadingCells.length,+ entities: s.entities, bodies: s.physicsBodies, physicsUp: s.physicsUp };+ // Only where it can matter: a system breakdown of every frame is more+ // data than a profile of one arrival needs.+ if (ms > ${step.costsAbove ?? 1.5}) row.costs = window.__estellaCooked.costs(6);+ out.push(row);// A macrotask turn between frames. Awaiting a step only drains// MICROtasks, and a cell arrives over the network — so a loop without// this starves the fetch and profiles a load that never lands.@@ -266,7 +270,9 @@ async function main() {}return out;})()`);+ const delivery = await exec('window.__estellaCooked.streaming().delivery');console.log(`profile ${step.as}: ${JSON.stringify(profile)}`);+ console.log(`delivery ${step.as}: ${JSON.stringify(delivery)}`);continue;}if (step.do === 'time') {diff --git a/tools/verify-world-residency.mjs b/tools/verify-world-residency.mjsindex 4c82dd08f..bd1ab8d94 100644--- a/tools/verify-world-residency.mjs+++ b/tools/verify-world-residency.mjs@@ -208,6 +208,13 @@ function main() {&& Math.abs(atC.at.ArchTop.x - 1900) < 1,'a child standing in another cell comes in with its root, not with its own place',`ArchTop at x=${atC.at.ArchTop?.x?.toFixed(0)}`);++ // ---- The one reference that crosses a document boundary ---------------+ claim(atC.at.RefProbe?.x === 1000,+ 'a reference the cell holds into the persistent world names the live entity',+ `probe at x=${atC.at.RefProbe?.x}`);+ claim(trip.atA.at.RefProbe?.x === 0,+ 'and there is nothing to resolve while the cell that holds it is absent');claim(trip.atA.at.ArchTop === undefined && atB.at.ArchTop === undefined,'and is gone whenever its root is');