A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat: add unified Assets architecture (Backend/Catalog/Loader registry)
esengine8bede5b8fb32
diff --git a/sdk/src/asset/AssetFieldRegistry.ts b/sdk/src/asset/AssetFieldRegistry.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ });+});