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
refactor: simplify Assets architecture based on code review
esengined1f7e3fa3edd
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex 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.tsindex 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.tsindex 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.tsindex 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);