Integrate Spine Animations with Pixi.js

This article provides a direct guide on how to integrate and render skeletal mesh animations exported from Esoteric Software’s Spine within a Pixi.js application. You will learn about the required export files, how to install the official integration plugin, and the JavaScript code needed to load assets and control animations on the stage.

1. Exporting Assets from Spine

To use Spine animations in PixiJS, you must export your skeleton from Spine using the correct settings. Ensure you export the following three files: * An Atlas File (.atlas): Contains texture packing information. * A Texture Image (.png): The packed spritesheet containing the mesh images. * A Skeleton Data File: Either a JSON (.json) or a binary (.skel) file containing the bone hierarchy, mesh attachments, and keyframes.

Ensure “Texture Packer” is enabled during export and that the output scale matches your project’s target resolution.

2. Installing the Pixi-Spine Plugin

Pixi.js does not support Spine animations natively. You must install the official companion package, pixi-spine (or @pixi-spine/all for modern npm-based setups). This plugin extends Pixi.js with the rendering pipelines needed to handle Spine’s complex skeletal and mesh deformations.

For npm projects, install the package matching your Pixi.js major version:

npm install pixi-spine

For browser-based CDN setups, include the script tag after the main Pixi.js library:

<script src="https://cdn.jsdelivr.net/npm/pixi.js@7.x/dist/pixi.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/pixi-spine@4.x/dist/pixi-spine.umd.min.js"></script>

3. Loading Spine Assets

Using the PixiJS asset loader, you can load the exported skeleton data. The pixi-spine plugin automatically detects Spine assets when you load the .json or .skel file, provided the .atlas and .png files share the same name and reside in the same directory.

import { Application, Assets } from 'pixi.js';
import 'pixi-spine'; // Side-effects import registers the spine parser

const app = new Application({ width: 800, height: 600 });
document.body.appendChild(app.view);

// Load the Spine JSON file (atlas and PNG will load automatically)
const spineAsset = await Assets.load('assets/character.json');

4. Creating and Displaying the Animation

Once loaded, instantiate the Spine object using the loaded resource’s data. Add the object to the PixiJS stage to render it, then position and scale it as needed.

import { Spine } from 'pixi-spine';

// Create the Spine sprite
const character = new Spine(spineAsset.spineData);

// Set position and scale
character.x = app.screen.width / 2;
character.y = app.screen.height / 2 + 200;
character.scale.set(0.5);

// Add to the stage
app.stage.addChild(character);

5. Controlling the Skeletal Animation

To play animations, access the state property of the Spine instance. Use the setAnimation method to play a specific track, and set the loop parameter to true or false.

// Play the "walk" animation on track 0, looping continuously
character.state.setAnimation(0, 'walk', true);

// Queue a "jump" animation to play after "walk" finishes
character.state.addAnimation(0, 'jump', false, 0);

Because the pixi-spine runtime handles mesh deformations, any vertex weights, FFD (Free-Form Deformation), or mesh animations configured inside the Spine editor will automatically calculate and render smoothly in real-time inside your Pixi.js application.