Skip to content

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

fix(runtime): a packaged game's scene unload released no assets at all

esenginee9c88e8954e2
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index ee8549c7f..99827d007 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -6196,6 +6196,7 @@ name: string
registerDrawCallback: (id: string, fn: DrawCallback) => void
setPersistent: (entity: Entity, persistent: boolean) => void
spawn: () => Entity
+trackAssets: (byType: ReadonlyMap<string, ReadonlySet<string>>) => void
unbindPostProcess: (camera: Entity) => void
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index b3077bbd0..bd37d6dd9 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -6366,6 +6366,7 @@ name: string
registerDrawCallback: (id: string, fn: DrawCallback) => void
setPersistent: (entity: Entity, persistent: boolean) => void
spawn: () => Entity
+trackAssets: (byType: ReadonlyMap<string, ReadonlySet<string>>) => void
unbindPostProcess: (camera: Entity) => void
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 6e3c42969..230f877b3 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -6191,6 +6191,7 @@ name: string
registerDrawCallback: (id: string, fn: DrawCallback) => void
setPersistent: (entity: Entity, persistent: boolean) => void
spawn: () => Entity
+trackAssets: (byType: ReadonlyMap<string, ReadonlySet<string>>) => void
unbindPostProcess: (camera: Entity) => void
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 3066c93f7..144259ce1 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -6436,6 +6436,7 @@ name: string
registerDrawCallback: (id: string, fn: DrawCallback) => void
setPersistent: (entity: Entity, persistent: boolean) => void
spawn: () => Entity
+trackAssets: (byType: ReadonlyMap<string, ReadonlySet<string>>) => void
unbindPostProcess: (camera: Entity) => void
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 7024457bd..095eb2dd2 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -6198,6 +6198,7 @@ name: string
registerDrawCallback: (id: string, fn: DrawCallback) => void
setPersistent: (entity: Entity, persistent: boolean) => void
spawn: () => Entity
+trackAssets: (byType: ReadonlyMap<string, ReadonlySet<string>>) => void
unbindPostProcess: (camera: Entity) => void
```
diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.ts
index bb8b55708..b71e0a33f 100644
--- a/sdk/src/runtime/runtimeLoader.ts
+++ b/sdk/src/runtime/runtimeLoader.ts
@@ -437,6 +437,10 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis
if (ctx) ctx.adopt(entity);
else app.world.insert(entity, SceneOwner, { scene: sceneName, persistent: false });
}
+ // And the assets, for the same reason: a packaged scene carries no
+ // `data`, so the manager's preload never ran and these references are
+ // ones only this function knows about.
+ ctx?.trackAssets(discovered.byType);
}
}
diff --git a/sdk/src/scene/sceneManager.ts b/sdk/src/scene/sceneManager.ts
index 47b03cea9..dde6ae34d 100644
--- a/sdk/src/scene/sceneManager.ts
+++ b/sdk/src/scene/sceneManager.ts
@@ -44,6 +44,13 @@ export interface SceneContext {
spawn(): Entity;
/** Track an externally-spawned entity as scene-owned (despawned on unload). */
adopt(entity: Entity): void;
+ /**
+ * Track assets a loader acquired for this scene, so unload gives them back.
+ *
+ * The asset half of {@link adopt}: a scene whose data arrives inside `setup`
+ * preloads its own, and a reference nothing records is one nothing releases.
+ */
+ trackAssets(byType: ReadonlyMap<string, ReadonlySet<string>>): void;
despawn(entity: Entity): void;
registerDrawCallback(id: string, fn: DrawCallback): void;
bindPostProcess(camera: Entity, stack: PostProcessStack): void;
@@ -123,6 +130,17 @@ class SceneContextImpl implements SceneContext {
});
}
+ trackAssets(byType: ReadonlyMap<string, ReadonlySet<string>>): void {
+ for (const [type, paths] of byType) {
+ // Materials are handle-keyed and skeletons belong to the
+ // SpineManager; both are released through their own doors.
+ if (type === 'material' || type === 'spine') continue;
+ let bucket = this.instance_.loadedByType.get(type);
+ if (!bucket) { bucket = new Set(); this.instance_.loadedByType.set(type, bucket); }
+ for (const path of paths) bucket.add(path);
+ }
+ }
+
despawn(entity: Entity): void {
this.instance_.entities.delete(entity);
this.app_.world.despawn(entity);
diff --git a/sdk/tests/scene-asset-release.test.ts b/sdk/tests/scene-asset-release.test.ts
index 77d8b95cc..4fc5c6a24 100644
--- a/sdk/tests/scene-asset-release.test.ts
+++ b/sdk/tests/scene-asset-release.test.ts
@@ -112,6 +112,37 @@ describe('Scene unload releases all tracked asset categories', () => {
}
});
+ it('releases assets a scene tracked from inside setup (the packaged-game shape)', async () => {
+ // A packaged game's config carries no `data`: the bytes arrive inside
+ // setup(), which preloads its own. Unless that loader REPORTS what it
+ // acquired, unload releases nothing at all.
+ const releasedTextures: string[] = [];
+ const releasedTyped: Array<[string, string]> = [];
+ const app = createMockApp({
+ releaseTexture: (r: string) => { releasedTextures.push(r); },
+ releaseTyped: (t: string, r: string) => { releasedTyped.push([t, r]); },
+ });
+ const manager = new SceneManagerState(app as never);
+
+ manager.register({
+ name: 'packaged',
+ // No `data` — exactly what createRuntimeSceneConfig produces.
+ setup: (ctx) => {
+ ctx.trackAssets(new Map([
+ ['texture', new Set(['tex/hero.png'])],
+ ['audio', new Set(['sfx/hit.wav'])],
+ ['tileset', new Set(['maps/tiles.estileset'])],
+ ]));
+ },
+ });
+ await manager.load('packaged');
+ await manager.unload('packaged');
+
+ expect(releasedTextures, 'a packaged scene released no textures').toContain('tex/hero.png');
+ expect(releasedTyped).toContainEqual(['audio', 'sfx/hit.wav']);
+ expect(releasedTyped).toContainEqual(['tileset', 'maps/tiles.estileset']);
+ });
+
it('releases every type the scene acquired, whatever its type', async () => {
const releasedTextures: string[] = [];
const releasedTyped: Array<[string, string]> = [];