How To Actually Use a Unity Sprite Resolver

Jun 16, 2020

I spent a whole bunch of hours trying to figure out how to use Sprite Libraries and Sprite Resolvers and FINALLY found the missing pieces.

For reference, here's a few of the many pages I was looking through in the Unity docs for guidance:

I also looked through each of these pages for the 4.x release. I knew something was up when I was seeing things in Unity that were quite a bit different from the tutorials.

The Issue

The issue centered around the fact that the docs allude to you being able to give "names" to each of the sprites in your Sprite Library, and then later reference those names in the Animation Clip as a way to specify which exact sprites to use during the animation. You enter the names in the editor as strings, but when you get over to the Animation Clip, everything is specified in—wait for it—floats. Why? Why.

Source: https://docs.unity3d.com/Packages/com.unity.2d.animation@3.2/manual/FFanimation.html Source: docs.unity3d.com

The tl;dr is that the backing scripts convert strings to "hashes", which end up as some CRC32-encoded bits that get stored as ints so that they can ultimately get rendered in the Animation Window as—you guessed it—floats. Confusing. I know.

I know this functionality is experimental and I'm guessing these docs have been carried forward for a while without much love, but yeah... some pieces are missing. So here's a guide for anyone that needs just a bit more help like me.

Pre-Reqs

Before getting started, you'll need to have a Prefab/Game Object, Animation Clip, and Animation Controller created already. Make sure the Prefab/Object is in the scene, has the Animator component attached to it, and that it references the Animation Controller you created. This part is no different from what you'd typically do.

1. Create the Sprite Library

In the Project section in Unity, right-click and create a new Sprite Library Asset (Experimental). Next, click the plus sign and create a new category. You can name it whatever you want. Each category holds an array of sprite entries, so set an array size and then drag your sprites over to each of the Sprite boxes. Each sprite entry needs a unique label so go ahead and enter those too. These are the things I mentioned before that manifest as floats ("hashes") in the Animation Window.

Note: If you plan to swap out Sprite Libraries (to change player skins, for example), you need to make sure these categories and labels are consistent across your Sprite Libraries.

2. Set Up the Game Object

Add the Sprite Library (Experimental) component and the Sprite Resolver (Experimental) component to your Game Object (click Add Component and search for them in the box). Drag your previously-created Sprite Library over to the Sprite Library Asset field on the Sprite Library component. This should cause your categories, labels, and sprites to show up under the Sprite Resolver component.

3. Set Up the Animation

Click on your game object and open up the Animation window. There are two properties you need to add here. Contrary to what the docs say, you'll want to add both Sprite Resolver.Label Hash and Sprite Resolver.Category Hash. The docs will have you believe there is a "label" property that's not a hash/float, but there totally isn't.

Animation Setup

Unfortunately, you can't just start manually keyframing these properties and typing values. Seemingly even if you know what the correct value should be. I'll get into how that works in the next section.

There's one more thing to note about the keyframes you do end up creating. You need to right-click and set them each to Broken with Both Tangents set to Constant. This has something to do with the hashes being discrete values, so tweening the float from one value to the next doesn't really make much sense.

4. Record the Animation

The final step is to add your animation keyframes. This is what links the animation to your Sprite Library. This is where I got lost for several hours trying to figure out the "correct" way to translate from string labels to floats and enter those values into my keyframes. Granted, I'm not the most experienced person with Unity animations, but like a lot of things in the animation workflow, it was very unclear to me how to make it happen.

Here's What to Do

Recording the animation is the key. From what I can tell, there's pretty much no value you can enter into the category or label hash that will work, even if it's a "correct" value. So hit the record button and click the first position on the timeline. Now, mouse over to your Sprite Resolver in the Inspector and select a category and label. Doing so should make a new keyframe show up in the Animation. You can repeat this process after clicking on another spot on the timeline. Once you're done, hit the record button again and revel in the glory that is your newly-created animation.

Check out this gif if you're a visual learner like me.