DEV Community: Trent Best

FSM_API: The Pure C# Core That Decouples Your Logic from Any Engine

Trent Best — Thu, 09 Oct 2025 20:31:42 +0000

We recently announced our pivot at The Singularity Workshop: shifting focus from building a custom ECS engine to perfecting the FSM_API (Finite State Machine Application Programming Interface). This move ensures a stronger, more maintainable foundation for MyVR and offers immediate, open-source value to every C# developer.

The FSM_API is the blazing-fast core of this vision. It is built to be completely engine-agnostic, allowing you to define complex, reliable behavior in pure C# and deploy it anywhere—from backend services and robotics to Unity or other game engines.

Here's how FSM_API provides the decoupling and power every developer needs in their toolkit:

🧠 1. Decoupling Logic: The IStateContext Contract

The biggest challenge in state management is coupling logic (the how) to data (the what). FSM_API solves this by requiring every managed entity to implement the simple IStateContext interface.

FSM Logic is Abstract: The FSM Definition (your blueprint) contains the states and transitions, but it knows nothing about "player health" or "door position". It only understands abstract actions like onEnter, onUpdate, and onExit.
Your Data is the Context: Your custom C# class (e.g., PlayerContext or LightSwitch) implements IStateContext. This object holds all the data and physical methods (like PlayAnimation() or TakeDamage()) that the FSM's actions will call.
A Self-Cleaning System: The IStateContext includes a crucial IsValid property. If your object is destroyed or no longer relevant, setting IsValid to false automatically tells the FSM_API to unregister and clean up the associated FSM instance, preventing memory leaks and errors.

This clear separation ensures your logic is reusable, and the system manages its own lifecycle.

⚙️ 2. Engine Agnosticism: Deployment Anywhere

Because the core FSM logic doesn't touch Unity's MonoBehaviour or any other engine code, FSM_API is instantly compatible with any C# environment.

Pure C# Ready: You can define a complex AI system using the fluent FSMBuilder and run it in a simple console application, a backend server, or a robotics controller.
Explicit Control with Processing Groups: In environments without a built-in game loop (like a console app or backend service), you gain explicit control over the update cycle using Processing Groups:
1. You create a logical group (e.g., "AI_Logic" or "Network_Processor").
2. You assign FSM instances to that group.
3. You manually call FSM_API.Interaction.Update("GroupName") exactly when you want the FSMs to tick.

This level of control is essential for server-side logic and custom engine environments where performance demands are high.

💡 3. Dynamic Power: Runtime Modification

Most FSM solutions are static: once defined, they can't change. FSM_API's FSMModifier shatters this limitation, enabling the runtime recomposition that powers our innovative AnyApp vision.

The FSMModifier allows you to change the FSM blueprint (the definition) after it has been built, even while instances are actively running from it.

Adaptive AI: Dynamically add a new "Enraged" state or modify the transition condition for "Flee" after a major in-game event.
Dynamic UI/Content: Add or remove navigation paths based on user unlocks or content downloads without requiring a full recompile or app restart.
Live Hot-Reloading: During development, modify FSM logic and apply the changes immediately in a running build for rapid iteration.

This is the key to creating applications that can genuinely adapt and change on the fly, transforming static software into fluid, composable experiences.

🚀 Get Started with the Free Core

The FSM_API is designed to be the fastest, most flexible, and most robust solution available for C# developers.

The core DLL is open-source and free, available now on NuGet. Get started today:

NuGet Package: TheSingularityWorkshop.FSM_API
Find out more about our full roadmap (MyVR, AnyApp, and the FSM_Layer Asset Store packages) on our Patreon page.

Stop Getting Blocked: How a Simple Design Pattern Unlocks Your Project's Complex Logic

Trent Best — Fri, 26 Sep 2025 23:57:31 +0000

Have you ever started a project—a simple game, a complex UI, or any interactive system—only to feel completely overwhelmed by the chaos of your main logic loop? You add an if statement for one behavior, and it breaks another. You try to fix it, and it breaks three more. Sound familiar?

You're not alone. This is the moment when many new developers get blocked.

But what if I told you there's a simple, powerful structure you can design before you even write the code? This design acts as a scaffold, letting you build complex, reliable behavior piece by piece.

That structure is called the Finite State Machine (FSM), and we're going to break down a demo to show you how it works and how it can unblock your next project.

The Power of a Structured Design: FSMs

