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.

fix(spine): route 4.2 through the side module in the runtime loader (S3 follow-up)

esengine6b5ebfa673fe
diff --git a/sdk/src/spine/loadSpineScene.ts b/sdk/src/spine/loadSpineScene.ts
index 622188c59..8a7e88dcd 100644
--- a/sdk/src/spine/loadSpineScene.ts
+++ b/sdk/src/spine/loadSpineScene.ts
@@ -8,12 +8,11 @@
* 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.
+ * Two phases are exposed separately so entity ids exist before binding: phase 1
+ * ({@link loadSpineAssets}) fetches + decodes assets and detects each version;
+ * phase 2 ({@link applySpineEntities}) loads them into the SpineManager after the
+ * scene spawns. Every version routes to its side-module backend — there is no
+ * native runtime. {@link loadSpineSceneEntities} is the combined convenience.
*/
import type { ESEngineModule } from '../wasm';
import type { Entity } from '../types';
@@ -46,36 +45,9 @@ function parseAtlasTextures(content: string): string[] {
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}.
+ * its runtime version. Keyed by `skeletonRef:atlasRef` for {@link applySpineEntities}.
*/
export async function loadSpineAssets(
module: ESEngineModule,
@@ -130,12 +102,6 @@ export async function loadSpineAssets(
}
}
- 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);
@@ -146,7 +112,7 @@ export async function loadSpineAssets(
/**
* 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
+ * SpineManager (every version loads its side-module backend) and apply the
* component's props, skin, and animation.
*/
export async function applySpineEntities(opts: {
@@ -168,7 +134,7 @@ export async function applySpineEntities(opts: {
if (!skelRef || !atlasRef) continue;
const info = assetInfo.get(`${skelRef}:${atlasRef}`);
- if (!info || !info.version || info.version === '4.2') continue;
+ if (!info || !info.version) continue;
const entity = entityMap.get(sceneEntity.id);
if (entity === undefined) continue;
diff --git a/sdk/tests/spine-apply-routing.test.ts b/sdk/tests/spine-apply-routing.test.ts
new file mode 100644
index 000000000..085d6901b
--- /dev/null
+++ b/sdk/tests/spine-apply-routing.test.ts
@@ -0,0 +1,74 @@
+/**
+ * @file spine-apply-routing.test.ts
+ * @brief Regression: after S3 (native runtime deleted), applySpineEntities must
+ * route EVERY version — including 4.2 — to the SpineManager. The pre-fix
+ * code skipped 4.2 (`version === '4.2'` → continue), a native-routing
+ * remnant that left 4.2 spine unrendered in the runtime/play path.
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { defineComponent, clearUserComponents } from '../src/component';
+import { applySpineEntities } from '../src/spine/loadSpineScene';
+import type { SceneData } from '../src/scene';
+import type { Entity } from '../src/types';
+
+const SPINE_COMP = 'ApplyRouting_Spine';
+
+beforeEach(() => {
+ clearUserComponents();
+ defineComponent(SPINE_COMP, { skeleton: '', atlas: '' }, {
+ spineFields: { skeletonField: 'skeleton', atlasField: 'atlas' },
+ });
+});
+
+function makeManager() {
+ return {
+ loadEntity: vi.fn(async () => '4.2'),
+ setEntityProps: vi.fn(),
+ setSkin: vi.fn(),
+ setAnimation: vi.fn(),
+ };
+}
+
+function sceneWith(skel: string, atlas: string): SceneData {
+ return {
+ version: 1,
+ entities: [{
+ id: 1,
+ components: [{ type: SPINE_COMP, data: { skeleton: skel, atlas, animation: 'walk' } }],
+ }],
+ } as unknown as SceneData;
+}
+
+describe('applySpineEntities routes every version to the SpineManager (S3)', () => {
+ it('loads a 4.2 entity — there is no native fallback to skip to', async () => {
+ const manager = makeManager();
+ const entity = 42 as Entity;
+ await applySpineEntities({
+ spineManager: manager as never,
+ sceneData: sceneWith('hero.skel', 'hero.atlas'),
+ entityMap: new Map([[1, entity]]),
+ registry: {} as never,
+ assetInfo: new Map([['hero.skel:hero.atlas', {
+ version: '4.2' as const, skelData: new Uint8Array(), atlasText: '', textures: new Map(),
+ }]]),
+ });
+ expect(manager.loadEntity).toHaveBeenCalledTimes(1);
+ expect(manager.loadEntity).toHaveBeenCalledWith(
+ entity, expect.anything(), '', expect.anything(), expect.anything());
+ expect(manager.setAnimation).toHaveBeenCalledWith(entity, 'walk', true);
+ });
+
+ it('still skips an asset with no detected version (no manager could load it)', async () => {
+ const manager = makeManager();
+ await applySpineEntities({
+ spineManager: manager as never,
+ sceneData: sceneWith('x.skel', 'x.atlas'),
+ entityMap: new Map([[1, 7 as Entity]]),
+ registry: {} as never,
+ assetInfo: new Map([['x.skel:x.atlas', {
+ version: null, skelData: new Uint8Array(), atlasText: '', textures: new Map(),
+ }]]),
+ });
+ expect(manager.loadEntity).not.toHaveBeenCalled();
+ });
+});