Spine

Build the Spine runtime adapter and install it into a project to use a Spine skeleton as a Studio character.

Spine animates by bones: a skeleton drives attachments drawn from a packed texture atlas. A Spine model is a skeleton file (.json or .skel), an .atlas, and the texture pages the atlas references.

Studio supports Spine characters, but unlike Live2D it does not build the Spine adapter. The adapter is built once and then installed into the project. For the general adapter module contract, see Write your own; this page covers the Spine-specific parts.

Licence requirements

Spine Runtimes are licensed by Esoteric Software. Every user of a product containing them holds their own Spine Editor licence, and every redistribution carries the Spine Runtimes License Agreement and its copyright notice. Studio ships no Spine code and does not build the adapter.

Three requirements follow:

Everyone who works with Spine needs their own Editor licence. It is counted per person, not per project. See Spine's purchase page.
Spine Essential and Professional are valid only below USD 500,000 in revenue and financing. Above that, Spine Enterprise is required; exceeding the threshold terminates an Essential or Professional licence rather than downgrading it.
The Spine Runtimes License Agreement ships with the game, in full. Put it in the runtime folder beside index.js: every file in that folder is published with the game.

Build the adapter

The adapter is one ES module that bridges a Spine runtime to the engine's puppet contract. Esoteric publishes the runtime on npm, so it should be referenced as an npm dependency rather than vendored.

Set up a build project

mkdir spine-adapter && cd spine-adapter
npm init -y
npm install @esotericsoftware/spine-webgl esbuild

Write the adapter

The adapter is a single file implementing the engine's PuppetBackend. Two parts are specific to Spine: the skeleton and atlas are separate files, so the atlas has to be resolved relative to the entry the host provides; and Spine requires its own WebGL context.

src/index.js

import {
    AnimationState, AnimationStateData, AtlasAttachmentLoader,
    GLTexture, ManagedWebGLRenderingContext, Physics,
    SceneRenderer, Skeleton, SkeletonBinary, SkeletonJson, TextureAtlas,
} from "@esotericsoftware/spine-webgl";

export default function createPuppetBackends({ log }) {
    log("info", "spine backend registered");
    return {
        name: "spine",
        mount(container, ctx) {
            // ctx.src is the skeleton file; ctx.resolveSibling() reaches the atlas
            // and its pages. ctx.options is interpreted by the adapter and can
            // carry the atlas name. Return { ready, apply, command, resize,
            // dispose } as the engine's Puppet contract describes.
            // ...
        },
    };
}

The engine's Puppet page documents every method, when each is called, and what a complete state means. The field mapping is: motion to a Spine animation name, skin to a Spine skin, and expression to whatever the rig uses for one, or nothing.

Bundle it

The output must be a single self-contained ES module, because that is what Studio loads.

build.mjs

import { build } from "esbuild";

// esbuild keeps a comment only when it contains `@license` or `@preserve` or opens with `/*!`, and
// the Spine sources open with none of them, so their copyright header is placed here instead.
const notice = `/*!
 * Spine Runtimes License Agreement: https://esotericsoftware.com/spine-runtimes-license
 * Copyright (c) 2013-2025, Esoteric Software LLC
 */`;

await build({
    entryPoints: ["src/index.js"],
    outfile: "dist/index.js",
    bundle: true,
    format: "esm",
    platform: "browser",
    target: "es2022",
    banner: { js: notice },
});

The banner keeps the copyright notice in the module. The agreement itself is the file placed in the runtime folder.

Install the adapter

Open the installer

From a character created with New character → Spine, select Install on its Drawing runtime row; or use Project → Runtimes → Spine → Install.

Confirm the licence terms

The dialog restates the requirements above. Tick the acknowledgement to continue.

Point Studio at the adapter output

Use Choose file for a single bundled index.js. If the adapter has sibling files it loads at runtime, use Choose folder, in which case the whole folder is copied.

Validation

Studio loads the module the same way the game will and confirms that it produces a backend. A module that produces none is rejected and rolled back, and is not left in the project.

Studio writes a README.md into the runtime folder, unless the folder already carries one. It records that the runtime was supplied rather than built by Studio, and that the licence has to be published with the game.

The folder is named after the backend the module registers. If the module registers itself as spine-pro and was installed as spine, Studio renames the folder to spine-pro and reports it. The engine resolves a character's runtime by the registered name, and a mismatch leaves the character undrawn on stage.

Add a model

A Spine model is a folder containing the skeleton, atlas and texture pages, so it is imported as a folder. Two settings are determined by the Spine format:

The entry file. Studio identifies the skeleton file. If the bundle contains several skeletons sharing one atlas, name the one this character uses in the Entry field.
The atlas. File names are not sufficient to identify the atlas, so the adapter determines it, conventionally by reading Options:

{ "atlas": "spineboy/spineboy-pma.atlas", "format": "binary" }

Options are passed to the adapter untouched; Studio reads none of the keys.

What the character supports

This depends on what the adapter reports. If it implements the engine's describe(), Studio fills the Motion, Skin and Parameter fields from the model — animation names, skin names, and any parameters the adapter exposes — and the preview draws the skeleton in its resting pose. If it does not, every field is a text box and the names are entered manually.

On this page