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.

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.esscene
index 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.ts
index 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.ts
index 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.ts
index 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 asked
diff --git a/sdk/src/residency/report.ts b/sdk/src/residency/report.ts
index 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.ts
index 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): Promis
const 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.ts
index 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.ts
index 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.mjs
index 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.mjs
index 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');