When you play an AnimationClip
, Animancer creates a ClipState
to manage it and keep track of its progress. Then if you play the same animation again later, it will reuse that same state.
ClipState
is the most common type of AnimancerState
, but there are other types such as Controller States and Mixer States which manage multiple animations in a single state.
The easiest way to access a state is usually to get the reference returned by the AnimancerComponent.Play
method:
void PlayAnimation(AnimancerComponent animancer, AnimationClip clip)
{
var state = animancer.Play(clip);
state.Time = ...
state.NormalizedTime = ...
state.Speed = ...
state.Events.OnEnd = ...
}
There are also various other ways of accessing and creating states:
Code | Description |
---|---|
|
This property stores the state that was most recently returned by the Play method. If you are using multiple Layers, this property refers to the base layer. |
|
This property stores the state that was most recently returned by the Play method of Layer x . |
|
If a state for the clip already exists, this Indexer returns it. Otherwise it throws a KeyNotFoundException . |
|
If a state for the clip already exists, this method assigns it to the state out Parameter and returns true . Otherwise the state will be null and the method returns false . |
|
If a state for the clip already exists, this method returns it. Otherwise it creates and returns a new one. The Play(clip) method uses this internally. |
|
Creates a new state even if one already existed for that animation. Note that each state must have a different Key or it will throw an ArgumentException . |
|
Create a new state without giving it a Key. |
|
If a state for the clip exists, this method destroys it and returns true . Otherwise it returns false . |
The Fine Control examples demonstrate how you can manipulate animation states in more detail.
Keys
When AnimancerComponent.Play
creates a state, it registers it in an internal Dictionary using a particular key so that it can later be retrieved using that key and reused.
- By default, the
AnimationClip
the state is playing will be used as its key, but the system allows you to use anyobject
as a key (every variable in C# is anobject
). - The
NamedAnimancerComponent
overrides itsGetKey
method to use the clip'sname
instead of theAnimationClip
itself. So callinganimancer.Play(clip)
uses thename
to lookup the state, but you can also pre-register the clip on startup by adding it to theAnimations
array in the Inspector or callinganimancer.States.GetOrCreate(clip)
so that later on you can callanimancer.Play("Animation Name")
in any script without a direct reference to theAnimationClip
. The Named Animations example explains howstring
names and other keys (such as enums) can be used in more detail.
void PlayAnimation(AnimancerComponent animancer, AnimationClip clip)
{
// Trying to play an animation before registering it does nothing.
animancer.TryPlay("Attack");
// But if you create a state with a key first, then you only need that key to play it later on.
animancer.States.Create("Attack", clip);
animancer.TryPlay("Attack");
// Or you can create the state and set its key manually:
var state = new ClipState(clip);
state.Key = "Attack";
}
- You don't need to set the
AnimancerState.Key
if you don't want to. You can simply create anew ClipState
(or whatever type of state you want) and keep a reference to it for when you want to use it. - If you want to have multiple states playing the same clip (such as if you need to play it on multiple Layers) you will need to register them all with different keys (or not register them at all).
FadeMode.FromStart
uses this to fade a clip out while fading another copy of it in at the same time.
Enum Keys
Unfortunately, since object
is a Reference Type, using a Value Type like an enum
in those methods implicitly creates a new object
to hold the value. This is called Boxing and has a notable impact on performance, particularly since the new object
is immediately discarded after the call and needs to be Garbage Collected. This does not mean enums should not be used, just that you should be aware of the inefficiency.
Object Keys
Another approach is to use actual object
s as keys. Rather than an enum
you could make a class
like this:
public static class CharacterAction
{
public static readonly object Idle = new object();
public static readonly object Walk = new object();
public static readonly object Run = new object();
// Etc.
}
Those object
s will not actually do anything on their own but can be used as keys in a similar fashion to an enum: animancer.States.Create(CharacterAction.Walk, _Walk);
.
Component Keys
If a script only has one animation that it will play, it could use itself as the key, so a Walk
script could create a state with animancer.States.Create(this, _Walk);
and play it with animancer.Play(this)
. That will not work if it is actually a Movement
script that handles both Walk and Run animations as separate states though.
Performance
Creating a state and connecting it to the Playable Graph takes a bit of time, just like any other operation. In the vast majority of cases this cost is so small that it is not worth considering, so you should just create states wherever is most convenient. This is why the most common way of using Animancer is to directly give it the AnimationClip
you want to play so that it can create a state for itif one does not already exist and then reuse it each time you play that animation in the future.
Initialising all or most of the states you will need on startup adds a bit of complexity and can improve performance, but only does so by putting a greater load upfront. That might be good during a loading screen, but if you instantiate a character during gameplay you have already paid a high performance cost for doing so, meaning that it might be better not to spend even more of that frame's time pre-initialising all the othe states as well. There are two main ways of initialising states upfront:
- Call
animancer.States.GetOrCreate
(orCreate
) in your startup code (such as anAwake
orStart
method). - Use a
NamedAnimancerComponent
and assign the clips in question to itsAnimations
array in the Inspector (or using a script). This simply callsGetOrCreate
for each one in itsAwake
method.
If you no longer need a state, you can call AnimancerState.Destroy
to remove it. Both the destroying and subsequent Garbage Collection also have a performance cost that may need to be managed.
The Performance Benchmarks section goes into further detail about the performance of Animancer.