spine-layout
A spine composition framework built on Pixi.js. It lets you assemble flexible scenes with Spine skeletons, and provides a powerful animation system with minimal code.
Full documentation: userland.pixijs.io/spine-layout
Architecture
SpineLayout is a Pixi.js Container that acts as a facade over seven specialized controllers:
SpineLayout (Container)
├── AnimationsController — playback, states, events, track management
├── SkinsController — skin switching across spines
├── SpineController — bone/slot queries, global positions, cloning
├── TextsController — dynamic text rendering & number animation
├── SceneController — hierarchical composition (nest spines, attach texts/buttons)
├── PointerController — bones that follow the mouse or finger
└── OrientationController — poses the layout for the shape of the screen
All spines are stored in a central Map<SpineID, Spine> registry and each controller operates against that registry.
Engines
The core renders through an Engine, so one scene runs on every Pixi from 4 to 8. A game picks its
Pixi when it creates the engine; the Spine runtime is then picked from the export version, among
the runtimes registered for that Pixi. The exports of one layout must all be of one Spine version:
a layout that mixes them throws MixedSpineVersionsError and builds nothing.
| Entry | Pixi | Spine runtimes |
|---|
@pixijs-userland/spine-layout | pixi.js v8 | spine-pixi-v8 4.3 (unchanged default entry) |
@pixijs-userland/spine-layout/pixi8 | pixi.js v8 | spine-pixi-v8 4.2 and 4.3 |
@pixijs-userland/spine-layout/pixi7 | Pixi 7 (window.PIXI) | @pixi-spine/* 4.0 (3.7, 3.8, 4.1; 4.0 through 4.1), spine-pixi-v7 4.2 and 4.3 |
@pixijs-userland/spine-layout/pixi6 | Pixi 6 (window.PIXI) | @pixi-spine/* 3.1 (3.7, 3.8, 4.0, 4.1) |
@pixijs-userland/spine-layout/pixi5 | Pixi 5 (window.PIXI) | pixi-spine 2.1 (3.8) or 2.0 (3.7), one per page |
@pixijs-userland/spine-layout/pixi4 | PIXI v4.8.9 (window.PIXI) | pixi-spine 1.6 (3.8) or 1.5 (3.7), one per page |
@pixijs-userland/spine-layout/core | none | SpineLayoutCore, the runtime matrix, choosePixi, pickRuntime |
@pixijs-userland/spine-layout/runtimes binds runtime packages to an engine and discovers the ones
a page loaded as globals. A Spine export is read by the runtime of its own editor major.minor; a
project pin can name another, and 4.0 and 4.1 exports reach the next runtime through a JSON
pre-pass. On Pixi 4–7 the stack is loaded as <script> tags and the engine is handed
window.PIXI:
import { createPixi4Engine, SpineLayoutCore } from '@pixijs-userland/spine-layout/pixi4';
const engine = createPixi4Engine(PIXI, { renderer: app.renderer });
const layout = new SpineLayoutCore({ engine });
A game whose own loader already reads its skeletons (unicore reads binary Spine 3.8 into
SkeletonData with its atlas) hands them over as they are: engine.assets.set('spine/bg.json', skeletonData). The engine takes a SkeletonData under a skeleton alias as read, with no atlas.
A project is one Spine version; skeletonVersion(skeleton) reads it from a .json or .skel.
One Pixi major is live per page. See the Engines guide
for loading, the differences between the engines and how to write another.
Examples
examples/ has one scene per Pixi major, each built with that major's engine from the exports in
examples/assets/: Pixi 8 with spine-pixi-v8 4.3 and a lazily loaded 4.2 in one scene, Pixi 7
with a Spine 3.8 and a 4.3 layout on one engine, and Pixi 6, 5 and 4 each on their own pixi-spine
with the 3.8 layout (texts, a bitmap font, a button, a second skin and particles). From this
package, after pnpm install:
pnpm examples --port <port> --strictPort --no-open
Then open http://localhost:<port>/examples/. Vite serves the layout from src; the legacy
stacks load as <script> globals, and the runtimes with no browser script of their own
(@pixi-spine/*, spine-pixi-v7) are bundled into examples/vendor/ as the server starts.
Initialization
From a Pixi.js manifest (recommended)
const layout = new SpineLayout({ debug: true });
await layout.createInstancesFromManifest(manifest, 'spines');
createInstancesFromManifest parses the manifest for .atlas / .json / .png triplets, builds the scene from its root, then wires the full hierarchy.
The scene has one entry point — root, or whatever options.root names. It is built first, its
spine_<id> slots name the spines built next, theirs name the ones after that, and so on down the
tree; the layout container holds the root and nothing else. A skeleton that is loaded but embedded
nowhere is not instanced at all — nothing points at it, so nothing would place it. createInstance
builds one anyway, together with everything it embeds in turn.
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
