TheSingularityWorkshop.FSM_API 1.0.9

FSM_API

💖 Support Us

Blazing-fast, software-agnostic Finite State Machine system for any C# application.

🔍 Overview

FSM_API is a modular, runtime-safe, and fully event-aware Finite State Machine (FSM) system designed to plug directly into any C# application from enterprise software to games, simulations, robotics, or reactive systems. It provides a powerful and decoupled approach to managing complex state-driven logic, ensuring clarity, consistency, and control across diverse domains.

✅ Thread-safe operations (main thread only, deferred mutation handling)
🧠 Decoupled state logic from data (POCO-friendly)
🏗️ Define once, instantiate many
🛠️ Error-tolerant FSM lifecycle management
🧪 Dynamic update ticking with frame/process throttling

No external dependencies. No frameworks required. No boilerplate setup. Pure C# power.

💡 Why FSM_API?

Traditional FSM systems often suffer from tight coupling to specific environments or force rigid coding patterns. FSM_API liberates your state management:

🚀 Quickstart

1. Define a simple context (your data model):

public class LightSwitch : IStateContext
{
    public bool IsOn = false;
    public bool IsValid => true; // Essential for FSM validation
    public string Name { get; set; } = "KitchenLight";
}

2. Define and build your FSM:

FSM_API.CreateProcessingGroup("MainLoop");

// Define the condition for the transition from "Off" to "On".
Func<IStateContext, bool> shouldTurnOn = ctx =>
{
    if (ctx is LightSwitch l)
    {
        return l.IsOn;
    }
    return false;
};

// Define the condition for the transition from "On" to "Off".
Func<IStateContext, bool> shouldTurnOff = ctx =>
{
    if (ctx is LightSwitch l)
    {
        return !l.IsOn;
    }
    return false;
};

// Use the fluent API to create and define the FSM.
// The .BuildDefinition() call finalizes the blueprint.
FSM_API.Create.CreateFiniteStateMachine("LightSwitchFSM", processRate: 1, processingGroup: "MainLoop")
    // Define the "Off" state and its OnEnter action.
    .State("Off", 
        onEnter: ctx => { if (ctx is LightSwitch l) l.IsOn = false; },
        onUpdate: null, 
        onExit: null)
    // Define the "On" state and its OnEnter action.
    .State("On", 
        onEnter: ctx => { if (ctx is LightSwitch l) l.IsOn = true; },
        onUpdate: null,
        onExit: null)
    .WithInitialState("Off") // Set the starting state.
    // Define the transitions using the condition functions.
    .Transition("Off", "On", shouldTurnOn)
    .Transition("On", "Off", shouldTurnOff)
    .BuildDefinition();

3. Create an instance:

var kitchenLight = new LightSwitch();
var handle = FSM_API.Create.CreateInstance("LightSwitchFSM", kitchenLight, "MainLoop");

4. Tick the FSM:

FSM_API.Interaction.Update("MainLoop");

🔧 Core Concepts

• FSMBuilder → fluently define states, transitions, and actions
• FSMHandle → runtime instance control (pause, reset, query state)
• IStateContext → implement for your domain objects (POCOs)
• Processing Groups → organize FSM ticking (UI, AI, physics, etc.)
• Error Handling → thresholds & diagnostics built-in
• Thread Safety → deferred mutation model keeps concurrency safe

📦 Features at a Glance

📘 What’s Next?

• 📖 Full Documentation & Wiki (TBD)
• 🧪 Unit Tests & Benchmarks (in development)
• 🔌 Plugins & Extension Framework (e.g., editors, debugging)

🤝 Contributing

PRs, issues, and extensions welcome! Let’s build smarter state logic together.

📄 License

MIT License – use it, hack it, build amazing things with it.

🧠 Brought to you by

The Singularity Workshop – Tools for the curious, the bold, and the systemically inclined.

<img src="FSM_API/Assets/TheSingularityWorkshop.png" alt="The Singularity Workshop" width="200" height="200">

Because state shouldn’t be a mess.

Support the project: Donate via PayPal