Jump to content

Spriter for Unity 5.0


Recommended Posts


Previous thread: http://brashmonkey.com/forum/index.php?/topic/3365-spriter-for-unity-43-updated-integrated/


Old version: https://github.com/Dharengo/Spriter2Unity


Even older version (Unity 4.x compatible): https://github.com/bonus2113/Spriter2Unity




So I've decided to build an entirely new version of the importer from scratch. This enabled me to work with it way more easily. Hopefully other programmers will also find it much easier to work with now:


Spriter2UnityDX 1.0.3


GitHub Link: https://github.com/Dharengo/Spriter2UnityDX


Anyone is free to fork it and do their own work. If it's pretty good stuff I'll merge it into the main branch.


Package Link: https://github.com/Dharengo/Spriter2UnityDX/raw/master/Packages/Spriter2UnityDX.unitypackage


Use instructions: 


!!!Requires Unity 5.x!!!


1) Import the above package into your Unity project. Just drag and drop it into your Project View.

2) Import your entire Spriter project folder (including the .scml file and all of the textures) into your Unity project.

3) The converter should automatically create a Prefab and an AnimatorController in the same folder that contains the .scml file.

4) When you make any changes to the .scml, the converter will attempt to modify existing assets if they exist.

5) If these updates cause any irregular behaviour, try deleting the Prefab and Controller and re-importing the .scml.


Differences from previous version:


-The textures' import settings are examined before building the prefab, and automatically set to the format that is needed to build the Spriter Entity.

-AnimationClips only contain curves for properties that actually change.

-When updating existing assets, priority goes to the AnimatorController that is actually connected to the prefab, in case you are using the same AnimatorController for multiple Spriter Entities.

-Body parts that have alternate textures (such as facial expressions) have an additional script component named "Sprite Swapper" on them which controls which sprite is displayed at any one time. You can manipulate this component at runtime to do fun things like give your characters alternate skins. For sprites that don't need a Sprite Swapper, you can just manipulate the Sprite Renderer.

-The root GameObject now holds an "Entity Renderer" which allows you to manipulate all of the children's Sprite Renderers simultaneously as if they were one sprite. Disabling the Entity Renderer will also disable all the Sprite Renderers, and enabling it will enable them again.

-Easily extensible, readable code.


(Currently) Unsupported Features & Future Ideas


-Automatically generate an Override Controller

