UniState State Machine for Unity

A State is an abstraction representing a specific condition or phase of a game (e.g., MainMenuView, GameplayState, or GameLoadingState).

Key characteristics:

• Logic Ownership: A state class contains all logic related to that phase, including loading and unloading resources.
• Lifecycle: States are responsible for their own resource allocation. Once a state is exited, all allocated resources should be released using the Disposables system.
• Decoupling: It is recommended to avoid using Unity GameObjects directly inside states. Instead, load them through an abstraction and use them as an interface (a 'View').
• Flexibility: UniState does not restrict your architectural patterns; you can use MVC, MVVM, or ECS within a state.

// Simple popup state example
public class SimplePopupState : StateBase
{
    private ISimplePopupView _view;

    public override async UniTask Initialize(CancellationToken token) 
    {
        _view = LoadPopupView(token);
        Disposables.Add(UnloadPopupView);
    }

    public override async UniTask<StateTransitionInfo> Execute(CancellationToken token)
    {
        await _view.Show(token);
        await _view.WaitForClick(token);

        return Transition.GoBack();
    }
    
    public override async UniTask Exit(CancellationToken token)
    {
        await _view.Hide(token);
    }

    private ISimplePopupView LoadPopupView(CancellationToken token) { /* Loading logic */ }
    private void UnloadPopupView() { /* Unloading logic */ }
}

When a state represents a complex feature (like a Shop) that has its own internal logic and sub-states, use a nested StateMachine.

Pattern:

1. The Root State loads the shared resources (e.g., the Shop View) and adds them to its Disposables.
2. The Root State then creates and executes a child StateMachine.
3. The Child States within that machine can access the resources loaded by the Root State (e.g., via Dependency Injection).
4. When the child machine finishes, the Root State completes and releases the shared resources.

public class RootShopPopupState : StateBase
{
    public override async UniTask Initialize(CancellationToken token) 
    {
        var disposable = LoadShopView();
        Disposables.Add(disposable);
    }

    public override async UniTask<StateTransitionInfo> Execute(CancellationToken token)
    {
        var stateMachine = StateMachineFactory.Create<StateMachine>();
        // Run the internal state machine for ShopPopup.
        await stateMachine.Execute<ShopPopupIdleState>(token);

        return Transition.GoBack();
    }
    
    private IDisposable LoadShopView() { /* Loading logic */ }
}

public class ShopPopupIdleState : StateBase
{
    private IShopView _view;
    
    // IShopView is injected by the DI framework, loaded by the parent RootShopPopupState
    public ShopPopupIdleState(IShopView view)
    {
         _view = view;
    }

    public override async UniTask<StateTransitionInfo> Execute(CancellationToken token)
    {
        await _view.Show(token);
        return Transition.GoBack();
    }
}

Composite States allow multiple independent sub-states to run simultaneously within a single parent state. This is useful for complex UI or parallel logic.

• Composite State: Inherit from CompositeStateBase or DefaultCompositeState.
• SubState: Inherit from SubStateBase<TParentCompositeState>. Sub-states are linked to the parent via the generic parameter.
• DefaultCompositeState: A ready-to-use implementation that propagates lifecycle methods to all sub-states. The composite state completes when the first sub-state finishes, then cancels the remaining sub-states.

Note: If using DefaultCompositeState without any sub-states, it will throw NoSubStatesException.

// Composite State implementation
internal class FooCompositeState : DefaultCompositeState { }

// SubState implementation
internal class BazSubState : SubStateBase<DefaultCompositeState> { }

To get started with UniState, follow these four steps:

1. Install the package via UPM or manifest.json.
2. Create States: Define classes inheriting from StateBase or StateBase<T>. Use the Execute method to implement logic and return a StateTransitionInfo to handle transitions.
3. Configure DI: Register the state machine and your states in your Dependency Injection container (e.g., VContainer, Zenject, or Reflex).
4. Run: Resolve the IStateMachine interface and call .Execute<TState>(CancellationToken.None) to start the machine.

// 1. Define States
public class MainMenuState : StateBase
{
    public override async UniTask<StateTransitionInfo> Execute(CancellationToken token)
    {
        return Transition.GoTo<GameplayState>();
    }
}

public class GameplayState : StateBase
{
    public override async UniTask<StateTransitionInfo> Execute(CancellationToken token)
    {
        return Transition.GoBack();
    }
}

