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(asset): retire RuntimeAssetProvider for the canonical Backend
yhh30eb8fe8fc7f
diff --git a/desktop/src/engine/spineLoad.ts b/desktop/src/engine/spineLoad.tsindex 51b81f91b..9158ebcec 100644--- a/desktop/src/engine/spineLoad.ts+++ b/desktop/src/engine/spineLoad.ts@@ -1,39 +1,30 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { SpinePlugin, loadSpineSceneEntities } from 'esengine/spine';-import type { RuntimeAssetProvider } from 'esengine/spine';+import type { RuntimeAssetSource } from 'esengine/spine';import { decodeImagePixels, type App, type SceneData } from 'esengine';/**- * Fetch-backed asset provider for spine in the editor: skeleton/atlas come over+ * Fetch-backed asset source for spine in the editor: skeleton/atlas come over* fetch as text/bytes; the atlas PNG is decoded to RGBA via the shared* `decodeImagePixels` (the same path the play realm uses — robust across the- * editor's http/app:// origins). `toUrl` maps an asset ref to a fetchable URL.+ * editor's http/app:// origins). `toUrl` maps an asset ref to a fetchable URL,+ * applied uniformly on fetch (so `resolveRef` stays identity).*/-class EditorSpineProvider implements RuntimeAssetProvider {- constructor(private readonly toUrl: (ref: string) => string) {}-- resolvePath(ref: string): string {- return this.toUrl(ref);- }-- async readText(ref: string): Promise<string> {- const r = await fetch(this.toUrl(ref));- if (!r.ok) throw new Error(`spine asset ${r.status}: ${ref}`);- return r.text();- }-- async readBinary(ref: string): Promise<Uint8Array> {- const r = await fetch(this.toUrl(ref));- if (!r.ok) throw new Error(`spine asset ${r.status}: ${ref}`);- return new Uint8Array(await r.arrayBuffer());- }-- async loadPixels(ref: string): Promise<{ width: number; height: number; pixels: Uint8Array }> {- const r = await fetch(this.toUrl(ref));- if (!r.ok) throw new Error(`spine texture ${r.status}: ${ref}`);- return decodeImagePixels(await r.blob());- }+function editorSpineSource(toUrl: (ref: string) => string): RuntimeAssetSource {+ const fetchOk = async (ref: string, kind: string): Promise<Response> => {+ const r = await fetch(toUrl(ref));+ if (!r.ok) throw new Error(`spine ${kind} ${r.status}: ${ref}`);+ return r;+ };+ return {+ backend: {+ resolveUrl: (ref) => toUrl(ref),+ fetchText: async (ref) => (await fetchOk(ref, 'asset')).text(),+ fetchBinary: async (ref) => (await fetchOk(ref, 'asset')).arrayBuffer(),+ },+ decodePixels: async (ref) => decodeImagePixels(await (await fetchOk(ref, 'texture')).blob()),+ };}/**@@ -58,7 +49,7 @@ export async function loadEditorSpine(try {await loadSpineSceneEntities({module,- provider: new EditorSpineProvider(toUrl),+ source: editorSpineSource(toUrl),spineManager,sceneData,entityMap: entityMap as Map<number, number>,diff --git a/sdk/src/asset/Backend.ts b/sdk/src/asset/Backend.tsindex c7e1d48a1..0cbfaf523 100644--- a/sdk/src/asset/Backend.ts+++ b/sdk/src/asset/Backend.ts@@ -50,6 +50,26 @@ export class HttpBackend implements Backend {}}+/**+ * Reads assets from the platform filesystem (WeChat `wx.getFileSystemManager`).+ * Paths are already resolved build paths (the runtime's `resolveRef` maps+ * uuid→build path before fetch), so `resolveUrl` is identity — there is no URL,+ * the path IS the file location.+ */+export class FileSystemBackend implements Backend {+ async fetchBinary(path: string): Promise<ArrayBuffer> {+ return platformReadFile(path);+ }++ async fetchText(path: string): Promise<string> {+ return platformReadTextFile(path);+ }++ resolveUrl(path: string): string {+ return path;+ }+}+export class EmbeddedBackend implements Backend {private assets_: Map<string, string>;diff --git a/sdk/src/asset/ProviderBackend.ts b/sdk/src/asset/ProviderBackend.tsdeleted file mode 100644index 28d715cf6..000000000--- a/sdk/src/asset/ProviderBackend.ts+++ /dev/null@@ -1,38 +0,0 @@-// 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/imageDecode.ts b/sdk/src/asset/imageDecode.tsindex 36b30213a..3bcb5d093 100644--- a/sdk/src/asset/imageDecode.ts+++ b/sdk/src/asset/imageDecode.ts@@ -64,3 +64,15 @@ export async function decodeImagePixels(src: ImageBitmapSource): Promise<Decodedbitmap.close?.();}}++/**+ * Fetch a URL and decode it to top-first RGBA pixels. The single fetch→blob→decode+ * path the runtime asset sources use for `estella://` / http origins (a CORS-mode+ * `<img>` taints the canvas on custom schemes; fetch→blob sidesteps it). Uses the+ * global `fetch` — these callers all run in a browser/electron context.+ */+export async function fetchDecodePixels(url: string): Promise<DecodedPixels> {+ const res = await fetch(url);+ if (!res.ok) throw new Error(`image fetch failed (${res.status}): ${url}`);+ return decodeImagePixels(await res.blob());+}diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex cca25ea54..0c6398124 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -197,7 +197,7 @@ export {loadRuntimeScene,createRuntimeSceneConfig,initRuntime,- type RuntimeAssetProvider,+ type RuntimeAssetSource,type LoadRuntimeSceneOptions,type RuntimeInitConfig,} from './runtimeLoader';@@ -206,7 +206,7 @@ export {// Preview// =============================================================================-export { PreviewPlugin, WebAssetProvider } from './preview';+export { PreviewPlugin } from './preview';// =============================================================================// Animationdiff --git a/sdk/src/index.wechat.ts b/sdk/src/index.wechat.tsindex f53756307..21ef3c037 100644--- a/sdk/src/index.wechat.ts+++ b/sdk/src/index.wechat.ts@@ -33,6 +33,5 @@ export {export {initWeChatRuntime,- WeChatAssetProvider,type WeChatRuntimeConfig,} from './wechatRuntime';diff --git a/sdk/src/playRealmRuntime.ts b/sdk/src/playRealmRuntime.tsindex ba822698e..4d4317cb9 100644--- a/sdk/src/playRealmRuntime.ts+++ b/sdk/src/playRealmRuntime.ts@@ -18,11 +18,12 @@import type { App } from './app';import type { ESEngineModule } from './wasm';import { initRuntime } from './runtimeLoader';-import type { RuntimeAssetProvider } from './runtimeLoader';+import type { RuntimeAssetSource } from './runtimeAssets';+import { HttpBackend } from './asset/Backend';import type { AddressableManifest } from './asset/AddressableManifest';import type { SceneData } from './scene';import type { PhysicsPluginConfig } from './physics/PhysicsPlugin';-import { decodeImagePixels } from './asset/imageDecode';+import { fetchDecodePixels } from './asset/imageDecode';const UUID_PREFIX = '@uuid:';@@ -49,51 +50,41 @@ export interface PlayRealmRuntimeConfig {}/**- * Fetches scene assets over the realm origin, resolving `@uuid:` refs through the- * editor-supplied manifest. Images go fetch → blob → the shared `decodeImagePixels`- * (NOT `<img crossorigin>`: Chromium refuses CORS-mode images for custom schemes- * like `estella://`, and a non-CORS `<img>` would taint the canvas so getImageData- * throws — fetch+blob sidesteps both). `estella://` is fetchable because it's a- * privileged supportFetchAPI scheme; the editor returns `access-control-allow-origin: *`.+ * Build the realm's asset source: `@uuid:` refs resolve through the editor-supplied+ * manifest (`resolveRef`), fetch goes over the realm origin via `HttpBackend`, and+ * images go fetch → blob → decode (NOT `<img crossorigin>`: Chromium refuses+ * CORS-mode images for custom schemes like `estella://`, and a non-CORS `<img>`+ * taints the canvas so getImageData throws — fetch+blob sidesteps both).+ * `estella://` is fetchable because it's a privileged supportFetchAPI scheme; the+ * editor returns `access-control-allow-origin: *`.*/-class FetchAssetProvider implements RuntimeAssetProvider {- constructor(private readonly manifest: Record<string, string>) {}-- resolvePath(ref: string): string {+function createPlayRealmSource(manifest: Record<string, string>): RuntimeAssetSource {+ const backend = new HttpBackend({ baseUrl: '' });+ const resolveRef = (ref: string): string => {if (!ref.startsWith(UUID_PREFIX)) return ref;- const url = this.manifest[ref.slice(UUID_PREFIX.length).toLowerCase()];+ const url = manifest[ref.slice(UUID_PREFIX.length).toLowerCase()];if (!url) throw new Error(`asset not in play manifest: ${ref}`);return url;- }-- async loadPixels(ref: string): Promise<{ width: number; height: number; pixels: Uint8Array }> {- const url = this.resolvePath(ref);- const res = await fetch(url);- if (!res.ok) throw new Error(`image fetch failed (${res.status}): ${url}`);- return decodeImagePixels(await res.blob());- }-- async readText(ref: string): Promise<string> {- return (await fetch(this.resolvePath(ref))).text();- }-- async readBinary(ref: string): Promise<Uint8Array> {- return new Uint8Array(await (await fetch(this.resolvePath(ref))).arrayBuffer());- }+ };+ return {+ backend,+ decodePixels: (path) => fetchDecodePixels(backend.resolveUrl(path)),+ resolveRef,+ };}/*** Boot the shipping runtime against a single in-memory scene snapshot. The host* page has already created `app` (createWebApp) + bound a GL context; here we- * register the snapshot as the sole scene, wire a fetch-backed provider, and run.+ * register the snapshot as the sole scene, wire a fetch-backed source, and run.*/export async function initPlayRealmRuntime(config: PlayRealmRuntimeConfig): Promise<void> {const { app, module, canvas, sceneData, assetManifest } = config;- const provider = new FetchAssetProvider(assetManifest);+ const source = createPlayRealmSource(assetManifest);await initRuntime({app,module,- provider,+ source,scenes: [{ name: '__play', data: sceneData }],firstScene: '__play',aspectRatio: canvas.width / canvas.height,diff --git a/sdk/src/playableRuntime.ts b/sdk/src/playableRuntime.tsindex f8655f783..899020158 100644--- a/sdk/src/playableRuntime.ts+++ b/sdk/src/playableRuntime.ts@@ -8,12 +8,13 @@* an {@link createEmbeddedSideModuleHost} from the exporter-inlined* base64 registry and hands it to `createWebApp`, so physics and spine* self-gate off `app.sideModules` exactly as in every other realm. This- * entry only owns the embedded asset provider + the runtime boot.+ * entry only owns the embedded asset source + the runtime boot.*/import type { App } from './app';import type { ESEngineModule } from './wasm';import { initRuntime } from './runtimeLoader';-import type { RuntimeAssetProvider } from './runtimeLoader';+import type { RuntimeAssetSource } from './runtimeAssets';+import { EmbeddedBackend } from './asset/Backend';import type { AddressableManifest } from './asset/AddressableManifest';import type { Vec2 } from './types';import type { SceneData } from './scene';@@ -30,40 +31,6 @@ export interface PlayableRuntimeConfig {manifest?: AddressableManifest | null;}-class EmbeddedAssetProvider implements RuntimeAssetProvider {- private readonly assets_: Record<string, string>;-- constructor(assets: Record<string, string>) {- this.assets_ = assets;- }-- async loadPixels(ref: string): Promise<{ width: number; height: number; pixels: Uint8Array }> {- return loadImagePixels(this.getAsset(ref));- }-- readText(ref: string): string {- return decodeDataUrlText(this.getAsset(ref));- }-- readBinary(ref: string): Uint8Array {- return decodeDataUrlBinary(this.getAsset(ref));- }-- resolvePath(ref: string): string {- return ref;- }-- private getAsset(ref: string): string {- const d = this.assets_[ref];- if (!d) throw new Error(`Asset not found: ${ref}`);- return d;- }-}--function decodeDataUrlText(dataUrl: string): string {- return atob(dataUrl.split(',')[1]);-}-function decodeDataUrlBinary(dataUrl: string): Uint8Array {const raw = atob(dataUrl.split(',')[1]);const bytes = new Uint8Array(raw.length);@@ -93,7 +60,13 @@ function loadImagePixels(dataUrl: string): Promise<{ width: number; height: numbexport async function initPlayableRuntime(config: PlayableRuntimeConfig): Promise<void> {const { app, module, assets, scenes, firstScene } = config;- const provider = new EmbeddedAssetProvider(assets);+ // Canonical asset source: the shared EmbeddedBackend (data-URLs) + a DOM image+ // decode over the same data-URL. Refs are the map keys (resolveRef = identity).+ const backend = new EmbeddedBackend(assets);+ const source: RuntimeAssetSource = {+ backend,+ decodePixels: (path) => loadImagePixels(backend.resolveUrl(path)),+ };if (app.hasResource(Audio)) {app.getResource(Audio).setAssetResolver((url: string) => {@@ -106,7 +79,7 @@ export async function initPlayableRuntime(config: PlayableRuntimeConfig): Promisawait initRuntime({app,module,- provider,+ source,scenes,firstScene,physicsConfig: config.physicsConfig,diff --git a/sdk/src/preview/PreviewPlugin.ts b/sdk/src/preview/PreviewPlugin.tsindex 5b0f4f6c2..7cd8c3137 100644--- a/sdk/src/preview/PreviewPlugin.ts+++ b/sdk/src/preview/PreviewPlugin.ts@@ -12,7 +12,9 @@ import { Transform, Camera, Canvas, ProjectionType, ClearFlags, type TransformDaimport { DEFAULT_DESIGN_WIDTH, DEFAULT_DESIGN_HEIGHT, DEFAULT_PIXELS_PER_UNIT } from '../defaults';import { platformFetch } from '../platform';import { SceneManager } from '../sceneManager';-import { WebAssetProvider } from './WebAssetProvider';+import { HttpBackend } from '../asset/Backend';+import { fetchDecodePixels } from '../asset/imageDecode';+import type { RuntimeAssetSource } from '../runtimeAssets';import { SpinePlugin } from '../spine/SpinePlugin';import { log } from '../logger';@@ -74,8 +76,13 @@ export class PreviewPlugin implements Plugin {}const sceneData = await response.json<SceneData>();- const provider = new WebAssetProvider(this.baseUrl_);- await provider.prefetch(sceneData);+ // Canonical asset source: http fetch over the preview origin + fetch→blob+ // image decode. Preview refs are plain paths (resolveRef = identity).+ const backend = new HttpBackend({ baseUrl: this.baseUrl_ });+ const source: RuntimeAssetSource = {+ backend,+ decodePixels: (path) => fetchDecodePixels(backend.resolveUrl(path)),+ };const spinePlugin = this.app_.getPlugin(SpinePlugin);const spineManager = spinePlugin?.spineManager ?? null;@@ -84,7 +91,7 @@ export class PreviewPlugin implements Plugin {app: this.app_,module: this.app_.wasmModule!,sceneData,- provider,+ source,spineManager,sceneName: PREVIEW_SCENE,});diff --git a/sdk/src/preview/WebAssetProvider.ts b/sdk/src/preview/WebAssetProvider.tsdeleted file mode 100644index dd93fc223..000000000--- a/sdk/src/preview/WebAssetProvider.ts+++ /dev/null@@ -1,142 +0,0 @@-// SPDX-License-Identifier: Apache-2.0-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-/**- * @file WebAssetProvider.ts- * @brief RuntimeAssetProvider for browser-based preview- */--import type { RuntimeAssetProvider } from '../runtimeLoader';-import type { SceneData } from '../scene';-import { getComponentAssetFieldDescriptors, getComponentSpineFieldDescriptor } from '../scene';-import { getAssetTypeEntry } from '../assetTypes';-import { decodeImagePixels } from '../asset/imageDecode';-import { log } from '../logger';--export class WebAssetProvider implements RuntimeAssetProvider {- private textCache_ = new Map<string, string>();- private binaryCache_ = new Map<string, Uint8Array>();- private baseUrl_: string;-- constructor(baseUrl: string) {- this.baseUrl_ = baseUrl.endsWith('/') ? baseUrl : baseUrl + '/';- }-- async prefetch(sceneData: SceneData): Promise<void> {- const textRefs = new Set<string>();- const binaryRefs = new Set<string>();- const bmfontRefs = new Set<string>();-- for (const entity of sceneData.entities) {- for (const comp of entity.components) {- if (!comp.data) continue;- const spineDesc = getComponentSpineFieldDescriptor(comp.type);- if (spineDesc) {- const skelPath = comp.data[spineDesc.skeletonField] as string;- const atlasPath = comp.data[spineDesc.atlasField] as string;- if (skelPath) {- if (getAssetTypeEntry(skelPath)?.contentType === 'binary') {- binaryRefs.add(skelPath);- } else {- textRefs.add(skelPath);- }- }- if (atlasPath) textRefs.add(atlasPath);- }- const descriptors = getComponentAssetFieldDescriptors(comp.type);- for (const desc of descriptors) {- const value = comp.data[desc.field];- if (typeof value !== 'string' || !value) continue;- if (desc.type === 'font') {- bmfontRefs.add(value);- textRefs.add(value);- } else if (desc.type === 'material') {- textRefs.add(value);- } else if (desc.type === 'anim-clip') {- textRefs.add(value);- } else if (desc.type === 'tilemap') {- textRefs.add(value);- } else if (desc.type === 'audio') {- binaryRefs.add(value);- }- }- }- }-- const fetches: Promise<void>[] = [];-- for (const ref of textRefs) {- fetches.push(- fetch(this.resolveUrl(ref))- .then(r => r.text())- .then(text => { this.textCache_.set(ref, text); })- .catch(err => { log.warn('preview', `Failed to prefetch text "${ref}"`, err); })- );- }-- for (const ref of binaryRefs) {- fetches.push(- fetch(this.resolveUrl(ref))- .then(r => r.arrayBuffer())- .then(buf => { this.binaryCache_.set(ref, new Uint8Array(buf)); })- .catch(err => { log.warn('preview', `Failed to prefetch binary "${ref}"`, err); })- );- }-- await Promise.all(fetches);-- const fntFetches: Promise<void>[] = [];- for (const ref of bmfontRefs) {- const fontEntry = getAssetTypeEntry(ref);- if (!(fontEntry?.editorType === 'bitmap-font' && fontEntry.contentType === 'json')) continue;- const text = this.textCache_.get(ref);- if (!text) continue;- try {- const json = JSON.parse(text);- const fntFile = json.type === 'label-atlas' ? json.generatedFnt : json.fntFile;- if (fntFile) {- const dir = ref.substring(0, ref.lastIndexOf('/'));- const fntRef = dir ? `${dir}/${fntFile}` : fntFile;- if (!this.textCache_.has(fntRef)) {- fntFetches.push(- fetch(this.resolveUrl(fntRef))- .then(r => r.text())- .then(t => { this.textCache_.set(fntRef, t); })- .catch(err => { log.warn('preview', `Failed to prefetch font "${fntRef}"`, err); })- );- }- }- } catch { /* ignore parse errors */ }- }- if (fntFetches.length > 0) {- await Promise.all(fntFetches);- }- }-- readText(ref: string): string {- const cached = this.textCache_.get(ref);- if (cached !== undefined) return cached;- throw new Error('Asset not prefetched: ' + ref);- }-- readBinary(ref: string): Uint8Array {- const cached = this.binaryCache_.get(ref);- if (cached !== undefined) return cached;- throw new Error('Asset not prefetched: ' + ref);- }-- async loadPixels(ref: string): Promise<{ width: number; height: number; pixels: Uint8Array }> {- const resp = await fetch(this.resolveUrl(ref));- return decodeImagePixels(await resp.blob());- }-- resolvePath(ref: string): string {- return ref;- }-- private resolveUrl(ref: string): string {- if (ref.startsWith('http://') || ref.startsWith('https://') || ref.startsWith('/')) {- return ref;- }- return this.baseUrl_ + ref;- }-}diff --git a/sdk/src/preview/index.ts b/sdk/src/preview/index.tsindex 6e03f5508..dae5ebb85 100644--- a/sdk/src/preview/index.ts+++ b/sdk/src/preview/index.ts@@ -6,4 +6,3 @@*/export { PreviewPlugin } from './PreviewPlugin';-export { WebAssetProvider } from './WebAssetProvider';diff --git a/sdk/src/runtimeAssets.ts b/sdk/src/runtimeAssets.tsindex 7c3239cf0..a266ee4b7 100644--- a/sdk/src/runtimeAssets.ts+++ b/sdk/src/runtimeAssets.ts@@ -9,16 +9,27 @@* runtime loader nor the spine loader has to import the other.*/import type { ESEngineModule } from './wasm';+import type { Backend } from './asset/Backend';import { requireResourceManager } from './resourceManager';import { withMalloc } from './wasmScratch';-/** How the loader fetches scene assets on a given target (http, virtual FS, …). */-export interface RuntimeAssetProvider {- loadPixels(ref: string): Promise<{ width: number; height: number; pixels: Uint8Array }>;- loadPixelsRaw?(ref: string): Promise<{ width: number; height: number; pixels: Uint8Array }>;- readText(ref: string): string | Promise<string>;- readBinary(ref: string): Uint8Array | Promise<Uint8Array>;- resolvePath(ref: string): string;+/**+ * How a target supplies scene assets to the single `Assets` channel, built from+ * canonical parts instead of a bespoke provider:+ * - `backend` — canonical fetch (text/binary, incl. KTX2 containers)+ * - `decodePixels` — platform image → RGBA (URL `<img>` can't reach `estella://`+ * / WeChat package files / inlined data-URLs); `flip` is applied on upload via+ * `createTextureFromPixels`, so decoders return top-first and ignore it+ * - `resolveRef` — ref → resolved (extension-bearing) path; must run before the+ * `TextureLoader` KTX2 extension check, so uuid/manifest lookup lives HERE, not+ * in `backend.resolveUrl`. Omit for identity.+ * (Signature declared locally, not imported from TextureLoader — that module+ * imports from this one, so importing back would cycle.)+ */+export interface RuntimeAssetSource {+ backend: Backend;+ decodePixels(path: string, flip: boolean): Promise<{ width: number; height: number; pixels: Uint8Array }>;+ resolveRef?(ref: string): string;}export interface TextureParams {diff --git a/sdk/src/runtimeLoader.ts b/sdk/src/runtimeLoader.tsindex 14b3d79b3..4c53c122d 100644--- a/sdk/src/runtimeLoader.ts+++ b/sdk/src/runtimeLoader.ts@@ -16,7 +16,6 @@ import { PhysicsPlugin, type PhysicsPluginConfig } from './physics/PhysicsPluginimport { SpinePlugin } from './spine/SpinePlugin';import type { App } from './app';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';@@ -26,7 +25,7 @@ import { Audio } from './audio/Audio';import { flushPendingSystems } from './app';import { requireResourceManager } from './resourceManager';import { log } from './logger';-import { type RuntimeAssetProvider, type TextureParams } from './runtimeAssets';+import { type RuntimeAssetSource, type TextureParams } from './runtimeAssets';import { loadSpineAssets, applySpineEntities } from './spine/loadSpineScene';import { transcoderFromModule, type BasisWasmModule } from './asset/basisTranscoder';@@ -34,9 +33,9 @@ import { transcoderFromModule, type BasisWasmModule } from './asset/basisTransco// Public Interface// =============================================================================-// RuntimeAssetProvider + createTextureFromPixels live in ./runtimeAssets so the+// RuntimeAssetSource + createTextureFromPixels live in ./runtimeAssets so the// spine scene loader can share them without importing this module.-export type { RuntimeAssetProvider } from './runtimeAssets';+export type { RuntimeAssetSource } from './runtimeAssets';// =============================================================================// Scene-local Assets channel@@ -44,32 +43,30 @@ export type { RuntimeAssetProvider } from './runtimeAssets';/*** 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)+ * canonical asset channel, driven by the realm's `RuntimeAssetSource`:+ * - fetch (text/binary, incl. KTX2 containers) → `source.backend`+ * - texture pixels → `source.decodePixels` (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).+ * `source.resolveRef` 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,+ app: App, module: ESEngineModule, source: RuntimeAssetSource, sceneData: SceneData,): AssetsClass {initBuiltinAssetFields();const assets = AssetsClass.create({- backend: new ProviderBackend(provider),+ backend: source.backend,module,getAudio: () => (app.hasResource(Audio) ? app.getResource(Audio) : null),getSpriteAnimation: () => (app.hasResource(SpriteAnimation) ? app.getResource(SpriteAnimation) : null),});- assets.setAssetRefResolver((ref) => provider.resolvePath(ref));+ if (source.resolveRef) assets.setAssetRefResolver(source.resolveRef);const loader = assets.getTextureLoader();- loader.setPixelDecoder((path, flip) =>- flip ? provider.loadPixels(path) : (provider.loadPixelsRaw?.(path) ?? provider.loadPixels(path)),- );+ loader.setPixelDecoder((path, flip) => source.decodePixels(path, flip));// KTX2 transcoder, self-gated off app.sideModules — identical wiring to// AssetPlugin.build so eager + on-demand loads transcode the same way.loader.setTranscoderProvider(async () => {@@ -80,15 +77,16 @@ function createSceneAssets(});// Per-texture import settings (filter/wrap) keyed by the scene's stored ref:- // normalize keys through resolvePath so they match the resolved path the+ // normalize keys through resolveRef so they match the resolved path the// TextureLoader sees, and map the stored {filterMode,wrapMode} shape to the// loader's {filter,wrap}.+ const resolveRef = source.resolveRef ?? ((r: string) => r);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)] = {+ resolved[resolveRef(ref)] = {filter: s.filterMode as TextureImportSettings['filter'],wrap: s.wrapMode as TextureImportSettings['wrap'],};@@ -126,7 +124,7 @@ export interface LoadRuntimeSceneOptions {app: App;module: ESEngineModule;sceneData: SceneData;- provider: RuntimeAssetProvider;+ source: RuntimeAssetSource;spineModule?: SpineWasmModule | null;spineManager?: SpineManager | null;physicsModule?: PhysicsWasmModule | null;@@ -162,7 +160,7 @@ function sceneUsesPhysics(sceneData: SceneData): boolean {}export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promise<void> {- const { app, module, sceneData, provider, physicsConfig, physicsEnabled, sceneName } = options;+ const { app, module, sceneData, source, physicsConfig, physicsEnabled, sceneName } = options;// The SpineManager is owned by SpinePlugin (built from the realm's// app.sideModules host); read it from there so every realm — play / playable /@@ -178,12 +176,12 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis// 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 sceneAssets = createSceneAssets(app, module, source, sceneData);const assetResult = await sceneAssets.preloadSceneAssets(sceneData, undefined, { skipSpine: true });sceneAssets.resolveSceneAssetPaths(sceneData, assetResult);- applyTextureMetadata(sceneData, assetResult.textureHandles, (ref) => provider.resolvePath(ref));+ applyTextureMetadata(sceneData, assetResult.textureHandles, source.resolveRef ?? ((ref) => ref));- const spineAssetInfo = await loadSpineAssets(module, provider, spineManager, discovered.spines);+ const spineAssetInfo = await loadSpineAssets(module, source, spineManager, discovered.spines);// Self-gating: install physics when the project declares it OR the scene uses// it, so no runtime entry can forget to wire it. The module comes from the@@ -255,7 +253,7 @@ export function createRuntimeSceneConfig(export interface RuntimeInitConfig {app: App;module: ESEngineModule;- provider: RuntimeAssetProvider;+ source: RuntimeAssetSource;scenes: Array<{ name: string; data: SceneData }>;firstScene: string;spineModule?: SpineWasmModule | null;@@ -277,7 +275,7 @@ export async function initRuntime(config: RuntimeInitConfig): Promise<void> {const sceneOpts: Omit<LoadRuntimeSceneOptions, 'sceneData' | 'sceneName'> = {app: config.app,module: config.module,- provider: config.provider,+ source: config.source,spineModule: config.spineModule,spineManager: config.spineManager,physicsModule: config.physicsModule,diff --git a/sdk/src/spine/index.ts b/sdk/src/spine/index.tsindex e5c03b615..9b9a7acf9 100644--- a/sdk/src/spine/index.ts+++ b/sdk/src/spine/index.ts@@ -12,4 +12,4 @@ export { wrapSpineModule } from './SpineModuleLoader';// Shared spine scene loader — the editor loads spine entities through the same// single implementation the builder runtime uses (see ./loadSpineScene).export { loadSpineSceneEntities, loadSpineAssets, applySpineEntities } from './loadSpineScene';-export type { RuntimeAssetProvider } from '../runtimeAssets';+export type { RuntimeAssetSource } from '../runtimeAssets';diff --git a/sdk/src/spine/loadSpineScene.ts b/sdk/src/spine/loadSpineScene.tsindex 5be63bf27..4233b41b9 100644--- a/sdk/src/spine/loadSpineScene.ts+++ b/sdk/src/spine/loadSpineScene.ts@@ -24,7 +24,7 @@ import { getAssetTypeEntry } from '../assetTypes';import { requireResourceManager } from '../resourceManager';import { log } from '../logger';import { SpineManager, type SpineVersion } from './SpineManager';-import { createTextureFromPixels, type RuntimeAssetProvider } from '../runtimeAssets';+import { createTextureFromPixels, type RuntimeAssetSource } from '../runtimeAssets';/** The opaque C++ registry handle SpineManager.loadEntity expects (app.world.getCppRegistry()). */type CppRegistry = Parameters<SpineManager['loadEntity']>[4];@@ -53,27 +53,30 @@ function parseAtlasTextures(content: string): string[] {*/export async function loadSpineAssets(module: ESEngineModule,- provider: RuntimeAssetProvider,+ source: RuntimeAssetSource,spineManager: SpineManager | null | undefined,spinePairs: ReadonlyArray<{ skeleton: string; atlas: string }>,): Promise<Map<string, SpineAssetInfo>> {const assetInfoMap = new Map<string, SpineAssetInfo>();+ const resolveRef = source.resolveRef ?? ((r: string) => r);for (const pair of spinePairs) {const skelRef = pair.skeleton;const atlasRef = pair.atlas;const cacheKey = `${skelRef}:${atlasRef}`;- const atlasPath = provider.resolvePath(atlasRef);+ // Resolve skeleton/atlas refs (uuid/manifest → build path); the derived+ // texPath below is already a path, so it is NOT re-resolved.+ const atlasPath = resolveRef(atlasRef);try {- const atlasContent = await provider.readText(atlasRef);+ const atlasContent = await source.backend.fetchText(atlasPath);- const skelPath = provider.resolvePath(skelRef);+ const skelPath = resolveRef(skelRef);const isBinary = getAssetTypeEntry(skelPath)?.contentType === 'binary';- const skelData = isBinary- ? await provider.readBinary(skelRef)- : await provider.readText(skelRef);+ const skelData: Uint8Array | string = isBinary+ ? new Uint8Array(await source.backend.fetchBinary(skelPath))+ : await source.backend.fetchText(skelPath);const version = spineManager? (typeof skelData === 'string'@@ -89,9 +92,7 @@ export async function loadSpineAssets(for (const texName of texNames) {const texPath = atlasDir + '/' + texName;try {- const result = provider.loadPixelsRaw- ? await provider.loadPixelsRaw(texPath)- : await provider.loadPixels(texPath);+ const result = await source.decodePixels(texPath, false);const handle = createTextureFromPixels(module, result, false);rm.registerTextureWithPath(handle, texPath);textures.set(texName, {@@ -168,7 +169,7 @@ export async function applySpineEntities(opts: {*/export async function loadSpineSceneEntities(opts: {module: ESEngineModule;- provider: RuntimeAssetProvider;+ source: RuntimeAssetSource;spineManager: SpineManager;sceneData: SceneData;entityMap: Map<number, Entity>;@@ -176,7 +177,7 @@ export async function loadSpineSceneEntities(opts: {}): Promise<void> {const discovered = discoverSceneAssets(opts.sceneData);if (discovered.spines.length === 0) return;- const assetInfo = await loadSpineAssets(opts.module, opts.provider, opts.spineManager, discovered.spines);+ const assetInfo = await loadSpineAssets(opts.module, opts.source, opts.spineManager, discovered.spines);await applySpineEntities({spineManager: opts.spineManager,sceneData: opts.sceneData,diff --git a/sdk/src/wechatRuntime.ts b/sdk/src/wechatRuntime.tsindex 01529e37c..8b71a2fbe 100644--- a/sdk/src/wechatRuntime.ts+++ b/sdk/src/wechatRuntime.ts@@ -9,10 +9,11 @@import { createWebApp } from './webAppFactory';import type { ESEngineModule } from './wasm';-import type { RuntimeAssetProvider } from './runtimeLoader';import { initRuntime } from './runtimeLoader';+import type { RuntimeAssetSource } from './runtimeAssets';+import { FileSystemBackend } from './asset/Backend';import { applyBuildRuntimeConfig, type RuntimeBuildConfig } from './defaults';-import { platformReadTextFile, platformReadFile, platformInstantiateWasm, platformLoadImagePixels } from './platform';+import { platformReadTextFile, platformInstantiateWasm, platformLoadImagePixels } from './platform';import { toBuildPath } from './assetTypes';import { ManifestModel, type AddressableManifest } from './asset/AddressableManifest';import { Assets } from './asset/AssetPlugin';@@ -21,35 +22,6 @@ import type { Vec2 } from './types';import type { SceneData } from './scene';import { log } from './logger';-// =============================================================================-// WeChat Asset Provider-// =============================================================================--export class WeChatAssetProvider implements RuntimeAssetProvider {- private readonly resolvePath_: (ref: string) => string;-- constructor(resolvePath: (ref: string) => string) {- this.resolvePath_ = resolvePath;- }-- async loadPixels(ref: string): Promise<{ width: number; height: number; pixels: Uint8Array }> {- return platformLoadImagePixels(this.resolvePath_(ref));- }-- async readText(ref: string): Promise<string> {- return platformReadTextFile(this.resolvePath_(ref));- }-- async readBinary(ref: string): Promise<Uint8Array> {- const buffer = await platformReadFile(this.resolvePath_(ref));- return new Uint8Array(buffer);- }-- resolvePath(ref: string): string {- return this.resolvePath_(ref);- }-}-// =============================================================================// Emscripten WASM Instantiation// =============================================================================@@ -150,7 +122,13 @@ export async function initWeChatRuntime(config: WeChatRuntimeConfig): Promise<vo// runtime loader below; this enables the on-demand subpackage path.if (app.hasResource(Assets)) app.getResource(Assets).setManifest(manifest);- const provider = new WeChatAssetProvider(resolvePath);+ // Canonical asset source: WeChat filesystem backend, wx image decode, manifest+ // ref resolution (bare-uuid → build path).+ const source: RuntimeAssetSource = {+ backend: new FileSystemBackend(),+ decodePixels: (path) => platformLoadImagePixels(path),+ resolveRef: resolvePath,+ };const scenes: Array<{ name: string; data: SceneData }> = [];for (const name of config.sceneNames) {@@ -161,7 +139,7 @@ export async function initWeChatRuntime(config: WeChatRuntimeConfig): Promise<voawait initRuntime({app,module,- provider,+ source,scenes,firstScene: config.firstScene,physicsConfig: config.physicsConfig,diff --git a/sdk/tests/filesystem-backend.test.ts b/sdk/tests/filesystem-backend.test.tsnew file mode 100644index 000000000..196212dcf--- /dev/null+++ b/sdk/tests/filesystem-backend.test.ts@@ -0,0 +1,38 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect } from 'vitest';+import { FileSystemBackend } from '../src/asset/Backend';+import { ManifestModel, type AddressableManifest } from '../src/asset/AddressableManifest';++describe('FileSystemBackend', () => {+ it('resolveUrl is identity — paths are already resolved build paths', () => {+ const be = new FileSystemBackend();+ expect(be.resolveUrl('assets/a1b2.ktx2')).toBe('assets/a1b2.ktx2');+ expect(be.resolveUrl('scenes/level.json')).toBe('scenes/level.json');+ });+});++describe('runtime resolveRef yields an extension-bearing path (KTX2 detection guard)', () => {+ // Regression guard for the class of bug where a runtime resolves a ref only at+ // fetch time (backend.resolveUrl), leaving TextureLoader to run its `.ktx2`+ // extension check on a bare uuid — which misses KTX2 and routes the container+ // through the image decoder. The manifest lookup must produce the extension+ // BEFORE the check, i.e. it belongs in resolveRef.+ it('manifest resolvePath maps a bare-uuid ref to its .ktx2 build path', () => {+ const manifest: AddressableManifest = {+ version: '2.0',+ groups: {+ main: {+ bundleMode: 'local',+ labels: [],+ assets: {+ 'uuid-1': { path: 'assets/deadbeef.ktx2', type: 'texture', size: 0, labels: [] },+ },+ },+ },+ };+ const resolved = ManifestModel.fromJson(manifest).resolvePath('uuid-1');+ expect(resolved).toBe('assets/deadbeef.ktx2');+ expect(resolved.toLowerCase().endsWith('.ktx2')).toBe(true);+ });+});diff --git a/sdk/tests/provider-backend.test.ts b/sdk/tests/provider-backend.test.tsdeleted file mode 100644index d0ed7cab9..000000000--- a/sdk/tests/provider-backend.test.ts+++ /dev/null@@ -1,78 +0,0 @@-// 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]);- });-});