Sprite Swap overview (Experimental Feature)

Sprite Swap is an experimental feature that enables you to change a GameObject’s rendered Sprite within the same character Prefab. This enables you to quickly and easily create multiple characters that look different while reusing existing bone and Mesh data. You can also use Sprite Swap to switch the displayed Sprite on each frame at run time to create frame-by-frame animation.

The workflow for implementing Sprite Swap differs if you are using the workflow that is integrated with 2D Animation, or if you are manually setting up the Sprite Swap components.

Sprite Swap Assets and components

The following Assets and components are part of the Sprite Swap process:

  1. The Sprite Library Asset contains the Categories and Labels of the Sprites.
  2. The Sprite Library component shows the currently referred to Sprite Library Asset.
  3. The Sprite Resolver component is used to request a Sprite registered to the Sprite Library Asset by referring to the Category and Label value of the desired Sprite.

How Unity generates Sprite Swap Assets and components

Unity generates the various Sprite Swap components in the following steps:

  1. When you import a .psb file with the PSD Importer, Unity generates a Prefab containing a Sprite for each Layer in the source file.

  2. If you create any Categories or Labels while editing the character Prefab, Unity automatically generates a Sprite Library Asset as a sub-Asset of the Prefab.

  3. When the Prefab is brought into the Scene view, Unity generates a GameObject for each Sprite in the Prefab that does not belong to a Category. However if the Sprite is the first Label in a Category, then Unity will generate a GameObject for the Sprite as well.

  4. If the Prefab has a Sprite Library Asset sub-Asset, then Unity attaches the Sprite Library component to the root GameObject which is set to reference the Sprite Library Asset created in step 1 by default.

  5. Unity attaches the Sprite Resolver component to all Sprite GameObjects that belong to a Category.

Refer to the respective component pages for more information on their functions and properties.

Sprite Swap and 2D Animation integration

Sprite Swap is integrated with the 2D Animation workflow. You must install the following packages or newer to use the Sprite Swap feature:

Skeletal animation limitations

To ensure Sprite Swap works correctly with skeletal animation, the skeleton must be identical between the Sprites being swapped. Use the Copy and Paste tools to duplicate the skeleton rig from one Sprite to the other Sprite(s) to ensure they can be swapped smoothly.

Animator limitations

Note that in a single Animator Controller, you cannot have one Animation Clip animating the Sprite Renderer’s Sprite field while another Animation Clip animates the Sprite Resolver’s Category or Label field. If these two clips are in the same Animator Controller, they will conflict with each other causing unwanted playback results.

To resolve this issue, we advise the following solutions. The first solution 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 Category or Label field; but not both types in the same Animator Controller.

The second solution is to update all Animation Clips to the same type so that they can all remain in a single Animator Controller, by converting all clips animating a Sprite Renderer’s Sprite to animating a Sprite Resolver’s Category or Label field, or vice versa.