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(assets): a texture reference has to know which generation it is for
esengine48cc45ac0856
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex ad46514fb..c91490081 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -235,7 +235,25 @@ export class Assets {// owner; release its GL handle so it doesn't leak VRAM.requireResourceManager().releaseTexture(result.handle);});- private textureRefCounts_ = new Map<string, number>();+ /**+ * Live texture references per cache key, oldest generation first.+ *+ * Carries the HANDLE, not just a count: invalidate() mints a new generation+ * while the previous still has holders, and one slot per key attributed+ * their release to the replacement — a texture stranded per hot reload.+ */+ private textureRefs_ = new Map<string, Array<{ handle: number; count: number }>>();++ /**+ * Bumped by releaseAll(). A load in flight across one has no owner left: the+ * scene that asked is gone and its references were dropped, so the texture+ * it produces is destroyed by the pool before the caller's `await` ever+ * resumes. Delivering that handle is a use-after-free; the load fails instead.+ */+ private resetEpoch_ = 0;+ /** Handles already disowned in this epoch, so N callers sharing one load+ * drop its single C++ reference once between them, not N times. */+ private abandoned_ = new Set<number>();private genericCache_ = new Map<string, AsyncCache<unknown>>();/** Per-asset reference counts for the generic caches, keyed `type:path`.* Same contract as textures: every load*() increments, every release*()@@ -299,6 +317,7 @@ export class Assets {const path = this.resolveLoadPath_(ref);const cacheKey = this.textureCacheKey_(path, flip);const settings = this.textureImportResolver_?.(ref);+ const epoch = this.resetEpoch_;const result = await this.textureCache_.getOrLoad(cacheKey, () => {// Warm-cache hit: a texture whose last reference was released stays// resident in the C++ pool (up to the texture budget) under this@@ -310,7 +329,20 @@ export class Assets {? this.textureLoader_.load(path, this.getLoadContext_()): this.textureLoader_.loadRaw(path, this.getLoadContext_());});- this.textureRefCounts_.set(cacheKey, (this.textureRefCounts_.get(cacheKey) ?? 0) + 1);+ // BEFORE acquiring, so no ledger entry is ever created for a load nobody+ // is left to own — one that N shared callers would each then drop,+ // releasing the load's single C++ reference N times.+ if (epoch !== this.resetEpoch_) {+ if (!this.abandoned_.has(result.handle)) {+ this.abandoned_.add(result.handle);+ requireResourceManager().releaseTexture(result.handle);+ evictTextureDimensions(result.handle);+ }+ throw new Error(+ `Assets were released while "${ref}" was loading; its texture has no owner. Load it again.`,+ );+ }+ this.acquireTextureRef_(cacheKey, result.handle);this.recordHandlePath_('texture', result.handle, path);// The 9-slice border belongs to the IMAGE, so it rides its import// settings and is stamped onto the handle here — the one place every@@ -1158,28 +1190,46 @@ export class Assets {// Release// =========================================================================+ /** Record one more holder of `handle` under `cacheKey`. */+ private acquireTextureRef_(cacheKey: string, handle: number): void {+ let generations = this.textureRefs_.get(cacheKey);+ if (!generations) {+ generations = [];+ this.textureRefs_.set(cacheKey, generations);+ }+ const existing = generations.find((g) => g.handle === handle);+ if (existing) existing.count++;+ else generations.push({ handle, count: 1 });+ }+releaseTexture(ref: string): void {const path = this.resolveLoadPath_(ref);for (const flip of [true, false]) {const key = this.textureCacheKey_(path, flip);- const count = this.textureRefCounts_.get(key);- if (count === undefined) continue;-- const info = this.textureCache_.get(key);- if (!info) continue;-- const newCount = count - 1;- if (newCount <= 0) {- // Last SDK reference: drop our one C++ ref. The pool decides- // what that means — free immediately (no budget), or retain as- // an evictable cache entry that the next load revives by key.- const rm = requireResourceManager();- rm.releaseTexture(info.handle);- evictTextureDimensions(info.handle);+ const generations = this.textureRefs_.get(key);+ if (!generations || generations.length === 0) continue;++ // Oldest first, so a superseded generation drains as its holders let+ // go. Holders are indistinguishable through a ref-keyed API, and a+ // release naming the old handle never comes.+ const oldest = generations[0];+ oldest.count--;+ if (oldest.count > 0) continue;++ generations.shift();+ if (generations.length === 0) this.textureRefs_.delete(key);++ // Last SDK reference: drop our one C++ ref. The pool decides what+ // that means — free immediately (no budget), or retain as an+ // evictable cache entry that the next load revives by key.+ const rm = requireResourceManager();+ rm.releaseTexture(oldest.handle);+ evictTextureDimensions(oldest.handle);+ // Only when it is still the cached value: a superseded handle left+ // the cache when its generation ended, and the entry there now+ // belongs to a generation with holders of its own.+ if (this.textureCache_.get(key)?.handle === oldest.handle) {this.textureCache_.delete(key);- this.textureRefCounts_.delete(key);- } else {- this.textureRefCounts_.set(key, newCount);}}}@@ -1273,7 +1323,9 @@ export class Assets {for (const flip of [true, false]) {const key = this.textureCacheKey_(path, flip);if (this.textureCache_.invalidate(key)) hit = true;- if (this.textureRefCounts_.delete(key)) hit = true;+ // The ledger is NOT dropped: holders of the outgoing generation+ // still owe a release, and forgetting them is what stranded their+ // texture with nobody able to free it.if (typeof rm?.invalidateTexturePath === 'function') {if (rm.invalidateTexturePath(key)) hit = true;}@@ -1361,7 +1413,7 @@ export class Assets {return {textureCached: tex.cached,pendingLoads: pending,- refCounts: this.textureRefCounts_.size + this.genericRefCounts_.size,+ refCounts: this.textureRefs_.size + this.genericRefCounts_.size,genericCaches: this.genericCache_.size,genericCached,handlePaths: this.handleToPath_.size,@@ -1373,12 +1425,27 @@ export class Assets {releaseAll(): void {const rm = requireResourceManager();+ this.resetEpoch_++;+ this.abandoned_.clear();+ const seen = new Set<number>();for (const info of this.textureCache_.values()) {+ seen.add(info.handle);rm.releaseTexture(info.handle);evictTextureDimensions(info.handle);}this.textureCache_.clearAll();- this.textureRefCounts_.clear();+ // Superseded generations are not in the cache and would otherwise+ // survive a releaseAll that claims to have let go of everything.+ for (const generations of this.textureRefs_.values()) {+ for (const generation of generations) {+ if (!seen.has(generation.handle)) {+ seen.add(generation.handle);+ rm.releaseTexture(generation.handle);+ evictTextureDimensions(generation.handle);+ }+ }+ }+ this.textureRefs_.clear();this.spineLoader_.releaseAll();this.materialLoader_?.releaseAll();diff --git a/sdk/tests/assets-invalidate-event.test.ts b/sdk/tests/assets-invalidate-event.test.tsindex 585c7a9b9..47d316915 100644--- a/sdk/tests/assets-invalidate-event.test.ts+++ b/sdk/tests/assets-invalidate-event.test.ts@@ -42,11 +42,11 @@ describe('Assets.onInvalidate', () => {const internal = assets as unknown as {textureCache_: { cache_: Map<string, unknown> };textureCacheKey_: (path: string, flip: boolean) => string;- textureRefCounts_: Map<string, number>;+ textureRefs_: Map<string, Array<{ handle: number; count: number }>>;};const key = internal.textureCacheKey_('tex/hot.png', false);internal.textureCache_.cache_.set(key, { handle: 42 });- internal.textureRefCounts_.set(key, 1);+ internal.textureRefs_.set(key, [{ handle: 42, count: 1 }]);const listener = vi.fn();assets.onInvalidate(listener);@@ -63,11 +63,11 @@ describe('Assets.onInvalidate', () => {const internal = assets as unknown as {textureCache_: { cache_: Map<string, unknown> };textureCacheKey_: (path: string, flip: boolean) => string;- textureRefCounts_: Map<string, number>;+ textureRefs_: Map<string, Array<{ handle: number; count: number }>>;};const key = internal.textureCacheKey_('tex/hot.png', false);internal.textureCache_.cache_.set(key, { handle: 42 });- internal.textureRefCounts_.set(key, 1);+ internal.textureRefs_.set(key, [{ handle: 42, count: 1 }]);const listener = vi.fn();const unsubscribe = assets.onInvalidate(listener);@@ -79,7 +79,7 @@ describe('Assets.onInvalidate', () => {// Re-populate cache and invalidate again — listener should NOT fire.internal.textureCache_.cache_.set(key, { handle: 43 });- internal.textureRefCounts_.set(key, 1);+ internal.textureRefs_.set(key, [{ handle: 43, count: 1 }]);assets.invalidate('tex/hot.png');expect(listener).toHaveBeenCalledTimes(1);});@@ -89,11 +89,11 @@ describe('Assets.onInvalidate', () => {const internal = assets as unknown as {textureCache_: { cache_: Map<string, unknown> };textureCacheKey_: (path: string, flip: boolean) => string;- textureRefCounts_: Map<string, number>;+ textureRefs_: Map<string, Array<{ handle: number; count: number }>>;};const key = internal.textureCacheKey_('tex/hot.png', false);internal.textureCache_.cache_.set(key, { handle: 42 });- internal.textureRefCounts_.set(key, 1);+ internal.textureRefs_.set(key, [{ handle: 42, count: 1 }]);const bad = vi.fn(() => { throw new Error('listener failed'); });const good = vi.fn();@@ -110,11 +110,11 @@ describe('Assets.onInvalidate', () => {const internal = assets as unknown as {textureCache_: { cache_: Map<string, unknown> };textureCacheKey_: (path: string, flip: boolean) => string;- textureRefCounts_: Map<string, number>;+ textureRefs_: Map<string, Array<{ handle: number; count: number }>>;};const key = internal.textureCacheKey_('tex/a.png', false);internal.textureCache_.cache_.set(key, { handle: 1 });- internal.textureRefCounts_.set(key, 1);+ internal.textureRefs_.set(key, [{ handle: 1, count: 1 }]);const a = vi.fn();const b = vi.fn();