StateMachineBuddy 5.0.5

StateMachineBuddy

A finite state machine library for .NET and MonoGame projects. Define states and messages, configure transitions between states, send messages to trigger transitions, and subscribe to events when state changes occur.

Installation

Install via NuGet:

dotnet add package StateMachineBuddy

NuGet Package: StateMachineBuddy Version: 5.0.2 Target Framework: .NET 8.0 License: MIT

Dependencies

• MonoGame.Framework.DesktopGL (3.8.*)
• FilenameBuddy (5.*)
• XmlBuddy (5.*)

Overview

StateMachineBuddy provides three state machine implementations:

Core Concepts

• State: A discrete condition the machine can be in
• Message: An input that may trigger a state transition
• Transition: A rule defining: when in state X and receiving message Y, move to state Z
• Initial State: The starting state of the machine

Quick Start

Using EnumStateMachine (Recommended)

using StateMachineBuddy;

// Define your states and messages as enums
public enum PlayerState { Idle, Walking, Running, Jumping }
public enum PlayerMessage { Walk, Run, Jump, Stop, Land }

// Create the state machine
var fsm = new EnumStateMachine<PlayerState, PlayerMessage>(PlayerState.Idle);

// Define transitions
fsm.Set(PlayerState.Idle, PlayerMessage.Walk, PlayerState.Walking);
fsm.Set(PlayerState.Idle, PlayerMessage.Run, PlayerState.Running);
fsm.Set(PlayerState.Idle, PlayerMessage.Jump, PlayerState.Jumping);
fsm.Set(PlayerState.Walking, PlayerMessage.Stop, PlayerState.Idle);
fsm.Set(PlayerState.Walking, PlayerMessage.Run, PlayerState.Running);
fsm.Set(PlayerState.Running, PlayerMessage.Stop, PlayerState.Idle);
fsm.Set(PlayerState.Jumping, PlayerMessage.Land, PlayerState.Idle);

// Subscribe to state changes
fsm.StateChangedEvent += (sender, args) =>
{
    Console.WriteLine($"State changed from {args.OldState} to {args.NewState}");
};

// Send messages to trigger transitions
fsm.SendStateMessage("Walk");  // Transitions from Idle to Walking
fsm.SendStateMessage("Run");   // Transitions from Walking to Running
fsm.SendStateMessage("Stop");  // Transitions from Running to Idle

Using IntStateMachine (Performance-Optimized)

using StateMachineBuddy;

public enum GameState { Menu, Playing, Paused, GameOver }
public enum GameMessage { Start, Pause, Resume, Die, Restart }

var fsm = new IntStateMachine();

// Initialize with enum types
fsm.Set(typeof(GameState), typeof(GameMessage), (int)GameState.Menu);

// Define transitions using integer indices
fsm.SetEntry((int)GameState.Menu, (int)GameMessage.Start, (int)GameState.Playing);
fsm.SetEntry((int)GameState.Playing, (int)GameMessage.Pause, (int)GameState.Paused);
fsm.SetEntry((int)GameState.Playing, (int)GameMessage.Die, (int)GameState.GameOver);
fsm.SetEntry((int)GameState.Paused, (int)GameMessage.Resume, (int)GameState.Playing);
fsm.SetEntry((int)GameState.GameOver, (int)GameMessage.Restart, (int)GameState.Menu);

// Subscribe to state changes
fsm.StateChangedEvent += (sender, args) =>
{
    Console.WriteLine($"Changed from {fsm.GetStateName(args.OldState)} to {fsm.GetStateName(args.NewState)}");
};

// Send messages
fsm.SendStateMessage((int)GameMessage.Start);  // Menu -> Playing

Using StringStateMachine

using StateMachineBuddy;

var fsm = new StringStateMachine();

// Add states and messages
fsm.AddStates(new[] { "idle", "active", "complete" });
fsm.AddMessages(new[] { "activate", "finish", "reset" });
fsm.SetInitialState("idle");

// Define transitions
fsm.Set("idle", "activate", "active");
fsm.Set("active", "finish", "complete");
fsm.Set("complete", "reset", "idle");

// Subscribe to state changes
fsm.StateChangedEvent += (sender, args) =>
{
    Console.WriteLine($"Changed from {args.OldState} to {args.NewState}");
};

// Send messages
fsm.SendStateMessage("activate");  // idle -> active

API Reference

IntStateMachine

High-performance state machine using integer indices internally stored in a 2D array.

Properties

Events

Initialization Methods

Runtime Methods

Lookup Methods

File I/O

StringStateMachine

Flexible state machine using string-based states and messages.

Properties

Events

Initialization Methods

Runtime Methods

File I/O

EnumStateMachine<TState, TMessage>

Type-safe wrapper around StringStateMachine for enum-based states and messages. Inherits from StringStateMachine.

Constructor

EnumStateMachine(TState initialState)

Methods

Inherits all properties, events, and methods from StringStateMachine. Use string versions of enum names when calling inherited methods like SendStateMessage("EnumValueName").

StateChangeEventArgs<T>

Event arguments passed to state change events.

State

Internal class representing a state and its transitions.

XML Configuration

State machines can be loaded from XML files using the MonoGame content pipeline.

XML Schema

<StateMachine initial="InitialStateName">
  <states>
    <state name="State1" />
    <state name="State2" />
    <state name="State3" />
  </states>
  <messages>
    <message name="Message1" />
    <message name="Message2" />
  </messages>
  <stateChanges>
    <state name="State1">
      <transitions>
        <transition message="Message1" state="State2" />
        <transition message="Message2" state="State3" />
      </transitions>
    </state>
    <state name="State2">
      <transitions>
        <transition message="Message1" state="State3" />
      </transitions>
    </state>
  </stateChanges>
</StateMachine>

Loading XML

var fsm = new StringStateMachine();
fsm.LoadXml(new Filename("path/to/statemachine.xml"), contentManager);

Model Classes

For programmatic construction or serialization:

StateMachineModel

StateModel

StateChangeModel

Behavior Notes

1. No transition defined: If no transition exists for the current state + message combination, SendStateMessage returns false and the state remains unchanged.

2. Self-transitions ignored: If a transition would result in the same state, no state change occurs and SendStateMessage returns false.

3. ForceState: Bypasses the transition table and directly sets the state. Fires StateChangedEvent if the state actually changes.

4. Invalid states/messages: Set() throws exceptions if states or messages haven't been added first.

5. Reset behavior: ResetToInitialState() fires ResetEvent instead of StateChangedEvent.

Project Structure

StateMachineBuddy/
├── IntStateMachine.cs       # Performance-optimized integer-based FSM
├── StringStateMachine.cs    # Flexible string-based FSM
├── EnumStateMachine.cs      # Type-safe enum wrapper
├── State.cs                 # State with transitions dictionary
├── StateChangeEventArgs.cs  # Event args for state changes
└── Models/
    ├── StateMachineModel.cs   # XML serialization model
    ├── StateModel.cs          # State definition model
    └── StateChangeModel.cs    # Transition definition model

Repository

GitHub: https://github.com/dmanning23/StateMachine

License

MIT License