Import Spine 2D animations in Unity 3D and linking effects to bones using 2D Toolkit

Here it will be described how to simplify the import of Spine animations into the Unity project, and what needs to be done to bind an arbitrary object (visual effect, collider, etc.) to the animation itself or its individual bones.

Let's take a look at the particle system available in the Unity editor.
At the end of the article comes the finished animation and test project, the result of which will look something like this:



So, what is needed to implement our plans:
')

1. Free version of Unity editor (v 4.5.3f3 at the time of this writing).
2. 2D Toolkit (v 2.4.0 at the time of this writing).
3. Spine animation editor.
4. Csharp library, which can be downloaded here (but it already exists in the attached project).

Importing animations from the Spine editor, manually, is described in a simple video instruction , however, in the case when several people work on the project, this may cause some difficulties. Therefore, it was written a window for import, in which you simply drag the animation export folder from the Spine editor and click "OK".

The process of creating animation itself will not be described here, the developer’s website has excellent documentation on this subject.

Let's start with export

Each Spine project is the actual folder with the images used and the file with the project settings (* .spine file). We also need another JSON file generated by the editor during the export. Export settings are shown below. It is important here not to forget to specify that we do NOT need an atlas when exporting (the “Create atlas” field). Next, we specify “[path to the Spine folder of the project] / Export” as the path, and press the export button.



As a result, we have the Spine project folder with what was already there, plus the necessary JSON file. The finished export folder with the source is in the archive “necr_2.zip”, which can be found at the end of this article.
If for some reason it is not desirable to transfer the animation source along with the folder, then it doesn’t matter, the “* .spine” file is not required for import.

Now we are creating a new 2D project in Unity, importing the “2D Toolkit” package and the contents of the “spine_test.unitypackage” file into it, which can also be downloaded at the end of this article.
In the resulting project, you can open and run the already finished scene, it lies in the folder “ExampleEffects”. In this scene, an animated ghost flies in front of the camera with an effect attached to one of the arm bones, if you can call it that.

But back to the import of animation.
To open the import window in our Unity project, you need to find the “Window” item in the top menu and select the “Spine Import Window” in the drop-down list, as shown in the figure below.



As a result, we will see a similar window:



Now we need the file “necr_2.zip”, it contains the export of animation from the Spine project. Unzip it and drag the resulting folder into the large field ">> Drag the folder export character here. <<". As a result, we see the generated atlas and a couple of settings, as in the figure below.



In the field “Pack method” we choose the most optimal variant, i.e. the one at which the value of "Atlas size" is less. The Padding field defines the gap between the textures in the atlas, with a value of 1, no artifacts have occurred. "Max atlas size" exists only for debugging, there always need a maximum value. And “Max texture size” sets the quality of the texture in Unity, the maximum value is also recommended.
The top field "Set person name" has a value. Since all imported animations will be stored in one place, the name must be unique, otherwise the window will show a warning below instead of the “OK” button. Clicking this button imports the animation and ends.
By the way, the MaxRectsBinPack script with a small add-on was used to create the atlas.

During the creation and linking of the required prefabs, several error messages may appear in the Unity console, but they do not affect the final result. As a result, we have a folder with the name specified during the import, which contains resources and a prefab called “animation”.



We pull it out onto the stage, press "Play" and watch an animated ghost. However, in order for the animation to turn on automatically, do not forget to set similar settings in the component shown in the image below (Time Scale is reduced for clarity).

Binding of objects to bones remains

For the test, you can use the prefabs "fx1_pref" and "fx2_pref" from the folder "ExampleEffects". We find the component “Spine Person” in the object inspector and set the settings, as shown in the figure below.



In the "Prefab" field, an object of type "GameObject" is selected, i.e. almost any game object, in our case it is a container containing the Particle system .
But the main field here is “animation”. The “simple” option means a regular embedded object that is not tied to any bone. Selecting the “withbone” value, you will be able to select a bone from the list to which the object will be attached. In the case of the ghost, the names of the bones are not very original, so you can experiment.
The "Free Z pos" field appeared due to the fact that for some effects a two-dimensional analogue of lighting was used, which always had to be between the interface and the playing field. So if you uncheck this box, then the z coordinate of the effect will always be equal to the fixed_z parameter (which will appear in the inspector).
Using the “Pivot”, “Rotation”, “Scale” fields you can adjust the position, rotation and size of the effect relative to the bone (in our case, scaling does not matter).
After the settings are set, you can start the scene, drag the object along different coordinates and look at the result.

This video can show what all this can do.


In the SpinePerson.cs script there are a couple more functions that might be useful to someone:

SpinePerson.setSpineImageActive
SpinePerson.replaceSpineImage

Using these functions, you can hide / show or replace a specific texture in the animation.
All scripts are located in the “SpineImport / scripts” folder, if desired, they are not difficult to change to the needs of a specific project.

Below is the attached Unity project and archive with animation:
- spine_test.unitypackage [updated, fix scale factor and rotate] ;
- necr_2.zip .