Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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' },