uw-state-machine

State Machine

Interface-based state machines for game flow, characters, and UI.

Before You Start

1. Read docs/ProjectConfig.yaml for:
   • architecture_pattern — "so-first" or "di-first" (affects how states and the StateMachine are created and wired).
   • mcp.unity_mcp — if true, call refresh_unity after creating files.
2. Read docs/CODING_STANDARDS.md for async patterns (Awaitable + CancellationToken) — state transitions are async.
3. Ensure the feature has an .asmdef — create with uw-unity-feature-scaffold if needed.

Core Interface

public interface IState
{
    Awaitable Enter(CancellationToken ct);
    Awaitable Exit(CancellationToken ct);
}

For states that need per-frame updates (character movement, AI ticking), extend with:

public interface IUpdatableState : IState
{
    void Update();
}

State Machine Service

Only one state is active at a time. Transitions are async to support loading screens, animations, and cleanup between states.

public class StateMachine
{
    private IState _currentState;

    public IState CurrentState => _currentState;

    public async Awaitable TransitionTo(IState newState, CancellationToken ct)
    {
        if (_currentState != null)
            await _currentState.Exit(ct);

        _currentState = newState;
        await _currentState.Enter(ct);
    }
}

If the current state implements IUpdatableState, the owner (a MonoBehaviour or update service) should call Update() each frame:

private void Update()
{
    if (_stateMachine.CurrentState is IUpdatableState updatable)
        updatable.Update();
}

CancellationToken Lifecycle

States receive a CancellationToken in Enter and Exit. This token controls the lifetime of async work within that state — when the token cancels, any in-flight awaits should stop cleanly.

Where tokens come from:

// Per-scene token — cancels when the scene unloads
private CancellationTokenSource _sceneCts;

private void OnEnable()
{
    _sceneCts = CancellationTokenSource.CreateLinkedTokenSource(
        Application.exitCancellationToken);
}

private void OnDisable()
{
    _sceneCts?.Cancel();
    _sceneCts?.Dispose();
}