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 loader gives back the texture era it bound, not the oldest
esengine4b4a899c0c5f
diff --git a/sdk/src/asset/AssetLoader.ts b/sdk/src/asset/AssetLoader.tsindex 574d8d5de..0ad8801d3 100644--- a/sdk/src/asset/AssetLoader.ts+++ b/sdk/src/asset/AssetLoader.ts@@ -1,6 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport type { Backend } from './Backend';+import type { AssetLease } from './AssetLease';import type { Catalog } from './Catalog';import type { TextureHandle, FontHandle } from '../types';import type { CppResourceManager } from '../wasm';@@ -23,9 +24,9 @@ export interface SpineLoadResult {export interface MaterialResult {handle: number;shaderHandle: number;- /** Texture refs this material bound; released on unload to balance the- * loadTexture that bound them (they aren't in the scene's texture set). */- texturePaths?: string[];+ /** Receipts for the textures this material bound; released on unload. Not+ * paths: a hot update between load and unload makes one path name two. */+ textureLeases?: AssetLease<TextureResult>[];/** Parent material handle for an `instanceOf` material, released on unload. */parentHandle?: number;}@@ -98,8 +99,18 @@ export interface LoadContext {catalog: Catalog;resourceManager: CppResourceManager;loadTexture(path: string, flipY?: boolean): Promise<TextureResult>;- /** Release a texture obtained via {@link loadTexture} (balances the refcount).- * Handles both flip variants, so the same ref that was loaded releases it. */+ /**+ * Load a texture and get the receipt for THIS acquisition — what a loader+ * holding a texture past its own `load` needs, because a path-addressed+ * release after an invalidate gives back the oldest era rather than the one+ * this loader was handed.+ */+ acquireTexture(path: string, flipY?: boolean): Promise<AssetLease<TextureResult>>;+ /**+ * Release by path — the compatibility door for a loader that only ever had+ * one. Exact while a path names one instance; after an invalidate it gives+ * back the OLDEST era sharing the path. See {@link acquireTexture}.+ */releaseTexture(path: string): void;loadText(path: string): Promise<string>;loadBinary(path: string): Promise<ArrayBuffer>;diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex b75570914..63f727856 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -1927,6 +1927,13 @@ export class Assets {}return self.loadTexture(path);},+ async acquireTexture(path: string, flipY?: boolean): Promise<AssetLease<TextureResult>> {+ const { result, lease } = await self.acquireTextureVariant_(path, flipY !== false);+ return {+ key: lease.key, generation: lease.generation, value: result,+ release: () => self.releaseTextureLease(lease),+ };+ },releaseTexture(path: string): void {self.releaseTexture(path);},diff --git a/sdk/src/asset/loaders/EnvironmentAssetLoader.ts b/sdk/src/asset/loaders/EnvironmentAssetLoader.tsindex 92250780b..2f53f1a65 100644--- a/sdk/src/asset/loaders/EnvironmentAssetLoader.ts+++ b/sdk/src/asset/loaders/EnvironmentAssetLoader.ts@@ -1,6 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-import type { AssetLoader, LoadContext } from '../AssetLoader';+import type { AssetLoader, LoadContext, TextureResult } from '../AssetLoader';+import type { AssetLease } from '../AssetLease';import { resolveDocumentRef } from '../documentRef';import type { EngineApi } from '../../ecs/bridge/engineApi';import { marshallingCore } from './engineCore';@@ -21,8 +22,9 @@ interface EnvironmentAssetData {/** A baked environment, named by the handle a Light references. */export interface EnvironmentResult {handle: number;- /** The atlas path, so unload releases the texture ref this load took. */- specularPath?: string;+ /** The receipt for the atlas, so unload gives back the era this load took —+ * a path names two of them once a hot update has landed. */+ specularLease?: AssetLease<TextureResult>;}/**@@ -55,15 +57,15 @@ export class EnvironmentAssetLoader implements AssetLoader<EnvironmentResult> {// the load: nine coefficients still light the scene, and a reflection that// silently took the whole asset down would be the worse answer.let specularHandle = 0;- let specularPath: string | undefined;+ let specularLease: AssetLease<TextureResult> | undefined;if (data.specular) {const resolved = resolveDocumentRef(path, data.specular);try {// flipY false: the atlas' rows are a layout, not a picture. Row 0// is mip 0, and a load that turned it over would put the mip// offsets — and every face's v — upside down.- specularHandle = (await ctx.loadTexture(resolved, false)).handle;- specularPath = resolved;+ specularLease = await ctx.acquireTexture(resolved, false);+ specularHandle = specularLease.value.handle;} catch (e) {log.warn('asset', `${path}: no reflection atlas at '${resolved}'`, e);}@@ -77,15 +79,15 @@ export class EnvironmentAssetLoader implements AssetLoader<EnvironmentResult> {});if (!handle) {- if (specularPath) ctx.releaseTexture(specularPath);+ specularLease?.release();throw new Error(`the engine rejected the environment in ${path}`);}- return { handle, specularPath };+ return { handle, specularLease };}- unload(asset: EnvironmentResult, ctx: LoadContext): void {+ unload(asset: EnvironmentResult): void {this.core_()?.environment_release?.(asset.handle);- if (asset.specularPath) ctx.releaseTexture(asset.specularPath);+ asset.specularLease?.release();}}diff --git a/sdk/src/asset/loaders/MaterialAssetLoader.ts b/sdk/src/asset/loaders/MaterialAssetLoader.tsindex 05306bcd9..e7ffce218 100644--- a/sdk/src/asset/loaders/MaterialAssetLoader.ts+++ b/sdk/src/asset/loaders/MaterialAssetLoader.ts@@ -1,6 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-import type { AssetLoader, LoadContext, MaterialResult } from '../AssetLoader';+import type { AssetLoader, LoadContext, MaterialResult, TextureResult } from '../AssetLoader';+import type { AssetLease } from '../AssetLease';import { BUILTIN_REF_PREFIX, isBuiltinAssetRef, resolveDocumentRef } from '../documentRef';import type { MaterialAssetData, ShaderHandle } from '../../render/material';import { Material } from '../../render/material';@@ -30,11 +31,11 @@ export class MaterialAssetLoader implements AssetLoader<MaterialResult> {const parentPath = resolveDocumentRef(path, data.instanceOf);const parent = await this.load(parentPath, ctx);const handle = Material.createFromAsset(data, 0, parent.handle);- const texturePaths = await this.applyTextureProps(handle, data, path, ctx);+ const textureLeases = await this.applyTextureProps(handle, data, path, ctx);return {handle,shaderHandle: parent.shaderHandle,- texturePaths: [...(parent.texturePaths ?? []), ...texturePaths],+ textureLeases: [...(parent.textureLeases ?? []), ...textureLeases],parentHandle: parent.handle,};}@@ -43,28 +44,29 @@ export class MaterialAssetLoader implements AssetLoader<MaterialResult> {const features = enabledSwitches(data.switches);const shaderHandle = await this.loadShader(path, data.shader, features, ctx);const handle = Material.createFromAsset(data, shaderHandle);- const texturePaths = await this.applyTextureProps(handle, data, path, ctx);+ const textureLeases = await this.applyTextureProps(handle, data, path, ctx);- return { handle, shaderHandle, texturePaths };+ return { handle, shaderHandle, textureLeases };}// A texture param is a string property (an asset ref); scalar/vector params are- // numbers/objects (handled by createFromAsset). Load each texture, bind it to its- // param, and return the refs so unload can release them (they hold a texture ref).+ // numbers/objects (handled by createFromAsset). Bind each texture and keep its+ // RECEIPT, so unload gives back the era this material bound rather than+ // whichever one shares its path by then.private async applyTextureProps(handle: number,data: MaterialAssetData,matPath: string,ctx: LoadContext,- ): Promise<string[]> {- const bound: string[] = [];+ ): Promise<AssetLease<TextureResult>[]> {+ const bound: AssetLease<TextureResult>[] = [];for (const [name, value] of Object.entries(data.properties)) {if (typeof value !== 'string') continue;const texPath = resolveDocumentRef(matPath, value);try {- const tex = await ctx.loadTexture(texPath);- Material.setUniform(handle, name, Material.tex(tex.handle));- bound.push(texPath); // recorded only on success — matches the refcount taken+ const tex = await ctx.acquireTexture(texPath);+ Material.setUniform(handle, name, Material.tex(tex.value.handle));+ bound.push(tex); // recorded only on success — matches the acquisition taken} catch (e) {// Missing texture: leave the param unbound (it samples whatever is at the unit).log.warn('asset', `Material ${matPath}: failed to load texture '${texPath}' for param '${name}'`, e);@@ -73,9 +75,9 @@ export class MaterialAssetLoader implements AssetLoader<MaterialResult> {return bound;}- unload(asset: MaterialResult, ctx: LoadContext): void {- if (asset.texturePaths) {- for (const texPath of asset.texturePaths) ctx.releaseTexture(texPath);+ unload(asset: MaterialResult): void {+ if (asset.textureLeases) {+ for (const lease of asset.textureLeases) lease.release();}if (asset.parentHandle !== undefined) Material.release(asset.parentHandle);Material.release(asset.handle);diff --git a/sdk/tests/material-asset-loader.test.ts b/sdk/tests/material-asset-loader.test.tsindex e5e6be557..63841a8a6 100644--- a/sdk/tests/material-asset-loader.test.ts+++ b/sdk/tests/material-asset-loader.test.ts@@ -28,7 +28,7 @@ function makeCtx(): LoadContext {return {catalog: { getBuildPath: (p: string) => p },loadText: vi.fn(async (p: string) => (p.endsWith('.esmaterial') ? materialJson : '// shader src')),- loadTexture: vi.fn().mockRejectedValue(new Error('404 not found')),+ acquireTexture: vi.fn().mockRejectedValue(new Error('404 not found')),} as unknown as LoadContext;}@@ -74,28 +74,36 @@ describe('MaterialAssetLoader texture release on unload', () => {const materialJson = JSON.stringify({type: 'material', shader: 'fx.esshader', properties: { mainTex: TEX_REF },});- const releaseTexture = vi.fn();+ const released: Array<{ key: string; generation: number }> = [];+ let generation = 0;const ctx = {catalog: { getBuildPath: (p: string) => p },loadText: vi.fn(async (p: string) => (p.endsWith('.esmaterial') ? materialJson : '// shader src')),- loadTexture: vi.fn(async () => ({ handle: 42 })),- releaseTexture,+ acquireTexture: vi.fn(async (path: string) => {+ const lease = {+ key: `texture:${path}`, generation: ++generation, value: { handle: 42 },+ release: () => released.push({ key: lease.key, generation: lease.generation }),+ };+ return lease;+ }),} as unknown as LoadContext;- return { ctx, releaseTexture };+ return { ctx, released };}- it('records bound texture refs and releases them on unload (no VRAM leak)', async () => {+ it('keeps the RECEIPT for each bound texture and gives it back on unload', async () => {const loader = new MaterialAssetLoader();- const { ctx, releaseTexture } = makeCtxWithTexture();+ const { ctx, released } = makeCtxWithTexture();const result = await loader.load(MAT_PATH, ctx);- // The bound texture is recorded so unload can balance its loadTexture ref;- // the scene's texture set never sees a material-internal texture.- expect(result.texturePaths).toEqual(['assets/materials/missing.png']);+ // The acquisition is recorded, not the path: a hot update between load+ // and unload makes one path name two eras, and a release addressed by+ // path gives back the older one — a stranger's.+ expect(result.textureLeases?.map((l) => l.key))+ .toEqual(['texture:assets/materials/missing.png']);expect(Material.setUniform).toHaveBeenCalled();loader.unload(result, ctx);- expect(releaseTexture).toHaveBeenCalledWith('assets/materials/missing.png');+ expect(released).toEqual([{ key: 'texture:assets/materials/missing.png', generation: 1 }]);expect(Material.release).toHaveBeenCalledWith(11);});});diff --git a/tools/check-live-asset-rebind.mjs b/tools/check-live-asset-rebind.mjsindex 238316dc1..0e8dad322 100644--- a/tools/check-live-asset-rebind.mjs+++ b/tools/check-live-asset-rebind.mjs@@ -21,10 +21,12 @@* what it takes out of the ledger is a row nobody can give back — that is* the leak the rebinder had, one row per successful hot update.* 4. The runtime scene loader hands the scene its receipts, not its paths.+ * 5. A loader holding a texture past its own load() acquires it, for the same+ * reason: it releases at unload, by which time the path may name two eras.** Run: node tools/check-live-asset-rebind.mjs (exit 1 on violation)*/-import { readFileSync, existsSync } from 'node:fs';+import { readFileSync, readdirSync, existsSync } from 'node:fs';import path from 'node:path';import { fileURLToPath } from 'node:url';@@ -146,6 +148,17 @@ if (!/\bpreloadSceneAssets\(/.test(loader)) {}}+// The same rule one layer down: a loader that keeps a texture releases it at+// unload, which is exactly when a path has stopped naming one instance.+const LOADERS = path.join(ROOT, 'sdk/src/asset/loaders');+for (const name of readdirSync(LOADERS).filter((f) => f.endsWith('.ts'))) {+ const code = stripComments(readFileSync(path.join(LOADERS, name), 'utf8'));+ const call = /\bctx\.releaseTexture\s*\(/.exec(code);+ if (call) {+ findings.push(`sdk/src/asset/loaders/${name}:${code.slice(0, call.index).split('\n').length} gives a held texture back by PATH — keep the receipt acquireTexture hands you.`);+ }+}+if (findings.length === 0) {console.log(`check-live-asset-rebind: the rebind path names none of the ${components.size} asset-bearing components, reads the declaration, and the scene loader hands over receipts.`);process.exit(0);