Importing skeleton data

April 18th, 2023

There are cases where you have no Spine project but want to import a skeleton into Spine using exported files. This tutorial will guide you through the process.

Unpacking texture atlas pages

If you have individual images files that have not been packed into a texture atlas, then you can skip this step. If your images have been packed into a texture atlas, you need to unpack them before they can be used in the Spine editor. This can be done with the Spine UI or via the command line. It's best to use the latest version of Spine to unpack an atlas.

If the atlas was packed with premultiplied alpha, Spine needs to unpremultiply the alpha when unpacking. For an atlas packed with newer versions of Spine, the atlas file knows that the atlas images have premultiplied alpha. The unpacker will use this information from the atlas file, if it exists.

For an atlas packed with an older version of Spine, you will need to tell Spine whether the atlas images are premultiplied. The transparent parts of an image will appear dark when the image is premultiplied. Here is a comparison of premultiplied and non-premultiplied (straight alpha) images:

Unpacking with the UI

To unpack via the Spine UI:

1. Make sure that the atlas file and the atlas images are in the same folder.
2. Open the Spine editor and choose Texture Unpacker from the main menu.

3. In the Texture Unpacker window:
   • Enter the path to the Atlas file. If your skeleton data has been exported for spine-unity, the file extension may be .atlas.txt, which will work fine.
   • Enter the Output folder, which is the path to the folder where you want the unpacked images to be stored.
   • Check Unpremultiply alpha if the atlas was packed with premultiplied alpha. If the atlas file has "pma:true", that will be used instead of this checkbox.

4. Click Unpack. The individual image files will be created for each texture region in the atlas.

Unpacking with the CLI

To unpack via the command line interface (CLI), specify these parameters:

You can also use the short command line parameters to do same:

You may want to use --update or -u, which allows you to run a specific version. For example, adding -u 4.1.20 to the above example will run Spine 4.1.20 to unpack. Unpacking with the latest non-beta version of Spine is best and you can do that by using -u latest.

Importing skeleton data

To import your skeleton data, first make sure you are using the same version of Spine that was used to export the data. This is especially important for binary data, but also applies to JSON data.

Next, check to see if the atlas file has a line specifying the atlas' scale. This information will be needed when importing. If not found, it means that either the skeleton's atlas was packed at a scale of 1 (the original image sizes) or that the atlas was packed with an older version of Spine.

To import skeleton data:

1. Open the main menu and choose Import Data.

2. In the Import Data window:
   • For File, enter the path to the JSON or binary file to import.
   • If the texture atlas was scaled, set the Scale value so the size of the skeleton will match the unpacked atlas images.
   • Enter the name of the skeleton to be imported.

3. Press Import and you will see your skeleton, but with MISSING images instead of the correct images. This happens because the image path has not been set, which we will fix in the next step. First, save the Spine project.

4. Select the Images node in the Tree view, and enter the path to the images folder in Path.

Now the skeleton images are displayed correctly:

Troubleshooting

Why aren't my images shown even if I set the correct image path?

If the skeleton was created in Spine Professional but you imported the skeleton data using Spine Essential, mesh attachments and constraints will not be imported because they are only available in Spine Professional. Use Spine Professional to import skeletons that contain Spine Professional features.

Why do I have dark borders around transparent areas of my images?

Your atlas images had premultiplied alpha and you did not check Unpremultiply alpha when unpacking the atlas. Try unpacking again with Unpremultiply alpha checked.

Why do I get white borders around transparent areas of my attachment images?

Your atlas images did not have premultiplied alpha and you checked Unpremultiply alpha when unpacking the atlas. Try unpacking again with Unpremultiply alpha unchecked.

Why are some of the parts smaller or larger than the correct size?

Your atlas was packed with a scale greater or less than 1. Import the skeleton again and specify the same scale value that was used to pack the atlas. If you don't know the scale, you can try some common values like 0.5 or 0.25.

Why is the animation of the imported skeleton incorrect?

To import correctly, you must use the same version of Spine that was used to export the data. You can find the Spine version in the exported data by opening it with a text editor and looking near the start of the file:

If the file is exported in binary format, you may want to use a hex editor to view the version number.

If your data is from an older version of Spine, run that version so you can import the data, then save a Spine project file and open that with the newer version of Spine that you want to use.

Why are the bones' icons changed to the default icon?

The bone icon information is not contained in the exported skeleton data, as it is only needed in Spine, so an imported skeleton will use the default icon for all the bones.

Why are the bones' colors reset and the edges between mesh vertices gone?

When skeleton data is exported without Nonessential data checked, some information that is not normally needed at runtime is not exported. The imported skeleton will still work, but will be missing the nonessential information. If you plan to import data in the future, be sure to check Nonessential data when exporting.

If you are having trouble importing a skeleton from exported files, we are happy to help on the Spine Forum!