spine-ts

The spine-ts runtime provides functionality to load and manipulate Spine skeletal animation data using TypeScript and JavaScript. spine-ts is split up into multiple modules:

1. Core: core/, the core classes to load and process Spine models
2. WebGL: webgl/, a self-contained WebGL backend, build on the core classes
3. Canvas: canvas/, a self-contained Canvas backend, build on the core classes
4. THREE.JS: threejs/, a self-contained THREE.JS backend, build on the core classes
5. Player: player/, a self-contained player to easily display Spine animations on your website, build on core classes & WebGL backend.

While the source code for the core library and backends is written in TypeScript, all code is compiled to easily consumable JavaScript.

Licensing

You are welcome to evaluate the Spine Runtimes and the examples we provide in this repository free of charge.

You can integrate the Spine Runtimes into your software free of charge, but users of your software must have their own Spine license. Please make your users aware of this requirement! This option is often chosen by those making development tools, such as an SDK, game toolkit, or software library.

In order to distribute your software containing the Spine Runtimes to others that don't have a Spine license, you need a Spine license at the time of integration. Then you can distribute your software containing the Spine Runtimes however you like, provided others don't modify it or use it to create new software. If others want to do that, they'll need their own Spine license.

For the official legal terms governing the Spine Runtimes, please read the Spine Runtimes License Agreement and Section 2 of the Spine Editor License Agreement.

Spine version

spine-ts works with data exported from Spine 3.8.xx.

spine-ts WebGL & players backends supports all Spine features.

spine-ts Canvas does not support white space stripped texture atlases, color tinting, mesh attachments and clipping. Only the alpha channel from tint colors is applied. Experimental support for mesh attachments can be enabled by setting spine.canvas.SkeletonRenderer.useTriangleRendering to true. Note that this method is slow and may lead to artifacts on some browsers.

spine-ts THREE.JS does not support two color tinting & blend modes. The THREE.JS backend provides SkeletonMesh.zOffset to avoid z-fighting. Adjust to your near/far plane settings.

spine-ts does not yet support loading the binary format.

Usage

1. Download the Spine Runtimes source using git or by downloading it as a zip via the download button above.
2. To use only the core library without rendering support, include the build/spine-core.js file in your project.
3. To use the WebGL backend, include the build/spine-webgl.js file in your project.
4. To use the Canvas backend, include the build/spine-canvas.js file in your project.
5. To use the Player, include build/spine-player.js and player/css/spine-player.css file in your project.
6. To use the THREE.JS backend, include the build/spine-threejs.js file in your project. THREE.JS must be loaded first.

All *.js files are self-contained and include both the core and respective backend classes.

If you write your app with TypeScript, additionally copy the corresponding build/spine-*.d.ts file to your project.

Note: If you are using the compiled .js files with ES6 or other module systems, you have to add

export { spine };

At the bottom of the .js file you are using. You can then import the module as usual, e.g.:

import { spine } from './spine-webgl.js';

Spine 3.8 THREE.JS 适配说明

本仓库在保留 Spine 3.8 原有浏览器全局构建的同时，增加了适合现代 THREE.JS 和 npm ES Module 项目的构建产物。适配要点如下：

1. 原始运行库使用 TypeScript namespace spine 和 module: none，生成的 build/spine-threejs.js 是传统浏览器脚本，不是 ES Module。它依赖全局 window.THREE，并通过全局变量 window.spine 暴露 API。
2. npm 构建仍先使用旧编译方式合并所有 namespace 源码，然后自动在产物中 添加 import * as THREE from "three"，以及 spine 的默认导出和命名导出。 不需要手工修改生成后的 JavaScript 文件。
3. dist/index.d.ts 会同步添加 THREE.JS 类型导入以及 spine 导出，确保 TypeScript 项目中的运行时导入方式和类型导入方式一致。
4. three 被声明为 peer dependency，不会被打包进运行库。应用和 Spine runtime 因此会使用同一个 THREE.JS 实例，避免材质等对象的 instanceof 判断因为加载了两份 THREE.JS 而失败。
5. 新版 THREE.JS 已逐步使用 clearUpdateRanges() 和 addUpdateRange() 更新 BufferAttribute。本仓库在 MeshBatcher.end() 中优先使用新 API，并为旧版 THREE.JS 保留 updateRange 回退逻辑。
6. 不能简单把 tsconfig.threejs.json 的 module 改为 es6。该运行库依赖 跨文件 namespace 合并和 outFile，标准 ESM 编译无法直接保持这种结构， 因此采用“旧格式编译 + ESM 收尾处理”的构建流程。

构建 npm 产物：

pnpm install
pnpm run build

构建流程会生成：

dist/index.js      # ES Module 运行时代码
dist/index.d.ts    # TypeScript 类型声明

可以在发布前检查最终文件清单：

npm pack --dry-run

npm pack 和 npm publish 会通过 prepack 自动重新构建 dist/。本包发布在 npmjs，消费者可以 直接同时安装本包和 THREE.JS：

