01 Quick Play

Difficulty: Beginner

Location: Assets/Plugins/Animancer/Examples/01 Basics/01 Quick Play

Namespace: Animancer.Examples.Basics

This example demonstrates how to use Animancer to implement some simple behaviour:

  1. Start with an Idle animation.
  2. When the user clicks the mouse, perform an Action.
  3. When that action is complete, return to Idle.

Overview

This example consists of one very simple script called PlayAnimationOnClick:

Experts: if you can already understand what this script doing just by reading it you can feel free to skip to the next example.

Beginners: if you have trouble understanding the concepts introduced here, you might want to start with some tutorials on the Unity Learn website to learn the basics of programming and using Unity before learning to use Animancer.

Questions and Feedback: the Help page lists several contact methods you can use if you have any questions or suggestions.

using Animancer;
using UnityEngine;

public class PlayAnimationOnClick : MonoBehaviour
{
    [SerializeField] private AnimancerComponent _Animancer;
    [SerializeField] private AnimationClip _Idle;
    [SerializeField] private AnimationClip _Action;

    private void OnEnable()
    {
        _Animancer.Play(_Idle);
    }

    private void Update()
    {
        if (Input.GetMouseButtonDown(0))
        {
            var state = _Animancer.Play(_Action);
            state.Events.OnEnd = OnActionEnd;
        }
    }

    private void OnActionEnd()
    {
        _Animancer.Play(_Idle, 0.25f);
    }
}

There are two characters in the scene which both use the same script, except one of them has Swing animations assigned in the Inspector while the other has Putt animations:

  • The Animator is Unity's component for objects that can play animations.
  • The AnimancerComponent is Animancer's main component which works with the Animator.
  • The PlayAnimationOnClick is the script for this example.
Swing Putt

New Script

Start by following the Basic Scene Setup instructions to create a new scene with the character in it.

Then follow the New Script instructions to create a script called PlayAnimationOnClick and open it up in your IDE (such as Visual Studio). Edit the script so that it looks like this:

using Animancer;
using UnityEngine;

public class PlayAnimationOnClick : MonoBehaviour
{
}

The New Script section also explains what each of the parts of the script mean, but you can come back to it later if you just want to see some animations playing.

Idle Animation

Now let's get the idle animation going. The first thing the PlayAnimationOnClick script needs is a reference to an AnimancerComponent that it wants to control. The most common ways to reference another script are explained in the Composition section, including the reason why the Animancer examples favour Serialized Fields.

So we declare a Serialized Field inside the class like so:

public class PlayAnimationOnClick : MonoBehaviour
{
    [SerializeField] private AnimancerComponent _Animancer;

Or you can use multiple lines if you prefer:

    [SerializeField]
    private AnimancerComponent _Animancer;

Since AnimancerComponent is in the Animancer Namespace, we either need to put using Animancer; at the top of the script or we need to specify the full name of the type as Animancer.AnimancerComponent.

We also need a reference to the idle animation, so let's add another field:

    [SerializeField] private AnimationClip _Idle;

Similarly, AnimationClip is in the UnityEngine Namespace so we have using UnityEngine; at the top of the script.

Then we can just tell it to play that animation on startup using an OnEnable method, which is one of the MonoBehaviour Messages (meaning that it has that specific name so Unity will call it for us on startup):

    private void OnEnable()
    {
        _Animancer.Play(_Idle);
    }

See the Methods page if you are unfamiliar with the concept of methods.

The full script now looks like this:

using Animancer;
using UnityEngine;

public class PlayAnimationOnClick : MonoBehaviour
{
    [SerializeField] private AnimancerComponent _Animancer;
    [SerializeField] private AnimationClip _Idle;
    
    private void OnEnable()
    {
        _Animancer.Play(_Idle);
    }
}

Let's save the script and go back to Unity to see it in action.

  1. Select your character in the Hierarchy window (the root object with the Animator component).
  2. Make sure the Apply Root Motion toggle is deselected since we do not want any movement in this example.
  3. Add an AnimancerComponent if you didn't do so already as part of the Basic Scene Setup.
  4. Add the PlayAnimationOnClick script you just created then assign each of its Serialized Fields:
  5. Drag and drop the AnimancerComponent into the Animancer field in that component.
  6. Use the circular icon next to the Idle field to open the Object Picker window to find the Idle animation you want to use. The original example uses Humanoid-GolfSwingReady.

Click here if you are wondering why some things look a little different from Unity's defaults in that video.

It's because of a plugin called Inspector Gadgets (also made by Kybernetik like Animancer).

Its main feature replaces the default Transform Inspector (which is hidden in the above video), but Inspector Gadgets Pro also adds a [Get] button (the above video shows an older version) to the Object Reference Fields (on the right of the PlayAnimationOnClick script) while they are null to save time by searching for an appropriate object with a single click.

Now if you press Play (the triangular button in the top center of the Unity Editor), the model will be playing the idle animation you gave it (the Humanoid-GolfSwingReady animation used here is just a stationary pose):

Remember to exit Play Mode after you are done looking.

Golf Club

That pose looks a bit funny without anything to hold so let's give him a golf club.