In its simplest form, a Finite State Machine is a way to model anything that behaves differently based on its current status. Every piece of logic is isolated into a State, and you define strict Transitions (rules) for moving between them.

This learned structure is the key to escaping the "spaghetti code" trap:

Define Intent: Draw a diagram of what you want to happen.
Implement Isolation: Write the code for each State and Transition in isolation.
Know It Works: Since the FSM framework manages the flow, you know the overall logic will function as designed—you just have to fill in the behavior for each small piece.

Let's see this in action using the Quick Brown Fox demo.

Case Study: The Quick Brown Fox Demo

Our simulation is based on the classic phrase, "The quick brown fox jumps over the lazy sleeping dog". We have two agents, and we use FSMs to define their entire behavioral logic.

1. The Simulation Setup (`SimpleDemoContext.cs`)

This is the central application, which manages the world and the agents.

The Fox starts at Position 0.
The Dog starts at Position 3.
The goal is for the Fox to reach the WinPosition of 10.

Every frame, the simulation context performs three steps:

Clear vision and collision data for all agents.
Perform Vision and Collision checks between agents (our world rules).
Calls FSM_API.Interaction.Update("Update") to tell every agent's FSM to run its logic for the current frame.

2. Modeling the Fox: The `QuickBrownFoxFSM`

The Fox's FSM is a perfect example of how a simple diagram can define complex behavior. The fox primarily Walks, Jumps over obstacles (the dog), or Flees if it collides.

Here is a summary of the Fox's logic:

State	Transition Condition	Action (OnUpdate)
Walking	ShouldJump: A visible agent is within 2 units. ShouldFlee: Collision with a dog.	Increments position by 1 (Speed).
Jumping	ShouldLand: Position is greater than or equal to `JumpEnd` (2 steps after jumping started).	Increments position by 1.
Fleeing	None (Terminal state).	Increments position by 2 (Speed).
Mangled	None (Terminal state).	Outputs current status.

Notice how clean the logic is for a State like Walking:

private void OnUpdateWalking(IStateContext context)
{
    if (context is QuickBrownFox fox)
    {
        // Simple: Just move forward by its speed
        fox.Position += fox.Speed; 
        Console.WriteLine($"{fox.Name} is walking:  {fox.Position}");
    }
}

Its complexity comes from the Transitions—the rules that change the state. The Fox will only switch from Walking to Jumping if the condition in ShouldJump is met:

private bool ShouldJump(IStateContext context)
{
    if (context is QuickBrownFox fox)
    {
        // Transition rule: Look at all visible agents (provided by SimpleDemoContext)
        foreach (var visible in fox.VisibleAgents)
        {
            var distance = visible.Position - fox.Position;
            if(distance <= 2) // If the visible agent is too close (within 2 units)
            {
                return true;
            }
        }
    }
    return false;
}

The Fox isn't doing collision logic; the main simulation is. The Fox is only checking its readily available VisibleAgents list, keeping its own code extremely focused!

3. Interacting Agents: The `LazyDogFSM`

The Dog's behavior is even simpler. It starts Sleeping until an external force (a collision) wakes it up.

Sleeping to Awake: The transition condition IsAwake returns true if a collision has occurred.
Awake to Chasing: The dog sees the fox (ShouldChase is true) and begins to chase at speed 3.
Chasing to Mangling: Collision with the Fox occurs again (IsMangling is true).

The true power is seen in the Mangling state, which demonstrates Inter-FSM Communication:

private void OnEnterMangling(IStateContext context)
{
    if (context is LazySleepingDog dog)
    {
        Console.WriteLine($"{dog.Name} has started Mangling the fox!");
        // The dog reaches into the Fox's FSM and forces a state change!
        dog.CollidedAgents.FirstOrDefault()?.State.TransitionTo("Mangled");
    }
}

The Dog doesn't need to know how the Fox gets mangled, only that it can force the Fox's FSM to the terminal Mangled state. This isolation keeps the Dog's code simple, too.

Your Takeaway: Design Before You Code

This simple example proves the structure works:

No monolithic if/else block is needed in one huge update function.
Design First: You can draft the FSM diagram first and use it as a blueprint for development.
Focus: You only need to think about what happens in that specific state and what rules trigger a specific transition.

This approach is your new scaffolding tool. It lets you design robust, complex applications without getting blocked by logic that breaks down the line. You know what needs to be implemented because you've already defined it on your diagram!

Get the FSM_API

You can access and support the FSM_API at the following links:

