Singularity/Library/PackageCache/com.unity.2d.animation@7.0.10/Documentation~/SpriteSwapIntro.md

Sprite Swapping

Sprite Swap is a feature that enables you to change a GameObject’s rendered Sprite at runtime. This has a number of uses, such as easily creating multiple characters which share a skeleton (requires the PSD Importer package) or reuse existing bone and Mesh data while looking visually different.

Using Sprite Swap to change the rendered Sprites on each frame at runtime, you can even simulate a frame-by-frame animation style. The 2D Animation package comes with several Sample projects of the other different ways you can use Sprite Swap to achieve different effects and features, refer to the Sample documentation here for more information about these examples.

Sprite Swap Assets and components

Sprite Swap requires the following Assets and components, which are all included with the 2D Animation package:

1. The Sprite Library Asset that contains a set of selected Sprites which are assigned to different Categories and Labels.
   
2. Attach the Sprite Library component to a GameObject to assign or change which Sprite Library Asset the GameObject refers to.
   
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.

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 bone and skeleton data from one Sprite to another to ensure they can be swapped correctly.

Animator limitations

In a single Animator Controller, you cannot have one Animation Clip animating the Sprite Renderer’s assigned Sprite while another Animation Clip animates the Sprite Resolver’s Sprite Key. 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 Sprite Key; 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 Sprite Key, or vice versa.