A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
refactor(sdk): extract shared spine scene loader (single impl for runtime + editor)
esengine269da086444f
diff --git a/sdk/src/runtimeAssets.ts b/sdk/src/runtimeAssets.tsnew file mode 100644index 000000000..7d766ee29--- /dev/null+++ b/sdk/src/runtimeAssets.ts@@ -0,0 +1,48 @@+/**+ * @file runtimeAssets.ts+ * @brief Shared runtime asset primitives — the pluggable asset-fetch provider+ * interface and the decoded-pixels → GL texture upload — used by the+ * builder runtime loader and the spine scene loader (and any editor that+ * drives the same load path). Kept in its own module so neither the+ * runtime loader nor the spine loader has to import the other.+ */+import type { ESEngineModule } from './wasm';+import { requireResourceManager } from './resourceManager';+import { withMalloc } from './wasmScratch';++/** How the loader fetches scene assets on a given target (http, virtual FS, …). */+export interface RuntimeAssetProvider {+ loadPixels(ref: string): Promise<{ width: number; height: number; pixels: Uint8Array }>;+ loadPixelsRaw?(ref: string): Promise<{ width: number; height: number; pixels: Uint8Array }>;+ readText(ref: string): string | Promise<string>;+ readBinary(ref: string): Uint8Array | Promise<Uint8Array>;+ resolvePath(ref: string): string;+}++export interface TextureParams {+ filterMode?: string;+ wrapMode?: string;+}++const FILTER_MODE_MAP: Record<string, number> = { 'nearest': 0, 'linear': 1 };+const WRAP_MODE_MAP: Record<string, number> = { 'repeat': 0, 'clamp': 1, 'mirror': 2 };++/** Upload decoded RGBA pixels as a GL texture; returns the engine texture handle. */+export function createTextureFromPixels(+ module: ESEngineModule,+ result: { width: number; height: number; pixels: Uint8Array },+ flipY: boolean = true,+ params?: TextureParams,+): number {+ const rm = requireResourceManager();+ return withMalloc(module, result.pixels.length, ptr => {+ module.HEAPU8.set(result.pixels, ptr);++ if (params && (params.filterMode || params.wrapMode) && rm.createTextureEx) {+ const filter = FILTER_MODE_MAP[params.filterMode ?? 'linear'] ?? 1;+ const wrap = WRAP_MODE_MAP[params.wrapMode ?? 'clamp'] ?? 1;+ return rm.createTextureEx(result.width, result.height, ptr, result.pixels.length, 1, flipY, filter, wrap);+ }+ return rm.createTexture(result.width, result.height, ptr, result.pixels.length, 1, flipY);+ });+}diff --git a/sdk/src/runtimeLoader.ts b/sdk/src/runtimeLoader.tsindex 352e190b6..fe1f53ded 100644--- a/sdk/src/runtimeLoader.ts+++ b/sdk/src/runtimeLoader.ts@@ -5,11 +5,11 @@import { SceneOwner } from './component';import { Material } from './material';-import { loadSceneData, getComponentAssetFieldDescriptors, getComponentSpineFieldDescriptor, type AssetFieldType, type SceneData } from './scene';+import { loadSceneData, getComponentAssetFieldDescriptors, type AssetFieldType, type SceneData } from './scene';import { discoverSceneAssets, getAssetPathsByType } from './asset/discoverAssets';import type { ESEngineModule } from './wasm';import type { SpineWasmModule } from './spine/SpineModuleLoader';-import { SpineManager, type SpineVersion } from './spine/SpineManager';+import { SpineManager } from './spine/SpineManager';import type { PhysicsWasmModule } from './physics/PhysicsModuleLoader';import { PhysicsPlugin, type PhysicsPluginConfig } from './physics/PhysicsPlugin';import type { App } from './app';@@ -28,51 +28,21 @@ import { requireResourceManager } from './resourceManager';import { parseTmjJson, resolveRelativePath } from './tilemap/tiledLoader';import { registerTilemapSource } from './tilemap/tilesetCache';import { log } from './logger';-import { withMalloc } from './wasmScratch';+import { createTextureFromPixels, type RuntimeAssetProvider, type TextureParams } from './runtimeAssets';+import { loadSpineAssets, applySpineEntities } from './spine/loadSpineScene';// =============================================================================// Public Interface// =============================================================================-export interface RuntimeAssetProvider {- loadPixels(ref: string): Promise<{ width: number; height: number; pixels: Uint8Array }>;- loadPixelsRaw?(ref: string): Promise<{ width: number; height: number; pixels: Uint8Array }>;- readText(ref: string): string | Promise<string>;- readBinary(ref: string): Uint8Array | Promise<Uint8Array>;- resolvePath(ref: string): string;-}+// RuntimeAssetProvider + createTextureFromPixels live in ./runtimeAssets so the+// spine scene loader can share them without importing this module.+export type { RuntimeAssetProvider } from './runtimeAssets';// =============================================================================// Texture Helpers// =============================================================================-const FILTER_MODE_MAP: Record<string, number> = { 'nearest': 0, 'linear': 1 };-const WRAP_MODE_MAP: Record<string, number> = { 'repeat': 0, 'clamp': 1, 'mirror': 2 };--interface TextureParams {- filterMode?: string;- wrapMode?: string;-}--function createTextureFromPixels(- module: ESEngineModule,- result: { width: number; height: number; pixels: Uint8Array },- flipY: boolean = true,- params?: TextureParams,-): number {- const rm = requireResourceManager();- return withMalloc(module, result.pixels.length, ptr => {- module.HEAPU8.set(result.pixels, ptr);-- if (params && (params.filterMode || params.wrapMode) && rm.createTextureEx) {- const filter = FILTER_MODE_MAP[params.filterMode ?? 'linear'] ?? 1;- const wrap = WRAP_MODE_MAP[params.wrapMode ?? 'clamp'] ?? 1;- return rm.createTextureEx(result.width, result.height, ptr, result.pixels.length, 1, flipY, filter, wrap);- }- return rm.createTexture(result.width, result.height, ptr, result.pixels.length, 1, flipY);- });-}-async function loadTextures(module: ESEngineModule,sceneData: SceneData,@@ -140,121 +110,6 @@ function resolveSceneAssetPaths(}}-// =============================================================================-// Spine Helpers-// =============================================================================--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;-}--function ensureVirtualDir(module: ESEngineModule, virtualPath: string): void {- const fs = module.FS;- if (!fs) return;- const dir = virtualPath.substring(0, virtualPath.lastIndexOf('/'));- if (!dir) return;- const parts = dir.split('/').filter(p => p);- let currentPath = '';- for (const part of parts) {- currentPath += '/' + part;- try { fs.mkdir(currentPath); } catch { /* already exists */ }- }-}--function writeToVirtualFS(module: ESEngineModule, virtualPath: string, data: string | Uint8Array): boolean {- const fs = module.FS;- if (!fs) return false;- try {- ensureVirtualDir(module, virtualPath);- fs.writeFile(virtualPath, data);- return true;- } catch (e) {- log.warn('runtime', `Failed to write virtual FS: ${virtualPath}`, e);- return false;- }-}--interface SpineAssetInfo {- version: SpineVersion | null;- skelData: Uint8Array | string;- atlasText: string;- textures: Map<string, { glId: number; w: number; h: number }>;-}--async function loadSpineAssetsToVirtualFS(- module: ESEngineModule,- provider: RuntimeAssetProvider,- spineManager: SpineManager | null | undefined,- spinePairs: ReadonlyArray<{ skeleton: string; atlas: string }>,-): Promise<Map<string, SpineAssetInfo>> {- const assetInfoMap = new Map<string, SpineAssetInfo>();-- for (const pair of spinePairs) {- const skelRef = pair.skeleton;- const atlasRef = pair.atlas;- const cacheKey = `${skelRef}:${atlasRef}`;-- const atlasPath = provider.resolvePath(atlasRef);-- try {- const atlasContent = await provider.readText(atlasRef);-- const skelPath = provider.resolvePath(skelRef);- const isBinary = getAssetTypeEntry(skelPath)?.contentType === 'binary';- const skelData = isBinary- ? await provider.readBinary(skelRef)- : await provider.readText(skelRef);-- const version = spineManager- ? (typeof skelData === 'string'- ? SpineManager.detectVersionJson(skelData)- : SpineManager.detectVersion(skelData))- : null;-- const texNames = parseAtlasTextures(atlasContent);- const atlasDir = atlasPath.substring(0, atlasPath.lastIndexOf('/'));- const rm = requireResourceManager();- const textures = new Map<string, { glId: number; w: number; h: number }>();-- for (const texName of texNames) {- const texPath = atlasDir + '/' + texName;- try {- const result = provider.loadPixelsRaw- ? await provider.loadPixelsRaw(texPath)- : await provider.loadPixels(texPath);- const handle = createTextureFromPixels(module, result, false);- rm.registerTextureWithPath(handle, texPath);- textures.set(texName, {- glId: rm.getTextureGLId(handle),- w: result.width,- h: result.height,- });- } catch (err) {- log.warn('runtime', `Failed to load texture: ${texPath}`, err);- }- }-- const isNative = !version || version === '4.2';- if (isNative) {- writeToVirtualFS(module, atlasPath, atlasContent);- writeToVirtualFS(module, skelPath, skelData);- }-- assetInfoMap.set(cacheKey, { version, skelData, atlasText: atlasContent, textures });- } catch (err) {- log.warn('runtime', `Failed to load spine asset: skel=${skelRef} atlas=${atlasRef}`, err);- }- }- return assetInfoMap;-}-// =============================================================================// BitmapFont Helpers// =============================================================================@@ -475,7 +330,7 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promisconst textureCache = await loadTextures(module, sceneData, provider, getAssetPathsByType(discovered, 'texture'));applyTextureMetadata(sceneData, textureCache);- const spineAssetInfo = await loadSpineAssetsToVirtualFS(module, provider, spineManager, discovered.spines);+ const spineAssetInfo = await loadSpineAssets(module, provider, spineManager, discovered.spines);if (physicsModule) {const config: PhysicsPluginConfig = {@@ -504,39 +359,8 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis(module as ESEngineModule).transform_update(cppRegistry);}- if (spineManager && cppRegistry && spineAssetInfo.size > 0) {- for (const sceneEntity of sceneData.entities) {- for (const comp of sceneEntity.components) {- const spineDesc = getComponentSpineFieldDescriptor(comp.type);- if (!spineDesc || !comp.data) continue;- const skelRef = comp.data[spineDesc.skeletonField] as string;- const atlasRef = comp.data[spineDesc.atlasField] as string;- if (!skelRef || !atlasRef) continue;-- const cacheKey = `${skelRef}:${atlasRef}`;- const info = spineAssetInfo.get(cacheKey);- if (!info || !info.version || info.version === '4.2') continue;-- const entity = entityMap.get(sceneEntity.id);- if (entity === undefined) continue;-- await spineManager.loadEntity(- entity, info.skelData, info.atlasText, info.textures, cppRegistry);-- spineManager.setEntityProps(entity, {- skeletonScale: (comp.data.skeletonScale as number) ?? 1,- flipX: (comp.data.flipX as boolean) ?? false,- flipY: (comp.data.flipY as boolean) ?? false,- layer: (comp.data.layer as number) ?? 0,- });- const skin = comp.data.skin as string;- if (skin) spineManager.setSkin(entity, skin);- const animation = comp.data.animation as string;- if (animation) {- spineManager.setAnimation(entity, animation, comp.data.loop !== false);- }- }- }+ if (spineManager && cppRegistry) {+ await applySpineEntities({ spineManager, sceneData, entityMap, registry: cppRegistry, assetInfo: spineAssetInfo });}if (sceneName && app.hasResource(SceneManager)) {diff --git a/sdk/src/spine/index.ts b/sdk/src/spine/index.tsindex 27e55220c..da325c0d3 100644--- a/sdk/src/spine/index.ts+++ b/sdk/src/spine/index.ts@@ -9,3 +9,7 @@ export type { SpineEventCallback, ConstraintList, TransformMixData, PathMixDataexport type { SpineModuleFactory, SpineWasmProvider } from './SpineModuleLoader';export { loadSpineModule, wrapSpineModule, createSpineFactories } from './SpineModuleLoader';export { WebSpineWasmProvider } from './WebSpineWasmProvider';+// Shared spine scene loader — the editor loads spine entities through the same+// single implementation the builder runtime uses (see ./loadSpineScene).+export { loadSpineSceneEntities, loadSpineAssets, applySpineEntities } from './loadSpineScene';+export type { RuntimeAssetProvider } from '../runtimeAssets';diff --git a/sdk/src/spine/loadSpineScene.ts b/sdk/src/spine/loadSpineScene.tsnew file mode 100644index 000000000..622188c59--- /dev/null+++ b/sdk/src/spine/loadSpineScene.ts@@ -0,0 +1,217 @@+/**+ * @file loadSpineScene.ts+ * @brief Shared spine scene loader. For every SpineAnimation entity in a scene+ * it fetches the skeleton/atlas/textures through the asset provider and+ * hands them to the SpineManager — the single spine runtime+ * implementation — then applies the component's props/skin/animation.+ * Both the builder runtime loader and the editor scene loader call this,+ * so spine loads identically on every target instead of being+ * re-implemented per host.+ *+ * Two phases are exposed separately because the runtime must preserve ordering:+ * the native (4.2) path writes the skeleton/atlas to the virtual FS during+ * {@link loadSpineAssets} BEFORE the scene spawns, while {@link applySpineEntities}+ * runs after, once entity ids exist. {@link loadSpineSceneEntities} is the+ * combined convenience for hosts (the editor) that only drive the 3.8/4.1 JS+ * runtimes, where that ordering doesn't matter.+ */+import type { ESEngineModule } from '../wasm';+import type { Entity } from '../types';+import { getComponentSpineFieldDescriptor, type SceneData } from '../scene';+import { discoverSceneAssets } from '../asset/discoverAssets';+import { getAssetTypeEntry } from '../assetTypes';+import { requireResourceManager } from '../resourceManager';+import { log } from '../logger';+import { SpineManager, type SpineVersion } from './SpineManager';+import { createTextureFromPixels, type RuntimeAssetProvider } from '../runtimeAssets';++/** The opaque C++ registry handle SpineManager.loadEntity expects (app.world.getCppRegistry()). */+type CppRegistry = Parameters<SpineManager['loadEntity']>[4];++interface SpineAssetInfo {+ version: SpineVersion | null;+ skelData: Uint8Array | string;+ atlasText: string;+ textures: Map<string, { glId: number; w: number; h: number }>;+}++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;+}++function ensureVirtualDir(module: ESEngineModule, virtualPath: string): void {+ const fs = module.FS;+ if (!fs) return;+ const dir = virtualPath.substring(0, virtualPath.lastIndexOf('/'));+ if (!dir) return;+ const parts = dir.split('/').filter(p => p);+ let currentPath = '';+ for (const part of parts) {+ currentPath += '/' + part;+ try { fs.mkdir(currentPath); } catch { /* already exists */ }+ }+}++function writeToVirtualFS(module: ESEngineModule, virtualPath: string, data: string | Uint8Array): boolean {+ const fs = module.FS;+ if (!fs) return false;+ try {+ ensureVirtualDir(module, virtualPath);+ fs.writeFile(virtualPath, data);+ return true;+ } catch (e) {+ log.warn('runtime', `Failed to write virtual FS: ${virtualPath}`, e);+ return false;+ }+}++/**+ * Phase 1 — fetch + decode each spine pair's skeleton/atlas/textures and detect+ * its runtime version. Native (4.2) pairs are also written to the virtual FS for+ * the C++ runtime. Keyed by `skeletonRef:atlasRef` for {@link applySpineEntities}.+ */+export async function loadSpineAssets(+ module: ESEngineModule,+ provider: RuntimeAssetProvider,+ spineManager: SpineManager | null | undefined,+ spinePairs: ReadonlyArray<{ skeleton: string; atlas: string }>,+): Promise<Map<string, SpineAssetInfo>> {+ const assetInfoMap = new Map<string, SpineAssetInfo>();++ for (const pair of spinePairs) {+ const skelRef = pair.skeleton;+ const atlasRef = pair.atlas;+ const cacheKey = `${skelRef}:${atlasRef}`;++ const atlasPath = provider.resolvePath(atlasRef);++ try {+ const atlasContent = await provider.readText(atlasRef);++ const skelPath = provider.resolvePath(skelRef);+ const isBinary = getAssetTypeEntry(skelPath)?.contentType === 'binary';+ const skelData = isBinary+ ? await provider.readBinary(skelRef)+ : await provider.readText(skelRef);++ const version = spineManager+ ? (typeof skelData === 'string'+ ? SpineManager.detectVersionJson(skelData)+ : SpineManager.detectVersion(skelData))+ : null;++ const texNames = parseAtlasTextures(atlasContent);+ const atlasDir = atlasPath.substring(0, atlasPath.lastIndexOf('/'));+ const rm = requireResourceManager();+ const textures = new Map<string, { glId: number; w: number; h: number }>();++ for (const texName of texNames) {+ const texPath = atlasDir + '/' + texName;+ try {+ const result = provider.loadPixelsRaw+ ? await provider.loadPixelsRaw(texPath)+ : await provider.loadPixels(texPath);+ const handle = createTextureFromPixels(module, result, false);+ rm.registerTextureWithPath(handle, texPath);+ textures.set(texName, {+ glId: rm.getTextureGLId(handle),+ w: result.width,+ h: result.height,+ });+ } catch (err) {+ log.warn('runtime', `Failed to load texture: ${texPath}`, err);+ }+ }++ const isNative = !version || version === '4.2';+ if (isNative) {+ writeToVirtualFS(module, atlasPath, atlasContent);+ writeToVirtualFS(module, skelPath, skelData);+ }++ assetInfoMap.set(cacheKey, { version, skelData, atlasText: atlasContent, textures });+ } catch (err) {+ log.warn('runtime', `Failed to load spine asset: skel=${skelRef} atlas=${atlasRef}`, err);+ }+ }+ return assetInfoMap;+}++/**+ * Phase 2 — for each SpineAnimation entity, route its loaded asset to the+ * SpineManager (3.8/4.1 JS runtimes; 4.2 stays under C++ control) and apply the+ * component's props, skin, and animation.+ */+export async function applySpineEntities(opts: {+ spineManager: SpineManager;+ sceneData: SceneData;+ entityMap: Map<number, Entity>;+ registry: CppRegistry;+ assetInfo: Map<string, SpineAssetInfo>;+}): Promise<void> {+ const { spineManager, sceneData, entityMap, registry, assetInfo } = opts;+ if (assetInfo.size === 0) return;++ for (const sceneEntity of sceneData.entities) {+ for (const comp of sceneEntity.components) {+ const spineDesc = getComponentSpineFieldDescriptor(comp.type);+ if (!spineDesc || !comp.data) continue;+ const skelRef = comp.data[spineDesc.skeletonField] as string;+ const atlasRef = comp.data[spineDesc.atlasField] as string;+ if (!skelRef || !atlasRef) continue;++ const info = assetInfo.get(`${skelRef}:${atlasRef}`);+ if (!info || !info.version || info.version === '4.2') continue;++ const entity = entityMap.get(sceneEntity.id);+ if (entity === undefined) continue;++ await spineManager.loadEntity(entity, info.skelData, info.atlasText, info.textures, registry);++ spineManager.setEntityProps(entity, {+ skeletonScale: (comp.data.skeletonScale as number) ?? 1,+ flipX: (comp.data.flipX as boolean) ?? false,+ flipY: (comp.data.flipY as boolean) ?? false,+ layer: (comp.data.layer as number) ?? 0,+ });+ const skin = comp.data.skin as string;+ if (skin) spineManager.setSkin(entity, skin);+ const animation = comp.data.animation as string;+ if (animation) {+ spineManager.setAnimation(entity, animation, comp.data.loop !== false);+ }+ }+ }+}++/**+ * Combined convenience: discover spine pairs in the scene, load their assets, and+ * apply them to the spawned entities. For hosts (the editor) driving the 3.8/4.1+ * JS runtimes, where the native virtual-FS ordering doesn't apply.+ */+export async function loadSpineSceneEntities(opts: {+ module: ESEngineModule;+ provider: RuntimeAssetProvider;+ spineManager: SpineManager;+ sceneData: SceneData;+ entityMap: Map<number, Entity>;+ registry: CppRegistry;+}): Promise<void> {+ const discovered = discoverSceneAssets(opts.sceneData);+ if (discovered.spines.length === 0) return;+ const assetInfo = await loadSpineAssets(opts.module, opts.provider, opts.spineManager, discovered.spines);+ await applySpineEntities({+ spineManager: opts.spineManager,+ sceneData: opts.sceneData,+ entityMap: opts.entityMap,+ registry: opts.registry,+ assetInfo,+ });+}