GitHub Repository: https://github.com/trentbest/fsm_api

NuGet Package: https://www.nuget.org/packages/TheSingularityWorkshop.FSM_API/

💖 Support Us: https://www.paypal.com/paypalme/TheSingularityWorkshop

The Singularity Workshop

A FSM Challenge for the c#/DotNet Dev Community

Trent Best — Fri, 19 Sep 2025 22:49:59 +0000

Hey everyone! 👋

I'm excited to share a fun challenge with you. For those looking to learn something new, test their skills, or just have some fun, I've created something I think you'll enjoy.

Introducing FSM_API

I've made my free, open-source FSM_API NuGet package public. It's a platform-agnostic C# library, meaning you can integrate its behavior into almost any C# application. If you've ever wanted to explore the power of Finite State Machines (FSMs), this is a great opportunity.

What is a Finite State Machine?
A finite state machine is a mathematical model of computation. It is an abstract machine that can be in exactly one of a finite number of states at any given time. The FSM can change from one state to another in response to some inputs; the change from one state to another is called a transition. An FSM is defined by a list of its states, its initial state, and the inputs that trigger each transition.

The Challenge: What Will You Create?

Your task is simple: install the FSM_API NuGet package and show us what you can build. It could be a simple game, a workflow for a business application, or a unique UI behavior. The possibilities are endless.

You can get the package here: NuGet.

Get Started

To help you, I'll be releasing a new public GitHub repository soon. It will feature four examples of how to integrate the API:

A minimal FSM-based console application that demonstrates the core loop.
An Advanced console application which demonstrates fine grained control over the initialization, update, and shutdown behavior.
A minimal FSM-based WPF application which demonstrates the simplest FSM loop.
An advanced WPF application that shows how to decouple your application's behavior from the UI itself, a key principle of modern software design.

I'm eager to see what you create. Share your ideas and projects in the comments below, and let's get building!

The Singularity Workshop

From Chaos to Cohesion: A Retrospective on How FSMs Connect Us to Domain Experts

Trent Best — Wed, 17 Sep 2025 20:35:18 +0000

Having spent the better part of 16 years creating complex drawing sets for various trades in the AEC industry where I not only created their complex 3D models but the sheets which were submitted for permit, or shop/field install drawings. I have had the privilege of working with Experts in their trades and I have built a career on using the software on their behalf and automating the software to do what their expertise prescribes.

When I started building my FSM_API, it began as an offshoot of a hobby, building Starcraft 2 bots. Frustrated with the complex commands and controls available in this domain, I explored all sorts of options, eventually realizing the absolute necessity for Finite State Machines.

However, the typical way of doing this—what we learn in the forums or watch in the tutorials—is itself valid, yet quite lacking. As I've also, as part of my career, driven efficiency up everywhere I work by analyzing complex workflows and identifying the bottlenecks, just like debugging.

The Problem with Traditional FSMs

The final piece of the puzzle clicked when we implement an FSM: we don't want to be blocked by having to always ensure it follows proper sequence, we don't want to have to provide similar or the same implementations, and most importantly, we want to be able to apply an FSM's behavior to as many contexts as possible. Here I recognized the need for a central abstraction, what I call the "Universal Unit of Work" which I believe I took from college math, but that was decades ago, so don't quote me on it.

This fundamental realization led to the core design principles of the FSM_API, which solves these issues by decoupling the FSM logic from its data, a concept referred to as the Context. This allows a single FSM blueprint to be instantiated and applied to many different objects or systems, streamlining development and ensuring consistency across an entire application. The core of this abstraction is that a domain expert, regardless of their coding background, can describe a complex process, which can then be directly translated into a functional FSM.

The shocker to me was that we can have an expert do something like this:

This diagram represents the expertise of a professional in their trade. They can capture every state, condition, and transition necessary to describe a complex workflow. By using a fluent, human-readable API, we can empower them to define this logic directly.

Translating Expertise into Code

The complex diagram above, which a typical coder would spend hours trying to replicate with convoluted if/else statements, can be translated into a clean and maintainable C# code block using the FSM_API. The API's fluent interface and clear method names allow for a near-direct transcription of the domain expert's diagram into functional, debuggable code.

The following code shows a comprehensive implementation of a Car Transmission FSM, demonstrating the power of the FSMBuilder to define a full domain of knowledge in a single, cohesive unit. Each state's actions (onEnter, onUpdate, onExit) are defined along with the specific transitions that connect them. This includes complex logic for gear shifting and critical safety protocols like the Fault state.