-CharacterMap support (I don't have Spriter Pro myself though, and I know very little about this at this point in time)

-Dynamic Reparenting (changing the parent of a sprite during the animation will not be translated to Unity)

-Support for other Pro features (subentities, notably)


Known Issues:


-Pivot points that are assigned on the canvas. Right now if you do this, your sprite will be misaligned when imported in Unity. I am planning on creating a fix for this on the next update, but not sure when that will be. For now, just set the default pivot point instead.

-On a related note, NOT setting any default pivot points at all will also cause irregular behavior.

-In some cases, the importer will endlessly loop. A workaround is manually setting your texture files to Sprite in the import settings. I have not figured out the cause for this but hopefully it'll be fixed in a future update.

-Bones that are added later during animations are perpetually disabled.

-The only supported curve types are smooth ones.


Warning: Only the basic features of Spriter are implemented. And most certainly none of the Pro features. That said, if you feel you're a pretty good coder, feel free to take a shot at implementing it yourself.


Warning: The tool as it is is very new. If you run into any unexpected behaviour, please tell me and I'll see if I can work out a fix.






-AnimationEvents are now preserved between reimports

-SpriteSwapper renamed to TextureController to avoid confusion

-Fixed a z-position issue with the SortingOrderUpdater

-Fixed an issue where flipped (negative-scaled) bones caused child sprites to appear out of place and in odd angles
-Added a toggle to the Entity Renderer that allows you to apply the .scml file's Z-index to the order-in-layer property of the Sprite Renderers
-Removed Spriter2UnityDX components from the Add Component menu, since they are automatically added or removed
-Fixed an issue where sprites appeared distorted when resizing bones
-Exceptions are wrapped up nicely and no longer abort the whole process
-Now adds AnimationClips to existing AnimatorStates if they exist
-Autosaves no longer trigger the importer


Fixes: -Fixed an issue where the Z-order would get messed up if body parts were moved during animation

Features: -Z-order can now be mutated by the animation

v1.0: Initial version

Link to comment
Share on other sites

Hello all,

I downloaded Spriter a few days ago and have been trying to get it to work with Unity 5.0, using the Spriter2Unity package mentioned above.


When importing a Spriter project into Unity, the prefabs are formed correctly, which is great.


There are, however, two features of Spriter that appear to be lost when a Spriter project is imported into Unity.

  • When a bone is scaled between keyframes in Spriter, the image does not scale in unity but remains at a constant size throughout the animation.
  • The easing curve, which is an incredibly useful feature, does not appear to be supported, and the animation transitions linearly from keyframe to keyframe.

I gather that the Spriter2Unity package is not maintained by the Spriter team, but support for Unity appears to be a major selling point for people.


Are these issues likely to be resolved in the near future?

Link to comment
Share on other sites

Whether or not these issues will be resolved mostly depends on whether or not someone is going to resume active development on the converter.


I simply do not have the time for it. I just make some minor modifications to suit my own ends.


That said, should I run into that issue myself and see the need to resolve it myself, I will take matters into my own hands. But I can give no ETA on this, or whether it will happen at all.


I'm sorry to say all of this. However, you are welcome to take a crack at it yourself.

Link to comment
Share on other sites

Good Morning~ I need some scripting help in spriter2Unity , I am aware that there is no CharacterMap implementation yet , but how can I access the sprites to be changed to another one during Run time? 
I tried this Method but the sprites remain the same 


1) I made a script that has a method called ChangeSprite , this Method invoked using "Animation Event", it will change all sprites to a specific one

	public void ___ChangeSprite(Sprite s){				foreach (var renderer in GetComponentsInChildren<SpriteRenderer> ()) {				renderer.sprite = s;		}	}

buuut it is not working , is ut being overriden somewhere in Spriter2Unity? or the sprites ment to be accessed diffrent way? I'd really appreciate an insight to the matter

Link to comment
Share on other sites

There actually used to be an implementation for that. I am in fact quite unsure why it has been taken out. That said, your sprite texture is probably being set by the Animation asset. So if you want to change it, you have to change it on the Animation.

Link to comment
Share on other sites

So anyways, contradictory to what I have been saying for a long time now.... I've actually been working on the converter. Kind of as a side project to prevent myself from burning out on the main one.


As part of the exercise I kind of decided to build the whole thing from scratch and do something about the huge maze of classes and method calls that might make it rather intimidating for other developers to work on it. There is no real logical reason for this, it's mostly a learning experience for myself, but if something comes out of it, it'd be a nice boon.



One big thing I've changed is the method by which the Scml data is parsed to C#. Originally, during every step of the process, the necessary data was read from the .scml file at every step. I've always felt a bit awkward querying data files directly (requires lots of lines of code to achieve relatively little), especially when it has to happen often. So instead of that, I parse the whole thing to a ScmlObject class instance in one swoop, then access the necessary data in that. It may be a personal thing, but I find it much easier to work with a C# class than it is to work with a data file.


Anyway, as for my progress so far: I've been able to replicate the part of the import process that creates the physical Prefab. As far as I've tested, all the bones and textures are in place. I haven't started on building the Animation assets yet, but I did add a really cool feature that automatically converts your texture data to the Sprite format if it's not already in a Sprite format. So no longer will users who use the converter expect to see their sprite, only to see a bunch of empty looking GameObjects without knowing why.


Building Animation assets seems like a fun task but that might take a little while to get right. I'll keep you guys posted though.

Link to comment
Share on other sites

Any idea why this would not work on SCML files created in beta Spriter?


We have some animations, created in Beta 3. I've opened them up in R4, and re-saved the file. Everything appears to look fine in the raw SCML, but for some reason, none of of the sprites are linked properly, and none of the animations play.


When I create a new anim from scratch, it imports fine.


