Coder Legion - Recent posts tagged c-sharp

Forging the Elements: A Deep Dive into Recursive Builders

Tue, 31 Mar 2026 00:29:33 +0000

Can you infer what the code below does just by glancing at it?

public VisualElement CreateGui(GuiContext ctx)
{
    var rootBuilder = new GraphicalUserInterfaceBuilder("PeriodicTableRoot")
        .WithAutoGrow()
        .WithFlexLayout(FlexDirection.Row)
        .WithBackgroundColor(new Color(0.08f, 0.08f, 0.1f));

    // --- LEFT PANEL: The Table ---
    var tablePanel = new GraphicalUserInterfaceBuilder("TableContainer")
        .WithFlexGrow(3)
        .WithPadding(15)
        .WithScrollable(true)
        .WithBorderRightWidth(2)
        .WithBorderRightColor(Color.black);

    tablePanel.AddHeader("THE SINGULARITY WORKSHOP: ELEMENTAL REPOSITORY", GuiSkin.Active.PrimaryAccent);

    // Generate the Grid
    tablePanel.AddChild(BuildPeriodicGrid());
    rootBuilder.AddChild(tablePanel);

    // --- RIGHT PANEL: The Inspector ---
    var inspectorPanel = new GraphicalUserInterfaceBuilder("InspectorContainer")
        .WithWidth(350)
        .WithPadding(15);

    inspectorPanel.AddHeader("THERMODYNAMIC INSPECTOR", Color.white);

    inspectorPanel.AddChild(context =>
    {
        _inspectorContainer = new GraphicalUserInterfaceBuilder("InspectorData").WithAutoGrow().Build();
        return _inspectorContainer;
    });

    rootBuilder.AddChild(inspectorPanel);

    RefreshInspector();
    return rootBuilder.Build();
}

If you guessed that it sets up a responsive, two-panel layout with a scrollable grid on the left and a data inspector on the right, you are correct. It reads almost like plain English.

This is the power of the Recursive Builder pattern.

We are looking at an interactive, fully functional Periodic Table of Elements.

Clicking on any element in this table doesn't just pull up static text. It dynamically generates the element's thermodynamic data alongside a live 3D view of the atom, complete with electron orbits and a clustered nucleus of protons and neutrons. See those gray + buttons? Those are empty slots. Click one, and you can synthesize entirely new materials. If you want to put Unobtanium or Vibranium on your table, the workshop will forge it.

But the real magic isn't just what was built; it's how it was built.

Realigning Your Thinking: The Recursive Builder Paradigm

Historically, building complex UIs in game engines or enterprise software has been an exercise in imperative state management. You instantiate an object, modify a dozen properties across ten lines of code, attach it to a parent, instantiate a child, modify its properties, attach it to the parent, and so on. It results in brittle, unreadable spaghetti code where the visual hierarchy is completely lost in the syntax.

Recursive builders demand a realignment in how you think about architecture.

1. Fluent Composition
Instead of modifying state line-by-line, we use a fluent interface (.WithAutoGrow().WithFlexLayout()). The builder acts as a staging area. It collects all your configurations and defers the actual instantiation of the VisualElement until the very end when .Build() is called.

2. Hierarchical (Recursive) Nesting
The real paradigm shift happens when builders consume other builders or return themselves recursively. Notice the .AddChild() methods. We aren't passing pre-built UI elements; we are passing nested build instructions—like BuildPeriodicGrid(). The code structure physically mirrors the UI tree structure.

3. Cognitive Unlocking
When you write UI code declaratively like this, your cognitive load drops massively. You stop thinking about how the engine applies a flex-grow property, and you start thinking purely in terms of architecture and layout. Once you build out your standard suite of custom builders (like GridGuiBuilder or GraphicalUserInterfaceBuilder), generating incredibly complex, interactive dashboards takes minutes, not days.

A Simple Threshold Implementation

Sat, 20 Dec 2025 05:45:14 +0000

