States

A robust and flexible state machine implementation for Unity

In One Line

States that flow like water, solid as rock.

Overview

The States Package is designed to manage complex state transitions and behaviors in your game objects and systems. It provides a clean, builder-pattern-based API for creating and managing state machines with support for nested states and system integration.

Package Info

display name

AceLand States

package name

com.aceland.states

latest version

2.0.0

namespace

AceLand.States

git repository

https://github.com/parsue/com.aceland.states.git

dependencies

com.aceland.library: 2.0.4
com.aceland.playerloophack: 1.0.5
com.aceland.taskutils: 2.0.2

Key Features

Builder pattern for intuitive state machine construction
Support for any-state transitions
Sub state machine capabilities
System integration through Unity's PlayerLoop
Automatic resource management and cleanup
Asynchronous state machine retrieval
Custom state action injection
Debug logging support

Core Components

StateMachine

The main class for creating and managing states. Provides:

State transitions management
Update cycle handling
Resource cleanup
System integration capabilities

State

Represents individual states within the state machine:

Customizable Enter/Update/Exit behaviors
Sub State Machine support
Action injection capabilities
Unique state identification

How It Works

Core Architecture

The States Package operates on a hierarchical system with several key components working together:

State Machine Core
- Maintains a registry of all states
- Manages transitions between states
- Handles the update cycle
- Controls state lifecycle (Enter → Update → Exit)
State Transitions
- Uses a double-buffered transition system to prevent race conditions
- Evaluates transitions in priority order:
  1. Any-state transitions
  2. Specific state transitions
- Prevents invalid transitions through state validation

Performance Considerations

Update Optimization
- Minimal garbage collection impact
- Cached transition evaluations
- Efficient state lookup through dictionary storage
Memory Efficiency
- States are shared when possible
- Action delegates are cached
- Transition conditions are optimized

Usage Example

This example works with Packages Task Utils, Player Loop Hack and Input for easy settings and handling.

Task Utils and Player Loop Hack is already installed with this package. To try this example, please install AceLand Input.

public enum StateMachineId
{
    Test1 = 900,
    Test2 = 901,
}

State Machine will run on calling Start(), and will stop on calling Stop().

Update state will be running on:

Build() - calling Update()
BuildAsSystem(state) - each PlayerLoop state.

using AceLand.Input.Events;
using AceLand.Input.State;
using AceLand.PlayerLoopHack;
using AceLand.States;
using UnityEngine;

public class StateMachineTest1 : MonoBehaviour, IButtonPressed
{
    // create all states name
    public enum States
    {
        Init, Splash, Title, Running, Quit,
    }
    
    // reference of StateMachine
    private IStateMachine _stateMachine;
    // state of machine
    private States _state;

    private void Awake()
    {
        InitStateMachine();
    }

    private void Start()
    {
        _stateMachine.Start();
    }

    private void OnDestroy()
    {
        _stateMachine.Stop();
        _stateMachine.Dispose();
    }

    private void InitStateMachine()
    {
        // create all states at one.
        IState[] states = State.Builders()
            .WithNames<States>()
            .Build();
        
        // inject actions to each state
        // there are 3 stages in all states [enter, update, exit]
        IState initState = states[0].InjectActions(enter: OnInitEnter);
        IState splashState = states[1].InjectActions(enter: OnSplashEnter);
        IState titleState = states[2].InjectActions(enter: OnTitleEnter);
        IState runningState = states[3].InjectActions(enter: OnRunningEnter);
        IState quitState = states[4].InjectActions(enter: OnQuitEnter);
        
        // create state machine with states and transitions
        _stateMachine = StateMachine.Builder()
            .WithStates(states)    // add all states to machine
            .WithEntryTransition(initState)    // set first state on machine start
            // add transitions with specified state to specified state
            .WithTransition(initState, splashState, () => _state is States.Splash)
            .WithTransition(splashState, titleState, () => _state is States.Title)
            .WithTransition(titleState, runningState, () => _state is States.Running)
            .WithTransition(runningState, titleState, () => _state is States.Title)
            // add transitions with any state to specified state
            .WithAnyTransition(quitState, () => _state is States.Quit)
            .WithId(StateMachineId.Test1)    // optional: set machine id
            .BuildAsSystem(PlayerLoopState.EarlyUpdate);
         // .BuildAsSystem(state) will run automatically when start
    }
    
    // Event from AceLand.Input
    public void OnButtonPressed(in BtnStatus btnStatus)
    {
        switch (btnStatus.Name)
        {
            // switch state
            case "space":
                _state = _state switch
                {
                    States.Init => States.Splash,
                    States.Splash => States.Title,
                    States.Title => States.Running,
                    States.Running => States.Title,
                    _ => _state,
                };
                break;
            
            // any state to quit
            case "e":
                _state = States.Quit;
                break;
        }
    }

    private void OnInitEnter() => Debug.Log("A -----> Init Enter");
    private void OnSplashEnter() => Debug.Log("A -----> Splash Enter");
    private void OnTitleEnter() => Debug.Log("A -----> Title Enter");
    private void OnRunningEnter() => Debug.Log("A -----> Running Enter");
    private void OnQuitEnter() => Debug.Log("A -----> Quit Enter");
}

State Machine will run on calling Start(), and will stop on calling Stop().

Update state will be running on:

Build() - calling Update()
BuildAsSystem(state) - each PlayerLoop state.

State Machine will become a Sub State Machine when injected to state in other machine.

