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(spine): 2.1, for projects still authored in a 2015 editor

yhh37a3c4dc0fee
diff --git a/.gitmodules b/.gitmodules
index d52e5edd7..4c8969257 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -44,3 +44,6 @@
path = third_party/spine-runtimes-4.3
url = https://github.com/EsotericSoftware/spine-runtimes.git
branch = 4.3
+[submodule "third_party/spine-runtimes-2.1"]
+ path = third_party/spine-runtimes-2.1
+ url = https://github.com/EsotericSoftware/spine-runtimes.git
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 80cd3d3f2..41c697efa 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -312,6 +312,7 @@ if(ES_BUILD_WEB OR ES_BUILD_WXGAME)
es_add_spine_module(spine_module_43 4.3 spine43)
es_add_spine_module(spine_module_41 4.1 spine41)
es_add_spine_module(spine_module_38 3.8 spine38)
+ es_add_spine_module(spine_module_21 2.1 spine21)
endif()
# Basis Universal KTX2 transcoder module (compressed textures — RC6)
diff --git a/build-tools/build.config.js b/build-tools/build.config.js
index 27067f31e..a7f7e5f88 100644
--- a/build-tools/build.config.js
+++ b/build-tools/build.config.js
@@ -99,6 +99,15 @@ export default {
'sdk/spine41.wasm': 'wasm/web/spine41.wasm',
},
},
+ spine21: {
+ buildDir: 'build-web',
+ cmakeFlags: ['-DES_BUILD_WEB=ON', '-DES_BUILD_TESTS=OFF', '-DES_ENABLE_WEBGPU=ON'],
+ targets: ['spine_module_21'],
+ outputs: {
+ 'sdk/spine21.js': 'wasm/web/spine21.js',
+ 'sdk/spine21.wasm': 'wasm/web/spine21.wasm',
+ },
+ },
spine43: {
buildDir: 'build-web',
cmakeFlags: ['-DES_BUILD_WEB=ON', '-DES_BUILD_TESTS=OFF', '-DES_ENABLE_WEBGPU=ON'],
@@ -143,7 +152,7 @@ export default {
'spine-wechat': {
buildDir: 'build-spine-wechat',
cmakeFlags: ['-DES_BUILD_WXGAME=ON', '-DES_BUILD_TESTS=OFF'],
- targets: ['spine_module', 'spine_module_43', 'spine_module_41', 'spine_module_38'],
+ targets: ['spine_module', 'spine_module_43', 'spine_module_41', 'spine_module_38', 'spine_module_21'],
outputs: {
'sdk/spine42.js': 'wasm/wechat/spine42.js',
'sdk/spine42.wasm': 'wasm/wechat/spine42.wasm',
@@ -153,6 +162,8 @@ export default {
'sdk/spine41.wasm': 'wasm/wechat/spine41.wasm',
'sdk/spine38.js': 'wasm/wechat/spine38.js',
'sdk/spine38.wasm': 'wasm/wechat/spine38.wasm',
+ 'sdk/spine21.js': 'wasm/wechat/spine21.js',
+ 'sdk/spine21.wasm': 'wasm/wechat/spine21.wasm',
},
},
},
diff --git a/build-tools/cli.js b/build-tools/cli.js
index 43eef87ff..5d08b9f7d 100644
--- a/build-tools/cli.js
+++ b/build-tools/cli.js
@@ -28,7 +28,7 @@ program
program
.command('build')
.description('Build ESEngine')
- .option('-t, --target <target>', 'Build target (web, wechat, spine, spine38, spine41, spine43, physics, physics-wechat, spine-wechat, basis, basis-wechat, sdk, all)', 'web')
+ .option('-t, --target <target>', 'Build target (web, wechat, spine, spine21, spine38, spine41, spine43, physics, physics-wechat, spine-wechat, basis, basis-wechat, sdk, all)', 'web')
.option('-d, --debug', 'Debug build', false)
.option('-r, --release', 'Release build (default)', true)
.option('-c, --clean', 'Clean before build', false)
@@ -52,7 +52,7 @@ program
const isDebug = options.debug && !options.release;
const targets = options.target === 'all'
- ? ['web', 'wechat', 'spine', 'spine38', 'spine41', 'spine43', 'physics', 'physics-wechat', 'spine-wechat', 'basis', 'basis-wechat', 'videodec', 'videodec-wechat']
+ ? ['web', 'wechat', 'spine', 'spine21', 'spine38', 'spine41', 'spine43', 'physics', 'physics-wechat', 'spine-wechat', 'basis', 'basis-wechat', 'videodec', 'videodec-wechat']
: [options.target];
if (options.clean) {
diff --git a/cmake/Emscripten.cmake b/cmake/Emscripten.cmake
index c96970aac..310d859e8 100644
--- a/cmake/Emscripten.cmake
+++ b/cmake/Emscripten.cmake
@@ -317,7 +317,9 @@ endfunction()
# exported ABI are shared across releases; what differs is the runtime's own sources
# and the backend that speaks to them — and the tree's shape says which:
#
-# 3.8 / 4.1 / 4.2 spine-c/spine-c/{src,include} the pure-C runtime
+# 2.1 spine-c/{src,include} the pure-C runtime, before it
+# was nested a level deeper
+# 3.8 / 4.1 / 4.2 spine-c/spine-c/{src,include} the same runtime, nested
# 4.3+ spine-cpp/{src,include} 4.3 regenerated spine-c as a
# wrapper over C++, so bind C++
#
@@ -347,6 +349,13 @@ function(es_add_spine_module TARGET_NAME VERSION OUTPUT_NAME)
# so -Os halves the module (615 KB -> 333 KB) with no measurable frame cost:
# 50 skeletons x 400 frames came out at 0.71 ms/frame against -O3's 0.76.
set(_opt -Os)
+ elseif(EXISTS "${_root}/spine-c/include/spine")
+ # 2.1: the same C runtime one directory up, and a dialect far enough from 3.8
+ # that it gets its own backend rather than an `#if` through that one.
+ set(_backend "${_bindings}/SpineRuntime21.cpp")
+ set(_include "${_root}/spine-c/include")
+ file(GLOB_RECURSE _runtime "${_root}/spine-c/src/spine/*.c")
+ set(_opt -O3)
else()
message(FATAL_ERROR
"Spine ${VERSION} is checked out at ${_root} but neither spine-c nor "
diff --git a/desktop/electron/sideModuleScan.ts b/desktop/electron/sideModuleScan.ts
index aad8ef737..bb71ffdf0 100644
--- a/desktop/electron/sideModuleScan.ts
+++ b/desktop/electron/sideModuleScan.ts
@@ -46,7 +46,7 @@ export function sceneUsesVideo(scene: SceneLike): boolean {
return false;
}
-export type SpineVersion = '3.8' | '4.1' | '4.2' | '4.3';
+export type SpineVersion = '2.1' | '3.8' | '4.1' | '4.2' | '4.3';
/**
* Which runtime reads a skeleton's reported version, newest prefix first — the same
@@ -58,6 +58,7 @@ const VERSION_PREFIXES: ReadonlyArray<readonly [string, SpineVersion]> = [
['4.2', '4.2'],
['4.1', '4.1'],
['3.', '3.8'],
+ ['2.1', '2.1'],
];
function runtimeFor(reported: string): SpineVersion | null {
@@ -72,6 +73,7 @@ export const SIDE_MODULE_FILE: Record<string, string> = {
physics: 'physics',
basis: 'basis',
videodec: 'videodec',
+ 'spine:2.1': 'spine21',
'spine:3.8': 'spine38',
'spine:4.1': 'spine41',
'spine:4.2': 'spine42',
@@ -83,6 +85,7 @@ export const WECHAT_MODULE_BUILD_TARGET: Record<string, string> = {
physics: 'physics-wechat',
basis: 'basis-wechat',
videodec: 'videodec-wechat',
+ 'spine:2.1': 'spine-wechat',
'spine:3.8': 'spine-wechat',
'spine:4.1': 'spine-wechat',
'spine:4.2': 'spine-wechat',
@@ -136,5 +139,5 @@ function tryRead3xVersion(data: Uint8Array): SpineVersion | null {
pos += vb;
if (verLen <= 1 || pos + verLen - 1 > data.length) return null;
const ver = new TextDecoder().decode(data.subarray(pos, pos + verLen - 1));
- return ver.startsWith('3.') ? runtimeFor(ver) : null;
+ return (ver.startsWith('3.') || ver.startsWith('2.')) ? runtimeFor(ver) : null;
}
diff --git a/desktop/src/project/format.ts b/desktop/src/project/format.ts
index 1d77b9e0b..601d7111b 100644
--- a/desktop/src/project/format.ts
+++ b/desktop/src/project/format.ts
@@ -234,7 +234,7 @@ export interface ProjectManifest {
defaultScene?: string;
/** Design resolution for the viewport / camera. */
designResolution?: DesignResolution;
- /** Spine runtime the project needs ('none' | '3.8' | '4.1' | '4.2' | '4.3' …). */
+ /** Spine runtime the project needs ('none' | '2.1' | '3.8' | '4.1' | '4.2' | '4.3' …). */
spineVersion?: string;
/** Per-path overrides of {@link DEFAULT_LAYOUT}. */
layout?: Partial<ProjectLayout>;
diff --git a/docs/astro/src/content/docs/guides/build-export.mdx b/docs/astro/src/content/docs/guides/build-export.mdx
index dfd9fc0ad..b1239a07f 100644
--- a/docs/astro/src/content/docs/guides/build-export.mdx
+++ b/docs/astro/src/content/docs/guides/build-export.mdx
@@ -199,7 +199,7 @@ the base engine stays small:
| Module | Artifacts | Loaded when |
|---|---|---|
| Physics (Box2D) | `physics.js` / `physics.wasm` | The project declares physics or a scene uses physics components. |
-| Spine | `spine38` / `spine41` / `spine42` `.js`/`.wasm` | A scene uses a Spine skeleton of that format version. |
+| Spine | `spine21` / `spine38` / `spine41` / `spine42` / `spine43` `.js`/`.wasm` | A scene uses a Spine skeleton of that format version. |
| Basis transcoder | `basis.js` / `basis.wasm` | The build shipped KTX2-compressed textures. |
| Video decoder | `videodec.js` / `videodec.wasm` | The wasm video path decodes a clip. |
diff --git a/docs/astro/src/content/docs/guides/spine.mdx b/docs/astro/src/content/docs/guides/spine.mdx
index 4eb176697..fd0c925e3 100644
--- a/docs/astro/src/content/docs/guides/spine.mdx
+++ b/docs/astro/src/content/docs/guides/spine.mdx
@@ -141,9 +141,10 @@ const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {
machine**, which can target Spine as well as sprites.
<Aside type="note">
- Estella supports Spine **3.8 / 4.1 / 4.2** — each skeleton version loads its own
- WebAssembly backend on demand (pay-for-use), which is why `Spine` and
- `SpineEvents` live on the `esengine/spine` subpath.
+ Estella supports Spine **2.1 / 3.8 / 4.1 / 4.2 / 4.3** — each skeleton version loads
+ its own WebAssembly backend on demand (pay-for-use), which is why `Spine` and
+ `SpineEvents` live on the `esengine/spine` subpath. A 2.1 skeleton must be exported
+ as JSON: that release's runtime shipped no reader for its own binary format.
</Aside>
<Aside type="caution">
diff --git a/docs/astro/src/content/docs/guides/wechat.mdx b/docs/astro/src/content/docs/guides/wechat.mdx
index 7b0cb46af..33dc48ee4 100644
--- a/docs/astro/src/content/docs/guides/wechat.mdx
+++ b/docs/astro/src/content/docs/guides/wechat.mdx
@@ -17,7 +17,7 @@ The WeChat target compiles the C++ core with WeChat's `WXWebAssembly` shims:
node build-tools/cli.js build -t wechat
# side modules, only if your game uses them:
node build-tools/cli.js build -t physics-wechat # physics
-node build-tools/cli.js build -t spine-wechat # Spine (builds 3.8 + 4.1 + 4.2)
+node build-tools/cli.js build -t spine-wechat # Spine (builds 2.1 + 3.8 + 4.1 + 4.2 + 4.3)
node build-tools/cli.js build -t basis-wechat # KTX2 / compressed textures
node build-tools/cli.js build -t videodec-wechat # video (MPEG-1 wasm decoder)
```
diff --git a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx b/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
index cd5f9d07d..1128f90a5 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
@@ -169,7 +169,7 @@ node build-tools/cli.js build -t wechat
| 模块 | 产物 | 何时加载 |
|---|---|---|
| 物理(Box2D) | `physics.js` / `physics.wasm` | 项目声明了物理,或场景使用了物理组件。 |
-| Spine | `spine38` / `spine41` / `spine42` 的 `.js`/`.wasm` | 场景使用了对应格式版本的 Spine 骨骼。 |
+| Spine | `spine21` / `spine38` / `spine41` / `spine42` / `spine43` 的 `.js`/`.wasm` | 场景使用了对应格式版本的 Spine 骨骼。 |
| Basis 转码器 | `basis.js` / `basis.wasm` | 构建里发布了 KTX2 压缩纹理。 |
| 视频解码器 | `videodec.js` / `videodec.wasm` | wasm 视频路径解码片段时。 |
diff --git a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx b/docs/astro/src/content/docs/zh-cn/guides/spine.mdx
index 137ffad77..b18dc6717 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/spine.mdx
@@ -129,8 +129,9 @@ const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {
- **用 [Animator](/docs/zh-cn/guides/animation/) 状态机驱动整个角色**,它既能驱动 Spine 也能驱动精灵。
<Aside type="note">
- Estella 支持 Spine **3.8 / 4.1 / 4.2**——每个骨骼版本按需加载自己的 WebAssembly 后端
- (按需付费),这也是 `Spine` 与 `SpineEvents` 位于 `esengine/spine` 子路径的原因。
+ Estella 支持 Spine **2.1 / 3.8 / 4.1 / 4.2 / 4.3**——每个骨骼版本按需加载自己的
+ WebAssembly 后端(按需付费),这也是 `Spine` 与 `SpineEvents` 位于 `esengine/spine`
+ 子路径的原因。2.1 的骨骼需导出为 JSON:该版本的运行时没有附带自己二进制格式的读取器。
</Aside>
<Aside type="caution">
diff --git a/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx b/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx
index 314eebade..9cd81559d 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx
@@ -16,7 +16,7 @@ Estella 能把同一个项目导出为**微信小游戏**。你为微信目标
node build-tools/cli.js build -t wechat
# 侧模块,仅当你的游戏用到时:
node build-tools/cli.js build -t physics-wechat # 物理
-node build-tools/cli.js build -t spine-wechat # Spine(一次构建 3.8 + 4.1 + 4.2)
+node build-tools/cli.js build -t spine-wechat # Spine(一次构建 2.1 + 3.8 + 4.1 + 4.2 + 4.3)
node build-tools/cli.js build -t basis-wechat # KTX2 / 压缩纹理
node build-tools/cli.js build -t videodec-wechat # 视频(MPEG-1 wasm 解码器)
```
diff --git a/native/CMakeLists.txt b/native/CMakeLists.txt
index 46cede43b..53bd2f7cd 100644
--- a/native/CMakeLists.txt
+++ b/native/CMakeLists.txt
@@ -79,8 +79,9 @@ add_subdirectory("${TP}/box2d" "${CMAKE_BINARY_DIR}/box2d" EXCLUDE_FROM_ALL)
#
# Which backend goes with which release is the tree's shape, exactly as the web build
# reads it (es_add_spine_module in cmake/Emscripten.cmake): 3.8 - 4.2 vendor the pure-C
-# runtime, 4.3 replaced it with a generated wrapper so we bind spine-cpp instead.
-set(ESTELLA_SPINE_VERSION "4.2" CACHE STRING "Spine runtime to link (4.3 / 4.2 / 4.1 / 3.8)")
+# runtime nested a level deep, 2.1 the same runtime flat and in a dialect of its own,
+# and 4.3 replaced it with a generated wrapper so we bind spine-cpp instead.
+set(ESTELLA_SPINE_VERSION "4.2" CACHE STRING "Spine runtime to link (4.3 / 4.2 / 4.1 / 3.8 / 2.1)")
set(SPINE_ROOT "${TP}/spine-runtimes-${ESTELLA_SPINE_VERSION}")
if(EXISTS "${SPINE_ROOT}/spine-c/spine-c/include")
set(SPINE_BACKEND "${SRC}/esengine/bindings/SpineRuntimeC.cpp")
@@ -90,9 +91,13 @@ elseif(EXISTS "${SPINE_ROOT}/spine-cpp/include")
set(SPINE_BACKEND "${SRC}/esengine/bindings/SpineRuntimeCpp.cpp")
set(SPINE_INCLUDE "${SPINE_ROOT}/spine-cpp/include")
file(GLOB SPINE_SOURCES "${SPINE_ROOT}/spine-cpp/src/spine/*.cpp")
+elseif(EXISTS "${SPINE_ROOT}/spine-c/include/spine")
+ set(SPINE_BACKEND "${SRC}/esengine/bindings/SpineRuntime21.cpp")
+ set(SPINE_INCLUDE "${SPINE_ROOT}/spine-c/include")
+ file(GLOB SPINE_SOURCES "${SPINE_ROOT}/spine-c/src/spine/*.c")
else()
message(FATAL_ERROR "Spine runtime ${ESTELLA_SPINE_VERSION} not vendored at ${SPINE_ROOT}. "
- "Pass -DESTELLA_SPINE_VERSION=<4.3|4.2|4.1|3.8>.")
+ "Pass -DESTELLA_SPINE_VERSION=<4.3|4.2|4.1|3.8|2.1>.")
endif()
add_library(spine_runtime STATIC ${SPINE_SOURCES})
diff --git a/native/README.md b/native/README.md
index 043e443a7..b3abcf2e6 100644
--- a/native/README.md
+++ b/native/README.md
@@ -81,13 +81,14 @@ their binding headers. `app.sideModules` still answers them, so the runtime's ow
gating installs physics or spine exactly as it does in a browser (see
`sdk/src/ecs/nativeSideModules.ts`).
-Spine is the one build-time choice: the vendored runtimes (3.8 / 4.1 / 4.2 / 4.3)
+Spine is the one build-time choice: the vendored runtimes (2.1 / 3.8 / 4.1 / 4.2 / 4.3)
export the same symbol names, so a binary carries exactly one.
`-DESTELLA_SPINE_VERSION=4.1` picks another; `spine_runtimeVersion()` reports what
was linked, and content authored against a different release is told so by name
instead of being decoded by the wrong parser. Which runtime backend a release uses
-follows from its tree: 3.8 through 4.2 vendor the pure-C runtime, while 4.3 replaced
-it with a generated wrapper, so that one binds spine-cpp (and picks up spine's own
+follows from its tree: 3.8 through 4.2 vendor the pure-C runtime, 2.1 vendors it flat
+and in a dialect old enough to warrant its own backend, and 4.3 replaced it with a
+generated wrapper, so that one binds spine-cpp (and picks up spine's own
SkeletonRenderer with it).
## Why this works (the architecture, proven on device)
diff --git a/sdk/etc/spine.api.md b/sdk/etc/spine.api.md
index 09e13e286..149a4d0ca 100644
--- a/sdk/etc/spine.api.md
+++ b/sdk/etc/spine.api.md
@@ -197,7 +197,7 @@ static prototype: SpinePlugin
## SpineVersion — type
```
-'3.8' | '4.1' | '4.2' | '4.3'
+'2.1' | '3.8' | '4.1' | '4.2' | '4.3'
```
## TransformMixData — interface
diff --git a/sdk/src/sideModules/registry.ts b/sdk/src/sideModules/registry.ts
index c5b24a048..7de903cab 100644
--- a/sdk/src/sideModules/registry.ts
+++ b/sdk/src/sideModules/registry.ts
@@ -15,7 +15,7 @@
*/
/** Spine skeleton format versions Estella ships a dedicated runtime for. */
-export type SpineVersion = '3.8' | '4.1' | '4.2' | '4.3';
+export type SpineVersion = '2.1' | '3.8' | '4.1' | '4.2' | '4.3';
/** Identifies an optional native module across every realm and transport. */
export type SideModuleId = 'physics' | 'basis' | 'videodec' | `spine:${SpineVersion}`;
@@ -40,13 +40,14 @@ export const SIDE_MODULES: Record<SideModuleId, SideModuleDescriptor> = {
// MPEG-1 software video decoder (pl_mpeg) — the engine-owned decode path
// behind the wasm video backend on runtimes without a reliable native decoder.
videodec: { file: 'videodec', globalName: 'ESVideoModule' },
+ 'spine:2.1': { file: 'spine21', globalName: 'ESSpineModule' },
'spine:3.8': { file: 'spine38', globalName: 'ESSpineModule' },
'spine:4.1': { file: 'spine41', globalName: 'ESSpineModule' },
'spine:4.2': { file: 'spine42', globalName: 'ESSpineModule' },
'spine:4.3': { file: 'spine43', globalName: 'ESSpineModule' },
};
-export const SPINE_VERSIONS: readonly SpineVersion[] = ['3.8', '4.1', '4.2', '4.3'];
+export const SPINE_VERSIONS: readonly SpineVersion[] = ['2.1', '3.8', '4.1', '4.2', '4.3'];
/** The {@link SideModuleId} carrying a given spine skeleton version. */
export function spineModuleId(version: SpineVersion): SideModuleId {
diff --git a/sdk/src/spine/SpineManager.ts b/sdk/src/spine/SpineManager.ts
index 55af63e24..0970ba0a9 100644
--- a/sdk/src/spine/SpineManager.ts
+++ b/sdk/src/spine/SpineManager.ts
@@ -25,6 +25,7 @@ const VERSION_PREFIXES: ReadonlyArray<readonly [string, SpineVersion]> = [
['4.2', '4.2'],
['4.1', '4.1'],
['3.', '3.8'],
+ ['2.1', '2.1'],
];
function runtimeFor(reported: string): SpineVersion | null {
@@ -353,7 +354,7 @@ function tryRead4xVersion(data: Uint8Array): SpineVersion | null {
return ver.startsWith('4.') ? runtimeFor(ver) : null;
}
-/** 3.x length-prefixed the hash too, so the version string sits just after it. */
+/** 3.x and 2.1 both length-prefix the hash, so the version string sits just after it. */
function tryRead3xVersion(data: Uint8Array): SpineVersion | null {
if (data.length < 4) return null;
let pos = 0;
@@ -365,5 +366,5 @@ function tryRead3xVersion(data: Uint8Array): SpineVersion | null {
pos += vb;
if (verLen <= 1 || pos + verLen - 1 > data.length) return null;
const ver = new TextDecoder().decode(data.subarray(pos, pos + verLen - 1));
- return ver.startsWith('3.') ? runtimeFor(ver) : null;
+ return (ver.startsWith('3.') || ver.startsWith('2.')) ? runtimeFor(ver) : null;
}
diff --git a/sdk/tests/sideModuleHost.test.ts b/sdk/tests/sideModuleHost.test.ts
index c62d91006..567b575d4 100644
--- a/sdk/tests/sideModuleHost.test.ts
+++ b/sdk/tests/sideModuleHost.test.ts
@@ -22,7 +22,7 @@ describe('side-module registry', () => {
it('spineModuleId covers every shipped version', () => {
expect(SPINE_VERSIONS.map(spineModuleId))
- .toEqual(['spine:3.8', 'spine:4.1', 'spine:4.2', 'spine:4.3']);
+ .toEqual(['spine:2.1', 'spine:3.8', 'spine:4.1', 'spine:4.2', 'spine:4.3']);
// Every id the versions produce has to be a module the loader knows how to fetch.
for (const version of SPINE_VERSIONS) {
expect(SIDE_MODULES[spineModuleId(version)]).toBeDefined();
diff --git a/sdk/tests/spine-multi-version-build.test.ts b/sdk/tests/spine-multi-version-build.test.ts
index 1df8627bf..8516e796a 100644
--- a/sdk/tests/spine-multi-version-build.test.ts
+++ b/sdk/tests/spine-multi-version-build.test.ts
@@ -90,7 +90,9 @@ describe('Spine multi-version build pipeline', () => {
['{"spine":"4.2.10"}', '4.2'],
['{"spine":"4.1.20"}', '4.1'],
['{"spine":"3.8.99"}', '3.8'],
+ ['{"spine":"2.1.27"}', '2.1'],
['{"spine":"3.7.94"}', '3.8'], // pre-3.8 data loads on the 3.8 runtime
+ ['{"spine":"2.0.18"}', null], // 2.0 is its own format; 2.1 will not read it
['{"spine":"5.0.0"}', null], // no runtime vendored: fail, don't guess
['{"skeleton":{}}', null],
];
diff --git a/sdk/tests/spine-version-detect.test.ts b/sdk/tests/spine-version-detect.test.ts
index 4508de8c3..65e8b33bd 100644
--- a/sdk/tests/spine-version-detect.test.ts
+++ b/sdk/tests/spine-version-detect.test.ts
@@ -48,6 +48,11 @@ describe('SpineManager.detectVersion', () => {
expect(SpineManager.detectVersion(data)).toBe('4.1');
});
+ it('detects a 2.1 binary header, which is shaped like 3.x', () => {
+ const data = make3xSkel('abc123', '2.1.27');
+ expect(SpineManager.detectVersion(data)).toBe('2.1');
+ });
+
it('detects 3.8 binary', () => {
const data = make3xSkel('abc123', '3.8.99');
expect(SpineManager.detectVersion(data)).toBe('3.8');
@@ -80,6 +85,10 @@ describe('SpineManager.detectVersionJson', () => {
expect(SpineManager.detectVersionJson('{"spine": "3.8.99"}')).toBe('3.8');
});
+ it('detects 2.1 json', () => {
+ expect(SpineManager.detectVersionJson('{"spine": "2.1.27"}')).toBe('2.1');
+ });
+
it('returns null for missing spine field', () => {
expect(SpineManager.detectVersionJson('{"version": "1.0"}')).toBeNull();
});
diff --git a/sdk/tests/spine21-load.integration.test.ts b/sdk/tests/spine21-load.integration.test.ts
new file mode 100644
index 000000000..7bb38103a
--- /dev/null
+++ b/sdk/tests/spine21-load.integration.test.ts
@@ -0,0 +1,187 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file spine21-load.integration.test.ts
+ * @brief The 2.1 side module, driven against exports of that era.
+ *
+ * @details 2.1 is the far end of the runtime seam: colour is four loose floats, a
+ * weighted mesh is its own attachment type, and triangle indices are `int`
+ * where the engine's buffers are 16-bit. Those are the three places a
+ * plausible-looking backend goes wrong silently, so they are what this
+ * drives — with the runtime's own spineboy (regions) and goblins (meshes,
+ * including a weighted one).
+ *
+ * Requires the built spine21 module (node build-tools/cli.js build -t
+ * spine21) and the spine-runtimes-2.1 submodule; skips otherwise.
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { WASM_DIR } from './helpers/loadWasm';
+import { wrapSpineModule, type SpineWasmModule } from '../src/spine/SpineModuleLoader';
+import { SpineModuleController } from '../src/spine/SpineController';
+
+const SPINE21_JS = resolve(WASM_DIR, 'spine21.js');
+const SPINE21_WASM = resolve(WASM_DIR, 'spine21.wasm');
+const ROOT = resolve(__dirname, '../../third_party/spine-runtimes-2.1');
+const BOY_JSON = resolve(ROOT, 'spine-c/data/spineboy.json');
+const BOY_ATLAS = resolve(ROOT, 'spine-c/data/spineboy.atlas');
+const GOBLINS_JSON = resolve(ROOT, 'spine-as3/spine-as3-example/src/goblins-mesh.json');
+const GOBLINS_ATLAS = resolve(ROOT, 'spine-as3/spine-as3-example/src/goblins-mesh.atlas');
+const HAS_ASSETS = existsSync(SPINE21_WASM) && existsSync(BOY_JSON);
+
+interface Batch {
+ vertexCount: number;
+ indices: number[];
+ rgba: [number, number, number, number];
+}
+
+describe.skipIf(!HAS_ASSETS)('Spine 2.1 side module', () => {
+ let raw: SpineWasmModule;
+ let controller: SpineModuleController;
+
+ beforeAll(async () => {
+ const wasmBinary = readFileSync(SPINE21_WASM);
+ const factory = (await import(SPINE21_JS)).default as (a: { wasmBinary: Uint8Array }) => Promise<SpineWasmModule>;
+ raw = await factory({ wasmBinary });
+ controller = new SpineModuleController(raw, wrapSpineModule(raw));
+ });
+
+ function load(jsonPath: string, atlasPath: string): number {
+ const atlasText = readFileSync(atlasPath, 'utf8');
+ const handle = controller.loadSkeleton(readFileSync(jsonPath, 'utf8'), atlasText, false);
+ expect(controller.getLastError()).toBe('');
+ expect(handle).toBeGreaterThan(0);
+
+ const size = atlasText.match(/size:\s*(\d+)\s*,\s*(\d+)/);
+ for (let page = 0; page < controller.getAtlasPageCount(handle); page++) {
+ controller.setAtlasPageTexture(handle, page, /*fake glId*/ 1,
+ size ? Number(size[1]) : 1024, size ? Number(size[2]) : 1024);
+ }
+ return handle;
+ }
+
+ function batchesOf(instance: number): Batch[] {
+ const batches: Batch[] = [];
+ controller.forEachMeshBatch(instance, (vertBytes, idxBytes, vertexCount, indexCount) => {
+ const f32 = new Float32Array(vertBytes.buffer, vertBytes.byteOffset, vertexCount * 8);
+ const u16 = new Uint16Array(idxBytes.buffer, idxBytes.byteOffset, indexCount);
+ batches.push({
+ vertexCount,
+ indices: Array.from(u16),
+ rgba: [f32[4], f32[5], f32[6], f32[7]],
+ });
+ });
+ return batches;
+ }
+
+ it('is the 2.1 runtime', () => {
+ const runtimeVersion = raw.cwrap('spine_runtimeVersion', 'number', []) as () => number;
+ expect(runtimeVersion()).toBe(21);
+ });
+
+ it('parses a 2.1 JSON export and exposes its animations', () => {
+ // Every later runtime rejects this file: the format changed with 3.0.
+ const handle = load(BOY_JSON, BOY_ATLAS);
+ const instance = controller.createInstance(handle);
+ expect(instance).toBeGreaterThan(0);
+ expect(controller.getAnimations(instance)).toEqual(
+ expect.arrayContaining(['walk', 'run', 'idle', 'jump']),
+ );
+ controller.destroyInstance(instance);
+ controller.unloadSkeleton(handle);
+ });
+
+ it('says which export setting to change when handed a binary skeleton', () => {
+ // 2.1's editor could write .skel, but its C runtime shipped no reader — so the
+ // module has to name the fix rather than fail as a corrupt file.
+ const handle = controller.loadSkeleton(
+ new Uint8Array([1, 2, 3, 4]), readFileSync(BOY_ATLAS, 'utf8'), true);
+ expect(handle).toBeLessThan(0);
+ expect(controller.getLastError()).toContain('JSON');
+ });
+
+ it('advances the walk animation — a limb bone moves over time', () => {
+ const handle = load(BOY_JSON, BOY_ATLAS);
+ const instance = controller.createInstance(handle);
+ expect(controller.play(instance, 'walk', true)).toBe(true);
+
+ controller.update(instance, 0.0);
+ const before = controller.getBonePosition(instance, 'front_foot');
+ controller.update(instance, 0.4);
+ const after = controller.getBonePosition(instance, 'front_foot');
+
+ expect(before).not.toBeNull();
+ expect(after).not.toBeNull();
+ const moved = Math.abs(after!.x - before!.x) + Math.abs(after!.y - before!.y);
+ expect(moved).toBeGreaterThan(0.5);
+
+ controller.destroyInstance(instance);
+ controller.unloadSkeleton(handle);
+ });
+
+ it('unpacks a tinted colour channel by channel', () => {
+ // 2.1 keeps colour as four loose floats rather than a struct, which is its own
+ // chance to write one channel into another.
+ const handle = load(BOY_JSON, BOY_ATLAS);
+ const instance = controller.createInstance(handle);
+ controller.update(instance, 0);
+ controller.setSkeletonColor(instance, 1.0, 0.4, 0.0, 0.8);
+
+ const [first] = batchesOf(instance);
+ expect(first).toBeDefined();
+ expect(first.rgba[0]).toBeCloseTo(1.0, 2);
+ expect(first.rgba[1]).toBeCloseTo(0.4, 2);
+ expect(first.rgba[2]).toBeCloseTo(0.0, 2);
+ expect(first.rgba[3]).toBeCloseTo(0.8, 2);
+
+ controller.destroyInstance(instance);
+ controller.unloadSkeleton(handle);
+ });
+
+ it('poses meshes and the weighted mesh 2.1 keeps as its own attachment type', () => {
+ const handle = load(GOBLINS_JSON, GOBLINS_ATLAS);
+ const instance = controller.createInstance(handle);
+ expect(controller.getSkins(instance)).toEqual(
+ expect.arrayContaining(['goblin', 'goblingirl']),
+ );
+
+ controller.setSkin(instance, 'goblin');
+ controller.play(instance, 'walk', true);
+ controller.update(instance, 0.1);
+
+ const batches = batchesOf(instance);
+ expect(batches.length).toBeGreaterThan(0);
+
+ // A mesh is more than a quad, so posing them at all shows up as geometry no
+ // region-only skeleton could produce.
+ const vertices = batches.reduce((n, b) => n + b.vertexCount, 0);
+ expect(vertices).toBeGreaterThan(4 * batches.length);
+
+ // 2.1 indexes triangles with `int`; these buffers are 16-bit. A narrowing that
+ // lost the value, or a rebase that forgot the batch offset, lands out of range.
+ for (const batch of batches) {
+ expect(batch.indices.length % 3).toBe(0);
+ for (const index of batch.indices) {
+ expect(index).toBeLessThan(batch.vertexCount);
+ }
+ }
+
+ controller.destroyInstance(instance);
+ controller.unloadSkeleton(handle);
+ });
+
+ it('reports a bounding box around the posed skeleton', () => {
+ const handle = load(BOY_JSON, BOY_ATLAS);
+ const instance = controller.createInstance(handle);
+ controller.play(instance, 'idle', true);
+ controller.update(instance, 0.2);
+
+ const bounds = controller.getBounds(instance);
+ expect(bounds.width).toBeGreaterThan(0);
+ expect(bounds.height).toBeGreaterThan(0);
+
+ controller.destroyInstance(instance);
+ controller.unloadSkeleton(handle);
+ });
+});
diff --git a/src/esengine/bindings/SpineRuntime21.cpp b/src/esengine/bindings/SpineRuntime21.cpp
new file mode 100644
index 000000000..37a33a988
--- /dev/null
+++ b/src/esengine/bindings/SpineRuntime21.cpp
@@ -0,0 +1,551 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file SpineRuntime21.cpp
+ * @brief The SpineRuntime backend for spine-c 2.1, the runtime a 2015 editor exports for.
+ *
+ * @details 2.1 predates most of what SpineRuntimeC.cpp assumes: colour is four loose
+ * floats rather than a struct, a slot blends additively or not at all, weighted
+ * meshes are their own attachment type, triangle indices are `int`, and the
+ * event listener is handed a track index instead of the entry. Threading that
+ * through the 3.8-4.2 backend would mean an `#if` around nearly every line, so
+ * it is its own backend — which is what the seam is for.
+ *
+ * What 2.1 does NOT have is as load-bearing as what it does: no clipping
+ * attachments, no transform or path constraints, and no binary skeleton
+ * reader. The first two answer empty; the third is reported as the export
+ * setting it is, because a 2.1 editor can write JSON and this runtime reads it.
+ *
+ * @author ESEngine Team
+ * @date 2026
+ *
+ * @copyright Copyright (c) 2026 ESEngine Team
+ * Licensed under the Apache License, Version 2.0.
+ */
+
+#include "SpineRuntime.hpp"
+
+#include <spine/spine.h>
+#include <spine/extension.h>
+
+#include <cstring>
+#include <vector>
+
+#if ES_SPINE_VERSION != 21
+#error "SpineRuntime21.cpp is the spine-c 2.1 backend; build it with ES_SPINE_VERSION=21."
+#endif
+
+// =============================================================================
+// spine-c Required Callbacks
+// =============================================================================
+//
+// As in the 3.8+ backend: the SDK owns atlas pages and registers their texture ids,
+// and the module never touches a filesystem.
+
+void _spAtlasPage_createTexture(spAtlasPage* self, const char* path) {
+ (void)self;
+ (void)path;
+}
+
+void _spAtlasPage_disposeTexture(spAtlasPage* self) {
+ (void)self;
+}
+
+char* _spUtil_readFile(const char* path, int* length) {
+ (void)path;
+ *length = 0;
+ return nullptr;
+}
+
+namespace es::spine {
+
+struct Skeleton {
+ spAtlas* atlas = nullptr;
+ spSkeletonData* data = nullptr;
+ spAnimationStateData* stateData = nullptr;
+
+ Skeleton() = default;
+ Skeleton(const Skeleton&) = delete;
+ Skeleton& operator=(const Skeleton&) = delete;
+
+ ~Skeleton() {
+ if (stateData) spAnimationStateData_dispose(stateData);
+ if (data) spSkeletonData_dispose(data);
+ if (atlas) spAtlas_dispose(atlas);
+ }
+};
+
+struct Instance {
+ spSkeleton* skeleton = nullptr;
+ spAnimationState* state = nullptr;
+
+ Instance() = default;
+ Instance(const Instance&) = delete;
+ Instance& operator=(const Instance&) = delete;
+
+ ~Instance() {
+ if (state) spAnimationState_dispose(state);
+ if (skeleton) spSkeleton_dispose(skeleton);
+ }
+};
+
+void destroy(Skeleton* skeleton) { delete skeleton; }
+void destroy(Instance* instance) { delete instance; }
+
+namespace {
+
+std::vector<float> g_worldVertices;
+/// 2.1 indexes triangles with `int`; the engine's vertex buffers are 16-bit.
+std::vector<uint16_t> g_indices;
+
+EventSink g_eventSink = nullptr;
+
+const uint16_t QUAD_INDICES[6] = {0, 1, 2, 2, 3, 0};
+
+spAtlasPage* pageAt(const Skeleton* skeleton, int index) {
+ if (!skeleton || index < 0) return nullptr;
+ spAtlasPage* page = skeleton->atlas->pages;
+ for (int i = 0; i < index && page; ++i) page = page->next;
+ return page;
+}
+
+/// Attachments point straight at their atlas region, whose page carries the id.
+uint32_t textureOf(const void* rendererObject) {
+ auto* region = reinterpret_cast<const spAtlasRegion*>(rendererObject);
+ if (!region || !region->page) return 0;
+ return static_cast<uint32_t>(reinterpret_cast<uintptr_t>(region->page->rendererObject));
+}
+
+void widenIndices(const int* triangles, int count) {
+ g_indices.resize(static_cast<size_t>(count));
+ for (int i = 0; i < count; ++i) {
+ g_indices[static_cast<size_t>(i)] = static_cast<uint16_t>(triangles[i]);
+ }
+}
+
+/** One slot's posed geometry, in the shared scratch buffers. */
+struct Posed {
+ const float* positions = nullptr;
+ const float* uvs = nullptr;
+ const uint16_t* indices = nullptr;
+ int vertexCount = 0;
+ int indexCount = 0;
+ uint32_t texture = 0;
+ float color[4] = {1.0f, 1.0f, 1.0f, 1.0f};
+};
+
+/**
+ * Pose whatever the slot is showing. Region, mesh and weighted mesh differ in how
+ * their vertices are computed and in nothing else, so both render() and bounds()
+ * read them through here rather than each walking the three cases.
+ */
+bool pose(spSlot* slot, Posed& out) {
+ spAttachment* attachment = slot->attachment;
+ if (!attachment) return false;
+
+ switch (attachment->type) {
+ case SP_ATTACHMENT_REGION: {
+ auto* region = reinterpret_cast<spRegionAttachment*>(attachment);
+ out.texture = textureOf(region->rendererObject);
+ if (!out.texture) return false;
+
+ g_worldVertices.resize(8);
+ spRegionAttachment_computeWorldVertices(region, slot->bone, g_worldVertices.data());
+ out.positions = g_worldVertices.data();
+ out.uvs = region->uvs;
+ out.indices = QUAD_INDICES;
+ out.vertexCount = 4;
+ out.indexCount = 6;
+ out.color[0] = region->r;
+ out.color[1] = region->g;
+ out.color[2] = region->b;
+ out.color[3] = region->a;
+ return true;
+ }
+ case SP_ATTACHMENT_MESH: {
+ auto* mesh = reinterpret_cast<spMeshAttachment*>(attachment);
+ out.texture = textureOf(mesh->rendererObject);
+ if (!out.texture) return false;
+
+ // verticesCount counts floats, not vertices.
+ g_worldVertices.resize(static_cast<size_t>(mesh->verticesCount));
+ spMeshAttachment_computeWorldVertices(mesh, slot, g_worldVertices.data());
+ widenIndices(mesh->triangles, mesh->trianglesCount);
+ out.positions = g_worldVertices.data();
+ out.uvs = mesh->uvs;
+ out.indices = g_indices.data();
+ out.vertexCount = mesh->verticesCount / 2;
+ out.indexCount = mesh->trianglesCount;
+ out.color[0] = mesh->r;
+ out.color[1] = mesh->g;
+ out.color[2] = mesh->b;
+ out.color[3] = mesh->a;
+ return true;
+ }
+ case SP_ATTACHMENT_SKINNED_MESH: {
+ // 3.x folded weighted meshes back into the mesh attachment; in 2.1 they
+ // are a separate type, sized by their UVs rather than by source vertices.
+ auto* mesh = reinterpret_cast<spSkinnedMeshAttachment*>(attachment);
+ out.texture = textureOf(mesh->rendererObject);
+ if (!out.texture) return false;
+
+ g_worldVertices.resize(static_cast<size_t>(mesh->uvsCount));
+ spSkinnedMeshAttachment_computeWorldVertices(mesh, slot, g_worldVertices.data());
+ widenIndices(mesh->triangles, mesh->trianglesCount);
+ out.positions = g_worldVertices.data();
+ out.uvs = mesh->uvs;
+ out.indices = g_indices.data();
+ out.vertexCount = mesh->uvsCount / 2;
+ out.indexCount = mesh->trianglesCount;
+ out.color[0] = mesh->r;
+ out.color[1] = mesh->g;
+ out.color[2] = mesh->b;
+ out.color[3] = mesh->a;
+ return true;
+ }
+ default:
+ return false; // bounding boxes draw nothing
+ }
+}
+
+EventKind kindOf(spEventType type) {
+ switch (type) {
+ case SP_ANIMATION_START: return EventKind::Start;
+ case SP_ANIMATION_END: return EventKind::End;
+ case SP_ANIMATION_COMPLETE: return EventKind::Complete;
+ default: return EventKind::Event;
+ }
+}
+
+/// 2.1 hands the listener a track index rather than the entry, so the animation's
+/// name is looked up rather than read off one. loopCount has no counterpart in the
+/// SDK's event shape, which reports a completion per loop either way.
+void eventListener(spAnimationState* state, int trackIndex, spEventType type,
+ spEvent* event, int loopCount) {
+ (void)loopCount;
+ if (!g_eventSink) return;
+
+ Event out;
+ out.kind = kindOf(type);
+ out.track = trackIndex;
+
+ spTrackEntry* entry = spAnimationState_getCurrent(state, trackIndex);
+ if (entry && entry->animation) out.animation = entry->animation->name;
+
+ if (type == SP_ANIMATION_EVENT && event) {
+ out.floatValue = event->floatValue;
+ out.intValue = event->intValue;
+ out.name = event->data->name;
+ out.stringValue = event->stringValue;
+ }
+ g_eventSink(out);
+}
+
+} // namespace
+
+// =============================================================================
+// Resources
+// =============================================================================
+
+Skeleton* loadSkeleton(const void* skeletonData, int length,
+ const char* atlasText, int atlasLength,
+ bool binary, std::string& error) {
+ if (binary) {
+ // Spine 2.1 could export .skel, but its C runtime shipped no reader for it —
+ // so the fix is an export setting, and saying which one is the whole job here.
+ error = "Spine 2.1 binary skeletons are not supported: re-export from Spine "
+ "with the skeleton data format set to JSON.";
+ return nullptr;
+ }
+
+ auto skeleton = std::make_unique<Skeleton>();
+
+ skeleton->atlas = spAtlas_create(atlasText, atlasLength, "", nullptr);
+ if (!skeleton->atlas || !skeleton->atlas->pages) {
+ error = "Failed to create atlas (invalid atlas text or no pages)";
+ return nullptr;
+ }
+
+ spSkeletonJson* reader = spSkeletonJson_create(skeleton->atlas);
+ if (!reader) {
+ error = "Failed to create skeleton json reader";
+ return nullptr;
+ }
+ reader->scale = 1.0f;
+ skeleton->data = spSkeletonJson_readSkeletonData(
+ reader, static_cast<const char*>(skeletonData));
+ if (!skeleton->data && reader->error) error = reader->error;
+ spSkeletonJson_dispose(reader);
+ (void)length; // the JSON reader takes a NUL-terminated string
+
+ if (!skeleton->data) return nullptr;
+
+ skeleton->stateData = spAnimationStateData_create(skeleton->data);
+ skeleton->stateData->defaultMix = 0.2f;
+ return skeleton.release();
+}
+
+int atlasPageCount(const Skeleton* skeleton) {
+ if (!skeleton) return 0;
+ int count = 0;
+ for (spAtlasPage* page = skeleton->atlas->pages; page; page = page->next) ++count;
+ return count;
+}
+
+const char* atlasPageName(const Skeleton* skeleton, int page) {
+ spAtlasPage* p = pageAt(skeleton, page);
+ return p ? p->name : nullptr;
+}
+
+void setAtlasPageTexture(Skeleton* skeleton, int page, uint32_t texture, int width, int height) {
+ spAtlasPage* p = pageAt(skeleton, page);
+ if (!p) return;
+
+ // Attachments reach the id through their region's page, so setting it here is
+ // enough — 4.0's second copy on the region did not exist yet.
+ p->rendererObject = reinterpret_cast<void*>(static_cast<uintptr_t>(texture));
+ p->width = width;
+ p->height = height;
+}
+
+void setDefaultMix(Skeleton* skeleton, float seconds) {
+ if (skeleton && skeleton->stateData) skeleton->stateData->defaultMix = seconds;
+}
+
+void setMixDuration(Skeleton* skeleton, const char* from, const char* to, float seconds) {
+ if (!skeleton || !skeleton->stateData) return;
+ spAnimation* a = spSkeletonData_findAnimation(skeleton->data, from);
+ spAnimation* b = spSkeletonData_findAnimation(skeleton->data, to);
+ if (a && b) spAnimationStateData_setMix(skeleton->stateData, a, b, seconds);
+}
+
+// =============================================================================
+// Instances
+// =============================================================================
+
+Instance* createInstance(Skeleton* skeleton) {
+ if (!skeleton) return nullptr;
+
+ auto instance = std::make_unique<Instance>();
+ instance->skeleton = spSkeleton_create(skeleton->data);
+ instance->state = spAnimationState_create(skeleton->stateData);
+ if (!instance->skeleton || !instance->state) return nullptr;
+
+ spSkeleton_setToSetupPose(instance->skeleton);
+ spSkeleton_updateWorldTransform(instance->skeleton);
+ return instance.release();
+}
+
+void update(Instance* instance, float dt) {
+ if (!instance) return;
+ spAnimationState_update(instance->state, dt);
+ spAnimationState_apply(instance->state, instance->skeleton);
+ spSkeleton_updateWorldTransform(instance->skeleton);
+}
+
+bool playAnimation(Instance* instance, const char* animation, bool loop, int track) {
+ if (!instance) return false;
+ return spAnimationState_setAnimationByName(instance->state, track, animation, loop) != nullptr;
+}
+
+bool addAnimation(Instance* instance, const char* animation, bool loop, float delay, int track) {
+ if (!instance) return false;
+ return spAnimationState_addAnimationByName(instance->state, track, animation, loop, delay) != nullptr;
+}
+
+void setSkin(Instance* instance, const char* skin) {
+ if (!instance) return;
+ if (!skin || skin[0] == '\0') {
+ spSkeleton_setSkin(instance->skeleton, nullptr);
+ } else {
+ spSkeleton_setSkinByName(instance->skeleton, skin);
+ }
+ spSkeleton_setSlotsToSetupPose(instance->skeleton);
+}
+
+void setTrackAlpha(Instance* instance, int track, float alpha) {
+ if (!instance) return;
+ spTrackEntry* entry = spAnimationState_getCurrent(instance->state, track);
+ // `mix` is what 2.1 applies the track with; the per-track alpha of later
+ // releases is the same knob under a name it had not been given yet.
+ if (entry) entry->mix = alpha;
+}
+
+void setEventSink(EventSink sink) {
+ g_eventSink = sink;
+}
+
+void enableEvents(Instance* instance) {
+ if (instance) instance->state->listener = eventListener;
+}
+
+// =============================================================================
+// Queries
+// =============================================================================
+
+int animationCount(const Instance* instance) {
+ return instance ? instance->skeleton->data->animationsCount : 0;
+}
+
+const char* animationName(const Instance* instance, int index) {
+ if (!instance) return nullptr;
+ spSkeletonData* data = instance->skeleton->data;
+ if (index < 0 || index >= data->animationsCount) return nullptr;
+ return data->animations[index]->name;
+}
+
+int skinCount(const Instance* instance) {
+ return instance ? instance->skeleton->data->skinsCount : 0;
+}
+
+const char* skinName(const Instance* instance, int index) {
+ if (!instance) return nullptr;
+ spSkeletonData* data = instance->skeleton->data;
+ if (index < 0 || index >= data->skinsCount) return nullptr;
+ return data->skins[index]->name;
+}
+
+bool bonePosition(const Instance* instance, const char* bone, float* x, float* y) {
+ if (!instance) return false;
+ spBone* b = spSkeleton_findBone(instance->skeleton, bone);
+ if (!b) return false;
+ *x = b->worldX;
+ *y = b->worldY;
+ return true;
+}
+
+bool boneRotation(const Instance* instance, const char* bone, float* degrees) {
+ if (!instance) return false;
+ spBone* b = spSkeleton_findBone(instance->skeleton, bone);
+ if (!b) return false;
+ // One world rotation before 4.0 split it per axis; report it for both.
+ *degrees = b->worldRotation;
+ return true;
+}
+
+void bounds(const Instance* instance, float* x, float* y, float* width, float* height) {
+ *x = *y = *width = *height = 0.0f;
+ if (!instance) return;
+
+ spSkeleton* skeleton = instance->skeleton;
+ float minX = 1e30f, minY = 1e30f, maxX = -1e30f, maxY = -1e30f;
+ bool any = false;
+
+ for (int i = 0; i < skeleton->slotsCount; ++i) {
+ Posed posed;
+ if (!pose(skeleton->drawOrder[i], posed)) continue;
+ for (int v = 0; v < posed.vertexCount; ++v) {
+ const float vx = posed.positions[v * 2];
+ const float vy = posed.positions[v * 2 + 1];
+ if (vx < minX) minX = vx;
+ if (vx > maxX) maxX = vx;
+ if (vy < minY) minY = vy;
+ if (vy > maxY) maxY = vy;
+ any = true;
+ }
+ }
+
+ if (!any) return;
+ *x = minX;
+ *y = minY;
+ *width = maxX - minX;
+ *height = maxY - minY;
+}
+
+int constraintCount(const Instance* instance, ConstraintKind kind) {
+ // Transform and path constraints arrived in 3.x; 2.1 skeletons have neither.
+ if (!instance || kind != ConstraintKind::Ik) return 0;
+ return instance->skeleton->ikConstraintsCount;
+}
+
+const char* constraintName(const Instance* instance, ConstraintKind kind, int index) {
+ if (!instance || kind != ConstraintKind::Ik) return nullptr;
+ if (index < 0 || index >= instance->skeleton->ikConstraintsCount) return nullptr;
+ return instance->skeleton->ikConstraints[index]->data->name;
+}
+
+bool transformMix(const Instance*, const char*, TransformMix*) { return false; }
+bool setTransformMix(Instance*, const char*, const TransformMix&) { return false; }
+bool pathMix(const Instance*, const char*, PathMix*) { return false; }
+bool setPathMix(Instance*, const char*, const PathMix&) { return false; }
+
+// =============================================================================
+// Posing
+// =============================================================================
+
+bool setAttachment(Instance* instance, const char* slot, const char* attachment) {
+ if (!instance) return false;
+ const char* name = (attachment && attachment[0] != '\0') ? attachment : nullptr;
+ return spSkeleton_setAttachment(instance->skeleton, slot, name) != 0;
+}
+
+bool setIkTarget(Instance* instance, const char* constraint, float x, float y, float mix) {
+ if (!instance) return false;
+ spIkConstraint* c = spSkeleton_findIkConstraint(instance->skeleton, constraint);
+ if (!c) return false;
+ c->target->x = x;
+ c->target->y = y;
+ c->mix = mix;
+ return true;
+}
+
+bool setSlotColor(Instance* instance, const char* slot, float r, float g, float b, float a) {
+ if (!instance) return false;
+ spSlot* s = spSkeleton_findSlot(instance->skeleton, slot);
+ if (!s) return false;
+ s->r = r;
+ s->g = g;
+ s->b = b;
+ s->a = a;
+ return true;
+}
+
+bool setSkeletonColor(Instance* instance, float r, float g, float b, float a) {
+ if (!instance) return false;
+ instance->skeleton->r = r;
+ instance->skeleton->g = g;
+ instance->skeleton->b = b;
+ instance->skeleton->a = a;
+ return true;
+}
+
+// =============================================================================
+// Geometry
+// =============================================================================
+
+void render(Instance* instance, TriangleSink& sink, bool clipping) {
+ // Clipping attachments are a 3.5 feature; a 2.1 skeleton has no clip region to
+ // apply, so the toggle has nothing to switch off.
+ (void)clipping;
+ if (!instance) return;
+
+ spSkeleton* skeleton = instance->skeleton;
+
+ for (int i = 0; i < skeleton->slotsCount; ++i) {
+ spSlot* slot = skeleton->drawOrder[i];
+ if (!slot) continue;
+
+ Posed posed;
+ if (!pose(slot, posed)) continue;
+
+ // 2.1 slots are normal or additive — multiply and screen came later, and no
+ // atlas of that era declares premultiplied alpha.
+ const int blendMode = slot->data->additiveBlending ? 1 : 0;
+
+ const float rgba[4] = {
+ skeleton->r * slot->r * posed.color[0],
+ skeleton->g * slot->g * posed.color[1],
+ skeleton->b * slot->b * posed.color[2],
+ skeleton->a * slot->a * posed.color[3],
+ };
+
+ sink.emit(posed.positions, posed.uvs, posed.vertexCount,
+ posed.indices, posed.indexCount, posed.texture, blendMode, rgba);
+ }
+}
+
+int version() {
+ return ES_SPINE_VERSION;
+}
+
+} // namespace es::spine
diff --git a/third_party/spine-runtimes-2.1 b/third_party/spine-runtimes-2.1
new file mode 160000
index 000000000..142e770e5
--- /dev/null
+++ b/third_party/spine-runtimes-2.1
@@ -0,0 +1 @@
+Subproject commit 142e770e5b4b42395a3a0a68ff3c8a21ba2774eb
diff --git a/toolchain.manifest.json b/toolchain.manifest.json
index d0c650b9c..553cc683a 100644
--- a/toolchain.manifest.json
+++ b/toolchain.manifest.json
@@ -18,6 +18,7 @@
],
"partial": {
"glm": ["glm"],
+ "spine-runtimes-2.1": ["spine-c/src", "spine-c/include"],
"spine-runtimes-3.8": ["spine-c/spine-c/src", "spine-c/spine-c/include"],
"spine-runtimes-4.1": ["spine-c/spine-c/src", "spine-c/spine-c/include"],
"spine-runtimes-4.2": [