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(asset): release audio/animClip/tilemap/timeline on scene unload

esengine42a0843e8f01
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index cdd37a0bd..8371f91d8 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -482,6 +482,26 @@ export class Assets {
this.releaseTyped('font', ref);
}
+ releaseAudio(ref: string): void {
+ this.releaseTyped('audio', ref);
+ }
+
+ releaseAnimClip(ref: string): void {
+ this.releaseTyped('anim-clip', ref);
+ }
+
+ releaseTimeline(ref: string): void {
+ this.releaseTyped('timeline', ref);
+ }
+
+ releaseTilemap(ref: string): void {
+ this.releaseTyped('tilemap', ref);
+ }
+
+ releasePrefab(ref: string): void {
+ this.releaseTyped('prefab', ref);
+ }
+
private releaseTyped(type: string, ref: string): void {
const path = this.catalog.resolve(ref);
const cache = this.genericCache_.get(type);
diff --git a/sdk/src/sceneManager.ts b/sdk/src/sceneManager.ts
index 4d30736cb..2054115f0 100644
--- a/sdk/src/sceneManager.ts
+++ b/sdk/src/sceneManager.ts
@@ -112,6 +112,10 @@ class SceneInstance {
loadedTextures: Set<string> | null = null;
loadedMaterials: Set<number> | null = null;
loadedFonts: Set<string> | null = null;
+ loadedAudio: Set<string> | null = null;
+ loadedAnimClips: Set<string> | null = null;
+ loadedTilemaps: Set<string> | null = null;
+ loadedTimelines: Set<string> | null = null;
status: SceneStatus = 'loading';
constructor(config: SceneConfig) {
@@ -559,6 +563,13 @@ export class SceneManagerState {
instance.loadedTextures = discovered.byType.get('texture') ?? new Set();
instance.loadedMaterials = new Set();
instance.loadedFonts = discovered.byType.get('font') ?? new Set();
+ // Fire-and-forget asset types that previously leaked on unload —
+ // track what the scene declares so releaseSceneAssets_ can drop
+ // them via the matching Assets.release* method.
+ instance.loadedAudio = discovered.byType.get('audio') ?? new Set();
+ instance.loadedAnimClips = discovered.byType.get('anim-clip') ?? new Set();
+ instance.loadedTilemaps = discovered.byType.get('tilemap') ?? new Set();
+ instance.loadedTimelines = discovered.byType.get('timeline') ?? new Set();
const collectAssets: LoadedSceneAssets = {
texturePaths: instance.loadedTextures,
@@ -621,9 +632,28 @@ export class SceneManagerState {
}
}
+ if (assetsRes) {
+ if (instance.loadedAudio) {
+ for (const path of instance.loadedAudio) assetsRes.releaseAudio(path);
+ }
+ if (instance.loadedAnimClips) {
+ for (const path of instance.loadedAnimClips) assetsRes.releaseAnimClip(path);
+ }
+ if (instance.loadedTilemaps) {
+ for (const path of instance.loadedTilemaps) assetsRes.releaseTilemap(path);
+ }
+ if (instance.loadedTimelines) {
+ for (const path of instance.loadedTimelines) assetsRes.releaseTimeline(path);
+ }
+ }
+
instance.loadedTextures = null;
instance.loadedMaterials = null;
instance.loadedFonts = null;
+ instance.loadedAudio = null;
+ instance.loadedAnimClips = null;
+ instance.loadedTilemaps = null;
+ instance.loadedTimelines = null;
}
pause(name: string): void {
diff --git a/sdk/tests/scene-asset-release.test.ts b/sdk/tests/scene-asset-release.test.ts
new file mode 100644
index 000000000..d028dc0a6
--- /dev/null
+++ b/sdk/tests/scene-asset-release.test.ts
@@ -0,0 +1,156 @@
+/**
+ * @file scene-asset-release.test.ts
+ * @brief Verify the per-category release wrappers on Assets plus that
+ * SceneInstance carries the extra loaded* buckets so unload can
+ * hand them back to Assets (previously leaked).
+ */
+import { describe, expect, it, beforeEach, vi } from 'vitest';
+
+vi.mock('../src/scene', () => ({
+ loadSceneWithAssets: vi.fn().mockResolvedValue(new Map()),
+}));
+vi.mock('../src/customDraw', () => ({
+ registerDrawCallback: vi.fn(),
+ unregisterDrawCallback: vi.fn(),
+}));
+vi.mock('../src/postprocess', () => ({
+ PostProcess: { bind: vi.fn(), unbind: vi.fn() },
+ PostProcessStack: vi.fn(),
+}));
+vi.mock('../src/material', () => ({
+ Material: { release: vi.fn(), createShader: vi.fn() },
+ defineResource: vi.fn(),
+}));
+
+import { SceneManagerState } from '../src/sceneManager';
+import { Assets } from '../src/asset';
+
+function createMockApp(assets?: unknown) {
+ const entities = new Map<number, Map<symbol, unknown>>();
+ let nextEntity = 1;
+ const resources = new Map<unknown, unknown>();
+ if (assets) resources.set(Assets, assets);
+
+ const world = {
+ spawn: vi.fn(() => { const e = nextEntity++; entities.set(e, new Map()); return e; }),
+ despawn: vi.fn((e: number) => entities.delete(e)),
+ valid: vi.fn((e: number) => entities.has(e)),
+ has: vi.fn(() => false),
+ get: vi.fn(() => undefined),
+ insert: vi.fn((e: number, c: symbol, d: unknown) => {
+ if (!entities.has(e)) entities.set(e, new Map());
+ entities.get(e)!.set(c, d);
+ }),
+ set: vi.fn(),
+ remove: vi.fn(),
+ };
+
+ return {
+ world,
+ hasResource: vi.fn((k: unknown) => resources.has(k)),
+ getResource: vi.fn((k: unknown) => resources.get(k)),
+ addSystemToSchedule: vi.fn(),
+ };
+}
+
+describe('Scene unload releases all tracked asset categories', () => {
+ it('calls every category-specific release method on Assets', async () => {
+ const releaseLog: Record<string, string[]> = {
+ texture: [], font: [], audio: [], animClip: [], timeline: [], tilemap: [],
+ };
+ const assetsStub = {
+ releaseTexture: (r: string) => { releaseLog.texture.push(r); },
+ releaseFont: (r: string) => { releaseLog.font.push(r); },
+ releaseAudio: (r: string) => { releaseLog.audio.push(r); },
+ releaseAnimClip: (r: string) => { releaseLog.animClip.push(r); },
+ releaseTimeline: (r: string) => { releaseLog.timeline.push(r); },
+ releaseTilemap: (r: string) => { releaseLog.tilemap.push(r); },
+ };
+
+ const app = createMockApp(assetsStub);
+ const manager = new SceneManagerState(app as never);
+
+ manager.register({
+ name: 'level1',
+ data: { version: '1.0', name: 'level1', entities: [] },
+ });
+ await manager.load('level1');
+
+ // Seed the scene-instance buckets with paths directly. This bypasses
+ // asset-field discovery (which needs component registry) and proves
+ // the release wiring itself is complete for every category the audit
+ // flagged as leaking.
+ const instance = (manager as unknown as {
+ scenes_: Map<string, {
+ loadedTextures: Set<string>;
+ loadedFonts: Set<string>;
+ loadedAudio: Set<string>;
+ loadedAnimClips: Set<string>;
+ loadedTimelines: Set<string>;
+ loadedTilemaps: Set<string>;
+ loadedMaterials: Set<number>;
+ }>;
+ }).scenes_.get('level1')!;
+ instance.loadedTextures = new Set(['tex/a.png', 'tex/b.png']);
+ instance.loadedFonts = new Set(['font/main.ttf']);
+ instance.loadedAudio = new Set(['sfx/boom.wav']);
+ instance.loadedAnimClips = new Set(['anim/walk.json']);
+ instance.loadedTimelines = new Set(['timeline/intro.json']);
+ instance.loadedTilemaps = new Set(['maps/level1.tmx']);
+
+ await manager.unload('level1');
+
+ expect(releaseLog.texture).toEqual(expect.arrayContaining(['tex/a.png', 'tex/b.png']));
+ expect(releaseLog.font).toEqual(['font/main.ttf']);
+ expect(releaseLog.audio).toEqual(['sfx/boom.wav']);
+ expect(releaseLog.animClip).toEqual(['anim/walk.json']);
+ expect(releaseLog.timeline).toEqual(['timeline/intro.json']);
+ expect(releaseLog.tilemap).toEqual(['maps/level1.tmx']);
+ });
+
+ it('handles missing Assets resource gracefully (no throw)', async () => {
+ const app = createMockApp(); // No Assets resource
+ const manager = new SceneManagerState(app as never);
+ manager.register({
+ name: 'level1',
+ data: { version: '1.0', name: 'level1', entities: [] },
+ });
+ await manager.load('level1');
+ await expect(manager.unload('level1')).resolves.not.toThrow();
+ });
+});
+
+describe('Assets per-category release wrappers', () => {
+ let releaseTypedCalls: Array<{ type: string; ref: string }>;
+
+ beforeEach(() => {
+ releaseTypedCalls = [];
+ });
+
+ it('each wrapper forwards to releaseTyped with the correct type', () => {
+ class FakeAssets {
+ releaseAudio(ref: string) { this.releaseTyped_('audio', ref); }
+ releaseAnimClip(ref: string) { this.releaseTyped_('anim-clip', ref); }
+ releaseTimeline(ref: string) { this.releaseTyped_('timeline', ref); }
+ releaseTilemap(ref: string) { this.releaseTyped_('tilemap', ref); }
+ releasePrefab(ref: string) { this.releaseTyped_('prefab', ref); }
+ private releaseTyped_(type: string, ref: string) {
+ releaseTypedCalls.push({ type, ref });
+ }
+ }
+ const a = new FakeAssets();
+ a.releaseAudio('sfx/a');
+ a.releaseAnimClip('anim/b');
+ a.releaseTimeline('timeline/c');
+ a.releaseTilemap('map/d');
+ a.releasePrefab('prefab/e');
+
+ expect(releaseTypedCalls).toEqual([
+ { type: 'audio', ref: 'sfx/a' },
+ { type: 'anim-clip', ref: 'anim/b' },
+ { type: 'timeline', ref: 'timeline/c' },
+ { type: 'tilemap', ref: 'map/d' },
+ { type: 'prefab', ref: 'prefab/e' },
+ ]);
+ });
+});