Licensing

!! A Spine license is [required](/git/spine-runtimes/spine-unity#licensing) to integrate the Spine Runtimes into your applications.
spine-unity Runtime Documentation
!! * [Installation](/spine-unity-installation) * [Examples](/spine-unity-examples) * [Assets](/spine-unity-assets) * [Main Components](/spine-unity-main-components) * [Utility Components](/spine-unity-utility-components) * [Rendering](/spine-unity-rendering) * [Timeline Extension UPM Package](/spine-unity-timeline) * [On-Demand Loading Extension UPM Packages](/spine-unity-on-demand-loading) * [FAQ](/spine-unity-faq)
!! # FAQ ## Import 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. !! > **Why does import fail with a window saying "Could not automatically set the AtlasAsset for .."?** ![](/img/spine-runtimes-guide/spine-unity/CommonError-AtlasAsset.png) Please make sure that your have named the atlas file extension `.atlas.txt` and not `.atlas`. See [Spine Unity Export for Beginners](/spine-unity-assets#Spine-Unity-Export-for-Beginners) for details. If the extension is correct and the issue still persists, please check whether there are any missing attachments in your skeleton. It is possible that some textures were not packed correctly due to invalid references. You can quickly check this by opening the [Find and Replace](/spine-tree#Find-and-replace) window from the tree view and enabling the `Missing images` option. ![](/img/spine-runtimes-guide/spine-unity/CommonError-MissingImages.png) > **Why do I get the error "Opening scene in read-only package!" when opening a scene from a git UPM package?** ![Opening scene in readonly package](/img/spine-runtimes-guide/spine-unity/opening-scene-readonly-package.png) Unfortunately a bug in Unity causes the error `"Opening scene in read-only package!"` when trying to directly open a scene within a package downloaded via git URL. To open the example scenes contained in the package, please copy the scene files from the package directory to your `Assets` directory using your system's file manager (*Explorer* or *Finder* respectively). ## Workflows > **Atlas Texture Workflow - Straight Alpha vs. PMA: Which should I use?** 1. **Use straight alpha when:** - You're using **Linear color space** (Unity's default for new projects - PMA is incompatible with Linear space) - You might switch between Linear and Gamma color spaces during development - You need compatibility with standard Unity shaders (most expect straight alpha textures) - You want a simpler workflow that works everywhere 2. **Use premultiplied alpha (PMA) when:** - You're using **Gamma color space** in your project exclusively - Mipmap quality is important for your project (PMA provides cleaner mipmaps with crisper details in semi-transparent areas) - You understand the workflow limitations and won't need Linear color space compatibility ![Mipmap comparison between straight alpha and PMA workflows](/img/spine-runtimes-guide/spine-unity/comparison/pma-mipmap-comparison.gif) See [Linear vs Gamma Color Space in Unity](/spine-unity-assets#Linear-vs-Gamma-Color-Space-in-Unity) and [ Atlas Texture Workflows](/spine-unity-assets#Atlas-Texture-Workflows) for details. ## Visual > **Why do I get dark borders around transparent areas of my attachment images?** ![](/img/spine-runtimes-guide/spine-unity/CommonError-PMA-as-Straight.png) Most likely you have exported your textures as `Premultiply alpha` (PMA) but your import Material or Texture settings in Unity don't match this. See [Premultiplied vs Straight Alpha Import](/spine-unity-assets#Premultiplied-vs-Straight-Alpha-Import) for details. If you are using `Linear` color space, note that PMA textures are not supported. Another potential cause is when straight alpha workflow is used together with `Generate Mip Maps` enabled in Texture import settings, but color bleed has not been applied to all transparent pixels. This may happen even when exporting from Spine with option `Bleed` enabled if you modify the exported texture in an image editor. Some do not properly re-apply color bleed in transparent areas where alpha is 0, leaving the RGB portion of the pixel black or white instead. Whenever the unmodified exported texture is displayed correctly but the modified is not, missing color bleed is likely the cause. > **Why do I get washed out desaturated colors making the skeleton look too white?** ![](/img/spine-runtimes-guide/spine-unity/CommonError-Linear-with-PMA.png) Most likely you are using Linear color space *(the default in new Unity projects)* but are using PMA auto-import settings in [Spine Preferences](/spine-unity-assets#Spine-Preferences). This leads to incorrect texture import settings, having incorrectly disabled `sRGB (Color Texture)`. Note that when using Linear color space in Unity, you can only use straight-alpha texture workflow, not PMA. See [Premultiplied vs Straight Alpha Import](/spine-unity-assets#Premultiplied-vs-Straight-Alpha-Import) for details. Alternatively you can also switch your project color space to Gamma via `Project Settings - Player - Other Settings - Color Space`, which comes with the advantage of more intuitive alpha blending similar to typical image editing applications. See [Linear vs Gamma Color Space in Unity](/spine-unity-assets#Linear-vs-Gamma-Color-Space-in-Unity) for details. > **Why do I get colorful stripes in transparent areas of my attachment images?** ![](/img/spine-runtimes-guide/spine-unity/CommonError-Straight-as-PMA.png) Most likely you have exported your textures as straight alpha (`Bleed`) but your import Material or Texture settings in Unity don't match this. See [Premultiplied vs Straight Alpha Import](/spine-unity-assets#Premultiplied-vs-Straight-Alpha-Import) for details. > **Why do I get white borders around my attachment images when enabling Generate Mip Maps?** ![](/img/spine-runtimes-guide/spine-unity/CommonError-PMA-sRGB-Mipmaps.png) Most likely you have exported your textures as `Premultiply alpha` (PMA) but your import Texture settings in Unity have incorrectly enabled `sRGB (Color Texture)`. See [Premultiplied vs Straight Alpha Import](/spine-unity-assets#Premultiplied-vs-Straight-Alpha-Import) for details. > **Why does my skeleton display wrong colors when I enable the Tint Black option in the material settings?** ![](/img/spine-runtimes-guide/spine-unity/CommonError-Tint-Black.png) Please make sure that you have enabled `Advanced - Tint Black` at the SkeletonRenderer component. > **I tried assigning materials at the MeshRenderer, but it is not possible. Why?** The Materials are controlled by the `SkeletonRenderer` every frame, see section [Materials](/spine-unity-rendering#Materials) for details. If you want to replace materials per instance or per Slot, see [Changing Materials Per Instance](/spine-unity-rendering#Changing-Materials-Per-Instance). > **Some of the included Spine shaders display incorrectly in my URP project. Why?** The spine-unity runtime package provides only [Built-In Render Pipeline](https://docs.unity3d.com/Manual/built-in-render-pipeline.html) shaders, which are not compatible with [Universal Render Pipeline](https://unity.com/srp/universal-render-pipeline) projects. Please use the provided URP shaders of the [Spine URP Shaders extension UPM package](/spine-unity-rendering#URP-Shaders-Extension-Package) instead. > **The Outline shader displays only outlines in my URP project. Why?** ![](/img/spine-runtimes-guide/spine-unity/CommonError-Outline-URP.png) There are two potential causes: 1. You're using a Built-In Render Pipeline shader such as `Spine/Skeleton` or `Spine/Outline/Skeleton` in your Universal Render Pipeline project. Built-In Render Pipeline shaders are not compatible with URP projects. Please use URP shaders of the [Spine URP Shaders extension UPM package](/spine-unity-rendering#URP-Shaders-Extension-Package) instead. 2. If you're using the correct URP shader `Universal Render Pipeline/Spine/Outline/Skeleton-OutlineOnly`, it renders only the outline because it's a single pass shader. You need to use e.g. the [`RenderExistingMesh`](/spine-unity-utility-components#RenderExistingMesh) component to re-render your skeleton mesh with this outline-only shader to add the outline behind your skeleton. See the `com.esotericsoftware.spine.URP-shaders/Examples/Outline Shaders URP` example scene included in the [Spine URP Shaders UPM package](/spine-unity-rendering#URP-Shaders-Extension-Package) for a working example setup. > **The Outline shader displays inner outlines around skeleton parts. Why?** ![](/img/spine-runtimes-guide/spine-unity/CommonError-Outline-Inner.png) When your skeleton requires multiple materials, the included outline shaders will incorrectly outline each submesh instead of the whole skeleton. The best solution is to ensure that only a single material is used. This can be achieved by either packing your atlas accordingly, or by [runtime repacking](/spine-unity-main-components#Combining-Skins). If this is not possible, you can use e.g. the [`RenderCombinedMesh`](/spine-unity-utility-components#RenderCombinedMesh) component to re-render your combined skeleton mesh with an outline-only shader to add the outline behind your skeleton. Available outline-only shaders are `Spine/Outline/OutlineOnly-ZWrite` for Built-In Render Pipeline and `Universal Render Pipeline/Spine/Outline/Skeleton-OutlineOnly` for URP. > **How can I replace Materials per Slot?** See [Changing Materials Per Instance](/spine-unity-rendering#Changing-Materials-Per-Instance). > **I tried using a normalmap on a skeleton, but it looks wrong. Why?** Please make sure that you have enabled `Advanced - Solve Tangents` at the `SkeletonRenderer` component. > **Why does SkeletonGraphic turn bright during fadeout of a UI panel via CanvasGroup alpha?** ![](/img/spine-runtimes-guide/spine-unity/CommonError-CanvasGroupBright.png) See section [SkeletonGraphic Component - CanvasGroup alpha](/spine-unity-main-components#CanvasGroup-alpha). > **Why do individual parts of my skeleton show through during alpha fadeout?** ![](/img/spine-runtimes-guide/spine-unity/CommonError-AlphaFadeOut.png) This is a common rendering problem of transparency being applied when overlapping triangles are drawn. See section [Fading a Skeleton In or Out](/spine-unity-rendering#Fading-a-Skeleton-In-or-Out) for more details. > **Why does my repacked skin display in the Editor but shows white polygons in the built executable?** ![](/img/spine-runtimes-guide/spine-unity/CommonError-RepackSkin.png) See section [runtime repacking](/spine-unity-main-components#Combining-Skins) where you will find an info box that lists the most common causes for this issue. ## Inconsistent behavior > **I'm using UPM packages via git URLs, why does the project behave differently on two machines?** If you are using a git URL that ends with e.g. `#4.2`, this leads to the Unity Package Manager downloading the latest version from the branch `4.2`. When the project is installing required packages for the first time, it downloads the latest required packages once. So a machine that downloads a required package earlier will have an older state of the package than another. You can select the package in the Package Manager and hit the `Update` button to update to the latest version by re-downloading the package. You can avoid this problem by replacing `#4.2` in your git URL with a specific git commit hash like `#5e8e4c21f11603ba1b72c220369d367582783744` to ensure everyone on your project has the same consistent state of the package. See below how to get a commit hash. Unfortunately the short commit hash like `#5e8e4c21` does not seem to work with Unity Package Manager. > **How can I get a git commit hash to use for the Package Manager git URL?** You can get the commit hash by visiting the [github commits page](https://github.com/EsotericSoftware/spine-runtimes/commits/4.2), selecting the desired branch and clicking the copy button (with tooltip "Copy the full SHA") at the right side of the commit to copy the commit hash to the clipboard. ![](/img/spine-runtimes-guide/spine-unity/copy-git-commit-hash.png) ## Performance > **Instantiating a skeleton causes an fps drop or GC memory allocation. How can I improve loading?** 1. If you are exporting your skeleton as `.json`, please consider switching to binary export as `.skel.bytes`. See [Binary Export for Unity](/spine-unity-assets#Binary-Export-for-Unity) for details. 1. If you are instantiating skeleton prefabs during gameplay, consider loading the skeleton at level-load time, and also using a pool of objects instead of instantiating and destroying prefabs. Pre-warm the pool by loading e.g. 10 instances at a non-critical level-load timepoint. Enable and re-position objects instead of instanting new ones, and disable (and `ClearTracks` on `AnimationState`) instead of destroying them. > **I see many draw calls / batches / materials at a single skeleton. Why?** You are likely using multiple atlas pages or Slot blend modes in alternating draw order. See sections [Materials](/spine-unity-rendering#Materials) and [Material Switching and Draw Calls](/spine-unity-rendering#Material-Switching-and-Draw-Calls) for details. When combining skins or attachments from multiple atlas textures, consider [runtime repacking](/spine-unity-main-components#Combining-Skins) to repack attachments to a single atlas texture (at the cost of a single repack operation). > **How can I improve the performance of a skeleton?** 1. Avoid using clipping polygons if possible, consider using Unity's masking features instead. If you need to use clipping attachments, use as few vertices at the clipping polygon as possible. The area of the polygon does not matter, only the vertex count does, so e.g. consider creating a large triangle instead of a two triangles to cover a rectangular area. 1. Use as few mesh deformation keys as possible. 1. Use as few vertices as possible. 1. Remove unnecessary keys, don't key everything. 1. Optimize any other metric displayed in the [Metrics view](/spine-metrics#Metrics-view) in the Spine Editor. 1. Use as few atlas page textures as possible. 1. When requiring multiple materials per skeleton, try optimizing your draw order in Spine to minimize the number of Material switches, or try optimizing atlas texture export so that attachments next to each other in the draw order list are grouped to the same atlas page texture. See sections [Materials](/spine-unity-rendering#Materials) and [Material Switching and Draw Calls](/spine-unity-rendering#Material-Switching-and-Draw-Calls) for details. 1. Try sharing a single larger atlas texture between multiple skeletons where possible. You can assign a single AtlasAsset at the [SkeletonDataAsset atlas assets array](/spine-unity-assets#Skeleton-Data-Asset) of different skeletons. See [Packing](/spine-texture-packer#Packing) for details. You may consider [packing by folder structure](/spine-texture-packer#Folder-structure) or using the [Command Line Interface](/spine-command-line-interface). [Previous: On-Demand Loading](/spine-unity-on-demand-loading)