Kinda stumped...


[Edit] Figured it out, seems to have been caused by some forward slashes that were present at the beginning of the image names in the SCML. Lookin forward to digging into this tomorrow :)

Link to comment
Share on other sites



There actually used to be an implementation for that. I am in fact quite unsure why it has been taken out. That said, your sprite texture is probably being set by the Animation asset.

I looked into the deleted implementation and restored it for testing , and it had many problems like creating a single Charmap (original one) and ignoring the rest of your CharMaps, Not following The SCML Documintation so it does not have variables to swap images and folders , and SpriteChang not working in 5.0 for me at all.




. So if you want to change it, you have to change it on the Animation.


thats my current progress regarding this matter:

If I change an animation Directly without an animation Event , I'll need to create multiple prefabs for diffrent charmaps , which is ok for monsters but not ok for hero. 

If I try to Change it via animation Events , I'll need to access each AnimationClip from Animator , and access the Curves and Keyframs, and find the curve that has the images and the time to swap the image which is guaaaaaaaaaah mindblowing and tiring x,x 


if there is an easy way to get a sprite from a running animation and change it , i'm currently unable to find it XD 


Ideally , it would be great if we simply attach script with a string of a charMap Name , run through every sprite renderer and change the sprites , and the animations play the new sprites instead of the original ones... like how these people are doing theirCharMap in min 20 to 23 , their method is really simple and friendly without accessing the animation at all , but sadly not working in Spriter2Unity implemntation 





Last but More importantly , Extreamlly happy to hear that you are working on a diffrent converter , and I approve of your Parsing approach since this is how I'd do it XD good luck in your project and hopefully it will be a blast :)




Link to comment
Share on other sites

&*^*%&^%( MY LIFE XD Ok I found a simple Solution in the same video I linked , I just need to change the Sprites in SpriteRenderer in a Method Called LateUpdate() and it will be applied to all animation Clips


for example :

	public void LateUpdate(Sprite s){				foreach (var renderer in GetComponentsInChildren<SpriteRenderer> ()) {				renderer.sprite = s;		}	}

now I just need to make a script that would handle different swapping situations , change a speficc sprite , change entire folders etc :) this is best since I'd need to animation events or edit animations at all
I'll share the long Script when I'm done and happy with it, for time being , peaceout~

Link to comment
Share on other sites

That.... works? I guess?


It's not a very elegant way of doing it, mind you. I mean you're basically playing tug o' war with the animator. The animator changes the sprite, you change it to something else. The animator changes it back, and you change it back as well.


This is one of the problems I intend to fix. The new version of the converter really should determine the sprite through scripting, not by force through the animation.


I don't think I'm going to implement Character Maps right now, but I do want to make it actually possible to be implemented at a later point (perhaps by someone else). With the converter as it is, that's just waay to much work. I want my new tool to be extensible.


But at the very least, the sprites should be swappable through script, and the Animator should not interfere with that. That's my philosophy anyways.

Link to comment
Share on other sites

It's not a very elegant way of doing it, mind you. I mean you're basically playing tug o' war with the animator. The animator changes the sprite, you change it to something else. The animator changes it back, and you change it back as well.

I know right XD? but sadly after 1 week of trying to change sprites, this is the only solution i found that actually change the sprite to something else with the current implementation.




But at the very least, the sprites should be swappable through script, and the Animator should not interfere with that. That's my philosophy anyways.


will be looking forward to your implementation because i like your philosophy XD

peace and out

Link to comment
Share on other sites

Hehe, thanks for the support. One thing I'm thinking about in building these animations is to only add curves for items that actually change their state over the course of it. That should also make it less of an issue to use Unity's nifty feature to combine concurrent animations.

Link to comment
Share on other sites

Ya this behavior is super important for us as well. Our title bardbarian was created in AIR, and I authored one of the earliest spriter plugins for AS3, and now we're looking to port it to Unity.


I'm happy to help contribute once the new version is posted.


We really need to be able to swap pieces dynamically at runtime. Usage examples include:
* Swapping Brad's head as he becomes more and more damages

