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(runtime): fold eager scene loading into the single Assets channel
yhhba407fceedc1
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex 235949504..6567253a8 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -469,7 +469,7 @@ export class Assets {async preloadSceneAssets(sceneData: SceneData,onProgress?: (loaded: number, total: number) => void,- options?: { readonly maxConcurrent?: number },+ options?: { readonly maxConcurrent?: number; readonly skipSpine?: boolean },): Promise<SceneAssetResult> {const missing: MissingAsset[] = [];const discovered = discoverSceneAssets(sceneData, (ref) => this.resolveRef(ref));@@ -544,13 +544,18 @@ export class Assets {pushHandleLoad(texturePaths, p => this.loadTexture(p), textureHandles, 'texture');pushHandleLoad(materialPaths, p => this.loadMaterial(p), materialHandles, 'material');pushHandleLoad(fontPaths, p => this.loadFont(p), fontHandles, 'font');- for (const pair of spinePairs) {- tasks.push(() =>- this.loadSpine(pair.skeleton, pair.atlas).then(() => {}).catch(e => {- log.warn('asset', `Failed to load spine: ${pair.skeleton}`, e);- recordFailure(pair.skeleton, 'spine', e);- }),- );+ // The runtime scene loader owns spine as a two-phase load+apply through the+ // SpineManager (skeletons must bind to spawned entities); it opts out here so+ // spine page textures / virtual-FS writes aren't done twice.+ if (!options?.skipSpine) {+ for (const pair of spinePairs) {+ tasks.push(() =>+ this.loadSpine(pair.skeleton, pair.atlas).then(() => {}).catch(e => {+ log.warn('asset', `Failed to load spine: ${pair.skeleton}`, e);+ recordFailure(pair.skeleton, 'spine', e);+ }),+ );+ }}pushFireAndForget(animClipPaths, p => this.loadAnimClip(p), 'anim-clip');pushFireAndForget(tilemapPaths, p => this.loadTilemap(p), 'tilemap');diff --git a/sdk/src/asset/ProviderBackend.ts b/sdk/src/asset/ProviderBackend.tsnew file mode 100644index 000000000..28d715cf6--- /dev/null+++ b/sdk/src/asset/ProviderBackend.ts@@ -0,0 +1,38 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file ProviderBackend.ts+ * @brief Adapts a RuntimeAssetProvider to the canonical `Backend` interface so+ * the runtime scene loader can drive the single `Assets` channel with a+ * platform's existing fetch (WeChat filesystem / `estella://` / inlined+ * data-URLs) instead of a parallel per-type loader implementation.+ *+ * The provider already resolves refs internally (`readText/readBinary` call+ * `resolvePath`), and `resolvePath` is idempotent across all providers, so it is+ * safe to feed an already-resolved path back through these methods.+ */+import type { Backend } from './Backend';+import type { RuntimeAssetProvider } from '../runtimeAssets';++export class ProviderBackend implements Backend {+ constructor(private readonly provider: RuntimeAssetProvider) {}++ async fetchBinary(path: string): Promise<ArrayBuffer> {+ const view = await this.provider.readBinary(path);+ // Return a standalone ArrayBuffer of exactly these bytes. A provider may+ // hand back a Uint8Array that views into a larger/pooled buffer; the asset+ // loaders assume the whole buffer is the asset.+ if (view.byteOffset === 0 && view.byteLength === view.buffer.byteLength) {+ return view.buffer as ArrayBuffer;+ }+ return view.slice().buffer as ArrayBuffer;+ }++ async fetchText(path: string): Promise<string> {+ return this.provider.readText(path);+ }++ resolveUrl(path: string): string {+ return this.provider.resolvePath(path);+ }+}diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.tsindex ee87c1ad3..48755092e 100644--- a/sdk/src/asset/loaders/TextureLoader.ts+++ b/sdk/src/asset/loaders/TextureLoader.ts@@ -7,6 +7,19 @@ import { requireResourceManager } from '../../resourceManager';import type { ESEngineModule } from '../../wasm';import { withMalloc } from '../../wasmScratch';import { isKtx2, loadCompressedTexture, type BasisTranscoder } from '../compressed';+import { createTextureFromPixels, type TextureParams } from '../../runtimeAssets';++/**+ * Decode a texture ref to raw RGBA pixels on the current platform. Set by a+ * caller that fetches through a channel `TextureLoader`'s URL-based `<img>`+ * decode can't reach — e.g. the runtime scene loader, whose asset providers+ * pre-decode from `estella://` / WeChat package files / inlined data-URLs. When+ * set, non-KTX2 textures upload through this instead of `loadImage(url)`.+ */+export type TexturePixelDecoder = (+ path: string,+ flip: boolean,+) => Promise<{ width: number; height: number; pixels: Uint8Array }>;/*** Texture import-time settings. Applied when the GL texture is first uploaded,@@ -72,6 +85,11 @@ export class TextureLoader implements AssetLoader<TextureResult> {private pendingSettings_: TextureImportSettings | undefined;setPendingSettings(s: TextureImportSettings | undefined): void { this.pendingSettings_ = s; }+ /** Platform pixel decoder (see {@link TexturePixelDecoder}). Null ⇒ the+ * default URL `<img>` decode path (editor / app Assets, unchanged). */+ private pixelDecoder_: TexturePixelDecoder | null = null;+ setPixelDecoder(decoder: TexturePixelDecoder | null): void { this.pixelDecoder_ = decoder; }+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);@@ -115,6 +133,15 @@ export class TextureLoader implements AssetLoader<TextureResult> {if (path.toLowerCase().endsWith('.ktx2')) {return this.loadCompressed(path, ctx, settings);}+ // A platform pixel decoder (runtime scene loader) pre-decodes to RGBA and+ // uploads through the shared createTexture path — the same code the old+ // runtimeLoader.loadTextures used — instead of a URL-based <img>.+ if (this.pixelDecoder_) {+ const result = await this.pixelDecoder_(path, flip);+ const params: TextureParams = { filterMode: settings?.filter, wrapMode: settings?.wrap };+ const handle = createTextureFromPixels(this.module_, result, flip, params);+ return { handle, width: result.width, height: result.height };+ }const url = ctx.backend.resolveUrl(ctx.catalog.getBuildPath(path));const img = await this.loadImage(url, flip);return this.createTextureFromImage(img, flip, settings);diff --git a/sdk/src/runtimeLoader.ts b/sdk/src/runtimeLoader.tsindex 24bbb2b97..14b3d79b3 100644--- a/sdk/src/runtimeLoader.ts+++ b/sdk/src/runtimeLoader.ts@@ -6,9 +6,8 @@*/import { SceneOwner } from './component';-import { Material } from './material';-import { loadSceneData, getComponentAssetFieldDescriptors, type AssetFieldType, type SceneData } from './scene';-import { discoverSceneAssets, getAssetPathsByType } from './asset/discoverAssets';+import { loadSceneData, updateCameraAspectRatio, type SceneData } from './scene';+import { discoverSceneAssets } from './asset/discoverAssets';import type { ESEngineModule } from './wasm';import type { SpineWasmModule } from './spine/SpineModuleLoader';import { SpineManager } from './spine/SpineManager';@@ -16,22 +15,19 @@ import type { PhysicsWasmModule } from './physics/PhysicsModuleLoader';import { PhysicsPlugin, type PhysicsPluginConfig } from './physics/PhysicsPlugin';import { SpinePlugin } from './spine/SpinePlugin';import type { App } from './app';-import { Assets } from './asset/AssetPlugin';-import { getAssetTypeEntry } from './assetTypes';+import { Assets as AssetsClass } from './asset/Assets';+import { ProviderBackend } from './asset/ProviderBackend';+import { initBuiltinAssetFields } from './asset/AssetFieldRegistry';+import type { TextureImportSettings } from './asset/loaders/TextureLoader';import { SceneManager, type SceneConfig } from './sceneManager';import { DEFAULT_GRAVITY, DEFAULT_FIXED_TIMESTEP } from './defaults';-import { type AnimClipAssetData, extractAnimClipTexturePaths, parseAnimClipData } from './animation/AnimClipLoader';import { SpriteAnimation } from './animation/SpriteAnimator';import { Audio } from './audio/Audio';import { flushPendingSystems } from './app';-import { updateCameraAspectRatio } from './scene';import { requireResourceManager } from './resourceManager';-import { parseTmjJson, resolveRelativePath } from './tilemap/tiledLoader';-import { registerTilemapSource } from './tilemap/tilesetCache';import { log } from './logger';-import { createTextureFromPixels, type RuntimeAssetProvider, type TextureParams } from './runtimeAssets';+import { type RuntimeAssetProvider, type TextureParams } from './runtimeAssets';import { loadSpineAssets, applySpineEntities } from './spine/loadSpineScene';-import { loadCompressedTexture, type CompressedUploadOptions, type BasisTranscoder } from './asset/compressed';import { transcoderFromModule, type BasisWasmModule } from './asset/basisTranscoder';// =============================================================================@@ -43,308 +39,81 @@ import { transcoderFromModule, type BasisWasmModule } from './asset/basisTranscoexport type { RuntimeAssetProvider } from './runtimeAssets';// =============================================================================-// Texture Helpers+// Scene-local Assets channel// =============================================================================-async function loadTextures(- module: ESEngineModule,- sceneData: SceneData,- provider: RuntimeAssetProvider,- texturePaths: Set<string>,- transcoder: BasisTranscoder | null,-): Promise<Record<string, number>> {- const cache: Record<string, number> = {};- const texSettings = (sceneData as any).textureImporterSettings as Record<string, TextureParams> | undefined;- const gl = transcoder ? getWebGL2(module) : null;- for (const ref of texturePaths) {- try {- const params = texSettings?.[ref];- // KTX2 stays GPU-compressed in VRAM: decode to a device format- // through the SAME compressed.ts core the editor TextureLoader uses, so- // both paths agree by construction. Non-KTX2 keeps the RGBA upload.- if (transcoder && gl && provider.resolvePath(ref).toLowerCase().endsWith('.ktx2')) {- const bytes = await provider.readBinary(ref);- const r = loadCompressedTexture(gl, module, transcoder, new Uint8Array(bytes), compressedOpts(params));- cache[ref] = r.handle;- } else {- const pixelData = await provider.loadPixels(ref);- cache[ref] = createTextureFromPixels(module, pixelData, true, params);- }- } catch (e) {- log.warn('runtime', `Failed to load texture: ${ref}`, e);- cache[ref] = 0;+/**+ * Build a scene-local `Assets` that loads this realm's scene through the single+ * canonical asset channel, driven by the realm's `RuntimeAssetProvider`:+ * - fetch (text/binary, incl. KTX2 containers) → `ProviderBackend`+ * - texture pixels → the provider's platform decoder (handles `estella://` /+ * WeChat package files / inlined data-URLs that a URL `<img>` can't)+ * - KTX2 transcode → the same self-gating Basis side-module the editor wires+ * The provider's `resolvePath` is the single ref resolver, so refs resolve to+ * their real (extension-bearing) build paths before KTX2 detection and fetch.+ * No ref counter / catalog is attached (parity with the old runtime loader,+ * which tracked neither and applied no atlas-frame indirection).+ */+function createSceneAssets(+ app: App, module: ESEngineModule, provider: RuntimeAssetProvider, sceneData: SceneData,+): AssetsClass {+ initBuiltinAssetFields();+ const assets = AssetsClass.create({+ backend: new ProviderBackend(provider),+ module,+ getAudio: () => (app.hasResource(Audio) ? app.getResource(Audio) : null),+ getSpriteAnimation: () => (app.hasResource(SpriteAnimation) ? app.getResource(SpriteAnimation) : null),+ });+ assets.setAssetRefResolver((ref) => provider.resolvePath(ref));++ const loader = assets.getTextureLoader();+ loader.setPixelDecoder((path, flip) =>+ flip ? provider.loadPixels(path) : (provider.loadPixelsRaw?.(path) ?? provider.loadPixels(path)),+ );+ // KTX2 transcoder, self-gated off app.sideModules — identical wiring to+ // AssetPlugin.build so eager + on-demand loads transcode the same way.+ loader.setTranscoderProvider(async () => {+ const host = app.sideModules;+ if (!host) return null;+ const mod = await host.acquire('basis');+ return mod ? transcoderFromModule(mod as unknown as BasisWasmModule) : null;+ });++ // Per-texture import settings (filter/wrap) keyed by the scene's stored ref:+ // normalize keys through resolvePath so they match the resolved path the+ // TextureLoader sees, and map the stored {filterMode,wrapMode} shape to the+ // loader's {filter,wrap}.+ const rawSettings = (sceneData as { textureImporterSettings?: Record<string, TextureParams> })+ .textureImporterSettings;+ if (rawSettings) {+ const resolved: Record<string, TextureImportSettings> = {};+ for (const [ref, s] of Object.entries(rawSettings)) {+ resolved[provider.resolvePath(ref)] = {+ filter: s.filterMode as TextureImportSettings['filter'],+ wrap: s.wrapMode as TextureImportSettings['wrap'],+ };}+ assets.setTextureImportSettingsResolver((ref) => resolved[ref]);}- return cache;-}--/** WebGL2 context the emscripten module renders into (for JS-side compressed- * uploads via gl.compressedTexImage2D), or null. */-function getWebGL2(module: ESEngineModule): WebGL2RenderingContext | null {- try {- const ctx = (module.GL as any)?.currentContext?.GLctx;- return (typeof WebGL2RenderingContext !== 'undefined' && ctx instanceof WebGL2RenderingContext) ? ctx : null;- } catch { return null; }-}-/** Map runtime TextureParams (filterMode/wrapMode) → compressed upload options. */-function compressedOpts(params?: TextureParams): CompressedUploadOptions {- const filter = params?.filterMode === 'nearest' ? 'nearest' : 'linear';- const wrap = params?.wrapMode === 'repeat' ? 'repeat' : params?.wrapMode === 'mirror' ? 'mirror' : 'clamp';- return { filter, wrap };-}--/** Acquire the Basis transcoder iff the scene uses any KTX2 texture — self-gating- * off app.sideModules, the same way physics/spine acquire their modules. */-async function acquireBasisIfNeeded(- app: App, provider: RuntimeAssetProvider, texturePaths: Set<string>,-): Promise<BasisTranscoder | null> {- if (!app.sideModules) return null;- let needs = false;- for (const ref of texturePaths) {- if (provider.resolvePath(ref).toLowerCase().endsWith('.ktx2')) { needs = true; break; }- }- if (!needs) return null;- const mod = await app.sideModules.acquire('basis');- return mod ? transcoderFromModule(mod as unknown as BasisWasmModule) : null;+ return assets;}+/** Apply 9-slice borders to loaded textures. `textureHandles` is keyed by the+ * resolved build path (Assets discovery resolves refs), so the metadata's+ * stored ref is resolved the same way before lookup. */function applyTextureMetadata(sceneData: SceneData,- textureCache: Record<string, number>,+ textureHandles: Map<string, number>,+ resolveRef: (ref: string) => string,): void {if (!sceneData.textureMetadata) return;const rm = requireResourceManager();- for (const ref in sceneData.textureMetadata) {- const handle = textureCache[ref];- if (handle) {- const metadata = sceneData.textureMetadata[ref];- if (metadata?.sliceBorder) {- const b = metadata.sliceBorder;- rm.setTextureMetadata(handle, b.left, b.right, b.top, b.bottom);- }- }- }-}--function resolveSceneAssetPaths(- sceneData: SceneData,- textureCache: Record<string, number>,- fontCache: Record<string, number>,- materialCache: Record<string, number>,-): void {- const cacheByType: Partial<Record<AssetFieldType, Record<string, number>>> = {- texture: textureCache,- material: materialCache,- font: fontCache,- };- for (const entity of sceneData.entities) {- for (const comp of entity.components) {- const descriptors = getComponentAssetFieldDescriptors(comp.type);- if (descriptors.length === 0) continue;-- const data = comp.data as Record<string, unknown>;- for (const desc of descriptors) {- const cache = cacheByType[desc.type];- if (cache && typeof data[desc.field] === 'string') {- data[desc.field] = cache[data[desc.field] as string] || 0;- }- }- }- }-}--// =============================================================================-// BitmapFont Helpers-// =============================================================================--async function loadBitmapFonts(- module: ESEngineModule,- provider: RuntimeAssetProvider,- fontPaths: Set<string>,-): Promise<Record<string, number>> {- const cache: Record<string, number> = {};- for (const ref of fontPaths) {- if (cache[ref] !== undefined) continue;- try {- let fntContent: string;- let fntDir: string;-- const fontEntry = getAssetTypeEntry(ref);- if (fontEntry?.editorType === 'bitmap-font' && fontEntry.contentType === 'json') {- const json = JSON.parse(await provider.readText(ref));- const fntFile = json.type === 'label-atlas' ? json.generatedFnt : json.fntFile;- if (!fntFile) { cache[ref] = 0; continue; }- const dir = ref.substring(0, ref.lastIndexOf('/'));- const fntRef = dir ? `${dir}/${fntFile}` : fntFile;- fntContent = await provider.readText(fntRef);- fntDir = fntRef.substring(0, fntRef.lastIndexOf('/'));- } else {- fntContent = await provider.readText(ref);- fntDir = ref.substring(0, ref.lastIndexOf('/'));- }-- const pageMatch = fntContent.match(/file="([^"]+)"/);- if (!pageMatch) { cache[ref] = 0; continue; }-- const texRef = fntDir ? `${fntDir}/${pageMatch[1]}` : pageMatch[1];- const pixels = provider.loadPixelsRaw- ? await provider.loadPixelsRaw(texRef)- : await provider.loadPixels(texRef);- const texHandle = createTextureFromPixels(module, pixels, false);-- const rm = requireResourceManager();- cache[ref] = rm.loadBitmapFont(fntContent, texHandle, pixels.width, pixels.height);- } catch (e) {- log.warn('runtime', `Failed to load bitmap font: ${ref}`, e);- cache[ref] = 0;- }- }- return cache;-}--// =============================================================================-// Material Helpers-// =============================================================================--async function loadMaterials(- provider: RuntimeAssetProvider,- materialPaths: Set<string>,-): Promise<Record<string, number>> {- const materialCache: Record<string, number> = {};- const shaderCache: Record<string, number> = {};- for (const matRef of materialPaths) {- if (materialCache[matRef] !== undefined) continue;- try {- const matData = JSON.parse(await provider.readText(matRef));- if (!matData.vertexSource || !matData.fragmentSource) {- materialCache[matRef] = 0;- continue;- }- const shaderKey = matData.vertexSource + matData.fragmentSource;- let shaderHandle = shaderCache[shaderKey];- if (!shaderHandle) {- shaderHandle = Material.createShader(matData.vertexSource, matData.fragmentSource);- shaderCache[shaderKey] = shaderHandle;- }- materialCache[matRef] = Material.createFromAsset(matData, shaderHandle);- } catch (e) {- log.warn('runtime', `Failed to load material: ${matRef}`, e);- materialCache[matRef] = 0;- }- }- return materialCache;-}--// =============================================================================-// Audio Helpers-// =============================================================================--async function preloadAudioClips(app: App, provider: RuntimeAssetProvider, audioPaths: Set<string>): Promise<void> {- if (audioPaths.size === 0) return;- if (!app.hasResource(Audio)) {- log.warn('runtime', 'No Audio resource; skipping audio preload (AudioPlugin not installed?)');- return;- }- const audio = app.getResource(Audio);-- const paths = [...audioPaths];-- if (provider) {- await Promise.all(paths.map(async (path) => {- try {- const binary = await provider.readBinary(path);- await audio.preloadFromData(path, binary.buffer as ArrayBuffer);- } catch (err) {- log.warn('runtime', `Failed to preload audio: ${path}`, err);- }- }));- } else {- await audio.preloadAll(paths).catch(err => {- log.warn('runtime', 'Failed to preload audio assets', err);- });- }-}--// =============================================================================-// Anim-Clip Helpers-// =============================================================================--async function loadAnimClips(- app: App,- module: ESEngineModule,- provider: RuntimeAssetProvider,- animClipPaths: Set<string>,-): Promise<void> {- const anim = app.hasResource(SpriteAnimation) ? app.getResource(SpriteAnimation) : null;- for (const clipPath of animClipPaths) {- try {- const clipText = await provider.readText(clipPath);- const clipData: AnimClipAssetData = JSON.parse(clipText);- const texturePaths = extractAnimClipTexturePaths(clipData);- const textureHandles = new Map<string, number>();-- for (const texPath of texturePaths) {- try {- const result = await provider.loadPixels(texPath);- textureHandles.set(texPath, createTextureFromPixels(module, result));- } catch (e) {- log.warn('runtime', `Failed to load anim texture: ${texPath}`, e);- textureHandles.set(texPath, 0);- }- }-- const clip = parseAnimClipData(clipPath, clipData, textureHandles);- anim?.registerClip(clip);- } catch (err) {- log.warn('runtime', `Failed to load animation clip: ${clipPath}`, err);- }- }-}--// =============================================================================-// Tilemap Helpers-// =============================================================================--async function loadTilemaps(- module: ESEngineModule,- provider: RuntimeAssetProvider,- tilemapPaths: Set<string>,-): Promise<void> {- for (const tmjPath of tilemapPaths) {- try {- const jsonText = await provider.readText(tmjPath);- const mapData = parseTmjJson(JSON.parse(jsonText));- if (!mapData) continue;-- const tilesets = [];- for (const ts of mapData.tilesets) {- const imagePath = resolveRelativePath(tmjPath, ts.image);- let textureHandle = 0;- try {- const result = await provider.loadPixels(imagePath);- textureHandle = createTextureFromPixels(module, result);- } catch (e) {- log.warn('runtime', `Failed to load tileset texture: ${imagePath}`, e);- }- tilesets.push({ textureHandle, columns: ts.columns, firstId: ts.firstGid });- }-- registerTilemapSource(tmjPath, {- tileWidth: mapData.tileWidth,- tileHeight: mapData.tileHeight,- layers: mapData.layers.map(l => ({- name: l.name,- width: l.width,- height: l.height,- tiles: l.tiles,- chunks: l.chunks ?? [],- infinite: l.infinite ?? false,- })),- tilesets,- });- } catch (err) {- log.warn('runtime', `Failed to load tilemap: ${tmjPath}`, err);+ for (const [ref, metadata] of Object.entries(sceneData.textureMetadata)) {+ const handle = textureHandles.get(resolveRef(ref));+ if (handle && metadata?.sliceBorder) {+ const b = metadata.sliceBorder;+ rm.setTextureMetadata(handle, b.left, b.right, b.top, b.bottom);}}}@@ -401,12 +170,18 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis// wins for headless/tests.const spineManager = options.spineManager ?? app.getPlugin(SpinePlugin)?.spineManager ?? null;+ // Spine pairs (raw refs) for the two-phase spine load+apply below; every+ // other asset type loads through the single canonical Assets channel.const discovered = discoverSceneAssets(sceneData);- const texturePaths = getAssetPathsByType(discovered, 'texture');- const transcoder = await acquireBasisIfNeeded(app, provider, texturePaths);- const textureCache = await loadTextures(module, sceneData, provider, texturePaths, transcoder);- applyTextureMetadata(sceneData, textureCache);+ // Eager scene assets (textures / fonts / materials / anim-clips / tilemaps /+ // audio) load through the single canonical Assets channel — one per-type+ // loader implementation, shared with the editor — driven by this realm's+ // provider. Spine stays a two-phase load+apply below (skipSpine).+ const sceneAssets = createSceneAssets(app, module, provider, sceneData);+ const assetResult = await sceneAssets.preloadSceneAssets(sceneData, undefined, { skipSpine: true });+ sceneAssets.resolveSceneAssetPaths(sceneData, assetResult);+ applyTextureMetadata(sceneData, assetResult.textureHandles, (ref) => provider.resolvePath(ref));const spineAssetInfo = await loadSpineAssets(module, provider, spineManager, discovered.spines);@@ -446,13 +221,6 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis}}- const fontCache = await loadBitmapFonts(module, provider, getAssetPathsByType(discovered, 'font'));- const materialCache = await loadMaterials(provider, getAssetPathsByType(discovered, 'material'));- await loadAnimClips(app, module, provider, getAssetPathsByType(discovered, 'anim-clip'));- await loadTilemaps(module, provider, getAssetPathsByType(discovered, 'tilemap'));- await preloadAudioClips(app, provider, getAssetPathsByType(discovered, 'audio'));-- resolveSceneAssetPaths(sceneData, textureCache, fontCache, materialCache);const entityMap = loadSceneData(app.world, sceneData);const cppRegistry = app.world.getCppRegistry();diff --git a/sdk/tests/provider-backend.test.ts b/sdk/tests/provider-backend.test.tsnew file mode 100644index 000000000..d0ed7cab9--- /dev/null+++ b/sdk/tests/provider-backend.test.ts@@ -0,0 +1,78 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect } from 'vitest';+import { ProviderBackend } from '../src/asset/ProviderBackend';+import type { RuntimeAssetProvider } from '../src/runtimeAssets';++/** Minimal provider that resolves `@uuid:x` → `assets/x.png` (idempotent) and+ * serves text/binary keyed by the resolved path. Mirrors the real providers'+ * shape: readText/readBinary resolve internally; resolvePath is idempotent. */+function makeProvider(): RuntimeAssetProvider & { calls: string[] } {+ const store: Record<string, { text: string; bytes: Uint8Array }> = {+ 'assets/a.png': { text: 'A', bytes: new Uint8Array([1, 2, 3]) },+ };+ const calls: string[] = [];+ const resolvePath = (ref: string): string =>+ ref.startsWith('@uuid:') ? `assets/${ref.slice('@uuid:'.length)}.png` : ref;+ return {+ calls,+ resolvePath,+ async loadPixels() { throw new Error('unused'); },+ readText(ref: string): string {+ calls.push(`readText:${ref}`);+ return store[resolvePath(ref)].text;+ },+ readBinary(ref: string): Uint8Array {+ calls.push(`readBinary:${ref}`);+ return store[resolvePath(ref)].bytes;+ },+ };+}++describe('ProviderBackend', () => {+ it('resolveUrl delegates to provider.resolvePath', () => {+ const backend = new ProviderBackend(makeProvider());+ expect(backend.resolveUrl('@uuid:a')).toBe('assets/a.png');+ expect(backend.resolveUrl('assets/a.png')).toBe('assets/a.png'); // idempotent+ });++ it('fetchText delegates to provider.readText', async () => {+ const backend = new ProviderBackend(makeProvider());+ expect(await backend.fetchText('assets/a.png')).toBe('A');+ });++ it('fetchBinary returns a standalone ArrayBuffer with the exact bytes', async () => {+ const backend = new ProviderBackend(makeProvider());+ const buf = await backend.fetchBinary('assets/a.png');+ expect(buf).toBeInstanceOf(ArrayBuffer);+ expect(Array.from(new Uint8Array(buf))).toEqual([1, 2, 3]);+ });++ it('fetchBinary copies out a view into a larger pooled buffer', async () => {+ const pool = new Uint8Array([9, 9, 1, 2, 3, 9]); // asset bytes at offset 2, len 3+ const provider: RuntimeAssetProvider = {+ resolvePath: (r) => r,+ async loadPixels() { throw new Error('unused'); },+ readText: () => '',+ readBinary: () => pool.subarray(2, 5),+ };+ const buf = await new ProviderBackend(provider).fetchBinary('x');+ expect(buf.byteLength).toBe(3);+ expect(Array.from(new Uint8Array(buf))).toEqual([1, 2, 3]);+ // Mutating the pool must not change the returned buffer (it's a copy).+ pool[2] = 0;+ expect(Array.from(new Uint8Array(buf))).toEqual([1, 2, 3]);+ });++ it('awaits async provider methods', async () => {+ const provider: RuntimeAssetProvider = {+ resolvePath: (r) => r,+ async loadPixels() { throw new Error('unused'); },+ readText: async () => 'async-text',+ readBinary: async () => new Uint8Array([7]),+ };+ const backend = new ProviderBackend(provider);+ expect(await backend.fetchText('x')).toBe('async-text');+ expect(Array.from(new Uint8Array(await backend.fetchBinary('x')))).toEqual([7]);+ });+});