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(sdk): WebSpineWasmProvider — browser loads the per-version spine side modules
esengine6779bec85344
diff --git a/sdk/src/spine/WebSpineWasmProvider.ts b/sdk/src/spine/WebSpineWasmProvider.tsnew file mode 100644index 000000000..98cdb7326--- /dev/null+++ b/sdk/src/spine/WebSpineWasmProvider.ts@@ -0,0 +1,41 @@+/**+ * @file WebSpineWasmProvider.ts+ * @brief Browser SpineWasmProvider — fetches the per-version spine side+ * modules (spine38.js/.wasm, spine41.js/.wasm, …) served alongside the+ * engine wasm, so the web runtime can run 3.8/4.1 assets and not only+ * the engine-linked 4.2. Wire it into createWebApp via the wasmBaseUrl+ * option (or pass an instance as spineProvider). WeChat uses its own+ * factory path (config.spineFactories), not this fetch-based provider.+ */+import type { SpineWasmProvider } from './SpineModuleLoader';++export class WebSpineWasmProvider implements SpineWasmProvider {+ private readonly baseUrl_: string;++ /**+ * @param baseUrl Directory the `spine{NN}.js`/`.wasm` files are served from —+ * typically the same directory as esengine.wasm. A trailing slash is optional.+ */+ constructor(baseUrl: string) {+ this.baseUrl_ = baseUrl.replace(/\/+$/, '');+ }++ /** Built artifacts are `spine38`/`spine41`/`spine42` (no separator). */+ private url(version: string, ext: 'js' | 'wasm'): string {+ return `${this.baseUrl_}/spine${version.replace('.', '')}.${ext}`;+ }++ async loadJs(version: string): Promise<string> {+ const url = this.url(version, 'js');+ const res = await fetch(url);+ if (!res.ok) throw new Error(`spine: failed to fetch ${url} (${res.status})`);+ return res.text();+ }++ async loadWasm(version: string): Promise<ArrayBuffer> {+ const url = this.url(version, 'wasm');+ const res = await fetch(url);+ if (!res.ok) throw new Error(`spine: failed to fetch ${url} (${res.status})`);+ return res.arrayBuffer();+ }+}diff --git a/sdk/src/spine/index.ts b/sdk/src/spine/index.tsindex 3553ccdb8..27e55220c 100644--- a/sdk/src/spine/index.ts+++ b/sdk/src/spine/index.ts@@ -8,3 +8,4 @@ export { SpineModuleController } from './SpineController';export type { SpineEventCallback, ConstraintList, TransformMixData, PathMixData } from './SpineController';export type { SpineModuleFactory, SpineWasmProvider } from './SpineModuleLoader';export { loadSpineModule, wrapSpineModule, createSpineFactories } from './SpineModuleLoader';+export { WebSpineWasmProvider } from './WebSpineWasmProvider';diff --git a/sdk/src/webAppFactory.ts b/sdk/src/webAppFactory.tsindex 2500e514e..c3b972f31 100644--- a/sdk/src/webAppFactory.ts+++ b/sdk/src/webAppFactory.ts@@ -10,7 +10,7 @@ import { postProcessPlugin } from './postprocess';import { timelinePlugin } from './timeline';import { timerPlugin } from './timer';import { lifecyclePlugin } from './lifecycle';-import { SpinePlugin } from './spine';+import { SpinePlugin, WebSpineWasmProvider } from './spine';import type { SpineWasmProvider } from './spine';export { uiPlugins };@@ -36,12 +36,21 @@ export { TimelinePlugin, timelinePlugin, registerTimelineAsset, parseTimelineAssexport interface CreateWebAppOptions extends WebAppOptions {spineProvider?: SpineWasmProvider;+ /**+ * Base URL the per-version spine side modules (spine38.js/.wasm, …) are served+ * from — usually the same directory as esengine.wasm. When set (and no explicit+ * spineProvider is given) a WebSpineWasmProvider is wired so 3.8/4.1 assets load+ * in the browser. Without either, only the engine-linked 4.2 runs.+ */+ wasmBaseUrl?: string;}const basePlugins = [timerPlugin, lifecyclePlugin(), animationPlugin, audioPlugin, particlePlugin, tilemapPlugin, postProcessPlugin, timelinePlugin];export function createWebApp(module: ESEngineModule, options?: CreateWebAppOptions): App {- const spinePlugin = new SpinePlugin(options?.spineProvider);+ const spineProvider = options?.spineProvider+ ?? (options?.wasmBaseUrl ? new WebSpineWasmProvider(options.wasmBaseUrl) : undefined);+ const spinePlugin = new SpinePlugin(spineProvider);const plugins = [...uiPlugins, ...basePlugins, spinePlugin, ...(options?.plugins ?? [])];return _createWebApp(module, { ...options, plugins });}diff --git a/sdk/tests/web-spine-provider.test.ts b/sdk/tests/web-spine-provider.test.tsnew file mode 100644index 000000000..eea5f2497--- /dev/null+++ b/sdk/tests/web-spine-provider.test.ts@@ -0,0 +1,44 @@+/**+ * @file web-spine-provider.test.ts+ * @brief WebSpineWasmProvider fetches the per-version spine side modules from+ * the configured base URL — the browser seam that lets 3.8/4.1 assets+ * load (createWebApp wires it from the wasmBaseUrl option).+ */+import { describe, it, expect, vi, afterEach } from 'vitest';+import { WebSpineWasmProvider } from '../src/spine/WebSpineWasmProvider';++afterEach(() => vi.unstubAllGlobals());++function mockFetch(body: { text?: string; bytes?: ArrayBuffer; ok?: boolean; status?: number }) {+ const fn = vi.fn(async (url: string) => ({+ ok: body.ok ?? true,+ status: body.status ?? 200,+ text: async () => body.text ?? '',+ arrayBuffer: async () => body.bytes ?? new ArrayBuffer(0),+ }));+ vi.stubGlobal('fetch', fn);+ return fn;+}++describe('WebSpineWasmProvider', () => {+ it('fetches spine{NN}.js as text from the base URL (trailing slash tolerated)', async () => {+ const fetchFn = mockFetch({ text: 'SPINE_JS_SOURCE' });+ const p = new WebSpineWasmProvider('/wasm/');+ expect(await p.loadJs('3.8')).toBe('SPINE_JS_SOURCE');+ expect(fetchFn).toHaveBeenCalledWith('/wasm/spine38.js');+ });++ it('fetches spine{NN}.wasm as an ArrayBuffer', async () => {+ const bytes = new Uint8Array([0, 0x61, 0x73, 0x6d]).buffer; // "\0asm"+ const fetchFn = mockFetch({ bytes });+ const p = new WebSpineWasmProvider('https://cdn.example.com/assets');+ expect(await p.loadWasm('4.1')).toBe(bytes);+ expect(fetchFn).toHaveBeenCalledWith('https://cdn.example.com/assets/spine41.wasm');+ });++ it('throws a clear error on a non-ok response instead of feeding garbage to the loader', async () => {+ mockFetch({ ok: false, status: 404 });+ const p = new WebSpineWasmProvider('/wasm');+ await expect(p.loadJs('4.2')).rejects.toThrow(/spine42\.js \(404\)/);+ });+});