* Swaping Brad's guitar strum hands, to make him appear to be playing guitar in all animations.

* Dynamic Blink Functionality on all characters


In AS3 it was all code driven, I simply had a little string_hash for each image, and I could swap it in with any other key easily:

player.swapPiece("head", "head_blink"); //Blink - Any time head should be displayed, head_blink is displayed instead




This also enabled really easy character skinning with just naming conventions, without really needing to rely on Spriters character maps.

goblin.swapAll("_purple", "_blue");


Everything was cached, and there was zero performance cost to having swaps.


Would be really great if we could figure out something as effective for Unity.


ps. The new version works so much better than before, last time we tested this, it took 15minutes to finish importing our main character, now? Just a few seconds... nice work!

Link to comment
Share on other sites

Thank Bonus2113 and alaa-eddine for that. I just worked out the weird warning messages. I think part of it has to do with Unity 5 as well since it made certain hacks unnecessary. The new version I'm working on may or may not be even faster.


Oh also part of it might have to do with the fact that your textures are already imported?

Link to comment
Share on other sites

Nah it wasn't textures, they're relatively small. It was some weird exponential growth thing, where as the number of different anims increased, it took longer to import, and since main char had like 15, it just lockd up completely. 


In any case, works great, can't wait to dig in and start adding some functionality back.

Link to comment
Share on other sites

Progress report:


I was able to craft an animation through scripting (work in progress). As it turns out, Spriter uses different values for things like position and rotation, so I'm going to have to come up with some translation algorithms (probably based on the original Spriter2Unity).


As promised, only curves for which any mutations exist are added to the animation. This should eliminate a lot of those redundant curves that just stay completely identical throughout the whole thing.


Mutating transform position works. Rotation: not yet, I think it has to do with Unity's eulerAngle cap but I think that can be easily fixed. Scale or any other properties: Untested.


One thing I'm really surprised about so far: The code I've been using is surprisingly compact compared to the original Spriter2Unity. I'm not sure why this is. Maybe I'm just overlooking a whole bunch of things, or the original was just overcomplicating things too much. I don't know.

Link to comment
Share on other sites

If anyone feels like testing a few things:




It's far from done, but the basic things should be working:


Disclaimer: This is a test version, this is not a finished project. I still would like to see some feedback, however.


What it DOES do:


-Automatically convert textures to Sprite if it hasn't already

-Creates the prefabs

-Creates animations (they are nested inside the prefab)


What it does NOT do:


-Create an AnimatorController; this is probably the next thing on my agenda, but for now you'll have to create one yourself


Currently supported animation curves:







No changing the sprite texture at this point in time. Will be pretty soon though.


Just import the package and play around with it a little. What I'm mostly interested in is whether or not there is any irregular behaviour.

Link to comment
Share on other sites

Ok I just woke up from a short nap and i just had to test it before going back to sleep XD
first of all , good job on your scml support class , waaaaaaaay much friendly than the original one


I tested the converter it a bit , one thing worth noting is , DELETING the prefab and trying to re-import it is not working atm , instead I get the following Warnning (line 1): 

