🎮 Unity Generic State Machine System

A flexible, modular, and easy-to-use state machine system for Unity that works with any enum-based state structure.

✨ Features

• 🔄 Fully Generic - Works with any enum type
• 🎯 Type-Safe - Compile-time type checking for states
• 🔗 Fluent API - Chain methods for easy setup
• ⚡ Three Callback Types - OnEnter, OnExit, and OnUpdate
• 📡 Event System - Subscribe to state transitions
• 🧩 Modular Design - Reusable across any game object or system
• 🛠️ Unity Integration - Seamless MonoBehaviour integration
• 🧪 Test Tools Included - Ready-to-use testing utilities

📦 Installation

1. Copy the following files to your Unity project:

   • StateMachine.cs → Core state machine logic
   • CharacterStateManager.cs → Example implementation
   • CharacterStateTester.cs → Testing utility

2. Place them in your project's scripts folder (e.g., Assets/_Project/Scripts/)

🚀 Quick Start

1. Define Your States

public enum CharacterState
{
    Idle,
    Walking,
    Running,
    Jumping
}

2. Create Your State Manager

using UnityEngine;

public class CharacterController : MonoBehaviour
{
    private StateMachine<CharacterState> stateMachine;

    private void Awake()
    {
        // Initialize with default state
        stateMachine = new StateMachine<CharacterState>(CharacterState.Idle);

        // Register states with callbacks
        stateMachine.RegisterState(CharacterState.Idle)
            .OnEnter(() => Debug.Log("Character is now idle"))
            .OnExit(() => Debug.Log("Character stopped being idle"))
            .OnUpdate(() => CheckForInput());

        stateMachine.RegisterState(CharacterState.Walking)
            .OnEnter(() => StartWalkAnimation())
            .OnUpdate(() => MoveCharacter(walkSpeed));

        stateMachine.RegisterState(CharacterState.Running)
            .OnEnter(() => StartRunAnimation())
            .OnUpdate(() => MoveCharacter(runSpeed));
    }

    private void Update()
    {
        // Update current state
        stateMachine.UpdateState();
    }

    // Change state from anywhere
    public void StartWalking()
    {
        stateMachine.ChangeState(CharacterState.Walking);
    }
}

3. Use State Queries

// Check single state
if (stateMachine.IsInState(CharacterState.Idle))
{
    // Do something
}

// Check multiple states
if (stateMachine.IsInAnyState(CharacterState.Walking, CharacterState.Running))
{
    // Character is moving
}

// Access current state
CharacterState current = stateMachine.CurrentState;
CharacterState previous = stateMachine.PreviousState;

📚 API Reference

StateMachine

Constructor

StateMachine<TState>(TState initialState)

Properties

• CurrentState - Get the current active state
• PreviousState - Get the last active state

Methods

• RegisterState(TState state) - Register a state and return a StateNode for configuration
• ChangeState(TState newState, bool force = false) - Transition to a new state
• UpdateState() - Update the current state (call in Update/FixedUpdate)
• IsInState(TState state) - Check if currently in a specific state
• IsInAnyState(params TState[] states) - Check if in any of the provided states

Events

• OnStateChanged - Triggered when state changes (provides previous and new state)

StateNode

Fluent API methods for configuring state callbacks:

RegisterState(MyState.Example)
    .OnEnter(() => { /* Called once when entering state */ })
    .OnExit(() => { /* Called once when exiting state */ })
    .OnUpdate(() => { /* Called every frame while in state */ });

🎯 Usage Examples

Example 1: AI Enemy States

public enum EnemyState { Idle, Patrol, Chase, Attack, Dead }

public class EnemyAI : MonoBehaviour
{
    private StateMachine<EnemyState> ai;
    private Transform player;

    private void Awake()
    {
        ai = new StateMachine<EnemyState>(EnemyState.Idle);

        ai.RegisterState(EnemyState.Patrol)
            .OnEnter(() => SetRandomPatrolPoint())
            .OnUpdate(() => PatrolBehavior());

        ai.RegisterState(EnemyState.Chase)
            .OnEnter(() => audioSource.Play(chaseSound))
            .OnUpdate(() => ChasePlayer())
            .OnExit(() => audioSource.Stop());

        ai.RegisterState(EnemyState.Attack)
            .OnEnter(() => animator.SetTrigger("Attack"))
            .OnUpdate(() => AttackBehavior());
    }

