Forums | Documentation | GitHub

Getting Started

Getting Started Documentation


The Latest Spine-Unity Runtime Unitypackage:

Spine-Unity 3.7 runtime unitypackage:
DOWNLOAD : https://esotericsoftware.com/files/runtimes/unity/spine-unity-3_7-2019-07-10.unitypackage
Compatible with Spine 3.7.x and Unity 5.6-2018.3b (Last updated: UTC - 2019 Jul 10)
For the changelog, see 3.7/CHANGELOG.md

Spine-Unity 3.8-beta runtime unitypackage:
DOWNLOAD : https://esotericsoftware.com/files/runtimes/unity/spine-unity-3_8-2019-07-17-beta.unitypackage
Compatible with Spine 3.8.x and Unity 2017.1-2019.1 (Last updated: UTC - 2019 Jul 17) For the changelog, see 3.8-beta/CHANGELOG.md

The Latest Spine-Unity Extension UPM (Unity Package Manager) Packages:

LWRP Shaders 3.8-beta UPM package com.esotericsoftware.spine.lwrp-shaders: DOWNLOAD: https://esotericsoftware.com/files/runtimes/unity/com.esotericsoftware.spine.lwrp-shaders-3_8-2019-07-17-beta.zip Compatible with Spine-Unity 3.8-beta and Unity 2019.1 (Last updated: UTC - 2019 Jul 17)

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 Getting Started.
For more options, see the documentation section on Installing.

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)

  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.
  • Much older versions of the unitypackage had inconsistent meta files for spine-c#. You may have to delete the older spine-csharp folder when updating. This otherwise works correctly.
  • Occasionally, major refactoring involves removing or merging some files. Importing the .unitypackage will not delete those leftover files when you update so you may have to do that yourself. Check here for announcements regarding changed/leftover files: http://esotericsoftware.com/forum/Noteworthy-Spine-Unity-Topics-5924

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

