spine-unity

Getting Started

Getting Started Documentation

Download

spine-unity 4.2

spine-unity unitypackage

  • spine-unity 4.2 (updated 2024-11-15, changelog)
    Compatible with Spine 4.2.00 or newer and Unity 2017.1-2023.1.
    Add package from git URL: (URLs for spine-csharp, spine-unity and examples)
    https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-csharp/src#4.2 https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Assets/Spine#4.2 https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Assets/Spine Examples#4.2

URP Shaders UPM package com.esotericsoftware.spine.urp-shaders

  • Unity 2019.3-2023.1: spine.urp-shaders 4.2 (updated 2024-11-11)
    Compatible with spine-unity 4.2 and Unity 2019.3-2023.1.
    Add package from git URL: (requires spine-unity installed via UPM)
    https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Modules/com.esotericsoftware.spine.urp-shaders#4.2

LWRP Shaders UPM package com.esotericsoftware.spine.lwrp-shaders

  • Unity 2019.1: spine.lwrp-shaders 4.2 (updated 2024-04-17)
    Compatible with spine-unity 4.2 and Unity 2019.1.
  • Unity 2019.2: spine.lwrp-shaders 4.2 (updated 2024-04-17)
    Compatible with spine-unity 4.2 and Unity 2019.2.
    Add package from git URL: (requires spine-unity installed via UPM)
    https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Modules/com.esotericsoftware.spine.lwrp-shaders#4.2

Timeline Extensions UPM package com.esotericsoftware.spine.timeline

Installing spine-unity in a new project

  1. Create an empty Unity project.
  2. Import the spine-unity.unitypackage you downloaded. (double-clicking on the unitypackage should open it in Unity).

If you are just getting started, there are more detailed steps in the documentation section on Installation.

Updating an existing project

  • As with Unity updates, it is always recommended that you back up your whole Unity project before performing an update.
  • Always check with your Lead Programmer and Technical Artist before updating your Spine runtime. Spine runtimes are source-available and designed to be user-modifiable based on varying project needs. Your project's Spine runtime may have been modified by your programmer. In this case, updating to the latest runtime also requires reapplying those modifications to the new version of the runtime.
  • Read the CHANGELOG.md file included in the downloaded unitypackage or on github. You can find the necessary documentation here when obsolete methods have been replaced with new counterparts.

In-place Update (.unitypackage)

When upgrading to a different major or minor version (e.g. from 3.8 to 4.0), please see the spine-unity documentation page section on updating. When upgrading to the same major and minor version (e.g. from 4.0 to a newer 4.0 package), you can follow the steps below:

  1. Open your Unity project.
  2. Import the .unitypackage into your existing project by double-clicking on the unitypackage file or dragging it into Unity editor Project view.
  3. The Import dialog will show which files are updated and will update them regardless of where you moved them in your project since you last imported.

    This functionality may not work correctly if your meta files were corrupted or replaced. In that case, you may have to do delete the old version of the runtime before importing the unitypackage.

For more options, see the spine-unity documentation page section on updating.

Installing Extension UPM Packages

  1. Download the Unity Package Manager (UPM) package via the download links above or find it in the spine-runtimes/spine-unity/Modules subdirectory on the git repository.
  2. If you have your Unity project open, it is recommended to either a) close Unity or b) close any scene containing Spine components (e.g. by opening a new empty scene).
  3. You can then either unzip (or copy if using git) the package to a) the Packages directory in your project where it will automatically be loaded, or b) to an arbitrary directory outside the Assets directory and then open Package Manager in Unity, select the + icon, choose Add package from disk.. and point it to the package.json file.
  4. The Project panel should now show an entry for your package, e.g. Spine Lightweight RP Shaders under Packages. If the directory is not yet listed, you need to close and re-open Unity to have it display the directory and its contents.

Updating an existing UPM package

  • The same principles as updating the Spine Unity runtime apply.
  • As mentioned above, it is always recommended that you back up your whole Unity project before performing an update.

In-place Update (via .zip file or git)

  1. If you have your Unity project open, it is recommended to either a) close Unity or b) close any scene containing Spine components (e.g. by opening a new empty scene).
  2. Copy the content of the new UPM package zip file or git directory over the existing one. Depending on how you have installed the UPM package, this will be either the project_root/Packages/package_name directory in your project or the arbitrary directory outside the Assets directory from where you have loaded it via Add package from disk...
  3. If you have closed Unity, open your project again in Unity.
  4. Unity will import the new assets and display a loading progress bar.

Known Issues:

  • You cannot drag SkeletonData Assets into the Hierarchy view if it is empty. You will need to drag them into Scene View, or create an empty GameObject before dragging into Hierarchy view.

