TheSingularityWorkshop.FSM_API 1.0.13

FSM_API

Join the CoderLegion Community

💖 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:

High-Performance Stress Testing & Benchmarks The FSM API is built for scale. Our initial baseline stress tests demonstrate the capacity to handle over 240,000 active agents at playable framerates (>30 FPS) using standard time-slicing techniques.

We are currently optimizing our backend lookup architecture, moving from string-based identifiers to a hash-based system. This change is anticipated to significantly reduce memory allocation overhead and CPU cycles per logic operation.

View the full Benchmark Report & Optimization Roadmap here

: Benchmark Report & Roadmap

🚀 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.

<a href="https://www.patreon.com/TheSingularityWorkshop" target="_blank"> <img src="Branding/TheSingularityWorkshop.png" alt="Support The Singularity Workshop on Patreon" height="200" style="display: block;"> </a>

Because state shouldn’t be a mess.

Support the project: Donate via PayPal