Welcome to the Solar2D’s Spine Documentation!¶

(Jump straight to the API reference)

Introduction¶

This documentation is your comprehensive guide to integrating and using the Spine Plugin within your Solar2D projects. If you’re looking for powerful 2D skeletal animations—complete with mixing, blending, skin switching, and event handling—this plugin is designed to streamline your animation workflow.

Spine (developed by Esoteric Software) is a popular tool for creating 2D skeletal animations. With this plugin, you can seamlessly play back and control Spine animations in your Solar2D games or applications. The result: beautiful and efficient character or UI animations that look great on every device.

Pick your line¶

The plugin ships one plugin per Spine line. Pick the line of the Spine editor you export your skeletons from, add its entry to the plugins table of build.settings and read that line’s documentation. Use one Spine plugin per app: plugin.spine42 and plugin.spine43 raise an error naming both plugins when the other line or the legacy plugin.spine is already loaded, but a legacy plugin.spine required after them cannot check and is not caught.

Spine 4.2: plugin.spine42 (version 2.0.1), documentation for 4.2.

settings =
{
    plugins =
    {
        ["plugin.spine42"] =
        {
            publisherId = "com.studycat",
        },
    },
}

Spine 4.3: plugin.spine43 (version 3.0.1), documentation for 4.3.

settings =
{
    plugins =
    {
        ["plugin.spine43"] =
        {
            publisherId = "com.studycat",
        },
    },
}

Legacy 1.2: plugin.spine, the earlier release, documentation for 1.2.

settings =
{
    plugins =
    {
        ["plugin.spine"] =
        {
            publisherId = "com.studycat",
        },
    },
}

The Simulator and the build download each plugin from the Solar2D Free Plugin Directory. To stay on one release, add version = "v2" to the entry: v2 is plugin.spine42 2.0.1 and plugin.spine43 3.0.1, and v1 stays on 2.0.0 and 3.0.0. The same archives stay attached to the GitHub releases spine42-2.0.1 and spine43-3.0.1 as a fallback: list their URLs in the entry’s supportedPlatforms to install from there instead.

Moving a project from plugin.spine 1.2 to a line, or from 4.2 to 4.3? See the migration guide and the CHANGELOG’s plugin.spine42 2.0.0 and plugin.spine43 3.0.0 releases.

How to Get Started¶

Check Spine License Requirements

Make sure you own a valid Spine license if necessary. Esoteric Software offers various Spine license tiers. Confirm you have the permission required to use the runtime.
Install the Plugin

To use this plugin, add this entry into the plugins table of build.settings. The Simulator and the build download the plugin from the Solar2D Free Plugin Directory. This is the entry for the line these docs describe; Pick your line lists the entry of every line.
```
settings =
{
    plugins =
    {
        ["plugin.spine43"] =
        {
            publisherId = "com.studycat",
        },
    },
}
```

Load the Plugin in Your Lua Code

local spine = require("plugin.spine43")

Import Your Spine Assets

Put your Spine-generated JSON or binary skeleton files, as well as any atlas/textures, into your project’s resource directory.
Start Animating

Familiarize yourself with the plugin’s core objects (e.g., Skeleton, physics, ik constraints) and methods. These are detailed in the API Reference: Spine Plugin. You’ll learn how to mix animations, update skeleton transforms, change skins, and more.

Differences from the Original Spine Runtime:¶

I built this plugin trying to make a complete integration to the original C++ Runtime. However, there are some key differences to keep in mind:

indexes: Indexes start at 1, not 0, including track indexes. Skin methods take slot names or Slot objects, never numeric slot indexes. Not my favorite change, but I want to prioritize consistency with the language and the engine first, and then with the original runtime.
events: Events have been customized to be more Solar2D-friendly. Event phases are "began", "completed", and "ended" instead of "start", "complete", and "end". (See spineEvent for more details).
times: All times are in milliseconds, not seconds. This is to keep consistency with Solar2D’s time units.
AnimationState: The AnimationState class has been removed. Instead, the Skeleton class has all the necessary methods to control animations.

Key Features¶

Compatibility: The plugin is compatible with Solar2D builds for iOS, Android, macOS and windows.
Performance: Unlike the old Lua Runtime, this plugin uses native code for optimal rendering and animation performance.

Physics: This line uses Spine 4.3, which has the physics system. You can create physics constraints in Spine and use them in Solar2D.

Documentation Contents¶

Below is a quick look at the main sections of this documentation:

API Reference: Spine Plugin
- spine
- skeleton
- skeleton.physics
- slot
- bone
- ikConstraint
- slider
- trackEntry
- skin
- attachment

Feedback & Contributions¶

We’re always looking to improve! If you run into any issues or have suggestions:

GitHub: Submit bug reports, feature requests, or pull requests to the repository.
Community Forums: Join the discussion on the Solar2D Community Forums.
Support: For more direct inquiries, check our Support Guidelines.

License¶

This project is subject to the Spine Runtimes License. Feel free to fork or modify the plugin code for your projects, but please respect the license terms.

Acknowledgments¶

Thanks to Studycat Limited for supporting me in bringing this project to life while I was working at the company.
Big thanks to Steven Johnson (ggcrunchy) for his unwavering support and contributions.
Thanks to the Esoteric Software team for developing and maintaining Spine.

Note

This plugin is independently maintained and is not officially endorsed by Esoteric Software.

We hope you find this documentation helpful and comprehensive. Let’s get animating with Spine for Solar2D!