spine-runtimes/spine-unity

spine-unity

The spine-unity runtime provides functionality to load, manipulate and render Spine skeletal animation data using Unity. spine-unity is based on spine-csharp.

For more documentation, see spine-unity Documentation.

While spine-unity can render directly with Unity, without the need for any other plugins, it also works with 2D Toolkit and can render skeletons using a TK2D texture atlas.

Licensing

This Spine Runtime may only be used for personal or internal use, typically to evaluate Spine before purchasing. If you would like to incorporate a Spine Runtime into your applications, distribute software containing a Spine Runtime, or modify a Spine Runtime, then you will need a valid Spine license. Please see the Spine Runtimes Software License for detailed information.

The Spine Runtimes are developed with the intent to be used with data exported from Spine. By purchasing Spine, Section 2 of the Spine Software License grants the right to create and distribute derivative works of the Spine Runtimes.

Spine version

spine-unity works with data exported from the latest version of Spine.

spine-unity supports all Spine features.

Documentation

A Spine skeleton GameObject (a GameObject with a SkeletonAnimation component on it) can be used throughout Unity like any other GameObject. It renders through MeshRenderer.

SkeletonUtility allows other GameObjects to interact with the Spine skeleton, to control bones in the skeleton, be controlled by the skeleton, attach colliders, etc.

For advanced uses and specific optimization cases, Spine skeletons can be "baked" into native Unity animation assets. Since Unity's animation feature-set does not overlap with Spine's perfectly, baked assets have many limitations and removed features. For most uses, baking is not necessary.

The Spine Unity Features Tutorial forum thread has many videos on how to use spine-unity.

For more documentation, see spine-unity Documentation.

Quick installation

Download and run this Unity package:

spine-unity.unitypackage

In the Assets/Examples/Scenes folder you will find many example scenes that demonstrate various spine-unity features.

Note: If you are still using Spine 2.1.xx, you'll need to use the older 2.1.xx compatible runtime. You can find it here: spine-unity-v2.unitypackage

Manual installation

You can also choose to setup and run from the Git files:

1. Download the Spine Runtimes source using git or by downloading it as a zip.
2. spine-unity requires both spine-csharp and spine-unity.
   • Copy the contents of spine-csharp/src to Assets/spine-csharp in your Unity project directory.
   • Copy the contents of spine-unity/Assets to Assets in your Unity project directory. Including Gizmos and spine-unity and Examples if you want them.

• Gizmos is a special folder in Unity. It needs to be at the root of your assets folder to function correctly. (ie. Assets/Gizmos

• spine-csharp and spine-unity can be placed in any subfolder you want.

---

Importing skeleton data

1. Add your .json, .atlas.txt and .png into your Unity project.
   • You can do this through Unity's Project View: Drag and drop a folder containing the .json, .atlas.txt and .png files exported from Spine directly into the Unity Project view.
   • ... or you can opt to do this through Windows File Explorer or OSX Finder. Move or copy your .json, .atlas.txt and .png files into your Unity project's Assets folder, ideally in its own subfolder.
2. spine-unity will automatically detect the .json and .atlas.txt and attempt to generate the necessary spine-unity assets.
3. To start using your Spine assets, right-click on the SkeletonDataAsset (the asset with the orange Spine logo on it) and choose Spine > Instantiate(SkeletonAnimation). This will add a GameObject with a SkeletonAnimation component on it.
   • If you are more familiar with Mecanim, you may choose Spine > Instantiate(Mecanim) instead.
4. For more info on how to control the animation, see the spine-unity Animation Control documentation.

The original manual setup video to shows which assets belong where and what spine-unity's automatic import actually does for you under the hood. In case you have a specialized asset setup, this video will be useful for understanding how assets fit together.

More resources:

• Drag and drop video
• readme PDF

---

Notes

• This slightly outdated spine-unity tutorial video may still be useful.
• Atlas images should use Premultiplied Alpha when using the shaders that come with spine-unity (Spine/Skeleton or Spine/SkeletonLit).
• Texture sizes: Unity scales large images down by default if they exceed 1024x1024. This can cause atlas coordinates to be incorrect. To fix this, make sure to set import settings in the Inspector for any large atlas image you have so Unity does not scale it down.
• Texture artifacts from compression: Unity's 2D project defaults import new images added to the project with the Texture Type "Sprite". This can cause artifacts when using the Spine/Skeleton shader. To avoid these artifacts, make sure the Texture Type is set to "Texture". spine-unity's automatic import will attempt to apply these settings but in the process of updating your textures, these settings may be reverted.