Unity Limitations:

  • Unity's physics components do not support dynamically assigned vertices so they cannot be used to mirror bone-weighted and deformed BoundingBoxAttachments. However, BoundingBoxAttachments' internal vertex data at runtime is still being deform correctly and can be used to perform hit detection with your own code.
  • Spine animations are not imported as Unity.AnimationClip objects. Unity uses a different curve scheme and the set of features do not overlap well with Spine's features. Instead, spine-unity animates using core C# Spine.Animation objects which retain all of Spine's animation features. This means a few conveniences may be absent, such as playing back animations in edit mode using the Animation panel.
  • Unity does not recognize arbitrary file types, so atlases need to be exported as .atlas.txt. Likewise, binary files need to be exported as .skel.bytes. For more information on importing Spine assets, see the documentation section on Assets
  • Unity has had a long-standing issue with multi-material/multi-submesh meshes, sorting and dynamic batching. If you have many duplicates of a skeleton that uses multiple materials, Unity's dynamic batching system will attempt to batch the similar materials but it breaks sorting within skeletons in the process of batching submeshes with similar materials. To work around this Unity bug, add a Sorting Group component to your Spine GameObject. However, it is still better for performance if your skeleton uses only one texture and material.

Compatibility

  • Runtimes cannot load exported binary file versions that are newer or older than the version it supports.
  • Json exports are more stable and have better chances of being compatible with future versions, but may still break.
  • If you want to avoid incompatibility issues with a set runtime version, you can choose a Spine editor version that matches that runtime specifically. This can be done in Spine's Settings... window.
    For more information, see this forum topic.

Older Versions

spine-unity unitypackages

spine-unity 4.1 for Unity 2017.1-2023.1.
spine-unity 4.1 2024-06-19
(Last updated: UTC - 2024 Jun 19)

spine-unity 4.0 for Unity 2017.1-2022.1.
spine-unity 4.0 2024-08-21
(Last updated: UTC - 2024 Aug 21)

spine-unity 3.8 for Unity 2017.1-2020.3
spine-unity 3.8 2021-11-10
(Last updated: UTC - 2021 Nov 10)

spine-unity 3.7 for Unity 5.6-2018.4
spine-unity 3.7 2019-08-05
(Last updated: UTC - 2019 Aug 05)

spine-unity 3.6 for Unity 5.6-2018.2:
spine-unity 3.6 2019-05-13
(Last updated: UTC - 2019 May 13)

spine-unity 3.5 for Unity 5.4-2017.1:
spine-unity 3.5 (Unity 5.4)
(Last updated: UTC - 2017 June 18)

spine-unity 3.0 for Unity 4.6:
spine-unity 3.0 (Unity 4.6)
(Last updated: UTC - 2017 May 9)

UPM packages

URP Shaders UPM packages com.esotericsoftware.spine.urp-shaders
spine.urp-shaders 4.1 2023-10-26 - Unity 2019.3-2023.1
Compatible with spine-unity 4.1 and Unity 2019.3-2023.1.

spine.urp-shaders 4.0 2022-05-25 - Unity 2019.3-2022.1
Compatible with spine-unity 4.0 and Unity 2019.3-2022.1.

spine.urp-shaders 3.8 2021-03-04 - Unity 2019.3-2020.3
Compatible with spine-unity 3.8 from 2019-12-20 or newer and Unity 2019.3-2020.3.

LWRP Shaders UPM packages com.esotericsoftware.spine.lwrp-shaders
spine.lwrp-shaders 4.1 2022-07-01 - Unity 2019.1
Compatible with spine-unity 4.1 and Unity 2019.1.
spine.lwrp-shaders 4.1 2022-07-01 - Unity 2019.2
Compatible with spine-unity 4.1 and Unity 2019.2.

spine.lwrp-shaders 4.0 2021-07-01 - Unity 2019.1
Compatible with spine-unity 4.0 and Unity 2019.1.
spine.lwrp-shaders 4.0 2021-07-01 - Unity 2019.2
Compatible with spine-unity 4.0 and Unity 2019.2.

spine.lwrp-shaders 3.8 2021-03-04 - Unity 2019.1
Compatible with spine-unity 3.8 and Unity 2019.1.

spine.lwrp-shaders 3.8 2021-03-04 - Unity 2019.2
Compatible with spine-unity 3.8 and Unity 2019.2.

Timeline Extensions UPM packages com.esotericsoftware.spine.timeline
spine.timeline 4.1 for spine-unity unitypackage (updated 2023-09-13)
Use this package if you have installed spine-unity from a unitypackage (the default).
Compatible with spine-unity 4.1 and Unity 2017.1-2023.1.
Alternative: spine.timeline 4.1 for spine-unity UPM (updated 2023-09-13)
Use this package if you have installed spine-unity via UPM packages using the Package Manager, instead of from a unitypackage. Compatible with spine-unity 4.1 and Unity 2017.1-2023.1.

spine.timeline 4.0 2022-06-01 for spine-unity unitypackage
Use this package if you have installed spine-unity from a unitypackage (the default).
Compatible with spine-unity 4.0 and Unity 2017.1-2022.1.
Alternative: spine.timeline 4.0 2022-06-01 for spine-unity UPM
Use this package if you have installed spine-unity via UPM packages using the Package Manager, instead of from a unitypackage. Compatible with spine-unity 4.0 and Unity 2017.1-2022.1.

spine.timeline 3.8 2021-03-19
Compatible with spine-unity 3.8 from 2019-10-3 or newer and Unity 2017.1-2020.3.

spine.timeline 3.8 2019-08-05
Compatible with spine-unity 3.8 before 2019-10-3 and Unity 2017.1-2019.2.