using System;
using TheSingularityWorkshop.FSM_API;

// 1. Define the Context Class
// This "data bag" holds all the real-time information the FSM needs to make decisions.
public class CarContext : IStateContext
{
    public float Speed { get; set; } = 0.0f;
    public bool BrakePedalPressed { get; set; } = false;
    public bool ThrottleDown { get; set; } = false;
    public bool EngineFault { get; set; } = false;
}

// 2. Define the FSM
// This class contains the blueprint for the entire car transmission system.
public static class CarTransmissionFSM
{
    public static void CreateComplexFSM()
    {
        FSM_API.Create.CreateFiniteStateMachine("CarFSM", -1, "VehicleUpdate")
            // --- Define Top-Level States ---
            .State("Park",
                onEnter: (ctx) => Console.WriteLine("Transmission is in Park."),
                onUpdate: (ctx) => { /* Check for input */ },
                onExit: (ctx) => Console.WriteLine("Exiting Park."))
            .State("Reverse",
                onEnter: (ctx) => Console.WriteLine("Transmission is in Reverse."),
                onUpdate: (ctx) => { /* Reverse logic */ },
                onExit: (ctx) => Console.WriteLine("Exiting Reverse."))
            .State("Neutral",
                onEnter: (ctx) => Console.WriteLine("Transmission is in Neutral."),
                onUpdate: (ctx) => { /* Idle engine logic */ },
                onExit: (ctx) => Console.WriteLine("Exiting Neutral."))
            .State("Fault",
                onEnter: (ctx) =>
                {
                    Console.WriteLine("CRITICAL FAULT: Transitioning to Fault state.");
                    // Simulate a critical safety action: disable the engine
                    ((CarContext)ctx).EngineFault = true;
                },
                onUpdate: (ctx) => Console.WriteLine("In Fault mode. Cannot proceed."),
                onExit: (ctx) => Console.WriteLine("Fault has been manually reset."))

            // --- Define Drive Sub-States (Gears) ---
            .State("First_Gear",
                onEnter: (ctx) => Console.WriteLine("Shifted into First Gear."),
                onUpdate: (ctx) => { /* Apply torque for first gear */ },
                onExit: (ctx) => { /* Prepare for shift up */ })
            .State("Second_Gear",
                onEnter: (ctx) => Console.WriteLine("Shifted into Second Gear."),
                onUpdate: (ctx) => { /* Apply torque for second gear */ },
                onExit: (ctx) => { /* Prepare for shift */ })
            .State("Third_Gear",
                onEnter: (ctx) => Console.WriteLine("Shifted into Third Gear."),
                onUpdate: (ctx) => { /* Apply torque for third gear */ },
                onExit: (ctx) => { /* Prepare for shift */ })
            .State("Fourth_Gear",
                onEnter: (ctx) => Console.WriteLine("Shifted into Fourth Gear."),
                onUpdate: (ctx) => { /* Apply torque for fourth gear */ },
                onExit: (ctx) => { /* Prepare for shift */ })

            // --- Set Initial State ---
            .WithInitialState("Park")

            // --- Define Transitions ---
            // Top-level transitions (P, R, N, D)
            .Transition("Park", "Reverse", (ctx) => ((CarContext)ctx).BrakePedalPressed)
            .Transition("Park", "First_Gear", (ctx) => ((CarContext)ctx).BrakePedalPressed)
            .Transition("Reverse", "Park", (ctx) => !((CarContext)ctx).BrakePedalPressed)
            .Transition("Reverse", "Neutral", (ctx) => true) // Always can shift from R to N
            .Transition("Neutral", "Park", (ctx) => true)
            .Transition("Neutral", "Reverse", (ctx) => ((CarContext)ctx).BrakePedalPressed)
            .Transition("Neutral", "First_Gear", (ctx) => ((CarContext)ctx).BrakePedalPressed)
            // A transition from any Drive gear back to Neutral or Park
            .AnyTransition("Neutral", (ctx) => !((CarContext)ctx).BrakePedalPressed && ((CarContext)ctx).Speed < 1.0f)
            .AnyTransition("Park", (ctx) => !((CarContext)ctx).BrakePedalPressed && ((CarContext)ctx).Speed < 1.0f)

            // Drive sub-state transitions (Gear Shifting)
            .Transition("First_Gear", "Second_Gear", (ctx) => ((CarContext)ctx).Speed > 15.0f && !((CarContext)ctx).ThrottleDown)
            .Transition("Second_Gear", "Third_Gear", (ctx) => ((CarContext)ctx).Speed > 30.0f)
            .Transition("Third_Gear", "Fourth_Gear", (ctx) => ((CarContext)ctx).Speed > 45.0f)

            // Downshifting transitions
            .Transition("Fourth_Gear", "Third_Gear", (ctx) => ((CarContext)ctx).Speed < 40.0f)
            .Transition("Third_Gear", "Second_Gear", (ctx) => ((CarContext)ctx).Speed < 25.0f)
            .Transition("Second_Gear", "First_Gear", (ctx) => ((CarContext)ctx).Speed < 10.0f || ((CarContext)ctx).ThrottleDown)

            // "Any-State" transitions for safety and error handling
            .AnyTransition("Fault", (ctx) => ((CarContext)ctx).EngineFault)
            .AnyTransition("Park", (ctx) => ((CarContext)ctx).BrakePedalPressed && ((CarContext)ctx).Speed < 1.0f)

            // Finalize the FSM blueprint
            .BuildDefinition();
    }
}