One of the most common design patterns we utilize—so utilized that we often don't even recognize it as a pattern—is that of breaching a limit.

Think about your daily routine:

Are we within the index limits of this array?
Has the player’s health dropped to zero?
Did the mana pool exceed the "Overcharge" value?

While writing a simple if (current > limit) isn't exactly a high-level engineering challenge, the inherent risk of a "fat-finger" typo is real. We’ve all been there: Should this be greater than, or greater than or equal to? In a complex system, sticking the landing every time is harder than it looks. By moving to the FSM_Threshold Pattern, we accept a tiny bit of overhead in exchange for absolute stability. We stop "recalling" the logic and start relying on a state machine that we know works.

High-Speed Implementation: The Factory

The goal of this architecture is to make implementation so easy it feels like a native attribute. The ThresholdFactory hides the math and FSM registration, giving you a one-line setup for any type.

Use Case 1: The Magic Overcharge

Instead of manually checking mana every frame, define a threshold that monitors for a "Magic Burn" state.

// Define it once
var manaMonitor = ThresholdFactory.Create(
    "ManaOvercharge", 
    limit: 100f, 
    m: ThresholdMode.Max, 
    r: ResetMode.Automatic, 
    cb: (t) => CastExplosionEffect()
);

// Just feed the data
manaMonitor.Accumulate(spellCost);

Use Case 2: The Character Health

Whether it's an int or a float, the factory handles the numeric comparison logic for you.

var health = ThresholdFactory.Create("PlayerHealth", 0, ThresholdMode.Min, ResetMode.Manual, OnDeath);

// No more "if (hp <= 0)" scattered in your movement, combat, and fall-damage scripts.
health.Accumulate(-damage);

Deep Dive: Inside the FSM_Threshold

The power of this system lies in the FSM_Threshold<T> class. It doesn't just store a value; it implements IStateContext, allowing it to serve as the "data bag" for the underlying FSM.

The Core Logic

The class manages three key values: _currentValue, _threshold, and _initialValue. Because it is a generic class, it can handle any type that provides an accumulator (to add values) and a comparator (to check the limit).

When you instantiate a threshold, it registers a unique FSM blueprint based on the type name (e.g., Threshold_Single). This blueprint consists of two primary states:

Monitoring: The default state where we wait for a breach.
Breached: Entered via the CheckLimit() transition. Upon entry, it immediately invokes your callback.

The "Manual Reset" Hammer

One of the most elegant parts of the design is how it handles manual resets. In a standard FSM, you might wait for a transition to evaluate as true. To ensure the engine is responsive and stable, we use a "hammer" approach:

public void ManualReset()
{
    _currentValue = _initialValue; // Reset the data
    Status.TransitionTo("Monitoring"); // Force the state back immediately
}

By calling Status.TransitionTo("Monitoring"), we bypass the standard transition evaluation and force the state machine back to its starting point, ensuring the code that works is always the code that is running.

The Factory: Simplifying Complexity

The ThresholdFactory is what makes this system consumable. It pre-defines the math for common types so the developer doesn't have to.

For example, look at the byte creation:

public static FSM_Threshold<byte> Create(string n, byte lim, ThresholdMode m, ResetMode r, Action<FSM_Threshold<byte>> cb)
    => new FSM_Threshold<byte>(n, 0, lim, m, r, (c, d) => (byte)(c + d), (c, l) => m == ThresholdMode.Max ? c >= l : c <= l, cb);

The factory injects the specific math for a byte (including the necessary cast) and the logic for Max vs Min modes. This means you never have to worry about if you "stuck the landing" on the comparison logic—the factory already did.

By utilizing this pattern, you move away from fragile, scattered if statements and toward a centralized, event-driven architecture that is as easy to use as it is stable.

Resources & Code:

The FSM Package (Unity Asset Store):
https://assetstore.unity.com/packages/slug/332450

NuGet Package (Non-Unity Core):
https://www.nuget.org/packages/TheSingularityWorkshop.FSM_API

