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(asset): retire RuntimeAssetProvider for the canonical Backend

yhh30eb8fe8fc7f
diff --git a/desktop/src/engine/spineLoad.ts b/desktop/src/engine/spineLoad.ts
index 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 Team
import { 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.ts
index 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.ts
deleted file mode 100644
index 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.ts
index 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<Decoded
bitmap.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.ts
index 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';
// =============================================================================
// Animation
diff --git a/sdk/src/index.wechat.ts b/sdk/src/index.wechat.ts
index 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.ts
index 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.ts
index 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: numb
export 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): Promis
await initRuntime({
app,
module,
- provider,
+ source,
scenes,
firstScene,
physicsConfig: config.physicsConfig,
diff --git a/sdk/src/preview/PreviewPlugin.ts b/sdk/src/preview/PreviewPlugin.ts
index 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 TransformDa
import { 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.ts
deleted file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 14b3d79b3..4c53c122d 100644
--- a/sdk/src/runtimeLoader.ts
+++ b/sdk/src/runtimeLoader.ts
@@ -16,7 +16,6 @@ import { PhysicsPlugin, type PhysicsPluginConfig } from './physics/PhysicsPlugin
import { 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.ts
index 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.ts
index 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.ts
index 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<vo
await 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.ts
new file mode 100644
index 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.ts
deleted file mode 100644
index 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]);
- });
-});