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.

refactor: simplify Assets architecture based on code review

esengined1f7e3fa3edd
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index befe43334..dbb200679 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -21,9 +21,8 @@ import { PrefabAssetLoader } from './loaders/PrefabAssetLoader';
import type { SpineModuleController } from '../spine/SpineController';
import {
getAssetFields, getCompoundAssetFields,
- initBuiltinAssetFields,
} from './AssetFieldRegistry';
-import type { SceneData, SceneEntityData } from '../scene';
+import type { SceneData } from '../scene';
import { SceneHandle, type ReleaseCallback } from './SceneHandle';
export interface AssetsOptions {
@@ -58,6 +57,7 @@ export class Assets {
private textureCache_ = new AsyncCache<TextureResult>();
private textureRefCounts_ = new Map<string, number>();
private genericCache_ = new Map<string, AsyncCache<unknown>>();
+ private loadContext_: LoadContext | null = null;
private constructor(options: AssetsOptions) {
this.backend = options.backend;
@@ -92,9 +92,9 @@ export class Assets {
async loadTexture(ref: string): Promise<TextureResult> {
const path = this.catalog.resolve(ref);
- const cacheKey = `${path}:f`;
+ const cacheKey = this.textureCacheKey_(path, true);
const result = await this.textureCache_.getOrLoad(cacheKey, () =>
- this.textureLoader_.load(path, this.createLoadContext()),
+ this.textureLoader_.load(path, this.getLoadContext_()),
);
this.textureRefCounts_.set(cacheKey, (this.textureRefCounts_.get(cacheKey) ?? 0) + 1);
return result;
@@ -102,9 +102,9 @@ export class Assets {
async loadTextureRaw(ref: string): Promise<TextureResult> {
const path = this.catalog.resolve(ref);
- const cacheKey = `${path}:n`;
+ const cacheKey = this.textureCacheKey_(path, false);
const result = await this.textureCache_.getOrLoad(cacheKey, () =>
- this.textureLoader_.loadRaw(path, this.createLoadContext()),
+ this.textureLoader_.loadRaw(path, this.getLoadContext_()),
);
this.textureRefCounts_.set(cacheKey, (this.textureRefCounts_.get(cacheKey) ?? 0) + 1);
return result;
@@ -112,16 +112,17 @@ export class Assets {
getTexture(ref: string): TextureResult | undefined {
const path = this.catalog.resolve(ref);
- return this.textureCache_.get(`${path}:f`);
+ return this.textureCache_.get(this.textureCacheKey_(path, true));
}
async loadSpine(skeletonRef: string, atlasRef?: string): Promise<SpineResult> {
const skelPath = this.catalog.resolve(skeletonRef);
+ const ctx = this.getLoadContext_();
if (atlasRef) {
const atlasPath = this.catalog.resolve(atlasRef);
- return this.spineLoader_.loadWithAtlas(skelPath, atlasPath, this.createLoadContext());
+ return this.spineLoader_.loadWithAtlas(skelPath, atlasPath, ctx);
}
- return this.spineLoader_.load(skelPath, this.createLoadContext());
+ return this.spineLoader_.load(skelPath, ctx);
}
async loadMaterial(ref: string): Promise<MaterialResult> {
@@ -287,72 +288,40 @@ export class Assets {
const fontHandles = new Map<string, number>();
const releaseCallbacks: ReleaseCallback[] = [];
- const promises: Promise<void>[] = [];
-
- for (const path of texturePaths) {
- promises.push(
- this.loadTexture(path).then(r => {
- textureHandles.set(path, r.handle);
- }).catch(e => {
- console.warn(`[Assets] Failed to load texture: ${path}`, e);
- textureHandles.set(path, 0);
+ const loadHandles = (
+ paths: Set<string>, loader: (p: string) => Promise<{ handle: number }>,
+ handles: Map<string, number>, label: string,
+ ): Promise<void>[] =>
+ [...paths].map(path =>
+ loader(path).then(r => { handles.set(path, r.handle); }).catch(e => {
+ console.warn(`[Assets] Failed to load ${label}: ${path}`, e);
+ handles.set(path, 0);
}),
);
- }
- for (const path of materialPaths) {
- promises.push(
- this.loadMaterial(path).then(r => {
- materialHandles.set(path, r.handle);
- }).catch(e => {
- console.warn(`[Assets] Failed to load material: ${path}`, e);
- materialHandles.set(path, 0);
+ const loadFireAndForget = (
+ paths: Set<string>, loader: (p: string) => Promise<unknown>, label: string,
+ ): Promise<void>[] =>
+ [...paths].map(path =>
+ loader(path).then(() => {}).catch(e => {
+ console.warn(`[Assets] Failed to load ${label}: ${path}`, e);
}),
);
- }
- for (const path of fontPaths) {
- promises.push(
- this.loadFont(path).then(r => {
- fontHandles.set(path, r.handle);
- }).catch(e => {
- console.warn(`[Assets] Failed to load font: ${path}`, e);
- fontHandles.set(path, 0);
- }),
- );
- }
-
- for (const pair of spinePairs) {
- promises.push(
+ const promises: Promise<void>[] = [
+ ...loadHandles(texturePaths, p => this.loadTexture(p), textureHandles, 'texture'),
+ ...loadHandles(materialPaths, p => this.loadMaterial(p), materialHandles, 'material'),
+ ...loadHandles(fontPaths, p => this.loadFont(p), fontHandles, 'font'),
+ ...spinePairs.map(pair =>
this.loadSpine(pair.skeleton, pair.atlas).then(() => {}).catch(e => {
console.warn(`[Assets] Failed to load spine: ${pair.skeleton}`, e);
}),
- );
- }
-
- for (const path of animClipPaths) {
- promises.push(this.loadAnimClip(path).then(() => {}).catch(e => {
- console.warn(`[Assets] Failed to load anim clip: ${path}`, e);
- }));
- }
-
- for (const path of tilemapPaths) {
- promises.push(this.loadTilemap(path).then(() => {}).catch(e => {
- console.warn(`[Assets] Failed to load tilemap: ${path}`, e);
- }));
- }
-
- for (const path of timelinePaths) {
- promises.push(this.loadTimeline(path).then(() => {}).catch(e => {
- console.warn(`[Assets] Failed to load timeline: ${path}`, e);
- }));
- }
-
- for (const path of audioPaths) {
- promises.push(this.loadAudio(path).then(() => {}).catch(e => {
- console.warn(`[Assets] Failed to load audio: ${path}`, e);
- }));
- }
+ ),
+ ...loadFireAndForget(animClipPaths, p => this.loadAnimClip(p), 'anim-clip'),
+ ...loadFireAndForget(tilemapPaths, p => this.loadTilemap(p), 'tilemap'),
+ ...loadFireAndForget(timelinePaths, p => this.loadTimeline(p), 'timeline'),
+ ...loadFireAndForget(audioPaths, p => this.loadAudio(p), 'audio'),
+ ];
await Promise.all(promises);
@@ -397,8 +366,8 @@ export class Assets {
releaseTexture(ref: string): void {
const path = this.catalog.resolve(ref);
- for (const suffix of [':f', ':n']) {
- const key = path + suffix;
+ for (const flip of [true, false]) {
+ const key = this.textureCacheKey_(path, flip);
const count = this.textureRefCounts_.get(key);
if (count === undefined) continue;
@@ -428,6 +397,7 @@ export class Assets {
this.textureRefCounts_.clear();
this.spineLoader_.releaseAll();
+ this.materialLoader_?.releaseAll();
for (const cache of this.genericCache_.values()) {
cache.clearAll();
@@ -455,10 +425,13 @@ export class Assets {
// Private
// =========================================================================
+ private materialLoader_: MaterialAssetLoader | null = null;
+
private registerBuiltinLoaders(): void {
this.register(this.textureLoader_);
this.register(this.spineLoader_);
- this.register(new MaterialAssetLoader());
+ this.materialLoader_ = new MaterialAssetLoader();
+ this.register(this.materialLoader_);
this.register(new FontAssetLoader());
this.register(new AudioAssetLoader());
this.register(new AnimClipAssetLoader());
@@ -467,6 +440,10 @@ export class Assets {
this.register(new PrefabAssetLoader());
}
+ private textureCacheKey_(path: string, flip: boolean): string {
+ return `${path}:${flip ? 'f' : 'n'}`;
+ }
+
private async loadTyped<T>(type: string, ref: string): Promise<T> {
const loader = this.loaders_.get(type) as AssetLoader<T> | undefined;
if (!loader) {
@@ -481,13 +458,14 @@ export class Assets {
}
return cache.getOrLoad(path, () =>
- loader.load(path, this.createLoadContext()),
+ loader.load(path, this.getLoadContext_()),
) as Promise<T>;
}
- private createLoadContext(): LoadContext {
+ private getLoadContext_(): LoadContext {
+ if (this.loadContext_) return this.loadContext_;
const self = this;
- return {
+ this.loadContext_ = {
backend: this.backend,
catalog: this.catalog,
resourceManager: requireResourceManager() as CppResourceManager,
@@ -504,5 +482,6 @@ export class Assets {
return self.backend.fetchBinary(self.backend.resolveUrl(path));
},
};
+ return this.loadContext_;
}
}
diff --git a/sdk/src/asset/loaders/MaterialAssetLoader.ts b/sdk/src/asset/loaders/MaterialAssetLoader.ts
index ee2366e3d..d6fcca462 100644
--- a/sdk/src/asset/loaders/MaterialAssetLoader.ts
+++ b/sdk/src/asset/loaders/MaterialAssetLoader.ts
@@ -6,12 +6,12 @@ import { AsyncCache } from '../AsyncCache';
const ES_SHADER_VERTEX_RE = /#pragma\s+vertex\s*([\s\S]*?)#pragma\s+end/;
const ES_SHADER_FRAGMENT_RE = /#pragma\s+fragment\s*([\s\S]*?)#pragma\s+end/;
-const shaderCache = new AsyncCache<ShaderHandle>();
-
export class MaterialAssetLoader implements AssetLoader<MaterialResult> {
readonly type = 'material';
readonly extensions = ['.esmaterial'];
+ private shaderCache_ = new AsyncCache<ShaderHandle>();
+
async load(path: string, ctx: LoadContext): Promise<MaterialResult> {
const buildPath = ctx.catalog.getBuildPath(path);
const text = await ctx.loadText(buildPath);
@@ -32,11 +32,15 @@ export class MaterialAssetLoader implements AssetLoader<MaterialResult> {
Material.release(asset.handle);
}
+ releaseAll(): void {
+ this.shaderCache_.clearAll();
+ }
+
private async loadShader(path: string, ctx: LoadContext): Promise<ShaderHandle> {
- const cached = shaderCache.get(path);
+ const cached = this.shaderCache_.get(path);
if (cached !== undefined) return cached;
- return shaderCache.getOrLoad(path, async () => {
+ return this.shaderCache_.getOrLoad(path, async () => {
const buildPath = ctx.catalog.getBuildPath(path);
const content = await ctx.loadText(buildPath);
const vertexMatch = content.match(ES_SHADER_VERTEX_RE);
diff --git a/sdk/src/asset/loaders/SpineAssetLoader.ts b/sdk/src/asset/loaders/SpineAssetLoader.ts
index 8ba77342d..5385eb9c3 100644
--- a/sdk/src/asset/loaders/SpineAssetLoader.ts
+++ b/sdk/src/asset/loaders/SpineAssetLoader.ts
@@ -50,22 +50,20 @@ export class SpineAssetLoader implements AssetLoader<SpineResult> {
const atlasDir = atlasPath.substring(0, atlasPath.lastIndexOf('/'));
const rm = requireResourceManager();
- const loadedTextures: { name: string; handle: number; width: number; height: number }[] = [];
- for (const texName of texNames) {
+ const texPromises = texNames.map(async (texName) => {
const texPath = atlasDir ? `${atlasDir}/${texName}` : texName;
try {
const texResult = await ctx.loadTexture(texPath, false);
rm.registerTextureWithPath(texResult.handle, texPath);
- loadedTextures.push({
- name: texName,
- handle: texResult.handle,
- width: texResult.width,
- height: texResult.height,
- });
+ return { name: texName, handle: texResult.handle, width: texResult.width, height: texResult.height };
} catch (err) {
console.warn(`[SpineLoader] Failed to load texture: ${texPath}`, err);
+ return null;
}
- }
+ });
+ const loadedTextures = (await Promise.all(texPromises)).filter(
+ (t): t is { name: string; handle: number; width: number; height: number } => t !== null,
+ );
const skelBuildPath = ctx.catalog.getBuildPath(skeletonPath);
const isBinary = getAssetTypeEntry(skeletonPath)?.contentType === 'binary';
diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.ts
index ee2085bb1..d91996ec6 100644
--- a/sdk/src/asset/loaders/TextureLoader.ts
+++ b/sdk/src/asset/loaders/TextureLoader.ts
@@ -8,15 +8,20 @@ export class TextureLoader implements AssetLoader<TextureResult> {
readonly extensions = ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp'];
private module_: ESEngineModule;
- private canvas_: HTMLCanvasElement | OffscreenCanvas;
- private ctx_: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+ private canvas_: HTMLCanvasElement | OffscreenCanvas | null = null;
+ private ctx_: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null = null;
constructor(module: ESEngineModule) {
this.module_ = module;
+ }
+
+ private ensureCanvas_(): { canvas: HTMLCanvasElement | OffscreenCanvas; ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D } {
+ if (this.canvas_ && this.ctx_) return { canvas: this.canvas_, ctx: this.ctx_ };
this.canvas_ = platformCreateCanvas(256, 256);
const ctx = this.canvas_.getContext('2d', { willReadFrequently: true });
if (!ctx) throw new Error('TextureLoader: failed to create 2D context');
this.ctx_ = ctx;
+ return { canvas: this.canvas_, ctx: this.ctx_ };
}
async load(path: string, ctx: LoadContext): Promise<TextureResult> {
@@ -127,13 +132,12 @@ export class TextureLoader implements AssetLoader<TextureResult> {
img: HTMLImageElement | ImageBitmap,
width: number, height: number, flip: boolean,
): TextureResult {
- const canvas = this.canvas_;
+ const { canvas, ctx } = this.ensureCanvas_();
if (canvas.width < width || canvas.height < height) {
canvas.width = Math.max(canvas.width, nextPowerOf2(width));
canvas.height = Math.max(canvas.height, nextPowerOf2(height));
}
- const ctx = this.ctx_ as CanvasRenderingContext2D;
ctx.clearRect(0, 0, canvas.width, canvas.height);
ctx.drawImage(img, 0, 0);