The Paradigm Shift

Now if we are able to get to this point where an expert has been able to input their domain of expertise into FSMs, then we only need a competent coder to follow behind implementing the scaffolded code. This changes everything! The complex, abstract logic that once resided solely within the mind of the expert is now a tangible, version-controlled asset. It becomes a unified logical architecture that is easily accessible and maintainable, bridging the gap between domain knowledge and software implementation. The FSM_API proves that by building the right tools, we can empower experts to define their complex worlds with ease.

Get the `FSM_API`

You can access and support the FSM_API at the following links:

GitHub Repository: https://github.com/trentbest/fsm_api
NuGet Package: https://www.nuget.org/packages/TheSingularityWorkshop.FSM_API/
PayPal: https://www.paypal.com/paypalme/TheSingularityWorkshop

Engineering "The" Loop

Trent Best — Wed, 17 Sep 2025 01:32:57 +0000

The Problem with the Classic Game Loop 🎮

Almost every interactive application, from video games to user interfaces, relies on a continuous execution loop. This loop is the heart of the application, responsible for everything from updating the game state to rendering graphics. While it's a fundamental concept, the traditional approach can often feel like a point of contention among developers. Why? Because the classic game loop, often a simple while(true) or while(IsRunning) block, can quickly become an unmanageable monolith.

Consider a typical game loop:

void MainGameLoop()
{
    Initialize();
    
    while (IsRunning)
    {
        ProcessInput();
        UpdateGameState();
        RenderGraphics();
        PlayAudio();
        // ...and a dozen other things
    }
    
    Shutdown();
}

This works for simple projects, but as an application grows, this single loop becomes a catch-all for complex logic. It tightly couples disparate systems (like input, rendering, and AI), making the code difficult to maintain, test, and debug. You end up with a single, massive function that handles everything, and any small change can have unintended consequences.

A Better Way: A State Machine-Driven Loop ✨

What if we could break free from this monolithic approach? What if our application's "loop" wasn't a static while statement, but a dynamic, self-managing system? That's the power of a Finite State Machine (FSM).

In our project, we've integrated this idea into the MainWindowViewModel for a WPF application. Instead of a single, endlessly running loop, our application's flow is managed by an FSM. Each "tick" of the application isn't a fixed set of actions, but a transition to a new state based on events.

Our MainWindowViewModel (from the provided code) implements the IStateContext interface:

public class MainWindowViewModel : INotifyPropertyChanged, IStateContext
{
    // ... properties and methods
    public bool IsValid { get; set; }
    public string Name { get; set; }

    public void InitializeState()
    {
        // This method will be called by the FSM
        // It will be the entry point for our initial actions
    }
}

This approach allows the FSM to dictate what happens at any given moment. For example, when the application starts, the FSM can trigger the InitializeState() method. If a user clicks a button, the FSM can transition the application into a new state that handles that specific action, like fetching GitHub repository data. The loop isn't a single, continuous block—it's a series of transitions and actions managed by a state machine.

This makes the MainWindowViewModel highly modular and responsive. We can have states like LoadingRepositories, ShowingGitHubStatus, or Idle, and the FSM ensures that the correct actions are executed for each state.

The API Evolution: From Simple to Dynamic 🚀