'Assets/SCML/TestSCML\entity_000.prefab' is not a valid asset file name.UnityEditor.PrefabUtility:CreatePrefab(String, GameObject, ReplacePrefabOptions)Spriter2UnityDX.Prefabs.PrefabBuilder:Build(ScmlObject, String) (at Assets/Spriter2UnityDX/Editor/PrefabBuilder.cs:33)Spriter2UnityDX.PostProcessing.ScmlPostProcessor:ProcessFiles(IList`1) (at Assets/Spriter2UnityDX/Editor/ScmlPostProcessor.cs:33)Spriter2UnityDX.PostProcessing.ScmlPostProcessor:OnPostprocessAllAssets(String[], String[], String[], String[]) (at Assets/Spriter2UnityDX/Editor/ScmlPostProcessor.cs:25)

which located at prefab Builder line 33 ,

				var name = entity.name;				var path = Path.Combine (directory, name + ".prefab");				var prefab = AssetDatabase.LoadAssetAtPath (path, typeof(GameObject));				GameObject instance;				if (prefab == null) {					instance = new GameObject (name);					prefab = PrefabUtility.CreatePrefab (path, instance, ReplacePrefabOptions.ConnectToPrefab); //HERE 				}

which is true because prefab entity_000.prefab was deleted by me, so re-importing should recreate the prefab from scratch(reading the SCML again) if and only if the prefab does not exists , right? for the time being , deleting the entire SCML folder and reimporting it again seems to solve the issue 


any how , really really really good start of the converter , I'll look into it again tonight to see if I find anything else or if there is a contribution I can give :)


peace and out

Link to comment
Share on other sites

I've never seen this error before. And I've deleted my prefabs and recreated them countless times. Besides, that code that you pointed out is supposed to run when there ISN'T a prefab file.


				var name = entity.name;				var path = Path.Combine (directory, name + ".prefab");				var prefab = AssetDatabase.LoadAssetAtPath (path, typeof(GameObject));				GameObject instance;				if (prefab == null) { // <<== Runs when there ISN'T a prefab					instance = new GameObject (name);					prefab = PrefabUtility.CreatePrefab (path, instance, ReplacePrefabOptions.ConnectToPrefab); // CREATES the prefab				}



'Assets/SCML/TestSCML\entity_000.prefab' is not a valid asset file name.

This looks like the real problem. Paths use forward slashes and not backslashes. Except if that's the case, it shouldn't have worked the first time you imported the .scml file either. This is puzzling. Anyway I'll insert a line of code that catches any backslashes and replaces them with forward ones. I guess Unity behaves differently on Windows machines.

Link to comment
Share on other sites



Hopefully fixed the above issues. Once again, I hope someone will check this out and play with it a little to find any irregular behaviour.


In addition, Animation assets should now have their loop types set correctly.


Also introduced a new feature: AnimatorController!


On the surface, this is almost identical to what the previous edition did, with a few differences:


-Instead of accessing the Asset Database to find an AnimatorController, it checks whether or not one is already attached to the prefab.

-It never removes or replaces anything that's already present in the AnimatorController, although the AnimationClip assets involved might get updated.

-It WILL add new states for new AnimationClips.

-If it finds an AnimatorOverrideController, it will be smart and modify the underlying AnimatorController

-Only if there is no AnimatorController attached to the prefab, will it create a new AnimatorController and then attach it to the prefab.


The idea is that the converter should not undo any custom modifications made by the user. For example, if they use the same AnimatorController for multiple entities, or if they use AnimatorOverrideControllers, this structure should not be broken by the import process.


Note that most of the above is untested, but it should work in theory. I'm excited to find out if it all works as intended.


I'm thinking of adding a menu item of some sort that opens a little window that lets you automatically generate an AnimatorOverrideController from a Spriter Prefab.


I still have to say one thing I really like about this is that for the AnimationClips, it ONLY adds curves for things that actually change. It really helps alleviate my obsession with redundancy. :P


Now, regarding the swapping of sprites (through animation, I mean stuff like maybe a blinking face, or a hand opening or closing), I'm kinda torn between what approach I would take:


-I could change the texture in an AnimationCurve. This is the "cleanest" way but it introduces an issue for users who want to swap textures through script (for changing clothes or weapon skins), because they'd actually have to edit the AnimationClip's curves at runtime.

-I could do the same as above, but add a little script that gives the user easy access to change the sprites. I am, however, a little unsure how this affects multiple instances of the same prefab.

-I could use AnimationEvents. This does, however, require that I create a Script Component that stores references to all the sprites. The benefit of this, however, is that to change the sprites, all the user needs to do is mess with the references on that Component, and the AnimationEvents take care of the rest. One VERY big flaw about this though, is that every time you re-import the .scml file, all of the AnimationClip's AnimationEvents will have to be wiped clean and then re-added. The result of this is that any user-defined AnimationEvents will be lost.

-Forget about changing the sprite's texture at all, and experiment with multiple GameObjects. This will enable the user to swap textures at runtime simply by accessing the SpriteRenderer component on each child GameObject. This approach will likely require the most code and the most experimentation, however. Another problem with this approach is that the child renderer's enabled state will from then on be controlled by the Animator, which introduces similar problems as having the Animator control the sprite's texture. Unlike the above, some kind of workaround may be found by inventing a special Script Component, but we'll have to see how convoluted that ends up being.

Link to comment
Share on other sites

fast input , amazing speed on your side , the problem is totally fixed and works like a charm now XD! it was the backslash as you said


Also I just noticed the curves improvments you made and just WOW XD! now thats clean, I tested it on a complex scml file with lots of curves and it works just fine (ignoring the fact that the spirits are not in their correct positions yet :P)



btw , my experiance with Unity is only 3 weeks more or less , so my contribution will be very limited sadly , I'll still try to test as much as I can (if that helps) and give feedback as necessary if that is ok :)


2 Issues about sprites :

1) I tried some of the SCML Files , the ones that has "sprites without bones" are not being played by the converter, am i the only one?

2) the alpha channel is always at 1, am i the only one?




 regarding texture swapping , as i said before , I hate Accessing the animationclip > find the Animationcurve > swap the picture each keyframe, to me it was very very tedious work , and I have no clue how you will approach it but when I did approach it , in the Animation , each monster kept the same charmap (if i set a single monster to be blue , everyone becomes blue etc) but again perhaps because I don't know how to handle animations properly :P

Regarding AnimationEvents , isn't Animation events best used with "Spriter Triggers " instead of sprites swapping? like reading a tag from SCML file and creat Animation event from it  (tags is not implemented in the previous Spriter2Unity and the current one if i am correct, but it would be very Helpful later in the far future if it was implemented)
if you wanna see what is spriter Trigger watch this :


regarding the last approach , game compnents , i think it has the most future potential , because of the possibility to add diffrent compenents to each gameobject that has a sprite . mind you I don't know why someone would need that :P perhaps adding physics or triggers on individuals sprites? I'm just shooting in the dark here XD anyhow lunch time , sorry for rambling alot

Link to comment
Share on other sites

The alpha channel should actually change according to what you set in spriter. Are you setting the alpha channel on the textures or on the bones? Bones have no renderer in Unity, so changing the alpha on those doesn't do anything.


Sprites with no bones? I'm going to have to test this.


I'm actually working on something really neat. It required a lot of wrestling with undocumented code and math I don't know the first thing about, but I've actually finished a prototype Sprite Swapper. It already swaps sprites during animation, but I also need to take into account sprites that are used in various different animations. It's a very easy to work with Script Component that's automatically added to any body part that uses multiple textures. It holds an editable array of sprite textures, with a numeric value that corresponds to the currently displayed Sprite. If you want to change body parts at run time, for single sprite body parts you can just change them in the renderer. For multisprite bodyparts, change them in the Sprite Swapper instead.

Link to comment
Share on other sites



Introducing: The Sprite Swapper. As I mentioned above, it is a Script Component that is added to a child Sprite object whenever it's necessary. If a particular body part only ever has one texture, there is no need for it. If you want to swap the sprite at runtime, just use a script to change it directly on the object's SpriteRenderer.


If the animation cycles between textures (say, for example, for different facial expressions), don't use the SpriteRenderer, it will be overridden by the SpriteSwapper component. The Sprite Swapper component contains an array of Sprite objects, each of which corresponds to one of the possible textures for that body part (such as the different facial expressions). If you need to change these at runtime (for example you have textures with a different skin color), just replace them in the array, like so:

SpriteSwapper swapper = GetComponent<SpriteSwapper> ();swapper.Sprites [0] = myNewSpriteReference;

Do this for every texture in the array.


Hopefully this will be a good help to you flexible programmers who like to switch things up through code.



Note that this implementation does not take care of textures that are added "out of nowhere" mid-animation, or in different animation. That implementation does not exist yet. I still haven't quite decided how I'm going to tackle that problem. Probably a similar technique I use with the Sprite Swapper.

Link to comment
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

  • Recently Browsing   0 members

    • No registered users viewing this page.
  • Create New...