GitHub Repository:
https://github.com/TrentBest/FSM_API

Simple Demos Repository (Run the Stress Test):
https://github.com/TrentBest/SimpleDemos (Clone this repo and run the StressProfiler project to reproduce these numbers.)

Support Our Work:

Patreon Page:
https://www.patreon.com/c/TheSingularityWorkshop

Support Us (PayPal Donation):
https://www.paypal.com/donate/?hosted_button_id=3Z7263LCQMV9J

We'd love to hear your thoughts! Please Like this post, Love the code, and Share your feedback or what you've built with the API in the comments.

The Deterministic Engine: Why The Singularity Workshop’s FSM_API Redefines C# State Management

Thu, 20 Nov 2025 05:37:21 +0000

The Deterministic Engine: Why The Singularity Workshop’s FSM_API Redefines C# State Management

The Finite State Machine (FSM) is a foundational concept in computer science, acting as the deterministic heartbeat for everything from game AI to complex enterprise business logic. For C# developers, choosing the right FSM library is not just a preference; it’s an architectural decision that dictates a system's reliability, performance, and, crucially, its thread safety.

The Singularity Workshop, via its robust NuGet package (TheSingularityWorkshop.FSM_API) and transparent GitHub repository (TrentBest/FSM_API) , has engineered the FSM_API to address the core shortcomings of conventional FSM implementations, delivering a control plane built for high-throughput, mission-critical applications.

Here is an analysis of the architectural decisions that set the FSM_API apart from existing solutions, establishing it as the superior choice for high-assurance C# development.

1. The Concurrency Chasm: Thread Safety by Design

The single greatest differentiator of the FSM_API is its uncompromising commitment to thread safety.

Traditional FSM libraries popular in the.NET ecosystem are inherently not thread-safe. When utilized in concurrent environments (which is nearly every modern server-side or game application), developers are forced to wrap critical methods, such as state-triggering calls, in external locking mechanisms. This practice introduces significant operational risk:

(Forgive the spelling errors in the images, good AI is hard to find!)

Risk of Race Conditions: External locking is difficult to manage perfectly and often leads to non-reproducible race conditions, particularly on highly concurrent or slower machines.
Performance Bottlenecks: Manual locking introduces synchronization overhead that can negate performance gains.

The Singularity Workshop eliminates this problem with its proprietary Deferred Mutation Handling model. The system operates on a thread-safe principle where "All modifications to FSM definitions and instances are meticulously deferred and processed safely on the main thread post-update, eliminating common concurrency issues".

This means the FSM_API handles the concurrency challenge internally and atomically, guaranteeing predictable state changes regardless of the thread they originated from. For any system requiring stability—such as high-frequency simulations, trading platforms, or robotics control—this architectural guarantee translates directly into reduced technical debt and higher ROI.

2. Architectural Purity: Decoupling Logic and Data

The FSM_API is designed with an emphasis on separation of concerns, which drastically improves unit testability and maintainability.

A. Context-Driven Behavior (`IStateContext`)