The two provided Unity C# scripts, FSM_UnityIntegration.cs and FSM_UnityIntegrationAdvanced.cs, showcase different approaches to creating a game loop driven by a Finite State Machine (FSM) API. The basic FSM_UnityIntegration script uses a rigid one-to-one mapping between Unity's lifecycle methods and a single FSM processing group. In contrast, FSM_UnityIntegrationAdvanced allows for a dynamic, runtime-modifiable list of processing groups for each Unity message, providing greater flexibility. Both scripts implement the singleton pattern to ensure only one instance of the integration exists in a scene.

The Basic Approach: Direct Mapping

In our initial API, we used a direct one-to-one mapping. Each Unity message (like Start, Update, OnDestroy) directly called a single, corresponding process group. This was a step up from the monolithic loop, but it was still quite rigid. You had a predefined set of actions for each phase of the application lifecycle.

For instance, the Update() method in the basic integration always calls the single _updateProcessingGroup:

void Update()
{
    FSM_API.Interaction.Update(_updateProcessingGroup);
    FSM_API.Interaction.Update(_unityHandles);
}

Pros:
- Simplicity: It's a simple, predictable model that's easy for new developers to grasp.
- Performance: The direct call to a single processing group is efficient and has minimal overhead.
- Reliability: The flow is fixed and well-defined, reducing the chance of unexpected behavior.
Cons:
- Rigidity: The biggest drawback is its lack of flexibility. You can't dynamically add or remove processing groups at runtime. To change what happens during an Update, you'd need to modify the code itself.
- Limited Customization: It's not suitable for scenarios where the game loop needs to change its behavior based on the application's state, such as enabling or disabling different systems (e.g., a combat system) only when a specific state is active.

The Advanced Approach: Runtime Modifiable Loops

Our more advanced API takes this a step further. We don't just have a single method for Update; instead, we provide a list of strings that represent the process groups to be executed. This is a simple but incredibly powerful change.

The Update() method in the advanced integration iterates through a list of groups, calling FSM_API.Interaction.Update() for each one:

void Update()
{
    foreach (var group in _updateProcessingGroup)
    {
        FSM_API.Interaction.Update(group);
    }
    FSM_API.Interaction.Update(_unityHandles);
}

This allows us to add, remove, or reorder process groups on the fly. For example, when the FSM enters a FetchRepositories state, it can dynamically add the GitHubRepositoryService process group to the update list using the AddProcessingGroup() method. When the fetch is complete, the FSM transitions to another state and can remove that process group. The application's loop isn't just a fixed sequence of events—it's a fluid, context-aware process.

Pros:
- Flexibility and Modularity: You can compose the game loop on the fly, adding and removing systems as needed without changing the core integration code.
- State-Driven Behavior: This approach fully leverages the power of the FSM. Different states can dictate which systems are active, making the application's behavior highly contextual and adaptive.
- Scalability: It's easier to add new systems without a cascading effect. You simply create a new processing group and add it to the relevant list when it's needed.
Cons:
- Complexity: This model is more complex to set up and manage. Developers must be mindful of which groups are active at any given time to avoid unexpected behavior.
- Potential Performance Overhead: Iterating through a list of groups every frame adds a small amount of overhead compared to a direct function call, though this is negligible in most cases.
- Debugging: It can be more challenging to debug, as the flow of execution isn't fixed; it depends on the current state and the contents of the processing group lists.

Comparison and Conclusion ⚖️

Feature	Basic Integration	Advanced Integration
Execution Model	Fixed: One-to-one mapping between Unity messages and FSM groups.	Dynamic: Iterates through a runtime-modifiable list of groups.
Flexibility	Low: Changes require code modification.	High: Groups can be added/removed at runtime.
Use Case	Ideal for simple applications with a consistent, unchanging game loop.	Best for complex, state-driven applications where systems need to be enabled/disabled dynamically.
Maintainability	Easy to maintain and understand for small projects.	More maintainable in the long run for large projects, as logic is isolated by state.
Scalability	Limited: Adding new features can lead to a monolithic `Update()` method.	High: New systems can be added without modifying core code.

The choice between the two integrations depends on the needs of the project. The basic FSM_UnityIntegration is a great starting point for developers who want a simple, reliable FSM-driven loop without the need for complex, dynamic behavior. The advanced FSM_UnityIntegrationAdvanced is a more powerful and scalable solution for larger, more complex applications that require a fluid and responsive game loop that can adapt to different application states. By leveraging the FSM to control which groups are active, the advanced model creates a truly context-aware application loop.

