Location: Assets/Plugins/Animancer/Examples/06 State Machines/01 Character

Recommended After: Basic Character

Learning Outcomes: in this example you will learn:

How to use Animancer's Finite State Machine system.

A useful pattern for dividing character logic into multiple scripts.

Why dividing complex logic into multiple scripts is a good idea.

This example demonstrates how the logic from the Basic Character example can be divided into multiple scripts using Animancer's Finite State Machine system.

Summary

• This example doesn't teach any new animation concepts.
• It explains why you should split complex logic into multiple scripts and demonstrates how you can do so.
• It uses Animancer's Finite State Machine system, but the general concepts can be utilised in practically any system.

Controls

• W = Move.
• Left Click = Shoot.

Introduction

Overview

The general code structure in this example has been used effectively in a wide range of different situations (both with and without Animancer) but like all design patterns it can't be perfect for everything so you should always feel free to add your own variations or use a different approach entirely depending on the needs of your situation.

Here's an overview of the main parts which make up a character in this system:

The code structure is much more complicated than the Basic Character example, but by the end of this example you should understand how it all fits together:

Character

It references the AnimancerComponent:

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

And has an accessor Property so other scripts can use that reference but not re-assign it:

    public AnimancerComponent Animancer => _Animancer;

The other fields aren't used in this example but are properly explained in later examples which reuse the scripts from this one:

[SerializeField]
private HealthPool _Health;
public HealthPool Health => _Health;

[SerializeField]
private CharacterParameters _Parameters;
public CharacterParameters Parameters => _Parameters;

[SerializeField]
private Equipment _Equipment;
public Equipment Equipment => _Equipment;

In a real project, this is where you would also put references to things like a Rigidbody or CharacterController, a script that detects whether the character is currently on the ground, character stats, an inventory system, etc.

State Machine

The Character class also holds the StateMachine that will manage their actions. It uses the Serialized Field pattern explained on the Initialization page:

[DefaultExecutionOrder(-10000)]
public sealed class Character : MonoBehaviour
{
    ...
    
    [SerializeField]
    private CharacterState.StateMachine _StateMachine;
    public CharacterState.StateMachine StateMachine => _StateMachine;

    private void Awake()
    {
        StateMachine.InitializeAfterDeserialize();
    }
}

The CharacterState class is explained properly below, but for now we're just interested in its nested StateMachine class which is using a State Machine with a Default State:

class CharacterState
{
    [System.Serializable]
    public class StateMachine : StateMachine<CharacterState>.WithDefault { }

    ...
}

States

The base State Type in this example is CharacterState.

It could Inherit from MonoBehaviour and implement IState, but it's easier to just Inherit from StateBehaviour:

public abstract class CharacterState : StateBehaviour
{

The nested StateMachine class was already mentioned above:

    [System.Serializable]
    public class StateMachine : StateMachine<CharacterState>.WithDefault { }

Every state has a reference to the Character it controls:

    [SerializeField]
    private Character _Character;
    public Character Character => _Character;

And in order to avoid needing the user to manually assign the Character for every state, it has an OnValidate method which uses the Extension Method Approach to automatically find an appropriate reference nearby:

#if UNITY_EDITOR
    protected override void OnValidate()
    {
        base.OnValidate();

        gameObject.GetComponentInParentOrChildren(ref _Character);
    }
#endif

That method needs to be in a #if UNITY_EDITOR block because the base method it overrides in StateBehaviour is also in a #if UNITY_EDITOR block.

There are also several more properties to determine which states can interrupt each other. They are explained properly in the Interruptions example:

    public virtual CharacterStatePriority Priority => CharacterStatePriority.Low;

    public virtual bool CanInterruptSelf => false;

    public override bool CanExitState
    {
        get
        {
            // There are several different ways of accessing the state change details:
            // var nextState = StateChange<CharacterState>.NextState;
            // var nextState = this.GetNextState();
            var nextState = _Character.StateMachine.NextState;
            if (nextState == this)
                return CanInterruptSelf;
            else if (Priority == CharacterStatePriority.Low)
                return true;
            else
                return nextState.Priority > Priority;
        }
    }
}

This example has 3 state types which inherit from that base:

• Idle
• Move
• Action

Idle State

The Idle state is very simple, just a Transition which it plays when the state is entered:

public sealed class IdleState : CharacterState
{
    [SerializeField] private ClipTransition _Animation;

    private void OnEnable()
    {
        Character.Animancer.Play(_Animation);
    }
}

CharacterState inherits from StateBehaviour which means it will automatically disable itself by default and then enable itself when the state machine enters that state. So the OnEnable method will effectively do the same as if we had used public override void OnEnterState().

Move State

There is no Move state script in this example because IdleState already does exactly what it needs, so the character simply has a second IdleState component with a different animation assigned.

The Brains example implements a proper MoveState to allow the character to actually move around the scene, including walking and running, as well as turning.

Action State

The Action state starts the same as the others but has a bit more complexity below:

public sealed class ActionState : CharacterState
{
    [SerializeField] private ClipTransition _Animation;

    private void OnEnable()
    {
        Character.Animancer.Play(_Animation);
    }

Unlike Idle and Move, this animation isn't looping so we want to return to Idle when it ends. The easiest way to do that is to set its End Event to return to its Default State:

    private void Awake()
    {
        _Animation.Events.OnEnd = Character.StateMachine.ForceSetDefaultState;
    }

It overrides the properties that control how it can be interrupted (which will be explained properly in the Interruptions example):

• Priority returns Medium so that it can interrupt the IdleState but not be interrupted by it (because IdleState uses the default Low priority from the base CharacterState).
• CanInterruptSelf returns true so that the character can still rapid fire like they could in the Basic Character example.

    public override CharacterStatePriority Priority => CharacterStatePriority.Medium;

    public override bool CanInterruptSelf => true;
}

Brain

A character's brain is responsible for deciding what they want to do. The Brains example explains why the system in general is designed the way it is, so this section only focusses on what this specific script does.

There are two things this character can choose to do: Move and perform an Action. So the brain has a Character to control and fields for each of those actions:

public sealed class BasicCharacterBrain : MonoBehaviour
{
    [SerializeField] private Character _Character;
    [SerializeField] private CharacterState _Move;
    [SerializeField] private CharacterState _Action;

Then it has an Update method which is similar to the Update method in the Basic Character example, but this one is simpler because the responsibility of determining what the character can do at any given time is already handled by the State Machine:

    private void Update()
    {
        UpdateMovement();
        UpdateAction();
    }

The UpdateMovement and UpdateAction methods are also very similar to the Methods in the Basic Character example and it avoids the extra complexity added in the Method Changes section because instead of directly telling Animancer to play animations it tells the character to try to enter states and leaves it up to those states to determine what actually happens:

    private void UpdateMovement()
    {
        float forward = ExampleInput.WASD.y;
        if (forward > 0)
        {
            _Character.StateMachine.TrySetState(_Move);
        }
        else
        {
            _Character.StateMachine.TrySetDefaultState();
        }
    }

    private void UpdateAction()
    {
        if (ExampleInput.LeftMouseUp)
            _Character.StateMachine.TryResetState(_Action);
    }
}

There are several different methods of Changing States used there:

Scene Setup

Since we put all that effort into logically separating the character's scripts, it's worthwhile to logically group their scene objects as well to avoid ending up with a long list of components on a single object in the Inspector:

With all that set up, now you can enter Play Mode to see the character in action:

What Next?