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(sdk): scene unload releases materials through Assets; reload restores a slept scene

esengine2faa4d47f1b8
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index 418eb5da2..b1beb502e 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -923,6 +923,19 @@ export class Assets {
this.releaseTyped('prefab', ref);
}
+ /**
+ * Release a material obtained via {@link loadMaterial}, addressed by its
+ * handle (materials are tracked by handle, not ref, in the scene manager).
+ * Routes through the shared refcount + cache path so a material shared by
+ * two scenes survives until its last owner releases it, and the cache never
+ * hands the next load a destroyed handle. Destroying the handle directly
+ * (bypassing this) would strand a dead handle in the material cache.
+ */
+ releaseMaterial(handle: number): void {
+ const path = this.pathForHandle('material', handle);
+ if (path !== null) this.releaseTyped('material', path);
+ }
+
private releaseTyped(type: string, ref: string): void {
const path = this.resolveLoadPath_(ref);
const cache = this.genericCache_.get(type);
diff --git a/sdk/src/sceneManager.ts b/sdk/src/sceneManager.ts
index 3a866242e..1f17cbe74 100644
--- a/sdk/src/sceneManager.ts
+++ b/sdk/src/sceneManager.ts
@@ -275,6 +275,12 @@ export class SceneManagerState {
if (existing.status === 'loading') {
return this.loadPromises_.get(name)!;
}
+ // Re-loading a scene that was slept/paused must run the full restore
+ // (remove Disabled, replay savedEnabled, re-enable post-process); a
+ // bare status flip would strand its entities disabled and leave
+ // wake()/resume() a permanent no-op.
+ if (existing.status === 'sleeping') this.wake(name);
+ else if (existing.status === 'paused') this.resume(name);
existing.status = 'running';
this.activeScene_ = name;
return this.contexts_.get(name)!;
@@ -533,7 +539,11 @@ export class SceneManagerState {
if (instance.loadedMaterials) {
for (const handle of instance.loadedMaterials) {
- Material.release(handle);
+ // Release through Assets so the material's refcount + path cache
+ // stay coherent; a bare Material.release strands the destroyed
+ // handle in the cache for the next scene that reuses the material.
+ if (assetsRes) assetsRes.releaseMaterial(handle);
+ else Material.release(handle);
}
}
diff --git a/sdk/tests/scene-asset-release.test.ts b/sdk/tests/scene-asset-release.test.ts
index 98557c4b2..5f277820c 100644
--- a/sdk/tests/scene-asset-release.test.ts
+++ b/sdk/tests/scene-asset-release.test.ts
@@ -26,6 +26,7 @@ vi.mock('../src/material', () => ({
import { SceneManagerState } from '../src/sceneManager';
import { Assets } from '../src/asset';
+import { Material } from '../src/material';
function createMockApp(assets?: unknown) {
const entities = new Map<number, Map<symbol, unknown>>();
@@ -110,6 +111,36 @@ describe('Scene unload releases all tracked asset categories', () => {
expect(releaseLog.tilemap).toEqual(['maps/level1.tmx']);
});
+ it('releases tracked materials through Assets by handle, not a bare Material.release', async () => {
+ vi.mocked(Material.release).mockClear();
+ const releasedHandles: number[] = [];
+ const assetsStub = {
+ releaseTexture: vi.fn(), releaseFont: vi.fn(), releaseAudio: vi.fn(),
+ releaseAnimClip: vi.fn(), releaseTimeline: vi.fn(), releaseTilemap: vi.fn(),
+ releaseMaterial: (h: number) => { releasedHandles.push(h); },
+ };
+
+ 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');
+
+ const instance = (manager as unknown as {
+ scenes_: Map<string, { loadedMaterials: Set<number> }>;
+ }).scenes_.get('level1')!;
+ instance.loadedMaterials = new Set([11, 22]);
+
+ await manager.unload('level1');
+
+ // Routed through Assets so the material refcount + path cache stay
+ // coherent; destroying the handle directly would strand it in the cache.
+ expect(releasedHandles).toEqual(expect.arrayContaining([11, 22]));
+ expect(Material.release).not.toHaveBeenCalled();
+ });
+
it('handles missing Assets resource gracefully (no throw)', async () => {
const app = createMockApp(); // No Assets resource
const manager = new SceneManagerState(app as never);
diff --git a/sdk/tests/sceneManager.test.ts b/sdk/tests/sceneManager.test.ts
index db0958e6a..766e37733 100644
--- a/sdk/tests/sceneManager.test.ts
+++ b/sdk/tests/sceneManager.test.ts
@@ -588,6 +588,35 @@ describe('SceneManager', () => {
manager.wake('level1');
expect(mockStack.setAllPassesEnabled).toHaveBeenCalledWith(true);
});
+
+ it('load() on a sleeping scene wakes it (restores enabled, clears sleeping)', async () => {
+ const entityMap = new Map([[100, 1]]);
+ vi.mocked(loadSceneWithAssets).mockResolvedValueOnce(entityMap);
+ setupEntityWithComponents(1);
+
+ manager.register({ name: 'level1', data: makeSceneData() });
+ await manager.load('level1');
+ manager.sleep('level1');
+ expect(manager.isSleeping('level1')).toBe(true);
+
+ // Re-loading a slept scene must run the full wake restore, not a bare
+ // status flip that would strand its entities Disabled forever.
+ await manager.load('level1');
+ expect(manager.getSceneStatus('level1')).toBe('running');
+ expect(manager.isSleeping('level1')).toBe(false);
+ expect(app._entities.get(1)!.get(Sprite).enabled).toBe(true);
+ });
+
+ it('load() on a paused scene resumes it (clears paused)', async () => {
+ manager.register({ name: 'level1', data: makeSceneData() });
+ await manager.load('level1');
+ manager.pause('level1');
+ expect(manager.isPaused('level1')).toBe(true);
+
+ await manager.load('level1');
+ expect(manager.getSceneStatus('level1')).toBe('running');
+ expect(manager.isPaused('level1')).toBe(false);
+ });
});
// =========================================================================