Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(sdk): WebSpineWasmProvider — browser loads the per-version spine side modules

esengine6779bec85344
diff --git a/sdk/src/spine/WebSpineWasmProvider.ts b/sdk/src/spine/WebSpineWasmProvider.ts
new file mode 100644
index 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.ts
index 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.ts
index 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, parseTimelineAss
export 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.ts
new file mode 100644
index 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\)/);
+ });
+});