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(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.ts
index 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 Team
import 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.mjs
index 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);