Conclusion: The Future is State-Driven 🤖

By moving from a monolithic while loop to a dynamic, FSM-driven execution model, we've created an application that is more:

Modular: Each process group and state handles a single responsibility.
Maintainable: Logic is isolated, making it easier to debug and modify.
Scalable: We can easily add new features without a cascading effect.
Runtime Modifiable: The application can adapt its behavior on the fly based on its current state.

This isn't just about elegant code; it's about building robust, flexible, and powerful applications that can grow and evolve without becoming a tangled mess. So next time you're about to write a classic while(true) loop, ask yourself: could a state machine do this better?

💖 Support Us

If you find this project useful, you can support its development through PayPal.

Donate via PayPal

🔗 Useful Links

NuGet Package: TheSingularityWorkshop.FSM_API
GitHub Repository: TrentBest/FSM_API
License: MIT License

🧠 Brought to you by

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

Because state shouldn’t be a mess.

Announcing The Singularity Workshop: A New FSM API for Unity

Trent Best — Sun, 07 Sep 2025 05:56:30 +0000

Today marks a major milestone for The Singularity Workshop—we've successfully submitted our first product, a lightweight and powerful FSM API, to the Unity Asset Store. This isn't just a simple tool; it's the first step in our mission to build foundational technologies that empower creators to bring their ambitious projects to life.

When building complex games or applications in Unity, managing states can become incredibly challenging. Our FSM API is designed to solve this problem by providing a clean, elegant, and high-performance framework for building state-driven logic. It's built for developers who want to focus on their core gameplay without getting bogged down in boilerplate code.

The core of the FSM API is a standalone C# library, delivered as a NuGet package. We then developed a dedicated integration layer that brings this core functionality directly into the Unity Editor. This approach allows us to ensure the API is robust and continuously developed while providing a seamless experience for Unity developers.

Join Our Journey

The submission to the Asset Store is just the beginning. The Singularity Workshop is committed to building a suite of interconnected tools that will help you create advanced systems for game AI, player mechanics, and more.

You can follow our journey and support our work here:

Explore the Code: Explore the Code: https://github.com/TrentBest/FSM_API

Get the NuGet Package:
https://www.nuget.org/packages/TheSingularityWorkshop.FSM_API/

Explore Our Vision:
https://www.patreon.com/TheSingularityWorkshop

Support the project: Donate via PayPal

Finite State Machines - the Universal Unit of Work

Trent Best — Sat, 06 Sep 2025 02:48:11 +0000

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. Your Door class can be opened and closed. Easy, right?

But in the wild, the simple, intuitive code you first wrote for a door 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.

Let's look at what our intuitive code looks like to begin with:

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.");
    }
}

Now, imagine we need to add a "locked" state. To accommodate this, our code is no longer simple. We have to add a new boolean flag, IsLocked, and then we have to modify all of our existing methods to account for this new state. We also have to add new methods, such as Lock and Unlock.

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.

Here are the pros and cons of using this approach:

Pros	Cons
Simple and quick to implement for basic cases.	Tight Coupling: Logic is tied 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 becomes a tangled mess.

The Typical FSM Solution and Its Pitfalls

A typical FSM approach would have you create distinct classes for each state (e.g., DoorOpenState, DoorClosedState, DoorLockedState) that all implement a common IState interface. The Door class would then hold a reference to its current state object. This is what you'll see in most tutorials and books.

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.

Here's an overview of the pros and cons of this and other FSM implementations:

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.	Framework-Dependent: Often tightly coupled to a specific game engine or framework.
Well-Established Pattern: A common and well-understood design pattern.	Rigid Design: FSM definition is static and difficult to modify at runtime.
Hierarchical FSMs (HFSMs): Allows for nested states, which can reduce complexity.	Hierarchical FSMs (HFSMs): Can introduce complexity and make the state machine harder to understand and debug.
Behavior Trees: A different approach that uses a tree structure to define behavior.	Behavior Trees: Can be overkill for simple state management and can be difficult to reason about the overall state of the system.
Hybrid Approaches: Combining FSMs with other patterns like Behavior Trees.	Hybrid Approaches: Can be overly complex and lead to "spaghetti code" if not carefully implemented.
State Pattern: Allows a context object to change its behavior depending on its internal state.	State Pattern: Can lead to a large number of classes for each state, which can be difficult to manage. Changes to the state machine often require changing multiple classes.

