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 scene gives back the assets it acquired, not the refs it declared
esenginebb14c6434f8d
diff --git a/sdk/src/asset/AssetLease.ts b/sdk/src/asset/AssetLease.tsindex 1089fc369..db6527892 100644--- a/sdk/src/asset/AssetLease.ts+++ b/sdk/src/asset/AssetLease.ts@@ -23,11 +23,10 @@ export interface AssetLease<T = unknown> {/*** @brief Everything one owner acquired, released together.*- * @details What a scene, a group or a document owns. It holds receipts rather- * than paths, so unloading releases what was actually acquired — not- * what the manifest says the owner would acquire if it loaded today.- * An acquisition that failed produced no lease, so there is nothing to- * release and nothing to guess about.+ * @details Holds receipts rather than paths, so unloading releases what was+ * actually acquired — not what the manifest says this owner would+ * acquire if it loaded today. A failed acquisition produced no lease,+ * so there is nothing to release and nothing to guess about.*/export class AssetScope {private leases_: AssetLease[] = [];diff --git a/sdk/src/asset/AssetRefLedger.ts b/sdk/src/asset/AssetRefLedger.tsindex d7316d755..eb30d7f4b 100644--- a/sdk/src/asset/AssetRefLedger.ts+++ b/sdk/src/asset/AssetRefLedger.ts@@ -111,10 +111,9 @@ export class AssetRefLedger<T> {/*** Drop one reference to `key` without a receipt, oldest generation first.*- * The compatibility door for callers that only ever knew a path. It is- * exact while a key has ONE generation, which is every key that was never- * invalidated; `ambiguous` says it had to guess, so a caller that can carry- * a lease is asked to. See {@link release}.+ * The compatibility door for callers that only knew a path. Exact while a+ * key has ONE generation — every key never invalidated; `ambiguous` says it+ * had to guess. See {@link release}.*/releaseOldest(key: string): { value: T; exhausted: boolean; ambiguous: boolean } | undefined {const generations = this.byKey_.get(key);diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex eebc0d0a5..92b03bb9a 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -19,7 +19,7 @@ import { requireResourceManager, getResourceManager, evictTextureDimensions } frimport type { TextureImportSettings, TextureImportSettingsResolver } from './loaders/TextureLoader';import { TextureLoader, textureResidencyKey } from './loaders/TextureLoader';import { AssetRefLedger, type AssetRefLease } from './AssetRefLedger';-import type { AssetLease } from './AssetLease';+import { AssetScope, type AssetLease } from './AssetLease';import { SpineAssetLoader } from './loaders/SpineAssetLoader';import { MaterialAssetLoader } from './loaders/MaterialAssetLoader';import { MeshAssetLoader } from './loaders/MeshAssetLoader';@@ -245,6 +245,12 @@ export interface SceneAssetResult {meshHandles: Map<string, number>;environmentHandles: Map<string, number>;releaseCallbacks: ReleaseCallback[];+ /**+ * What this preload actually acquired. Release side reads THIS rather than+ * re-deriving from the scene's declared refs: a failed load left no lease,+ * and an invalidate mid-load left the receipt of the era we really got.+ */+ scope: AssetScope;missing: MissingAsset[];}@@ -1155,6 +1161,7 @@ export class Assets {const meshHandles = new Map<string, number>();const environmentHandles = new Map<string, number>();const releaseCallbacks: ReleaseCallback[] = [];+ const scope = new AssetScope();let loadedCount = 0;@@ -1186,6 +1193,7 @@ export class Assets {for (const path of paths) {tasks.push(() =>acquire(path).then(lease => {+ scope.add(lease);releaseCallbacks.push(() => lease.release());if (handles) {handles.set(path, (lease.value as { handle?: number } | null)?.handle ?? 0);@@ -1252,7 +1260,7 @@ export class Assets {});return { textureHandles, materialHandles, fontHandles, meshHandles, environmentHandles,- releaseCallbacks, missing };+ releaseCallbacks, scope, missing };}resolveSceneAssetPaths(sceneData: SceneData, result: SceneAssetResult): void {diff --git a/sdk/src/scene/scene.ts b/sdk/src/scene/scene.tsindex 589428993..22b0d2e81 100644--- a/sdk/src/scene/scene.ts+++ b/sdk/src/scene/scene.ts@@ -77,6 +77,12 @@ export interface LoadedSceneAssets {materialHandles: Set<number>;fontPaths: Set<string>;spineKeys: Set<string>;+ /**+ * The receipts the preload produced, handed to whoever owns the scene.+ * Present means the owner releases through these and must not also release+ * the same assets by path — that is the double free this replaces.+ */+ scope?: import('../asset/AssetLease').AssetScope;}/** Progress during a scene load, in assets: how many are done of how many.@@ -532,6 +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);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 d608bc8d2..4738b286a 100644--- a/sdk/src/scene/sceneManager.ts+++ b/sdk/src/scene/sceneManager.ts@@ -9,6 +9,7 @@ import type { App } from '../app/app';import type { Entity, Color } from '../types';import type { SceneData, SceneLoadOptions, LoadedSceneAssets, SceneLoadProgressCallback } from './scene';import { discoverSceneAssets } from '../asset/discoverAssets';+import { AssetScope } from '../asset/AssetLease';import type { SystemDef } from '../ecs/system';import { Material } from '../render/material';import type { DrawCallback } from '../render/customDraw';@@ -105,13 +106,18 @@ class SceneInstance {readonly savedEnabled = new Map<Entity, Map<RenderableComponentDef, boolean>>();readonly systemIds: symbol[] = [];/**- * Every path-keyed asset this scene acquired, by declared type. NOT a fixed- * list: it was seven fields, and the four types added since were preloaded- * and never released, because adding one meant remembering three places.+ * What this scene's preload actually acquired, receipt by receipt. Released+ * as a scope at unload, so what goes back is what was taken — not what the+ * scene's refs resolve to by then.+ */+ readonly assetScope = new AssetScope();+ /**+ * Path-keyed assets registered by a loader that did its own acquiring+ * ({@link SceneContext.trackAssets}) — a packaged scene carries no data, so+ * the manager's preload never ran for it. Released by path, because a path+ * is all such a caller ever had.*/readonly loadedByType = new Map<string, Set<string>>();- /** Materials are keyed by HANDLE, not path — released through their own door. */- loadedMaterials: Set<number> | null = null;status: SceneStatus = 'loading';constructor(config: SceneConfig) {@@ -550,27 +556,18 @@ export class SceneManagerState {onProgress?: SceneLoadProgressCallback,): Promise<void> {if (sceneData) {- const discovered = discoverSceneAssets(sceneData);instance.loadedByType.clear();- // Whatever the scene declared, whatever its type. Materials are- // collected as handles below; skeletons belong to the SpineManager.- for (const [type, paths] of discovered.byType) {- if (type === 'material' || type === 'spine') continue;- instance.loadedByType.set(type, new Set(paths));- }- const bucketFor = (type: string): Set<string> => {- let set = instance.loadedByType.get(type);- if (!set) { set = new Set(); instance.loadedByType.set(type, set); }- return set;- };- instance.loadedMaterials = new Set();const collectAssets: LoadedSceneAssets = {- // The SAME sets the preloader fills in with what it actually- // loaded, so the release side sees acquisitions, not intentions.- texturePaths: bucketFor('texture'),- materialHandles: instance.loadedMaterials,- fontPaths: bucketFor('font'),+ // What the scene DECLARED is an intention; ownership is the set+ // of receipts the preload hands back, and only successful+ // acquisitions produce one.+ scope: instance.assetScope,+ // The handle sets are the loader's scratch; ownership is the+ // scope, so nothing here is read back at unload.+ texturePaths: new Set(),+ materialHandles: new Set(),+ fontPaths: new Set(),spineKeys: new Set(),};@@ -632,22 +629,15 @@ export class SceneManagerState {? this.app_.getResource(Assets): null;- // Whatever the scene acquired, through the one batch door. A type with a- // registered loader has a release channel; one without no-ops.- assetsRes?.releaseAssets(instance.loadedByType);+ // What this scene actually acquired, given back by receipt. Materials+ // included — their leases are in here too, so releasing them again by+ // handle below would be the double free this whole path exists to stop.+ instance.assetScope.releaseAll();- if (instance.loadedMaterials) {- for (const handle of instance.loadedMaterials) {- // 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);- }- }+ // Assets a loader acquired on its own and only registered by path.+ assetsRes?.releaseAssets(instance.loadedByType);instance.loadedByType.clear();- instance.loadedMaterials = null;}pause(name: string): void {diff --git a/sdk/tests/asset-generation-ownership.test.ts b/sdk/tests/asset-generation-ownership.test.tsindex 74ac057bf..ec0de9013 100644--- a/sdk/tests/asset-generation-ownership.test.ts+++ b/sdk/tests/asset-generation-ownership.test.ts@@ -105,6 +105,86 @@ describe('asset ownership is generation-exact', () => {expect(ledger.rows).toBe(0);});+ it('a scene preload hands back a receipt per SUCCESSFUL acquire', async () => {+ // Covers the wiring a mocked scene loader cannot: preloadSceneAssets+ // fills the scope itself, and a load that threw leaves nothing in it.+ const unloaded: string[] = [];+ let n = 0;+ const assets = makeAssets(unloaded);+ assets.register<{ handle: number; id: string }>({+ type: 'mesh',+ load: async (path: string) => {+ if (path.includes('broken')) throw new Error('no bytes');+ return { handle: 70 + (++n), id: `mesh${n}` };+ },+ unload: (v: { id: string }) => { unloaded.push(v.id); },+ } as never);++ const scene = {+ version: '1.0', name: 's', entities: [+ { id: 1, name: 'a', parent: null, children: [],+ components: [{ type: 'MeshRenderer', data: { mesh: 'ship.esmesh' } }] },+ { id: 2, name: 'b', parent: null, children: [],+ components: [{ type: 'MeshRenderer', data: { mesh: 'broken.esmesh' } }] },+ ],+ } as never;++ const base = assets.sizes().refRows;+ const result = await assets.preloadSceneAssets(scene);+ expect(result.missing.map(m => m.ref)).toContain('broken.esmesh');+ // One receipt: the failed acquire owns nothing, so unload has nothing+ // to give back for it and nothing to guess at.+ expect(result.scope.size).toBe(1);++ result.scope.releaseAll();+ expect(unloaded).toEqual(['mesh1']);+ expect(assets.sizes().refRows).toBe(base);+ });++ it('one scene\'s unload cannot touch another scene\'s generation', async () => {+ const unloaded: string[] = [];+ const assets = makeAssets(unloaded);+ const base = assets.sizes().refRows;++ const sceneA = new AssetScope();+ sceneA.add(await assets.acquireTyped('font', 'shared.ttf'));++ // A hot update lands between the two scenes.+ assets.invalidate('shared.ttf');++ const sceneB = new AssetScope();+ sceneB.add(await assets.acquireTyped('font', 'shared.ttf'));++ sceneB.releaseAll();+ expect(unloaded).toEqual(['gen2']); // B gave back B's era+ expect(assets.sizes().refRows).toBe(base + 1); // A still holds one++ sceneA.releaseAll();+ expect(unloaded).toEqual(['gen2', 'gen1']);+ expect(assets.sizes().refRows).toBe(base);+ });++ it('a scene survives many hot updates and still balances at unload', async () => {+ // The dogfood shape: load, hot-update the same asset repeatedly, unload.+ // Every era that was acquired is given back exactly once.+ const unloaded: string[] = [];+ const assets = makeAssets(unloaded);+ const base = assets.sizes().refRows;+ const scene = new AssetScope();++ scene.add(await assets.acquireTyped('font', 'hero.ttf'));+ for (let i = 0; i < 10; i++) {+ assets.invalidate('hero.ttf');+ scene.add(await assets.acquireTyped('font', 'hero.ttf'));+ }+ expect(scene.size).toBe(11);++ scene.releaseAll();+ expect(unloaded).toHaveLength(11);+ expect(new Set(unloaded).size).toBe(11); // no era freed twice+ expect(assets.sizes().refRows).toBe(base); // and none stranded+ });+it('a scope releases what it actually acquired', async () => {const unloaded: string[] = [];const assets = makeAssets(unloaded);diff --git a/sdk/tests/scene-asset-receipts.test.ts b/sdk/tests/scene-asset-receipts.test.tsnew file mode 100644index 000000000..96d54cf0f--- /dev/null+++ b/sdk/tests/scene-asset-receipts.test.ts@@ -0,0 +1,66 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file scene-asset-receipts.test.ts+ * @brief A scene load hands its owner the receipts the preload produced.+ *+ * @details Deliberately does NOT mock loadSceneWithAssets: every other scene+ * test does, so the one line that carries ownership from the preload+ * to the scene had no coverage at all — removing it left the suite+ * green while unload silently stopped releasing anything.+ */+import { describe, it, expect, vi } from 'vitest';+import { World } from '../src/ecs/world';+import { loadSceneWithAssets } from '../src/scene/scene';+import { Assets } from '../src/asset/Assets';+import { AssetScope } from '../src/asset/AssetLease';+import type { Backend } from '../src/asset/Backend';+import type { SceneData } from '../src/scene/scene';++vi.mock('../src/wasm/resourceManager', () => ({+ requireResourceManager: () => ({ releaseTexture: vi.fn(), invalidateTexturePath: vi.fn(() => false) }),+ getResourceManager: () => null,+ evictTextureDimensions: vi.fn(),+}));++describe('a scene owns the receipts its preload produced', () => {+ it('carries them to collectAssets, and they release the real asset', async () => {+ const unloaded: string[] = [];+ 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<{ handle: number; id: string }>({+ type: 'mesh',+ load: async () => ({ handle: 70 + (++n), id: `mesh${n}` }),+ unload: (v: { id: string }) => { unloaded.push(v.id); },+ } as never);++ const scene = {+ version: '1.0', name: 's',+ entities: [{+ id: 1, name: 'ship', parent: null, children: [],+ components: [{ type: 'MeshRenderer', data: { mesh: 'ship.esmesh' } }],+ }],+ } as unknown as SceneData;++ const scope = new AssetScope();+ await loadSceneWithAssets(new World(), scene, {+ assets,+ collectAssets: {+ scope,+ texturePaths: new Set(), materialHandles: new Set(),+ fontPaths: new Set(), spineKeys: new Set(),+ },+ });++ expect(scope.size, 'the preload acquired a mesh but the scene got no receipt').toBe(1);+ scope.releaseAll();+ expect(unloaded).toEqual(['mesh1']);+ });+});diff --git a/sdk/tests/scene-asset-release.test.ts b/sdk/tests/scene-asset-release.test.tsindex b9b0c9717..f4ea06de2 100644--- a/sdk/tests/scene-asset-release.test.ts+++ b/sdk/tests/scene-asset-release.test.ts@@ -2,14 +2,30 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @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).+ * @brief A scene gives back what it acquired: the receipts its preload+ * produced, plus path-keyed assets a loader registered itself.+ *+ * @details Ownership is the set of RECEIPTS, not the refs the scene declares —+ * a declared asset whose load failed was never acquired, and after+ * invalidate() one path no longer names one instance.*/import { describe, expect, it, beforeEach, vi } from 'vitest';+// Stands in for the preload: the real loadSceneWithAssets hands the owner the+// receipts its acquires produced, and unload releases through those.+const preloaded: Array<{ type: string; path: string; released: number }> = [];vi.mock('../src/scene/scene', () => ({- loadSceneWithAssets: vi.fn().mockResolvedValue(new Map()),+ loadSceneWithAssets: vi.fn(async (_w: unknown, _d: unknown, options?: {+ collectAssets?: { scope?: { add: (l: unknown) => unknown } };+ }) => {+ for (const entry of preloaded) {+ options?.collectAssets?.scope?.add({+ key: `${entry.type}:${entry.path}`, generation: 1, value: null,+ release: () => { entry.released++; },+ });+ }+ return new Map();+ }),}));vi.mock('../src/render/customDraw', () => ({registerDrawCallback: vi.fn(),@@ -88,7 +104,7 @@ function createMockApp(assets?: unknown) {describe('Scene unload releases all tracked asset categories', () => {// Shared across the mock module, so a test that seeds it must not leak into// the next one's scene.- beforeEach(() => { discovered.byType = new Map(); });+ beforeEach(() => { discovered.byType = new Map(); preloaded.length = 0; });/*** Every path-keyed type a scene can declare, one path each.@@ -110,29 +126,40 @@ describe('Scene unload releases all tracked asset categories', () => {['animatorcontroller', 'anim/hero.esanimator'],];- it('buckets every type discovery reports, including ones added later', async () => {- // The original bug lived HERE, not in the release wiring: seven- // hard-coded buckets, so a scene declaring a tileset acquired a- // reference the manager never recorded and unload could not give back.- discovered.byType = new Map(TRACKED.map(([type, path]) => [type, new Set([path])]));+ it('gives back every receipt its preload produced, whatever the type', async () => {+ // The original bug lived in the bucketing: seven hard-coded categories,+ // so a tileset was acquired and never given back. Ownership is receipts+ // now, so a newly added type either produces one or was never acquired.+ for (const [type, path] of TRACKED) preloaded.push({ type, path, released: 0 });const app = createMockApp({ releaseTexture: vi.fn(), releaseTyped: vi.fn() });const manager = new SceneManagerState(app as never);manager.register({ name: 'declaring', data: { version: '1.0', name: 'd', entities: [] } });await manager.load('declaring');+ await manager.unload('declaring');- const instance = (manager as unknown as {- scenes_: Map<string, { loadedByType: Map<string, Set<string>> }>;- }).scenes_.get('declaring')!;-- for (const [type, path] of TRACKED) {- expect(- [...(instance.loadedByType.get(type) ?? [])],- `the scene declared a ${type} and the manager kept no bucket for it`,- ).toContain(path);+ for (const entry of preloaded) {+ expect(entry.released, `the ${entry.type} it acquired was never given back`).toBe(1);}});+ it('declaring an asset it never acquired releases nothing', async () => {+ // A failed load leaves no receipt, so unload has nothing to hand back+ // and nothing to guess at. Declaring is not owning.+ discovered.byType = new Map(TRACKED.map(([type, path]) => [type, new Set([path])]));+ const released: Array<[string, string]> = [];+ const app = createMockApp({+ releaseTexture: (r: string) => { released.push(['texture', r]); },+ releaseTyped: (t: string, r: string) => { released.push([t, r]); },+ });+ const manager = new SceneManagerState(app as never);+ manager.register({ name: 'declaring', data: { version: '1.0', name: 'd', entities: [] } });+ await manager.load('declaring');+ await manager.unload('declaring');++ expect(released).toEqual([]);+ });+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@@ -198,33 +225,22 @@ describe('Scene unload releases all tracked asset categories', () => {}});- it('releases tracked materials through Assets by handle, not a bare Material.release', async () => {+ it('releases materials through their receipt, not a bare Material.release', async () => {vi.mocked(Material.release).mockClear();- const releasedHandles: number[] = [];- const assetsStub = {- releaseTexture: vi.fn(), releaseTyped: vi.fn(), releaseFont: vi.fn(), releaseAudio: vi.fn(),- releaseAnimClip: vi.fn(), releaseTimeline: vi.fn(), releaseTilemap: vi.fn(),- releaseMaterial: (h: number) => { releasedHandles.push(h); },- };+ preloaded.push({ type: 'material', path: 'mat/hero.esmat', released: 0 });- const app = createMockApp(assetsStub);+ const app = createMockApp({ releaseTexture: vi.fn(), releaseTyped: vi.fn() });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]));+ // Through the lease, so the material's refcount + path cache stay+ // coherent; destroying the handle directly strands it in the cache.+ expect(preloaded[0].released).toBe(1);expect(Material.release).not.toHaveBeenCalled();});diff --git a/sdk/tests/sceneManager.test.ts b/sdk/tests/sceneManager.test.tsindex efe1dfcfc..a76c02fb3 100644--- a/sdk/tests/sceneManager.test.ts+++ b/sdk/tests/sceneManager.test.ts@@ -324,13 +324,17 @@ describe('SceneManager', () => {expect(PostProcess.unbind).toHaveBeenCalledWith(1);});- it('unload() releases material handles from loadedAssets', async () => {+ it('unload() releases what the scene acquired, by receipt', async () => {+ let released = 0;vi.mocked(loadSceneWithAssets).mockImplementationOnce(async (_world, _data, options) => {- if (options?.collectAssets) {- options.collectAssets.materialHandles.add(10);- options.collectAssets.materialHandles.add(20);- }+ // What the real preload hands back: a receipt per successful+ // acquire, materials included. Releasing by handle instead+ // would free whatever that path resolves to at unload.+ options?.collectAssets?.scope?.add({+ key: 'material:hero.esmat', generation: 1, value: null,+ release: () => { released++; },+ } as never);return new Map();});@@ -339,8 +343,8 @@ describe('SceneManager', () => {await manager.load('level1');await manager.unload('level1');- expect(Material.release).toHaveBeenCalledWith(10);- expect(Material.release).toHaveBeenCalledWith(20);+ expect(released).toBe(1);+ expect(Material.release).not.toHaveBeenCalled();});it('unload() clears activeScene if unloaded scene was active', async () => {