Playing Animations

After you have Downloaded Animancer, you can add an AnimancerComponent to your model and control it with a script:

  1. Add a reference to the AnimancerComponent (let’s call it animancer).
  2. Add a reference to the AnimationClip asset you want to play (let’s call it clip).
  3. Then you simply call animancer.Play(clip).

AnimancerController.Play returns an AnimancerState that can be used to access and control the animation details such as Speed and Time.

Example

The Quick Play example gives a detailed step by step explanation of how to play animations, but here's an overview:

using Animancer;
using UnityEngine;

public sealed class PlayAnimation : MonoBehaviour
{
    [SerializeField] private AnimancerComponent _Animancer;
    [SerializeField] private AnimationClip _Clip;

    private void OnEnable()
    {
        _Animancer.Play(_Clip);

        // You can manipulate the animation using the returned AnimancerState:
        // var state = _Animancer.Play(_Clip);
        // state.Speed = ...                  // See the Fine Control examples.
        // state.Time = ...                   // See the Fine Control examples.
        // state.NormalizedTime = ...         // See the Fine Control examples.
        // state.Events.OnEnd = ...           // See End Events.

        // If the animation was already playing, it will continue from the current time.
        // So to force it to play from the beginning you can just reset the Time:
        _Animancer.Play(_Clip).Time = 0;
    }
}

Play Methods

The AnimancerComponent class has several Play methods with different parameter sets depending on what you want to do.

Play Immediately

Play(AnimationClip clip)
Play(AnimancerState state)
Play(object key)

These methods immediately snap the character into the new animation. This is particularly good for Sprite animations such as those in the Basic Movement example because there is nothing to blend, the character can only show one Sprite at a time.

The differences between these parameters are explained on the States page.

Cross Fade

Play(AnimationClip clip,              float fadeDuration, FadeMode mode = FadeMode.FixedSpeed)
Play(AnimancerState state,            float fadeDuration, FadeMode mode = FadeMode.FixedSpeed)
Play(object key,                      float fadeDuration, FadeMode mode = FadeMode.FixedSpeed)

These methods fade the new animation in over time and fade the old animation out at the same time, which is known as Cross Fading. This is often much better for Skeletal Animations because it allows a character model to smoothly transition from the ending pose of one animation into the starting pose of another animation without requiring both poses to be exactly the same. It also means that the transition can still be smooth if an animation is interrupted at any time. The Playing and Fading example demonstrates the differences between playing animations immediately and cross fading between them.

Note that the FadeMode parameter is optional so the following two lines will both do the same thing:

animancer.Play(clip, 0.25f)
animancer.Play(clip, 0.25f, FadeMode.FixedSpeed)

Transition

Play(ITransition transition)
Play(ITransition transition, float fadeDuration, FadeMode mode = FadeMode.FixedSpeed)
These methods allow Transitions to apply all their details in a single call. This includes the fadeDuration (unless you use the second method to specify it yourself) as well as any other details defined in the transition such as Speed, Start Time, and any Animancer Events which can all be configured in the Inspector when using the inbuilt transition types instead of hard coding those details into your script.

Pausing

There are several different ways you can pause and stop individual animations or all of them at once:

using Animancer;
using UnityEngine;

public sealed class PausingExample : MonoBehaviour
{
    [SerializeField] private AnimancerComponent _Animancer;
    [SerializeField] private AnimationClip _Clip;

    // Freeze a single animation on its current frame:
    public void PauseClip()
    {
        var state = _Animancer.States[_Clip];
        state.IsPlaying = false;
    }

    // Freeze all animations on their current frame:
    public void PauseAll()
    {
        _Animancer.Playable.PauseGraph();
    }

    // Stop a single animation from affecting the character and rewind it to the start:
    public void StopClip()
    {
        _Animancer.Stop(_Clip);

        // Or you can call it on the state directly:
        var state = _Animancer.States[_Clip];
        state.Stop();
    }

    // Stop all animations from affecting the character and rewind them to the start:
    public void StopAll()
    {
        _Animancer.Stop();
    }

