Licensing
A Spine license is required to integrate the Spine Runtimes into your applications.
Assets
Exporting Spine Assets for Unity
Export User Guide
You can find complete instructions in the Spine User Guide on how to
Spine Unity Export for Beginners
The following shows a simple way to export Spine assets for Unity.
-
After you have created your skeleton and animations, click on
Spine Menu
>Export...
(CTRL
+E
). This opens the Export window.
-
Choose
JSON
on the upper-left of the Export window.
Note: For production you should later prefer binary skeleton exports over JSON exports, as they are smaller in size and faster to load.
-
Check the
Texture Atlas
Pack
checkbox. (CheckingNonessential data
,Pretty print
are also recommended for beginners). Be sure to haveAnimation cleanup
disabled, otherwise keys identical to setup pose will not be exported.
- Click on
Pack Settings
below thePack
checkbox. This opens the Texture Packer Settings window. - On the lower-right, look for the textbox labeled
Atlas extension
and make sure it is set to.atlas.txt
. - You're done with the Texture Packer Settings window. Click
OK
to close.
- Click on
-
In the Export window, pick an output folder. (Recommendation: Create a new empty folder.)
-
Click
Export
. -
This will export three files:
skeleton-name.json
orskeleton-name.skel.bytes
, containing your skeleton and animation data.skeleton-name.atlas.txt
, containing information about the texture atlas.- One or more
.png
files, each representing on page of your texture atlas containing the packed images your skeleton uses.
Note: For 2D Toolkit users, Step 3 (packing a
.png
and.atlas.txt
) is not necessary. Instead, you will have the appropriate field in your SkeletonDataAsset to assign a reference totk2dSpriteCollectionData
. Please consult the Installation section on how to enable 2D Toolkit support.
Binary Export for Unity
Exporting in binary format instead of JSON will result in smaller file size and faster loading.
The following shows how to change to binary export for spine-unity.
- Choose
Binary
on the upper-left of the Export window instead ofJSON
. - Set the
Extension
to.skel.bytes
.
Note: spine-unity cannot load files with extension
.skel
. Be sure to use extension.skel.bytes
.
Advanced - Automating Exports
If you have many projects, it is recommended to automate the export of your skeleton and atlas assets using the Spine command line interface. This eliminates repetitive manual work and allows for easy re-export of all projects at once, should you decide to upgrade to a newer Spine version.
You can explore examples of utilizing the command line interface here.
For example, we use this script to export all the Spine example projects and to create texture atlases: export.sh
Advanced - Single Texture Atlas Export and SkeletonGraphic
It is recommended in general to use a single-texture (single-page) atlas where possible to reduce the number of draw calls caused by additional submeshes. This is especially true for SkeletonGraphic. Due to limitations of the used Unity CanvasRenderer
, SkeletonGraphic is limited to a single texture by default. You can enable Advanced - Multiple CanvasRenderers
at the SkeletonGraphic
component Inspector to generate a child CanvasRenderer
GameObject
for every submesh to raise the texture limit. For performance reasons, this is best avoided where possible. This means Skeletons used in UI shall be packed as a single-texture (single-page) atlas, rather than multi-page atlases.
If they do not fit into a single atlas page, you can pack texture atlas pages grouped by folder. This way you can ensure that each skin requires only a single atlas page.
When the images are placed in the respective folders, you can export the skeleton with the following steps:
- Press
Ctrl+E
or in the dropdown menu selectExport...
- Enable
Texture Atlas
Pack
and selectImage Folder
instead ofAttachments
right to it. - (optional) Check in
Pack Settings
if underOptions
in the bottom rightFlatten Paths
andCombine Subdirectories
is disabled (this is the default). - Click Export.
Advanced - Premultiplied vs Straight Alpha Export
Spine offers two basic workflows via Texture Packer Settings how atlas textures can be exported:
- Premultiplied alpha (the default, premultiplied in Gamma color space)
- Straight alpha
Premultiplied alpha workflow offers some advantages over straight alpha, no additional draw calls for additive-blended attachments and better mip-map generation being two of them.
It is very important to match export and import settings correctly, see section Advanced - Premultiplied vs Straight Alpha Import for correct settings in Unity.
Importing Spine Assets into Unity
- Open your Unity project in the Unity Editor. It should already have a functioning spine-unity runtime in it, as described in section Installation.
- Open the folder of the exported files. (
.json
,.atlas.txt
and.png
) - Copy the exported files (or the folder containing them) to your desired subfolder of your project's
Assets
folder. You can do this by dragging the exported files from an Explorer/Finder window into your desired folder in Unity's Project panel.
The spine-unity runtime will automatically generate the necessary additional Unity assets upon detecting the added files.
The following assets are generated:
- an _Atlas asset for the texture atlas file (
.atlas.txt
). It holds a reference to the material and the.atlas.txt
file. - a _Material asset for each texture atlas page (
.png
). It holds references to the shader and the.png
texture. - a _SkeletonData asset for skeleton data files (
.json
,.skel.bytes
). It holds a reference to the.json
or.skel.bytes
file and the generated _Atlas asset. It additionally provides custom import and animation settings for your skeleton, see section Skeleton Data Asset.
Advanced - Premultiplied vs Straight Alpha Import
As described in Advanced - Premultiplied vs Straight Alpha Export, Spine offers two basic workflows of how atlas textures can be exported:
- Premultiplied alpha (the default, premultiplied in Gamma color space)
- Straight alpha
Preferences parameter Atlas Texture Settings
for correct import settings
Important Note: It is very important that whenever the Premultiply alpha
setting is enabled upon atlas texture export, both the Material's Straight Alpha Texture
parameter and the Texture's Alpha Is Transparency
setting in Unity are disabled and vice versa. The spine-unity runtime provides a Spine
preferences section in Unity's Preferences
window, accessible via Edit - Preferences
(Unity - Preferences
on Mac). It provides an Atlas Texture Settings parameter to automatically apply the proper texture and material import settings at newly imported atlas textures. Right below you can find material templates for Additive Material
, Multiply Material
and Screen Material
. When switching to straight alpha workflow, these template material references need to be adjusted accordingly as well.
When exporting atlas textures from Spine with Premultiply alpha
enabled (the default), you can leave Atlas Texture Settings
at PMATexturePreset
, and the blend mode materials at SkeletonPMAAdditive
, SkeletonPMAMultiply
and SkeletonPMAScreen
. If you have disabled Premultiply alpha
, set Atlas Texture Settings
to StraightAlphaTexturePreset
and blend mode materials to SkeletonStraightAdditive
, SkeletonStraightMultiply
and SkeletonStraightScreen
. You can also create your own TextureImporter
Preset
asset and blend mode material templates and assign them here. When creating your own, it is recommended to choose a name with PMA
or Straight
in it to reflect the used blend mode.
Whenever you see dark borders around transparent areas, or colorful stripes around your attachment images, it is very likely because of incorrect import settings.
Correct Texture Packer export and Texture and Material import settings:
- Premultiplied Alpha Texture Packer setting
Premultiply alpha
enabled,
Unity Texture settingssRGB (Color Texture)
andAlpha Is Transparency
disabled,
Unity Material parameterStraight Alpha Texture
disabled.
Note:
sRGB (Color Texture)
was previously recommended to be enabled, however whenGenerate Mip Maps
is enabled, this combination may lead to white seams. To avoid these artifacts and because it has no drawbacks in Gamma space, it is now recommended to keepsRGB (Color Texture)
disabled with PMA textures.
- Straight Alpha Texture Packer setting
Premultiply alpha
disabled,Bleed
enabled,
Unity Texture settingssRGB (Color Texture)
andAlpha Is Transparency
enabled,
Unity Material parameterStraight Alpha Texture
enabled.
The default texture packer settings use Premultiply alpha
. All Spine shaders that come with the spine-unity runtime are also configured to use Premultiply alpha
workflow by default, they have the Straight Alpha Texture
parameter disabled as default.
There might are use cases however, where you may want to use straight alpha workflow. Some of the use cases are:
- When using Linear color space, you must use straight alpha.
The premultiplication is performed in Gamma space upon export, which will cause incorrect borders when converted back to Linear space on import. You will receive a log warning message when this combination is detected at a material. - When you want to use a shader other than the included Spine shaders.
Typically shaders will assume straight alpha textures, which will lead to incorrect black borders around attachment images.
Be sure to configure all textures and materials accordingly as described above when switching to straight alpha workflow. You can check or modify the current color space via Project Settings - Player - Other Settings - Color Space
.
Import Troubleshooting
When something goes wrong importing your skeleton into Unity there are a number of possible causes, from incorrect Spine export settings to incorrect settings in Unity. This video will help you better understand the correct settings for many common problems during import.
Advanced - Unity SpriteAtlas as Atlas Provider
Note: It is encouraged to follow the normal Spine workflow and use sprite atlases created by Spine instead of Unity
Sprite Atlas
assets. Spine atlases provide superior packing, support multiple atlas pages and are less prone to problems. Use Unity'sSprite Atlas
assets as an atlas provider only when you cannot use the normal Spine workflow. Also consider that you can re-pack used texture regions of a collected skin to a single atlas texture at runtime.
You can use Unity's SpriteAtlas
as atlas provider as an alternative to .atlas.txt
and .png
files alongside a skeleton data file. Import is handled via a special Spine SpriteAtlas Import
tool window accessible via Window - Spine - SpriteAtlas Import
.
Steps to prepare the Sprite Atlas
:
- Create a
Sprite Atlas
viaAssets - Create - Sprite Atlas
. - Add the folder containing the Sprites to be used as attachments to
Objects for Packing
in theSprite Atlas
Inspector. - (a) For Unity versions prior to 2018.2, please manually disable
Tight Packing
and enableRead/Write Enabled
.
(b) in Unity versions 2018.2 an newer, these settings are automatically adjusted for you. - Assign the
Sprite Atlas
to theSprite Atlas
property in the newSpine SpriteAtlas Import
window. Additional assets are generated automatically. - Hit
Load regions by entering Play mode
to briefly switch into play mode and back again to load the region information. YourSprite Atlas
is now ready for use as a Spine atlas.
To use the atlas at a .json
or .skel.bytes
skeleton asset:
- Place the
.json
or.skel.bytes
file in the same directory as the newly created atlas assets. - Assign it to the
Skeleton json/skel file
property in theSpine SpriteAtlas Import
window. - Hit
Import Skeleton
to generate the_SkeletonData
file using theSprite Atlas
assets.
Spine Preferences
The spine-unity runtime provides a Spine
section in Unity's Preferences
window, accessible via Edit - Preferences
(Unity - Preferences
on Mac). Here you can setup default values used upon skeleton import and instantiation, as well as customize appearance and update behavior of the spine-unity runtime.
- Show Hierarchy Icons. Show relevant icons next to
GameObjects
in the Hierarchy panel with Spine components on them. - Auto-reload scene components. Reloads skeleton components in the scene whenever their SkeletonDataAsset is modified. This may be slow when your scenes have large numbers of SkeletonRenderer or SkeletonGraphic components.
- Reload SkeletonData after Play. When enabled, the shared SkeletonData of all skeletons in the active scene is reloaded (from the .json or .skel.bytes file) after exiting play-mode. This may add undesired delays, but prevents (accidental) modifications to the shared SkeletonData during play-mode carrying over its effect into subsequent plays.
- Auto-Import Settings
- Default Mix. The Default Mix Duration for newly imported SkeletonDataAssets.
- Default SkeletonData Scale. The default
Scale
value for newly imported SkeletonDataAssets. - Default Shader. The default shader assigned at materials created for newly imported skeleton atlas textures.
- Apply Atlas Texture Settings. Apply reference
Atlas Texture Settings
at texture importers specified below. - Atlas Texture Settings. Apply the selected texture import settings at newly imported atlas textures and materials. When exporting atlas textures from Spine with
Premultiply alpha
enabled (the default), you can leave it atPMATexturePreset
. If you have disabledPremultiply alpha
, set it toStraightAlphaTexturePreset
. You can also create your ownTextureImporter
Preset
asset and assign it here. - Additive Material. Material template for slot blend mode
Additive
. SeeSkeletonData
Blend Mode Materials. - Multiply Material. Material template for slot blend mode
Multiply
. SeeSkeletonData
Blend Mode Materials. - Screen Material. Material template for slot blend mode
Screen
. SeeSkeletonData
Blend Mode Materials.
- Warnings
- Atlas Extension Warning. Log a warning and recommendation whenever a
.atlas
file is found. - Texture Settings Warning. Log a warning and recommendation whenever texture import settings are detected that could lead to undesired effects, e.g. white border artifacts.
- Component & Material Warning. Log a warning and recommendation whenever Component and Material settings are not compatible.
- SkeletonDataAsset no file Error. Log an error when querying
SkeletonData
fromSkeletonDataAsset
with no json or binary file assigned.
- Atlas Extension Warning. Log a warning and recommendation whenever a
- Editor Instantiation
- Default Slot Z-Spacing. The default Z Spacing parameter of newly instantiated SkeletonRenderer or SkeletonGraphic components.
- Default Loop. The default
Loop
parameter of newly instantiated SkeletonRenderer or SkeletonGraphic components. - Physics Inheritance
- Default Position. The Default Physics Inheritance - Position scale factor parameter of newly instantiated SkeletonRenderer or SkeletonGraphic components.
- Default Rotation. The Default Physics Inheritance - Rotation scale factor parameter of newly instantiated SkeletonRenderer or SkeletonGraphic components.
- Mecanim Bake Settings
- Include Folder Name in Event. When enabled, Mecanim events will call methods named
"FolderNameEventName"
, when disabled it will call"EventName"
.
- Include Folder Name in Event. When enabled, Mecanim events will call methods named
- Handles and Gizmos
- Editor Bone Scale. Size of bones and similar gizmo elements displayed in the Scene view.
- Prefabs
- Fix Prefab Overr. MeshFilter. Global setting for the equally named skeleton component Inspector parameter, section Advanced. When the component parameter is set to
Use Global Settings
, this setting is used. - Optimize Preview Meshes. When enabled, Spine prefab preview meshes will be removed in a pre-build step to reduce build size. This increases build time as all prefabs in the project will be processed.
- Fix Prefab Overr. MeshFilter. Global setting for the equally named skeleton component Inspector parameter, section Advanced. When the component parameter is set to
- Timeline Extension - relevant for the Timeline Extension UPM Package
- Default Mix Duration. The default value for the
Default Mix Duration
parameter of newly createdSpine Animation State Clips
. - Use Blend Duration. The default value for the
Use Blend Duration
parameter of newly createdSpine Animation State Clips
.
- Default Mix Duration. The default value for the
Updating Spine Assets
During development, you may frequently update your Spine skeleton data and texture atlas files. You can simply overwrite these files (.json
, .skel.bytes
, .atlas.txt
, .png
). Re-export the assets from the Spine Editor and copy the exported files to your subfolder of your project's Assets
folder again, overwriting the existing files.
Unity will detect changes to these files and automatically re-import the modified assets. After re-import, all references to previously imported Spine assets will be intact and use the latest data.
Note: Unity sometimes fails to recognize file changes. In this case, locate the folder containing the Spine assets in Unity's Project panel that you want to re-import, right-click on the folder, then select
Reimport
from the context menu.
Skeleton Data Asset
The skeleton data asset (named with suffix _SkeletonData
) stores information about the bone hierarchy, slots, draw order, animations and other data that constitutes your skeleton. Other components provided by the spine-unity runtime reference and share this skeleton data asset to animate and display a skeleton.
To inspect or modify a skeleton data asset, select it in Unity's Project panel. The Inspector panel will display all properties of the skeleton data for review and modification.
Skeleton Data
The SkeletonData section provides general import settings of the skeleton.
-
Scale. Allows you to specify a custom import scale value, affecting all skeleton instances referencing this data asset. Changing the value will immediately affect all instances of this skeleton.
Note: When you want to precisely match e.g. 32px of artwork to 1 game unit (and the attachment images have not been scaled in Spine), you can set this
Scale
parameter to1/px_per_unit
. So for32px/unit
you would setScale
to1/32 = 0.03125
. -
SkeletonData Modifiers. Provide a way for users to add additional processing to skeleton data assets after loading from a
.json
or.skel.bytes
file has been completed. Please consult section SkeletonData Modifier Assets below for additional information. -
Blend Modes - Upgrade. Upgrades an obsolete
BlendModeMaterialAsset
to the native Blend Mode Materials properties shown below. -
Blend Mode Materials. Skeleton slots with special blend modes require additional materials. These materials are setup automatically upon import, unless a
BlendModeMaterialAsset
is in use with older Unity and spine-unity versions. It is recommended to upgrade an assignedBlendModeMaterialAsset
via theBlend Modes - Upgrade
button above, as it prevents problems with newer Unity versions. You can customize material templates for each blend mode in the Spine Preferences.- Apply Additive Material. When enabled, slots with
Additive
blend mode will also have materials generated for them. Enable this parameter when using Straight alpha workflow. It is not necessary when using PMA workflow asNormal
andAdditive
slots can be drawn with the same PMA material. - Additive Materials, Multiply Materials, Screen Materials. These lists show the currently used blend mode materials for each blend mode.
- Apply Additive Material. When enabled, slots with
Atlas
Atlas references are used by the skeleton to resolve the exported image name references to the respective image areas for rendering.
Upon import the Atlas Assets
array is automatically populated with one entry per atlas asset (ending with _Atlas).
In case spine-unity failed to automatically assign all required atlas assets, you can change the Atlas Assets
Size
to the desired amount of atlas assets and manually assign the required atlas assets to Element0
- ElementN
.
Mix Settings
The skeleton data asset allows you to specify animation mix times.
Default Mix Duration
allows you to enter the default mix time, in seconds.
You can define mix times for two specific animations by clicking the Add Custom Mix
button in the Custom Mix Durations
section of the asset and setting specific mix durations, overriding the default mix duration value above.
Components using the skeleton data asset, like the skeleton animation component, use these mix times when playing back animations.
Preview
The Preview section for a skeleton data asset allows you to inspect all bones, slots, animations, skins, and events contained in the asset.
You can playback animations via the play buttons to the left of each animation and view a live update of the respective slots via Show Attachments
in the Slots
section. The timeline bar shows all events as purple markers. Hover over the markers while playing to display the event name.
Use the Create Animation Reference Assets
button to generate reference assets for all animations of the skeleton. An AnimationReferenceAsset
acts as a Unity asset referencing a single Spine.Animation
and can be assigned to component properties in the Inspector.
Skeleton Mecanim
In case you want to use Unity's Mecanim animation system instead of Spine's default animation system, you can generate and assign a Mecanim controller via Generate Mecanim Controller
.
Skeleton Baking
Note: Baking is a specialized tool and is not the recommended way of using Skeletons in spine-unity! It is not used for SkeletonMecanim, SkeletonAnimation or SkeletonGraphic (UI) components! It will instead bake a Skeleton down to a less flexible Prefab with a fixed hierarchy of
Transforms
withMeshRenderers
and compatible animation clips. A lot of Spine's features don't exist in Unity's Animation system so they can't be translated and are ignored in the process.
To open the Skeleton Baking Window
, click on the gear icon at the top right of the SkeletonDataAsset
Inspector and choose Skeleton Baking
.
A detailled list of supported and unsupported features can be found here in SkeletonBaker.cs.
Note: Baking is not using the recently added Unity 2D animation system but the previously existing 3D
MeshRenderer
based system.
Texture Atlas Asset
The texture atlas asset contains information about the images used by your skeleton, namely on what texture atlas page an image is stored, as well as its UV texture coordinates on the texture atlas page.
You can view the material of the texture atlas pages by double clicking the material asset in the Materials
array.
Note: You can modify the materials and textures referenced by the texture atlas asset. When modifying textures, make sure the UV texture coordinates stay valid. The
SkeletonRenderer
components use a normalMeshRenderer
for rendering, so materials and textures are applied normally just like they would when assigned at e.g. a cube or quad. So you can replace or pre-process the textures at the materials of your Texture Atlas Asset as needed.
The Set Mipmap Bias to -0.5
button is intended for advanced users and can be used to compensate for blurry appearance when Generate Mip Maps
is enabled on an atlas texture.
You can generate sprites for each image element of an atlas by pressing the Apply Regions as Texture Sprite Slices
button. The generated sprites reference areas of the texture atlas image (png
file) and can be used as any Unity sprite asset.
SkeletonData Modifier Assets
SkeletonData modifier assets provide a way for users to add additional processing to skeleton data assets after loading from a .json
or .skel.bytes
file has been completed.
SkeletonDataAsset's Inspector provides a Skeleton Data Modifiers
list you can add assets to.
Writing a custom SkeletonDataModifierAsset class
You can write your own custom SkeletonDataModifierAsset
class to add additional processing to skeleton data assets after loading from a .json
or .skel.bytes
file. SkeletonDataModifierAsset
is an abstract ScriptableObject
class where you can derive your own classes from.
-
Create a new class derived from
SkeletonDataModifierAsset
and implement thevoid Apply (SkeletonData skeletonData)
method. Add theCreateAssetMenu
class attribute to list an entry for your class in theAsset -> Create
menu.C#[[CreateAssetMenu(menuName = "TopMenu/Submenu/SubSubmenu", order = 200)]
public class BlendModeMaterialsAsset : SkeletonDataModifierAsset {
public override void Apply (SkeletonData skeletonData) {
...
}
} -
Create an instance of your new class by selecting your desired folder in the Project panel and selecting your newly created
Asset -> Create
menu entry. Assign the created asset at an element of theSkeleton Data Modifiers
list of your SkeletonData asset.
Apply(skeletonData)
will be called after loading data from the .json
or .skel.bytes
file has been completed.
BlendModeMaterialsAsset Modifier Asset (obsolete)
Note: spine-unity now provides native support for slot blend modes
Additive
,Multiply
andScreen
at eachSkeletonDataAsset
, with automatic setup at newly imported skeleton assets.BlendModeMaterialAssets
are now obsolete and replaced by the native properties atSkeletonDataAsset
. TheSkeletonDataAsset
Inspector provides a newBlend Modes - Upgrade
button to upgrade an obsoleteBlendModeMaterialAsset
to the native blend modes properties. This upgrade will be performed automatically on imported and re-imported assets in Unity 2020.1 and newer to prevent reportedBlendModeMaterialAsset
issues in these Unity versions. spine-unity 4.0 and newer will automatically perform this upgrade regardless of the Unity version.
BlendModeMaterialsAsset
is a SkeletonData modifier asset class included in spine-unity. It holds references to materials that can be used to render attachments within slots that have the Additive
, Multiply
and Screen
blend modes assigned to them in the Spine editor.
The Material references stored in BlendModeMaterials assets are used as templates to generate new Materials that use the appropriate texture needed by the loaded attachments.
The spine-unity runtime comes packaged with a ready-to-use BlendModeMaterialsAsset
named Default BlendModeMaterials
. Using this included asset allows the attachments in slots with special blend modes to use the included default Multiply
and Screen
shaders: Spine/Blend Modes/Skeleton PMA Multiply
and Spine/Blend Modes/Skeleton PMA Screen
.
If you need to use different Materials or shaders or Materials with different settings, you can create new BlendModeMaterialsAsset
s using Create -> Spine -> SkeletonData Modifiers -> Blend Mode Materials
. Then assign your Material templates to the created asset.