Stingray.StateMachine.Godot 1.0.5

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.
• ⚡ Generic: Context-aware (IState<TContext>) for easy state sharing.
• 🎣 Event-Driven: Hooks for StateEntered, StateExited, StateTransitioned, and Completed.
• 🎮 Godot-Friendly: Optional TransitionToScene that loads scenes by type name.

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. When used with Godot, your state classes should be Nodes (scenes) so the current scene can be cast to IState<TContext>.

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>();

// Build the scene index once at startup (Godot only).
// A good place is an Autoload singleton or the main scene's _Ready().
ScenePathIndex.Build();

// Register states
fsm.AddState<IdleState>()
   .AddState<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);
}

Godot Example (TransitionToScene)

public partial class IdleState : Node, IState<GameContext> {
    public void Enter(GameContext context, StateMachine<GameContext> stateMachine) {
        // ...
    }

    public StateResult<GameContext> Execute(GameContext context, StateMachine<GameContext> stateMachine) {
        return StateResult<GameContext>.TransitionTo<PlayState>();
    }

    public void Exit(GameContext context, StateMachine<GameContext> stateMachine) {
        // ...
    }
}

public partial class PlayState : Node, IState<GameContext> {
    public void Enter(GameContext context, StateMachine<GameContext> stateMachine) { }
    public StateResult<GameContext> Execute(GameContext context, StateMachine<GameContext> stateMachine) {
        // Load a new scene by type name
        stateMachine.TransitionToScene<RewardSelectionScene>(context);
        return StateResult<GameContext>.Continue();
    }
    public void Exit(GameContext context, StateMachine<GameContext> stateMachine) { }
}

Godot Scene Convention

TransitionToScene resolves scene files by class name. The .tscn file name must match the state class name:

• RewardSelectionScene → res://Any/Folder/RewardSelectionScene.tscn

Scene names must be unique across the project. The index will throw a clear error on duplicates.

Godot Notes

• ScenePathIndex.Build() throws if two .tscn files share the same name.
• If a matching scene file is not found, TransitionToScene throws and tells you the expected file name.

API Reference

StateMachine<TContext>

• AddState(IState<T> state): Registers a state type from an instance (instance is not stored).
• AddState(Type stateType): Registers a state by type.
• AddState<TState>(): Registers a state by type with compile-time checking.
• 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.
• TransitionToScene<TState>(TContext context): Transitions to a state and attempts to change a Godot scene using ScenePathIndex.
• SceneEnterRetryLimit: Number of frames to retry waiting for CurrentScene after TransitionToScene. Default is 60 (retries continue even if the limit is exceeded).

ScenePathIndex

• Build(): Scans res:// for .tscn files using Godot's APIs and builds a name-to-path index.

StateResult<TContext>

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

License

MIT