npm install @verdammt/spine3dot8-runtimes three

默认导出和命名导出均可使用：

import spine from "@verdammt/spine3dot8-runtimes";
// 或：import { spine } from "@verdammt/spine3dot8-runtimes";

const skeletonMesh = new spine.threejs.SkeletonMesh(skeletonData);

发布 npm 包

GitHub Actions 会在 GitHub Release 正式发布后构建、测试并发布 npm 包。仓库的 Actions secret 中必须配置具有发布权限的 NPM_TOKEN。Release 标签应为 v<package.json version>，例如发布 1.0.1 时使用 v1.0.1；已经发布到 npm 的版本不能再次发布。

build/spine-threejs.js 仍是旧版浏览器全局产物。如果使用 <script> 标签， 必须先加载 THREE.JS，再加载该文件。npm 项目应使用 dist/index.js 或直接从 包名导入，不应直接引用 build/spine-threejs.js。

THREE.JS 在 0.x 版本中也可能包含破坏性变更。发布 npm 包前，应根据实际 测试过的 THREE.JS 版本收窄 peerDependencies.three 的版本范围，并重点验证 骨骼网格创建、纹理过滤、透明材质、顶点更新和资源释放。

Examples

To run the examples, the image, atlas, and JSON files must be served by a webserver, they can't be loaded from your local disk. Spawn a light-weight web server in the root of spine-ts, then navigate to the index.html file for the example you want to view. E.g.:

cd spine-ts
python -m SimpleHTTPServer

Then open http://localhost:8000/webgl/example, http://localhost:8000/canvas/example, https://localhost:8000/threejs/example or http://localhost:8000/player/example in your browser.

WebGL Demos

The spine-ts WebGL demos load their image, atlas, and JSON files from our webserver and so can be run directly, without needing a webserver. The demos can be viewed all on one page or in individual, standalone pages which are easy for you to explore and edit. See the standalone demos source code and view the pages here:

• Spine vs sprite sheets
• Image changes
• Transitions
• Meshes
• Skins
• Hoverboard
• Vine
• Clipping
• Stretchyman
• Tank
• Transform constraints

Please note that Chrome and possibly other browsers do not use the original CORS headers when loading cached resources. After the initial page load for a demo, you may need to forcefully refresh (hold shift and click refresh) or clear your browser cache.

Development Setup

The spine-ts runtime and the various backends are implemented in TypeScript for greater maintainability and better tooling support. To setup a development environment, follow these steps.

1. Install NPM and make sure it's available on the command line
2. On the command line, Install the TypeScript compiler via npm install -g typescript
3. Install Visual Studio Code
4. On the command line, change into the spine-ts directory
5. Start the TypeScript compiler in watcher mode for the backend you want to work on:

• Core: tsc -w -p tsconfig.core.json, builds core/src, outputs build/spine-core.js|d.ts|js.map
• WebGL: tsc -w -p tsconfig.webgl.json, builds core/src and webgl/src, outputs build/spine-webgl.js|d.ts|js.map
• Canvas: tsc -w -p tsconfig.canvas.json, builds core/src and canvas/src, outputs build/spine-canvas.js|d.ts|js.map
• THREE.JS: tsc -w -p tsconfig.threejs.json, builds core/src and threejs/src, outputs build/spine-threejs.js|d.ts|js.map
• Player: tsc -w -p tsconfig.player.json, builds core/src and player/src, outputs build/spine-player.js|d.ts|js.map

6. Open the spine-ts folder in Visual Studio Code. VS Code will use the tsconfig.json file all source files from core and all backends for your development pleasure. The actual JavaScript output is still created by the command line TypeScript compiler process from the previous step.

Each backend contains an example/ folder with an index.html file that demonstrates the respective backend. For development, we suggest to run a HTTP server in the root of spine-ts, e.g.

cd spine-ts
python -m SimpleHTTPServer

Then navigate to http://localhost:8000/webgl/example, http://localhost:8000/canvas/example, http://localhost:8000/threejs/example or http://localhost:8000/player/example

Spine-ts WebGL backend

By default, the spine-ts WebGL backend supports two-color tinting. This has a neglible effect on performance, as more per vertex data has to be submitted to the GPU, and the fragment shader has to do a few more arithmetic operations.

You can disable two-color tinting like this:

// If you use SceneRenderer, disable two-color tinting via the last constructor argument
var sceneRenderer = new spine.SceneRenderer(canvas, gl, false);

// If you use SkeletonRenderer and PolygonBatcher directly,
// disable two-color tinting in the respective constructor
// and use the shader returned by Shader.newColoredTextured()
// instead of Shader.newTwoColoredTextured()
var batcher = new spine.PolygonBatcher(gl, false);
var skeletonRenderer = new spine.SkeletonRenderer(gl, false);
var shader = Shader.newColoredTextured();

Using the Player

Please see the documentation for the Spine Web Player