  1. Expand the character's hierarchy until you reach the RightHandHolder bone (an extra bone which is a child of the right hand in a good position for holding objects). Note that if you hold Alt when you expand or collapse something, it will do the same for all of that object's children as well.
  2. Go to the Assets/Plugins/Animancer/Examples/Art/Props folder.
  3. Drag the GolfClub prefab from the Project window onto the RightHandHolder object in the Hierarchy window (a child of the right hand bone) to instantiate the prefab as a child of that bone. The position and rotation of the GolfClub should all be at 0.

Note that a "bone" is simply a regular GameObject / Transform which deforms the character model as it moves and rotates. So even though the RightHandHolder is part of the FBX file the model comes from, it's not really a bone because it doesn't affect the model (it is simply there to make it easy to position objects in the hand).

Now he will be holding the golf club when we press Play.

Remember to exit Play Mode after you are done looking.

Swing Animation

A golf club won't do much good if he can't swing it, so let's get on that.

First we need to add another AnimationClip field to the script. Just make a copy of the _Idle field and rename it to _Action.

Then we want to know when the player clicks the mouse, so let's make an Update method to check that:

private void Update()
{
    // GetMouseButtonDown returns true during the frame when you first click the mouse.
    // The parameter specifies which mouse button we want:
    // 0 = Left Click.
    // 1 = Right Click.
    // 2 = Middle Click.
    if (Input.GetMouseButtonDown(0))
    {
    }
}

See the Methods page for more information about Flow Control (the if statement), Parameters (the 0), and Return Values (the value returned by GetMouseButtonDown).

Inside that if block we want to play the _Action animation, so we can just copy the contents of the OnEnable method and change the parameter.

The full script now looks like this:

using Animancer;
using UnityEngine;

public class PlayAnimationOnClick : MonoBehaviour
{
    [SerializeField] private AnimancerComponent _Animancer;
    [SerializeField] private AnimationClip _Idle;
    [SerializeField] private AnimationClip _Action;
    
    private void OnEnable()
    {
        _Animancer.Play(_Idle);
    }

    private void Update()
    {
        if (Input.GetMouseButtonDown(0))
        {
            _Animancer.Play(_Action);
        }
    }
}

Save the script again and go back to Unity.

Before it will do anything, we need to give it the swing animation. Just select the character and assign the Action animation in the Inspector the same way we assigned the Idle. The original example uses the Humanoid-GolfSwing animation.

Now when we enter Play Mode we can click to trigger the swing animation.

Remember to exit Play Mode after you are done looking.

After the Action

The character now has an obvious problem: he can swing like a champ, but then he gets delayed stagefright and freezes in place. Fortunately there's a simple cure for that if we go back to the script.

All we need to do is wait until the animation is done then return to idle so let's first create a method to be called:

private void OnActionEnd()
{
    _Animancer.Play(_Idle);
}

Then we can go back to the Update method, grab the AnimancerState returned by Play, and assign that new method as a callback to its OnEnd event:

var state = _Animancer.Play(_Action);
state.Events.OnEnd = OnActionEnd;

There are a couple of different ways we could have done that which are listed on the AnimancerEvent.Sequence.OnEnd page. The End Events page also explains some alternative approaches instead of using the OnEnd callback.

The full script looks like this:

using Animancer;
using UnityEngine;

public class PlayAnimationOnClick : MonoBehaviour
{
    [SerializeField] private AnimancerComponent _Animancer;
    [SerializeField] private AnimationClip _Idle;
    [SerializeField] private AnimationClip _Action;

    private void OnEnable()
    {
        _Animancer.Play(_Idle);
    }

    private void Update()
    {
        if (Input.GetMouseButtonDown(0))
        {
            var state = _Animancer.Play(_Action);
            state.Events.OnEnd = OnActionEnd;
        }
    }

    private void OnActionEnd()
    {
        _Animancer.Play(_Idle);
    }
}

If we take another look at it in Play Mode we can see the character return to idle after the swing so we can click to swing again.

Remember to exit Play Mode after you are done looking.

Smooth Transitions

There's still an obvious problem with it though: when the swing ends, the character snaps instantly back to idle instead of moving smoothly from where the swing ended. This could be solved by making sure that the swing animation ends in exactly the same pose where the idle starts, but that is not always practical. Fortunately, this can be easily solved by Cross Fading between the animations. The Playing and Fading example goes into more detail on the subject, but let's give it a quick try here.

All you need to do is add another parameter to the Play call to tell it how long you want the transition to take:

_Animancer.Play(_Idle);// Play instantly.
_Animancer.Play(_Idle, 0.25f);// Cross Fade over 0.25 seconds.

The final script looks like this:

using Animancer;
using UnityEngine;

public class PlayAnimationOnClick : MonoBehaviour
{
    [SerializeField] private AnimancerComponent _Animancer;
    [SerializeField] private AnimationClip _Idle;
    [SerializeField] private AnimationClip _Action;

    private void OnEnable()
    {
        _Animancer.Play(_Idle);
    }

    private void Update()
    {
        if (Input.GetMouseButtonDown(0))
        {
            var state = _Animancer.Play(_Action);
            state.Events.OnEnd = OnActionEnd;
        }
    }

    private void OnActionEnd()
    {
        _Animancer.Play(_Idle, 0.25f);
    }
}

And here is what it looks like in Play Mode:

Note that Animancer Lite only allows a fade duration of 0.25 seconds. You can try out any duration you want in the Unity Editor, but it will warn you that it will always use the default duration in runtime builds unless you purchase Animancer Pro.

What Next?

That is all for this first tutorial, but there are plenty more where that came from:

  • The Playing and Fading example goes into more detail about the differences between the various parameter combinations you can give when calling the Play method.
  • The Transitions example shows how you can customise animation details such as the fade duration in the Inspector instead of hard-coding them in your scripts.
  • The Golf Events example builds upon this one to show how you can make Animancer trigger a function at a specific time during an animation to hit a ball and also how to adjust the transition back to Idle to look more natural.

The up arrow in the bottom right corner of the page will take you back to the top.