Spine 2D Player Guide

Author: Pheonix KageDesu
RPG Maker Versions: MZ Only
URL: https://kdworkshop.net/plugins/spine-player/

---

Table of Contents

• Requirements
• Exporting from Spine
• Installation
• Basic Script Calls
• Command Chaining
• Binding Group
• Events System
• Manipulation API
• Skins API
• Attachments API
• Animations API
• Waiting for Animations
• Sound Effects
• Spine Events Integration
• Messaging System

---

Requirements

• RPG Maker MZ
• Spine 2D (recommended: 3.8.75)
• Spine JSON + Atlas export

---

Exporting from Spine

Use the following export settings:

• Data format: JSON
• Texture Atlas: Pack (default settings)

Tip

If your output image looks blurry in RPG Maker: - Disable Premultiply Alpha in Spine export settings
This may also reduce file size.

---

Installation

1. Place your Spine animations into:

   img/pSpineAssets/
   

2. Each animation must be inside a separate folder.

3. The folder should contain the required Spine files (JSON, Atlas, textures).

---

Basic Script Calls

Create Animation

CreateSAnim(ID, FILENAME, X, Y);

• ID -- Unique animation identifier
• FILENAME -- Name of the .json file (without extension)
• X, Y -- Initial position

Example:

CreateSAnim("spineboy", "spineboy", 0, 0);

Get Animation Instance

SAnim(ID);

Example:

SAnim("spineboy").setAnimation("portal");

Remove Animation

RemoveSAnim(ID, MAP_ID);

Example:

RemoveSAnim("spineboy");

---

Command Chaining

All animation commands support chaining:

SAnim("spineboy")
    .bindToScreen()
    .setPosition(0, 0)
    .setScale(0.5);

---

Save & Remove Group

Method Description

---

.keep() Saves animation on the current map (experimental) .remove() Deletes the animation (same as RemoveSAnim)

---

Binding Group

Screen & Layer Binding

.bindToScreen();
.bindBelowPictures();
.bindBelowWindows();
.bindToMap(z);

• z range: 0--9\
• z >= 4 renders above character sprites
• When bound to map, coordinates use map cells, not pixels

Example:

SAnim("spineboy").setPosition(5, 5); // Map cells, not pixels

---

Events System

Event Hooks

.setScriptOnStart(script, animationName);
.setScriptOnComplete(script, animationName);
.setScriptOnEnd(script, animationName);
.clearAllEvents();

• script -- JavaScript code or Common Event ID
• animationName -- Specific animation (leave empty for any)

Examples

Run Common Event 32 when "jump" completes:

SAnim("spineboy").setScriptOnComplete(32, "jump");

Run script when "shoot" starts:

SAnim("spineboy").setScriptOnStart("console.log('shoot')", "shoot");

Remove animation when any animation ends:

SAnim("spineboy").setScriptOnEnd("RemoveSAnim('spineboy')");

---

Manipulation API

Transform & Movement

.setPosition(x, y)
.moveTo(x, y, duration)     // duration in frames
.moveBy(dx, dy, duration)
.setScale(x, y)             // default = 1.0
.setTimeScale(timescale)    // default = 1.0

Example:

SAnim("spineboy").setScale(0.5);

Visual Effects

.shake(dx, dy, duration)
.setAlpha(alpha)            // 0 = transparent, 1 = opaque
.fadeIn(duration)           // frames (60 = 1 second)
.fadeOut(duration, isRemoveAfter)

Flip (mirror) animation:

SAnim("spineboy").setScale(-1, 1);

---

Skins API

Basic Skin Control

.setSkin(skinName, isResetPose = true);

Examples:

SAnim("spineboy").setSkin("formal");
SAnim("spineboy").setSkin(""); // Reset to default

Runtime Skin Building

.buildSkin(newSkinName, ...existingSkins);

Example:

SAnim("spineboy").buildSkin("armored", "helmet", "armor", "boots");

Step-by-Step Skin Creation

.createSkin("newSkinName");
.addToCreatedSkin("existingSkinName");
.applyCreatedSkin();

---

Attachments API

.setAttachment(slotName, attachmentName);
.setAttachmentFromAnySlot(slotName, attachmentName);
.clearAttachment(slotName);

Example:

SAnim("spineboy").setAttachment("right_hand", "pistol");

---

Animations API

Play Animation

.setAnimation(name, isLoop = false, mixDuration = 0, trackIndex = 0);

Example:

SAnim("spineboy").setAnimation("walk", true);

Queue Animation

.addAnimation(name, isLoop, delay, mixDuration, trackIndex);

Stop Animation

.stopAnimation(mixDuration, trackIndex);
.addEndOfAnimation(delay, mixDuration, trackIndex);

Supports multi-track animation layering (e.g., shooting while running).

---

Waiting for Animations

Inside RPG Maker Events:

this.waitSAnimComplete(ID, ANIMATION_NAME);

• If ANIMATION_NAME is omitted, waits for any animation to finish

Example:

this.waitSAnimComplete("spineboy", "jump");

---

Sound Effects

If a sound is set inside the event, it will play automatically. Requirements: - Place files in audio/SE - Volume control is supported

---

Spine Events Integration

You can bind Spine animation events directly to scripts or Common Events:

.setScriptOnEvent(eventName, script);

Example:

SAnim("spineboy").setScriptOnEvent("MyEvent", 44);

---

Messaging System

Animations can be linked to dialogue messages by face or speaker name.

Bind by Face

.bindToMessageByFace(faceName, faceIndex, isHighlight);

• faceName = "" → any face
• faceIndex = -1 → any index
• isHighlight → darkens non-speaking characters

Example:

SAnim("fairy").bindToMessageByFace("Nature", 5, true);

Bind by Speaker Name

.bindToMessageByName(speakerName, isHighlight);

Example:

SAnim("reid").bindToMessageByName("Reid", true);

Unbind

.unbindFromMessage();

---

Talking & Idle Animations in Messages

After binding to messages:

.setMessageTalkAnimation(animationName, mixDuration);
.setMessageIdleAnimation(animationName, mixDuration);

Example:

SAnim("fairy").setMessageTalkAnimation("talk1", 0.5);

Behavior: - While text is shown → Talk animation plays - When text ends → Idle animation plays

Dynamic Control Characters in Text

\SAT[animationName:mixDuration]  // Change talk animation
\SAI[animationName:mixDuration]  // Change idle animation

Example:

Some text... \SAT[talk3] ... then idle \SAI[idle1:0.5]