A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(scene): a load that did not commit leaves nothing of itself behind
esengine47d6bfe10301
diff --git a/sdk/src/scene/scene.ts b/sdk/src/scene/scene.tsindex 22b0d2e81..b883324d5 100644--- a/sdk/src/scene/scene.ts+++ b/sdk/src/scene/scene.ts@@ -538,10 +538,10 @@ export async function loadSceneWithAssets(assets.resolveSceneAssetPaths(data, result);applyTextureMetadata(data, result.textureHandles);if (options.collectAssets) {- // The receipts, when the owner asked for them. Materials keep their- // handle set too — callers read it to know what a scene is wearing —- // but the RELEASE rides the scope.- for (const lease of result.scope.leases()) options.collectAssets.scope?.add(lease);+ // The receipts MOVE to the owner (absorb, not add): two scopes each+ // holding every receipt leaves "which one releases it" unanswered.+ // Materials keep their handle set too, but the RELEASE rides the scope.+ options.collectAssets.scope?.absorb(result.scope);for (const handle of result.materialHandles.values()) {if (handle) options.collectAssets.materialHandles.add(handle);}diff --git a/sdk/src/scene/sceneManager.ts b/sdk/src/scene/sceneManager.tsindex 943be4a40..351fc9156 100644--- a/sdk/src/scene/sceneManager.ts+++ b/sdk/src/scene/sceneManager.ts@@ -456,49 +456,29 @@ export class SceneManagerState {}/**- * Roll back a load that threw partway. Without this, the half-registered- * instance stays in `scenes_` stuck at `status==='loading'` while its- * `loadPromise` is deleted in `finally` — so a retry hits the- * `status==='loading'` branch and returns the now-undefined loadPromise,- * wedging the scene so it can NEVER be loaded again. We also despawn any- * entities `setup`/`loadSceneData_` spawned before the throw, to avoid a leak.+ * Roll back a load that threw partway, through the teardown a successful+ * unload runs: a half-loaded scene owns what a loaded one owns.+ *+ * `keepPersistent: false` because persistence is a property of a COMMITTED+ * scene — a failed load cannot promote an entity into a global one.*/private rollbackFailedLoad_(name: string, instance: SceneInstance): void {- for (const entity of instance.entities) {- if (this.app_.world.valid(entity)) this.app_.world.despawn(entity);- }- instance.entities.clear();- // Only clear the registry slots if they still point at THIS instance — a- // concurrent unload+reload may already own them, and clobbering the newer- // load would corrupt it. (A cancelled load's unload already cleared them.)- if (this.scenes_.get(name) === instance) {- this.scenes_.delete(name);- this.contexts_.delete(name);- }+ this.disposeSceneOwnedState_(instance, false);+ this.removeSceneSlot_(name, instance);}- async unload(name: string, options?: TransitionOptions): Promise<void> {- const instance = this.scenes_.get(name);- if (!instance) return;-- const ctx = this.contexts_.get(name)!;- instance.status = 'unloading';-- if (instance.config.cleanup) {- try {- instance.config.cleanup(ctx);- } catch (err) {- // A throwing user cleanup must NOT abort the teardown below —- // that would leak every entity/system/texture the scene owns.- log.error('scene', `Scene "${name}" cleanup callback threw; continuing teardown`, err);- }- }-- const keepPersistent = options?.keepPersistent ?? true;+ /**+ * Give back everything this instance owns — the one teardown protocol.+ *+ * Idempotent by construction: every collection is emptied as it is walked.+ * An `unload` during a load tears the instance down, and that load's own+ * rollback then runs over it again — over whatever its setup added between.+ */+ private disposeSceneOwnedState_(instance: SceneInstance, keepPersistent: boolean): void {+ const world = this.app_.world;for (const entity of instance.entities) {- if (keepPersistent && this.app_.world.valid(entity) &&- this.app_.world.has(entity, SceneOwner)) {- const data = this.app_.world.get(entity, SceneOwner);+ if (keepPersistent && world.valid(entity) && world.has(entity, SceneOwner)) {+ const data = world.get(entity, SceneOwner);if (data.persistent) {// A persistent entity outlives its origin scene, so it is now// global. Clear the owning-scene tag — otherwise every@@ -508,16 +488,15 @@ export class SceneManagerState {// scene === '' is the existing "always active" rule.if (data.scene !== '') {data.scene = '';- this.app_.world.insert(entity, SceneOwner, data);+ world.insert(entity, SceneOwner, data);}continue;}}- if (this.app_.world.valid(entity)) {- this.app_.world.despawn(entity);- }+ if (world.valid(entity)) world.despawn(entity);}instance.entities.clear();+ instance.savedEnabled.clear();for (const id of instance.drawCallbacks.keys()) {unregisterDrawCallback(id);@@ -536,7 +515,17 @@ export class SceneManagerState {instance.postProcessBindings.clear();this.releaseSceneAssets_(instance);+ }+ /**+ * Forget the scene, if the slot is still this instance's.+ *+ * The identity check is the whole point: a concurrent unload + reload may+ * already have put a NEWER instance in the slot, and a rollback that+ * cleared it by name would delete the live scene out from under it.+ */+ private removeSceneSlot_(name: string, instance: SceneInstance): void {+ if (this.scenes_.get(name) !== instance) return;this.scenes_.delete(name);this.contexts_.delete(name);this.additiveScenes_.delete(name);@@ -544,13 +533,29 @@ export class SceneManagerState {this.sleepingScenes_.delete(name);const orderIdx = this.loadOrder_.indexOf(name);- if (orderIdx !== -1) {- this.loadOrder_.splice(orderIdx, 1);- }+ if (orderIdx !== -1) this.loadOrder_.splice(orderIdx, 1);+ if (this.activeScene_ === name) this.activeScene_ = null;+ }++ async unload(name: string, options?: TransitionOptions): Promise<void> {+ const instance = this.scenes_.get(name);+ if (!instance) return;- if (this.activeScene_ === name) {- this.activeScene_ = null;+ const ctx = this.contexts_.get(name)!;+ instance.status = 'unloading';++ if (instance.config.cleanup) {+ try {+ instance.config.cleanup(ctx);+ } catch (err) {+ // A throwing user cleanup must NOT abort the teardown below —+ // that would leak every entity/system/texture the scene owns.+ log.error('scene', `Scene "${name}" cleanup callback threw; continuing teardown`, err);+ }}++ this.disposeSceneOwnedState_(instance, options?.keepPersistent ?? true);+ this.removeSceneSlot_(name, instance);}/**diff --git a/sdk/tests/scene-load-transaction.test.ts b/sdk/tests/scene-load-transaction.test.tsnew file mode 100644index 000000000..636b82290--- /dev/null+++ b/sdk/tests/scene-load-transaction.test.ts@@ -0,0 +1,222 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file scene-load-transaction.test.ts+ * @brief A scene load that did not commit leaves nothing of itself behind.+ *+ * @details A load that did not commit owns the same kinds of thing a loaded+ * scene owns: its preload's receipts, the systems added before+ * `setup`, whatever `setup` registered before it threw. All of them+ * go back, or a retry succeeds on top of a ghost.+ *+ * Nothing here mocks the acquisition pipeline, the draw-callback+ * registry or the system schedule: what is under test is exactly the+ * wiring a mock would replace.+ */+import { describe, it, expect, vi, beforeEach } from 'vitest';+import { App } from '../src/app/app';+import { Schedule, defineSystem } from '../src/ecs/system';+import { SceneManager, SceneManagerState } from '../src/scene/sceneManager';+import { Assets as AssetsResource } from '../src/asset/AssetPlugin';+import { Assets } from '../src/asset/Assets';+import { AssetScope } from '../src/asset/AssetLease';+import { PostProcess } from '../src/postprocess';+import { getDrawCallbacks, clearDrawCallbacks } from '../src/render/customDraw';+import type { Backend } from '../src/asset/Backend';+import type { Entity } from '../src/types';++vi.mock('../src/wasm/resourceManager', () => ({+ requireResourceManager: () => ({ releaseTexture: vi.fn(), invalidateTexturePath: vi.fn(() => false) }),+ getResourceManager: () => null,+ evictTextureDimensions: vi.fn(),+}));++/** Every generation of the asset is a distinguishable object, so a double+ * release is visible as a repeated entry rather than as a silent no-op. */+function makeAssets(unloaded: string[]): Assets {+ let n = 0;+ const assets = Assets.create({+ backend: {+ fetchBinary: vi.fn(async () => new ArrayBuffer(8)),+ fetchText: vi.fn(async () => '{}'),+ resolveUrl: (p: string) => `http://test/${p}`,+ } as unknown as Backend,+ module: { _malloc: vi.fn(() => 0), _free: vi.fn(), HEAPU8: new Uint8Array(16), GL: null, FS: null } as never,+ });+ assets.register<{ id: string }>({+ type: 'font',+ load: async () => ({ id: `gen${++n}` }),+ unload: (v: { id: string }) => { unloaded.push(v.id); },+ } as never);+ return assets;+}++/** The post-process surface a scene binds against, modelled: bind/unbind/getStack+ * over a table, so "the binding is gone" is something the test can read. */+function postProcessFake() {+ const bound = new Map<Entity, unknown>();+ return {+ bind: (camera: Entity, stack: unknown) => { bound.set(camera, stack); },+ unbind: (camera: Entity) => { bound.delete(camera); },+ getStack: (camera: Entity) => bound.get(camera) ?? null,+ size: () => bound.size,+ };+}++function harness() {+ const unloaded: string[] = [];+ const app = App.new();+ const assets = makeAssets(unloaded);+ const manager = new SceneManagerState(app);+ const pp = postProcessFake();+ app.insertResource(AssetsResource, assets as never);+ app.insertResource(SceneManager, manager);+ app.insertResource(PostProcess, pp as never);+ return { app, assets, manager, pp, unloaded };+}++const CAMERA = 7 as Entity;++describe('a scene load that fails leaves nothing of itself behind', () => {+ beforeEach(() => { clearDrawCallbacks(); });++ it('gives back every kind of thing the scene owned, and a retry is clean', async () => {+ const { app, assets, manager, pp, unloaded } = harness();+ const base = assets.sizes().refRows;+ let ticks = 0;+ let spawned = 0 as Entity;++ const counting = defineSystem([], () => { ticks++; }, { name: 'LevelSystem' });+ const touchEverything = async (ctx: import('../src/scene/sceneManager').SceneContext): Promise<void> => {+ spawned = ctx.spawn();+ const scope = new AssetScope();+ scope.add(await assets.acquireTyped('font', 'hero.ttf'));+ ctx.trackAssetScope(scope);+ ctx.registerDrawCallback('ghost', () => {});+ ctx.bindPostProcess(CAMERA, { setAllPassesEnabled: vi.fn() } as never);+ };++ manager.register({+ name: 'level',+ systems: [{ schedule: Schedule.Update, system: counting }],+ setup: async (ctx) => { await touchEverything(ctx); throw new Error('boom'); },+ });++ await expect(manager.load('level')).rejects.toThrow('boom');++ expect(manager.getScene('level')).toBeNull();+ expect(manager.getLoaded()).toEqual([]);+ expect(app.world.valid(spawned), 'the entity it spawned').toBe(false);+ expect(assets.sizes().refRows, 'the receipts it acquired').toBe(base);+ expect(unloaded).toEqual(['gen1']);+ expect(getDrawCallbacks().has('ghost'), 'the draw callback it registered').toBe(false);+ expect(pp.getStack(CAMERA), 'the post-process it bound').toBeNull();++ // The system needs a SUCCEEDING load to show: a scene-scoped system is+ // gated on its scene running, so after a failure "removed" and "merely+ // idle" look the same.+ manager.register({+ name: 'level',+ systems: [{ schedule: Schedule.Update, system: counting }],+ setup: () => {},+ });+ await manager.load('level');+ await app.tick(1 / 60);+ expect(ticks, 'the failed load\'s system is still registered too').toBe(1);+ });++ it('rolls back a setup that failed after an await, not only a synchronous one', async () => {+ // Where real failures live: a scene awaits the network, a DLC, a plugin,+ // and throws long after its assets were acquired.+ const { app, assets, manager, pp, unloaded } = harness();+ const base = assets.sizes().refRows;+ let spawned = 0 as Entity;+ let release = (): void => {};+ const gate = new Promise<void>((r) => { release = r; });++ manager.register({+ name: 'level',+ setup: async (ctx) => {+ spawned = ctx.spawn();+ const scope = new AssetScope();+ scope.add(await assets.acquireTyped('font', 'hero.ttf'));+ ctx.trackAssetScope(scope);+ ctx.registerDrawCallback('ghost', () => {});+ ctx.bindPostProcess(CAMERA, { setAllPassesEnabled: vi.fn() } as never);+ await gate;+ throw new Error('boom, later');+ },+ });++ const loading = manager.load('level');+ const rejected = expect(loading).rejects.toThrow('boom, later');+ release();+ await rejected;++ expect(app.world.valid(spawned)).toBe(false);+ expect(assets.sizes().refRows).toBe(base);+ expect(unloaded).toEqual(['gen1']);+ expect(getDrawCallbacks().has('ghost')).toBe(false);+ expect(pp.getStack(CAMERA)).toBeNull();+ expect(manager.getScene('level')).toBeNull();+ });++ it('an unload during the load, then the load\'s own rollback, frees each thing once', async () => {+ // The teardown runs twice over one instance — and the second time it has+ // to cope with what the first one could not have seen: the in-flight+ // setup went on acquiring after the unload had already let go.+ const { app, assets, manager, pp, unloaded } = harness();+ const base = assets.sizes().refRows;+ let release = (): void => {};+ const gate = new Promise<void>((r) => { release = r; });+ let spawned = 0 as Entity;++ manager.register({+ name: 'level',+ setup: async (ctx) => {+ await gate;+ // Everything here lands AFTER the unload has torn the instance down.+ spawned = ctx.spawn();+ const scope = new AssetScope();+ scope.add(await assets.acquireTyped('font', 'hero.ttf'));+ ctx.trackAssetScope(scope);+ ctx.registerDrawCallback('ghost', () => {});+ ctx.bindPostProcess(CAMERA, { setAllPassesEnabled: vi.fn() } as never);+ },+ });++ const loading = manager.load('level');+ await Promise.resolve();+ await manager.unload('level'); // the first teardown+ const rejected = expect(loading).rejects.toThrow(/cancelled/i);+ release();+ await rejected; // the load resumes, is cancelled, rolls back++ expect(app.world.valid(spawned), 'the entity the cancelled load spawned').toBe(false);+ expect(assets.sizes().refRows, 'what it acquired after the unload').toBe(base);+ expect(unloaded, 'freed once, not twice').toEqual(['gen1']);+ expect(getDrawCallbacks().has('ghost')).toBe(false);+ expect(pp.size()).toBe(0);+ expect(manager.getScene('level')).toBeNull();+ });++ it('a failed load cannot promote an entity to global ownership', async () => {+ // Persistence is a property of a COMMITTED scene. An entity marked+ // persistent inside a setup that then threw was never part of a scene+ // anyone kept, and must not escape the transaction as a global one.+ const { app, manager } = harness();+ let spawned = 0 as Entity;++ manager.register({+ name: 'level',+ setup: (ctx) => {+ spawned = ctx.spawn();+ ctx.setPersistent(spawned, true);+ throw new Error('boom');+ },+ });++ await expect(manager.load('level')).rejects.toThrow('boom');+ expect(app.world.valid(spawned), 'a persistent entity escaped a failed load').toBe(false);+ });+});diff --git a/tools/check-scene-teardown.mjs b/tools/check-scene-teardown.mjsnew file mode 100644index 000000000..142924795--- /dev/null+++ b/tools/check-scene-teardown.mjs@@ -0,0 +1,127 @@+#!/usr/bin/env node+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file check-scene-teardown.mjs — one teardown protocol, and it covers the instance.+ *+ * A scene that unloads and a load that failed halfway own the same kinds of+ * thing. They had two implementations of giving them back, and the second one+ * was missing four steps: a failed load released no assets, removed no systems,+ * unregistered no draw callbacks and unbound no post-process.+ *+ * 1. `unload` and `rollbackFailedLoad_` perform no teardown of their own —+ * both go through disposeSceneOwnedState_.+ * 2. The protocol still performs all of them. Emptying a collection is not+ * giving its contents back: dropping the `removeSystem` loop while keeping+ * `systemIds.length = 0` leaves the systems running and looks tidy.+ * 3. Every piece of state a SceneInstance owns is named in that teardown.+ * This is the one that catches the NEXT field: a collection added to the+ * instance and forgotten in the protocol is invisible until it leaks.+ *+ * Run: node tools/check-scene-teardown.mjs (exit 1 on violation)+ */+import { readFileSync, existsSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const FILE = 'sdk/src/scene/sceneManager.ts';++if (!existsSync(path.join(ROOT, FILE))) {+ console.error(`check-scene-teardown is stale: ${FILE} does not exist.`);+ process.exit(1);+}++/** Comments out, line numbers intact. */+const stripComments = (text) =>+ text+ .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))+ .replace(/\/\/[^\n]*/g, '');++const src = stripComments(readFileSync(path.join(ROOT, FILE), 'utf8'));++/**+ * One method body, braces balanced. Anchored at the member declaration: matching+ * the bare name found `this.unload(` — a call site that appears before the+ * definition — and read a body that was not the method's at all.+ */+function methodBody(name) {+ const m = new RegExp(`\\n {4}(?:private |protected |public )?(?:async )?${name}\\s*\\(`).exec(src);+ if (!m) return null;+ let i = src.indexOf('{', m.index + m[0].length - 1);+ const start = i;+ for (let depth = 0; i < src.length; i++) {+ if (src[i] === '{') depth++;+ else if (src[i] === '}' && --depth === 0) break;+ }+ return { text: src.slice(start + 1, i), line: src.slice(0, m.index).split('\n').length + 1 };+}++const findings = [];++const dispose = methodBody('disposeSceneOwnedState_');+const releaseAssets = methodBody('releaseSceneAssets_');+if (!dispose || !releaseAssets) {+ console.error(`${FILE} disposeSceneOwnedState_ / releaseSceneAssets_ is gone — the scene teardown protocol has no single implementation to hold.`);+ process.exit(1);+}+// The protocol is the two together: dispose runs releaseSceneAssets_.+const protocol = dispose.text + releaseAssets.text;++// --- 1. neither door tears down on its own ---------------------------------+const TEARDOWN_OPS = [+ /\bworld\.despawn\s*\(/,+ /\bunregisterDrawCallback\s*\(/,+ /\bremoveSystem\s*\(/,+ /\bunbind\s*\(/,+ /\breleaseAll\s*\(/,+ /\breleaseAssets\s*\(/,+];+for (const name of ['unload', 'rollbackFailedLoad_']) {+ const body = methodBody(name);+ if (!body) {+ findings.push(`${FILE} ${name}() is gone — this guard is reading the wrong file.`);+ continue;+ }+ for (const op of TEARDOWN_OPS) {+ if (!op.test(body.text)) continue;+ findings.push(`${FILE}:${body.line} ${name}() tears down on its own (${op.source}) instead of through disposeSceneOwnedState_ — that is how the two copies came to disagree.`);+ break;+ }+}++// --- 2. and the protocol still performs every one of them ------------------+for (const op of TEARDOWN_OPS) {+ if (op.test(protocol)) continue;+ findings.push(`${FILE}:${dispose.line} the teardown protocol no longer does ${op.source} — emptying the collection that held them is not giving them back.`);+}++// --- 3. every piece of instance state is in the protocol -------------------+const cls = /class SceneInstance \{([\s\S]*?)\n\}/.exec(src);+if (!cls) {+ console.error(`${FILE} cannot read SceneInstance — this guard parses its fields.`);+ process.exit(1);+}+/** State whose lifetime is NOT the instance's to end, with the reason. */+const NOT_OWNED = new Map([+ ['config', 'the registration this instance was made from; it outlives the instance'],+ ['status', 'a flag on the instance itself, not something held on its behalf'],+]);+const fields = [...cls[1].matchAll(/^\s+(?:readonly )?([A-Za-z0-9_]+)(?:\s*[:=])/gm)].map((m) => m[1]);+const owned = fields.filter((f) => !NOT_OWNED.has(f));+if (owned.length < 5) {+ console.error(`check-scene-teardown: found only ${owned.length} owned field(s) on SceneInstance — the parser no longer matches how they are declared.`);+ process.exit(1);+}+for (const field of owned) {+ if (new RegExp(`\\b${field}\\b`).test(protocol)) continue;+ findings.push(`${FILE} SceneInstance.${field} is never given back: the teardown protocol does not touch it, so a failed or unloaded scene leaves it live.`);+}++if (findings.length === 0) {+ console.log(`check-scene-teardown: one protocol, covering all ${owned.length} pieces of scene-owned state.`);+ process.exit(0);+}+for (const f of findings) console.error(f);+console.error('\nA scene that did not commit leaves nothing behind. Extend disposeSceneOwnedState_ rather than the caller.');+process.exit(1);diff --git a/tools/gates.mjs b/tools/gates.mjsindex 4116da8f2..a5252dff0 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -111,6 +111,9 @@ export const GATES = [// A field declares that it carries an asset in one place; everything that acts// on live assets has to read THAT rather than keep a list of components beside it.{ id: 'live-asset-rebind', run: 'node tools/check-live-asset-rebind.mjs' },+ // A scene that unloads and a load that failed halfway own the same things;+ // two implementations of giving them back is how one came to miss four steps.+ { id: 'scene-teardown', run: 'node tools/check-scene-teardown.mjs' },// …and that each of them can be reached on a device, where the registry is// assembled from ptr accessors rather than from embind.{ id: 'native-components', run: 'node tools/check-native-components.mjs' },