Stingray.StateMachine 1.0.2

Stingray.StateMachine

A lightweight, framework-agnostic hierarchical state machine library for .NET 8.0+.

Features

• 🎯 Type-Safe: Uses C# types for state identification and transitions.
• 🔗 Decoupled: Zero dependencies. Works with any game engine or application.
• ⚡ Generic: Context-aware (IState<TContext>) for easy state sharing.
• 🎣 Event-Driven: Hooks for StateEntered, StateExited, StateTransitioned, and Completed.

Installation

Add the generic NuGet package to your project (ensure you have built/packed the solution):

dotnet add package Stingray.StateMachine

Usage

1. Define Your Context

The context is the shared data explicitly passed to your states. It must implement IContext.

using Stingray.StateMachine;

public class GameContext : IContext {
    public int PlayerId { get; set; }
    public bool IsGameOver { get; set; }
}

2. Define States

Implement IState<TContext>. Each method receives both the context and the state machine instance.

using Stingray.StateMachine;

public class IdleState : IState<GameContext> {
    public void Enter(GameContext context, StateMachine<GameContext> stateMachine) {
        Console.WriteLine("Entering Idle");
    }

    public StateResult<GameContext> Execute(GameContext context, StateMachine<GameContext> stateMachine) {
        if (context.IsGameOver) {
            return StateResult<GameContext>.Complete();
        }

        // Transition to another state by type
        return StateResult<GameContext>.TransitionTo<PlayState>();
    }

    public void Exit(GameContext context, StateMachine<GameContext> stateMachine) {
        Console.WriteLine("Exiting Idle");
    }
}

public class PlayState : IState<GameContext> { ... }

3. Setup and Run

var context = new GameContext();
var fsm = new StateMachine<GameContext>();

// Register states
fsm.AddState(new IdleState())
   .AddState(new PlayState());

// Set entry point
fsm.SetInitialState<IdleState>();

// Start
fsm.Start(context);

// Update loop (e.g., in your game loop)
while (fsm.IsRunning) {
    fsm.Step(context);
}

API Reference

StateMachine<TContext>

• AddState(IState<T> state): Registers a state instance.
• SetInitialState<TState>(): Sets the starting state.
• Start(TContext context): Enters the initial state.
• Step(TContext context): Executes the current state's logic. Returns true if completed.
• TransitionTo<TState>(TContext context): Forcefully transitions to a state.

StateResult<TContext>

• Continue(): Stay in current state.
• TransitionTo<TState>(): Switch to a new state.
• Complete(): End the state machine execution.

License

MIT