Introduction to Sprite Swap

This page introduces what's Sprite Swap, its different uses and its limitations. Sprite Swap refers to changing the rendered Sprite of a GameObject at runtime, which is useful when animating the Sprites that make up a 2D actor or other GameObjects.

For example, you can swap the individual Sprites that make up an animated actor to create multiple actors that share the same skeleton (requires the PSD Importer package; or create animation clips by swapping the Sprites at runtime.

You can import sample projects for the 2D Animation package by selecting the option in the 2D Animation package window. Refer to the individual Sprite Swap examples pages for more information about these samples.

Required assets and components

Sprite Swap requires the following Assets and component, which are available with the 2D Animation package:

  • Sprite Library Asset: The Sprite Library Asset contains a set of selected Sprites which are assigned to different Categories and Labels.

  • Sprite Library component: The Sprite Library component determines which Sprite Library Asset a GameObject refers to.

  • Sprite Resolver component: The Sprite Resolver component requests a Sprite registered to the Sprite Library Asset by referring to the Category and Label value of the desired Sprite.

Technical limitations

The following are technical limitations which you should keep in mind when using Sprite Swap.

Skeletal animation limitations

If you want to animate your actor and use Sprite Swap with skeletal animation, both sprites that are swapped must have an identical skeleton. Use the Copy and Paste tools of the Skinning Editor to duplicate the bone and skeleton data from one sprite to another to ensure they will swap correctly.

Animator limitations

In a single Animator Controller, you can't have one Animation Clip animating the Sprite Renderer’s assigned sprite while another Animation Clip animates the Sprite Resolver’s sprite hash. If these two clips are in the same Animator Controller, they will conflict with each other and cause unwanted playback results.

Use the following recommended methods to resolve this issue.

  1. The first method is to separate the Animation Clips into separate Animator Controllers that contain only clips that animate either a Sprite Renderer’s sprite or the Sprite Resolver’s sprite hash but not both types in the same Animator Controller.

  2. The second method is to update all Animation Clips to the same type so that they can all remain in a single Animator Controller. To do so, convert all clips animating a Sprite Renderer’s sprite to animating a Sprite Resolver’s sprite hash, or vice versa.

Additional resources