    private void Update()
    {
        ai.UpdateState();

        // State transition logic
        if (ai.IsInState(EnemyState.Patrol) && PlayerInRange())
        {
            ai.ChangeState(EnemyState.Chase);
        }
    }
}

Example 2: UI Menu System

public enum MenuState { MainMenu, Settings, Gameplay, Paused }

public class MenuManager : MonoBehaviour
{
    private StateMachine<MenuState> menu;

    private void Awake()
    {
        menu = new StateMachine<MenuState>(MenuState.MainMenu);

        menu.RegisterState(MenuState.MainMenu)
            .OnEnter(() => ShowPanel(mainMenuPanel))
            .OnExit(() => HidePanel(mainMenuPanel));

        menu.RegisterState(MenuState.Settings)
            .OnEnter(() => ShowPanel(settingsPanel))
            .OnExit(() => HidePanel(settingsPanel));

        menu.RegisterState(MenuState.Gameplay)
            .OnEnter(() => Time.timeScale = 1f)
            .OnUpdate(() => CheckForPause());

        menu.RegisterState(MenuState.Paused)
            .OnEnter(() => {
                Time.timeScale = 0f;
                ShowPanel(pausePanel);
            })
            .OnExit(() => Time.timeScale = 1f);
    }
}

Example 3: Vehicle System

public enum VehicleState { Parked, Driving, Crashed, Repairing }

public class VehicleController : MonoBehaviour
{
    private StateMachine<VehicleState> vehicle;

    private void Awake()
    {
        vehicle = new StateMachine<VehicleState>(VehicleState.Parked);

        vehicle.OnStateChanged += (from, to) => 
        {
            Debug.Log($"Vehicle: {from} → {to}");
        };

        vehicle.RegisterState(VehicleState.Driving)
            .OnEnter(() => StartEngine())
            .OnUpdate(() => HandleDriving())
            .OnExit(() => StopEngine());

        vehicle.RegisterState(VehicleState.Crashed)
            .OnEnter(() => {
                DisableControls();
                SpawnSmokeEffect();
            });
    }
}

🧪 Testing

The system includes a comprehensive testing utility:

1. Add CharacterStateTester component to your GameObject
2. Reference your state machine manager
3. Use multiple test methods:

Testing Methods

• 🎮 In-Game UI - Click buttons during play mode
• ⌨️ Keyboard Shortcuts - 1-4 for states, Space to cycle
• 🔍 Inspector Context Menu - Right-click component for manual controls
• ⏰ Auto Test Mode - Enable automatic state cycling

Keyboard Shortcuts

1 - Go to first state
2 - Go to second state
3 - Go to third state
4 - Go to fourth state
Space - Cycle through states

🏗️ Architecture

StateMachine<TState>
├── StateNode (per state)
│   ├── OnEnter (Action)
│   ├── OnExit (Action)
│   └── OnUpdate (Action)
├── CurrentState (TState)
├── PreviousState (TState)
└── OnStateChanged (Event)

💡 Best Practices

1. Initialize in Awake - Set up state machine before other components need it
2. Call UpdateState() - Don't forget to call this in Update/FixedUpdate
3. Use Events - Subscribe to OnStateChanged for global state tracking
4. Validate Transitions - Check current state before changing
5. Clean Callbacks - Keep OnEnter/OnExit/OnUpdate methods focused and small

⚠️ Important Notes

• State changes during OnEnter or OnExit callbacks are supported but use carefully
• UpdateState() must be called manually in your Update loop
• Changing to the same state does nothing (unless force = true)
• All callbacks are optional - register only what you need

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is available under the MIT License.

🙏 Credits

Designed for modular and scalable Unity game development.

---

📞 Support

If you encounter any issues or have questions, please open an issue on GitHub.

Made with ❤️ for the Unity community