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
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.esscenenew file mode 100644index 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.metanew file mode 100644index 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.esprojectnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.tsindex 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 agnosticconst { 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.tsindex 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.tsindex 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.mdindex 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 | undefinedsteamAppId: number | undefineduiTheme: "dark" | "light" | undefineduiThemeOverrides: ThemeOverrides | undefined+worlds: WorldManifest[] | undefined```## RuntimeOnly — const @public@@ -7262,6 +7263,7 @@ type: string```cleanup: ((ctx: SceneContext) => void) | undefineddata: SceneData | undefined+externalEntities: (() => ReadonlyMap<number, Entity>) | undefinedname: stringpath: string | undefinedsetup: ((ctx: SceneContext) => void | Promise<void>) | undefined@@ -7319,6 +7321,7 @@ abortOnMissingAssets: boolean | undefinedassetBaseUrl: string | undefinedassets: Assets | undefinedcollectAssets: LoadedSceneAssets | undefined+externalEntities: ReadonlyMap<number, number> | undefinedonMissingAssets: MissingAssetCallback | undefinedonProgress: SceneLoadProgressCallback | undefined```@@ -10093,7 +10096,9 @@ assetRefsByCell: Record<string, number>authoredCellEntityCounts: Record<string, number>cellCount: numbercellEntityCounts: Record<string, number>+cellHandles: Record<string, number[]>cellRenderCounts: Record<string, number>+cellStableIds: Record<string, number[]>desiredCells: string[]loadCount: numberloadingCells: string[]@@ -10109,14 +10114,14 @@ unloadingCells: string[]```isLoaded: (name: string) => booleanloadAdditive: (name: string) => Promise<unknown>-register: (config: { name: string; path: string; }) => void+register: (config: SceneConfig) => voidunload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>```## WorldStreamer — class @experimental```clear: () => void-loadManifest: (manifest: WorldManifest) => void+loadManifest: (manifest: WorldManifest, sceneConfig?: (cell: WorldCell) => SceneConfig) => voidmanifest: WorldManifest | nullresidencyOf: (name: string) => CellResidencystatus: () => WorldStreamerStatus@@ -12204,6 +12209,11 @@ ParticlePluginPerceptionPlugin```+## 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 @@ ServicesPluginMotionDriver<AnimatorClipMotion>```+## stableEntityId — function @experimental+```+(app: App, entity: Entity): number | undefined+```+## stackOf — function @experimental```(error: unknown): string | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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 | undefinedsteamAppId: number | undefineduiTheme: "dark" | "light" | undefineduiThemeOverrides: ThemeOverrides | undefined+worlds: WorldManifest[] | undefined```## RuntimeOnly — const @public@@ -7455,6 +7456,7 @@ type: string```cleanup: ((ctx: SceneContext) => void) | undefineddata: SceneData | undefined+externalEntities: (() => ReadonlyMap<number, Entity>) | undefinedname: stringpath: string | undefinedsetup: ((ctx: SceneContext) => void | Promise<void>) | undefined@@ -7512,6 +7514,7 @@ abortOnMissingAssets: boolean | undefinedassetBaseUrl: string | undefinedassets: Assets | undefinedcollectAssets: LoadedSceneAssets | undefined+externalEntities: ReadonlyMap<number, number> | undefinedonMissingAssets: MissingAssetCallback | undefinedonProgress: SceneLoadProgressCallback | undefined```@@ -10286,7 +10289,9 @@ assetRefsByCell: Record<string, number>authoredCellEntityCounts: Record<string, number>cellCount: numbercellEntityCounts: Record<string, number>+cellHandles: Record<string, number[]>cellRenderCounts: Record<string, number>+cellStableIds: Record<string, number[]>desiredCells: string[]loadCount: numberloadingCells: string[]@@ -10302,14 +10307,14 @@ unloadingCells: string[]```isLoaded: (name: string) => booleanloadAdditive: (name: string) => Promise<unknown>-register: (config: { name: string; path: string; }) => void+register: (config: SceneConfig) => voidunload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>```## WorldStreamer — class @experimental```clear: () => void-loadManifest: (manifest: WorldManifest) => void+loadManifest: (manifest: WorldManifest, sceneConfig?: (cell: WorldCell) => SceneConfig) => voidmanifest: WorldManifest | nullresidencyOf: (name: string) => CellResidencystatus: () => WorldStreamerStatus@@ -12447,6 +12452,11 @@ ParticlePluginPerceptionPlugin```+## 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 @@ ServicesPluginMotionDriver<AnimatorClipMotion>```+## stableEntityId — function @experimental+```+(app: App, entity: Entity): number | undefined+```+## stackOf — function @experimental```(error: unknown): string | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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 | undefinedsteamAppId: number | undefineduiTheme: "dark" | "light" | undefineduiThemeOverrides: ThemeOverrides | undefined+worlds: WorldManifest[] | undefined```## RuntimeOnly — const @public@@ -7257,6 +7258,7 @@ type: string```cleanup: ((ctx: SceneContext) => void) | undefineddata: SceneData | undefined+externalEntities: (() => ReadonlyMap<number, Entity>) | undefinedname: stringpath: string | undefinedsetup: ((ctx: SceneContext) => void | Promise<void>) | undefined@@ -7314,6 +7316,7 @@ abortOnMissingAssets: boolean | undefinedassetBaseUrl: string | undefinedassets: Assets | undefinedcollectAssets: LoadedSceneAssets | undefined+externalEntities: ReadonlyMap<number, number> | undefinedonMissingAssets: MissingAssetCallback | undefinedonProgress: SceneLoadProgressCallback | undefined```@@ -10088,7 +10091,9 @@ assetRefsByCell: Record<string, number>authoredCellEntityCounts: Record<string, number>cellCount: numbercellEntityCounts: Record<string, number>+cellHandles: Record<string, number[]>cellRenderCounts: Record<string, number>+cellStableIds: Record<string, number[]>desiredCells: string[]loadCount: numberloadingCells: string[]@@ -10104,14 +10109,14 @@ unloadingCells: string[]```isLoaded: (name: string) => booleanloadAdditive: (name: string) => Promise<unknown>-register: (config: { name: string; path: string; }) => void+register: (config: SceneConfig) => voidunload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>```## WorldStreamer — class @experimental```clear: () => void-loadManifest: (manifest: WorldManifest) => void+loadManifest: (manifest: WorldManifest, sceneConfig?: (cell: WorldCell) => SceneConfig) => voidmanifest: WorldManifest | nullresidencyOf: (name: string) => CellResidencystatus: () => WorldStreamerStatus@@ -12209,6 +12214,11 @@ ParticlePluginPerceptionPlugin```+## 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 @@ ServicesPluginMotionDriver<AnimatorClipMotion>```+## stableEntityId — function @experimental+```+(app: App, entity: Entity): number | undefined+```+## stackOf — function @experimental```(error: unknown): string | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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 | undefinedsteamAppId: number | undefineduiTheme: "dark" | "light" | undefineduiThemeOverrides: ThemeOverrides | undefined+worlds: WorldManifest[] | undefined```## RuntimeOnly — const @public@@ -7503,6 +7504,7 @@ type: string```cleanup: ((ctx: SceneContext) => void) | undefineddata: SceneData | undefined+externalEntities: (() => ReadonlyMap<number, Entity>) | undefinedname: stringpath: string | undefinedsetup: ((ctx: SceneContext) => void | Promise<void>) | undefined@@ -7560,6 +7562,7 @@ abortOnMissingAssets: boolean | undefinedassetBaseUrl: string | undefinedassets: Assets | undefinedcollectAssets: LoadedSceneAssets | undefined+externalEntities: ReadonlyMap<number, number> | undefinedonMissingAssets: MissingAssetCallback | undefinedonProgress: SceneLoadProgressCallback | undefined```@@ -10340,7 +10343,9 @@ assetRefsByCell: Record<string, number>authoredCellEntityCounts: Record<string, number>cellCount: numbercellEntityCounts: Record<string, number>+cellHandles: Record<string, number[]>cellRenderCounts: Record<string, number>+cellStableIds: Record<string, number[]>desiredCells: string[]loadCount: numberloadingCells: string[]@@ -10356,14 +10361,14 @@ unloadingCells: string[]```isLoaded: (name: string) => booleanloadAdditive: (name: string) => Promise<unknown>-register: (config: { name: string; path: string; }) => void+register: (config: SceneConfig) => voidunload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>```## WorldStreamer — class @experimental```clear: () => void-loadManifest: (manifest: WorldManifest) => void+loadManifest: (manifest: WorldManifest, sceneConfig?: (cell: WorldCell) => SceneConfig) => voidmanifest: WorldManifest | nullresidencyOf: (name: string) => CellResidencystatus: () => WorldStreamerStatus@@ -12466,6 +12471,11 @@ ParticlePluginPerceptionPlugin```+## 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 @@ ServicesPluginMotionDriver<AnimatorClipMotion>```+## stableEntityId — function @experimental+```+(app: App, entity: Entity): number | undefined+```+## stackOf — function @experimental```(error: unknown): string | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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 | undefinedsteamAppId: number | undefineduiTheme: "dark" | "light" | undefineduiThemeOverrides: ThemeOverrides | undefined+worlds: WorldManifest[] | undefined```## RuntimeOnly — const @public@@ -7264,6 +7265,7 @@ type: string```cleanup: ((ctx: SceneContext) => void) | undefineddata: SceneData | undefined+externalEntities: (() => ReadonlyMap<number, Entity>) | undefinedname: stringpath: string | undefinedsetup: ((ctx: SceneContext) => void | Promise<void>) | undefined@@ -7321,6 +7323,7 @@ abortOnMissingAssets: boolean | undefinedassetBaseUrl: string | undefinedassets: Assets | undefinedcollectAssets: LoadedSceneAssets | undefined+externalEntities: ReadonlyMap<number, number> | undefinedonMissingAssets: MissingAssetCallback | undefinedonProgress: SceneLoadProgressCallback | undefined```@@ -10116,7 +10119,9 @@ assetRefsByCell: Record<string, number>authoredCellEntityCounts: Record<string, number>cellCount: numbercellEntityCounts: Record<string, number>+cellHandles: Record<string, number[]>cellRenderCounts: Record<string, number>+cellStableIds: Record<string, number[]>desiredCells: string[]loadCount: numberloadingCells: string[]@@ -10132,14 +10137,14 @@ unloadingCells: string[]```isLoaded: (name: string) => booleanloadAdditive: (name: string) => Promise<unknown>-register: (config: { name: string; path: string; }) => void+register: (config: SceneConfig) => voidunload: (name: string, options?: { keepPersistent?: boolean; }) => Promise<void>```## WorldStreamer — class @experimental```clear: () => void-loadManifest: (manifest: WorldManifest) => void+loadManifest: (manifest: WorldManifest, sceneConfig?: (cell: WorldCell) => SceneConfig) => voidmanifest: WorldManifest | nullresidencyOf: (name: string) => CellResidencystatus: () => WorldStreamerStatus@@ -12232,6 +12237,11 @@ ParticlePluginPerceptionPlugin```+## 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 @@ ServicesPluginMotionDriver<AnimatorClipMotion>```+## stableEntityId — function @experimental+```+(app: App, entity: Entity): number | undefined+```+## stackOf — function @experimental```(error: unknown): string | undefineddiff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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/basisTranscimport 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.tsindex 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, Eif (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.tsindex 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.mjsnew file mode 100644index 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));