A Better Way: FSM_API and Centralized State

The FSM_API is a new approach to FSMs that is designed to be blazing-fast, software-agnostic, and fully decoupled from your application's logic. It's a declarative, data-driven approach that allows you to define your FSM once and use it everywhere.

The key 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.

Here's our door, refactored with the FSM_API.

1. Define the Context

Our Door class is now a simple POCO. All its logic is handled 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.

First, let's create a simple FSM to handle the door's opening and closing. This is the DoorFSM:

FSM_API.Create.CreateFiniteStateMachine("DoorFSM")
    .State("Closed", onEnter: (ctx) => { ((Door)ctx).IsOpen = false; })
    .State("Open", onEnter: (ctx) => { ((Door)ctx).IsOpen = true; })
    .WithInitialState("Closed")
    .Transition("Closed", "Open", (ctx) => !((Door)ctx).IsLocked)
    .Transition("Open", "Closed")
    .Transition("Closed", "Locked")
    .Transition("Locked", "Closed", (ctx) => !((Door)ctx).IsLocked)
    .Transition("Unlocked", "Closed")
    .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 is what makes the FSM_API a powerful choice for highly configurable or live-updating systems.

Here's an overview of the pros and cons of our API:

Pros	Cons
Centralized State: FSM logic is separated from data.	Learning Curve: New concepts might take time to grasp, especially if you are used to traditional FSM implementations.
Extremely Lightweight: The core FSM_API.dll is a tiny 45kb, and the full NuGet package is only 417.09kb.	Minimalism: The API is minimal by design; you will need to rely on the provided documentation and quick-start guides to get started.
Runtime Redefinition: FSMs can be modified on the fly.
Lightweight & Performant: Minimal memory allocations and optimized performance.
Framework Agnostic: No external dependencies or frameworks required.
Thread-Safe: Designed for safe, deferred mutation handling.
Error-Tolerant: Built-in diagnostics prevent runaway logic.

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: https://www.nuget.org/packages/TheSingularityWorkshop.FSM_API
GitHub Repository: https://github.com/TrentBest/FSM_API

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

DEV Community: Trent Best

FSM_API: The Pure C# Core That Decouples Your Logic from Any Engine

🧠 1. Decoupling Logic: The IStateContext Contract

This clear separation ensures your logic is reusable, and the system manages its own lifecycle.

⚙️ 2. Engine Agnosticism: Deployment Anywhere

This level of control is essential for server-side logic and custom engine environments where performance demands are high.

💡 3. Dynamic Power: Runtime Modification

This is the key to creating applications that can genuinely adapt and change on the fly, transforming static software into fluid, composable experiences.

🚀 Get Started with the Free Core

Stop Getting Blocked: How a Simple Design Pattern Unlocks Your Project's Complex Logic

The Power of a Structured Design: FSMs

Case Study: The Quick Brown Fox Demo

1. The Simulation Setup (SimpleDemoContext.cs)

2. Modeling the Fox: The QuickBrownFoxFSM

3. Interacting Agents: The LazyDogFSM

Your Takeaway: Design Before You Code

Get the FSM_API

The Singularity Workshop

A FSM Challenge for the c#/DotNet Dev Community

Introducing FSM_API

The Challenge: What Will You Create?

Get Started

From Chaos to Cohesion: A Retrospective on How FSMs Connect Us to Domain Experts

The Problem with Traditional FSMs

Translating Expertise into Code

The Paradigm Shift

Get the FSM_API

Engineering "The" Loop

The Problem with the Classic Game Loop 🎮

A Better Way: A State Machine-Driven Loop ✨

The API Evolution: From Simple to Dynamic 🚀

The Basic Approach: Direct Mapping

The Advanced Approach: Runtime Modifiable Loops

Comparison and Conclusion ⚖️

Conclusion: The Future is State-Driven 🤖

💖 Support Us

🔗 Useful Links

🧠 Brought to you by

Announcing The Singularity Workshop: A New FSM API for Unity

Join Our Journey

Finite State Machines - the Universal Unit of Work

The Typical FSM Solution and Its Pitfalls

A Better Way: FSM_API and Centralized State

1. Define the Context

2. Multiple FSMs on a Single Context

1. The Simulation Setup (`SimpleDemoContext.cs`)

2. Modeling the Fox: The `QuickBrownFoxFSM`

3. Interacting Agents: The `LazyDogFSM`

Get the `FSM_API`