    // Stop all previous animations and play a new one:
    public void Play()
    {
        _Animancer.Play(_Clip);
    }

    // Play an animation without affecting any others:
    public void PlayIsolatedClip()
    {
        var state = _Animancer.States.GetOrCreate(_Clip);
        state.Play();
    }
}

Edit Mode

Animancer allows you to play animations in Edit Mode just as easily as they can be played normally, which is useful for previewing them in the scene.

The simplest way to use this feature is with the MonoBehaviour.OnValidate event message which gets called by the Unity Editor in Edit Mode whenever an instance of the script is loaded or a value is changed in the inspector. So you can simply use it to call AnimancerUtilities.EditModePlay:

[SerializeField] private AnimancerComponent _Animancer;
[SerializeField] private AnimationClip _Idle;

private void OnValidate()
{
    AnimancerUtilities.EditModePlay(_Animancer, _Idle);
}

The AnimancerUtilities.EditModePlay method takes care of a few extra concerns that aren't normally an issue in Play Mode, but at its core it's still just a regular call to AnimancerComponent.Play:

[System.Diagnostics.Conditional("UNITY_EDITOR")]
public static void EditModePlay(AnimancerComponent animancer, AnimationClip clip, bool pauseImmediately = true)
{
#if UNITY_EDITOR
    if (UnityEditor.EditorApplication.isPlayingOrWillChangePlaymode ||
        animancer == null || clip == null)
        return;

    // Delay for a frame in case this was called at a bad time (such as during OnValidate).
    UnityEditor.EditorApplication.delayCall += () =>
    {
        if (UnityEditor.EditorApplication.isPlayingOrWillChangePlaymode ||
            animancer == null || clip == null)
            return;

        animancer.Play(clip);

        if (pauseImmediately)
        {
            animancer.Evaluate();
            animancer.Playable.PauseGraph();
        }
    };
#endif
}
  • The [Conditional] attribute causes the compiler to remove any calls to that method from runtime builds (when UNITY_EDITOR isn't defined), which allows us to support convenient features like this during development without impacting runtime performance at all.
  • It checks EditorApplication.isPlayingOrWillChangePlaymode to avoid doing anything in Play Mode. Otherwise changing anything in the script's Inspector in Play Mode would play the specified Idle animation and pause the graph in the middle of gameplay, which the rest of the script isn't expecting to happen.
  • Unity will actually give errors if we try to play an animation directly inside OnValidate, so it also uses EditorApplication.delayCall to wait for one frame.
  • Passing true as the pauseImmediately parameter causes it to simply show the first frame of the animation and then stop while false would allow the animation to play normally. The default value is true because most people do not want things animating and moving around while they're trying to edit a scene, but it is mostly a matter of personal preference so feel free to try either way.
  • Also note that animations in Edit Mode do not count as modifications to the scene that will flag it as dirty (to tell Unity that it needs to be saved). This generally doesn't matter since any time the scene is opened the animation will simply be played again. However, when the scene does get saved it could be at any point in the animation and save whatever values it currently has, which would show up as modifications in a version control system.

  • This feature is especially convenient for Sprite animations like those in the Basic Movement example so that you can simply play the first frame of whatever Idle animation you assign to each character so that it will show the correct Sprite without you needing to also set the Sprite manually.
  • The Doors example allows each door to start anywhere between open and closed, so it uses this feature to show exactly where every door will be in the Scene view without needing to enter Play Mode.

Note that before Unity 2018.3, playing animations in Edit Mode did not work properly so you will need to update to a later version of Unity if you wish to use this feature.

States The most common type of AnimancerState is a ClipState which plays a single AnimationClip and is registered in an internal dictionary using that clip as the key.
Inspector Animancer shows the real-time details of all animations in the Inspector so you can observe what they are doing and control them manually for testing and debugging purposes.
Component Types There are several different kinds of AnimancerComponent and you can make your own to add or modify functionality.
Directional Animation Sets group animations into sets of up/right/down/left (including or excluding diagonals) to implement characters who can face any direction while performing various actions.