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)
!!
# Assets
## Exporting Spine Assets for Unity
### Export User Guide
You can find complete instructions in the Spine User Guide on how to
1. [Export skeleton & animation data](/spine-export)
2. [Export texture atlases containing the images of your skeleton](/spine-texture-packer)
### Spine Unity Export for Beginners
The following shows a simple way to export Spine assets for Unity. Once you are familiar with the basics you can choose optimized settings for improved results.
1. After you have created your skeleton and animations, click on `Spine Menu`>`Export...` (`CTRL`+`E`). This opens the **Export window**.
1. Choose `JSON` on the upper-left of the Export window.
> Note: For production you should later prefer [binary skeleton](#Binary-Export-for-Unity) exports over JSON exports, as they are smaller in size and faster to load.
1. Check the `Texture Atlas` `Pack` checkbox. (Checking `Nonessential data`, `Pretty print` are also recommended for beginners). Be sure to have `Animation cleanup` disabled, otherwise keys identical to setup pose will not be exported.
1. Click on `Pack Settings` below the `Pack` checkbox. This opens the **Texture Packer Settings** window.
1. On the lower-right, look for the textbox labeled `Atlas extension` and make sure it is set to `.atlas.txt`.
1. > **For spine-unity 4.3 and newer:** Disable `Premultiply alpha` and enable `Bleed`.
> 
1. You're done with the Texture Packer Settings window. Click `OK` to close.
1. In the **Export window**, pick an output folder. (Recommendation: Create a new empty folder.)
1. Click `Export`.
1. This will export three files:
1. `skeleton-name.json` or `skeleton-name.skel.bytes`, containing your skeleton and animation data.
2. `skeleton-name.atlas.txt`, containing information about the texture atlas.
3. One or more `.png` files, each representing on page of your texture atlas containing the packed images your skeleton uses.
1. You can now continue with section [Importing Spine Assets into Unity](#Importing-Spine-Assets-into-Unity).
### 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.
1. Choose `Binary` on the upper-left of the Export window instead of `JSON`.
1. 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](/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](/spine-command-line-interface#Examples).
For example, we use this script to export all the Spine example projects and to create texture atlases: [export.sh](https://github.com/EsotericSoftware/spine-runtimes/blob/4.2/examples/export/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](/spine-unity-main-components#SkeletonGraphic-Component). Due to limitations of the used Unity `CanvasRenderer`, [SkeletonGraphic](/spine-unity-main-components#SkeletonGraphic-Component) 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](/spine-texture-packer#Folder-structure). 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:
1. Press `Ctrl+E` or in the dropdown menu select `Export...`
2. Enable `Texture Atlas` `Pack` and select `Image Folder` instead of `Attachments` right to it.
3. (optional) Check in `Pack Settings` if under `Options` in the bottom right `Flatten Paths` and `Combine Subdirectories` is disabled (this is the default).
4. Click Export.
## Atlas Texture Workflows
### Linear vs Gamma Color Space in Unity
> **Important Note:** It is very important to decide on the [color space](https://docs.unity3d.com/6000.2/Documentation/Manual/differences-linear-gamma-color-space.html) to be used in your Unity project early on as it has a big impact on how any blending will look. This affects both alpha-blending or semi-transparent parts as well as additive/multiply/screen blending for special effects. Additionally, the used color space dictates how you can export your atlas texture assets from the Spine Editor.
Unity uses Linear color space by default for new projects. However, many Spine users work with 2D assets that have been carefully layered and color-corrected in external editors like Photoshop, which default to Gamma-space blending. As a result, blended colors will appear duller and more desaturated in Unity compared to the original artwork, which can be frustrating.
For this reason, we generally recommend switching the project to **Gamma color space** for more intuitive blending that better matches the original design.
That said, **Linear color space** is still appropriate—particularly if you're using Spine skeletons in realistic 3D environments with dynamic lighting.
#### Advantages of Gamma color space
- Blending behaves in a more intuitive way (image editors perform blending in Gamma space by default).
- Easier to author in any image editor in advance and preview the result.
- You can use PMA textures which provide better mip-mapping.
#### Advantages of Linear color space
- 3D lighting: angle-dependent light falloff (for 2D skeletons done via normalmaps) is more physically correct.
- When layering additive light layers, any light-pixels add up in a more physically realistic way. *(Note this may or may not be what you want)*
- Post-processing effects work best in Linear color space.
You can switch your Unity project color space to Gamma via `Edit - Project Settings` (`Unity - Project Settings` on Mac) `Player - Other Settings - Color Space`.
#### Spine Editor Color Space
The Spine Editor defaults to Gamma color space, but can be switched to Linear space in [Spine - Settings - Viewport](https://de.esotericsoftware.com/spine-settings#Color-management).
Once you have decided on a project color space, it is highly recommended to also adjust the Spine Editor to match your Unity project for consistent results.
### Premultiplied vs Straight Alpha Export
Spine offers two basic workflows via Texture Packer Settings how atlas textures can be exported:
1. **Straight alpha** (required when using Linear color space)
Texture Packer setting `Premultiply alpha` disabled, `Bleed` enabled.
1. **Premultiplied alpha (PMA)** (default export mode in Spine Editor, premultiplied in Gamma color space)
Texture Packer setting `Premultiply alpha` enabled.
**Choosing the right workflow:**
- **If you're uncertain about color space** or might switch between Linear and Gamma in the future: Use **straight alpha** workflow as it is compatible with both color spaces.
- **If you're certain you'll use Gamma color space exclusively:** Use **premultiplied alpha (PMA)** workflow as it provides superior mipmap quality with crisper details in semi-transparent areas.
Unity now uses Linear color space for new projects by default, and premultiplied alpha textures are incompatible with Linear color space (causing incorrect borders when converted from Gamma to Linear space). See section [Linear vs Gamma Color Space in Unity](#Linear-vs-Gamma-Color-Space-in-Unity) for details.
It is very important to match export and import settings correctly, see section [Premultiplied vs Straight Alpha Import](#Premultiplied-vs-Straight-Alpha-Import) for correct settings in Unity.
## Importing Spine Assets into Unity
1. Open your Unity project in the Unity Editor. It should already have a functioning spine-unity runtime in it, as described in section [Installation](/spine-unity-installation).
2. Open the folder of the exported files. (`.json`, `.atlas.txt` and `.png`)
3. 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:
1. an **_Atlas** asset for the texture atlas file (`.atlas.txt`). It holds a reference to the material and the `.atlas.txt` file.
2. a **_Material** asset for each texture atlas page (`.png`). It holds references to the shader and the `.png` texture.
3. 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](#Skeleton-Data-Asset).
### Premultiplied vs Straight Alpha Import
As described in [Premultiplied vs Straight Alpha Export](#Premultiplied-vs-Straight-Alpha-Export),
Spine offers two basic workflows of how atlas textures can be exported:
1. **Straight alpha** (required with Linear color space)
1. **Premultiplied alpha (PMA)** (default export mode in Spine Editor, premultiplied in Gamma color space)
#### Preferences Auto-Import settings for correct import
**Important Note:** It is very important that the texture import and material settings match the atlas texture export settings. The spine-unity runtime provides a [Spine Preferences section](#Spine-Preferences) in Unity's `Preferences` window, accessible via `Edit - Preferences` (`Unity - Preferences` on Mac) which provides **Auto-Import settings** to ensure proper setup.
1. Since version 4.3 the Preferences sections provides `Switch Texture Workflow` buttons for quickly switching to `Straight Alpha` or `PMA`, saving you any manual adjustments of (2) and (3) below.
2. The *Atlas Texture Settings* parameter is used to automatically apply the proper texture import settings at newly imported atlas textures. When switching from straight alpha workflow to PMA or vice versa, this preset needs to be adjusted.
3. `Additive Material`, `Multiply Material` and `Screen Material` define the template materials for each blend mode. When switching from straight alpha workflow to PMA or vice versa, these need to be adjusted accordingly as well.
For **straight alpha workflow** *(already the default in spine-unity 4.3 and newer)*:
- a) use the `Switch Texture Workflow` - `Straight Alpha` button to switch presets at once.
- b) or manually set `Atlas Texture Settings` to `StraightAlphaTexturePreset`, and set blend mode materials to `SkeletonStraightAdditive`, `SkeletonStraightMultiply` and `SkeletonStraightScreen`.
For **premultiplied alpha (PMA) workflow** (only works with Gamma color space):
- a) use the `Switch Texture Workflow` - `PMA` button to switch presets at once.
- b) or manually set `Atlas Texture Settings` to `PMATexturePreset`, and set blend mode materials to `SkeletonPMAAdditive`, `SkeletonPMAMultiply` and `SkeletonPMAScreen`. This was the default in spine-unity 4.2 and earlier.
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.