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.

feat: add unified Assets architecture (Backend/Catalog/Loader registry)

esengine8bede5b8fb32
diff --git a/sdk/src/asset/AssetFieldRegistry.ts b/sdk/src/asset/AssetFieldRegistry.ts
new file mode 100644
index 000000000..ebd467420
--- /dev/null
+++ b/sdk/src/asset/AssetFieldRegistry.ts
@@ -0,0 +1,107 @@
+export type AssetFieldType = 'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'tilemap' | 'timeline';
+
+export interface AssetFieldDescriptor {
+ field: string;
+ type: AssetFieldType;
+}
+
+export interface CompoundFieldDescriptor {
+ type: string;
+ fields: Record<string, string>;
+}
+
+interface RegistryEntry {
+ fields: AssetFieldDescriptor[];
+ compounds: CompoundFieldDescriptor[];
+}
+
+const registry_ = new Map<string, RegistryEntry>();
+
+function ensureEntry(componentType: string): RegistryEntry {
+ let entry = registry_.get(componentType);
+ if (!entry) {
+ entry = { fields: [], compounds: [] };
+ registry_.set(componentType, entry);
+ }
+ return entry;
+}
+
+export function registerAssetFields(componentType: string, fields: AssetFieldDescriptor[]): void {
+ const entry = ensureEntry(componentType);
+ entry.fields = fields;
+}
+
+export function registerCompoundAssetFields(componentType: string, compound: CompoundFieldDescriptor): void {
+ const entry = ensureEntry(componentType);
+ entry.compounds.push(compound);
+}
+
+export function getAssetFields(componentType: string): AssetFieldDescriptor[] {
+ return registry_.get(componentType)?.fields ?? [];
+}
+
+export function getCompoundAssetFields(componentType: string): CompoundFieldDescriptor[] {
+ return registry_.get(componentType)?.compounds ?? [];
+}
+
+export function getAllRegisteredComponents(): string[] {
+ return Array.from(registry_.keys());
+}
+
+export function clearAssetFieldRegistry(): void {
+ registry_.clear();
+}
+
+export function initBuiltinAssetFields(): void {
+ registerAssetFields('Sprite', [
+ { field: 'texture', type: 'texture' },
+ { field: 'material', type: 'material' },
+ ]);
+
+ registerCompoundAssetFields('SpineAnimation', {
+ type: 'spine',
+ fields: { skeleton: 'skeletonPath', atlas: 'atlasPath' },
+ });
+ registerAssetFields('SpineAnimation', [
+ { field: 'material', type: 'material' },
+ ]);
+
+ registerAssetFields('BitmapText', [
+ { field: 'font', type: 'font' },
+ ]);
+
+ registerAssetFields('Image', [
+ { field: 'texture', type: 'texture' },
+ { field: 'material', type: 'material' },
+ ]);
+
+ registerAssetFields('UIRenderer', [
+ { field: 'texture', type: 'texture' },
+ { field: 'material', type: 'material' },
+ ]);
+
+ registerAssetFields('SpriteAnimator', [
+ { field: 'clip', type: 'anim-clip' },
+ ]);
+
+ registerAssetFields('AudioSource', [
+ { field: 'clip', type: 'audio' },
+ ]);
+
+ registerAssetFields('ParticleEmitter', [
+ { field: 'texture', type: 'texture' },
+ { field: 'material', type: 'material' },
+ ]);
+
+ registerAssetFields('Tilemap', [
+ { field: 'source', type: 'tilemap' },
+ ]);
+
+ registerAssetFields('TilemapLayer', [
+ { field: 'texture', type: 'texture' },
+ ]);
+
+ registerAssetFields('TimelinePlayer', [
+ { field: 'timeline', type: 'timeline' },
+ ]);
+}
diff --git a/sdk/src/asset/AssetLoader.ts b/sdk/src/asset/AssetLoader.ts
new file mode 100644
index 000000000..4cd176382
--- /dev/null
+++ b/sdk/src/asset/AssetLoader.ts
@@ -0,0 +1,59 @@
+import type { Backend } from './Backend';
+import type { Catalog } from './Catalog';
+import type { TextureHandle, FontHandle } from '../types';
+import type { CppResourceManager } from '../wasm';
+
+export interface TextureResult {
+ handle: TextureHandle;
+ width: number;
+ height: number;
+}
+
+export interface SpineResult {
+ skeletonHandle: number;
+}
+
+export interface MaterialResult {
+ handle: number;
+ shaderHandle: number;
+}
+
+export interface FontResult {
+ handle: FontHandle;
+}
+
+export interface AudioResult {
+ bufferId: string;
+}
+
+export interface AnimClipResult {
+ clipId: string;
+}
+
+export interface TilemapResult {
+ sourceId: string;
+}
+
+export interface TimelineResult {
+ timelineId: string;
+}
+
+export interface PrefabResult {
+ data: unknown;
+}
+
+export interface LoadContext {
+ backend: Backend;
+ catalog: Catalog;
+ resourceManager: CppResourceManager;
+ loadTexture(path: string, flipY?: boolean): Promise<TextureResult>;
+ loadText(path: string): Promise<string>;
+ loadBinary(path: string): Promise<ArrayBuffer>;
+}
+
+export interface AssetLoader<T> {
+ readonly type: string;
+ readonly extensions: string[];
+ load(path: string, ctx: LoadContext): Promise<T>;
+ unload(asset: T): void;
+}
diff --git a/sdk/src/asset/AssetPlugin.ts b/sdk/src/asset/AssetPlugin.ts
index 5749f13df..88a01adf0 100644
--- a/sdk/src/asset/AssetPlugin.ts
+++ b/sdk/src/asset/AssetPlugin.ts
@@ -1,15 +1,9 @@
-/**
- * @file AssetPlugin.ts
- * @brief Plugin that provides asset loading capabilities
- */
-
import type { App, Plugin } from '../app';
import { defineResource } from '../resource';
import { AssetServer } from './AssetServer';
-
-// =============================================================================
-// Assets Resource
-// =============================================================================
+import { Assets as AssetsImpl } from './Assets';
+import { HttpBackend } from './Backend';
+import { initBuiltinAssetFields } from './AssetFieldRegistry';
export type AssetsData = AssetServer;
@@ -18,9 +12,10 @@ export const Assets = defineResource<AssetsData>(
'Assets'
);
-// =============================================================================
-// Asset Plugin
-// =============================================================================
+export const AssetsV2 = defineResource<AssetsImpl>(
+ null!,
+ 'AssetsV2'
+);
export class AssetPlugin implements Plugin {
build(app: App): void {
@@ -30,7 +25,16 @@ export class AssetPlugin implements Plugin {
return;
}
- app.insertResource(Assets, new AssetServer(module));
+ initBuiltinAssetFields();
+
+ const assetServer = new AssetServer(module);
+ app.insertResource(Assets, assetServer);
+
+ const assets = AssetsImpl.create({
+ backend: new HttpBackend({ baseUrl: assetServer.baseUrl ?? '' }),
+ module,
+ });
+ app.insertResource(AssetsV2, assets);
}
}
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
new file mode 100644
index 000000000..befe43334
--- /dev/null
+++ b/sdk/src/asset/Assets.ts
@@ -0,0 +1,508 @@
+import type { Backend } from './Backend';
+import { Catalog, type AtlasFrameInfo } from './Catalog';
+import type {
+ AssetLoader, LoadContext, TextureResult, SpineResult,
+ MaterialResult, FontResult, AudioResult, AnimClipResult,
+ TilemapResult, TimelineResult, PrefabResult,
+} from './AssetLoader';
+import { AsyncCache } from './AsyncCache';
+import type { ESEngineModule } from '../wasm';
+import type { CppResourceManager } from '../wasm';
+import { requireResourceManager, evictTextureDimensions } from '../resourceManager';
+import { TextureLoader } from './loaders/TextureLoader';
+import { SpineAssetLoader } from './loaders/SpineAssetLoader';
+import { MaterialAssetLoader } from './loaders/MaterialAssetLoader';
+import { FontAssetLoader } from './loaders/FontAssetLoader';
+import { AudioAssetLoader } from './loaders/AudioAssetLoader';
+import { AnimClipAssetLoader } from './loaders/AnimClipAssetLoader';
+import { TilemapAssetLoader } from './loaders/TilemapAssetLoader';
+import { TimelineAssetLoader } from './loaders/TimelineAssetLoader';
+import { PrefabAssetLoader } from './loaders/PrefabAssetLoader';
+import type { SpineModuleController } from '../spine/SpineController';
+import {
+ getAssetFields, getCompoundAssetFields,
+ initBuiltinAssetFields,
+} from './AssetFieldRegistry';
+import type { SceneData, SceneEntityData } from '../scene';
+import { SceneHandle, type ReleaseCallback } from './SceneHandle';
+
+export interface AssetsOptions {
+ backend: Backend;
+ catalog?: Catalog;
+ module: ESEngineModule;
+}
+
+export interface AssetBundle {
+ textures: Map<string, TextureResult>;
+ materials: Map<string, MaterialResult>;
+ spine: Map<string, SpineResult>;
+ fonts: Map<string, FontResult>;
+}
+
+export interface SceneAssetResult {
+ textureHandles: Map<string, number>;
+ materialHandles: Map<string, number>;
+ fontHandles: Map<string, number>;
+ releaseCallbacks: ReleaseCallback[];
+}
+
+export class Assets {
+ readonly backend: Backend;
+ readonly catalog: Catalog;
+
+ private module_: ESEngineModule;
+ private loaders_ = new Map<string, AssetLoader<unknown>>();
+ private textureLoader_: TextureLoader;
+ private spineLoader_: SpineAssetLoader;
+
+ private textureCache_ = new AsyncCache<TextureResult>();
+ private textureRefCounts_ = new Map<string, number>();
+ private genericCache_ = new Map<string, AsyncCache<unknown>>();
+
+ private constructor(options: AssetsOptions) {
+ this.backend = options.backend;
+ this.catalog = options.catalog ?? Catalog.empty();
+ this.module_ = options.module;
+
+ this.textureLoader_ = new TextureLoader(options.module);
+ this.spineLoader_ = new SpineAssetLoader(options.module);
+
+ this.registerBuiltinLoaders();
+ }
+
+ static create(options: AssetsOptions): Assets {
+ return new Assets(options);
+ }
+
+ // =========================================================================
+ // Loader Registry
+ // =========================================================================
+
+ register<T>(loader: AssetLoader<T>): void {
+ this.loaders_.set(loader.type, loader as AssetLoader<unknown>);
+ }
+
+ getLoader<T>(type: string): AssetLoader<T> | undefined {
+ return this.loaders_.get(type) as AssetLoader<T> | undefined;
+ }
+
+ // =========================================================================
+ // Typed Load Methods (User API)
+ // =========================================================================
+
+ async loadTexture(ref: string): Promise<TextureResult> {
+ const path = this.catalog.resolve(ref);
+ const cacheKey = `${path}:f`;
+ const result = await this.textureCache_.getOrLoad(cacheKey, () =>
+ this.textureLoader_.load(path, this.createLoadContext()),
+ );
+ this.textureRefCounts_.set(cacheKey, (this.textureRefCounts_.get(cacheKey) ?? 0) + 1);
+ return result;
+ }
+
+ async loadTextureRaw(ref: string): Promise<TextureResult> {
+ const path = this.catalog.resolve(ref);
+ const cacheKey = `${path}:n`;
+ const result = await this.textureCache_.getOrLoad(cacheKey, () =>
+ this.textureLoader_.loadRaw(path, this.createLoadContext()),
+ );
+ this.textureRefCounts_.set(cacheKey, (this.textureRefCounts_.get(cacheKey) ?? 0) + 1);
+ return result;
+ }
+
+ getTexture(ref: string): TextureResult | undefined {
+ const path = this.catalog.resolve(ref);
+ return this.textureCache_.get(`${path}:f`);
+ }
+
+ async loadSpine(skeletonRef: string, atlasRef?: string): Promise<SpineResult> {
+ const skelPath = this.catalog.resolve(skeletonRef);
+ if (atlasRef) {
+ const atlasPath = this.catalog.resolve(atlasRef);
+ return this.spineLoader_.loadWithAtlas(skelPath, atlasPath, this.createLoadContext());
+ }
+ return this.spineLoader_.load(skelPath, this.createLoadContext());
+ }
+
+ async loadMaterial(ref: string): Promise<MaterialResult> {
+ return this.loadTyped('material', ref);
+ }
+
+ async loadFont(ref: string): Promise<FontResult> {
+ return this.loadTyped('font', ref);
+ }
+
+ async loadAudio(ref: string): Promise<AudioResult> {
+ return this.loadTyped('audio', ref);
+ }
+
+ async loadAnimClip(ref: string): Promise<AnimClipResult> {
+ return this.loadTyped('anim-clip', ref);
+ }
+
+ async loadTilemap(ref: string): Promise<TilemapResult> {
+ return this.loadTyped('tilemap', ref);
+ }
+
+ async loadTimeline(ref: string): Promise<TimelineResult> {
+ return this.loadTyped('timeline', ref);
+ }
+
+ async loadPrefab(ref: string): Promise<PrefabResult> {
+ return this.loadTyped('prefab', ref);
+ }
+
+ // =========================================================================
+ // Generic Load (for custom loaders)
+ // =========================================================================
+
+ async load<T>(type: string, ref: string): Promise<T> {
+ return this.loadTyped<T>(type, ref);
+ }
+
+ // =========================================================================
+ // Atlas Query
+ // =========================================================================
+
+ getAtlasFrame(ref: string): AtlasFrameInfo | null {
+ const path = this.catalog.resolve(ref);
+ return this.catalog.getAtlasFrame(path);
+ }
+
+ // =========================================================================
+ // Label Batch Load
+ // =========================================================================
+
+ async loadByLabel(label: string): Promise<AssetBundle> {
+ const paths = this.catalog.getByLabel(label);
+ const bundle: AssetBundle = {
+ textures: new Map(),
+ materials: new Map(),
+ spine: new Map(),
+ fonts: new Map(),
+ };
+
+ const promises: Promise<void>[] = [];
+ for (const path of paths) {
+ const entry = this.catalog.getEntry(path);
+ if (!entry) continue;
+
+ switch (entry.type) {
+ case 'texture':
+ promises.push(
+ this.loadTexture(path).then(r => { bundle.textures.set(path, r); }),
+ );
+ break;
+ case 'material':
+ promises.push(
+ this.loadMaterial(path).then(r => { bundle.materials.set(path, r); }),
+ );
+ break;
+ case 'spine':
+ promises.push(
+ this.loadSpine(path).then(r => { bundle.spine.set(path, r); }),
+ );
+ break;
+ case 'font':
+ promises.push(
+ this.loadFont(path).then(r => { bundle.fonts.set(path, r); }),
+ );
+ break;
+ }
+ }
+
+ await Promise.allSettled(promises);
+ return bundle;
+ }
+
+ // =========================================================================
+ // Raw Data (escape hatch)
+ // =========================================================================
+
+ async fetchJson<T = unknown>(ref: string): Promise<T> {
+ const path = this.catalog.resolve(ref);
+ const buildPath = this.catalog.getBuildPath(path);
+ const text = await this.backend.fetchText(buildPath);
+ return JSON.parse(text) as T;
+ }
+
+ async fetchBinary(ref: string): Promise<ArrayBuffer> {
+ const path = this.catalog.resolve(ref);
+ const buildPath = this.catalog.getBuildPath(path);
+ return this.backend.fetchBinary(buildPath);
+ }
+
+ async fetchText(ref: string): Promise<string> {
+ const path = this.catalog.resolve(ref);
+ const buildPath = this.catalog.getBuildPath(path);
+ return this.backend.fetchText(buildPath);
+ }
+
+ // =========================================================================
+ // Scene Asset Preloading
+ // =========================================================================
+
+ async preloadSceneAssets(sceneData: SceneData): Promise<SceneAssetResult> {
+ const texturePaths = new Set<string>();
+ const materialPaths = new Set<string>();
+ const fontPaths = new Set<string>();
+ const animClipPaths = new Set<string>();
+ const audioPaths = new Set<string>();
+ const tilemapPaths = new Set<string>();
+ const timelinePaths = new Set<string>();
+ const spinePairs: Array<{ skeleton: string; atlas: string }> = [];
+
+ for (const entity of sceneData.entities) {
+ for (const comp of entity.components) {
+ const fields = getAssetFields(comp.type);
+ for (const { field, type } of fields) {
+ const value = comp.data[field];
+ if (typeof value !== 'string' || !value) continue;
+ switch (type) {
+ case 'texture': texturePaths.add(value); break;
+ case 'material': materialPaths.add(value); break;
+ case 'font': fontPaths.add(value); break;
+ case 'anim-clip': animClipPaths.add(value); break;
+ case 'audio': audioPaths.add(value); break;
+ case 'tilemap': tilemapPaths.add(value); break;
+ case 'timeline': timelinePaths.add(value); break;
+ }
+ }
+
+ const compounds = getCompoundAssetFields(comp.type);
+ for (const compound of compounds) {
+ if (compound.type === 'spine') {
+ const skeleton = comp.data[compound.fields.skeleton] as string;
+ const atlas = comp.data[compound.fields.atlas] as string;
+ if (skeleton && atlas) {
+ spinePairs.push({ skeleton, atlas });
+ }
+ }
+ }
+ }
+ }
+
+ const textureHandles = new Map<string, number>();
+ const materialHandles = new Map<string, number>();
+ const fontHandles = new Map<string, number>();
+ const releaseCallbacks: ReleaseCallback[] = [];
+
+ const promises: Promise<void>[] = [];
+
+ for (const path of texturePaths) {
+ promises.push(
+ this.loadTexture(path).then(r => {
+ textureHandles.set(path, r.handle);
+ }).catch(e => {
+ console.warn(`[Assets] Failed to load texture: ${path}`, e);
+ textureHandles.set(path, 0);
+ }),
+ );
+ }
+
+ for (const path of materialPaths) {
+ promises.push(
+ this.loadMaterial(path).then(r => {
+ materialHandles.set(path, r.handle);
+ }).catch(e => {
+ console.warn(`[Assets] Failed to load material: ${path}`, e);
+ materialHandles.set(path, 0);
+ }),
+ );
+ }
+
+ for (const path of fontPaths) {
+ promises.push(
+ this.loadFont(path).then(r => {
+ fontHandles.set(path, r.handle);
+ }).catch(e => {
+ console.warn(`[Assets] Failed to load font: ${path}`, e);
+ fontHandles.set(path, 0);
+ }),
+ );
+ }
+
+ for (const pair of spinePairs) {
+ promises.push(
+ this.loadSpine(pair.skeleton, pair.atlas).then(() => {}).catch(e => {
+ console.warn(`[Assets] Failed to load spine: ${pair.skeleton}`, e);
+ }),
+ );
+ }
+
+ for (const path of animClipPaths) {
+ promises.push(this.loadAnimClip(path).then(() => {}).catch(e => {
+ console.warn(`[Assets] Failed to load anim clip: ${path}`, e);
+ }));
+ }
+
+ for (const path of tilemapPaths) {
+ promises.push(this.loadTilemap(path).then(() => {}).catch(e => {
+ console.warn(`[Assets] Failed to load tilemap: ${path}`, e);
+ }));
+ }
+
+ for (const path of timelinePaths) {
+ promises.push(this.loadTimeline(path).then(() => {}).catch(e => {
+ console.warn(`[Assets] Failed to load timeline: ${path}`, e);
+ }));
+ }
+
+ for (const path of audioPaths) {
+ promises.push(this.loadAudio(path).then(() => {}).catch(e => {
+ console.warn(`[Assets] Failed to load audio: ${path}`, e);
+ }));
+ }
+
+ await Promise.all(promises);
+
+ return { textureHandles, materialHandles, fontHandles, releaseCallbacks };
+ }
+
+ resolveSceneAssetPaths(sceneData: SceneData, result: SceneAssetResult): void {
+ const { textureHandles, materialHandles, fontHandles } = result;
+
+ for (const entity of sceneData.entities) {
+ for (const comp of entity.components) {
+ const fields = getAssetFields(comp.type);
+ for (const { field, type } of fields) {
+ const value = comp.data[field];
+ if (typeof value !== 'string' || !value) continue;
+
+ switch (type) {
+ case 'texture': {
+ comp.data[field] = textureHandles.get(value) ?? 0;
+ const atlasInfo = this.catalog.getAtlasFrame(value);
+ if (atlasInfo) {
+ comp.data['uvOffset'] = { x: atlasInfo.uvOffset[0], y: atlasInfo.uvOffset[1] };
+ comp.data['uvScale'] = { x: atlasInfo.uvScale[0], y: atlasInfo.uvScale[1] };
+ }
+ break;
+ }
+ case 'material':
+ comp.data[field] = materialHandles.get(value) ?? 0;
+ break;
+ case 'font':
+ comp.data[field] = fontHandles.get(value) ?? 0;
+ break;
+ }
+ }
+ }
+ }
+ }
+
+ // =========================================================================
+ // Release
+ // =========================================================================
+
+ releaseTexture(ref: string): void {
+ const path = this.catalog.resolve(ref);
+ for (const suffix of [':f', ':n']) {
+ const key = path + suffix;
+ const count = this.textureRefCounts_.get(key);
+ if (count === undefined) continue;
+
+ const info = this.textureCache_.get(key);
+ if (!info) continue;
+
+ const newCount = count - 1;
+ if (newCount <= 0) {
+ const rm = requireResourceManager();
+ rm.releaseTexture(info.handle);
+ evictTextureDimensions(info.handle);
+ this.textureCache_.delete(key);
+ this.textureRefCounts_.delete(key);
+ } else {
+ this.textureRefCounts_.set(key, newCount);
+ }
+ }
+ }
+
+ releaseAll(): void {
+ const rm = requireResourceManager();
+ for (const info of this.textureCache_.values()) {
+ rm.releaseTexture(info.handle);
+ evictTextureDimensions(info.handle);
+ }
+ this.textureCache_.clearAll();
+ this.textureRefCounts_.clear();
+
+ this.spineLoader_.releaseAll();
+
+ for (const cache of this.genericCache_.values()) {
+ cache.clearAll();
+ }
+ this.genericCache_.clear();
+ }
+
+ // =========================================================================
+ // Spine Controller
+ // =========================================================================
+
+ setSpineController(controller: SpineModuleController): void {
+ this.spineLoader_.setSpineController(controller);
+ }
+
+ getSpineLoader(): SpineAssetLoader {
+ return this.spineLoader_;
+ }
+
+ getTextureLoader(): TextureLoader {
+ return this.textureLoader_;
+ }
+
+ // =========================================================================
+ // Private
+ // =========================================================================
+
+ private registerBuiltinLoaders(): void {
+ this.register(this.textureLoader_);
+ this.register(this.spineLoader_);
+ this.register(new MaterialAssetLoader());
+ this.register(new FontAssetLoader());
+ this.register(new AudioAssetLoader());
+ this.register(new AnimClipAssetLoader());
+ this.register(new TilemapAssetLoader());
+ this.register(new TimelineAssetLoader());
+ this.register(new PrefabAssetLoader());
+ }
+
+ private async loadTyped<T>(type: string, ref: string): Promise<T> {
+ const loader = this.loaders_.get(type) as AssetLoader<T> | undefined;
+ if (!loader) {
+ throw new Error(`No loader registered for type: ${type}`);
+ }
+ const path = this.catalog.resolve(ref);
+
+ let cache = this.genericCache_.get(type);
+ if (!cache) {
+ cache = new AsyncCache<unknown>();
+ this.genericCache_.set(type, cache);
+ }
+
+ return cache.getOrLoad(path, () =>
+ loader.load(path, this.createLoadContext()),
+ ) as Promise<T>;
+ }
+
+ private createLoadContext(): LoadContext {
+ const self = this;
+ return {
+ backend: this.backend,
+ catalog: this.catalog,
+ resourceManager: requireResourceManager() as CppResourceManager,
+ async loadTexture(path: string, flipY?: boolean): Promise<TextureResult> {
+ if (flipY === false) {
+ return self.loadTextureRaw(path);
+ }
+ return self.loadTexture(path);
+ },
+ async loadText(path: string): Promise<string> {
+ return self.backend.fetchText(self.backend.resolveUrl(path));
+ },
+ async loadBinary(path: string): Promise<ArrayBuffer> {
+ return self.backend.fetchBinary(self.backend.resolveUrl(path));
+ },
+ };
+ }
+}
diff --git a/sdk/src/asset/Backend.ts b/sdk/src/asset/Backend.ts
new file mode 100644
index 000000000..342dd0c67
--- /dev/null
+++ b/sdk/src/asset/Backend.ts
@@ -0,0 +1,87 @@
+import { platformFetch, platformReadFile, platformReadTextFile } from '../platform';
+
+export interface Backend {
+ fetchBinary(path: string): Promise<ArrayBuffer>;
+ fetchText(path: string): Promise<string>;
+ resolveUrl(path: string): string;
+}
+
+export interface HttpBackendOptions {
+ baseUrl: string;
+}
+
+export class HttpBackend implements Backend {
+ private baseUrl_: string;
+
+ constructor(options: HttpBackendOptions) {
+ this.baseUrl_ = options.baseUrl.replace(/\/+$/, '');
+ }
+
+ async fetchBinary(path: string): Promise<ArrayBuffer> {
+ const url = this.resolveUrl(path);
+ const response = await platformFetch(url);
+ return response.arrayBuffer();
+ }
+
+ async fetchText(path: string): Promise<string> {
+ const url = this.resolveUrl(path);
+ const response = await platformFetch(url);
+ return response.text();
+ }
+
+ resolveUrl(path: string): string {
+ if (path.startsWith('http://') || path.startsWith('https://') || path.startsWith('/')) {
+ return path;
+ }
+ return `${this.baseUrl_}/${path}`;
+ }
+}
+
+export class EmbeddedBackend implements Backend {
+ private assets_: Map<string, string>;
+
+ constructor(assets: Record<string, string>) {
+ this.assets_ = new Map(Object.entries(assets));
+ }
+
+ async fetchBinary(path: string): Promise<ArrayBuffer> {
+ const dataUrl = this.getDataUrl(path);
+ const base64 = dataUrl.slice(dataUrl.indexOf(',') + 1);
+ const binary = atob(base64);
+ const bytes = new Uint8Array(binary.length);
+ for (let i = 0; i < binary.length; i++) {
+ bytes[i] = binary.charCodeAt(i);
+ }
+ return bytes.buffer;
+ }
+
+ async fetchText(path: string): Promise<string> {
+ const dataUrl = this.getDataUrl(path);
+ if (dataUrl.startsWith('data:') && dataUrl.includes(';base64,')) {
+ const base64 = dataUrl.slice(dataUrl.indexOf(',') + 1);
+ const binary = atob(base64);
+ const bytes = new Uint8Array(binary.length);
+ for (let i = 0; i < binary.length; i++) {
+ bytes[i] = binary.charCodeAt(i);
+ }
+ return new TextDecoder().decode(bytes);
+ }
+ return dataUrl;
+ }
+
+ resolveUrl(path: string): string {
+ return this.assets_.get(path) ?? path;
+ }
+
+ has(path: string): boolean {
+ return this.assets_.has(path);
+ }
+
+ private getDataUrl(path: string): string {
+ const dataUrl = this.assets_.get(path);
+ if (!dataUrl) {
+ throw new Error(`EmbeddedBackend: asset not found: ${path}`);
+ }
+ return dataUrl;
+ }
+}
diff --git a/sdk/src/asset/Catalog.ts b/sdk/src/asset/Catalog.ts
new file mode 100644
index 000000000..f6d49778d
--- /dev/null
+++ b/sdk/src/asset/Catalog.ts
@@ -0,0 +1,101 @@
+export interface AtlasFrameInfo {
+ atlas: string;
+ frame: { x: number; y: number; w: number; h: number };
+ uvOffset: [number, number];
+ uvScale: [number, number];
+}
+
+export interface CatalogEntry {
+ type: string;
+ atlas?: string;
+ frame?: { x: number; y: number; w: number; h: number };
+ uv?: { offset: [number, number]; scale: [number, number] };
+ deps?: string[];
+ buildPath?: string;
+}
+
+export interface CatalogData {
+ version: number;
+ entries: Record<string, CatalogEntry>;
+ addresses?: Record<string, string>;
+ labels?: Record<string, string[]>;
+}
+
+export class Catalog {
+ private entries_: Map<string, CatalogEntry>;
+ private addresses_: Map<string, string>;
+ private labels_: Map<string, string[]>;
+
+ private constructor(
+ entries: Map<string, CatalogEntry>,
+ addresses: Map<string, string>,
+ labels: Map<string, string[]>,
+ ) {
+ this.entries_ = entries;
+ this.addresses_ = addresses;
+ this.labels_ = labels;
+ }
+
+ static fromJson(data: CatalogData): Catalog {
+ const entries = new Map(Object.entries(data.entries));
+ const addresses = new Map(Object.entries(data.addresses ?? {}));
+ const labels = new Map(Object.entries(data.labels ?? {}));
+ return new Catalog(entries, addresses, labels);
+ }
+
+ static empty(): Catalog {
+ return new Catalog(new Map(), new Map(), new Map());
+ }
+
+ resolve(ref: string): string {
+ const addressPath = this.addresses_.get(ref);
+ if (addressPath) return addressPath;
+ if (this.entries_.has(ref)) return ref;
+ return ref;
+ }
+
+ getEntry(path: string): CatalogEntry | null {
+ return this.entries_.get(path) ?? null;
+ }
+
+ getAtlasFrame(path: string): AtlasFrameInfo | null {
+ const entry = this.entries_.get(path);
+ if (!entry?.atlas || !entry.frame || !entry.uv) return null;
+ return {
+ atlas: entry.atlas,
+ frame: entry.frame,
+ uvOffset: entry.uv.offset,
+ uvScale: entry.uv.scale,
+ };
+ }
+
+ getBuildPath(path: string): string {
+ const entry = this.entries_.get(path);
+ return entry?.buildPath ?? path;
+ }
+
+ getDeps(path: string): string[] {
+ const entry = this.entries_.get(path);
+ return entry?.deps ?? [];
+ }
+
+ getByLabel(label: string): string[] {
+ return this.labels_.get(label) ?? [];
+ }
+
+ getAllLabels(): string[] {
+ return Array.from(this.labels_.keys());
+ }
+
+ hasEntry(path: string): boolean {
+ return this.entries_.has(path);
+ }
+
+ hasAddress(address: string): boolean {
+ return this.addresses_.has(address);
+ }
+
+ get isEmpty(): boolean {
+ return this.entries_.size === 0;
+ }
+}
diff --git a/sdk/src/asset/SceneHandle.ts b/sdk/src/asset/SceneHandle.ts
new file mode 100644
index 000000000..ecd306f0f
--- /dev/null
+++ b/sdk/src/asset/SceneHandle.ts
@@ -0,0 +1,27 @@
+import type { Entity } from '../types';
+
+export type ReleaseCallback = () => void;
+
+export class SceneHandle {
+ readonly entities: Entity[];
+ private releaseCallbacks_: ReleaseCallback[];
+ private released_ = false;
+
+ constructor(entities: Entity[], releaseCallbacks: ReleaseCallback[]) {
+ this.entities = entities;
+ this.releaseCallbacks_ = releaseCallbacks;
+ }
+
+ get isReleased(): boolean {
+ return this.released_;
+ }
+
+ release(): void {
+ if (this.released_) return;
+ this.released_ = true;
+ for (const cb of this.releaseCallbacks_) {
+ cb();
+ }
+ this.releaseCallbacks_ = [];
+ }
+}
diff --git a/sdk/src/asset/index.ts b/sdk/src/asset/index.ts
index 5326ee4df..269c4bcee 100644
--- a/sdk/src/asset/index.ts
+++ b/sdk/src/asset/index.ts
@@ -1,8 +1,3 @@
-/**
- * @file index.ts
- * @brief Asset module exports
- */
-
export {
AssetServer,
type TextureInfo,
@@ -10,7 +5,7 @@ export {
type SliceBorder,
type SpineDescriptor,
type FileLoadOptions,
- type AssetBundle,
+ type AssetBundle as LegacyAssetBundle,
type AddressableAssetType,
type AddressableResultMap,
type AddressableManifest,
@@ -18,10 +13,22 @@ export {
type AddressableManifestAsset,
} from './AssetServer';
export { AsyncCache } from './AsyncCache';
-export { Assets, AssetPlugin, assetPlugin, type AssetsData } from './AssetPlugin';
+export { Assets, AssetsV2, AssetPlugin, assetPlugin, type AssetsData } from './AssetPlugin';
export { MaterialLoader, type LoadedMaterial, type ShaderLoader } from './MaterialLoader';
export { AssetRefCounter, type AssetRefInfo } from './AssetRefCounter';
+export { Assets as AssetsImpl, type AssetsOptions, type AssetBundle, type SceneAssetResult } from './Assets';
+export { type Backend, HttpBackend, EmbeddedBackend, type HttpBackendOptions } from './Backend';
+export { Catalog, type CatalogData, type CatalogEntry, type AtlasFrameInfo } from './Catalog';
+export { type AssetLoader, type LoadContext, type TextureResult, type SpineResult, type MaterialResult, type FontResult, type AudioResult } from './AssetLoader';
+export { SceneHandle } from './SceneHandle';
+export {
+ registerAssetFields, registerCompoundAssetFields,
+ getAssetFields, getCompoundAssetFields,
+ initBuiltinAssetFields,
+ type AssetFieldType, type AssetFieldDescriptor, type CompoundFieldDescriptor,
+} from './AssetFieldRegistry';
+
import type { App } from '../app';
import { Assets } from './AssetPlugin';
diff --git a/sdk/src/asset/loaders/AnimClipAssetLoader.ts b/sdk/src/asset/loaders/AnimClipAssetLoader.ts
new file mode 100644
index 000000000..36ad8d12b
--- /dev/null
+++ b/sdk/src/asset/loaders/AnimClipAssetLoader.ts
@@ -0,0 +1,35 @@
+import type { AssetLoader, LoadContext, AnimClipResult } from '../AssetLoader';
+import { extractAnimClipTexturePaths, parseAnimClipData, type AnimClipAssetData } from '../../animation/AnimClipLoader';
+import { registerAnimClip } from '../../animation/SpriteAnimator';
+
+export class AnimClipAssetLoader implements AssetLoader<AnimClipResult> {
+ readonly type = 'anim-clip';
+ readonly extensions = ['.esanim'];
+
+ async load(path: string, ctx: LoadContext): Promise<AnimClipResult> {
+ const buildPath = ctx.catalog.getBuildPath(path);
+ const text = await ctx.loadText(buildPath);
+ const data: AnimClipAssetData = JSON.parse(text);
+ const texturePaths = extractAnimClipTexturePaths(data);
+ const textureHandles = new Map<string, number>();
+
+ for (const texPath of texturePaths) {
+ try {
+ const result = await ctx.loadTexture(texPath, true);
+ textureHandles.set(texPath, result.handle);
+ } catch (e) {
+ console.warn(`[AnimClipLoader] Failed to load texture: ${texPath}`, e);
+ textureHandles.set(texPath, 0);
+ }
+ }
+
+ const clip = parseAnimClipData(path, data, textureHandles);
+ registerAnimClip(clip);
+
+ return { clipId: path };
+ }
+
+ unload(_asset: AnimClipResult): void {
+ // AnimClips registered globally, no per-asset cleanup
+ }
+}
diff --git a/sdk/src/asset/loaders/AudioAssetLoader.ts b/sdk/src/asset/loaders/AudioAssetLoader.ts
new file mode 100644
index 000000000..e24ffdb26
--- /dev/null
+++ b/sdk/src/asset/loaders/AudioAssetLoader.ts
@@ -0,0 +1,18 @@
+import type { AssetLoader, LoadContext, AudioResult } from '../AssetLoader';
+import { Audio } from '../../audio/Audio';
+
+export class AudioAssetLoader implements AssetLoader<AudioResult> {
+ readonly type = 'audio';
+ readonly extensions = ['.mp3', '.wav', '.ogg', '.m4a', '.aac'];
+
+ async load(path: string, ctx: LoadContext): Promise<AudioResult> {
+ const buildPath = ctx.catalog.getBuildPath(path);
+ const buffer = await ctx.loadBinary(buildPath);
+ await Audio.preloadFromData(path, buffer);
+ return { bufferId: path };
+ }
+
+ unload(_asset: AudioResult): void {
+ // Audio buffers are managed globally by Audio system
+ }
+}
diff --git a/sdk/src/asset/loaders/FontAssetLoader.ts b/sdk/src/asset/loaders/FontAssetLoader.ts
new file mode 100644
index 000000000..dcb49c585
--- /dev/null
+++ b/sdk/src/asset/loaders/FontAssetLoader.ts
@@ -0,0 +1,62 @@
+import type { AssetLoader, LoadContext, FontResult } from '../AssetLoader';
+import { requireResourceManager } from '../../resourceManager';
+import { getAssetTypeEntry } from '../../assetTypes';
+import type { FontHandle } from '../../types';
+
+export class FontAssetLoader implements AssetLoader<FontResult> {
+ readonly type = 'font';
+ readonly extensions = ['.bmfont', '.fnt'];
+
+ async load(path: string, ctx: LoadContext): Promise<FontResult> {
+ const entry = getAssetTypeEntry(path);
+ if (entry?.editorType === 'bitmap-font' && entry.contentType === 'json') {
+ return this.loadBmfontJson(path, ctx);
+ }
+ return this.loadFntFile(path, ctx);
+ }
+
+ unload(asset: FontResult): void {
+ const rm = requireResourceManager();
+ rm.releaseBitmapFont(asset.handle);
+ }
+
+ private async loadBmfontJson(path: string, ctx: LoadContext): Promise<FontResult> {
+ const buildPath = ctx.catalog.getBuildPath(path);
+ const text = await ctx.loadText(buildPath);
+ const json = JSON.parse(text) as {
+ type: string;
+ fntFile?: string;
+ generatedFnt?: string;
+ };
+
+ const fntFile = json.type === 'label-atlas' ? json.generatedFnt : json.fntFile;
+ if (!fntFile) {
+ throw new Error(`Invalid bmfont asset: no fnt file specified in ${path}`);
+ }
+
+ const dir = path.substring(0, path.lastIndexOf('/'));
+ const fntPath = dir ? `${dir}/${fntFile}` : fntFile;
+ return this.loadFntFile(fntPath, ctx);
+ }
+
+ private async loadFntFile(path: string, ctx: LoadContext): Promise<FontResult> {
+ const buildPath = ctx.catalog.getBuildPath(path);
+ const fntContent = await ctx.loadText(buildPath);
+ const pageMatch = fntContent.match(/file="([^"]+)"/);
+ if (!pageMatch) {
+ throw new Error(`No page texture found in .fnt file: ${path}`);
+ }
+
+ const texName = pageMatch[1];
+ const dir = path.substring(0, path.lastIndexOf('/'));
+ const texPath = dir ? `${dir}/${texName}` : texName;
+
+ const texResult = await ctx.loadTexture(texPath, false);
+ const rm = requireResourceManager();
+ const handle = rm.loadBitmapFont(
+ fntContent, texResult.handle, texResult.width, texResult.height,
+ ) as FontHandle;
+
+ return { handle };
+ }
+}
diff --git a/sdk/src/asset/loaders/MaterialAssetLoader.ts b/sdk/src/asset/loaders/MaterialAssetLoader.ts
new file mode 100644
index 000000000..ee2366e3d
--- /dev/null
+++ b/sdk/src/asset/loaders/MaterialAssetLoader.ts
@@ -0,0 +1,60 @@
+import type { AssetLoader, LoadContext, MaterialResult } from '../AssetLoader';
+import type { MaterialAssetData, ShaderHandle } from '../../material';
+import { Material } from '../../material';
+import { AsyncCache } from '../AsyncCache';
+
+const ES_SHADER_VERTEX_RE = /#pragma\s+vertex\s*([\s\S]*?)#pragma\s+end/;
+const ES_SHADER_FRAGMENT_RE = /#pragma\s+fragment\s*([\s\S]*?)#pragma\s+end/;
+
+const shaderCache = new AsyncCache<ShaderHandle>();
+
+export class MaterialAssetLoader implements AssetLoader<MaterialResult> {
+ readonly type = 'material';
+ readonly extensions = ['.esmaterial'];
+
+ async load(path: string, ctx: LoadContext): Promise<MaterialResult> {
+ const buildPath = ctx.catalog.getBuildPath(path);
+ const text = await ctx.loadText(buildPath);
+ const data = JSON.parse(text) as MaterialAssetData;
+
+ if (data.type !== 'material') {
+ throw new Error(`Invalid material file type: ${data.type} at ${path}`);
+ }
+
+ const shaderPath = resolveShaderPath(path, data.shader);
+ const shaderHandle = await this.loadShader(shaderPath, ctx);
+ const handle = Material.createFromAsset(data, shaderHandle);
+
+ return { handle, shaderHandle };
+ }
+
+ unload(asset: MaterialResult): void {
+ Material.release(asset.handle);
+ }
+
+ private async loadShader(path: string, ctx: LoadContext): Promise<ShaderHandle> {
+ const cached = shaderCache.get(path);
+ if (cached !== undefined) return cached;
+
+ return shaderCache.getOrLoad(path, async () => {
+ const buildPath = ctx.catalog.getBuildPath(path);
+ const content = await ctx.loadText(buildPath);
+ const vertexMatch = content.match(ES_SHADER_VERTEX_RE);
+ const fragmentMatch = content.match(ES_SHADER_FRAGMENT_RE);
+
+ if (!vertexMatch?.[1] || !fragmentMatch?.[1]) {
+ throw new Error(`Invalid shader format: ${path}`);
+ }
+
+ return Material.createShader(vertexMatch[1].trim(), fragmentMatch[1].trim());
+ });
+ }
+}
+
+function resolveShaderPath(materialPath: string, shaderPath: string): string {
+ if (shaderPath.startsWith('/') || shaderPath.startsWith('http') || shaderPath.startsWith('assets/')) {
+ return shaderPath;
+ }
+ const dir = materialPath.substring(0, materialPath.lastIndexOf('/'));
+ return dir ? `${dir}/${shaderPath}` : shaderPath;
+}
diff --git a/sdk/src/asset/loaders/PrefabAssetLoader.ts b/sdk/src/asset/loaders/PrefabAssetLoader.ts
new file mode 100644
index 000000000..5f200571d
--- /dev/null
+++ b/sdk/src/asset/loaders/PrefabAssetLoader.ts
@@ -0,0 +1,18 @@
+import type { AssetLoader, LoadContext, PrefabResult } from '../AssetLoader';
+import type { PrefabData } from '../../prefab';
+
+export class PrefabAssetLoader implements AssetLoader<PrefabResult> {
+ readonly type = 'prefab';
+ readonly extensions = ['.esprefab'];
+
+ async load(path: string, ctx: LoadContext): Promise<PrefabResult> {
+ const buildPath = ctx.catalog.getBuildPath(path);
+ const text = await ctx.loadText(buildPath);
+ const data = JSON.parse(text) as PrefabData;
+ return { data };
+ }
+
+ unload(_asset: PrefabResult): void {
+ // Prefab data is plain JSON, no GPU resources
+ }
+}
diff --git a/sdk/src/asset/loaders/SpineAssetLoader.ts b/sdk/src/asset/loaders/SpineAssetLoader.ts
new file mode 100644
index 000000000..8ba77342d
--- /dev/null
+++ b/sdk/src/asset/loaders/SpineAssetLoader.ts
@@ -0,0 +1,162 @@
+import type { AssetLoader, LoadContext, SpineResult } from '../AssetLoader';
+import { requireResourceManager } from '../../resourceManager';
+import { getAssetTypeEntry } from '../../assetTypes';
+import type { ESEngineModule } from '../../wasm';
+import type { SpineModuleController } from '../../spine/SpineController';
+
+export class SpineAssetLoader implements AssetLoader<SpineResult> {
+ readonly type = 'spine';
+ readonly extensions = ['.skel'];
+
+ private module_: ESEngineModule;
+ private spineController_: SpineModuleController | null = null;
+ private loaded_ = new Set<string>();
+ private virtualFSPaths_ = new Set<string>();
+ private skeletonHandles_ = new Map<string, number>();
+
+ constructor(module: ESEngineModule) {
+ this.module_ = module;
+ }
+
+ setSpineController(controller: SpineModuleController): void {
+ this.spineController_ = controller;
+ }
+
+ getSkeletonHandle(cacheKey: string): number | undefined {
+ return this.skeletonHandles_.get(cacheKey);
+ }
+
+ isLoaded(cacheKey: string): boolean {
+ return this.loaded_.has(cacheKey);
+ }
+
+ async load(skeletonPath: string, ctx: LoadContext): Promise<SpineResult> {
+ const deps = ctx.catalog.getDeps(skeletonPath);
+ const atlasPath = deps.length > 0 ? deps[0] : null;
+ if (!atlasPath) {
+ throw new Error(`Spine skeleton has no atlas dependency: ${skeletonPath}. Pass atlas explicitly or configure Catalog deps.`);
+ }
+ return this.loadWithAtlas(skeletonPath, atlasPath, ctx);
+ }
+
+ async loadWithAtlas(skeletonPath: string, atlasPath: string, ctx: LoadContext): Promise<SpineResult> {
+ const cacheKey = `${skeletonPath}:${atlasPath}`;
+ if (this.loaded_.has(cacheKey)) {
+ return { skeletonHandle: this.skeletonHandles_.get(cacheKey) ?? -1 };
+ }
+
+ const atlasContent = await ctx.loadText(ctx.catalog.getBuildPath(atlasPath));
+ const texNames = parseAtlasTextures(atlasContent);
+ const atlasDir = atlasPath.substring(0, atlasPath.lastIndexOf('/'));
+ const rm = requireResourceManager();
+
+ const loadedTextures: { name: string; handle: number; width: number; height: number }[] = [];
+ for (const texName of texNames) {
+ const texPath = atlasDir ? `${atlasDir}/${texName}` : texName;
+ try {
+ const texResult = await ctx.loadTexture(texPath, false);
+ rm.registerTextureWithPath(texResult.handle, texPath);
+ loadedTextures.push({
+ name: texName,
+ handle: texResult.handle,
+ width: texResult.width,
+ height: texResult.height,
+ });
+ } catch (err) {
+ console.warn(`[SpineLoader] Failed to load texture: ${texPath}`, err);
+ }
+ }
+
+ const skelBuildPath = ctx.catalog.getBuildPath(skeletonPath);
+ const isBinary = getAssetTypeEntry(skeletonPath)?.contentType === 'binary';
+ const skelData = isBinary
+ ? new Uint8Array(await ctx.loadBinary(skelBuildPath))
+ : await ctx.loadText(skelBuildPath);
+
+ this.writeToVirtualFS(atlasPath, atlasContent);
+ this.writeToVirtualFS(skeletonPath, skelData);
+
+ this.loaded_.add(cacheKey);
+
+ let skeletonHandle = -1;
+ if (this.spineController_) {
+ skeletonHandle = this.spineController_.loadSkeleton(skelData, atlasContent, isBinary);
+ if (skeletonHandle >= 0) {
+ const pageCount = this.spineController_.getAtlasPageCount(skeletonHandle);
+ for (let i = 0; i < pageCount; i++) {
+ const pageName = this.spineController_.getAtlasPageTextureName(skeletonHandle, i);
+ const tex = loadedTextures.find(t => t.name === pageName);
+ if (tex) {
+ const glId = rm.getTextureGLId(tex.handle);
+ this.spineController_.setAtlasPageTexture(
+ skeletonHandle, i, glId, tex.width, tex.height,
+ );
+ }
+ }
+ this.skeletonHandles_.set(cacheKey, skeletonHandle);
+ }
+ }
+
+ return { skeletonHandle };
+ }
+
+ unload(_asset: SpineResult): void {
+ // Spine resources managed by SpineController lifecycle
+ }
+
+ releaseAll(): void {
+ if (this.spineController_) {
+ for (const handle of this.skeletonHandles_.values()) {
+ this.spineController_.unloadSkeleton(handle);
+ }
+ }
+ this.skeletonHandles_.clear();
+ this.loaded_.clear();
+ this.cleanupVirtualFS();
+ }
+
+ private writeToVirtualFS(virtualPath: string, data: string | Uint8Array): void {
+ if (this.virtualFSPaths_.has(virtualPath)) return;
+ const fs = this.module_.FS;
+ if (!fs) return;
+
+ try {
+ ensureVirtualDir(fs, virtualPath);
+ fs.writeFile(virtualPath, data);
+ this.virtualFSPaths_.add(virtualPath);
+ } catch (e) {
+ console.warn(`[SpineLoader] Failed to write virtual FS: ${virtualPath}`, e);
+ }
+ }
+
+ private cleanupVirtualFS(): void {
+ const fs = this.module_.FS;
+ if (!fs) return;
+ for (const path of this.virtualFSPaths_) {
+ try { fs.unlink(path); } catch { /* already removed */ }
+ }
+ this.virtualFSPaths_.clear();
+ }
+}
+
+function ensureVirtualDir(fs: any, virtualPath: string): void {
+ const dir = virtualPath.substring(0, virtualPath.lastIndexOf('/'));
+ if (!dir) return;
+ const parts = dir.split('/').filter((p: string) => p);
+ let currentPath = '';
+ for (const part of parts) {
+ currentPath += '/' + part;
+ try { fs.mkdir(currentPath); } catch { /* already exists */ }
+ }
+}
+
+function parseAtlasTextures(content: string): string[] {
+ const textures: string[] = [];
+ for (const line of content.split('\n')) {
+ const trimmed = line.trim();
+ if (trimmed && !trimmed.includes(':') && (/\.png$/i.test(trimmed) || /\.jpg$/i.test(trimmed))) {
+ textures.push(trimmed);
+ }
+ }
+ return textures;
+}
diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.ts
new file mode 100644
index 000000000..ee2085bb1
--- /dev/null
+++ b/sdk/src/asset/loaders/TextureLoader.ts
@@ -0,0 +1,170 @@
+import type { AssetLoader, LoadContext, TextureResult } from '../AssetLoader';
+import { platformCreateCanvas, platformCreateImage } from '../../platform';
+import { requireResourceManager } from '../../resourceManager';
+import type { ESEngineModule } from '../../wasm';
+
+export class TextureLoader implements AssetLoader<TextureResult> {
+ readonly type = 'texture';
+ readonly extensions = ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp'];
+
+ private module_: ESEngineModule;
+ private canvas_: HTMLCanvasElement | OffscreenCanvas;
+ private ctx_: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+
+ constructor(module: ESEngineModule) {
+ this.module_ = module;
+ this.canvas_ = platformCreateCanvas(256, 256);
+ const ctx = this.canvas_.getContext('2d', { willReadFrequently: true });
+ if (!ctx) throw new Error('TextureLoader: failed to create 2D context');
+ this.ctx_ = ctx;
+ }
+
+ async load(path: string, ctx: LoadContext): Promise<TextureResult> {
+ return this.loadWithFlip(path, ctx, true);
+ }
+
+ async loadRaw(path: string, ctx: LoadContext): Promise<TextureResult> {
+ return this.loadWithFlip(path, ctx, false);
+ }
+
+ async loadFromPixels(
+ width: number, height: number, pixels: Uint8Array, flipY: boolean,
+ ): Promise<TextureResult> {
+ const rm = requireResourceManager();
+ const ptr = this.module_._malloc(pixels.length);
+ this.module_.HEAPU8.set(pixels, ptr);
+ const handle = rm.createTexture(width, height, ptr, pixels.length, 1, flipY);
+ this.module_._free(ptr);
+ return { handle, width, height };
+ }
+
+ unload(asset: TextureResult): void {
+ const rm = requireResourceManager();
+ rm.releaseTexture(asset.handle);
+ }
+
+ private async loadWithFlip(path: string, ctx: LoadContext, flip: boolean): Promise<TextureResult> {
+ const url = ctx.backend.resolveUrl(ctx.catalog.getBuildPath(path));
+ const img = await this.loadImage(url);
+ return this.createTextureFromImage(img, flip);
+ }
+
+ private loadImage(src: string): Promise<HTMLImageElement | ImageBitmap> {
+ return new Promise((resolve, reject) => {
+ const img = platformCreateImage();
+ img.crossOrigin = 'anonymous';
+ img.onload = async () => {
+ if (typeof createImageBitmap !== 'undefined') {
+ try {
+ const bitmap = await createImageBitmap(img, {
+ premultiplyAlpha: 'none',
+ colorSpaceConversion: 'none',
+ });
+ resolve(bitmap);
+ return;
+ } catch {
+ // fallback
+ }
+ }
+ resolve(img);
+ };
+ img.onerror = () => reject(new Error(`Failed to load image: ${src}`));
+ img.src = src;
+ });
+ }
+
+ private createTextureFromImage(
+ img: HTMLImageElement | ImageBitmap, flip: boolean,
+ ): TextureResult {
+ const { width, height } = img;
+ const gl = this.getWebGL2Context();
+
+ if (gl) {
+ return this.createTextureWebGL2(gl, img, width, height, flip);
+ }
+ return this.createTextureFallback(img, width, height, flip);
+ }
+
+ private getWebGL2Context(): WebGL2RenderingContext | null {
+ try {
+ const glObj = (this.module_ as any).GL;
+ if (glObj?.currentContext?.GLctx instanceof WebGL2RenderingContext) {
+ return glObj.currentContext.GLctx;
+ }
+ } catch {
+ // fallback
+ }
+ return null;
+ }
+
+ private createTextureWebGL2(
+ gl: WebGL2RenderingContext,
+ img: HTMLImageElement | ImageBitmap,
+ width: number, height: number, flip: boolean,
+ ): TextureResult {
+ const texture = gl.createTexture()!;
+ gl.bindTexture(gl.TEXTURE_2D, texture);
+ gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, flip ? 1 : 0);
+ gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, 0);
+ gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img as any);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.REPEAT);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.REPEAT);
+ gl.generateMipmap(gl.TEXTURE_2D);
+ gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 0);
+
+ const glObj = (this.module_ as any).GL;
+ const glTextureId = glObj.getNewId(glObj.textures);
+ glObj.textures[glTextureId] = texture;
+
+ const rm = requireResourceManager();
+ const handle = rm.registerExternalTexture(glTextureId, width, height);
+ return { handle, width, height };
+ }
+
+ private createTextureFallback(
+ img: HTMLImageElement | ImageBitmap,
+ width: number, height: number, flip: boolean,
+ ): TextureResult {
+ const canvas = this.canvas_;
+ if (canvas.width < width || canvas.height < height) {
+ canvas.width = Math.max(canvas.width, nextPowerOf2(width));
+ canvas.height = Math.max(canvas.height, nextPowerOf2(height));
+ }
+
+ const ctx = this.ctx_ as CanvasRenderingContext2D;
+ ctx.clearRect(0, 0, canvas.width, canvas.height);
+ ctx.drawImage(img, 0, 0);
+
+ const imageData = ctx.getImageData(0, 0, width, height);
+ const pixels = new Uint8Array(imageData.data.buffer);
+ unpremultiplyAlpha(pixels);
+
+ const rm = requireResourceManager();
+ const ptr = this.module_._malloc(pixels.length);
+ this.module_.HEAPU8.set(pixels, ptr);
+ const handle = rm.createTexture(width, height, ptr, pixels.length, 1, flip);
+ this.module_._free(ptr);
+
+ return { handle, width, height };
+ }
+}
+
+function unpremultiplyAlpha(pixels: Uint8Array): void {
+ for (let i = 0; i < pixels.length; i += 4) {
+ const a = pixels[i + 3];
+ if (a > 0 && a < 255) {
+ const scale = 255 / a;
+ pixels[i] = Math.min(255, Math.round(pixels[i] * scale));
+ pixels[i + 1] = Math.min(255, Math.round(pixels[i + 1] * scale));
+ pixels[i + 2] = Math.min(255, Math.round(pixels[i + 2] * scale));
+ }
+ }
+}
+
+function nextPowerOf2(n: number): number {
+ let p = 1;
+ while (p < n) p *= 2;
+ return p;
+}
diff --git a/sdk/src/asset/loaders/TilemapAssetLoader.ts b/sdk/src/asset/loaders/TilemapAssetLoader.ts
new file mode 100644
index 000000000..b1403f916
--- /dev/null
+++ b/sdk/src/asset/loaders/TilemapAssetLoader.ts
@@ -0,0 +1,50 @@
+import type { AssetLoader, LoadContext, TilemapResult } from '../AssetLoader';
+import { parseTmjJson, resolveRelativePath } from '../../tilemap/tiledLoader';
+import { registerTilemapSource } from '../../tilemap/tilesetCache';
+
+export class TilemapAssetLoader implements AssetLoader<TilemapResult> {
+ readonly type = 'tilemap';
+ readonly extensions = ['.tmj', '.tmx'];
+
+ async load(path: string, ctx: LoadContext): Promise<TilemapResult> {
+ const buildPath = ctx.catalog.getBuildPath(path);
+ const text = await ctx.loadText(buildPath);
+ const mapData = parseTmjJson(JSON.parse(text));
+ if (!mapData) {
+ throw new Error(`Failed to parse tilemap: ${path}`);
+ }
+
+ const tilesets = [];
+ for (const ts of mapData.tilesets) {
+ const imagePath = resolveRelativePath(path, ts.image);
+ let textureHandle = 0;
+ try {
+ const result = await ctx.loadTexture(imagePath, true);
+ textureHandle = result.handle;
+ } catch (e) {
+ console.warn(`[TilemapLoader] Failed to load tileset texture: ${imagePath}`, e);
+ }
+ tilesets.push({ textureHandle, columns: ts.columns });
+ }
+
+ registerTilemapSource(path, {
+ 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,
+ });
+
+ return { sourceId: path };
+ }
+
+ unload(_asset: TilemapResult): void {
+ // Tilemap sources registered globally
+ }
+}
diff --git a/sdk/src/asset/loaders/TimelineAssetLoader.ts b/sdk/src/asset/loaders/TimelineAssetLoader.ts
new file mode 100644
index 000000000..51d43e294
--- /dev/null
+++ b/sdk/src/asset/loaders/TimelineAssetLoader.ts
@@ -0,0 +1,38 @@
+import type { AssetLoader, LoadContext, TimelineResult } from '../AssetLoader';
+import { parseTimelineAsset, extractTimelineAssetPaths } from '../../timeline/TimelineLoader';
+import { registerTimelineAsset, registerTimelineTextureHandles } from '../../timeline/TimelinePlugin';
+
+export class TimelineAssetLoader implements AssetLoader<TimelineResult> {
+ readonly type = 'timeline';
+ readonly extensions = ['.estimeline'];
+
+ async load(path: string, ctx: LoadContext): Promise<TimelineResult> {
+ const buildPath = ctx.catalog.getBuildPath(path);
+ const text = await ctx.loadText(buildPath);
+ const raw = JSON.parse(text);
+ const asset = parseTimelineAsset(raw);
+ const paths = extractTimelineAssetPaths(asset);
+
+ const textureHandles = new Map<string, number>();
+ for (const texPath of paths.textures) {
+ try {
+ const result = await ctx.loadTexture(texPath, true);
+ textureHandles.set(texPath, result.handle);
+ } catch (e) {
+ console.warn(`[TimelineLoader] Failed to load texture: ${texPath}`, e);
+ textureHandles.set(texPath, 0);
+ }
+ }
+
+ registerTimelineAsset(path, asset);
+ if (textureHandles.size > 0) {
+ registerTimelineTextureHandles(path, textureHandles);
+ }
+
+ return { timelineId: path };
+ }
+
+ unload(_asset: TimelineResult): void {
+ // Timeline assets registered globally
+ }
+}
diff --git a/sdk/tests/asset-backend.test.ts b/sdk/tests/asset-backend.test.ts
new file mode 100644
index 000000000..c632a262c
--- /dev/null
+++ b/sdk/tests/asset-backend.test.ts
@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+import { EmbeddedBackend, HttpBackend } from '../src/asset/Backend';
+
+describe('HttpBackend', () => {
+ it('resolves relative paths with baseUrl', () => {
+ const backend = new HttpBackend({ baseUrl: 'http://localhost:3456/assets' });
+ expect(backend.resolveUrl('sprites/hero.png')).toBe('http://localhost:3456/assets/sprites/hero.png');
+ });
+
+ it('passes through absolute URLs', () => {
+ const backend = new HttpBackend({ baseUrl: 'http://localhost:3456' });
+ expect(backend.resolveUrl('https://cdn.example.com/image.png')).toBe('https://cdn.example.com/image.png');
+ expect(backend.resolveUrl('http://other.com/file.json')).toBe('http://other.com/file.json');
+ expect(backend.resolveUrl('/absolute/path.png')).toBe('/absolute/path.png');
+ });
+
+ it('strips trailing slashes from baseUrl', () => {
+ const backend = new HttpBackend({ baseUrl: 'http://localhost:3456/' });
+ expect(backend.resolveUrl('sprites/hero.png')).toBe('http://localhost:3456/sprites/hero.png');
+ });
+});
+
+describe('EmbeddedBackend', () => {
+ const textDataUrl = 'data:text/plain;base64,' + btoa('hello world');
+ const binaryDataUrl = 'data:application/octet-stream;base64,' + btoa('\x01\x02\x03');
+ const backend = new EmbeddedBackend({
+ 'config.txt': textDataUrl,
+ 'data.bin': binaryDataUrl,
+ });
+
+ it('fetchText decodes base64 data URL', async () => {
+ const text = await backend.fetchText('config.txt');
+ expect(text).toBe('hello world');
+ });
+
+ it('fetchBinary decodes base64 data URL', async () => {
+ const buffer = await backend.fetchBinary('data.bin');
+ const bytes = new Uint8Array(buffer);
+ expect(bytes).toEqual(new Uint8Array([1, 2, 3]));
+ });
+
+ it('throws on missing asset', async () => {
+ await expect(backend.fetchText('missing.txt')).rejects.toThrow('asset not found');
+ });
+
+ it('has returns true for existing assets', () => {
+ expect(backend.has('config.txt')).toBe(true);
+ expect(backend.has('missing.txt')).toBe(false);
+ });
+
+ it('resolveUrl returns data URL for existing assets', () => {
+ expect(backend.resolveUrl('config.txt')).toBe(textDataUrl);
+ });
+
+ it('resolveUrl returns path as-is for missing assets', () => {
+ expect(backend.resolveUrl('missing.txt')).toBe('missing.txt');
+ });
+});
diff --git a/sdk/tests/asset-field-registry.test.ts b/sdk/tests/asset-field-registry.test.ts
new file mode 100644
index 000000000..4caedb8bc
--- /dev/null
+++ b/sdk/tests/asset-field-registry.test.ts
@@ -0,0 +1,89 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+ registerAssetFields,
+ registerCompoundAssetFields,
+ getAssetFields,
+ getCompoundAssetFields,
+ getAllRegisteredComponents,
+ clearAssetFieldRegistry,
+ initBuiltinAssetFields,
+} from '../src/asset/AssetFieldRegistry';
+
+describe('AssetFieldRegistry', () => {
+ beforeEach(() => {
+ clearAssetFieldRegistry();
+ });
+
+ it('registers and retrieves single fields', () => {
+ registerAssetFields('Sprite', [
+ { field: 'texture', type: 'texture' },
+ { field: 'material', type: 'material' },
+ ]);
+
+ const fields = getAssetFields('Sprite');
+ expect(fields).toHaveLength(2);
+ expect(fields[0]).toEqual({ field: 'texture', type: 'texture' });
+ expect(fields[1]).toEqual({ field: 'material', type: 'material' });
+ });
+
+ it('registers and retrieves compound fields', () => {
+ registerCompoundAssetFields('SpineAnimation', {
+ type: 'spine',
+ fields: { skeleton: 'skeletonPath', atlas: 'atlasPath' },
+ });
+
+ const compounds = getCompoundAssetFields('SpineAnimation');
+ expect(compounds).toHaveLength(1);
+ expect(compounds[0].type).toBe('spine');
+ expect(compounds[0].fields).toEqual({ skeleton: 'skeletonPath', atlas: 'atlasPath' });
+ });
+
+ it('returns empty arrays for unregistered components', () => {
+ expect(getAssetFields('Unknown')).toEqual([]);
+ expect(getCompoundAssetFields('Unknown')).toEqual([]);
+ });
+
+ it('lists all registered components', () => {
+ registerAssetFields('Sprite', [{ field: 'texture', type: 'texture' }]);
+ registerAssetFields('Image', [{ field: 'texture', type: 'texture' }]);
+
+ const components = getAllRegisteredComponents();
+ expect(components).toContain('Sprite');
+ expect(components).toContain('Image');
+ });
+
+ it('initBuiltinAssetFields registers all known components', () => {
+ initBuiltinAssetFields();
+
+ const components = getAllRegisteredComponents();
+ expect(components).toContain('Sprite');
+ expect(components).toContain('SpineAnimation');
+ expect(components).toContain('BitmapText');
+ expect(components).toContain('Image');
+ expect(components).toContain('UIRenderer');
+ expect(components).toContain('SpriteAnimator');
+ expect(components).toContain('AudioSource');
+ expect(components).toContain('ParticleEmitter');
+ expect(components).toContain('Tilemap');
+ expect(components).toContain('TilemapLayer');
+ expect(components).toContain('TimelinePlayer');
+
+ const spineCompounds = getCompoundAssetFields('SpineAnimation');
+ expect(spineCompounds).toHaveLength(1);
+ expect(spineCompounds[0].type).toBe('spine');
+
+ const spineSingleFields = getAssetFields('SpineAnimation');
+ expect(spineSingleFields).toEqual([{ field: 'material', type: 'material' }]);
+ });
+
+ it('can register both fields and compounds for same component', () => {
+ registerAssetFields('MyComponent', [{ field: 'texture', type: 'texture' }]);
+ registerCompoundAssetFields('MyComponent', {
+ type: 'custom',
+ fields: { a: 'fieldA', b: 'fieldB' },
+ });
+
+ expect(getAssetFields('MyComponent')).toHaveLength(1);
+ expect(getCompoundAssetFields('MyComponent')).toHaveLength(1);
+ });
+});
diff --git a/sdk/tests/assets.test.ts b/sdk/tests/assets.test.ts
new file mode 100644
index 000000000..0ae47a1e6
--- /dev/null
+++ b/sdk/tests/assets.test.ts
@@ -0,0 +1,146 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Assets } from '../src/asset/Assets';
+import { Catalog, type CatalogData } from '../src/asset/Catalog';
+import type { Backend } from '../src/asset/Backend';
+import type { AssetLoader, LoadContext } from '../src/asset/AssetLoader';
+
+const mockModule = {
+ _malloc: vi.fn(() => 0),
+ _free: vi.fn(),
+ HEAPU8: new Uint8Array(1024),
+ GL: null,
+ FS: null,
+} as any;
+
+vi.mock('../src/resourceManager', () => ({
+ requireResourceManager: () => ({
+ createTexture: vi.fn(() => 42),
+ registerExternalTexture: vi.fn(() => 42),
+ releaseTexture: vi.fn(),
+ releaseBitmapFont: vi.fn(),
+ getTextureGLId: vi.fn(() => 1),
+ registerTextureWithPath: vi.fn(),
+ getTextureDimensions: vi.fn(() => ({ width: 64, height: 64 })),
+ }),
+ evictTextureDimensions: vi.fn(),
+}));
+
+vi.mock('../src/platform', () => ({
+ platformCreateCanvas: () => {
+ const canvas = {
+ width: 256, height: 256,
+ getContext: () => ({
+ clearRect: vi.fn(),
+ drawImage: vi.fn(),
+ getImageData: () => ({
+ data: { buffer: new ArrayBuffer(256 * 256 * 4) },
+ }),
+ }),
+ };
+ return canvas;
+ },
+ platformCreateImage: () => {
+ const img: any = {};
+ setTimeout(() => { img.width = 64; img.height = 64; img.onload?.(); }, 0);
+ return img;
+ },
+ platformFetch: vi.fn(),
+ platformReadFile: vi.fn(),
+ platformReadTextFile: vi.fn(),
+ platformFileExists: vi.fn(),
+}));
+
+function createMockBackend(): Backend {
+ return {
+ fetchBinary: vi.fn(async () => new ArrayBuffer(8)),
+ fetchText: vi.fn(async () => '{}'),
+ resolveUrl: vi.fn((path: string) => `http://test/${path}`),
+ };
+}
+
+const catalogData: CatalogData = {
+ version: 1,
+ entries: {
+ 'sprites/hero.png': {
+ type: 'texture',
+ atlas: 'atlas_0.png',
+ frame: { x: 0, y: 0, w: 64, h: 64 },
+ uv: { offset: [0, 0], scale: [0.5, 0.5] },
+ },
+ 'sprites/bg.png': { type: 'texture' },
+ },
+ addresses: {
+ 'hero': 'sprites/hero.png',
+ },
+ labels: {
+ 'icons': ['sprites/hero.png', 'sprites/bg.png'],
+ },
+};
+
+describe('Assets', () => {
+ let assets: Assets;
+ let backend: Backend;
+
+ beforeEach(() => {
+ backend = createMockBackend();
+ assets = Assets.create({
+ backend,
+ catalog: Catalog.fromJson(catalogData),
+ module: mockModule,
+ });
+ });
+
+ it('creates instance with catalog', () => {
+ expect(assets.catalog).toBeDefined();
+ expect(assets.backend).toBe(backend);
+ });
+
+ it('creates instance with empty catalog', () => {
+ const a = Assets.create({ backend, module: mockModule });
+ expect(a.catalog.isEmpty).toBe(true);
+ });
+
+ it('resolves address in getAtlasFrame', () => {
+ const frame = assets.getAtlasFrame('hero');
+ expect(frame).not.toBeNull();
+ expect(frame!.atlas).toBe('atlas_0.png');
+ expect(frame!.uvOffset).toEqual([0, 0]);
+ });
+
+ it('returns null atlas frame for non-atlas texture', () => {
+ expect(assets.getAtlasFrame('sprites/bg.png')).toBeNull();
+ });
+
+ describe('custom loader', () => {
+ interface CustomData { value: string }
+
+ const customLoader: AssetLoader<CustomData> = {
+ type: 'custom',
+ extensions: ['.custom'],
+ load: vi.fn(async (_path: string, ctx: LoadContext) => {
+ const text = await ctx.loadText(_path);
+ return { value: text };
+ }),
+ unload: vi.fn(),
+ };
+
+ it('registers and loads custom type', async () => {
+ (backend.fetchText as any).mockResolvedValue('hello custom');
+ assets.register(customLoader);
+ const result = await assets.load<CustomData>('custom', 'data/test.custom');
+ expect(result.value).toBe('hello custom');
+ });
+
+ it('throws for unregistered type', async () => {
+ await expect(assets.load('unknown', 'foo')).rejects.toThrow('No loader registered');
+ });
+ });
+
+ describe('fetchJson', () => {
+ it('fetches and parses JSON', async () => {
+ (backend.fetchText as any).mockResolvedValue('{"key": "value"}');
+ const result = await assets.fetchJson<{ key: string }>('config.json');
+ expect(result.key).toBe('value');
+ });
+ });
+});
diff --git a/sdk/tests/catalog.test.ts b/sdk/tests/catalog.test.ts
new file mode 100644
index 000000000..5a35d3357
--- /dev/null
+++ b/sdk/tests/catalog.test.ts
@@ -0,0 +1,123 @@
+import { describe, it, expect } from 'vitest';
+import { Catalog, type CatalogData } from '../src/asset/Catalog';
+
+const testData: CatalogData = {
+ version: 1,
+ entries: {
+ 'sprites/hero.png': {
+ type: 'texture',
+ atlas: 'atlas_0.png',
+ frame: { x: 100, y: 50, w: 64, h: 64 },
+ uv: { offset: [0.049, 0.024], scale: [0.031, 0.031] },
+ },
+ 'sprites/bg.png': {
+ type: 'texture',
+ },
+ 'characters/hero.skel': {
+ type: 'spine',
+ deps: ['characters/hero.atlas'],
+ },
+ 'materials/glow.esmaterial': {
+ type: 'material',
+ buildPath: 'materials/glow.json',
+ },
+ },
+ addresses: {
+ 'player_icon': 'sprites/hero.png',
+ 'glow_mat': 'materials/glow.esmaterial',
+ },
+ labels: {
+ 'ui-icons': ['sprites/hero.png', 'sprites/bg.png'],
+ },
+};
+
+describe('Catalog', () => {
+ const catalog = Catalog.fromJson(testData);
+
+ describe('resolve', () => {
+ it('resolves address to path', () => {
+ expect(catalog.resolve('player_icon')).toBe('sprites/hero.png');
+ expect(catalog.resolve('glow_mat')).toBe('materials/glow.esmaterial');
+ });
+
+ it('resolves known path to itself', () => {
+ expect(catalog.resolve('sprites/bg.png')).toBe('sprites/bg.png');
+ });
+
+ it('returns unknown ref as-is', () => {
+ expect(catalog.resolve('unknown/path.png')).toBe('unknown/path.png');
+ });
+ });
+
+ describe('getAtlasFrame', () => {
+ it('returns atlas info for packed texture', () => {
+ const frame = catalog.getAtlasFrame('sprites/hero.png');
+ expect(frame).toEqual({
+ atlas: 'atlas_0.png',
+ frame: { x: 100, y: 50, w: 64, h: 64 },
+ uvOffset: [0.049, 0.024],
+ uvScale: [0.031, 0.031],
+ });
+ });
+
+ it('returns null for non-atlas texture', () => {
+ expect(catalog.getAtlasFrame('sprites/bg.png')).toBeNull();
+ });
+
+ it('returns null for unknown path', () => {
+ expect(catalog.getAtlasFrame('unknown.png')).toBeNull();
+ });
+ });
+
+ describe('getBuildPath', () => {
+ it('returns mapped build path', () => {
+ expect(catalog.getBuildPath('materials/glow.esmaterial')).toBe('materials/glow.json');
+ });
+
+ it('returns original path when no mapping', () => {
+ expect(catalog.getBuildPath('sprites/bg.png')).toBe('sprites/bg.png');
+ expect(catalog.getBuildPath('unknown.png')).toBe('unknown.png');
+ });
+ });
+
+ describe('getDeps', () => {
+ it('returns dependencies', () => {
+ expect(catalog.getDeps('characters/hero.skel')).toEqual(['characters/hero.atlas']);
+ });
+
+ it('returns empty array for no deps', () => {
+ expect(catalog.getDeps('sprites/bg.png')).toEqual([]);
+ expect(catalog.getDeps('unknown.png')).toEqual([]);
+ });
+ });
+
+ describe('getByLabel', () => {
+ it('returns paths for label', () => {
+ expect(catalog.getByLabel('ui-icons')).toEqual(['sprites/hero.png', 'sprites/bg.png']);
+ });
+
+ it('returns empty array for unknown label', () => {
+ expect(catalog.getByLabel('unknown')).toEqual([]);
+ });
+ });
+
+ describe('empty catalog', () => {
+ const empty = Catalog.empty();
+
+ it('isEmpty is true', () => {
+ expect(empty.isEmpty).toBe(true);
+ });
+
+ it('resolve returns ref as-is', () => {
+ expect(empty.resolve('any/path.png')).toBe('any/path.png');
+ });
+
+ it('getAtlasFrame returns null', () => {
+ expect(empty.getAtlasFrame('any.png')).toBeNull();
+ });
+
+ it('getDeps returns empty', () => {
+ expect(empty.getDeps('any.skel')).toEqual([]);
+ });
+ });
+});
diff --git a/sdk/tests/scene-handle.test.ts b/sdk/tests/scene-handle.test.ts
new file mode 100644
index 000000000..067ddc915
--- /dev/null
+++ b/sdk/tests/scene-handle.test.ts
@@ -0,0 +1,36 @@
+import { describe, it, expect, vi } from 'vitest';
+import { SceneHandle } from '../src/asset/SceneHandle';
+
+describe('SceneHandle', () => {
+ it('stores entities', () => {
+ const handle = new SceneHandle([1, 2, 3], []);
+ expect(handle.entities).toEqual([1, 2, 3]);
+ });
+
+ it('calls release callbacks on release', () => {
+ const cb1 = vi.fn();
+ const cb2 = vi.fn();
+ const handle = new SceneHandle([1], [cb1, cb2]);
+
+ handle.release();
+
+ expect(cb1).toHaveBeenCalledOnce();
+ expect(cb2).toHaveBeenCalledOnce();
+ });
+
+ it('only releases once', () => {
+ const cb = vi.fn();
+ const handle = new SceneHandle([1], [cb]);
+
+ handle.release();
+ handle.release();
+
+ expect(cb).toHaveBeenCalledOnce();
+ expect(handle.isReleased).toBe(true);
+ });
+
+ it('isReleased is false initially', () => {
+ const handle = new SceneHandle([1], []);
+ expect(handle.isReleased).toBe(false);
+ });
+});