using AceLand.Input.Events;
using AceLand.Input.State;
using AceLand.PlayerLoopHack;
using AceLand.States;
using AceLand.TaskUtils;
using UnityEngine;

public class StateMachineTest2 : MonoBehaviour, IButtonPressed
{
    public enum States
    {
        Loading, Play, Pause,
    }
    
    private IStateMachine _stateMachine;
    private States _state;

    private void Awake()
    {
        InitStateMachine();
        InjectStateMachine();
    }

    private void OnDestroy()
    {
        _stateMachine.Stop();
        _stateMachine.Dispose();
    }

    private void InitStateMachine()
    {
        IState[] states = State.Builders()
            .WithNames<States>()
            .Build();
        IState loadingState = states[0].InjectActions(enter: OnLoadingEnter);
        IState playState = states[1].InjectActions(enter: OnPlayEnter);
        IState pauseState = states[2].InjectActions(enter: OnPauseEnter);

        _stateMachine = StateMachine.Builder()
            .WithStates(states)
            .WithEntryTransition(loadingState)
            .WithTransition(loadingState, playState, () => _state is States.Play)
            .WithTransition(playState, pauseState, () => _state is States.Pause)
            .WithTransition(pauseState, playState, () => _state is States.Play)
            .WithId(StateMachineId.Test2)
            .Build();
         // .Build() will create a manual machine that update manually.
    }

    private void InjectStateMachine()
    {
        // Get machine Test1
        StateMachine.GetAsync(StateMachineId.Test1)
            .Then(machine =>
            {
                Debug.Log("Inject StateMachine B to Machine A Running State");
                // Get State from machine Test1
                machine.GetState(StateMachineTest1.States.Running)
                    // inject Test2 as sub machine
                    .InjectSubStateMachine(_stateMachine)
                    // reset Test2 state on exit
                    .InjectActions(exit: () => _state = States.Loading);
            })
            .Catch(e => Debug.Log(e, this));
    }
    
    public void OnButtonPressed(in BtnStatus btnStatus)
    {
        // do not update state if Test2 is not active
        if (!_stateMachine.IsActive) return;
        
        switch (btnStatus.Name)
        {
            // switch state
            case "z":
                _state = _state switch
                {
                    States.Loading => States.Play,
                    States.Play => States.Pause,
                    States.Pause => States.Play,
                    _ => _state,
                };
                break;
        }
    }

    private void OnLoadingEnter() => Debug.Log("B -----------> Loading Enter");
    private void OnPlayEnter() => Debug.Log("B -----------> Play Enter");
    private void OnPauseEnter() => Debug.Log("B -----------> Pause Enter");
}

Sub State Machine will start and stop on injected state Enter and Exit.

Update state will be running on:

Build() - will update on same PlayerLoop state of machine injected to
BuildAsSystem(state) - will update on set PlayerLoop state.

Prewarm Provider

State Machine is a core system design. Initialization should be started in very early state.

Prewarm Provider is a scriptable object. System will build the State Machine after assembly ready state. When the scene starts to load, the whole state machines system is already ready. This can also prevent from GetAsync process.

using AceLand.EventDriven.EventSignal;
using AceLand.States;
using AceLand.States.Profiles;
using UnityEngine;

namespace AceLand.Profiles
{
    public enum States
    {
        Init, Title, Story, Play, Pause, Quit,
    }
    
    [CreateAssetMenu(fileName = "State Machine Prewarm", menuName = "Profiles/State Machine Prewarm")]
    public class StateMachinePrewarm : StateMachinePrewarmProvider
    {
        public IStateMachine GetStateMachine() => _stateMachine;
    
        private IStateMachine _stateMachine;
        private Signal<States> _stateSignal;
        
        public override void PrewarmStateMachine()
        {
            _stateSignal = Signal.Builder()
                .WithId("StateMachineState")
                .WithValue(States.Init)
                .Build();

            var states = State.Builders()
                .WithNames<States>()
                .Build();
            var initState = states[0];
            var titleState = states[1];
            var storyState = states[2];
            var playState = states[3];
            var pauseState = states[4];
            var quitState = states[5];

            _stateMachine = StateMachine.Builder()
                .WithStates(states)
                .WithEntryTransition(initState)
                .WithTransition(initState, titleState, () => _stateSignal.Value is States.Title)
                .WithAnyTransition(storyState, () => _stateSignal.Value is States.Story)
                .WithAnyTransition(playState, () => _stateSignal.Value is States.Play)
                .WithAnyTransition(pauseState, () => _stateSignal.Value is States.Pause)
                .WithAnyTransition(quitState, () => _stateSignal.Value is States.Quit)
                .WithId("StateMachine")
                .Build();
        }

        public override void Dispose()
        {
            _stateMachine?.Dispose();
        }
    }
}

With Event Signal, State can be controlled by another class.

Please see Event Driven for details.

Exceptions

On GetAsync or GetReadonlyAsync function, exceptions will be returned on errors.

Exception

Description

StateMachineNotFoundException

When State Machine is not found with given ID

StateNotFoundException

When State with wrong given value type

StateMachine.GetAsync("ID")
    .Then(OnGetStateMachine)
    .Catch<StateMachineNotFoundException>(OnNotFound)
    .Catch(Debug.LogError);

Best Practices

Always dispose of state machines when no longer needed
Use meaningful state names for better debugging
Implement transition conditions as pure functions
Utilize sub state machines for complex state hierarchies
Consider using system integration for performance-critical scenarios

PreviousSecurity (dev)NextChange Log

Last updated 1 month ago