StateMachine

Package: com.amanotes.statemachine
Version: 1.0.0

Generic type-safe state machine for Unity with enum-based states and transition validation.

Features

• 🎮 Type-safe state management with generics
• 🎯 Automatic transition validation
• 🎨 Enter/Exit callbacks per state
• 🚀 Fluent API for state registration
• 🔧 State change event notifications

Documentation

Complete API inline in this README (mini-package: 2 classes).

Installation

Add the package to your Unity project via Packages/manifest.json:

{
  "dependencies": {
    "com.amanotes.statemachine": "1.0.0"
  },
  "scopedRegistries": [
    {
      "name": "npmjs",
      "url": "https://registry.npmjs.org/",
      "scopes": [
        "com.amanotes.statemachine"
      ]
    }
  ]
}

Quick Start

public enum GameState { Menu, Playing, Paused }

public class GameStateMachine : StateMachine<GameState>
{
    public GameStateMachine() : base(GameState.Menu)
    {
        RegisterState(GameState.Menu)
            .WithTransitionTo(GameState.Playing);
        
        RegisterState(GameState.Playing)
            .WithTransitionTo(GameState.Paused);
        
        RegisterState(GameState.Paused)
            .WithTransitionTo(GameState.Playing);
    }
}

var sm = new GameStateMachine();
sm.OnEnter(GameState.Playing, () => Debug.Log("Game started"));
sm.Reset();
sm.TransitionTo(GameState.Playing);

API Reference

Key Classes

StateMachine

• Purpose: Generic state machine with transition validation
• Key methods: RegisterState(), TransitionTo(), OnEnter(), OnExit()
• Key properties: CurrentState, PreviousState, IsStarted

StateInfo

• Purpose: State metadata and transition builder
• Key methods: WithTransitionTo()

StateMachine

Properties:

• TKey CurrentState - Current active state
• TKey PreviousState - Previously active state
• bool IsStarted - Whether state machine has been started
• string CurrentStateName - Name of current state
• Action<TKey, TKey> OnStateChanged - Event fired on state transitions

Lifecycle:

• StateMachine() - Constructor without initial state
• StateMachine(TKey initialState) - Constructor with initial state
• void Start(TKey state) - Start state machine at specific state
• void Reset() - Reset to initial state (if provided)
• bool TransitionTo(TKey key) - Transition to new state (validates transition)
• void Clear() - Clear current state without resetting

Registration:

• StateInfo<TKey> RegisterState(TKey key, string name = null) - Register state
• void AddTransition(TKey from, TKey to) - Add valid transition

Callbacks:

• void OnEnter(TKey key, Action callback) - Add enter callback
• void OnExit(TKey key, Action callback) - Add exit callback
• void RemoveOnEnter(TKey key, Action callback) - Remove enter callback
• void RemoveOnExit(TKey key, Action callback) - Remove exit callback
• void AddOnStateChanged(Action<TKey, TKey> callback) - Add state change listener

Queries:

• bool IsState(TKey key) - Check if currently in state
• bool HasState(TKey key) - Check if state is registered
• string GetStateName(TKey key) - Get state name

StateInfo

Properties:

• TKey Key - State key
• int Id - Internal state ID
• string Name - State name
• Action OnEnter - Enter callback
• Action OnExit - Exit callback
• StateMachine<TKey> StateMachine - Parent state machine

Methods:

• StateInfo<TKey> WithTransitionTo(TKey to) - Add transition (fluent API)

Dependencies

• Unity 2021.3+

Version History

See CHANGELOG.md