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.

feat(runtime): a packaged world brings its places in, and its rows stay nameable

esenginefea2640446f1
diff --git a/examples/world-streaming-3d/assets/scenes/main.esscene b/examples/world-streaming-3d/assets/scenes/main.esscene
new file mode 100644
index 000000000..dfe886550
--- /dev/null
+++ b/examples/world-streaming-3d/assets/scenes/main.esscene
@@ -0,0 +1,718 @@
+{
+ "version": 4,
+ "name": "main",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 300,
+ "y": 200,
+ "z": 900
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 0,
+ "fov": 55,
+ "nearPlane": 10,
+ "farPlane": 6000,
+ "isActive": true,
+ "priority": 0
+ }
+ },
+ {
+ "type": "ThirdPersonCamera",
+ "data": {
+ "target": 2,
+ "distance": 420,
+ "pitch": 18
+ }
+ },
+ {
+ "type": "WorldPersistent",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "World",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "StreamedWorld",
+ "data": {
+ "cellSize": 600,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Player",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 300,
+ "y": 60,
+ "z": 300
+ },
+ "scale": {
+ "x": 0.6,
+ "y": 1.2,
+ "z": 0.6
+ }
+ }
+ },
+ {
+ "type": "CharacterController3D",
+ "data": {
+ "radius": 30,
+ "halfHeight": 30,
+ "stepHeight": 40,
+ "snapDown": 50
+ }
+ },
+ {
+ "type": "ThirdPersonController",
+ "data": {
+ "camera": 0,
+ "moveSpeed": 320,
+ "jumpSpeed": 520,
+ "idleThreshold": 8
+ }
+ },
+ {
+ "type": "Health",
+ "data": {
+ "current": 100,
+ "max": 100
+ }
+ },
+ {
+ "type": "PerceptionTarget",
+ "data": {}
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "WorldStreamingSource",
+ "data": {
+ "loadRadius": 250,
+ "unloadRadius": 450,
+ "enabled": true
+ }
+ },
+ {
+ "type": "WorldPersistent",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 3,
+ "name": "Ground",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 1200,
+ "y": -20,
+ "z": 400
+ },
+ "scale": {
+ "x": 32,
+ "y": 0.4,
+ "z": 16
+ }
+ }
+ },
+ {
+ "type": "RigidBody3D",
+ "data": {
+ "bodyType": 0
+ }
+ },
+ {
+ "type": "BoxCollider3D",
+ "data": {
+ "halfExtents": {
+ "x": 1600,
+ "y": 20,
+ "z": 800
+ },
+ "friction": 0.6
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.3,
+ "g": 0.34,
+ "b": 0.3,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "WorldPersistent",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 4,
+ "name": "Sun",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "rotation": {
+ "w": 0.83394695,
+ "x": -0.52086316,
+ "y": 0.18230211,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Light",
+ "data": {
+ "type": 1,
+ "intensity": 1.05,
+ "enabled": true,
+ "color": {
+ "r": 1,
+ "g": 0.96,
+ "b": 0.9,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "WorldPersistent",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 5,
+ "name": "NavVolume",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 900,
+ "y": 125,
+ "z": 300
+ }
+ }
+ },
+ {
+ "type": "NavVolume",
+ "data": {
+ "halfExtents": {
+ "x": 1200,
+ "y": 200,
+ "z": 600
+ },
+ "cellSize": 25,
+ "cellHeight": 10,
+ "agentHeight": 120,
+ "agentRadius": 30,
+ "stepHeight": 40
+ }
+ },
+ {
+ "type": "WorldPersistent",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 6,
+ "name": "Scout",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 1500,
+ "y": 60,
+ "z": 300
+ }
+ }
+ },
+ {
+ "type": "WorldStreamingSource",
+ "data": {
+ "loadRadius": 250,
+ "unloadRadius": 450,
+ "enabled": false
+ }
+ },
+ {
+ "type": "WorldPersistent",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 7,
+ "name": "Bobber",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 300,
+ "y": 60,
+ "z": 2700
+ }
+ }
+ },
+ {
+ "type": "WorldStreamingSource",
+ "data": {
+ "loadRadius": 250,
+ "unloadRadius": 450,
+ "enabled": false
+ }
+ },
+ {
+ "type": "WorldPersistent",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 8,
+ "name": "Canary",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 60,
+ "z": -200
+ }
+ }
+ },
+ {
+ "type": "Health",
+ "data": {
+ "current": 100,
+ "max": 100
+ }
+ },
+ {
+ "type": "WorldPersistent",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 20,
+ "name": "RockA",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 300,
+ "y": 30,
+ "z": 150
+ },
+ "scale": {
+ "x": 1,
+ "y": 1,
+ "z": 1
+ }
+ }
+ },
+ {
+ "type": "RigidBody3D",
+ "data": {
+ "bodyType": 0
+ }
+ },
+ {
+ "type": "BoxCollider3D",
+ "data": {
+ "halfExtents": {
+ "x": 50,
+ "y": 50,
+ "z": 50
+ },
+ "friction": 0.6
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.6,
+ "g": 0.55,
+ "b": 0.45,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 30,
+ "name": "Wall",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 900,
+ "y": 60,
+ "z": 480
+ },
+ "scale": {
+ "x": 8,
+ "y": 1.6,
+ "z": 0.8
+ }
+ }
+ },
+ {
+ "type": "RigidBody3D",
+ "data": {
+ "bodyType": 0
+ }
+ },
+ {
+ "type": "BoxCollider3D",
+ "data": {
+ "halfExtents": {
+ "x": 400,
+ "y": 80,
+ "z": 40
+ },
+ "friction": 0.6
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.5,
+ "g": 0.36,
+ "b": 0.3,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 31,
+ "name": "Enemy",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 1150,
+ "y": 60,
+ "z": 100
+ },
+ "scale": {
+ "x": 0.6,
+ "y": 1.2,
+ "z": 0.6
+ }
+ }
+ },
+ {
+ "type": "CharacterController3D",
+ "data": {
+ "radius": 30,
+ "halfHeight": 30,
+ "stepHeight": 40,
+ "snapDown": 50
+ }
+ },
+ {
+ "type": "NavAgent",
+ "data": {
+ "speed": 260,
+ "radius": 30,
+ "arriveRadius": 40,
+ "repathInterval": 0.35
+ }
+ },
+ {
+ "type": "Perceiver",
+ "data": {
+ "range": 420,
+ "fovDegrees": 360,
+ "losLayers": 1
+ }
+ },
+ {
+ "type": "Perception",
+ "data": {}
+ },
+ {
+ "type": "Hunter",
+ "data": {
+ "attackRange": 100,
+ "attackInterval": 1.6
+ }
+ },
+ {
+ "type": "Health",
+ "data": {
+ "current": 25,
+ "max": 25
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.8,
+ "g": 0.3,
+ "b": 0.28,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 40,
+ "name": "Arch",
+ "parent": null,
+ "children": [
+ 41
+ ],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 1500,
+ "y": 40,
+ "z": 300
+ },
+ "scale": {
+ "x": 2,
+ "y": 1,
+ "z": 2
+ }
+ }
+ },
+ {
+ "type": "RigidBody3D",
+ "data": {
+ "bodyType": 0
+ }
+ },
+ {
+ "type": "BoxCollider3D",
+ "data": {
+ "halfExtents": {
+ "x": 100,
+ "y": 50,
+ "z": 100
+ },
+ "friction": 0.6
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.45,
+ "g": 0.45,
+ "b": 0.6,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 41,
+ "name": "ArchTop",
+ "parent": 40,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 200,
+ "y": 60,
+ "z": 0
+ },
+ "scale": {
+ "x": 1,
+ "y": 1,
+ "z": 1
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.7,
+ "g": 0.7,
+ "b": 0.85,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 50,
+ "name": "Beacon",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 300,
+ "y": 30,
+ "z": 3300
+ },
+ "scale": {
+ "x": 1,
+ "y": 1,
+ "z": 1
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.9,
+ "g": 0.85,
+ "b": 0.4,
+ "a": 1
+ }
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/examples/world-streaming-3d/assets/scenes/main.esscene.meta b/examples/world-streaming-3d/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..71b73133e
--- /dev/null
+++ b/examples/world-streaming-3d/assets/scenes/main.esscene.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "66f52bdd-02bb-427a-aff1-16e4285b9ff4",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {}
+}
diff --git a/examples/world-streaming-3d/project.esproject b/examples/world-streaming-3d/project.esproject
new file mode 100644
index 000000000..ca62d5e82
--- /dev/null
+++ b/examples/world-streaming-3d/project.esproject
@@ -0,0 +1,13 @@
+{
+ "formatVersion": "1",
+ "name": "World Streaming 3D",
+ "description": "A world cut into cells at cook time: places exist because a source is near them, and stop existing when none is.",
+ "tag": "3D",
+ "version": "0.1.0",
+ "defaultScene": "assets/scenes/main.esscene",
+ "designResolution": {
+ "width": 960,
+ "height": 640
+ },
+ "spineVersion": "none"
+}
diff --git a/examples/world-streaming-3d/src/main.ts b/examples/world-streaming-3d/src/main.ts
new file mode 100644
index 000000000..ffc97901e
--- /dev/null
+++ b/examples/world-streaming-3d/src/main.ts
@@ -0,0 +1,72 @@
+// The gestures a criterion needs and residency must not provide: switching a
+// source off, moving one along a boundary, aiming a blow at an entity that is
+// gone. Residency itself is declared, and nothing below loads or unloads.
+import {
+ addSystemToSchedule, Schedule, defineSystem, GetWorld, Res, EventWriter, Time,
+ Input, Damage, Transform, WorldStreamingSource,
+} from 'esengine';
+import type { World, InputState, TimeData, EventWriterInstance, DamagePayload } from 'esengine';
+
+/** Flip a named source on or off. The only thing that changes is who is asking. */
+function toggleSource(world: World, name: string): void {
+ const entity = world.findEntityByName(name);
+ if (entity === null || !world.has(entity, WorldStreamingSource)) return;
+ world.update(entity, WorldStreamingSource, (source) => { source.enabled = !source.enabled; });
+}
+
+const sourceKeysSystem = defineSystem(
+ [Res(Input), GetWorld()],
+ (input: InputState, world: World) => {
+ if (input.isKeyPressed('KeyK')) toggleSource(world, 'Player');
+ if (input.isKeyPressed('KeyL')) toggleSource(world, 'Scout');
+ if (input.isKeyPressed('KeyM')) toggleSource(world, 'Bobber');
+ },
+ { name: 'SourceKeysSystem' },
+);
+
+/**
+ * Walk the bobber back and forth across a cell's load threshold without ever
+ * reaching its unload one. Written by the game because a criterion about the
+ * hysteresis band needs a position accurate to the unit, and a key held for a
+ * number of frames is not that.
+ */
+const bobberSystem = defineSystem(
+ [Res(Time), GetWorld()],
+ (time: TimeData, world: World) => {
+ const bobber = world.findEntityByName('Bobber');
+ if (bobber === null || !world.has(bobber, WorldStreamingSource)) return;
+ if (!world.get(bobber, WorldStreamingSource).enabled) return;
+ world.update(bobber, Transform, (transform) => {
+ transform.position.z = 2800 + 100 * Math.sin(time.elapsed * 4);
+ });
+ },
+ { name: 'BobberSystem' },
+);
+
+/**
+ * Aim a blow at an entity remembered from before its cell unloaded, and at one
+ * that never leaves.
+ *
+ * The pair is the point: the canary proves the gesture reached the damage bus,
+ * so the enemy being untouched is a handle refused, not a key that did nothing.
+ */
+let remembered = 0;
+const staleBlowSystem = defineSystem(
+ [Res(Input), GetWorld(), EventWriter(Damage)],
+ (input: InputState, world: World, damage: EventWriterInstance<DamagePayload>) => {
+ const enemy = world.findEntityByName('Enemy');
+ if (enemy !== null) remembered = enemy;
+ if (!input.isKeyPressed('KeyJ') || remembered === 0) return;
+ const player = world.findEntityByName('Player') ?? 0;
+ const canary = world.findEntityByName('Canary');
+ damage.send({ target: remembered, source: player, amount: 25, x: 0, y: 0, z: 0 });
+ if (canary !== null) {
+ damage.send({ target: canary, source: player, amount: 25, x: 0, y: 0, z: 0 });
+ }
+ },
+ { name: 'StaleBlowSystem' },
+);
+
+addSystemToSchedule(Schedule.Update, sourceKeysSystem);
+addSystemToSchedule(Schedule.Update, bobberSystem);
+addSystemToSchedule(Schedule.Update, staleBlowSystem);
diff --git a/examples/world-streaming-3d/tsconfig.json b/examples/world-streaming-3d/tsconfig.json
new file mode 100644
index 000000000..1f11ff310
--- /dev/null
+++ b/examples/world-streaming-3d/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "compilerOptions": {
+ "target": "ES2020",
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "strict": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "declaration": false,
+ "outDir": "./dist",
+ "rootDir": ".",
+ "paths": {
+ "esengine": ["./.esengine/sdk/index.d.ts"],
+ "esengine/wasm": ["./.esengine/sdk/wasm.d.ts"]
+ }
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules"]
+}
diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.ts
index 0b8566844..e2b8c04f1 100644
--- a/pipeline/src/runtime/gameHost.ts
+++ b/pipeline/src/runtime/gameHost.ts
@@ -19,8 +19,11 @@ import {
acquireWebGPUDevice, ThirdPersonCamera, CharacterController3D, AnimatorController,
Animator, TPC_SPEED, TPC_GROUNDED, Particle, MeleeAttack, Health,
Hunter, NavAgent, Perception, AnimatorRootMotion,
+ worldResidencyReport,
+} from 'esengine';
+import type {
+ SceneData, AddressableManifest, PackagedGameConfig, RenderSurfaceSource, WorldManifest,
} from 'esengine';
-import type { SceneData, AddressableManifest, PackagedGameConfig, RenderSurfaceSource } from 'esengine';
import type { ESEngineModule } from 'esengine/wasm';
async function boot(): Promise<void> {
const canvas = document.getElementById('canvas') as HTMLCanvasElement;
@@ -77,6 +80,14 @@ async function boot(): Promise<void> {
if (!chosen) throw new Error(`[estella] no scene named "${wanted}" in this package`);
const sceneData = (await (await fetch(`./${chosen}`)).json()) as SceneData;
+ // The cooked worlds this build carries. Fetched beside the entry scene because
+ // residency answers for the entry scene from its first frame, and a manifest
+ // that arrived later would be a world that popped in.
+ const worlds: WorldManifest[] = [];
+ for (const world of cfg.worlds ?? []) {
+ worlds.push((await (await fetch(`./${world.manifest}`)).json()) as WorldManifest);
+ }
+
const wasmBase = new URL('./wasm/', import.meta.url).href; // relative → mount-path agnostic
const { default: createModule } = (await import(/* @vite-ignore */ `${wasmBase}esengine.js`)) as {
default: (options?: Record<string, unknown>) => Promise<ESEngineModule>;
@@ -420,6 +431,40 @@ async function boot(): Promise<void> {
return {};
}
},
+ /**
+ * What residency did, and what the subsystems still hold.
+ *
+ * The counts are the whole point: a far cell that is not DRAWN and one
+ * that does not EXIST look identical from a camera. Read-only — nothing
+ * here loads a cell, so residency still has to have been caused by walking.
+ */
+ streaming(): Record<string, unknown> {
+ const report = worldResidencyReport(app);
+ // By NAME: the 3D world is a side module, and importing its resource
+ // here would pull the whole thing into a game that may not use physics.
+ const physics = app.getResourceByName('Physics3DRuntime') as {
+ bodies: Map<number, unknown>;
+ characters: Map<number, unknown>;
+ joints: Map<number, unknown>;
+ } | undefined;
+ let stalePhysics = 0;
+ for (const rows of [physics?.bodies, physics?.characters, physics?.joints]) {
+ for (const entity of rows?.keys() ?? []) {
+ if (!app.world.valid(entity)) stalePhysics++;
+ }
+ }
+ return {
+ ...report,
+ physicsBodies: physics?.bodies.size ?? 0,
+ physicsCharacters: physics?.characters.size ?? 0,
+ // Rows physics still keeps for entities the world no longer has. A
+ // teardown that forgot one shows up here and nowhere else.
+ stalePhysics,
+ navAgents: app.world.getEntitiesWithComponents([NavAgent]).length,
+ hunters: app.world.getEntitiesWithComponents([Hunter]).length,
+ entities: app.world.entityCount(),
+ };
+ },
/** 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. */
@@ -461,6 +506,7 @@ async function boot(): Promise<void> {
{ name: entryName, data: sceneData },
...sceneList.filter((s) => s.path !== cfg.entryScene).map((s) => ({ name: s.name, path: s.path })),
],
+ ...(worlds.length > 0 ? { worlds } : {}),
firstScene: entryName,
aspectRatio: canvas.width / canvas.height,
// Everything the config APPLIES to a live app: physics, the mixer, the theme.
diff --git a/pipeline/src/world/partitionWorld.ts b/pipeline/src/world/partitionWorld.ts
index 8df4f0e97..23e033320 100644
--- a/pipeline/src/world/partitionWorld.ts
+++ b/pipeline/src/world/partitionWorld.ts
@@ -384,15 +384,19 @@ function checkReferences(
persistentRefs: Set<number>,
errors: string[],
): void {
- const sameCell = (a: Placement, b: Placement): boolean =>
- a.cell !== null && b.cell !== null && a.cell.x === b.cell.x && a.cell.z === b.cell.z;
+ // One document, whether that is the persistent scene or one cell: everything
+ // in it comes and goes together, so a reference inside it can never dangle.
+ const sameDocument = (a: Placement, b: Placement): boolean =>
+ a.cell === null
+ ? b.cell === null
+ : b.cell !== null && a.cell.x === b.cell.x && a.cell.z === b.cell.z;
const check = (holder: SceneEntry, componentType: string, field: string, value: unknown): void => {
const one = (candidate: unknown): void => {
if (typeof candidate !== 'number' || !byId.has(candidate)) return;
const from = placement.get(holder.id);
const to = placement.get(candidate);
- if (!from || !to || from.root === to.root || sameCell(from, to)) return;
+ if (!from || !to || from.root === to.root || sameDocument(from, to)) return;
if (from.cell !== null && to.cell === null) { persistentRefs.add(candidate); return; }
const where = to.cell === null ? 'the persistent world' : `cell ${to.cell.x},${to.cell.z}`;
errors.push(
diff --git a/pipeline/tests/partition-world.test.ts b/pipeline/tests/partition-world.test.ts
index aff3b2721..5697d1ea9 100644
--- a/pipeline/tests/partition-world.test.ts
+++ b/pipeline/tests/partition-world.test.ts
@@ -103,6 +103,23 @@ describe('partitionWorld', () => {
expect(partition.errors.join('\n')).toContain('not top-level');
});
+ it('leaves references inside the persistent world alone', () => {
+ // Two persistent roots are one document: a camera naming the player it
+ // follows comes and goes with it, so nothing can dangle between them.
+ const partition = cut(scene(
+ entity(0, 'World', null, { components: [declaration] }),
+ entity(1, 'Camera', [0, 0, 0], {
+ components: [
+ { type: 'WorldPersistent', data: {} },
+ { type: 'ThirdPersonCamera', data: { target: 2 } },
+ ],
+ }),
+ entity(2, 'Player', [10, 0, 10], { components: [{ type: 'WorldPersistent', data: {} }] }),
+ ))!;
+ expect(partition.errors).toEqual([]);
+ expect(partition.persistentRefs).toEqual([]);
+ });
+
it('refuses a hard reference from one cell into another', () => {
const partition = cut(scene(
entity(0, 'World', null, { components: [declaration] }),
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 51c6f1aab..613b81467 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 · 1624 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1626 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -7106,6 +7106,7 @@ spineModule: SpineWasmModule | null | undefined
steamAppId: number | undefined
uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
+worlds: WorldManifest[] | undefined
```
## RuntimeOnly — const @public
@@ -7262,6 +7263,7 @@ type: string
```
cleanup: ((ctx: SceneContext) => void) | undefined
data: SceneData | undefined
+externalEntities: (() => ReadonlyMap<number, Entity>) | undefined
name: string
path: string | undefined
setup: ((ctx: SceneContext) => void | Promise<void>) | undefined
@@ -7319,6 +7321,7 @@ abortOnMissingAssets: boolean | undefined
assetBaseUrl: string | undefined
assets: Assets | undefined
collectAssets: LoadedSceneAssets | undefined
+externalEntities: ReadonlyMap<number, number> | undefined
onMissingAssets: MissingAssetCallback | undefined
onProgress: SceneLoadProgressCallback | undefined
```
@@ -10093,7 +10096,9 @@ assetRefsByCell: Record<string, number>
authoredCellEntityCounts: Record<string, number>
cellCount: number
cellEntityCounts: Record<string, number>
+cellHandles: Record<string, number[]>
cellRenderCounts: Record<string, number>
+cellStableIds: Record<string, number[]>
desiredCells: string[]
loadCount: number
loadingCells: string[]
@@ -10109,14 +10114,14 @@ unloadingCells: string[]
```
isLoaded: (name: string) => boolean
loadAdditive: (name: string) => Promise<unknown>
-register: (config: { name: string; path: string; }) => void
+register: (config: SceneConfig) => void
unload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>
```
## WorldStreamer — class @experimental
```
clear: () => void
-loadManifest: (manifest: WorldManifest) => void
+loadManifest: (manifest: WorldManifest, sceneConfig?: (cell: WorldCell) => SceneConfig) => void
manifest: WorldManifest | null
residencyOf: (name: string) => CellResidency
status: () => WorldStreamerStatus
@@ -12204,6 +12209,11 @@ ParticlePlugin
PerceptionPlugin
```
+## persistentEntityRows — function @experimental
+```
+(app: App, manifest: WorldManifest): ReadonlyMap<number, Entity>
+```
+
## pickEntitiesByRay — function @experimental
```
(world: PickWorld, ray: WorldRay, opts?: EntityPickOptions): Entity[]
@@ -12506,7 +12516,7 @@ PrefabsPlugin
## remapEntityFields — function @experimental
```
-(compData: SceneComponentData, entityMap: Map<number, Entity>): void
+(compData: SceneComponentData, entityMap: Map<number, Entity>, external?: ReadonlyMap<number, Entity>): void
```
## removeAnimatorParam — function @experimental
@@ -13049,6 +13059,11 @@ ServicesPlugin
MotionDriver<AnimatorClipMotion>
```
+## stableEntityId — function @experimental
+```
+(app: App, entity: Entity): number | undefined
+```
+
## stackOf — function @experimental
```
(error: unknown): string | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index b8f00925c..fc6cf8551 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 · 1643 experimental · 3 deprecated
+Symbols: 113 public · 89 beta · 1645 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -7299,6 +7299,7 @@ spineModule: SpineWasmModule | null | undefined
steamAppId: number | undefined
uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
+worlds: WorldManifest[] | undefined
```
## RuntimeOnly — const @public
@@ -7455,6 +7456,7 @@ type: string
```
cleanup: ((ctx: SceneContext) => void) | undefined
data: SceneData | undefined
+externalEntities: (() => ReadonlyMap<number, Entity>) | undefined
name: string
path: string | undefined
setup: ((ctx: SceneContext) => void | Promise<void>) | undefined
@@ -7512,6 +7514,7 @@ abortOnMissingAssets: boolean | undefined
assetBaseUrl: string | undefined
assets: Assets | undefined
collectAssets: LoadedSceneAssets | undefined
+externalEntities: ReadonlyMap<number, number> | undefined
onMissingAssets: MissingAssetCallback | undefined
onProgress: SceneLoadProgressCallback | undefined
```
@@ -10286,7 +10289,9 @@ assetRefsByCell: Record<string, number>
authoredCellEntityCounts: Record<string, number>
cellCount: number
cellEntityCounts: Record<string, number>
+cellHandles: Record<string, number[]>
cellRenderCounts: Record<string, number>
+cellStableIds: Record<string, number[]>
desiredCells: string[]
loadCount: number
loadingCells: string[]
@@ -10302,14 +10307,14 @@ unloadingCells: string[]
```
isLoaded: (name: string) => boolean
loadAdditive: (name: string) => Promise<unknown>
-register: (config: { name: string; path: string; }) => void
+register: (config: SceneConfig) => void
unload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>
```
## WorldStreamer — class @experimental
```
clear: () => void
-loadManifest: (manifest: WorldManifest) => void
+loadManifest: (manifest: WorldManifest, sceneConfig?: (cell: WorldCell) => SceneConfig) => void
manifest: WorldManifest | null
residencyOf: (name: string) => CellResidency
status: () => WorldStreamerStatus
@@ -12447,6 +12452,11 @@ ParticlePlugin
PerceptionPlugin
```
+## persistentEntityRows — function @experimental
+```
+(app: App, manifest: WorldManifest): ReadonlyMap<number, Entity>
+```
+
## pickEntitiesByRay — function @experimental
```
(world: PickWorld, ray: WorldRay, opts?: EntityPickOptions): Entity[]
@@ -12749,7 +12759,7 @@ PrefabsPlugin
## remapEntityFields — function @experimental
```
-(compData: SceneComponentData, entityMap: Map<number, Entity>): void
+(compData: SceneComponentData, entityMap: Map<number, Entity>, external?: ReadonlyMap<number, Entity>): void
```
## removeAnimatorParam — function @experimental
@@ -13292,6 +13302,11 @@ ServicesPlugin
MotionDriver<AnimatorClipMotion>
```
+## stableEntityId — function @experimental
+```
+(app: App, entity: Entity): number | undefined
+```
+
## stackOf — function @experimental
```
(error: unknown): string | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 9863bd7d2..fa76f9a18 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 · 1623 experimental · 3 deprecated
+Symbols: 113 public · 86 beta · 1625 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7101,6 +7101,7 @@ spineModule: SpineWasmModule | null | undefined
steamAppId: number | undefined
uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
+worlds: WorldManifest[] | undefined
```
## RuntimeOnly — const @public
@@ -7257,6 +7258,7 @@ type: string
```
cleanup: ((ctx: SceneContext) => void) | undefined
data: SceneData | undefined
+externalEntities: (() => ReadonlyMap<number, Entity>) | undefined
name: string
path: string | undefined
setup: ((ctx: SceneContext) => void | Promise<void>) | undefined
@@ -7314,6 +7316,7 @@ abortOnMissingAssets: boolean | undefined
assetBaseUrl: string | undefined
assets: Assets | undefined
collectAssets: LoadedSceneAssets | undefined
+externalEntities: ReadonlyMap<number, number> | undefined
onMissingAssets: MissingAssetCallback | undefined
onProgress: SceneLoadProgressCallback | undefined
```
@@ -10088,7 +10091,9 @@ assetRefsByCell: Record<string, number>
authoredCellEntityCounts: Record<string, number>
cellCount: number
cellEntityCounts: Record<string, number>
+cellHandles: Record<string, number[]>
cellRenderCounts: Record<string, number>
+cellStableIds: Record<string, number[]>
desiredCells: string[]
loadCount: number
loadingCells: string[]
@@ -10104,14 +10109,14 @@ unloadingCells: string[]
```
isLoaded: (name: string) => boolean
loadAdditive: (name: string) => Promise<unknown>
-register: (config: { name: string; path: string; }) => void
+register: (config: SceneConfig) => void
unload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>
```
## WorldStreamer — class @experimental
```
clear: () => void
-loadManifest: (manifest: WorldManifest) => void
+loadManifest: (manifest: WorldManifest, sceneConfig?: (cell: WorldCell) => SceneConfig) => void
manifest: WorldManifest | null
residencyOf: (name: string) => CellResidency
status: () => WorldStreamerStatus
@@ -12209,6 +12214,11 @@ ParticlePlugin
PerceptionPlugin
```
+## persistentEntityRows — function @experimental
+```
+(app: App, manifest: WorldManifest): ReadonlyMap<number, Entity>
+```
+
## pickEntitiesByRay — function @experimental
```
(world: PickWorld, ray: WorldRay, opts?: EntityPickOptions): Entity[]
@@ -12511,7 +12521,7 @@ PrefabsPlugin
## remapEntityFields — function @experimental
```
-(compData: SceneComponentData, entityMap: Map<number, Entity>): void
+(compData: SceneComponentData, entityMap: Map<number, Entity>, external?: ReadonlyMap<number, Entity>): void
```
## removeAnimatorParam — function @experimental
@@ -13054,6 +13064,11 @@ ServicesPlugin
MotionDriver<AnimatorClipMotion>
```
+## stableEntityId — function @experimental
+```
+(app: App, entity: Entity): number | undefined
+```
+
## stackOf — function @experimental
```
(error: unknown): string | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 4697306d4..295c8b01b 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 · 1645 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1647 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7347,6 +7347,7 @@ spineModule: SpineWasmModule | null | undefined
steamAppId: number | undefined
uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
+worlds: WorldManifest[] | undefined
```
## RuntimeOnly — const @public
@@ -7503,6 +7504,7 @@ type: string
```
cleanup: ((ctx: SceneContext) => void) | undefined
data: SceneData | undefined
+externalEntities: (() => ReadonlyMap<number, Entity>) | undefined
name: string
path: string | undefined
setup: ((ctx: SceneContext) => void | Promise<void>) | undefined
@@ -7560,6 +7562,7 @@ abortOnMissingAssets: boolean | undefined
assetBaseUrl: string | undefined
assets: Assets | undefined
collectAssets: LoadedSceneAssets | undefined
+externalEntities: ReadonlyMap<number, number> | undefined
onMissingAssets: MissingAssetCallback | undefined
onProgress: SceneLoadProgressCallback | undefined
```
@@ -10340,7 +10343,9 @@ assetRefsByCell: Record<string, number>
authoredCellEntityCounts: Record<string, number>
cellCount: number
cellEntityCounts: Record<string, number>
+cellHandles: Record<string, number[]>
cellRenderCounts: Record<string, number>
+cellStableIds: Record<string, number[]>
desiredCells: string[]
loadCount: number
loadingCells: string[]
@@ -10356,14 +10361,14 @@ unloadingCells: string[]
```
isLoaded: (name: string) => boolean
loadAdditive: (name: string) => Promise<unknown>
-register: (config: { name: string; path: string; }) => void
+register: (config: SceneConfig) => void
unload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>
```
## WorldStreamer — class @experimental
```
clear: () => void
-loadManifest: (manifest: WorldManifest) => void
+loadManifest: (manifest: WorldManifest, sceneConfig?: (cell: WorldCell) => SceneConfig) => void
manifest: WorldManifest | null
residencyOf: (name: string) => CellResidency
status: () => WorldStreamerStatus
@@ -12466,6 +12471,11 @@ ParticlePlugin
PerceptionPlugin
```
+## persistentEntityRows — function @experimental
+```
+(app: App, manifest: WorldManifest): ReadonlyMap<number, Entity>
+```
+
## pickEntitiesByRay — function @experimental
```
(world: PickWorld, ray: WorldRay, opts?: EntityPickOptions): Entity[]
@@ -12768,7 +12778,7 @@ PrefabsPlugin
## remapEntityFields — function @experimental
```
-(compData: SceneComponentData, entityMap: Map<number, Entity>): void
+(compData: SceneComponentData, entityMap: Map<number, Entity>, external?: ReadonlyMap<number, Entity>): void
```
## removeAnimatorParam — function @experimental
@@ -13311,6 +13321,11 @@ ServicesPlugin
MotionDriver<AnimatorClipMotion>
```
+## stableEntityId — function @experimental
+```
+(app: App, entity: Entity): number | undefined
+```
+
## stackOf — function @experimental
```
(error: unknown): string | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index fab606363..6f2781216 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 · 1635 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1637 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7108,6 +7108,7 @@ spineModule: SpineWasmModule | null | undefined
steamAppId: number | undefined
uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
+worlds: WorldManifest[] | undefined
```
## RuntimeOnly — const @public
@@ -7264,6 +7265,7 @@ type: string
```
cleanup: ((ctx: SceneContext) => void) | undefined
data: SceneData | undefined
+externalEntities: (() => ReadonlyMap<number, Entity>) | undefined
name: string
path: string | undefined
setup: ((ctx: SceneContext) => void | Promise<void>) | undefined
@@ -7321,6 +7323,7 @@ abortOnMissingAssets: boolean | undefined
assetBaseUrl: string | undefined
assets: Assets | undefined
collectAssets: LoadedSceneAssets | undefined
+externalEntities: ReadonlyMap<number, number> | undefined
onMissingAssets: MissingAssetCallback | undefined
onProgress: SceneLoadProgressCallback | undefined
```
@@ -10116,7 +10119,9 @@ assetRefsByCell: Record<string, number>
authoredCellEntityCounts: Record<string, number>
cellCount: number
cellEntityCounts: Record<string, number>
+cellHandles: Record<string, number[]>
cellRenderCounts: Record<string, number>
+cellStableIds: Record<string, number[]>
desiredCells: string[]
loadCount: number
loadingCells: string[]
@@ -10132,14 +10137,14 @@ unloadingCells: string[]
```
isLoaded: (name: string) => boolean
loadAdditive: (name: string) => Promise<unknown>
-register: (config: { name: string; path: string; }) => void
+register: (config: SceneConfig) => void
unload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>
```
## WorldStreamer — class @experimental
```
clear: () => void
-loadManifest: (manifest: WorldManifest) => void
+loadManifest: (manifest: WorldManifest, sceneConfig?: (cell: WorldCell) => SceneConfig) => void
manifest: WorldManifest | null
residencyOf: (name: string) => CellResidency
status: () => WorldStreamerStatus
@@ -12232,6 +12237,11 @@ ParticlePlugin
PerceptionPlugin
```
+## persistentEntityRows — function @experimental
+```
+(app: App, manifest: WorldManifest): ReadonlyMap<number, Entity>
+```
+
## pickEntitiesByRay — function @experimental
```
(world: PickWorld, ray: WorldRay, opts?: EntityPickOptions): Entity[]
@@ -12534,7 +12544,7 @@ PrefabsPlugin
## remapEntityFields — function @experimental
```
-(compData: SceneComponentData, entityMap: Map<number, Entity>): void
+(compData: SceneComponentData, entityMap: Map<number, Entity>, external?: ReadonlyMap<number, Entity>): void
```
## removeAnimatorParam — function @experimental
@@ -13077,6 +13087,11 @@ ServicesPlugin
MotionDriver<AnimatorClipMotion>
```
+## stableEntityId — function @experimental
+```
+(app: App, entity: Entity): number | undefined
+```
+
## stackOf — function @experimental
```
(error: unknown): string | undefined
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 591a7bd42..cb2f43e1f 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -241,6 +241,8 @@ export {
worldResidencyPlugin,
worldResidencySystem,
worldResidencyReport,
+ persistentEntityRows,
+ stableEntityId,
type StreamedWorldData,
type WorldStreamingSourceData,
type WorldCell,
diff --git a/sdk/src/residency/WorldStreamer.ts b/sdk/src/residency/WorldStreamer.ts
index d46c614e4..91bd0531c 100644
--- a/sdk/src/residency/WorldStreamer.ts
+++ b/sdk/src/residency/WorldStreamer.ts
@@ -18,6 +18,7 @@
*/
import { desiredResidency, type ResidencySource, type WorldCell, type WorldManifest } from './cells';
+import type { SceneConfig } from '../scene/sceneManager';
import { defineResource } from '../ecs/resource';
import { log } from '../util/logger';
@@ -31,7 +32,7 @@ export type CellResidency = 'unloaded' | 'loading' | 'resident' | 'unloading';
* @experimental
*/
export interface WorldStreamHost {
- register(config: { name: string; path: string }): void;
+ register(config: SceneConfig): void;
loadAdditive(name: string): Promise<unknown>;
unload(name: string, options?: { keepPersistent?: boolean }): Promise<void>;
isLoaded(name: string): boolean;
@@ -72,17 +73,17 @@ export class WorldStreamer {
}
/**
- * Adopt a cooked world: its cells become loadable scenes and residency starts
- * answering for them.
+ * Adopt a cooked world: its cells become loadable scenes and residency
+ * answers for them.
*
- * Registered here rather than beside the game's own scenes: a cell is content
+ * Registered here, not beside the game's own scenes: a cell is content
* residency brings in, and `switchTo('cell_3_2')` is a second author.
*/
- loadManifest(manifest: WorldManifest): void {
+ loadManifest(manifest: WorldManifest, sceneConfig?: (cell: WorldCell) => SceneConfig): void {
this.manifest_ = manifest;
this.cells_.clear();
for (const cell of manifest.cells) {
- this.host_.register({ name: cell.name, path: cell.path });
+ this.host_.register(sceneConfig?.(cell) ?? { name: cell.name, path: cell.path });
this.cells_.set(cell.name, { cell, residency: 'unloaded', desired: false });
}
}
diff --git a/sdk/src/residency/identity.ts b/sdk/src/residency/identity.ts
new file mode 100644
index 000000000..2ce851812
--- /dev/null
+++ b/sdk/src/residency/identity.ts
@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file identity.ts
+ * @brief The authored id an entity came from, which is what survives a cell
+ * leaving and coming back.
+ *
+ * @details A runtime handle names an entity that EXISTS; a cell's unload ends
+ * every one of them and its reload mints new ones. So a handle is the
+ * wrong thing to write down about a place, and the authored id — the row
+ * the cook wrote into the cell document — is the right one.
+ *
+ * Recorded through `SceneOrigins`, which a streamed world switches on:
+ * a game that never streams keeps paying nothing for the table.
+ */
+
+import type { App } from '../app/app';
+import type { Entity } from '../types';
+import { SceneManager } from '../scene/sceneManager';
+import { sceneOriginOf } from '../scene/sceneOrigins';
+import type { WorldManifest } from './cells';
+
+/**
+ * Authored id → live entity, for the persistent rows a cell is allowed to name.
+ *
+ * Only the rows the cook recorded: a table of the whole persistent world would
+ * be a cost every frame of every game pays for the handful of references that
+ * actually cross the boundary.
+ */
+export function persistentEntityRows(
+ app: App, manifest: WorldManifest,
+): ReadonlyMap<number, Entity> {
+ const rows = new Map<number, Entity>();
+ if (manifest.persistentRefs.length === 0 || !app.hasResource(SceneManager)) return rows;
+ const wanted = new Set(manifest.persistentRefs);
+ const persistent = app.getResource(SceneManager).getScene(manifest.scene);
+ if (persistent === null) return rows;
+ for (const entity of persistent.entities) {
+ const authored = sceneOriginOf(app, entity);
+ if (authored !== undefined && wanted.has(authored)) rows.set(authored, entity);
+ }
+ return rows;
+}
+
+/**
+ * The authored id `entity` was loaded from — its identity across a cell's
+ * lifetime, as opposed to the handle, which is only good while it exists.
+ */
+export function stableEntityId(app: App, entity: Entity): number | undefined {
+ return sceneOriginOf(app, entity);
+}
diff --git a/sdk/src/residency/index.ts b/sdk/src/residency/index.ts
index f84ffaa4d..1b0cecbf9 100644
--- a/sdk/src/residency/index.ts
+++ b/sdk/src/residency/index.ts
@@ -19,3 +19,4 @@ export {
} from './WorldStreamer';
export { worldResidencyPlugin, worldResidencySystem } from './residencyPlugin';
export { worldResidencyReport, type WorldResidencyReport } from './report';
+export { persistentEntityRows, stableEntityId } from './identity';
diff --git a/sdk/src/residency/report.ts b/sdk/src/residency/report.ts
index 61bf419cd..9e72d3354 100644
--- a/sdk/src/residency/report.ts
+++ b/sdk/src/residency/report.ts
@@ -17,6 +17,7 @@
import type { App } from '../app/app';
import { SceneManager } from '../scene/sceneManager';
import { WorldStreaming } from './WorldStreamer';
+import { stableEntityId } from './identity';
import { renderableComponents } from '../ecs/component';
/** @experimental */
@@ -39,6 +40,10 @@ export interface WorldResidencyReport {
assetRefsByCell: Record<string, number>;
/** What the cook put in each cell — the number a live count is checked against. */
authoredCellEntityCounts: Record<string, number>;
+ /** The authored rows each resident cell instantiated; unchanged by a reload. */
+ cellStableIds: Record<string, number[]>;
+ /** The runtime handles those rows currently have; a reload mints new ones. */
+ cellHandles: Record<string, number[]>;
/** Live entities the persistent world owns; residency never touches these. */
persistentEntities: number;
}
@@ -48,7 +53,7 @@ const EMPTY: WorldResidencyReport = {
desiredCells: [], residentCells: [], loadingCells: [], unloadingCells: [],
loadCount: 0, unloadCount: 0,
cellEntityCounts: {}, cellRenderCounts: {}, assetRefsByCell: {},
- authoredCellEntityCounts: {}, persistentEntities: 0,
+ authoredCellEntityCounts: {}, cellStableIds: {}, cellHandles: {}, persistentEntities: 0,
};
/**
@@ -68,6 +73,8 @@ export function worldResidencyReport(app: App): WorldResidencyReport {
const cellRenderCounts: Record<string, number> = {};
const assetRefsByCell: Record<string, number> = {};
const authoredCellEntityCounts: Record<string, number> = {};
+ const cellStableIds: Record<string, number[]> = {};
+ const cellHandles: Record<string, number[]> = {};
const drawing = renderableComponents();
for (const cell of manifest.cells) {
authoredCellEntityCounts[cell.name] = cell.entityCount;
@@ -76,11 +83,18 @@ export function worldResidencyReport(app: App): WorldResidencyReport {
// between "not here" and "here and empty" that a zero would hide.
if (context === null) continue;
let drawn = 0;
+ const stable: number[] = [];
+ const handles: number[] = [];
for (const entity of context.entities) {
if (drawing.some((component) => app.world.has(entity, component))) drawn++;
+ const authored = stableEntityId(app, entity);
+ if (authored !== undefined) stable.push(authored);
+ handles.push(entity);
}
cellEntityCounts[cell.name] = context.entities.size;
cellRenderCounts[cell.name] = drawn;
+ cellStableIds[cell.name] = stable.sort((a, b) => a - b);
+ cellHandles[cell.name] = handles.sort((a, b) => a - b);
assetRefsByCell[cell.name] = scenes.assetScopeFor(cell.name)?.size ?? 0;
}
@@ -95,6 +109,7 @@ export function worldResidencyReport(app: App): WorldResidencyReport {
loadCount: status.loadCount,
unloadCount: status.unloadCount,
cellEntityCounts, cellRenderCounts, assetRefsByCell, authoredCellEntityCounts,
+ cellStableIds, cellHandles,
persistentEntities: scenes.getScene(manifest.scene)?.entities.size ?? 0,
};
}
diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.ts
index 94f0a3b03..50685a95f 100644
--- a/sdk/src/runtime/runtimeLoader.ts
+++ b/sdk/src/runtime/runtimeLoader.ts
@@ -7,7 +7,7 @@
import { SceneOwner } from '../ecs/component';
import { loadSceneData, updateCameraAspectRatio, sceneHasPrefabEntries, expandScenePrefabs, type SceneData } from '../scene/scene';
-import { recordSceneOrigins } from '../scene/sceneOrigins';
+import { recordSceneOrigins, enableSceneOrigins } from '../scene/sceneOrigins';
import type { PrefabData } from '../prefab/types';
import { switchTheme, resolveThemeTokens, type ThemeOverrides } from '../ui';
import { discoverSceneAssets } from '../asset/discoverAssets';
@@ -27,6 +27,9 @@ import { transcoderFromModule, type BasisWasmModule } from '../asset/basisTransc
import type { BasisTranscoder } from '../asset/compressed';
import type { TextureImportSettings } from '../asset/loaders/TextureLoader';
import { SceneManager, type SceneConfig } from '../scene/sceneManager';
+import { WorldStreaming } from '../residency/WorldStreamer';
+import { persistentEntityRows } from '../residency/identity';
+import type { WorldManifest } from '../residency/cells';
import { DEFAULT_GRAVITY, DEFAULT_FIXED_TIMESTEP } from '../defaults';
import { SpriteAnimation } from '../animation/SpriteAnimator';
import { Audio } from '../audio/Audio';
@@ -547,6 +550,12 @@ export interface RuntimeInitConfig {
* time; `path` registers a lazy scene fetched through the runtime Assets
* on first {@link SceneManagerState.switchTo}/load. One of the two. */
scenes: Array<{ name: string; data?: SceneData; path?: string }>;
+ /**
+ * Cooked worlds the build carries. The one belonging to `firstScene` is
+ * adopted by the streamer after that scene is up — its cells are content
+ * residency brings in, so they are deliberately not in `scenes`.
+ */
+ worlds?: WorldManifest[];
firstScene: string;
spineModule?: SpineWasmModule | null;
spineManager?: SpineManager | null;
@@ -648,11 +657,31 @@ export async function initRuntime(config: RuntimeInitConfig): Promise<void> {
mgr.register(createRuntimeSceneConfig(scene.name, scene.data, sceneOpts, scene.path));
}
+ // Identity before the world exists: a streamed entity's authored id is what
+ // survives its cell leaving, and the table only records what loads after this.
+ const world = (config.worlds ?? []).find((candidate) => candidate.scene === firstScene) ?? null;
+ for (const other of config.worlds ?? []) {
+ if (other !== world) {
+ log.warn('residency', `world "${other.scene}" is cooked but only the entry scene's is adopted`);
+ }
+ }
+ if (world) enableSceneOrigins(app);
+
if (firstScene) {
mgr.setInitial(firstScene);
await mgr.load(firstScene);
}
+ if (world && app.hasResource(WorldStreaming)) {
+ // 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),
+ }));
+ }
+
if (aspectRatio !== undefined) {
updateCameraAspectRatio(app.world, aspectRatio);
}
diff --git a/sdk/src/scene/scene.ts b/sdk/src/scene/scene.ts
index b883324d5..89caf50ea 100644
--- a/sdk/src/scene/scene.ts
+++ b/sdk/src/scene/scene.ts
@@ -108,6 +108,12 @@ export interface SceneLoadOptions {
* assets get handle 0, scene loads anyway).
*/
abortOnMissingAssets?: boolean;
+ /**
+ * Authored ids this document may reference that live in another one — the
+ * persistent rows a streamed cell is allowed to name. Absent = a reference
+ * outside the document resolves to nothing, which is what it always did.
+ */
+ externalEntities?: ReadonlyMap<number, Entity>;
}
export class MissingAssetsError extends Error {
@@ -166,13 +172,24 @@ export function getComponentSkeletalFieldDescriptor(
// Entity Reference Remapping
// =============================================================================
-export function remapEntityFields(compData: SceneComponentData, entityMap: Map<number, Entity>): void {
+/**
+ * Resolve a document's entity references to live entities.
+ *
+ * `external` answers for authored ids that live in ANOTHER document — the rows a
+ * streamed cell is allowed to name in the persistent world. An id neither map
+ * knows is cleared, never left as a number that names a different entity.
+ */
+export function remapEntityFields(
+ compData: SceneComponentData,
+ entityMap: Map<number, Entity>,
+ external?: ReadonlyMap<number, Entity>,
+): void {
const comp = getComponent(compData.type);
if (!comp || comp.entityFields.length === 0) return;
const data = compData.data as Record<string, unknown>;
const remap = (editorId: unknown): unknown => {
if (typeof editorId !== 'number' || editorId === INVALID_ENTITY) return editorId;
- const runtimeId = entityMap.get(editorId);
+ const runtimeId = entityMap.get(editorId) ?? external?.get(editorId);
if (runtimeId === undefined) {
log.warn(
'scene',
@@ -431,7 +448,9 @@ function checkLoadable(sceneData: SceneData): void {
}
}
-function spawnAndLoadEntities(world: World, sceneData: SceneData): Map<number, Entity> {
+function spawnAndLoadEntities(
+ world: World, sceneData: SceneData, external?: ReadonlyMap<number, Entity>,
+): Map<number, Entity> {
checkLoadable(sceneData);
const entityMap = new Map<number, Entity>();
@@ -455,7 +474,7 @@ function spawnAndLoadEntities(world: World, sceneData: SceneData): Map<number, E
if (isPrefabEntry(entityData)) continue;
const entity = entityMap.get(entityData.id)!;
for (const compData of entityData.components) {
- remapEntityFields(compData, entityMap);
+ remapEntityFields(compData, entityMap, external);
loadComponent(world, entity, compData, entityData.name);
}
}
@@ -547,7 +566,7 @@ export async function loadSceneWithAssets(
}
}
}
- return spawnAndLoadEntities(world, data);
+ return 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 8eea05dcc..d8cf17778 100644
--- a/sdk/src/scene/sceneManager.ts
+++ b/sdk/src/scene/sceneManager.ts
@@ -51,6 +51,12 @@ export interface SceneConfig {
systems?: Array<{ schedule: Schedule; system: SystemDef }>;
setup?: (ctx: SceneContext) => void | Promise<void>;
cleanup?: (ctx: SceneContext) => void;
+ /**
+ * Authored ids this scene may reference in ANOTHER document, resolved at load
+ * time. A streamed cell names the persistent world through this; nothing else
+ * has a document boundary to cross.
+ */
+ externalEntities?: () => ReadonlyMap<number, Entity>;
}
/**
@@ -669,6 +675,7 @@ export class SceneManagerState {
const loadOptions: SceneLoadOptions = { collectAssets };
if (onProgress) loadOptions.onProgress = onProgress;
+ if (config.externalEntities) loadOptions.externalEntities = config.externalEntities();
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
new file mode 100644
index 000000000..99cd3dd9c
--- /dev/null
+++ b/tools/launchers/residency-run.mjs
@@ -0,0 +1,234 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file residency-run.mjs — drive a packaged streamed world and read what exists.
+ *
+ * A camera cannot answer this. "The far place is not drawn" and "the far place
+ * does not exist" produce the same pixels, and a body an unload forgot is
+ * invisible until someone walks into it. So this drives the real package with
+ * real input and reads `__estellaCooked.streaming()` — counts, per cell, of
+ * things that ARE.
+ *
+ * Which key walks which way is CALIBRATED rather than assumed: movement is
+ * relative to the camera, so a fixture that reorients its camera would silently
+ * turn every leg of a route into someone walking backwards.
+ *
+ * electron tools/launchers/residency-run.mjs --dir <exportDir> --script <file.json>
+ * --w / --h surface size (default 640x360)
+ * --budget <n> give up on a leg after this many frames (default 900)
+ * --log <regex> also print console lines matching this
+ *
+ * A script is a list of steps: {do:"read",as}, {do:"walkTo",x,z},
+ * {do:"tap",key}, {do:"step",frames}. Each read prints one JSON line.
+ */
+import { app, BrowserWindow } from 'electron';
+import http from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { onRendererConsole } from '../lib/rendererConsole.mjs';
+
+app.commandLine.appendSwitch('enable-unsafe-swiftshader');
+app.commandLine.appendSwitch('force-color-profile', 'srgb');
+app.commandLine.appendSwitch('force-device-scale-factor', '1');
+
+const argv = process.argv.slice(2);
+const flag = (name, fallback) => {
+ const i = argv.indexOf(`--${name}`);
+ return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : fallback;
+};
+
+const DIR = path.resolve(flag('dir', ''));
+const SCRIPT = flag('script', '');
+const W = Number(flag('w', '640'));
+const H = Number(flag('h', '360'));
+const BUDGET = Number(flag('budget', '900'));
+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'];
+
+const MIME = {
+ '.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript',
+ '.json': 'application/json', '.wasm': 'application/wasm', '.png': 'image/png',
+ '.jpg': 'image/jpeg', '.webp': 'image/webp', '.ktx2': 'image/ktx2',
+ '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.css': 'text/css',
+};
+
+function serve(root) {
+ const server = http.createServer(async (req, res) => {
+ try {
+ let rel = decodeURIComponent(new URL(req.url, 'http://x').pathname).replace(/^\/+/, '');
+ if (rel === '') rel = 'index.html';
+ const abs = path.join(root, rel);
+ if (!abs.startsWith(root)) { res.writeHead(403).end(); return; }
+ const bytes = await readFile(abs);
+ res.writeHead(200, { 'content-type': MIME[path.extname(abs).toLowerCase()] ?? 'application/octet-stream' })
+ .end(bytes);
+ } catch {
+ res.writeHead(404).end();
+ }
+ });
+ return new Promise((resolve) => server.listen(0, '127.0.0.1', () => resolve(server)));
+}
+
+/** Hold keys for `frames` engine frames of fixed dt, then release. */
+const holdScript = (keys, frames) => `
+(() => {
+ const target = document.querySelector('canvas') ?? window;
+ const send = (type, code) => {
+ const e = new KeyboardEvent(type, { code, key: code, bubbles: true, cancelable: true });
+ target.dispatchEvent(e);
+ if (target !== window) window.dispatchEvent(new KeyboardEvent(type, { code, key: code, bubbles: true }));
+ };
+ const held = ${JSON.stringify(keys)};
+ for (const k of held) send('keydown', k);
+ return (async () => {
+ await window.__estellaCooked.step(${frames}, 1 / 60);
+ for (const k of held) send('keyup', k);
+ return true;
+ })();
+})()
+`;
+
+/** Press and release a key inside one frame, then let `frames` more run. */
+const tapScript = (key, frames) => `
+(() => {
+ const target = document.querySelector('canvas') ?? window;
+ const send = (type, code) => {
+ const e = new KeyboardEvent(type, { code, key: code, bubbles: true, cancelable: true });
+ target.dispatchEvent(e);
+ if (target !== window) window.dispatchEvent(new KeyboardEvent(type, { code, key: code, bubbles: true }));
+ };
+ send('keydown', ${JSON.stringify(key)});
+ return (async () => {
+ await window.__estellaCooked.step(1, 1 / 60);
+ send('keyup', ${JSON.stringify(key)});
+ await window.__estellaCooked.step(${frames}, 1 / 60);
+ return true;
+ })();
+})()
+`;
+
+function fail(message, code = 1) {
+ console.log(`✗ ${message}`);
+ app.exit(code);
+}
+
+async function main() {
+ if (!DIR || !existsSync(path.join(DIR, 'index.html'))) return fail(`no index.html under ${DIR || '(--dir)'}`, 2);
+ if (!SCRIPT || !existsSync(SCRIPT)) return fail(`no script at ${SCRIPT || '(--script)'}`, 2);
+ const steps = JSON.parse(await readFile(SCRIPT, 'utf8'));
+ const server = await serve(DIR);
+ const win = new BrowserWindow({
+ width: W, height: H, useContentSize: true, show: false,
+ webPreferences: { offscreen: false, backgroundThrottling: false },
+ });
+ await win.webContents.session.clearCache();
+ const errors = [];
+ const stop = onRendererConsole(win.webContents, (msg) => {
+ if (/error|uncaught|failed/i.test(msg)) errors.push(msg.slice(0, 300));
+ if (logRe?.test(msg)) console.log(` ${msg}`);
+ });
+ await win.loadURL(`http://127.0.0.1:${server.address().port}/?headless`);
+ const exec = (js) => win.webContents.executeJavaScript(js);
+
+ let ready = false;
+ for (let i = 0; i < 300 && !ready; i++) {
+ ready = await exec(`(() => {
+ const c = window.__estellaCooked;
+ if (!c || !c.streaming) return false;
+ return !!c.probe(['Player']).at.Player;
+ })()`).catch(() => false);
+ if (!ready) await new Promise((r) => setTimeout(r, 100));
+ }
+ if (!ready) { stop(); server.close(); return fail('the package never exposed a streaming report', 2); }
+ if (!(await exec('(() => { window.__estellaCooked.setPaused(true); return true; })()').catch(() => false))) {
+ stop(); server.close(); return fail('this package cannot hand over its clock', 2);
+ }
+
+ const where = async () => (await exec(`window.__estellaCooked.probe(${JSON.stringify(['Player'])})`)).at.Player;
+ const read = async () => ({
+ streaming: await exec('window.__estellaCooked.streaming()'),
+ at: (await exec(`window.__estellaCooked.probe(${JSON.stringify(NAMES)})`)).at,
+ combat: await exec(`window.__estellaCooked.combat("Player", ${JSON.stringify(['Enemy', 'Canary', 'Player'])})`),
+ ai: await exec('window.__estellaCooked.ai("Enemy")'),
+ });
+
+ // Which key walks which way, measured — movement is camera-relative. LAZILY,
+ // because walking to find out moves the character, and a script that opens by
+ // reading what boot produced would read a world calibration already changed.
+ let basis = null;
+ const calibrate = async () => {
+ if (basis !== null) return true;
+ basis = {};
+ for (const key of ['KeyW', 'KeyD']) {
+ const before = await where();
+ await exec(holdScript([key], 20));
+ const after = await where();
+ basis[key] = { x: after.x - before.x, z: after.z - before.z };
+ await exec(holdScript([key === 'KeyW' ? 'KeyS' : 'KeyA'], 20));
+ }
+ if (Math.hypot(basis.KeyW.x, basis.KeyW.z) < 1) return false;
+ console.log(` calibrated: KeyW → (${basis.KeyW.x.toFixed(0)}, ${basis.KeyW.z.toFixed(0)}), `
+ + `KeyD → (${basis.KeyD.x.toFixed(0)}, ${basis.KeyD.z.toFixed(0)})`);
+ return true;
+ };
+
+ /** The keys that move toward (x, z), from the measured basis. */
+ const keysToward = (from, to, deadband) => {
+ const dx = to.x - from.x;
+ const dz = to.z - from.z;
+ const keys = [];
+ for (const [key, opposite] of [['KeyW', 'KeyS'], ['KeyD', 'KeyA']]) {
+ const v = basis[key];
+ const along = (dx * v.x + dz * v.z) / (Math.hypot(v.x, v.z) || 1);
+ if (Math.abs(along) > deadband) keys.push(along > 0 ? key : opposite);
+ }
+ return keys;
+ };
+
+ for (const step of steps) {
+ if (step.do === 'read') {
+ console.log(`reading ${step.as}: ${JSON.stringify(await read())}`);
+ continue;
+ }
+ if (step.do === 'step') { await exec(holdScript([], step.frames ?? 30)); continue; }
+ if (step.do === 'tap') { await exec(tapScript(step.key, step.frames ?? 10)); continue; }
+ if (step.do === 'hold') { await exec(holdScript(step.keys ?? [], step.frames ?? 30)); continue; }
+ if (step.do === 'walkTo') {
+ if (!(await calibrate())) { stop(); server.close(); return fail('holding a key moved the character nowhere', 1); }
+ const goal = { x: step.x, z: step.z };
+ const deadband = step.deadband ?? 30;
+ let spent = 0;
+ let last = await where();
+ let stuck = 0;
+ while (spent < (step.budget ?? BUDGET)) {
+ const keys = keysToward(last, goal, deadband);
+ if (keys.length === 0) break;
+ await exec(holdScript(keys, 10));
+ spent += 10;
+ const now = await where();
+ // A leg that stops moving has arrived at something else — a wall, or a
+ // floor that is no longer there. Reporting it is the point of some legs.
+ if (Math.hypot(now.x - last.x, now.z - last.z) < 1) stuck += 1; else stuck = 0;
+ last = now;
+ if (stuck >= (step.patience ?? 3)) break;
+ }
+ console.log(` walked to (${last.x.toFixed(0)}, ${last.z.toFixed(0)}) in ${spent} frames`
+ + (stuck >= (step.patience ?? 3) ? ' — stopped early' : ''));
+ continue;
+ }
+ stop(); server.close();
+ return fail(`unknown step "${step.do}"`, 2);
+ }
+
+ if (errors.length > 0) console.log(` ${errors.length} console error(s): ${errors[0]}`);
+ console.log('ok');
+ stop();
+ server.close();
+ app.exit(0);
+}
+
+app.whenReady().then(main).catch((err) => fail(String(err), 2));