// 2. Register in DI (Example using VContainer-style syntax)
builder.RegisterStateMachine<IStateMachine, StateMachine>();
builder.RegisterState<MainMenuState>();
builder.RegisterState<GameplayState>();

// 3. Run the State Machine
public class Game
{
    private readonly IStateMachine _stateMachine;

    public Game(IStateMachine stateMachine)
    {
        _stateMachine = stateMachine;
    }

    public void Start()
    {
        _stateMachine.Execute<MainMenuState>(CancellationToken.None).Forget();
    }
}

UniState supports Zenject/Extenject via extension methods on the DiContainer.

Preparation

If Zenject/Extenject is installed via UPM, no preparation is needed. If installed manually, add the UNISTATE_ZENJECT_SUPPORT define symbol in Player Settings -> Player -> Scripting Define Symbols.

Registration

Use the extension methods to bind state machines and states. Use the AsSingle variants for singleton lifetimes, though standard bindings are preferred for general use.

Usage

Resolve the IStateMachine from the container and call Execute.

// Registration
private void BindStates(DiContainer container)
{
    // General use
    container.BindStateMachine<IStateMachine, BarStateMachine>();
    container.BindState<BarState>();
    container.BindState<IBarState, BarState>();
    
    // Singleton version
    container.BindStateMachineAsSingle<IStateMachine, BarStateMachine>();
    container.BindStateAsSingle<BarState>();
    container.BindStateAsSingle<IBarState, BarState>();
}

// Usage
public class GameEntryPoint : IStartable
{
    private readonly IStateMachine _stateMachine;

    public GameEntryPoint(IStateMachine stateMachine)
    {
        _stateMachine = stateMachine;
    }

    public void Start()
    {
        _stateMachine.Execute<StartGameState>(CancellationToken.None).Forget();
    }
}

UniState provides extension methods for Reflex's ContainerBuilder.

Preparation

If Reflex is installed via UPM, no preparation is needed. If installed manually, add the UNISTATE_REFLEX_SUPPORT define symbol in Player Settings -> Player -> Scripting Define Symbols.

Registration

Use RegisterStateMachine and RegisterState on the ContainerBuilder.

• RegisterState(typeof(MyState)) registers the state as itself and all its implemented interfaces.
• Use the two-parameter overload to explicitly expose an additional abstract/base contract.
• Use Lifetime.Singleton when a singleton lifetime is required.

Usage

Resolve the IStateMachine from the Reflex container and call Execute.

// Registration
private void RegisterStates(ContainerBuilder builder)
{
    // Recommended usage
    builder.RegisterStateMachine(typeof(StateMachine), typeof(IStateMachine));
    builder.RegisterState(typeof(BarState));
    builder.RegisterState(typeof(BarState), typeof(BarBaseState));
    
    // Singleton version (use cautiously)
    builder.RegisterStateMachine(typeof(StateMachine), typeof(IStateMachine), Lifetime.Singleton);
    builder.RegisterState(typeof(BarState), Lifetime.Singleton);
    builder.RegisterState(typeof(BarState), typeof(BarBaseState), Lifetime.Singleton);
}

// Usage
public class DiceEntryPoint
{
    private readonly IStateMachine _stateMachine;
    public DiceEntryPoint(IStateMachine stateMachine) => _stateMachine = stateMachine;

    public void Start()
    {
        _stateMachine.Execute<StartGameState>(CancellationToken.None).Forget();
    }
}

To define logic in UniState, inherit from StateBase and override the Execute method. The Execute method must return a UniTask<StateTransitionInfo>, which determines the next step in the workflow using the Transition helper.

Common transition types include:

• Transition.GoTo<TState>(): Moves to a specific state class.
• Transition.GoBack(): Returns to the previous state in the stack.
• Transition.GoToExit(): Terminates the state machine.

Example workflow:

1. Define states inheriting from StateBase.
2. Use Transition to drive flow (e.g., GoTo<NextState>()).
3. Handle asynchronous operations using the provided CancellationToken.

internal class StartGameState : StateBase
{
    public override async UniTask<StateTransitionInfo> Execute(CancellationToken token)
    {
        // Perform logic
        await UniTask.Delay(TimeSpan.FromSeconds(2), cancellationToken: token);
        
        // Transition to the next state
        return Transition.GoTo<RollDiceState>();
    }
}