Installing Spine-Unity Extension UPM (Unity Package Manager) Packages

  1. Download the Unity Package Manager (UPM) package via the download links above or find it in the spine-runtimes/spine-unity/Packages 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 `
/Packages/` 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. - UnityEngine.UI.MaskableGraphic does not support using more than one texture, so uses of SkeletonGraphic are limited to skeletons with only one atlas page/texture. At the cost of masking, an experimental version of SkeletonGraphic which splits it into multiple UI objects can be found here: http://esotericsoftware.com/files/runtimes/unity/spine-unity-experimental-SkeletonGraphicMultiObject-3_6-2018-04-19.unitypackage - 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 Getting Started](http://esotericsoftware.com/spine-unity#Getting-Started) - 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](http://esotericsoftware.com/forum/Spine-editor-and-runtime-version-management-6534). **Fixed Bugs** * (2019 Jul 17) Note: A lot of restructuring has been performed, please consult the CHANGELOG.md file for further info. * (2019 Jul 17) Fixed json curve import: was mis-interpreting curves as linear instead of a smooth curve. * (2019 Jul 17) Fixed a bug in SpineMecanim which caused dipping to SetupPose during transitions due to MixBlend.Replace on first track. * (2019 Jul 10) Fixed example asset stretchyman normal and emission maps. * (2019 Jul 10) Changed default `sRGB (Color Texture)` attribute at spine atlas texture import back to `true`. This creates consistent and correct look in linear and gamma color space which is more important than rare mipmap problems. * (2019 Jun 18) Fixed runtime import hanging on "Importing small assets" in Unity 2019.3 and creating multiple Assets/Editor1-N dirs. * (2019 Jun 16) Fixed a crash upon importing realted to stencil mode auto-updater. * (2019 Jun 13) Fixed root bone transform for skeleton scale to use world axes. * (2019 Jun 03) Fixed endless loop in Unity Editor when updating assets due to stencil parameter auto-update. * (2019 May 28) Fixed Spine shaders not displaying on Nintendo Switch. * (2019 May 15) Fixed a rare bug regarding incorrect attachment state after multiple transitions. Now the last subsequent attachment timeline always mixes out to the setup pose. * (2019 May 13) Fixed locale-based potential exceptions when parsing a Spine atlas. * (2019 May 10) Fixed `Shadow alpha cutoff` shader parameters ignoring SlotColor.alpha at all Spine shaders. Now texture color alpha is multiplied with slot color alpha before the alpha test. * (2019 May 02) Fixed error message "Animator is not playing an AnimatorController" at SkeletonMecanim and prefabs. * (2019 Apr 27) Changed line endings in .cginc and .shader files to lf to prevent automatically created warnings by Unity's code updater which inserts lines with lf line endings. * (2019 Apr 27) Now using SettingsProvider for Spine Preferences. This stores Spine settings in Assets/Editor/SpineSettings.asset which can be shared with team members. * (2019 Apr 25) Fixed initial animation not being mixed out in some circumstances due to PoseSkeleton call. Removed PoseSkeleton and PoseWithAnimation extension methods to prevent related issues on user side. Fixed incorrect random Nth frame preview in Scene view for SkeletonAnimation and SkeletonGraphic. * (2019 Apr 25) Fixed unnecessary updates in editor when SkeletonRenderer is selected. * (2019 Apr 18) Fixed SkeletonDataAsset auto-update mechanism on .json file change for both scene view and inspector. * (2019 Apr 18) Fixed "Skin not found: default" error at binary .skel.bytes files when instantiating a skeleton via SkeletonGraphic. * (2019 Apr 17) Fixed broken inspector preview in Unity 2019. * (2019 Apr 05) Fixed SkeletonMecanim leftover animation rotations when transitioning to an empty "Write Defaults" state. * (2019 Apr 02) Fixed SkeletonMecanim layer blend modes, now it detects Override/Add from the animation controller. * (2019 Apr 02) SkeletonMecanim: Fixed some animator related warnings in editor. * (2019 Mar 26) Fixed wrong atlas assets being assigned upon import when multiple skeletons are exported to the same directory. * (2019 Mar 20) Added SkeletonUtilityBone's missing 'Create 2D Hinge Chain' button in inspector. * (2019 Mar 19) Fixed incorrect behavior in animation transitions, e.g. deform timeline behavior upon rewind. * (2019 Mar 19) Fixed exception in incorrect material setting detection mechanism. * (2019 Mar 04) Now materials are no longer cleared to null when MeshRenderer is disabled. * (2019 Feb 26) Fixed another occurrence of compile errors when enabling the TK2D define due to asmdef files. * (2019 Feb 15) Fixed compile errors when enabling the TK2D define due to asmdef files preventing dependency. * (2019 Feb 11) Fixed Unity Timeline editor errors after `Add Spine Animation State Clip Clip` due to unset Animation Reference. * (2019 Feb 11) Fixed AnimationState not respecting MixBlend.first for rotate timelines. * (2019 Feb 07) SkeletonRenderSeparator now initializes added SkeletonPartsRenderer children correctly. * (2019 Feb 06) Fixed SkeletonPartsRenderer mesh tangent error. Also fixed another potential size mismatch at mesh normals/tangents vs vertices. * (2019 Feb 04) Fixed compilation errors when TK2D define is set. * (2019 Feb 01) Fixed another import error with message 'Skeleton JSON file not set for SkeletonData asset'. * (2019 Jan 31) Fixed a SkeletonGraphic related import error occurring occasionally on first import. Error message was usually 'Skeleton JSON file not set for SkeletonData asset'. * (2019 Jan 29) Added warning to prevent light ghosting artifacts in transparent area when `Alpha Is Transparency` is enabled on PMA textures. * (2019 Jan 28) Changed default texture settings and added warning to prevent white border artifacts when mip maps are enabled on PMA textures. * (2019 Jan 28) Fixed SkeletonGraphic's 'Starting Animation' property being cleared upon saving under some circumstances. * (2019 Jan 22) Fixed PointFollower error message on script rebuild. * (2019 Jan 16) Fixed removing unreferenced SlotBlendMode material entries. * (2019 Jan 14) Fixed errors upon "Reimport All". * (2019 Jan 09) Fixed SpineAtlasRegionDrawer label error. * (2019 Jan 09) Fixed 'Instantiate from Script' example (missing script in SkeletonGraphic part). * (2019 Jan 09) Fixed 'Goblins'' example scene click behaviour. * (2018 Dec 29) Made components compatible with new 2018.3 Prefab Mode. * (2018 Dec 29) Minor fix for EditorInstantiation.NewGameObject. * (2018 Dec 18) Mesh Generation: Fixed Tint Black buffers sometimes becoming the wrong size when the vertex buffer changes. * (2018 Dec 17) Added missing Skeleton scale initializer. (3.7) * (2018 Dec 17) Fixed path constraint computations being invalid if a path's length is ever NaN. * (2018 Dec 12) Fixed some cases where SkeletonGraphic prefabs log errors when imported. * (2018 Dec 12) Normalized line-endings in the unitypackage to CRLF. * (2018 Dec 10) Handled case where assets may be located in a different folder. * (2018 Dec 10) Fixed prefab warnings for 2018.3 where baking is inapplicable. * (2018 Dec 10) Fixed SkeletonBakingWindow directives in the header in the wrong order. * (2018 Dec 10) Fixed disable inherit scale, especially when skeleton is flipped. * (2018 Dec 8) Fixed runtime repacking case where there were zero textures repacked. * (2018 Dec 7) Fixed atlas processing where the Atlas asset was invalid. * (2018 Dec 5) Fixed the "Set Texture Importer Settings" editor preference not being stored correctly. * (2018 Nov 28) Fixed a bug where slot color animations behaved unexpectedly relative to setup pose. * (2018 Nov 15) Fixed SkeletonRenderers using the arrays branch of mesh generation not storing the correct submesh count. This affected tangent calculations for SkeletonRenderers that used multiple submeshes and materials. * (2018 Nov 12) Fix SkeletonRenderSeparator not updating when instantiated in Unity Editor edit mode. * (2018 Nov 12) Fix SkeletonGraphic runtime instantiation not having a required material parameter. * (2018 Nov 12) Fix SkeletonUtility not following IK bones correctly. * (2018 Oct 24) Fixed WorldToLocalRotation and LocalToWorldRotation rotation transformation functions on the Bone class to account for local rotation and shearX. * (2018 Oct 18) Fixed MeshGenerator disposing previously created buffer objects, potentially causing unnecessary GC alloc when per-submesh branch of mesh generation is used. * (2018 Oct 17) Fixed MeshGenerator causing GC alloc per frame when per-submesh branch of mesh generation is used, such as when ClippingAttachments are active. * (2018 Oct 8) Fixed SkeletonRenderer/SkeletonAnimation skin field not applying changes reliably when multi-editing. * (2018 Oct 8) Fixed obsolete code causing warnings from using flip instead of scale in SkeletonFlip timeline mixer. * (2018 Oct 8) Fixed data reloading when SkeletonRenderer/SkeletonAnimation/SkeletonGraphic had missing textures and materials when switching from play mode to edit mode. * (2018 Oct 1) Fixed an bug where cloned linked meshes would not retain the original MeshAttachment color. * (2018 Sep 25) Fixed an issue where Rigidbody2D would be added at runtime without warning. * (2018 Sep 24) Fixed an issue where SkeletonAnimation and SkeletonGraphic Initialize raises the first events, which causes them to skip those events on the first Update. First events should now be correctly raised on the first Update. * (2018 Sep 24) Fixed a bug where initial flipX and flipY would be copied to all selected Spine objects when multi-selected in Unity editor. * (2018 Sep 10) Fixed a bug where AnimationState would cause an infinite loop from a cycling linked list. * (2018 Aug 25) Fixed a bug where using GetRemappedClone without PMA would result in an attachment without a Material. * (2018 Aug 25) Fixed a bug where rotation timelines would spin indefinitely. * (2018 Jul 17) Fixed a typo in the conditional compile for Unity 2017.2 and above. * (2018 Jul 2) Fixed a bug where AtlasUtilities.GetRepackedAttachments would have misaligned arrays when your attachment list had non-renderable Attachments. * (2018 Jun 7) Fixed an issue where a Spine-generated mesh would leak if you force-reinitialized a SkeletonRenderer/SkeletonAnimation/SkeletonAnimator. * (2018 May 25) Fixed an issue where the first frame of a (Unity Timeline) SpineAnimationStateClip playing would not visually reflect the new animation despite having no mixing. * (2018 May 24) Fixed a bug where skeleton previews were not working, or animation previews were playing too fast. * (2018 May 10) Fixed a bug where clipping would function incorrectly with SkeletonRenderSeparator. * (2018 Apr 12) Fix case where Tint Black was used and no attachments were rendered causing a NullReferenceException. * (2018 Mar 27) Fix SpineAttributes not correctly detecting sibling or base properties, especially when array fields are involved. * (2018 Mar 23) Fixed new tangents not being solved every frame. * (2018 Mar 14) Fix DrawBoundingBox. * (2018 Feb 8) Fix "none" item for SpineSlot attribute. * (2018 Jan 12) [AnimationState] Fixed incorrect delay being calculated for non-loop animations. * (2018 Jan 9) Fixed previous BoneFollower fix not applied to world-space Transform mode. * (2018 Jan 8) Fixed BoneFollower adding redundant rotation when bone is locally flipped and BoneFollower is following local scale. * (2018 Jan 6) Fixed SkeletonAnimator not caching clip info in existing lists in Unity 5.6. It caused memory allocation per frame. * (2018 Jan 5) Fixed SkeletonAnimator's MecanimTranslator not clearing completely when calling Initialize. * (2017 Dec 24) We've temporarily removed the included asmdef file until we can add and arrange the editor assembly definitions so that building for the target platform works. * (2017 Dec 22) Fixed the BoundingBoxFollower inspector not correctly initializing the BoneFollower it creates through the Add BoneFollower button. * (2017 Dec 15) Fixed a Clipping attachment bug where clipping would not stop if the end slot was empty or non-renderable (eg, had a BoundingBoxAttachment, PathAttachment or PointAttachment). * (2017 Dec 7) Fixed handling of play-pause in the SkeletonDataAsset inspector. * (2017 Nov 13) Fixed the Drag-and-Drop cursor tooltip "Create Spine GameObject" not showing up. * [See history...](http://esotericsoftware.com/spine-unity-history#Fixed-Bugs) **Important notes when upgrading** * (2017 October 16) The old AttachmentTools static class called `SpriteAtlasAttachmentExtensions` was renamed AtlasUtilities. Any methods that were called as statics rather than extension methods must now refer to that new name. Extension method calls will not need any code changes. * (2017 June 11) SkeletonGraphic now allows you to override the mainTexture with a repacked texture using SkeletonGraphic.OverrideTexture. * (2017 May 6) Sprite Shaders: When updating shaders from any source, especially ones that use cginc files, it may be necessary to restart Unity or right-click then choose `Reimport All` in the project panel so the cginc files are properly reimported. https://forum.unity3d.com/threads/is-there-a-way-to-force-shaders-to-update-when-cginc-files-are-updated.336041/ * (2017 May 6) Sprite Shaders: Some files from the older version of the Sprite shaders were removed. delete the whole `spine-unity/Modules/Shaders/Sprite` subfolder before upgrading to ensure no old unused files are left behind. * (2017 May 6) Sprite Shaders: Updated to the latest source version. Some serialization may have changed. If you used these shaders, do go over your Material assets and make sure they have the correct settings: https://github.com/traggett/UnitySpriteShaders * (2017 Mar 30) You now have the option to disable multi-mixing to get rid of the dipping issue. This can be set with the `AnimationState.MultipleMixing` bool property. In 3.5, it is enabled by default so updating your runtime will not result in unexpected changes in animation behavior. You can change the code so AnimationState sets the value to false by default to remove unwanted dipping at the cost of multiple mixing. This default may change in 3.6. * (2017 Jan 24) Based on Unity Technology recommendations, whenever SkeletonUtility (or BoundingBoxFollower) generates PolygonColliders based on Spine Bounding Boxes, it will also add a Kinematic Rigidbody2D to that object. This means each of those GameObjects are their own immutable box2D body and cost significantly less computationally to move/animate. * [See history...](http://esotericsoftware.com/spine-unity-history#Important-Notes-when-Upgrading) ---------- ## Older Versions **Spine-Unity 3.6 for Unity 5.6-2018.2:** https://esotericsoftware.com/files/runtimes/unity/spine-unity-3_6-2019-05-13.unitypackage (Last updated: UTC - 2019 May 13) **Spine-Unity 3.6 for Unity 5.4:** http://esotericsoftware.com/files/runtimes/unity/spine-unity-3_6_Unity-5_4-2017-06-20.unitypackage (Last updated: UTC - 2017 June 20) **Spine-Unity 3.5 for Unity 5.4-2017.1:** http://esotericsoftware.com/files/runtimes/unity/spine-unity-3_5_Unity-5_4.unitypackage (Last updated: UTC - 2017 June 18) **Spine-Unity 3.0 for Unity 4.6:** http://esotericsoftware.com/files/runtimes/unity/spine-unity-3_0_Unity-4_6.unitypackage (Last updated: UTC - 2017 May 9)