Instead of tying the FSM logic directly to a concrete class, the FSM_API utilizes the IStateContext interface. This simple, POCO-friendly (Plain Old C# Object) interface functions as the "data bag" for the specific FSM instance.

Logic vs. Data: The FSM handles the how and when of state transitions, while the IStateContext object provides the necessary data.
Testability: Because the state logic is entirely decoupled from the application's domain data, FSMs become "highly testable in isolation". This simplifies Continuous Integration workflows and accelerates development.

B. The Purity of the Transition

The FSMTransition class is rigorously defined to enforce high standards of state machine purity. A transition rule is comprised only of the From state, the To state, and a Guard (Condition).

Crucially, the FSM_API intentionally excludes mechanisms for defining transition actions. This design choice forces developers to place all side effects associated with a state change into the guaranteed OnEnter or OnExit actions of the respective states.

This strict structure prevents "goto pasta" logic and ensures that the system's behavior is always defined locally within the state's lifecycle, maximizing readability, verifiability, and formal analysis.

3. Performance, Agnosticism, and Low TCO

Performance is not an afterthought; it is a core feature of The Singularity Workshop's offering:

Blazing-Fast and Lightweight: The system is engineered for optimized performance and minimal memory allocations. This efficiency ensures the FSM_API can handle millions of executions locally, which is crucial for demanding simulation scenarios.
Zero-Dependency Footprint: The FSM_API is Framework Agnostic. It requires "No external dependencies. No frameworks required. No boilerplate setup". This significantly reduces the Total Cost of Ownership (TCO) for enterprises, eliminating maintenance burdens, licensing complexities, and compatibility issues that come with relying on large external frameworks. It works seamlessly across the entire.NET spectrum, from.NET Framework 4.7 through.NET 8.0.

4. Advanced Orchestration: Dynamic Control and Groups

Beyond mere state tracking, the FSM_API provides features essential for orchestrating large populations of interacting entities:

Processing Groups: Developers can organize multiple FSM instances into named Processing Groups (e.g., "AI Update Loop," "UI Logic"). This allows for granular, dynamic update ticking and frame/process throttling , enabling developers to prioritize critical system FSMs while throttling non-critical ones, maximizing computational efficiency.
Runtime Redefinition: FSM definitions can be redefined while actively running. This capability supports advanced operational models like live patching of behavioral logic and dynamic reconfiguration without requiring application downtime or recompilation—a powerful tool for high-availability systems.
Error Tolerance: The library includes built-in diagnostics and thresholds designed to monitor and manage complex logic failures, proactively preventing "runaway logic or invalid state contexts" and ensuring application stability without a full system crash.

Conclusion: The Investment in Architectural Defensibility

The Singularity Workshop FSM_API is not just a replacement for existing C# FSM tools; it is an architectural upgrade. It provides a level of guaranteed thread safety and architectural purity that existing solutions force developers to implement manually, inefficiently, and often incorrectly.

By utilizing the FSM_API (NuGet: TheSingularityWorkshop.FSM_API), C# developers gain:

Reliability: Guaranteed stability via Deferred Mutation Handling.
Performance: Minimal allocation, blazing-fast execution speeds.
Maintainability: Decoupled logic, easy unit testing, and highly readable definitions built using the Fluent API.

For serious developers and enterprises building systems where failure is not an option, the FSM_API provides the robust, deterministic foundation necessary to scale complex behavioral logic with confidence.

Support the Vision and See the Code!

If this pattern has helped clean up your Update() loop, please consider supporting our development! Your support ensures we can continue to provide advanced, architectural solutions for cleaner game development.

Resources & Code:

The FSM Package (Unity Asset Store):
https://assetstore.unity.com/packages/slug/332450

NuGet Package (Non-Unity Core):
https://www.nuget.org/packages/TheSingularityWorkshop.FSM_API

GitHub Repository:
https://github.com/TrentBest/FSM_API

Support Our Work:

Patreon Page:
https://www.patreon.com/c/TheSingularityWorkshop

Support Us (PayPal Donation):
https://www.paypal.com/donate/?hosted_button_id=3Z7263LCQMV9J

We'd love to hear your thoughts! Please Like this post, Love the code, and Share your feedback in the comments.

A Finite State of One: Rethinking the Singleton Pattern with FSMs

Sun, 16 Nov 2025 06:50:33 +0000

A Finite State of One: Rethinking the Singleton Pattern with FSMs

The Singleton pattern is a cornerstone of game development and application architecture, ensuring a class has only one instance and providing a global point of access. Yet, its implementation in C# can often feel like wrestling with unnecessary boilerplate—or worse, a forced, inflexible use of generics that clutters your codebase.

What if your Singleton could be inherently self-regulating, decoupling the enforcement logic from the class itself, all while giving you granular control over performance?

We recently discovered an incredibly intuitive and versatile approach that achieves just this, leveraging the power of a modern Finite State Machine (FSM) framework, specifically TheSingularityWorkshop.FSM_API, to abstract and enforce the Singleton constraint.

The Pain Points of Traditional Singletons

Most C# Singletons fall into two camps, both of which introduce either bloat or manual effort:

The Boilerplate (Non-Generic): Requires manual static field, private constructor, and thread-safety logic for every class.
The Generic (Templated): Reduces boilerplate but introduces a base class dependency, which can be seen as "bloat" and often complicates inheritance hierarchies.

Here is a quick look at the typical C# Unity implementation:

public class ClassicInputManager : MonoBehaviour
{
    private static ClassicInputManager _instance;

    public static ClassicInputManager Instance
    {
        get
        {
            if (_instance == null)
            {
                _instance = FindObjectOfType<ClassicInputManager>();
                if (_instance == null)
                {
                    Debug.LogError("ClassicInputManager not found in scene!");
                }
            }
            return _instance;
        }
    }

    // Other class members...
}

This is fragile: what if two instances are accidentally placed in the scene? You have to add clumsy boilerplate to Awake() or Start() to destroy duplicates, and the instance check runs on every single call to Instance.

The FSM-Driven Singleton: Self-Healing and Performant

The FSM_Singleton is an abstraction layer that wraps your target class (the actual Singleton, like a BuildersInputManager) and delegates the enforcement of uniqueness to an FSM instance.

By creating an FSM instance upon the target's initialization, we gain immediate access to the FSM API's core benefits: robust lifecycle management and customizable processing rates.

In the example below, the BuildersInputManager simply creates an FSM_Singleton in its Awake() method:

public class BuildersInputManager : MonoBehaviour, IStateContext
{
    // ...
    void Awake()
    {
        // Establish this as a singleton, checking for duplicates every 10 update calls
        new FSM_Singleton(this, 10, "Update"); 
    }
    // ...
}

The magic lies within the FSM_Singleton's constructor and the single "Operating" state of its FSM definition:

public class FSM_Singleton : IStateContext
{
    public FSM_Singleton(IStateContext stateContext, int processRate, string processGroup)
    {
        // 1. Create FSM Definition (if it doesn't exist)
        if(!FSM_API.Interaction.Exists("BuildersInputManager", processGroup))
        {
            FSM_API.Create.CreateFiniteStateMachine("BuildersInputManager", processRate, processGroup)
                .State("Operating", null, OnUpdateOperating, null)
                .BuildDefinition();
        }
        // 2. Create FSM Instance for the target context
        Status = FSM_API.Create.CreateInstance("BuildersInputManager", this, processGroup);
        // ...
    }

    private void OnUpdateOperating(IStateContext context)
    {
        if(context is FSM_Singleton singleton)
        {
            Enforce(singleton); // Check and remove duplicates
        }
    }

    private void Enforce(FSM_Singleton singleton)
    {
        var bucket = FSM_API.Internal.GetBucket(stateContext.Name, singleton.ProcessGroup);
        if (bucket.Instances.Count > 1)
        {
            RemoveRedundant(singleton, bucket);
        }
    }
    
    private static void RemoveRedundant(FSM_Singleton singleton, FSM_API.Internal.FsmBucket bucket)
    {
        for (int i = bucket.Instances.Count - 1; i >= 0; i--)
        {
            var instanceHandle = bucket.Instances[i];
            if (instanceHandle.Id != singleton.Status.Id)
            {
                Debug.LogWarning($"Destroyed duplicate instance with ID: {instanceHandle.Id}");
                FSM_API.Interaction.DestroyInstance(instanceHandle);
            }
        }
    }
    // ...
}

Versatility and Performance: Decoupling Enforcement

This mechanism showcases the ingenuity of decoupled architecture. Unlike traditional Singleton implementations, where duplicate checks must occur on every static property access or during immediate object instantiation, the FSM_Singleton establishes a self-healing contract. It initiates a constant, scheduled validation loop to ensure the existence of exactly one instance.

In the typical and expected scenario, the OnUpdateOperating logic performs a lightning-fast API call to retrieve the instance count, instantly confirming a count of one, and then terminates its execution for that cycle. This high-performance check effectively minimizes frame-time overhead.

Crucially, in the rare event that a duplicate is accidentally created, the enforcement logic will instantly eradicate it (DestroyInstance). This limits the duplicate's lifespan to the number of frames defined by the FSM's ProcessRate. By setting ProcessRate = 10 (as in the example), we drastically reduce overhead because the resource-intensive cleanup iteration runs only periodically, yet the detection and destruction of a redundant instance is still handled automatically and asynchronously.

Furthermore, the FSM framework allows for assigning this check to a specific Processing Group, enabling advanced scheduling tactics such as running the validation only during periods of available frame time, thus prioritizing critical game logic.

Analysis: FSM vs. Classic Singleton

Feature	Classic C# Singleton (Standard Boilerplate)	FSM_Singleton (TheSingularityWorkshop.FSM_API)
Enforcement Logic	Scattered throughout the target class (`Awake`/`Start` for cleanup, static property for creation/access).	Centralized and abstracted in the dedicated `FSM_Singleton` class.
Duplicate Handling	Must be manually coded for destruction; highly prone to developer error and race conditions.	Self-Healing via periodic FSM state updates (`OnUpdateOperating`), automatically detecting and destroying duplicates.
Performance	Enforcement or creation checks typically run every frame or on every public static `Instance` access, leading to constant minor overhead.	Highly Configurable via `ProcessRate` (e.g., run every 10th frame, or only on event), significantly minimizing the update overhead.
Code Style	Requires repetitive boilerplate (static field, private constructor, lock) or forces generic base class inheritance, potentially complicating the object hierarchy.	Clean pattern implementation without unnecessary generics, relying on standard interfaces (`IStateContext`) and a clean API wrapper.

The FSM-based approach successfully elevates the Singleton pattern beyond a rigid architectural constraint, transforming it into a flexible, self-regulating service. This decoupled solution expertly manages its own lifecycle and performance with exceptional granularity, representing a potent abstraction that simplifies the codebase and entirely eliminates the common implementation headaches associated with managing instance uniqueness.

Resources & Code:

The FSM Package (Unity Asset Store):
https://assetstore.unity.com/packages/slug/332450

NuGet Package (Non-Unity Core):
https://www.nuget.org/packages/TheSingularityWorkshop.FSM_API

GitHub Repository:
https://github.com/TrentBest/FSM_API

Support Our Work:

Patreon Page:
https://www.patreon.com/c/TheSingularityWorkshop

Support Us (PayPal Donation):
https://www.paypal.com/donate/?hosted_button_id=3Z7263LCQMV9J

We'd love to hear your thoughts! Please Like this post, Love the code, and Share your feedback in the comments.

Finite State Machines - the Universal Unit of Work

Tue, 04 Nov 2025 22:53:50 +0000

Escaping Boolean Hell: Why Your State Machine Needs to be Data-Driven

We've all been there: a simple boolean flag here, a nested if statement there. It seems harmless at first, but soon your codebase is a tangled mess of conditional logic.

Let's take the humble Door class. It can be opened and closed. Easy, right?

The Simple, Intuitive Code

public class Door
{
    public bool IsOpen { get; set; } = false;

    public void Open()
    {
        IsOpen = true;
        Console.WriteLine("The door is now open.");
    }

    public void Close()
    {
        IsOpen = false;
        Console.WriteLine("The door is now closed.");
    }
}

The Inevitable Complexity Creep

In the wild, the simple, intuitive code you first wrote quickly starts to smell. The moment we try to add a new feature, such as a lock, our elegant two-state object becomes a mess of conditional logic.

To accommodate the "locked" state, we add a new boolean flag, IsLocked, and then we must modify all existing methods to account for it.

public class Door
{
    public bool IsOpen { get; set; } = false;
    public bool IsLocked = false; // We added this!

    public void Open()
    {
        if (!IsLocked) // We modified this!
        {
            IsOpen = true;
            Console.WriteLine("The door is now open.");
        }
        else
        {
            Console.WriteLine("The door is locked and cannot be opened.");
        }
    }

    public void Close()
    {
        IsOpen = false;
        Console.WriteLine("The door is now closed.");
    }

    public void Lock() // We added this!
    {
        IsLocked = true;
        Console.WriteLine("The door is now locked.");
    }

    public void Unlock() // We added this!
    {
        IsLocked = false;
        Console.WriteLine("The door is now unlocked.");
    }
}

What about a Broken state? Or a Sliding door? Or a RollUp door? We can approximate these with more booleans, but each new addition requires us to go back and add more and more if/else statements to every method. It’s not scalable, it’s brittle, and it’s full of boilerplate.

Pros	Cons
Simple and quick to implement for basic cases.	Tight Coupling: Logic is tied directly to a single object.
No external dependencies or abstractions.	Boilerplate: `if/else` checks for every state change.
	Difficult to Scale: Adding new features breaks existing logic.
	Difficult to Maintain: Code quickly becomes a tangled mess.

The Typical FSM Solution and Its Pitfalls

A traditional Finite State Machine (FSM) approach uses the State Pattern, where you create distinct classes for each state that implement a common interface. The main Door class holds a reference to its current state object.

Traditional State Pattern Implementation

public interface IState<T>
{
    void Enter(T context);
    void Update(T context);
    void Exit(T context);
}
    
public class DoorContext
{
    public bool IsOpen { get; set; } = false;
}
    
public class DoorClosedState : IState<DoorContext>
{
    public void Enter(DoorContext context)
    {
        context.IsOpen = false;
        Console.WriteLine("The door is now closed.");
    }
    
    public void Update(DoorContext context) { }
    public void Exit(DoorContext context) { }
}
    
public class DoorOpenState : IState<DoorContext>
{
    public void Enter(DoorContext context)
    {
        context.IsOpen = true;
        Console.WriteLine("The door is now open.");
    }
    
    public void Update(DoorContext context) { }
    public void Exit(DoorContext context) { }
}

Now, what does it take to add a "locked" state to this? It's not as simple as adding a boolean. We need to create a new state class, DoorLockedState, and then modify our existing states and the context to allow for transitions to this new state. This still requires a fair amount of boilerplate and modification of existing code.

FSM Solution Trade-offs

Pros	Cons
Clean State Separation: Logic for each state is in a distinct class.	Boilerplate: Requires a lot of code to set up states, transitions, and the state machine itself.
Enforced Transitions: The model naturally enforces valid transitions.	Rigid Design: FSM definition is static and difficult to modify at runtime.
Well-Established Pattern: A common and well-understood design pattern.	State Explosion: Can lead to a large number of classes for each state, making it difficult to manage.

A Better Way: FSM_API and Centralized State

The FSM_API embraces a declarative, data-driven approach that is designed to be blazing-fast, software-agnostic, and fully decoupled from your application's logic.

The core concept is that the FSM_API operates on Plain Old C# Objects (POCOs) that simply implement the IStateContext interface. This ensures a clean separation between your FSM logic and your application's data.

1. Define the Context

Our Door class is now a simple POCO. All its transition and state-entry logic is handled externally by the FSMs we are about to create.

public class Door : IStateContext
{
    public bool IsOpen { get; set; } = false;
    public bool IsLocked = false;
    public string Name { get; set; } = "FrontDoor";
    public bool IsValid => true; // FSM API will not operate on this if false.
}

2. Multiple FSMs on a Single Context

The true power of FSM_API is its ability to manage multiple, independent behaviors on a single context object. This allows us to separate our "open/close" logic from our "lock/unlock" logic.

Here is the declarative definition for the DoorFSM:

FSM_API.Create.CreateFiniteStateMachine("DoorFSM")
    .State("Closed", onEnter: (ctx) => { ((Door)ctx).IsOpen = false; })
    .State("Open", onEnter: (ctx) => { ((Door)ctx).IsOpen = true; })
    .State("Locked")
    .WithInitialState("Closed")
    // Transition to Open only if not locked
    .Transition("Closed", "Open", (ctx) => !((Door)ctx).IsLocked) 
    .Transition("Open", "Closed")
    // Transition to Locked from Closed
    .Transition("Closed", "Locked") 
    // Transition from Locked back to Closed only if unlocked
    .Transition("Locked", "Closed", (ctx) => !((Door)ctx).IsLocked) 
    .BuildDefinition();

Because the FSM_API allows for runtime redefinition of FSMs, we can dynamically add states and transitions to our door object without recompiling. This capability makes it a powerful choice for highly configurable or live-updating systems.

FSM_API Trade-offs

Pros	Cons
Centralized State: FSM logic is fully separated from data.	Learning Curve: New concepts might take time to grasp if you are used to traditional FSM implementations.
Runtime Redefinition: FSMs can be modified on the fly without recompilation.	Minimalism: The API is minimal by design; you will need to rely on the provided documentation to get started.
Lightweight & Performant: Minimal memory allocations and optimized performance.
Framework Agnostic: No external dependencies or frameworks required (works with .NET Framework 4.7 through .NET 8.0).
Thread-Safe: Designed for safe, deferred mutation handling.

This is just a glimpse of what's possible with the FSM_API. Its features make it a robust choice for any C# application requiring sophisticated state management.

If you'd like to get started, you can find our NuGet package and all the documentation on our GitHub repository:

NuGet Package: TheSingularityWorkshop.FSM_API
GitHub Repository: TrentBest/FSM_API
Patreon Page: https://www.patreon.com/c/TheSingularityWorkshop
Unity Integration (Advanced): https://assetstore.unity.com/packages/slug/332450
Unity Integration (Basic): Currently pending Marketing.

If you feel this tool is valuable to you, please consider supporting the project. Donate via PayPal

Coder Legion - Recent posts tagged c-sharp

Forging the Elements: A Deep Dive into Recursive Builders

Realigning Your Thinking: The Recursive Builder Paradigm

A Simple Threshold Implementation

High-Speed Implementation: The Factory

Use Case 1: The Magic Overcharge

Use Case 2: The Character Health

Deep Dive: Inside the FSM_Threshold

The Core Logic

The "Manual Reset" Hammer

The Factory: Simplifying Complexity

The Deterministic Engine: Why The Singularity Workshop’s FSM_API Redefines C# State Management

The Deterministic Engine: Why The Singularity Workshop’s FSM_API Redefines C# State Management

1. The Concurrency Chasm: Thread Safety by Design

2. Architectural Purity: Decoupling Logic and Data

A. Context-Driven Behavior (IStateContext)

B. The Purity of the Transition

3. Performance, Agnosticism, and Low TCO

4. Advanced Orchestration: Dynamic Control and Groups

Conclusion: The Investment in Architectural Defensibility

A Finite State of One: Rethinking the Singleton Pattern with FSMs

A Finite State of One: Rethinking the Singleton Pattern with FSMs

The Pain Points of Traditional Singletons

The FSM-Driven Singleton: Self-Healing and Performant

Versatility and Performance: Decoupling Enforcement

Analysis: FSM vs. Classic Singleton

Finite State Machines - the Universal Unit of Work

Escaping Boolean Hell: Why Your State Machine Needs to be Data-Driven

The Simple, Intuitive Code

The Inevitable Complexity Creep

The Typical FSM Solution and Its Pitfalls

Traditional State Pattern Implementation

FSM Solution Trade-offs

A Better Way: FSM_API and Centralized State

1. Define the Context

2. Multiple FSMs on a Single Context

FSM_API Trade-offs

A. Context-Driven Behavior (`IStateContext`)