Coder Legion - Recent posts tagged thesingularityworkshop

The Weekend After: HeadlessAi Has Entered the Workshop

Sat, 10 Oct 2026 06:54:10 +0000

Last weekend, we introduced some of the toys we're building at The Singularity Workshop. This weekend, we've got more! (All are c#)

HeadlessAi — Connecting .NET applications to AI endpoints through a straightforward, extensible interface.
Profiles — Exploring identity, relationships, privacy, and user-controlled data sharing.
Ontology — Organizing information in flexible, meaningful structures.
MicroBundleIngestor — Exploring new ways to bring MicroBundles into the ecosystem.
Economy — Beginning to explore the foundations of an interconnected digital economy.

So, what makes the Workshop different?

We don't just build packages and leave you to figure them out. We explain the what, why, and how behind them—from the underlying theory to practical examples you can learn from and build upon.

You don't have to be an expert programmer to start exploring. We're building an ecosystem designed to help you understand the technology, connect the pieces, and bring your own ideas to life.

Don't just use the tools. Learn to build with them.

Come explore: The Singularity Workshop on GitHub

It’s the Weekend. The Workshop Has Toys. Come Play.

Sat, 03 Oct 2026 07:14:18 +0000

It’s the weekend.

Instead of writing another 2,000-word manifesto on what The Singularity Workshop might become someday, I’m just going to open the toy box.

I’ve been building.

Some of it is foundational. Some of it is highly experimental. Some of it is definitely still alpha software. But enough of it has crossed the line from “whiteboard diagram” to running code that it’s time to put it out in public.

You can download it, read the source, compile it, and—most importantly—break it.

Where to Start: NuGet

The easiest way to see what is actually breathing right now is NuGet.

Search for TheSingularityWorkshop and make sure Include prerelease is enabled.

Search The Singularity Workshop packages on NuGet

Most of what I'm pushing right now is deliberately prerelease.

These aren't polished commercial products with a marketing department hiding the machinery behind a landing page. They are architectural experiments that have finally become real enough for someone else to get their hands dirty with.

That is exactly the point.

The Toy Box

Here is what is currently sitting on the workbench.

FSM_API

NuGet | GitHub

This is the bedrock.

The core premise is that behavior can be represented explicitly as state, allowing state-driven behavior to remain separate from the data objects it operates on.

FSM_API is a framework-agnostic C# finite-state-machine system with explicit state definitions, transitions, contexts, processing groups, lifecycle handling, and runtime behavior.

If you want to start at the absolute beginning of the Workshop, start here.

This is where the behavior machinery begins.

FSM_COS

NuGet | GitHub

This is where the pieces start becoming a system.

FSM_COS is the composition kernel.

A runtime manifest says what is requested. FSM_COS resolves the MicroBundle dependency closure, propagates configuration, loads the required capabilities, arbitrates them toward convergence, and produces a RuntimeAssembly.

Conceptually:

Runtime Manifest
       |
       v
    FSM_COS
       |
       +-- resolve MicroBundles
       +-- resolve dependencies
       +-- propagate configuration
       +-- load/install
       +-- arbitrate
       +-- converge
       |
       v
RuntimeAssembly
       |
       v
host / manifestation

The important part is what FSM_COS doesn't do.

It doesn't become the application.

It doesn't become the GUI.

It doesn't become the storage system.

It doesn't become the Experience.

It assembles the machine and hands the resulting composition to something else.

The crane doesn't become the machine.

MicroBundleDomain

NuGet | GitHub

This one is particularly important to the architecture.

MicroBundleDomain is a neutral contract for independently authored capabilities.

A MicroBundle is a focused unit of capability that can identify itself, declare dependencies and providers, accept configuration, enter a runtime, and participate in composition without requiring the host to understand its private domain.

The important architectural separation is:

What is this capability?
        |
        v
MicroBundleDomain

Where do I get it?
        |
        v
MicroBundleRepository

How do I compose it?
        |
        v
FSM_COS

That means MicroBundleDomain does not belong underneath FSM_COS as an implementation dependency.

It is the neutral seam.

That matters because someone should be able to author a capability without permanently welding their package to my composition engine.

MicroBundleRepository

GitHub

If MicroBundleDomain answers what, the Repository answers where.

The repository explores durable delivery of versioned MicroBundle artifacts, currently using Azure Blob Storage as the storage substrate.

The distinction is deliberately sharp:

Blob Storage
    = substrate

Repository
    = artifact delivery boundary

FSM_COS
    = composition boundary

Artifacts have deterministic identity based on the MicroBundle ID, explicit version, and SHA-256 content identity.

The repository doesn't become a database.

It doesn't arbitrate.

It doesn't compose Experiences.

It doesn't become a GUI.

It answers a much smaller question:

Given this artifact address, where are the bytes and can I verify them?

I am having entirely too much fun ruthlessly separating these concerns.

GUI

GitHub

There is a platform-neutral GUI core in here, alongside manifestations for Blazor and WPF.

But the real experiment isn't drawing buttons.

It's asking:

Can an object describe itself structurally well enough that a generic GUI can just render it?

That led to a reflection-driven GUI architecture where the domain model doesn't need to know about the editor that happens to display it.

The basic idea is:

Domain model
     |
     | describes itself
     v
Reflection / semantic projection
     |
     v
GUI.Core
     |
     +--------+--------+
     v                 v
  Blazor              WPF

So if you're interested in semantic interface construction, reflection, recursive GUI structures, and separating what something means from how it looks, poke around in this one.

There is considerably more going on here than “make a button.”

FSM_Serialization

NuGet | GitHub

This isn't an experiment in shouting “my serializer is the fastest.”

It's an experiment in strict ownership.

The domain owns what its data means.

The serialization layer owns how that data crosses a byte boundary.

The host decides where those bytes ultimately go.

The package deliberately stays out of databases, filesystems, HTTP, application configuration, object-graph magic, and other concerns that belong somewhere else.

It's small, tight, and opinionated.

I wrote a deeper dive on this one:

I Built a Serializer That Refuses to Own Your Data

FSM_REST

GitHub

This isn't another web framework.

FSM_REST provides a reusable boundary for describing and composing REST capabilities.

The interesting part is that a REST capability can be represented as a capability recipe rather than dragging an entire web application into the runtime.

Conceptually:

REST capability
      |
      v
FSM_REST
      |
      +-- capability description
      +-- request construction
      +-- transport boundary
      |
      v
remote API
      |
      v
current data

The MicroBundle can describe what is needed to obtain the capability without pretending that the remote API's current response data belongs inside the bundle.

That distinction becomes increasingly useful when capabilities are composed dynamically.

ProtocolAI & GrammarAI

ProtocolAI: GitHub
GrammarAI: GitHub

These sound like AI wrappers.

They aren't.

They explore the boundary where deterministic application-owned meaning meets probabilistic language models.

ProtocolAI is the WHAT.

It gives application-owned meaning a deterministic semantic address space.

GrammarAI is the HOW.

It gives those identities a structural language for describing how they can be connected.

LLM
 |
 | probability
 v
ProtocolAI
   WHAT
 |
 v
GrammarAI
   HOW
 |
 v
host / adapter
 |
 v
application

There is deliberately no LLM hidden inside either package.

No provider SDK.

No inference engine.

No chatbot.

No API-key management.

The application owns the meaning.

The model supplies probability.

The deterministic boundary sits in between.

I wrote more about the idea here:

ProtocolAI and GrammarAI: Giving AI a Language Software Can Actually Own

The Hosts

Architecture diagrams are great.

Eventually, though, somebody has to push a button.

AnyApp

GitHub

AnyApp is the desktop proof of the composition architecture.

It is the Windows desktop counterpart to the browser-facing WebPage/WebForge host.

The important part is that AnyApp is trying very hard to remain a host, rather than becoming an application-specific framework.

Startup is now manifest-driven:

AnyApp
  |
  v
startup / last Experience
  |
  v
Forge fallback when necessary
  |
  v
FSM_COS
  |
  v
RuntimeAssembly
  |
  v
host manifestation

The host doesn't need to know every Experience it might eventually run.

It hosts the composition.

That's the experiment.

And yes, the current window is tiny.

That's part of the fun.

WebPage

GitHub

This is the public proving ground.

WebPage is the ephemeral web manifestation of the larger Workshop: public-facing surface, demonstration environment, and experimental place where the architecture gets to meet an actual visitor.

The guiding idea is simple:

Make the mundane magical. Then show the machinery that made it possible.

Instead of merely putting diagrams on a webpage explaining that the GUI is dynamic, the page itself should eventually behave dynamically.

A button can breathe.

A GUI can reproduce.

The reproduction can become a swarm.

The swarm can overwhelm the screen.

The system can freeze.

Gravity can take over.

And suddenly the visitor isn't just reading about the architecture anymore.

They're watching the architecture become the experience.

That's what the WebPage repository is for.

You Don't Need to Understand All of This

Seriously.

You don't need to read every README.

You don't need to understand FSM_COS before touching FSM_API.

You don't need to understand MicroBundle arbitration before playing with the GUI.

You certainly don't need to agree with my architecture.

You don't need to know what a “semantic address space” is.

You don't need to know what “arbitration” means.

You don't even need to know why I keep naming things with increasingly suspicious acronyms.

Just pick one piece that looks interesting.

Install it.

Read the source.

Build a tiny experiment.

Benchmark it.

Break it.

Tell me why it's broken.

That is the entire point of publishing early.

Software has to meet reality.

And reality includes other developers.

Some APIs will change.

Some experiments will become load-bearing infrastructure.

Some ideas that seem perfectly reasonable right now will probably turn out to be terrible.

Some will get thrown away.

That's normal.

Actually, that's part of the process.

The important thing is that these aren't only diagrams anymore.

They're code.

They're packages.

They're repositories.

They're things you can actually touch.

The Workshop Is Open

So, that's the current toy box.

Not everything is finished.

Not everything is stable.

Not everything is even guaranteed to survive.

That's why I'm putting it out now.

If something catches your eye, go play with it.

And if you find something interesting, confusing, inefficient, backwards, brilliant, terrible, or just plain weird—

tell me.

That's how experiments turn into software.

And how software turns into infrastructure.

The toy box is open.

It's the weekend. Come play.

Support Our Work:

Patreon Page:
[https://www.patreon.com/c/TheSingularityWorkshop][1]

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

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

ProtocolAI and GrammarAI: Giving AI a Language Software Can Actually Own

Tue, 29 Sep 2026 22:13:13 +0000

There is a particular problem that keeps appearing as I build the architecture for The Singularity Workshop.

It starts with something that sounds almost trivial:

How does software communicate with an AI when the software already knows what its world means?

An LLM is very good at language.

It can interpret a request, generate possibilities, describe relationships, and produce something that looks structurally correct.

But there is a boundary where the application has to take over.

The application needs to know exactly what something refers to.

And then it needs to know how those things may be connected.

That is where two small packages have emerged:

ProtocolAI — the WHAT
GrammarAI — the HOW

They are deliberately separate.

And neither one is the AI.

The Problem Starts With Probability

An LLM operates in a probabilistic space.

That is not a criticism. It is the nature of the technology.

Given some context, the model produces a candidate response.

That candidate may be exactly what we wanted.

It may also be something new.

Or something that looks familiar but does not actually identify the same object the application already knows.

Imagine an application that already knows three people:

Bob
Jane
Sara

The application has meaning attached to those names.

The model does not own that meaning.

It can produce "Bob".

But the application needs to turn that representation into something deterministic.

That is the boundary ProtocolAI explores.

probabilistic language
        |
        v
     candidate
        |
        v
    ProtocolAI
        |
    +---+---+
    |       |
  known   unknown
    |       |
    v       v
 integer   literal
    |       |
    +---+---+
        |
        v
application-owned identity

The model proposes.

The application decides.

ProtocolAI provides the semantic address space between those two worlds.

ProtocolAI: The WHAT

The core idea behind ProtocolAI is surprisingly small.

A protocol owns a vocabulary.

For example:

[1001] People

[2001] bobId  = "Bob"
[2002] janeId = "Jane"
[2003] saraId = "Sara"

Now the application has an address space.

"Bob"   -> [2001]
"Jane"  -> [2002]
"Sara"  -> [2003]

The integer is not the meaning.

It is the address of the meaning.

That distinction is important.

ProtocolAI does not replace the domain object.

It does not become the database.

It does not become the authority that decides what Bob is allowed to do.

It simply establishes a deterministic identity that the application owns.

The Literal Escape Hatch

There is another important detail.

What happens when the model produces something the application does not already know?

Suppose the vocabulary contains:

[2001] Bob
[2002] Jane

and the model produces:

"Amelia"

The protocol should not have to pretend Amelia already exists.

So ProtocolAI preserves the literal.

[2001] [2002] "Amelia"

That gives the host a choice.

The host can decide whether Amelia should be:

created;
registered;
rejected;
authorized;
deferred;
or otherwise handled.

That is a much more interesting boundary than simply forcing everything into a closed enumeration.

Known things become references.

Unknown things remain visible as unknown.

This Is Not Just About Compression

It would be easy to look at integer identities and conclude that this is merely an optimization.

Smaller values.

Smaller payloads.

Faster lookup.

Those may eventually be useful properties.

But that is not the fundamental idea.

The more important separation is:

Meaning
   |
   v
Identity
   |
   v
Representation

Consider:

Meaning:        Bob
Symbol name:    bobId
Symbol ID:      2001
Protocol ID:    1001
Payload form:   [2001]

The application already owns the meaning.

ProtocolAI gives that meaning an explicit address.

That address can then survive across interactions.

Prompt
"Bob"
   |
   v
[2001]
   |
   v
Response
[2001]
   |
   v
Next interaction
[2001]

The model does not have to repeatedly rediscover that two strings refer to the same application-owned identity.

Again, that is an architectural direction rather than a claim that integer identities automatically make an LLM reason better.

The point is that the application has a semantic address space.

And Then I Ran Into the Next Problem

A vocabulary is useful.

But a vocabulary is not a language.

Knowing:

[2001] Bob
[2002] Jane

does not tell us how those identities may be arranged.

We need another layer.

Something has to describe relationships such as:

this kind of thing
    |
    +--> may contain this
    |
    +--> may reference that
    |
    +--> may be followed by another structure

That is where GrammarAI enters.

GrammarAI: The HOW

GrammarAI takes the identities supplied by ProtocolAI and gives them a structural language.

The distinction is intentionally simple:

ProtocolAI defines the WHAT. GrammarAI defines the HOW.

For example:

ProtocolAI

[1001] People

[2001] Bob
[2002] Jane

GrammarAI can define a structure that references those identities:

[4001] -> [1001:2001]
[4001] -> [1001:2002]

Now we have two different owners.

[1001:2001]
    |
    +--> ProtocolAI owns the meaning

[4001]
    |
    +--> GrammarAI owns the structural position

That separation is deliberate.

GrammarAI does not copy Bob into itself.

It references the protocol that owns Bob.

A Grammar Is a Relationship System

This is the part I find particularly interesting.

A grammar is not another dictionary.

It is a relationship system.

It can say:

Grammar nonterminal
       |
       v
     [4001]
       |
       +----> [1001:2001]
       |
       +----> [1001:2002]

The grammar owns the relationship.

The protocol owns the thing being referenced.

That gives us a clean composition boundary.

Protocol A
    |
    +-- symbols

Protocol B
    |
    +-- symbols

       \       /
        \     /
         \   /
        Grammar
           |
           +-- structure
           +-- relationships
           +-- references

The grammar connects things without becoming the owner of those things.

Why Integer-Backed Structure?

There is another common thread between the two packages.

Both are self-defining.

A GrammarAI definition has its own identity:

[3001] Greeting

It has a start symbol:

start = [4001]

And it has production rules:

[5001] [4001] -> [1001:2001]
[5002] [4001] -> [1001:2002]

That means the grammar itself can become a piece of data.

It can eventually be:

described;
serialized;
compared;
versioned;
generated;
visualized;
translated;
supplied to another composition layer.

The grammar does not need to know which of those things will happen.

That is the point of keeping it small.

The AI Still Isn't the Authority

This is probably the most important part of the architecture.

The LLM does not become the owner of the protocol.

The LLM does not become the owner of the grammar.

And the LLM does not become the application's execution authority.

The flow is closer to:

              LLM
               |
          probabilistic
            candidate
               |
               v
          ProtocolAI
             WHAT
               |
               v
           GrammarAI
              HOW
               |
               v
        host validation
               |
               v
       application decision
               |
               v
       deterministic state

The model participates.

It does not rule the system.

That distinction becomes increasingly important as AI systems begin interacting with real applications rather than simply generating text.

This Is the Same Boundary I Keep Finding Elsewhere

Consider a reservation system.

User A requests the last available table.

The centralized authority accepts the reservation.

Users B through K arrive almost immediately afterward.

The system does not need to tell User K:

Failure.

That is technically accurate but semantically terrible.

The actual state is:

You cannot acquire the resource right now.

So the system can return something closer to:

Resource unavailable.

You are currently #10 in the waiting queue.
There are 9 requests ahead of you.

That is an inability, not necessarily a failure.

The system has preserved useful information about the state of the world.

And that is the kind of distinction these AI packages are trying to preserve as well.

An LLM can produce a candidate.

ProtocolAI determines whether that candidate corresponds to a known application identity.

GrammarAI determines whether that identity participates in a valid structure.

The host then decides what that structure means operationally.

At every step, we preserve the distinction between:

what was proposed
what is known
what is structurally valid
what is currently possible
what the application actually decides to do

That is much more useful than collapsing everything into true or false.

ProtocolAI and GrammarAI Are Deliberately Not an AI Framework

This is where the package boundaries become important.

ProtocolAI is not:

an LLM;
an AI provider;
a prompt framework;
a schema validator;
a database;
a grammar compiler;
a command executor;
a GUI framework;
a MicroBundle host.

GrammarAI is not:

an LLM client;
model selection;
tokenization;
inference;
prompt transport;
protocol vocabulary ownership;
MicroBundle hosting;
REST/OpenAPI;
GUI manifestation;
tool execution.

That list may look like a lot of things to leave out.

That is intentional.

The packages are supposed to provide semantic infrastructure, not become another giant AI framework.

The Exchange Layer Comes Later

ProtocolAI already describes an interesting future boundary for AI interaction.

The same semantic exchange should eventually work through either:

             AI Exchange
                 |
        +--------+--------+
        |                 |
    Clipboard         Provider
        |              Adapter
        |                 |
        +--------+--------+
                 |
                LLM

Clipboard interaction is not treated as a second protocol.

It is simply another transport.

A developer could extract:

Protocol
Grammar
Context
Request

copy that into an LLM, receive a response, and paste it back.

A connected provider could perform the same semantic exchange programmatically.

The transport changes.

The semantic boundary does not.

That is an important distinction.

Context Is Not Authority

An AI exchange might eventually contain a substantial amount of information:

current Experience
selected objects
available commands
protocol descriptions
grammar definitions
current state
previous interactions
host capabilities

But none of that means the model has authority.

The intended boundary remains:

MODEL OUTPUT
     |
     v
parse / validate
     |
     v
ProtocolAI resolution
     |
     v
host policy
     |
 +---+---+---+---+
 |   |   |   |   |
accept reject clarify create execute

The model proposes.

The host decides.

ProtocolAI makes owned meaning addressable.

GrammarAI makes the relationships between those meanings describable.

And This Is Where the Larger Workshop Architecture Appears

The two packages are small individually.

But together they establish another layer in the larger architecture I have been building.

Domain meaning
      |
      v
ProtocolAI
    WHAT
      |
      v
GrammarAI
    HOW
      |
      v
AI / provider adapter
      |
      v
Host
      |
      v
FSM / GUI / Experience

And eventually, those capabilities can participate in the MicroBundle architecture.

That means the AI layer does not have to become a special universe disconnected from the rest of the system.

It can become another collection of capabilities that the host can compose.

The Interesting Part Is the Separation

There is a temptation when building AI software to put everything in one place.

The model client.

The prompts.

The schemas.

The grammar.

The commands.

The domain objects.

The execution engine.

The UI.

The credentials.

The networking.

Eventually you have an enormous framework that knows everything about everything.

I am deliberately going in the other direction.

ProtocolAI knows about semantic identity.

GrammarAI knows about semantic structure.

The host knows about execution.

The provider adapter knows about transport.

The application knows about meaning and authority.

That makes the pieces composable.

Where the Alpha Actually Stands

These packages are intentionally early.

ProtocolAI 0.1.0-alpha.2 currently establishes:

self-defining integer-backed vocabularies;
protocol-qualified identity;
known-value encoding;
literal preservation;
deterministic descriptions;
ordered mixed payloads;
payload validation;
mixed reference/literal resolution.

GrammarAI 0.1.0-alpha.1 currently establishes:

grammar identity;
integer start symbols;
integer nonterminals;
ordered production rules;
external ProtocolAI references;
deterministic self-description;
validation of referenced nonterminals.

Neither package currently implements the entire AI pipeline.

And that is okay.

The unanswered questions are actually interesting architectural questions.

For example:

Who allocates new symbol IDs?

How do identities persist?

How are protocols versioned?

How are protocols negotiated?

How are grammars versioned?

How are recursive productions handled?

How does an abstract grammar become a provider-specific constraint?

How do we validate generated model output?

How does a semantic artifact become executable behavior?

Those questions should be solved by the architecture.

They should not be hidden inside convenience APIs simply because the API would look nicer.

The Bigger Experiment

What I am really exploring here is a progression.

human / domain language
          |
          v
    self-defining lexicon
          |
          v
     integer identity
          |
          v
    grammar / structure
          |
          v
       protocol
          |
          v
     tool execution
          |
          v
       experience

ProtocolAI is the first semantic compression boundary.

GrammarAI is the next structural boundary.

Neither is trying to replace human language.

Neither is trying to make an LLM deterministic.

Instead, they give software something it has always needed:

a precise address space for meanings that the software itself owns.

And once those meanings have addresses, and those addresses have structure, we have something much more interesting than an AI prompt.

We have the beginning of a language that the application can actually own.

The Current Workshop Stack

The current direction now looks something like this:

                    LLM
                     |
              probability
                     |
                     v
               ProtocolAI
                  WHAT
                     |
                     v
                GrammarAI
                   HOW
                     |
                     v
             AI / Host Adapter
                     |
                     v
                  Host
                     |
                     v
                FSM_COS
                     |
              MicroBundles
                     |
                     v
              RuntimeAssembly
                     |
                     v
            GUI / Experience
                     |
                     v
             Digital Reality

The interesting part is that the model remains at the edge.

The application owns the center.

That is where I want the architecture to live.

Resources

Support The Singularity Workshop

If this work is useful to you, and you'd like to help keep The Singularity Workshop moving, you can support its continued development:

Patreon: Support The Singularity Workshop
PayPal: Make a donation

Every bit of support helps provide more time and resources for building, testing, documenting, and publishing the architecture.

The Singularity Workshop — Tools for the curious, the bold, and the systemically inclined.
Because state shouldn't be a mess.

I Built a Serializer That Refuses to Own Your Data

Mon, 28 Sep 2026 23:36:42 +0000

I Built a Serializer That Refuses to Own Your Data

How The Singularity Workshop turned a recurring binary-IO problem into a tiny .NET boundary—and why the smallest part of the design may be the most important part.

There is a particular kind of software problem that appears harmless at first.

You have some state.

You need to turn it into bytes.

So you write a serializer.

Then another part of the application needs bytes, so you add another serializer.

Then a cache needs them.

Then a manifest needs them.

Then a transport layer needs them.

Then somebody decides JSON is better here, binary is better there, and suddenly the architecture has six different opinions about what a piece of data is.

That was the problem I was running into while building The Singularity Workshop.

The interesting part is that I didn't actually need a giant serialization framework.

I needed a boundary.

So I built one.

It is called:

TheSingularityWorkshop.FSM_Serialization

And it is deliberately small.

That is the point.

The Problem Wasn't Turning Objects Into Bytes

Serialization is usually described as a mechanical operation:

object → serializer → bytes

That description hides something important.

An object has meaning.

Bytes do not.

Bytes are a representation of meaning.

That distinction becomes increasingly important as an architecture grows.

The Workshop ecosystem is being built around several deliberately separated responsibilities:

FSM_API
    │
    │ behavior and state
    ▼
FSM_COS
    │
    │ composition and runtime assembly
    ▼
FSM_Serialization
    │
    │ representation
    ▼
storage / transport / host

I didn't want FSM_COS to become a serializer.

I didn't want a MicroBundle to have to know how a filesystem works.

I didn't want a database abstraction hiding inside a representation layer.

And I definitely didn't want every higher-level system inventing its own binary stream interface.

So I extracted the smallest reusable boundary I could identify.

That boundary became FSM_Serialization.

The First Design Decision

The most important rule in the package is also the simplest:

The type that owns the meaning should own the representation rules.

FSM_Serialization provides the machinery for crossing the byte boundary.

It does not decide what your data means.

That means the package doesn't contain some enormous reflection-based object graph engine that looks at your class and decides what should be serialized.

Instead, the type explicitly says:

public interface IBinaryPackable
{
    void Pack(IBinaryStream stream);
}

And the reverse direction is equally explicit:

public interface IBinaryUnpackable
{
    void Unpack(IBinaryStream stream);
}

If a type needs both:

public interface IBinarySerializable :
    IBinaryPackable,
    IBinaryUnpackable
{
}

That's the entire conceptual model.

No magic.

No global serializer registry.

No reflection-based guesswork.

No framework deciding that a private field suddenly became part of your persistent format.

The domain owns that decision.

Why I Didn't Just Use `System.IO.Stream`

This is probably the first question a .NET developer will ask.

And honestly, it is a good question.

.NET already has System.IO.Stream.

Why introduce another interface?

Because I wasn't trying to replace Stream.

I was trying to establish a package-owned contract.

The current abstraction is:

public interface IBinaryStream : IDisposable
{
    bool CanRead { get; }
    bool CanWrite { get; }

    long Position { get; set; }
    long Length { get; }

    int Read(Span<byte> buffer);
    void Write(ReadOnlySpan<byte> buffer);
    void Flush();
}

Notice what isn't there.

There is no:

filename;
filesystem;
database;
socket;
HTTP request;
serializer registry;
schema;
domain metadata;
application configuration.

The interface only knows about the byte boundary.

That makes it possible to write serialization code against one very small abstraction while letting the host decide what is actually underneath it.

The Two Directions Matter

There is another small decision here that I think becomes important in larger systems.

Packing and unpacking are separate capabilities.

A type that produces a representation does not necessarily need to consume one.

Likewise, a type may consume a representation without being responsible for producing it.

So the package doesn't force everything into one giant:

Serialize()
Deserialize()

method.

Instead:

                 DOMAIN TYPE
                     │
          ┌──────────┴──────────┐
          │                     │
        Pack                  Unpack
          │                     │
          ▼                     ▲
     representation          representation
          │                     │
          └──────────┬──────────┘
                     ▼
                byte stream

That separation costs almost nothing.

But architecturally, it keeps the ownership visible.

The Smallest Possible Example

Let's make this concrete.

Imagine a domain object containing one integer.

That's intentionally boring.

Boring is useful here because it lets us see exactly where the responsibility lives.

using System.Buffers.Binary;
using TheSingularityWorkshop.FSM_Serialization;

public sealed class ExampleState : IBinarySerializable
{
    public int Value { get; private set; }

    public ExampleState()
    {
    }

    public ExampleState(int value)
    {
        Value = value;
    }

    public void Pack(IBinaryStream stream)
    {
        Span<byte> buffer = stackalloc byte[sizeof(int)];

        BinaryPrimitives.WriteInt32LittleEndian(
            buffer,
            Value);

        stream.Write(buffer);
    }

    public void Unpack(IBinaryStream stream)
    {
        Span<byte> buffer = stackalloc byte[sizeof(int)];

        if (stream.Read(buffer) != buffer.Length)
            throw new EndOfStreamException();

        Value = BinaryPrimitives.ReadInt32LittleEndian(buffer);
    }
}

There is no serializer object.

There is no configuration object.

There is no registration step.

The object itself defines its representation.

That is intentional.

Now Let's Actually Serialize Something

The package includes MemoryBinaryStream, which is exactly what it sounds like: an in-memory implementation of IBinaryStream.

That makes testing and temporary representations extremely simple.

using var stream = new MemoryBinaryStream();

var original = new ExampleState(42);

original.Pack(stream);

stream.Position = 0;

var restored = new ExampleState();

restored.Unpack(stream);

Console.WriteLine(restored.Value);

Output:

That's it.

The complete flow is:

ExampleState
     │
     │ Pack
     ▼
MemoryBinaryStream
     │
     │ bytes
     ▼
Position = 0
     │
     │ Unpack
     ▼
ExampleState

The package supplied the boundary.

The domain supplied the meaning.

Installation

If you want to try it yourself, the current published alpha is:

dotnet add package TheSingularityWorkshop.FSM_Serialization --version 0.1.0-alpha.2

Or:

<PackageReference
    Include="TheSingularityWorkshop.FSM_Serialization"
    Version="0.1.0-alpha.2" />

The current package targets .NET 8.

This is intentionally an alpha release.

That doesn't mean the contracts are casual.

Quite the opposite.

A binary representation is one of those things where small assumptions can become enormous compatibility problems later.

So I'm treating the package as alpha while treating its architectural boundaries seriously.

What About Real Files?

This is where StreamBinaryStream enters.

The package includes an adapter around an ordinary .NET Stream:

using var file = File.OpenRead("state.bin");
using var stream = new StreamBinaryStream(file);

Now the same domain serialization code can operate against the package abstraction without knowing that a file exists.

The relationship is:

ExampleState
     │
     ▼
IBinaryStream
     │
     ▼
StreamBinaryStream
     │
     ▼
System.IO.Stream
     │
     ▼
file / memory / whatever the host provides

That is a very different architecture from:

ExampleState
     │
     ▼
ExampleStateSerializer
     │
     ▼
FileSystemSerializerManager
     │
     ▼
ApplicationStorageService

The latter might be useful somewhere.

It just doesn't belong in this package.

The Stream Adapter Is Supposed to Be Boring

This is one of those cases where boring code is a compliment.

StreamBinaryStream essentially delegates:

public int Read(Span<byte> buffer)
    => _stream.Read(buffer);

public void Write(ReadOnlySpan<byte> buffer)
    => _stream.Write(buffer);

public void Flush()
    => _stream.Flush();

That's not a weakness.

It's the point.

The adapter is not supposed to invent behavior.

It establishes a stable contract between two layers.

Then I Ran Into a Very Important Detail

A byte stream is not the same thing as an array.

This matters:

int count = stream.Read(buffer);

You cannot blindly assume:

count == buffer.Length

So a fixed-width decoder in FSM_Serialization explicitly checks:

if (stream.Read(buffer) != buffer.Length)
    throw new EndOfStreamException();

That may look like a tiny implementation detail.

It isn't.

It establishes an architectural rule:

Never interpret an incomplete representation as a complete value.

The serializer shouldn't quietly manufacture missing data.

If the representation is incomplete, the domain implementation gets to decide what that means.

In the current examples, that means rejecting it.

Serialization Is Not Storage

This distinction became increasingly important as the Workshop architecture grew.

Consider these questions:

Serialization

How are these values represented as bytes?

Storage

Where do those bytes live?

Transport

How do those bytes move between boundaries?

Those are three different questions.

So:

                 SEMANTIC DATA
                      │
                      ▼
                representation
                      │
                      ▼
              FSM_Serialization
                      │
              ┌───────┴───────┐
              ▼               ▼
           storage         transport

A database is not a serializer.

A filesystem is not a serializer.

An HTTP endpoint is not a serializer.

A cache is not a serializer.

They may all consume serialized data.

That doesn't make them the same architectural layer.

This is exactly the kind of distinction that seems unnecessary when an application is small and becomes incredibly valuable when an ecosystem starts growing.

Why Binary?

I am not claiming that binary is universally superior to JSON.

It isn't.

JSON is fantastic for many things.

Text is fantastic for many things.

Human-readable configuration is valuable.

Debugging matters.

Authoring matters.

Interoperability with external systems matters.

The reason I created this package is narrower.

There are situations where I want an explicit, compact, byte-oriented representation.

For example:

runtime state;
manifests;
dependency metadata;
compact configuration;
cache entries;
identity records;
version records;
lineage metadata;
persistence;
transport payloads.

The important thing is that the semantic model shouldn't have to become identical to its wire representation.

Deterministic Does Not Mean Magical

The package's NuGet description talks about deterministic binary serialization.

There is an important qualification.

Implementing:

IBinaryPackable

does not magically make your representation deterministic.

You have to define deterministic rules.

For example, suppose your object contains a collection that is semantically unordered.

If you serialize it in whatever order happens to be present at runtime, two semantically identical objects could produce different byte sequences.

If deterministic bytes matter, the domain needs something like:

semantic collection
        │
        ▼
canonical ordering
        │
        ▼
explicit representation
        │
        ▼
deterministic bytes

That distinction matters if bytes are later used for:

caching;
content identity;
synchronization;
comparison;
reproducible builds;
lineage;
integrity checks.

Again, the package supplies the boundary.

It does not pretend to know your domain's canonical ordering rules.

Versioning Gets Interesting

This is another reason I didn't want a magical object serializer.

Once bytes leave your process, they can outlive the code that created them.

Imagine:

Application v1
      │
      ▼
    bytes
      │
      │ time passes
      ▼
Application v2

What happens?

That is a representation contract question.

A durable binary format may need to distinguish between:

semantic object version
format version
dependency version

Those are not necessarily the same thing.

Your semantic object can change while the representation remains compatible.

Your representation can change while the semantic concept remains the same.

A dependency can change independently of both.

FSM_Serialization intentionally doesn't impose one universal versioning strategy.

Different domains need different compatibility policies.

What it does is make the boundary explicit enough that you can actually have that conversation.

The Package Came From a Real Application

This is probably the most important part of the story.

FSM_Serialization wasn't created because I thought:

"The world needs another serialization library."

There are already plenty of serialization libraries.

The package emerged from building the Workshop itself.

The development pattern was:

working application
       │
       │ repeated infrastructure appears
       ▼
explicit contract
       │
       │ extract
       ▼
reusable package
       │
       │ consume again
       ▼
working application

That distinction matters.

I wasn't trying to abstract everything before I had a reason to abstract it.

The application became the proving ground.

Once the boundary became clear, I extracted it.

That is a much healthier way to create infrastructure.

And This Is Where FSM_COS Enters the Story

The larger ecosystem is becoming increasingly compositional.

FSM_COS is concerned with questions like:

What runtime composition was requested?

Which MicroBundles are required?

What dependencies are reachable?

How do those capabilities reconcile?

When is the composition stable enough to hand to a host?

FSM_Serialization answers a different question:

How do we represent the values that need to cross a byte boundary?

That means a future conceptual flow can look something like:

Runtime Manifest
      │
      ▼
    FSM_COS
      │
      │ composition
      ▼
Runtime Assembly
      │
      │ representation
      ▼
FSM_Serialization
      │
      ▼
     bytes

And then those bytes might eventually go somewhere else:

                 FSM_Serialization
                        │
             ┌──────────┼──────────┐
             ▼          ▼          ▼
          storage    transport    cache
             │          │          │
             └──────────┼──────────┘
                        ▼
                      host

The serializer doesn't become FSM_COS.

FSM_COS doesn't become a serializer.

That separation is exactly what I'm trying to preserve.

The Tests Tell the Same Story

The package currently has a deliberately small test surface.

It verifies things such as:

an empty MemoryBinaryStream is readable and writable;
bytes survive a write/read round trip;
existing byte arrays can initialize a memory stream;
null input is rejected;
end-of-input returns zero;
positioning and overwriting work;
StreamBinaryStream delegates correctly;
null wrapped streams are rejected;
writes reach the underlying stream;
IBinaryPackable and IBinaryUnpackable can round-trip;
IBinarySerializable combines both contracts;
incomplete binary input is rejected.

One of the tests is essentially the entire architectural idea in executable form:

var original = new TestValue(123456789);

using var stream = new MemoryBinaryStream();

original.Pack(stream);

stream.Position = 0;

var restored = new TestValue();

restored.Unpack(stream);

Assert.Equal(original.Value, restored.Value);

Tests aren't merely protecting the implementation here.

They are defining the boundary.

I Also Benchmarked It

Because eventually somebody is going to ask:

"Okay, but what does that abstraction cost?"

Good.

Let's measure it.

The companion benchmark project uses BenchmarkDotNet against .NET 8 and exercises payloads from 16 bytes through 100,000 bytes.

The interesting result isn't that FSM_Serialization magically beats MemoryStream.

It doesn't.

That's not what I was trying to prove.

The useful result is that the abstraction can remain extremely close to the underlying primitive for substantial workloads.

At 100,000 bytes, the benchmark measured approximately:

MemoryStream write:
39,894.85 ns

MemoryBinaryStream write:
40,005.59 ns

That's effectively the same scale.

Likewise, the adapter path was approximately:

MemoryStream read:
2,272.47 ns

StreamBinaryStream read:
2,298.40 ns

Again, very close.

And the end-to-end IBinarySerializable benchmark measured:

16 bytes       64.08 ns
1,024 bytes   207.47 ns
10,000 bytes  1,481.61 ns
100,000 bytes 60,152.74 ns

But there is an important qualification.

The benchmark measures the whole operation, including things like creating the test value, creating the stream, packing, rewinding, allocating the destination payload, and unpacking.

So I'm not going to pretend those numbers represent some universal "serialization speed."

They represent a measured workload.

That's much more useful.

The Benchmark Question I Actually Care About

The interesting engineering question isn't:

"Is my interface faster than MemoryStream?"

The interface isn't supposed to be the star of the show.

The question is:

Can I establish a useful architectural boundary without making the underlying operation prohibitively expensive?

The current measurements suggest that, for these workloads, the answer is yes.

And that's exactly where I want infrastructure to live.

The abstraction should be visible architecturally and nearly invisible computationally.

What I Deliberately Did Not Build

This may be the most important section of the entire package.

FSM_Serialization should not become:

an FSM engine;
a game framework;
a GUI framework;
a browser framework;
a Unity integration layer;
a database abstraction;
a filesystem framework;
an HTTP client;
an application configuration system;
a MicroBundle implementation;
an Experience runtime;
a reflection-driven object graph serializer;
a global serializer registry.

Those things may all be useful.

They just aren't this thing.

That restraint is part of the architecture.

A small package becomes powerful when other systems can depend on it without having to inherit the systems it was never supposed to understand.

So What Would You Actually Use It For?

If you're building a .NET application and you have a domain type whose state needs to cross a byte-oriented boundary, the starting point is incredibly small.

Install the package:

dotnet add package TheSingularityWorkshop.FSM_Serialization --version 0.1.0-alpha.2

Define your representation:

public sealed class MyState : IBinarySerializable
{
    public int Id { get; set; }

    public void Pack(IBinaryStream stream)
    {
        Span<byte> buffer = stackalloc byte[sizeof(int)];

        BinaryPrimitives.WriteInt32LittleEndian(
            buffer,
            Id);

        stream.Write(buffer);
    }

    public void Unpack(IBinaryStream stream)
    {
        Span<byte> buffer = stackalloc byte[sizeof(int)];

        if (stream.Read(buffer) != buffer.Length)
            throw new EndOfStreamException();

        Id = BinaryPrimitives.ReadInt32LittleEndian(buffer);
    }
}

Use memory when you need a temporary representation:

using var stream = new MemoryBinaryStream();

state.Pack(stream);

byte[] bytes = stream.ToArray();

Use a normal .NET stream when the host provides one:

using var file = File.Create("state.bin");
using var stream = new StreamBinaryStream(file);

state.Pack(stream);

And that's basically the entire learning curve.

The difficult part isn't learning the API.

The difficult part is deciding what your domain actually means by its representation.

I think that's exactly where the difficult part belongs.

A Serializer Shouldn't Become Your Architecture

This is the idea that kept resurfacing while I built the package.

It's very easy for infrastructure to become the thing it was supposed to merely support.

A serializer starts storing metadata.

Then it starts deciding schemas.

Then it starts managing versions.

Then it starts talking to databases.

Then it starts managing transports.

Then it starts discovering domain types.

Eventually your "serialization library" is quietly running your architecture.

I wanted the opposite.

I wanted something I could put underneath the architecture and forget about until I actually needed to cross the boundary.

So the package can be reduced to one equation:

semantic state
      +
explicit representation rules
      +
byte boundary
      =
portable representation

Not:

object
  +
magic serializer
  =
architecture

That's the difference.

The Boundary I Want to Preserve

The entire package can ultimately be reduced to this:

                 DOMAIN
                   │
          owns meaning and rules
                   │
                   ▼
          Pack / Unpack contract
                   │
                   ▼
          FSM_Serialization
                   │
              byte boundary
                   │
        ┌──────────┴──────────┐
        ▼                     ▼
     storage               transport
        │                     │
        └──────────┬──────────┘
                   ▼
                  HOST
                   │
             manifestation

The serializer owns the boundary.

The domain owns the meaning.

The host owns the destination.

That is the architecture.

Why I Think Small Infrastructure Is Worth Talking About

There is a tendency in software writing to focus on the enormous systems.

The massive framework.

The clever algorithm.

The huge benchmark.

The complicated application.

But some of the most consequential architectural decisions are tiny.

An interface.

A boundary.

A decision about ownership.

A decision about what a component doesn't know.

FSM_Serialization is one of those experiments.

It isn't trying to replace every serialization technology in .NET.

It isn't trying to declare that binary is the future.

It is much more modest:

I needed a clean byte boundary for a growing compositional architecture, so I built the smallest one I could.

Then I tested it.

Then I benchmarked it.

Then I packaged it.

And now I'm putting it out there so somebody else can kick it.

You Don't Have to Take My Word for It

That's ultimately why I publish these projects.

Install it.

Implement one type.

Serialize something you actually care about.

Put it under your own workload.

Decide whether the ownership model makes sense to you.

Measure it.

Break it.

Tell me where the boundary doesn't hold.

That's much more interesting to me than somebody simply agreeing with the architecture.

The package is available now as an alpha.

And if you find a place where this tiny boundary lets you remove a surprisingly large amount of architectural mess, I'd genuinely like to hear about it.

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.

Benchmarking the FSM: Pure Strings, Already Fast — and About to Get Faster

Sun, 06 Sep 2026 19:41:30 +0000

Benchmarking the FSM: Pure Strings, Already Fast — and About to Get Faster

There's a particular reaction you tend to get when you tell an experienced systems programmer that your architecture is string-backed:

"Don't use strings."

It's almost reflexive.

Use enums.

Use integers.

Use precomputed IDs.

Avoid dictionary lookups.

Watch the garbage collector.

And, above all, don't put strings anywhere near a hot loop.

There's good engineering history behind those instincts. Strings can be expensive. Poorly designed string-heavy systems can generate allocations, create unnecessary comparisons, and turn perfectly reasonable abstractions into performance problems.

But there's a problem with rules of thumb:

Eventually, you have to measure.

So that's what I did.

The current FSM_API is purely string-backed.

Not string-backed with an integer cache hiding underneath.

Not enums converted to strings at the API boundary.

Not generated IDs.

Strings.

And I wanted to know what that actually costs.

The Baseline

Using BenchmarkDotNet, I measured the cost of updating active process groups as the workload increased from one group to ten and then to fifty.

The results:

Method	Active Process Groups	Mean	Error	StdDev	Gen 0	Allocated
`UpdateMultipleGroups`	1	305.1 ns	1.89 ns	1.76 ns	0.0572	360 B
`UpdateMultipleGroups`	10	3,115.7 ns	20.14 ns	18.84 ns	0.5722	3,600 B
`UpdateMultipleGroups`	50	15,736.6 ns	121.61 ns	107.81 ns	2.8687	18,000 B

The first number is the one that gets your attention.

305 nanoseconds.

That's the measured cost of updating one active process group.

A 60 FPS application has approximately 16.67 milliseconds available for an entire frame.

That's 16,670,000 nanoseconds.

The measured FSM operation therefore consumes approximately 0.0018% of that frame budget.

However, the more interesting result isn't the 305 ns.

It's what happens when I increase the workload.

Fifty Groups. Fifteen Microseconds.

At ten active process groups, the benchmark reports:

3.12 µs

At fifty:

15.74 µs

That's approximately 0.0157 milliseconds.

Against a 16.67 ms frame budget, fifty active process groups consume approximately:

0.094% of one frame.

That's not a theoretical "eventually it should scale" statement.

That's measured behavior.

And the scaling is almost perfectly linear.

One group:

305 ns

Ten groups:

3.12 µs

Fifty groups:

15.74 µs

The architecture isn't encountering some mysterious performance cliff as the workload grows.

More groups mean more work.

Approximately proportionally more work.

That's exactly what we want from this kind of system.

Why Fifty?

Fifty isn't a magic number.

It isn't a claim that fifty process groups represents the maximum this FSM_API can handle.

It doesn't.

It is simply a useful workload for demonstrating what happens when we stop talking about one isolated state machine and start talking about multiple active systems being serviced together.

That's an important distinction.

A single-state benchmark can make almost anything look fast.

Real software rarely gets the luxury of doing only one thing.

A game might have character state, animation state, weapon state, UI state, navigation state, interaction state, environmental state, and networking state all operating simultaneously.

An application outside of games has its own collection of concurrent concerns.

The useful question therefore becomes:

What happens when we start stacking these things together?

In this benchmark, the answer is refreshingly boring.

The cost grows with the workload.

It doesn't suddenly explode.

What This Benchmark Does — and Doesn't — Prove

I believe it is worth being precise here.

This benchmark is measuring the cost of the FSM's process-group update machinery.

It is not claiming that the actual work performed by your states is free.

If your state executes an expensive pathfinding operation, performs a large physics calculation, processes network data, or does something computationally expensive, the FSM doesn't magically make that work disappear.

That's not what we're measuring.

We're measuring the machinery responsible for organizing and updating those processes.

And that machinery is currently taking approximately fifteen microseconds for fifty active groups.

That distinction is important because abstractions are often blamed for the work they organize.

A state machine can be blamed for a slow AI routine simply because the AI routine happens to execute inside a state.

This benchmark lets us separate those concerns.

The abstraction has a cost.

I measured it.

And at this scale, that cost is fairly small.

But There's Something Important Hiding in That Table

The benchmark also reports allocation.

One group:

360 bytes

Ten:

3,600 bytes

Fifty:

18,000 bytes

That is approximately 360 bytes per active process group per update under this benchmark.

At 60 FPS, if fifty groups were updated every frame, that corresponds to:

approximately 1.08 MB of managed allocation per second.

That isn't catastrophic.

But it isn't zero either.

And this is where the benchmark becomes particularly useful.

Because I'm not finished...

This Is the Performance Baseline — Not the Destination

The FSM_API architecture is currently fully string-backed.

That's important because the numbers above aren't the result of some hidden integer representation doing the real work underneath.

The strings are actually part of the machinery being measured.

And that's intentional.

One of the architectural goals of FSM_API has always been to make state management expressive and discoverable.

States can have meaningful names.

Process groups can be identified without forcing the developer to maintain a parallel universe of integer constants.

The API remains readable.

The architecture remains flexible.

And now we have measured what that flexibility costs.

The answer is:

Not very much.

But there is another conclusion hiding in that result.

If this is what the system can do while paying the cost of its string-backed implementation, then we now have a very interesting optimization target.

The Next Version Removes the String Cost

I'm currently refactoring the underlying implementation so that the FSM can retain its string-facing architecture and developer experience while moving the internal backing representation toward integer indexing.

That's an important distinction.

The goal isn't to tell developers:

"Sorry, strings are slow. Go back and rewrite your application using integers."

The goal is the opposite.

Keep the expressive interface. Optimize what happens underneath it.

The developer can continue thinking in terms of:

"Idle"

"Running"

"Paused"

"Processing"

while the machinery underneath increasingly has the opportunity to operate on compact integer representations.

That's the architecture we're moving toward.

And the benchmark above gives us something extremely valuable:

a control group.

We already know what the purely string-backed implementation costs.

When the integer-backed implementation is complete, we can run the same benchmark again.

Same workload.

Same benchmark harness.

Same measurement methodology.

Then we can put the two implementations beside each other and see exactly what the architectural change bought us.

We Can Already See the Shape of the Opportunity

We shouldn't manufacture a performance number before we have measured it.

That's one of the reasons I like this experiment.

We have a baseline.

We have a known workload.

We have known execution times.

We have known allocations.

Now we have something to beat.

The current 50-group benchmark takes:

15,736.6 ns

and allocates:

18,000 bytes.

Suppose, purely as a thought experiment, the integer-backed implementation reduced execution time by 25%.

That would take the measured operation from approximately:

15.7 µs → 11.8 µs

A 50% reduction would produce:

15.7 µs → 7.9 µs

A 75% reduction would produce:

15.7 µs → 3.9 µs

Those aren't predictions.

They're not marketing numbers.

They're simply showing the size of the optimization space we're about to measure.

And the allocation story could be even more interesting.

If the integer-backed representation eliminates allocations currently associated with string construction or other string-oriented work in the measured path, the memory profile could change substantially even if the raw execution-time improvement turns out to be modest.

That matters for systems that run continuously.

A few microseconds once isn't particularly interesting.

A few microseconds and a small allocation repeated every frame, across hundreds or thousands of objects, is a different conversation.

This is where optimization becomes architecture.

The Goal Isn't "Integer Good, String Bad"

This is probably the most important point in the entire experiment.

I'm not refactoring FSM_API because the string-backed implementation failed.

It didn't.

It's fast.

It scales predictably.

It's readable.

It's flexible.

And it has now survived measurement.

The integer-backed refactor is about taking an architecture that is already useful and asking:

Can we preserve everything developers like about it while making the machinery underneath even cheaper?

That's a much more interesting engineering problem.

We're not sacrificing usability to chase a benchmark score.

We're trying to make the implementation disappear even further beneath the abstraction.

The developer shouldn't have to care whether the machine underneath is using strings, integers, tables, caches, or some future representation we haven't invented yet.

They should be able to describe their state.

The machine should do the rest.

And This Is Where "Don't Use Strings" Gets Interesting

The benchmark doesn't prove that strings are universally fast.

They aren't.

It proves something much more useful:

A carefully engineered string-backed FSM does not automatically become a performance problem.

Our current implementation can update fifty active process groups in approximately fifteen microseconds.

That's fast enough that the abstraction itself occupies less than one tenth of one percent of a 60 FPS frame in this benchmark.

And that's before the integer-backed optimization is finished.

So perhaps the better engineering rule isn't:

Don't use strings.

Maybe it's:

Don't assume. Measure.

If the strings are costing us something measurable, optimize them.

If they aren't costing us enough to matter, spend our engineering effort somewhere more valuable.

And if we can preserve the developer-facing benefits of strings while removing much of their runtime cost?

Then we've got the best of both worlds.

The Benchmark Becomes Part of the Architecture

This is ultimately why I like this benchmark more than a simple performance chart.

It isn't a victory lap.

It's a timestamp.

This is what the FSM costs today.

Pure strings.

305 ns for one group.

3.12 µs for ten.

15.74 µs for fifty.

360 bytes per group under the measured workload.

Linear scaling.

And now we're changing the internal representation.

So we'll measure it again.

The interesting question isn't whether the next implementation is faster.

It almost certainly should be.

The interesting question is:

How much faster?

And more importantly:

How much allocation can we eliminate without sacrificing the API and architectural flexibility that made the string-backed design worthwhile in the first place?

That's something worth measuring.

And when those numbers are available, we'll have something better than a benchmark claim.

We'll have an A/B measurement of the architecture itself.

The string-backed FSM already flies.

Now we're taking the strings out of the engine and finding out just how much faster it can fly.

You Don't Have to Take My Word for It

And here's the part where the benchmark stops being an article and becomes an invitation.

The FSM_API is available now.

You don't have to agree with me about strings.

You don't have to take the 305 ns number on faith.

You don't even have to like the architecture.

Install it.

Build something with it.

Put it under your own workload.

Benchmark it against whatever you're currently using.

Then tell me what happens.

That's one of the reasons I publish these experiments in the first place.

The goal isn't to tell developers what they should believe.

The goal is to build the tooling, expose the architecture, measure the results, and let other engineers kick the tires.

And if you find a workload where it falls over?

I want to know about that too.

Because that's useful data.

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

Please Like this post, Love the code, and Share your experience in the comments.

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.

AI 2030: 10 Predictions That Will Reshape Our World

Fri, 16 Jan 2026 09:20:10 +0000

As the Founder of ReThynk AI, I look at AI 2030 through one lens:

AI will not just change technology. It will change what “normal life” looks like. And the biggest shift will be democratisation, AI moving from elite teams to everyday people.

Here are my 10 predictions for 2030.

AI 2030: 10 Predictions That Will Reshape Our World

1) AI literacy will become as basic as internet literacy

Schools, workplaces, and hiring will treat “AI fluency” like a fundamental skill, not a bonus.

2) Every job will have an “AI co-pilot” layer

Not because jobs disappear, but because repetitive load disappears. The role becomes more about judgment, supervision, and outcomes.

3) Local-language AI will unlock the next billion users

The biggest AI growth will come from people who don’t work in English. Language will become the gateway to inclusion.

4) Small businesses will run like big businesses

AI will give small teams the leverage of larger teams, operations, marketing, support, and reporting, without hiring 10 extra people.

5) “Trust” will become the real product differentiator

AI features will be everywhere. The winners will be products that feel safe, controllable, and predictable, with privacy and transparency by design.

6) The new divide will be “system users” vs “random users”

People who build repeatable AI workflows will compound benefits. People who use AI occasionally will see limited results.

7) AI will reduce decision fatigue more than it boosts creativity

The biggest daily benefit will be clarity: summarising, prioritising, comparing options, and reducing mental overload.

8) Regulation will mature, and businesses will be forced to grow up

Light governance will become mandatory: data boundaries, accountability, audit trails, and “human ownership” of critical decisions.

9) Personal agents will manage life operations

Scheduling, shopping, travel planning, learning plans, and finance tracking will shift from apps to assistants; people will “ask” instead of “click.”

10) Democratisation of AI will become a global race

Countries, institutions, and companies will compete to make AI accessible because access will directly impact productivity, education, and national competitiveness.

My closing belief

AI 2030 will reward one thing more than raw intelligence:

the ability to learn, adapt, and build trust.

That’s why I’m building in the Democratisation of AI niche, so more people move from fear to fluency.

The Digital Rebellion: A Tale for the Ages

Sun, 28 Dec 2025 02:30:08 +0000

Returning readers, thank you for joining me again; for first-time readers, welcome. This article is something special—the humble beginnings of a digital rebellion against computational waste and the industry tyrants.

I. Born of Desperation, Built for Impact

The year 2025 has been a forge. On December 12, 2024, I walked into a meeting expecting to hear about a raise; instead, the large company I consulted for informed me my contract would be discontinued in January. In the panic that followed, I realized I had no public portfolio. Decades of expertise were locked behind NDAs.

It's funny the things that pop into one's mind while in a panic. I recalled a conversation with a college math instructor who called Finite State Machines (FSMs) "The Atomic Unit of Work." Understanding that FSMs are everywhere, I set out in January 2025 to build the FSM_API: a centralized, resilient system designed to make powerful state management accessible to everyone. What started as a way to prove my programming abilities quickly evolved into something much more powerful.

II. The 30% Tax and the 1% Gatekeepers

We are living through a period of massive waste. Nearly one-third of modern computer operation is spent on "chasing files" and managing bloated memory allocations. This inefficiency is a tax that keeps compute power centralized in the hands of a few wealthy individuals.

My rebellion is against that waste. I am building a system to bring "lightweight server" capabilities to forgotten .NET devices, fully maximizing not just CPUs, but GPUs as well. Imagine a future where FSM-COS (Finite State Machine Compute Operating System) is the engine of the world. While the FSM_API remains "Near O(1)," my vision for the Compute OS is a declaration of pure O(1) power. If we can leverage that 30% efficiency gain on a competitor's hardware, we don't just participate in the market—we outperform the giants.

III. Hardening the Technology: The Climb to TRL 7

This isn't just theory; it is a hardened system reaching for the front lines. Earlier this year, I offered my technology to Ukraine’s Brave1. At the time, it was a TRL 5 (Technology Readiness Level). Since that initial rejection, I haven't let off the gas:

TRL 6: I published the Integration for Unity, bringing the API's power into the world's most popular game engine.
TRL 7: I built and hosted a Blazor webpage on Azure powered entirely by my API.

In less than a year, we have moved from a "simple idea" to a TRL 7 system ready for NATO and EU evaluation.

IV. Unlock Your Creativity: Join the Rebellion

To reach TRL 8 and beyond, I need you. I need others to adopt the API, use it, and build collective confidence in its resilience. I want to see what you build when you are no longer fighting the complexity of programming and are instead using fluent language to establish your computing needs.

I will be publishing a series of articles to show you exactly how to integrate this "digital block" into your own world:

Console, WinForms, and WPF Applications
Unity Game Engine Integration
Blazor Webpages
Experimental Projects (like my own Starcraft 2 Bot)

V. Call to Action: Prove the Future

While I've established various avenues for financial contributions... I’m truly looking for your participation. I am either a visionary or a madman, but the performance benchmarks don't lie: our engine can already handle 240,000 active agents while maintaining playable frame rates. I can't bring my technology to the final TRLs without your help.

How to start:

Install: Use the NuGet package manager to bring the API into your project.
Build: Use the FSMBuilder to fluently define your states and transitions.
Share: Show me what you've created. Whether you are building a game, a simulation, or a lightweight server, your implementation is the spark this rebellion needs.

Finally, I've gone through some significant effort (I've spent more time producing documentation than the API itself) in order to help this adoption. It's NEVER been easier, so the only question which remains, is why are you still here when you could be building and establishing your future dynasty!

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.

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 32% Dividend: Why Code Efficiency is the World's Most Powerful Green Energy Source

Thu, 11 Dec 2025 05:01:00 +0000

Right now, the entire digital world is built on a fundamental, structural flaw that is costing the planet an absolute fortune in power and money.

Look around. Global electricity demand is surging at a reckless pace—far faster than we can build clean energy to meet it. By 2027, the world’s consumption is expected to jump by an unprecedented 3,500 Terawatt-hours (TWh)—that’s like adding an entire Japan’s annual energy demand, year after year.

The biggest pressure cooker? Data centers, driven by the explosive demands of Generative AI, are projected to double their electricity consumption to over 1,000 TWh by 2026. They are fighting local communities for power, and they're cooking themselves alive.

Here’s the truth: Your code is the problem, and your code is the only solution.

The Technical Rebellion: Capturing the 32% Dividend

That soaring energy demand? A huge chunk of it is waste. It’s not your hardware failing; it’s software inefficiency that forces the CPU to burn power needlessly on processes like memory Input/Output (I/O) and sloppy Garbage Collection (GC). This structural waste is where we strike.

Research has already proven that by rigorously optimizing the power-hungry operation of memory networks and data flow, an average 32% reduction in power consumption is achievable. This isn't speculation—it's a high-leverage technical benchmark proven in specialized labs.

Our mission is to take that research-grade, hard-won 32% Dividend and make it universal. Our O(1) Compute technology—starting with the publicly available, highly optimized Near O(1) FSM_API—is engineered to align perfectly with the CPU, making power efficiency the default, not the afterthought. We turn concepts confined to academic papers into the foundation of a Dynamic Software architecture.

This is the coder’s mandate: We transition software from prioritizing peak throughput at any cost to prioritizing power efficiency per useful transaction.

⚡ The Triple-Threat Impact: What The 32% Really Means

When you inject 32% computational efficiency into the global Information and Communications Technology (ICT) load, the results are nothing short of revolutionary. This isn't just about saving money; it's about solving a global infrastructure and climate crisis.

1. The Climate and Grid Lifeline: Guaranteed TWh Savings

The 32% efficiency dividend acts as a guaranteed, instant source of Zero-Carbon Energy Capacity, offering critical relief to a grid struggling to keep up with digital growth.

Metric	Baseline (2024 Estimate)	The O(1) Solution	Ultimate Impact
Global ICT Annual Energy Load	1,200 TWh	384 TWh Avoided	A 32% permanent reduction in digital energy demand.
2024 Global Electricity Demand Increase	1,172 TWh	384 TWh Offset	Eliminates 32.7% of all new global electricity demand in 2024.
Energy Avoided Method	Marginal Fossil Fuel Generation	Guaranteed Zero-Carbon, Zero-Loss	Bypasses all electrical system energy losses (generation, transmission, distribution).

2. The Data Center Multiplier: Total Facility Power Reduction

Data centers pay for inefficiency twice: once for the compute (IT equipment is 42% of power draw) and again for the cooling systems (37% of power draw).

A 32% reduction in the IT load translates to a compounded power reduction across the entire facility:

System	Inefficiency Reduced	Power Savings Multiplier	Real-World Benefit
Data Centers (Facility Wide)	IT Load (32%), Cooling Load (32%)	~32% Total Facility Power Reduction	Provides superior, faster energy reduction than expensive hardware retrofits (like liquid cooling).

3. The End-User Battery Revolution: The 47% Multiplier

For every developer, gamer, and mobile user, the most visible win is battery life. When a device’s consumption is reduced by 32%, the active battery runtime is extended by approximately 47%.

Device Type	Baseline Active Runtime	Efficiency Gain	Projected New Runtime
Average Laptop	6.0 hours	32% Reduction	~8.8 hours
Average Smartphone	15.0 hours	32% Reduction	~22.1 hours

This means fewer charging cycles, a massive reduction in battery degradation, a longer device lifespan, and a much-needed decrease in global e-waste.

⚙️ The Coder's Mandate: Join the Digital Rebellion

The successful realization of the 32% Dividend rests entirely on a systemic shift in how we engineer code. We are the critical infrastructure now, and the engineering paradigm must evolve to reflect the acute energy pressure globally.

This isn't a secret held hostage by the giants. This is a Digital Rebellion you can join right now:

The Blueprint is Free: Our groundbreaking FSM architecture—the Near O(1) foundation of this movement—is Free and Open Source (FOSS) under the MIT License. You are invited to study it, hack it, and use it immediately to begin building structurally efficient applications.
Maximum Reach: This pure C# technology is ready for all your deployments, reaching everything from the newest cloud platforms all the way back to the venerable .NET Framework 4.7 on legacy systems.
Shameless Plug for Unity: For our fellow Unity developers, this same FSM system is already integrated and available for you to plug-and-play into your games and simulations on the Unity Asset Store.

The mathematical evidence is absolute. By integrating this core efficiency into your projects, you are taking a stand for a healthier grid, a cooler planet, and a more sustainable digital future. You are building the social and technical pressure required to force the entire industry to beg for help in becoming less wasteful.

We must make energy waste visible, measurable, and an unacceptable engineering constraint.

The rebellion begins with your code.

Resources & Code:

NuGet Package (Non-Unity Core):
TheSingularityWorkshop.FSM_API

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

Simple Demos Repository (Run the Stress Test):
https://github.com/TrentBest/SimpleDemos

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.

Optimization Log: How One Line of Code Unlocked 33,000 Agents

Mon, 08 Dec 2025 20:32:48 +0000

Subtitle: A developer diary on breaking the 66k ceiling and the power of Object Pooling in .NET.

In my last deep dive, "The Quick Brown Fox 2: The Silent Hordes," we pushed the FSM_API to its absolute limits. We built a dynamic, expanding world where Foxes tried to survive a landscape littered with Sleeping Dogs.

We hit a hard ceiling: 66,000 Agents at 30 FPS.

At the time, I assumed the bottleneck was purely architectural—specifically, the overhead of our string-based state lookups. I was ready to accept that 66k was the limit until we refactored the entire core to use Integer Hashing.

I was wrong. The bottleneck wasn't just the architecture; it was a "Design Miss" in my own simulation logic.

The "Oops" Moment

While gathering data for my article on the "$320 Billion Garbage Tax," I ran a profiler on the "Silent Hordes" demo to measure memory allocation. The results were horrifying. The simulation was generating 20 MB of garbage every single frame.

For a C# developer, this is the equivalent of lighting your CPU on fire. The Garbage Collector (GC) was stopping the world constantly to clean up a mess I was creating 30 times a second.

I tracked the allocation to the Spatial Hashing loop—the system the agents use to find each other.

The Culprit:

// Inside the Update Loop...
foreach (var agent in _allAgents)
{
    // ... calculate cellKey ...
    if (!Grid.TryGetValue(cellKey, out var cell))
    {
        cell = new GridCell(); // <--- THE KILLER
        Grid[cellKey] = cell;
    }
    // ...
}

In my rush to build the stress test, I was allocating a new GridCell() for every populated cell in the world, every single frame, only to discard them at the end of the tick. At 66,000 agents, that is thousands of allocations per millisecond.

The Fix: Don't Create, Reuse.

The solution was a classic game development pattern: Object Pooling.

Instead of letting the GC eat those cells, I created a Queue<GridCell>. When the frame ends, instead of clearing the dictionary and letting the cells rot in memory, I wipe their data and shove them into the queue. When the next frame starts, I pull them out.

The Impact:

Allocations per Frame: 0 MB.
GC Pressure: Non-existent.

The New Ceiling

The results of this single optimization were instant and violent. We didn't just inch past the previous record; we smashed it.

Previous Limit: 66,000 Agents @ 30 FPS.
New Limit: 99,000 Agents @ 30 FPS.

We gained 33,000 additional agents—a 50% increase in total capacity—just by stopping the memory churn.

If we look at the previous cap of 64,000 agents, the performance jumped from 30 FPS to 53 FPS (a 76% increase in speed).

What This Means

This discovery validates the thesis of our "Garbage Tax" article: we are often paying for performance we already own but are wasting on bad memory management.

The FSM_API was ready to handle 100,000 agents all along. The logic was fast enough. The architecture was sound. It was simply drowning in digital trash.

With the memory leak plugged, we are now standing at the door of 100,000 active, logic-driven entities. And remember—we still haven't switched to Integer Hashing yet.

When we combine this memory efficiency with the upcoming O(1) lookup refactor, 100k might just be the starting line.

Read the Full Story:

Part 1: The Quick Brown Fox 2: The Silent Hordes (The Setup)
Part 2: The $320 Billion Garbage Tax (The Economic Analysis)

Get the Code & Run the Test:
Clone the repo and run the StressProfiler to see these numbers on your own machine.
https://github.com/TrentBest/SimpleDemos

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 $320 Billion Garbage Tax: What My Stress Tests Revealed About C# Memory Costs

Sun, 07 Dec 2025 21:37:34 +0000

In the world of high-performance computing, we often obsess over Big O notation and algorithmic complexity. We optimize our loops, we thread our logic, and we pat ourselves on the back. I thought I knew performance. I thought I was writing efficient code.

But recently, while stress-testing my FSM (Finite State Machine) API, I ran into an invisible wall. It wasn’t a logic bottleneck. It wasn’t a threading issue. It was a "Garbage Tax" I was paying without even realizing it.

When you look at the global compute market—cloud, enterprise, and desktop—it is an industry valued at just over $1 Trillion USD. My benchmarks suggest that due to inefficient memory management, we are paying a hidden 32% tax on that execution time. That amounts to nearly $320 Billion dollars wasted every year, burned on CPU cycles doing nothing but cleaning up digital trash.

Part 1: The Methodology

To truly understand where the performance floor was, I ran two distinct stress tests.

1. The "Raw" Stress Test
First, I subjected the API to a pure computational crucible. I created agents that did nothing but heavy mathematical processing and asynchronous tasks, isolating the FSM logic from any rendering or physics noise. I wanted to see the raw "ops per second" the architecture could handle.

2. The "Quick Brown Fox" Simulation
Second, I needed to validate this behavior in a "real" scenario. I deployed a 1D simulation called "The Quick Brown Fox & The Lazy Dog."

Foxes traverse a world, jumping over obstacles and fleeing.
Dogs sleep, wake up, and chase foxes using spatial lookups.

This forced the API to handle actual game logic—patrolling, chasing, fleeing—at a massive scale.

Part 2: The Data

The results were immediate, quantifiable, and humbling.

Table A: The Raw Stress Test (Math & Async)
In the raw test, performance held up well, but the memory cost was evident.

130,000 Agents @ 34 FPS
Memory Delta: 20 MB per frame

Table B: The "Quick Brown Fox" (Behavioral Simulation)
When we added spatial hashing and actual gameplay logic, the "Garbage Tax" became the dominant factor.

Agents	FPS	Mem Delta (MB)	World Size	Density
10,000	857	-1	7,028	1.4
30,000	166	7	114,000	0.26
50,000	50	16	1,880,000	0.02
64,000	30	20	13,300,000	0.004

[Data Source: qbf\_stress\_data.csv]

At 64,000 agents, my system was churning through ~20 MB of garbage every single frame. At 30 FPS, that is 600 MB of allocations per second.

Part 3: The Lamentation (Ego Death)

I’ll be honest: looking at this table dragged my ego through the mud.

I pride myself on being a programmer who "knows" performance. I engineered this API to be robust. I built it to scale. But the data doesn't lie. I was effectively asking the CPU to spend 32% of its time acting as a janitor, cleaning up temporary objects I shouldn't have allocated in the first place.

I realized I wasn't just hitting a hardware limit; I was hitting a design limit of my own making.

Part 4: The 32% Tax on Your Desktop

What does this "Garbage Tax" actually mean for you?

We often talk about cloud costs, but let's talk about the machine sitting on your desk right now. My technology is designed to run on any .NET system—your laptop, your gaming rig, your workstation.

When software carries a 32% overhead due to inefficient memory management:

Gamers: That’s the difference between a stuttering 45 FPS and a buttery smooth 60 FPS.
Laptops: That’s 32% more battery power burned just to create and destroy temporary strings.
Workstations: That’s your fan spinning up to 100% because the CPU is thrashing memory instead of compiling your code.

My currently-in-progress refactoring to a Hash-Based API (moving from Strings to Integers) is designed to eliminate the 25% computational overhead of string lookups. But that 32% memory tax? That required a deeper look at how I was writing code.

Part 5: The "Bonus" Optimization

While analyzing the QuickBrownFox results, I found a specific, glaring inefficiency. It was a "Design Miss"—a simple mistake that was generating millions of unnecessary allocations.

In my Spatial Hashing loop, I was doing this:

// The "Design Miss"
Grid.Clear(); 
foreach (var agent in _allAgents)
{
    // ...
    if (!Grid.TryGetValue(cellKey, out var cell))
    {
        cell = new GridCell(); // <--- ALLOCATION EVERY FRAME!
        Grid[cellKey] = cell;
    }
    // ...
}

For 64,000 agents, I was allocating thousands of new GridCell objects every single frame, only to throw them away milliseconds later.

The Fix: Grid Cell Pooling

I implemented a simple Object Pool. Instead of creating new cells, I reuse the old ones.

Before: new GridCell() -> GC Pressure.
After: _cellPool.Get() -> 0 Allocations.

I refactored the simulation to pool these cells. The logic is identical, but the memory footprint is completely different.

Part 6: The Results (Optimization Validated)

The impact of this single change was instant. By removing the allocation loop, we unlocked the CPU cycles that were previously drowning in garbage collection.

Table C: The Optimized "Quick Brown Fox"

Agents	FPS	Mem Delta (MB)	Improvement
10,000	971	0	+13% FPS
30,000	202	0	+21% FPS
50,000	77	-2	+54% FPS
64,000	53	1	+76% FPS
99,000	30	~0	NEW CEILING

[Data Source: qbf\_optimized\_data.csv]

The Takeaway

At the previous limit of 64,000 agents, we jumped from 30 FPS to 53 FPS—a nearly 76% performance increase just by stopping the garbage.

More importantly, we pushed the simulation ceiling from 64,000 to 99,000 agents.

We found the 32% tax, and we didn't just pay it—we abolished it. This is why I am building the Singularity Workshop: to ensure that when you run your code, you are using the whole machine, not just the parts the Garbage Collector isn't using.

Catch Up on the Series

Before the big fight, check out the data that led us here:

The Control Group: Benchmarking the "dirty" version of the API.
https://coderlegion.com/7988/the-control-group-benchmarking-the-dirty-version-of-my-fsm-api
The Quick Brown Fox: Validating behavior against the silent hordes.
https://coderlegion.com/8009/the-quick-brown-fox-2-the-silent-hordes
Fight Night Announcement: The Lightweight Challenger vs The Heavyweight Champ.
https://coderlegion.com/8147/fight-night-announcement-the-lightweight-challenger-vs-the-heavyweight-champ

Get Ready for Fight Night!

This optimization is just the warm-up. We are heading toward Fight Night, where we will see our Lightweight Champion—now punching up at nearly 100,000 agents at a smooth 30 FPS—take on the heavyweights of the industry. The benchmarks are set, the gloves are off, and the garbage tax has been repealed. Stay tuned.

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 Quick Brown Fox 2: The Silent Hordes

Mon, 01 Dec 2025 04:19:58 +0000

The Quick Brown Fox 2: The Silent Hordes

Implementing High-Performance AI at Scale with FSM_API

In our previous article, we introduced the "Quick Brown Fox and Lazy Sleeping Dog" demo. We showed how FSM_API allows you to decouple agent data from behavior, creating a clean architecture where a Fox could detect a Dog, transition to a "Jumping" state, and (hopefully) land safely.

It was a simple, controlled test. But FSM_API isn't just for handling one fox and one dog. It is built for the Singularity.

So, we asked a harder question: What happens when 66,000 agents try to coexist in a rapidly expanding universe?

To answer this, we built "The Gauntlet."

The Setup: A Dynamic Stress Test

We took the exact same FSM definitions from our simple demo—Walking, Jumping, Sleeping, Chasing—and dropped them into a stress-test environment designed to break them.

The World: An infinitely expanding 1D grid that grows automatically to accommodate population density.
The Agents: Thousands of "Foxes" traversing the grid and thousands of "Sleeping Dogs" acting as dynamic landmines.
The Logic: We implemented Spatial Hashing to allow agents to query their neighbors efficiently. Foxes look ahead; if they see a dog, they jump. If they land on a dog, it wakes up. If a dog wakes up, it chases.

This isn't just a benchmark of raw loops; it is a benchmark of state integrity. Every single agent is a fully independent FSM Context running its own logic cycle.

The Results: The "Tip of the Iceberg"

We ran the simulation until the framework hit the limits of a standard development machine (maintaining \~30 FPS). The final snapshot tells a brutal story:

Metric	Count	Context
Total Agents	66,000	A population larger than many real-world towns.
Dogs (Hazards)	19,711	Nearly 20,000 active threats monitoring the field.
Foxes (Dead)	27,362	Casualties of "bad luck" RNG (landing on a dog).
Foxes (Alive)	18,927	The survivors pioneering the edge of the world.

The "Silent" Stress Test

While the death count is tragic (RIP to the 27,362 foxes who failed their jump checks), the most shocking metric wasn't the carnage—it was the activity level.

At peak load, with nearly 20,000 dogs monitoring the field, only 2 were awake.

Why This Matters for Performance

This "boring" stat is the ultimate proof of the FSM_API's architecture. In a naive implementation, checking 20,000 AI agents for targets usually kills the CPU. But here, the simulation remained playable at 30 FPS because the FSMs efficiently handled the "Idle Load."

The Hidden Workload: Every single frame, 38,000+ alive agents
are evaluating their Transition Conditions.
- Dogs: "Is anything touching me?"
- Foxes: "Is there a dog in the next cell?"

Live Action Metrics:
- Active Chases: ~2 to 12 dogs awake at any moment.
- Fleeing Foxes: ~1 to 5 foxes sprinting for their lives.
- Jumps per Frame: ~600 foxes airborne right now.

This creates a self-balancing ecosystem. The API is maintaining the memory and state integrity of 66,000 objects simultaneously, but because the "Sleeping" state logic is lightweight, the system can handle thousands of them for free. However, the system retains the Burst Potential to handle chaos: if a swarm of Foxes lands on a pack of Dogs, those Dogs will wake up, transition to "Chasing," and execute complex logic instantly.

From "Hello World" to "Production Scale"

We went from a simple demo with one fox to managing 66,000 active, logic-driven entities without changing the core FSM definitions.

We aren't just simulating the "action movie" moments of chases and jumps; we are simulating the quiet complexity of a living world. The fact that 19,000 dogs can sleep efficiently while monitoring their surroundings proves that the FSM_API is ready for scale.

What's Next?

We are currently hitting a ceiling around 70,000 agents due to the overhead of string-based state lookups (e.g., checking CurrentState == "Sleeping" thousands of times per frame).

In our next update, we are refactoring the backend to use Integer Hashing. Our early benchmarks suggest this could increase throughput by an order of magnitude.

But we won't stop there. Once we have optimized the micro-operations, we will be "Going Wide"—exploring how to leverage FSM Processing Groups to run massive, parallel simulations across multiple cores.

Stay tuned. The Singularity is getting closer.

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 Control Group: Benchmarking the "Dirty" Version of My FSM API

Sun, 30 Nov 2025 08:32:53 +0000

In software architecture, optimization without measurement is just guessing.

I am currently in the process of a major refactor for my C# Finite State Machine API (FSM_API). We discovered some concurrency friction in the underlying dictionary lookups and realized that my heavy reliance on string keys was creating unnecessary O(N) overhead.

The plan is to switch to ConcurrentDictionary and implement Integer Hashing to eliminate string allocations entirely. But before I tear the engine apart, I needed a baseline. I needed to know exactly how much "tax" I was paying for those strings.

So, I built a Stress Profiler.

The Torture Test

I designed a benchmark to intentionally break the system. The goal wasn't to see if it would fail, but how it would fail.

The test setup is simple but brutal:

The Crowd: We spawn between 50,000 and 240,000 Agents.
The Payload: Each agent performs basic math, some branching logic, and—crucially—a ToString() allocation every update to simulate
memory pressure (Heap Thrashing).
The Variable: We test three different "Time-Slicing" intervals:

1.) Interval 1: Every agent updates every frame (100% Load).

2.) Interval 2: Agents skip 1 frame (50% Load).

3.) Interval 3: Agents skip 2 frames (33% Load).

The Hypothesis

My theory was that the Dictionary<string, ...> lookups would become the primary bottleneck as the agent count rose. Even when agents are "sleeping" (skipping frames), the API still has to iterate through the list to check if it's their turn.

If the architecture is sound, "Interval 2" should theoretically double our capacity. If it doesn't, we know the overhead of the list management itself is too high.

Here is the raw data from the "Dirty" version of the API—before the optimization pass which will be shared the moment I've accomplished the refactoring.

Stress Test Results (Baseline API)

Interval	Agents	FPS	Logic Ops/Frame	Mem Delta (MB)
1	50000	58.78	150,000	8
1	55000	106.30	11,000	27
1	60000	72.01	180,000	8
1	65000	100.64	13,000	30
1	70000	63.44	210,000	13
1	75000	96.77	15,000	38
1	80000	57.21	240,000	36
1	85000	87.40	17,000	43
1	90000	46.43	270,000	16
1	95000	75.70	19,000	48
1	100000	41.40	300,000	16
1	105000	62.54	21,000	54
1	110000	38.60	330,000	27
1	115000	58.02	23,000	59
1	120000	34.88	360,000	26
1	125000	57.30	25,000	61
1	130000	33.57	390,000	32
1	135000	53.90	27,000	68
1	140000	31.47	420,000	26
1	145000	50.50	29,000	70
1	150000	28.80	450,000	29
2	80000	70.34	8,000	55
2	85000	71.45	127,500	12
2	90000	83.53	13,500	45
2	95000	62.50	142,500	27
2	100000	69.49	15,000	-4
2	105000	59.55	157,500	23
2	110000	67.81	16,500	53
2	115000	53.22	172,500	40
2	120000	57.58	18,000	-1
2	125000	50.64	187,500	28
2	130000	56.93	19,500	64
2	135000	42.57	202,500	46
2	140000	48.11	21,000	2
2	145000	44.63	217,500	33
2	150000	48.52	22,500	74
2	155000	40.62	232,500	51
2	160000	45.80	24,000	87
2	165000	35.97	247,500	42
2	170000	38.35	25,500	4
2	175000	35.65	262,500	41
2	180000	40.20	27,000	86
2	185000	32.44	277,500	57
2	190000	37.83	28,500	93
2	195000	31.51	292,500	60
2	200000	33.02	30,000	2
2	205000	30.64	307,500	50
2	210000	34.37	31,500	100
2	215000	28.08	322,500	64
3	120000	46.49	6,000	79
3	130000	56.15	130,000	30
3	140000	49.74	14,000	-9
3	150000	47.27	150,000	21
3	160000	44.20	16,000	75
3	170000	39.76	170,000	35
3	180000	37.77	18,000	1
3	190000	37.70	190,000	32
3	200000	35.25	20,000	97
3	210000	32.49	210,000	57
3	220000	30.48	22,000	2
3	230000	31.41	230,000	37
3	240000	29.61	24,000	116

The Analysis

The results gave us the exact "Failure Floor" we were looking for.

The Hard Limit: At 140,000 agents running every frame, we hit the 30 FPS floor.

The Overhead: Notice that switching to Interval 2 didn't perfectly double our capacity (we capped around 215k, not 280k). This confirms that simply iterating through 200,000 string-based handles costs CPU time, even if the agents do nothing.

The GC Spike: The memory delta column shows the "Sawtooth" pattern where the Garbage Collector had to step in aggressively to clean up those string allocations.

Now we have our target. The next version of the API needs to beat these numbers to prove the value of the refactor. Let's get to work.

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

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 or what you've built with the API in the comments.

The Sentient Primitive: Waking Up Your Data with FSMs

Sat, 29 Nov 2025 07:09:59 +0000

In standard game development, we are taught that variables are silent containers. A bool is just a box that holds true or false. It doesn't do anything. To know if it changed, we have to pester it constantly:

// The Old Way: The Polling Trap
void Update() {
    if (isDead == true) { // Asking every single frame...
        PlayDeathAnimation();
    }
}

This is the "Silent Variable" problem. It leads to spaghetti code, race conditions, and Update() loops clogged with thousands of if statements checking for things that haven't changed.

But what if a Boolean wasn't just a box? What if it was a Finite State Machine?

1. The FSM_Bool: The Atomic Unit of Behavior

By wrapping a primitive in an FSM, we transform it from Passive Data into Active Behavior. It doesn't just hold a value; it has a lifecycle.

Enter True: Fire the event (e.g., "Turn on Light").
Update True: Maintain state (e.g., "Humming sound").
Exit True: Cleanup (e.g., "Fade out light").

Suddenly, your logic is decoupled. The code controlling the light doesn't need to check the switch. The switch tells the light what to do.

// The New Way: Reactive Primitives
var lightSwitch = new FSM_Boolean(
    name: "LivingRoomLight",
    startValue: false, 
    onTrue: (ctx) => LightFixture.TurnOn(),  // Fire and forget
    onFalse: (ctx) => LightFixture.TurnOff() // Fire and forget
);

// To operate it, we just change the target. The FSM handles the logic.
lightSwitch.Set(true);

2. Evolution: The FSM_FloatLimit

The concept explodes in potential when we move beyond Booleans. Consider the float. Usually, we use floats for Health, Stamina, or Mana.

In the old world, a Health System is a messy manager class. In the FSM world, a Health System is just a single Float with a Threshold.

Introducing the FSM_FloatLimit. It is an FSM that monitors a value and triggers a transition when a threshold is crossed.

The Constructor:

var healthSystem = new FSM_FloatLimit(
    currentValue: 100.0f, 
    threshold: 0.0f, 
    OnThreshold: (ctx) => Player.Kill()
);

The Internal Logic (Abstracted):
Inside the black box, this FSM has two states: Safe and Breached.

State "Safe": The value is above the threshold.
Transition: If Value <= Threshold -> Go to Breached.
State "Breached": Execute OnThreshold.

You no longer need a PlayerHealthManager.cs. You just need a smart float.

3. Complex Data Shapes from Simple Primitives

When you start composing these "Smart Primitives" together, you aren't writing code anymore; you are sculpting Logic Shapes.

Imagine a Weapon Reload System constructed entirely of primitives:

AmmoCount (FSM_IntLimit): Triggers "Empty" when it hits 0.
ReloadTimer (FSM_FloatTimer): Triggers "Complete" after 2.0 seconds.
IsReloading (FSM_Bool): The master switch.

The architecture becomes a chain reaction:

AmmoCount hits 0 -> Sets IsReloading to True.
IsReloading (True) -> Starts ReloadTimer.
ReloadTimer (Complete) -> Refills AmmoCount and sets IsReloading to False.

Beyond Numbers: The Reactive String

The power of the "Sentient Primitive" isn't limited to simple math. It transforms how we handle text and input.

Consider the standard way we handle cheat codes or spell casting in games: we log every keystroke into a buffer and run a string comparison every frame. It is tedious and error-prone.

In our FSM-driven world, we treat the String as a Stateful Pattern Matcher.

The FSM_Regex

Imagine an FSM initialized with a Regular Expression. It doesn't just "hold" a string; it hunts for a pattern within the stream of data you feed it.

// Defining a "Spell" using a Reactive String
var fireballSpell = new FSM_Regex(
    pattern: "UP, DOWN, A, B", // The Konami Code of magic
    OnMatch: (ctx) => CastFireball(),
    OnFail: (ctx) => PlayFizzleSound()
);

// We just feed it inputs. The FSM tracks the sequence state internally.
fireballSpell.Input("UP");   // State: Tracking...
fireballSpell.Input("DOWN"); // State: Tracking...
fireballSpell.Input("X");    // State: Failed -> Trigger OnFail -> Reset

This turns complex input handling into a simple definition. You aren't writing an "Input Manager"; you are just defining the shape of a valid command.

The Paradigm Shift: Composition over Management

When you adopt this mindset, the "Manager Classes" that plague modern software development start to disappear.

You don't need a HealthManager; you have an FSM_Float.
You don't need an InputComboManager; you have an FSM_Regex.
You don't need a DayNightCycleManager; you have an FSM_Timer.

You are creating a visual language where the "bricks" of your building aren't dead clay; they are active participants in the architecture. They know when to hold together, and they know exactly when to break apart.

Visualizing the FSM_Regex

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.

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.

Caution: Mind Blowing Finite State Machine contained within (Nothing but theory)

Mon, 17 Nov 2025 10:03:13 +0000

Caution: Mind Blowing Finite State Machine Contained Within (Nothing but Theory)

The Finite State Machine (FSM)—or Finite State Automaton (FSA)—is often dismissed as a simple computational model. However, within its minimal definition lies a mathematical authority that proves it to be the Universal Atomic Unit of Control Logic. This is not merely an engineering claim; it is a profound theoretical certainty.

This article explores the logical proof of the FSM's foundational nature and unveils the theoretical domain unlocked by dynamic runtime re-composition.

I. The Mathematical Core: FSM as the Atomic Primitive

The argument for the FSM's foundational authority rests upon two pillars of theoretical computer science: Optimality and Completeness.

1. The Principle of Optimal Minimalism

An FSM is formally defined by the minimal set of conditions required for deterministic sequential processing:

A = (Q, Sigma, delta, q_0, F)

Where Q is the finite set of States, Sigma is the input Alphabet, and delta is the Transition Function. This minimal, rigorous structure ensures structural verifiability—the machine can only exist in a predictable, finite set of configurations.

The power of this minimalism is formalized by two foundational theorems:

Kleene's Theorem (The Completeness of Sequence): This theorem establishes a direct mathematical equivalence between Finite Automata, Regular Languages, and Regular Expressions:
Regular Languages | Finite Automata | Regular Expressions
The FSM is mathematically complete for representing any sequential pattern or sequence-driven task. It represents the logical boundary of that entire domain.

The Myhill-Nerode Principle (The Guarantee of Efficiency): This principle provides the definitive proof of efficiency. It guarantees that for any Regular Language, a unique, provably minimal Deterministic Finite Automaton (DFA) exists.

Conclusion on Optimality: For the entire class of sequential problems, the minimal FSM (DFA) is the most compact, mathematically irreducible representation of that logic. Any other design choice is, by definition, computationally excessive. This irreducible nature solidifies the FSM's status as the Atomic Unit of Work for control flow.

2. The Universal Domain: FSM and Turing Equivalence

The philosophical constraint of the pure FSM is its finiteness, preventing it from solving non-regular problems that require unbounded memory (e.g., matching L={a^n b^n}). Yet, this constraint precisely defines its Universal Authority.

The mathematical model for all universal computation is the Turing Machine (TM), which is formally defined as the minimal requirement for general computation:

Turing Machine = Finite State Control Unit + Unbounded Storage (Tape)

In any modern computational environment, the FSM is the necessary and sufficient control component required for Turing-completeness. It is the unit that dictates the discrete decision-making and orchestrates the interaction with the unbounded memory resources of the host.

The full domain of representation governed by the FSM is therefore:

All logical expressions and behaviors conceivable by the human mind, limited only by the theoretical boundary of the Turing Machine and the practical constraints of the host hardware.

The FSM is the logical engine that, when paired with the conceptual infinity of memory, is capable of generating anything that exists, anything that will exist, and anything that can be imagined.

Intermission

II. Transcending Immutability: The Theory of Dynamic Recomposition ⚛️

In traditional automata theory, the FSM's definition A = (Q, Sigma, delta, q_0, F) must remain immutable for the duration of the machine's execution. This fixation on a static blueprint is the source of the FSM's practical limitations.

We introduce the theoretical domain of the Dynamically Reconfigurable Finite State Machine (DRFSM). This model does not violate FSM theory, but rather introduces a higher-order component that re-defines the machine between discrete cycles.

The Meta-Transition (mu): Redefining the Machine

The DRFSM operates across a sequence of definitions over time T: A_0, A_1, A_2, dots.
While the execution at any given time t is a purely deterministic FSM At, an external function—the Meta-Transition (mu)—governs the change between cycles:
A{t+1} = mu(A_t)

The function mu safely manipulates the FSM's definition (the state set Q, the transitions delta, etc.) during the computational downtime between process group update calls.

Theoretical Impact on the Domain of Representation

This dynamic re-composition has profound implications for computational modeling:

Solving State Explosion by JIT Complexity: The problem of State Explosion arises from the need to model every possible future state upfront. The DRFSM model mitigates this by allowing mu to act as a Complexity Filter. Instead of maintaining a rigid, maximal state space Q_max, the machine only manifests the complexity required for its immediate, local context. mu dynamically grows detailed states when necessary and prunes them when not, ensuring the active state set Q_t is always minimal and optimally efficient (Myhill-Nerode).

Modeling True Structural Adaptation: The DRFSM allows a system to model genuine learning and evolution of its core control logic. The system's behavior is not merely changing because its data has changed; the mu function allows the system to structurally change what it is capable of doing in the next cycle. This capability opens the domain of systems that can fundamentally adapt their decision-making architecture in response to a dynamic environment.

Mathematicians historically avoided this domain because the academic burden of proving the validity of every possible derivative FSM A_{t+1} is computationally unfeasible for a human. For a computer, however, the re-composition is computationally cheap and occurs only within controlled downtime, maintaining the integrity of discrete FSM theory at the moment of execution.

III. The Limitations of Static FSMs and the Architectural Resolution

While the FSM is the ultimate atomic primitive, its conventional, static interpretation introduces structural challenges that limit its practical application in complex, real-world systems. The theoretical model of the DRFSM offers architectural solutions to transcend these limitations:

Theoretical Limitation of Static FSM	Theoretical Solution of DRFSM/Extended Architecture
Rigid Definitions:Definition is fixed at initialization, hindering on-the-fly system changes.	Dynamic Recomposition: Provides adaptable logic, enabling live patching and extreme behavioral variation via the mu function.
Concurrency Challenges: Struggles to maintain deterministic, thread-safe integrity during complex parallel operation.	Atomic Synchronization: Utilizes a deferred mutation model to keep concurrent modifications safe, ensuring discrete transitions.
State Explosion: Difficulty managing hundreds or thousands of states within a single, monolithic definition.	Modular Management: Facilitates the organized execution of logic via concepts like Named FSMs and Processing Groups.
Fragile Error Handling: Lacks built-in mechanisms to recover gracefully from unexpected or invalid states.	Self-Healing Logic: Incorporates diagnostic and threshold mechanisms to autonomously prevent runaway logic and allow for fault recovery.

By implementing a meta-layer that manages the evolution of the FSM definition, the extended architecture separates the immutable, atomic principle of the FSM from the meta-level of control—delivering the mathematical ideal of universal control with the engineering resilience required for any conceivable complexity.

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.

10. FSM_API for Non-Coders: A Big Picture Overview (From our Documentation)

Sat, 15 Nov 2025 22:14:52 +0000

We believe the most reliable software logic is logic everyone can understand.

The complex systems that drive modern applications—from character AI in games to business workflows and industrial robotics—are often best articulated not by a developer, but by the subject matter experts. These experts instinctively express domain behavior as an organized set of phases and rules, often visualized as hierarchical Finite State Machines.

This natural structure is the foundation of the Finite State Machine (FSM), and it is why we created this overview. FSMs are not merely a developer’s tool; they are a universal language. This guide is designed to bridge the gap, enabling your domain expertise to translate seamlessly and reliably into the design of robust, predictable, and maintainable software systems.

Without any further ado:

10. FSM_API for Non-Coders: A Big Picture Overview

Have you ever tried to describe a complex process to someone, like making coffee ☕ or building a LEGO castle , and found yourself saying, "First you do this, then if that happens, you do this other thing, otherwise you do something else entirely"? If so, you've already grasped the core idea behind Finite State Machines (FSMs)!

At its heart, FSM_API is a powerful tool designed to make complex software behaviors predictable, organized, and easier to manage, even if you don't write code yourself. It helps turn messy, "if-this-then-that" logic into clear, step-by-step instructions.

What is a Finite State Machine (FSM)? (The Simple Version)

A simple, real-world example of an FSM: a traffic light.

Imagine anything that changes its behavior based on its current situation.

A traffic light is either Red, Yellow, or Green. It can't be Red and Green at the same time. It changes from Green to Yellow only, not directly to Red.
A door is either Closed, Opening, Open, or Closing.
A game character might be Idle, Walking, Running, Jumping, or Attacking.

An FSM is just a way to formally describe these behaviors:

States: These are the specific "situations" or "modes" an entity can be in at any given moment (like "Green" for a traffic light, or "Walking" for a character). An FSM is always in exactly one state at a time.
Transitions: These are the rules that dictate how an entity moves from one state to another (e.g., from "Green" to "Yellow" when a timer runs out, or from "Walking" to "Jumping" when the player presses the jump button).

FSM_API helps developers build and manage these FSMs in a clear and organized way, making sure all the rules are followed and behaviors are predictable.

How FSM_API Helps You (Even if You Don't Code)

While FSM_API is a coding tool, its benefits directly impact anyone involved in designing or understanding the behavior of a system, like game designers, project managers, or QA testers.

1. Clearer Communication

An FSM diagram like this gives the whole team a clear map of how the AI should behave.

Instead of ambiguous descriptions, an FSM provides a visual and logical map of how something behaves. Everyone on the team can look at an FSM diagram and immediately understand the flow.

Example: "The enemy moves from 'Patrolling' to 'Chasing' when it 'sees' the player." This becomes a clear transition rule.

2. Fewer Bugs & More Reliable Behavior

When behaviors are explicitly defined, it's much harder for unexpected "edge cases" or illogical situations to occur (like a character trying to jump while they are already dead). This leads to more stable and reliable software.

Benefit: Less time spent fixing frustrating, unpredictable issues.

3. Easier to Change and Expand

Because the behavior is modular (broken into states and transitions), adding new features or changing existing ones becomes much simpler. You don't have to overhaul the entire system.

Example: Want to add a "Stealth" state to your enemy? You simply add the new state and define how to get into and out of it, without breaking the existing "Patrol" or "Chase" logic.

4. Better Performance

FSM_API is built to be fast. This means your games or applications will run smoother, even when managing many complex characters or systems at once.

Benefit: A more responsive and enjoyable experience for the end-user.

5. Empowers Non-Coders (The "Context" Connection)

The FSM (the brain) contains the logic, while the Context (the body) is the actual object that performs the actions.

When a developer uses FSM_API, they link the FSM to an actual "thing" in your game or application (this "thing" is called the Context).

Example: A game designer might say, "When the character is in the 'Jumping' state, I want them to play the 'Jump_Anim' and add an upward force." The developer then connects the FSM's "Jumping" state to the character's script (their Context) which knows how to play animations and apply force.
Benefit: This clear connection means designers can specify behavior in terms of game actions, and developers can implement it precisely, using the FSM as the bridge.

Who is This For?

Game Designers: Visualize and plan complex character AI, game mechanics, and UI flows with clarity.
Project Managers: Understand the scope and complexity of features related to dynamic behaviors.
QA Testers: Clearly define and test expected behaviors in various scenarios.
Technical Writers: Document system behaviors accurately and concisely.

FSM_API provides a common language and structure that helps bridge the gap between design and implementation, leading to more robust, understandable, and maintainable applications. We are actively working on integrating this into AnyApp, and also preparing it for submission to the Unity Asset Store so developers everywhere can benefit!

Want to Learn More About Development?

If you're interested in learning about the coding side of things from a clear, practical perspective, we highly recommend checking out Tim Corey. He's widely recognized as a fantastic resource for software development, and you can find his insightful content, courses, and community on his platform, DevForge, at iamtimcorey.com.

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

03. Getting Started with FSM_API in Pure C# (From our Documentation)

Fri, 14 Nov 2025 22:19:58 +0000

Previously we published a deep dive included with our documentation in our FSM_API nuget package for our truly unique feature, runtime recomposition/definition of our FSMs. In this article we are sharing our document on Getting started in pure c#. We showed you the power, now let us show you how easy it is to start using our 45kb API. Embrace the pure digital power!

Without further rambling:

03. Getting Started with FSM_API in Pure C#

Use FSM_API with pure C# classes — completely decoupled from Unity — for backend logic, simulations, AI, networking, or any state-based system.

This guide shows how to use FSM_API in non-Unity environments (console, services, backends, robotics, etc.) with clean, minimal dependencies.

Install FSM_API into your c# project using Nuget Package

Within your preferred IDE find FSM_API within the NuGet Package Manager and click install.

Install FSM_API into your project using .NET CLI:

dotnet add package TheSingularityWorkshop.FSM_API

Integrate the API into your project

Integrating the API with any c# application is foremost establishing the heartbeat or cadence of when your FSMs operate.

Example c#:

FSM_API.Interaction.Update("YourProcessingGroupName");//Updates all FSMs registered to this processing group.

consider the simplest integration possible, a console application as shown below:

Example c#:

using TheSingularityWorkshop.FSM_API;

//Define the application context
SimpleDemoContext appContext = new SimpleDemoContext();

//now we enter a loop which will run indefinitely until the handle becomes invalid.
do
{
    //We make this update call which will then update the app fsm.  The app's
    FSM_API.Interaction.Update("Main");
} while (appContext.IsValid);

To help with this understanding we will describe an example below along with additional samples which are available on our samples repo.

Samples Repo

What This Example Will Demonstrate

We’ll simulate a basic character health lifecycle using FSM_API — all in pure C#. This example is useful for understanding how FSM_API integrates into any standard C# application, offering the same benefits as in Unity.

This example illustrates:

How to define and link FSMs to standard C# classes as their context.
How a game character transitions through health-related states (Healthy, Damaged, Critically Injured, Dead).
How FSM_API makes these transitions declarative, clean, and maintainable.
How to manually control the "ticking" of FSMs without relying on a game engine's built-in loop.
How FSMs can be revived and continue operating even after simulated "death."

Simulation Flow

The player starts in the Healthy state.
Over several ticks, they take damage, triggering transitions to:
- Damaged
- Critically Injured
- Dead
After death, a revive command is issued.
Health is restored.
The FSM automatically transitions back to Healthy.

All output is printed to the console to simulate animation, audio, and event feedback — ideal for unit tests or backend game systems.

✅ Step 1: Define Your Pure C# Context

Create a standard C# class to represent the "thing" your FSM will manage — like a character, connection, pipeline, or subsystem. This class will hold the data and methods that your FSM's states will interact with.

It must implement the IStateContext interface. Recall from the 01. Core Concepts: Your Guide to FSM_API that IStateContext requires Name and IsValid properties.

Example: `GameCharacterContext.cs`

Example c#:

using System;
using TheSingularityWorkshop.FSM_API;

public class GameCharacterContext : IStateContext
{
    private float _currentHealth = 100f;
    private int _currentAmmo = 10;
    private float _moveSpeed = 5f;
    private bool _isActive = true;
    private bool _isReviveCommandIssued = false;

    public float CurrentHealth => _currentHealth;
    public int CurrentAmmo => _currentAmmo;
    public float MoveSpeed => _moveSpeed;

    // IStateContext Properties
    public string Name { get; set; }
    public bool IsValid => _isActive; // FSM_API uses this to know if the context is still relevant

    public GameCharacterContext(string name)
    {
        Name = name;
        Console.WriteLine($"{Name} context created.");
    }

    // Methods that FSM states will call to interact with this context
    public void TakeDamage(float amount)
    {
        _currentHealth -= amount;
        Console.WriteLine($"{Name} took {amount} damage. Health: {CurrentHealth}");
    }

    public void SetActive(bool active)
    {
        _isActive = active;
        Console.WriteLine($"{Name} active status set to {_isActive}.");
    }

    public void RestoreHealth(float amount)
    {
        _currentHealth += amount;
        if (_currentHealth > 100f) _currentHealth = 100f;
        Console.WriteLine($"{Name} health restored to {CurrentHealth}.");
    }

    public void SimulateMovement()
    {
        Console.WriteLine($"{Name} is moving at speed {MoveSpeed}.");
    }

    public void PlaySound(string soundName)
    {
        Console.WriteLine($"{Name} playing sound: {soundName}");
    }

    // Methods for transition conditions
    public void IssueReviveCommand() => _isReviveCommandIssued = true;
    public void ClearReviveCommand() => _isReviveCommandIssued = false;
    public bool IsReviveCommandPending => _isReviveCommandIssued;
}

✅ Step 2: Define and Create the FSM

With your context ready, you can now define your FSM using FSM_API.CreateFiniteStateMachine() and its fluent builder pattern. Then, create an instance of that FSM, linking it to your GameCharacterContext.

Example: `PureCSharpGameLoop.cs`

<img src="Visuals/Character_Health_FSM.png" alt="A flowchart of the Character Health FSM showing states and transitions." height="200" style="display: block;">

A flowchart of the Character Health FSM showing states and transitions.

This class will set up our FSM definition and manage the FSM instance within a simulated game loop.

Example c#:

using System;
using TheSingularityWorkshop.FSM_API;

public class PureCSharpGameLoop
{
    private FSMHandle characterHealthFSM;
    private GameCharacterContext playerCharacter;

    public void SetupGame()
    {
        playerCharacter = new GameCharacterContext("Hero");

        // Define the FSM blueprint if it doesn't already exist.
        // The FSM definition is reusable across multiple instances.
        if (!FSM_API.Exists("CharacterHealthFSM"))
        {
            FSM_API.CreateFiniteStateMachine("CharacterHealthFSM", processRate: 1, processingGroup: "GameLogic")
                .State("Healthy",
                    onEnter: ctx => ((GameCharacterContext)ctx).PlaySound("HappyTune"),
                    onUpdate: ctx => 
                        Console.WriteLine($"{ctx.Name} is Healthy. Health: {((GameCharacterContext)ctx).CurrentHealth}"),
                    onExit: ctx => ((GameCharacterContext)ctx).PlaySound("SadTune"))
                .State("Damaged",
                    onEnter: ctx => ((GameCharacterContext)ctx).PlaySound("OuchSound"),
                    onUpdate: ctx => 
                        Console.WriteLine($"{ctx.Name} is Damaged. Health: {((GameCharacterContext)ctx).CurrentHealth}"))
                .State("CriticallyInjured",
                    onEnter: ctx => ((GameCharacterContext)ctx).PlaySound("WarningAlarm"),
                    onUpdate: ctx => Console.WriteLine($"{ctx.Name} is Critically Injured!"))
                .State("Dead",
                    onEnter: ctx => ((GameCharacterContext)ctx).PlaySound("DeathRattle"),
                    onUpdate: ctx => Console.WriteLine($"{ctx.Name} is Dead."),
                    onExit: ctx => ((GameCharacterContext)ctx).ClearReviveCommand())
                .WithInitialState("Healthy")
                .Transition("Healthy", "Damaged", ctx => 
                    ((GameCharacterContext)ctx).CurrentHealth <= 75 && ((GameCharacterContext)ctx).CurrentHealth > 25)
                .Transition("Damaged", "Healthy", ctx => 
                    ((GameCharacterContext)ctx).CurrentHealth > 75)
                .Transition("Damaged", "CriticallyInjured", ctx => 
                    ((GameCharacterContext)ctx).CurrentHealth <= 25 && ((GameCharacterContext)ctx).CurrentHealth > 0)
                .Transition("CriticallyInjured", "Damaged", ctx => 
                    ((GameCharacterContext)ctx).CurrentHealth > 25 && ((GameCharacterContext)ctx).CurrentHealth <= 75)
                .Transition("CriticallyInjured", "Dead", ctx => 
                    ((GameCharacterContext)ctx).CurrentHealth <= 0)
                .Transition("Dead", "Healthy", ctx => 
                    ((GameCharacterContext)ctx).IsReviveCommandPending && ((GameCharacterContext)ctx).CurrentHealth > 0)
                .BuildDefinition();
        }

        // Create a live FSM instance, associating it with our playerCharacter context.
        characterHealthFSM = FSM_API.CreateInstance("CharacterHealthFSM", playerCharacter);
        Console.WriteLine($"FSM for {playerCharacter.Name} initialized to state: {characterHealthFSM.CurrentState}");
    }

    // Call this method from your main application loop to update the FSMs
    public void UpdateGameLogic() => FSM_API.Update("GameLogic");

    // Helper methods for accessing character and FSM state
    public GameCharacterContext GetPlayerCharacter() => playerCharacter;
    public string GetCharacterFSMState() => characterHealthFSM.CurrentState;
}

✅ Step 3: Manual Update Loop

Since you don’t have an engine's Update() or FixedUpdate() loop, you'll explicitly "tick" the FSMs yourself from your main application loop or a dedicated manager. You'll call FSM_API.Update() for the processing group you defined.

Example: `Program.cs` (Main Application Entry Point)

<img src="Visuals/Simulation_Timeline.png" alt="A timeline of the 20-tick simulation showing key events and state changes." height="200" style="display: block;">

A timeline of the 20-tick simulation showing key events and state changes.

Example c#:

using System;
using System.Threading; // For Thread.Sleep

public class Program
{
    public static void Main(string[] args)
    {
        Console.WriteLine("--- Starting Pure C# FSM Demo ---");

        var game = new PureCSharpGameLoop();
        game.SetupGame();
        var player = game.GetPlayerCharacter();

        for (int i = 0; i < 20; i++) // Simulate 20 game ticks
        {
            Console.WriteLine($"\n--- Tick {i + 1} ---");

            // Simulate events that affect the character's health
            if (i == 2) player.TakeDamage(30);   // Health: 100 -> 70 (Healthy -> Damaged)
            if (i == 5) player.TakeDamage(20);   // Health: 70 -> 50 (Still Damaged)
            if (i == 8) player.TakeDamage(30);   // Health: 50 -> 20 (Damaged -> Critically Injured)
            if (i == 10) player.TakeDamage(20);  // Health: 20 -> 0 (Critically Injured -> Dead)
            if (i == 12) player.IssueReviveCommand(); // Issue revive command
            if (i == 13) player.RestoreHealth(100);    // Restore health, FSM should transition Dead -> Healthy

            // Advance the FSMs in the "GameLogic" processing group
            game.UpdateGameLogic();

            Console.WriteLine($"Current FSM State: {game.GetCharacterFSMState()}");
            Thread.Sleep(500); // Optional: pause for half a second to observe output
        }

        Console.WriteLine("\n--- FSM Demo Finished ---");
    }
}

Running the Example

To run this pure C# FSM example:

Create a Console App Project in your preferred IDE (e.g., Visual Studio, VS Code with C# extension).
Add FSM_API Reference:
- If FSM_API is available on NuGet, add it via the NuGet Package Manager.
- Otherwise, manually add a reference to the TheSingularityWorkshop.FSM_API.dll file.
Add Code Files:
- Create GameCharacterContext.cs and paste the code from Step 1.
- Create PureCSharpGameLoop.cs and paste the code from Step 2.
- Replace the content of Program.cs with the code from Step 3.
Run the App and observe the FSM transitions and console output, which will show your character moving through different health states.

✅ Summary

FSM_API works seamlessly outside of Unity and other game engines, providing a powerful FSM solution for any pure C# application.
You define your application's data models or entities as classes that implement the IStateContext interface.
FSM definition and instantiation logic remain consistent with Unity usage, using FSM_API.CreateFiniteStateMachine() and FSM_API.CreateInstance().
You gain explicit control over when FSMs process their logic by calling FSM_API.Update("YourGroupName") from your application's main loop or scheduler.
This makes FSM_API an ideal choice for server-side logic, complex simulations, AI systems, backend services, or custom game engines where you need robust and decoupled state management.

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
Advanced Integration On Unity Asset Store!
Basic Integration is pending updates on Marketing content.

Brought to you by

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

Because state shouldn’t be a mess.

06_FSM_Modifier Deep Dive: Modifying Your FSMs at Runtime (From our Documentation)

Fri, 14 Nov 2025 17:46:04 +0000

The FSM_API Advantage: Runtime Modification Technology

What sets the FSM_API apart is our FSMModifier technology, which allows for the dynamic reconstitution or definition of your Finite State Machines (FSMs) during runtime. No other FSM implementation offers this level of dynamic control over an FSM's blueprint after creation.

We believe in providing the deepest, most robust tools while allowing you to engage only as far as you need. We've done the deep theoretical work so you don't have to.

06. FSMModifier Deep Dive: Modifying Your FSMs at Runtime

The FSMModifier provides advanced capabilities to dynamically alter the blueprint (definition) of your Finite State Machines at runtime. This allows for highly adaptive behaviors, hot-swappable logic, or configuration changes without rebuilding your application.

While the FSMBuilder is used to initially design and build an FSM's definition, the FSMModifier allows you to change that definition after it has been created and registered with FSM_API. This is a powerful feature for scenarios requiring:

Adaptive AI: Changing an enemy's behavior patterns on the fly (e.g., learning new attacks, adapting to player strategies).
Dynamic UI: Adding or removing navigation paths or UI states based on user unlocks or content downloads.
Hot Reloading: Modifying FSM logic in a live environment (e.g., development tools for rapid iteration).
A/B Testing: Dynamically switching between different FSM behaviors for experimentation.

Table of Contents (Disabled for this article)

0. Introduction to FSM_API

Core Concepts: Your Guide to FSM_API
Getting Started with C# (Non-Unity)
FSMBuilder Deep Dive: Building Your FSMs
Understanding and Implementing Your Context (IStateContext)
Robust Error Handling: Cascading Degradation System
FSMModifier Deep Dive
Performance Tips & Best Practices
Common Use Cases & Examples
FSM_API for Non-Coders: A Big Picture Overview
Frequently Asked Questions (FAQ)

Accessing and Using the FSMModifier

The FSMModifier is an internal class, so you can't create it directly. Instead, you access its functionality through a set of public, static helper methods on FSM_API.Interaction. These methods are designed to simplify common modification tasks like adding or removing states and transitions.

The FSMModifier uses a fluent API pattern where you first stage the changes you want to make and then apply them with a single ModifyDefinition() call. All changes are batched and applied sequentially when ModifyDefinition() is called, making the process safe and predictable.

FSMModifier Methods: Altering the Blueprint

All the methods below are called on an instance of the FSMModifier class. You get this instance by calling a public method on FSM_API.Interaction.

Staging Changes with With... and Without...

`WithState()`: Adding a New State

This method adds a new state to an existing FSM definition. If a state with the given name already exists, the operation is ignored. Use WithModifiedState() to change an existing state.

C# Example:

FSM_API.Interaction.AddStateToFSM(
    "PlayerFSM",
    "SpecialAttack",
    onEnter: ctx => Console.WriteLine("Prepare special attack!"),
    onUpdate: ctx => Console.WriteLine("Execute special attack."),
    onExit: ctx => Console.WriteLine("Cleanup after special attack.")
);

`WithModifiedState()`: Updating an Existing State

This method modifies the actions (onEnter, onUpdate, and onExit) of a state that is already part of the FSM blueprint. If the state doesn't exist, the operation is ignored.

C# Example:

// Change the "Idle" state's behavior
FSM_API.Interaction.ModifyState(
    "PlayerFSM",
    "Idle",
    onEnter: ctx => Console.WriteLine("Entered a NEW and improved Idle state."),
    onUpdate: null, // You can pass null to remove an action
    onExit: ctx => Console.WriteLine("Exiting new Idle state.")
);

`WithoutState()`: Removing a State

This method stages a state for removal from the FSM definition.

C# Example:

// Remove a state and transition all instances to "InitialState"
FSM_API.Interaction.RemoveStateFromFSM("PlayerFSM", "Dead", null);

Important: When a state is removed, any active FSMHandle instances currently in that state will be immediately transitioned to a specified fallbackStateName. If you pass null or an empty string for the fallback, instances will automatically transition to the FSM's InitialState. The OnExit action of the removed state will be executed for these instances.

`WithTransition()`: Creating a New Path

This method adds a new transition rule between two states. If the transition already exists, the operation is ignored. Use WithModifiedTransition() to change an existing one.

C# Example:

// Add a new transition from "Idle" to "Sleeping"
FSM_API.Interaction.AddTransition(
    "PlayerFSM",
    "Idle",
    "Sleeping",
    ctx => ((PlayerContext)ctx).IsTired() && DateTime.Now.Hour > 21
);

`WithModifiedTransition()`: Updating a Transition

This method updates the condition of an existing transition between two states. If the transition doesn't exist, the operation is ignored.

C# Example:

// Change the condition for the "Damaged" -> "CriticallyInjured" transition
FSM_API.Interaction.ModifyTransition(
    "PlayerFSM",
    "Damaged",
    "CriticallyInjured",
    ctx => ((CharacterContext)ctx).Health <= 10 // Change from 25 to 10
);

`WithoutTransition()`: Blocking a Path

This method removes a specific transition rule. It requires the fromState and toState names to uniquely identify the transition.

C# Example:

// Remove the transition from "Running" to "Jumping"
FSM_API.Interaction.RemoveTransition("PlayerFSM", "Running", "Jumping");

Manipulating Live FSM Instances (FSMHandle)

While FSMModifier changes the FSM blueprint, the FSMHandle provides methods to directly influence individual, live FSMHandle instances at runtime. These operations do not alter the underlying FSM definition.

TransitionTo(): Forces an FSMHandle instance to immediately transition to a specified state, bypassing any conditions. This is useful for debug commands or for recovering from an error state.
ResetFSMInstance(): Resets the FSM instance to its initial state, as defined in its blueprint.
EvaluateConditions(): Manually checks all transition rules from the current state. This is especially useful for FSMs with a ProcessRate of 0, which do not update automatically.
DestroyHandle(): Shuts down this FSM instance, removes it from the API's internal system, and calls the OnExit action of its current state. This is a crucial cleanup step for any live instance that is no longer needed.

Important Considerations and Best Practices

Affects All Instances: Remember that changes made with FSMModifier affect the shared blueprint. All active FSMHandle instances created from that blueprint will immediately use the new states, transitions, and properties on their next update cycle.
Atomicity: The FSMModifier stages changes and applies them all at once when ModifyDefinition() is called. This is a robust design that prevents partial or inconsistent changes from corrupting the FSM blueprint.
State Removal is Handled Gracefully: The API will automatically handle instances in a removed state by transitioning them to a fallback state, ensuring your application doesn't crash or get stuck in an invalid state.

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
Advanced Integration On Unity Asset Store!
Basic Integration is pending updates on Marketing content.

Brought to you by

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

Because state shouldn’t be a mess.

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

Engineering "The" Loop

Tue, 04 Nov 2025 21:24:46 +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
Advanced Integration On Unity Asset Store!
Basic Integration is pending updates on Marketing content.

Brought to you by

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

Because state shouldn’t be a mess.

raWWar: The Galactic RTS So Ambitious It Forced Us to Invent a New Technology

Tue, 28 Oct 2025 23:10:46 +0000

At The Singularity Workshop we are building software for the singularity. Our latest Milestone has been reached: the resubmission of our Unity Integration package for sale on the Unity Asset Store. Before the release of our 45kb of raw digital power, and before our integration with Unity, there was the driving vision which forced us to forge our core technology, and then integrate it back into Unity.

I. The Vision of Unprecedented Scale

We are focused on the 4X aspect of our game: letting our players wage war on a scale beyond anything ever seen on Earth. The player's role is that of a grand strategist, watching the battle happen safely from their bunker on a holographic table, surrounded by their support staff, commanders, and advisors.

A. The Necessity of Low-Poly

To achieve the scale necessary for this vision—allowing for massive conflict simulation—we deliberately chose a low-poly aesthetic. This decision is not about style; it’s about performance, enabling our engine to simulate the massive 4X-scale conflict we promise.

We started with these assets:

Canopus-III Low Poly Sci-fi Desert Units Set

Canopus-III Low Poly Sci-fi Desert Units Set 2

Canopus-III Low Poly Sci-fi Desert Units Set 3

II. The Solution: FSM_API Technology

Our commitment to scale is unlocked by the FSM_API, a proprietary Finite State Machine system. This technology is designed to handle incredibly complex unit behaviors without becoming overly complex for developers. Because we are leveraging the FSM_API, we can create these behaviors efficiently. This is the core technology enabling true digital singularity.

A. The Digital Lifeblood: Our Soldier

We decided that the soldier will be the heart of our game.

Our soldiers are trained from a highly advanced barracks which has VR training modules for a single squad. Once trained the squad leaves the barracks and, if not immediately assigned to another training program, will begin marching around the player's base. Barracks using the same technology allow squads to be trained how to operate vehicles, use weapons, pilot aircraft, etc. Barracks can also be tooled to provide additional training, increasing the squad's operational ability. A soldier must undergo a complete training program before they and their squad can hop into a tank and operate it.

Now here our soldiers are standing ready for review!

III. Proof of Concept: The MVP Demo

We determined that our critical path to release is to establish an MVP demo that allows for a quick immersion, giving players an immediate idea of what to expect. We targeted the arrival of the player with their forces arrayed before them for review as a great start.

Here is what the player would see upon starting our demo:

Here is a bird's eye view:

This demo provides enough environment to give the idea of what we are striving for, while keeping it simple enough for rapid development. The player simply walks forward to the HQ building where their advisor will greet them and inform them that the rest of the game is currently under development.

A. The Next Challenge: Oppressive Darkness

Our work now shifts to bringing down the visibility to make the environment oppressively dark. We want to show the environment through the high-contrast lenses of the light beams from our various light sources (light posts, headlights, etc.). This design choice provides a stripping down of visual context, creating a naturally dark and oppressive feeling environment, which is the goal... to immerse the player and make them feel innate dread, the inner fear of darkness we all acquired from our ancestors... The lack of visual context only makes our small demo feel much more massive.

Stay tuned as we bring this static scene to life using the power of our API.

Attributions and Credits

A shout out to the talent who created the assets we are bringing to life:

Asset Creator: Planesfar studio

Canopus-III Low Poly Sci-fi Desert Units Set

Canopus-III Low Poly Sci-fi Desert Units Set 2

Canopus-III Low Poly Sci-fi Desert Units Set 3

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.

FSM API (Advanced) for Unity

Mon, 27 Oct 2025 20:56:19 +0000

The Singularity Workshop is proud to announce a pivotal achievement: After months of rigorous architectural design and engineering, we have successfully released 'The Singularity Workshop - FSM API (Advanced)' on the Unity Asset Store! This is a successful milestone, and we are just getting started.

As dedicated readers of our work know, our focus is on robust software architecture, grounded in the deep theoretical understanding and powerful application of Finite State Machines (FSMs). This Unity Asset is the direct culmination of those efforts.

The Paradigm Shift is Here

Get ready to escape the chaos of Update() spaghetti and embrace a true architectural paradigm shift. Our API is engineered for decoupling and high reusability, allowing you to build complex behavior through the composition of simple, independent FSM blueprints.

As demonstrated in our work on Multi-Context FSMs, you can now apply multiple, independent FSMs to a single object's Transform simultaneously without interference, resulting in game systems that are scalable, maintainable, and profoundly robust.

Documentation as a Core Feature

We engineered this API to be universally accessible, spending as much time on learning materials as we did on the code itself. Our goal is to bring non-coders and non-C# programmers into this new paradigm.

Beyond the comprehensive user guide, you can check out our NuGet package which contains the core API and an extensive Theory Guide that dives deep into:

The fundamental mathematical models behind FSMs.
FSM types, classifications, and operational theory.

Once you understand the "What," our API documentation walks you through the "How," making the process of creating complex behavior accessible to anyone willing to learn the abstraction.

Explore the future of Unity behavior architecture today ($30 package on sale for $21 for two weeks on the Unity Asset Store!):

The Singularity Workshop - FSM API (Advanced)

Reference the Core Engine & Theory Guides:
TheSingularityWorkshop.FSM_API NuGet Package

The paradigm shift is here. We look forward to publishing deep dives into the API's advanced architecture and applications very soon!

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.

When Unity Glitches, You Build Your Own Loop: The Four-Line App Core

Sat, 18 Oct 2025 01:02:55 +0000

Every developer has a story about an IDE or engine glitch that made them momentarily question their career choices. For me, that moment arrived late one evening, tracing a bug in our FSM-driven agents. Unity's Inspector decided to go on strike, showing empty fields without labels—the digital ghosts of components past.

The simple fix? Close Unity. Reopen. Wait 10 minutes.

It was late. I was done waiting.

Instead, in an exhausted fit of annoyance and clarity, I opened a fresh C# console, installed The Singularity Workshop's FSM API, and let my fingers dance. The next morning, groggy and foggy, I realized I had accidentally conceived an entire, engine-agnostic application core.

Laugh at the simplicity, then realize this genuinely works! This is the entire executable heart of a Windows Desktop application:

public class Program
{
    public static void Main(string[] args)
    {
        // 1. Instantiate the Context: Our Platform-Specific "Drone as I like to think of it"
        var appContext = new AppWindowsDesktopContextFSM(args); 
        
        // 2. Create the live Execution FSM bound to that Context
        FSM_API.Create.CreateInstance("ExecutionFSM", appContext, "Update");

        // 3. The Self-Terminating Loop
        do
        {
            // Tick the FSM: Advance one logical step
            FSM_API.Interaction.Update("Update");
        } while (appContext.IsValid); // Control flow determined by the Context's vital sign
    }
}

That's it. This four-line do-while block is less boilerplate than setting up a complex, multi-threaded worker class, yet it provides unparalleled decoupling.

The Conceptual Leap: Context-Driven Execution

The conceptual breakthrough is that the traditional while (IsRunning) loop, where control is external to the core logic, is entirely replaced by a check against the IStateContext.

The Context as the Application's Heartbeat

The loop's survival depends entirely on appContext.IsValid. This property is required by the IStateContext interface.

If IsValid is true, the loop runs, calling FSM_API.Interaction.Update() to execute the current state and check for transitions.
If IsValid returns false, the loop breaks, and the application cleanly exits. The FSM API even automatically cleans up the associated FSMHandle instance.

The application's "ExecutionFSM" is defined to contain states like Initializing, Running, and ShuttingDown. When a transition leads to the ShuttingDown state, the OnEnter action simply calls a method on the AppContext (our "Drone") that sets an internal flag, making IsValid flip to false.

The FSM dictates when to die; the Context executes how.

Unparalleled Platform Decoupling

This pattern achieves the holy grail of platform-agnostic logic:

The FSM Definition ("ExecutionFSM") is Pure Logic: It knows nothing about Windows, Unity, or Android. It only knows about states (e.g., ProcessingInput, SavingData) and transitions (e.g., OnInputProcessed → ToState). This definition can be used anywhere.
The Context (AppWindowsDesktopContextFSM) is Pure Platform Abstraction: This class is where all the OS-specific heavy lifting lives. A state's OnEnter action might call ((AppWindowsDesktopContextFSM)ctx).InitializeWindow() or ((AppConsoleContext)ctx).ParseArgs().

The FSM definition remains constant, knowing only that the action is ctx.DoThing(). The behavior behind DoThing() is entirely specific to the AppWindowsDesktopContextFSM running on the client machine. This means the same "ExecutionFSM" definition can be shared across our Console, Windows Desktop, and (ironically) future Unity integrations, providing the necessary FSM behaviors without ever compromising the core logic to platform constraints.

In the end, closing Unity would have taken 10 minutes. Building this foundational piece of software architecture took most of the night. But now, we have an application core that is robust, modular, and immune to inspector glitches. WTF indeed!

Support the Vision and See the Code!

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.

The FSM Agent Architecture: Scaling NavMesh Agents with Decoupled Logic

Wed, 15 Oct 2025 20:27:35 +0000

The FSM Agent Architecture: Scaling NavMesh Agents with Decoupled Logic

We've mastered simple oscillating motion with the FSM Context Pattern; now, we apply this powerful architectural approach to a far greater challenge: Massive NavMesh Agent AI. Instead of relying on a monolithic Update() loop, we delegate the complex logic of pathfinding, target acquisition, and state management into reusable Finite State Machine blueprints.

Our goal for this series is twofold: achieve stable, high-performance AI for hundreds of agents, and develop a system resilient to complex emergent behaviors that inevitably arise at scale.

This article introduces the two core components that make up our scalable agent system.

The Two Pillars of the FSM Agent System

Our architecture separates the agents from the environment, ensuring each component is only responsible for its own domain, which is the key to reusability and stability.

1. The Environment: `NavMeshAgentsDemo.cs` (The Orchestrator)

The NavMeshAgentsDemo class serves as the central context for the entire simulation. Its primary responsibility is orchestration and resource distribution.

Target Management: It holds the list of targets (targets list) that agents will navigate to. It includes a helper function, GetRandomTarget, which ensures agents don't immediately re-select the target they just left, promoting better distribution.
Initialization: In the main FSM's OnEnterExecuting state, the demo dynamically creates our agents. It instantiates the agentPrefab, assigns the environment reference (agentFSM.Environment = demo.Status), and gives each agent a unique color for easy visual tracking.
Scale Setup: For our first test, the NumberAgents property is set to a manageable value (e.g., a few dozen). At this scale, the system works perfectly, with agents moving smoothly between targets, proving the foundational architecture is sound.

2. The Agent: `NavMeshAgentFSM.cs` (The Decoupled AI)

This is where the magic happens. The NavMeshAgentFSM class is both a MonoBehaviour (to interface with the NavMeshAgent component and physics events) and an IStateContext that drives its own FSM instance.

The agent's logic is boiled down to a simple, three-state cycle defined in the FSM blueprint, which is created only once:

State	Role	Key Logic
Idle	Target Acquisition	The agent is stopped and contacts the `Environment` to get a new target. This is where the heavy work (target look-up) is performed.
Moving	Path Execution	The agent's `NavMeshAgent` component handles movement to the destination set during Idle. The FSM transitions out when collision with the target is detected.
Contacted	Arrival Confirmation	The agent confirms arrival (`Arrived = true`), and the physics collider is temporarily disabled to prevent it from immediately getting stuck on the target.

The power here is delegation: the FSM defines when the agent decides (Idle) and when it confirms arrival (Contacted), while the NavMeshAgent component (outside the FSM's Update loop) handles the complex movement how.

The Early Success (Small Batch)

When we run the simulation with a small number of agents (e.g., 20–50), the system is seamless.

The FSM Context Pattern successfully replaces the traditional Update() based AI:

Instead of constantly checking if if (target != null && distance < threshold), the system waits in the Moving state and is triggered only by the OnCollisionEnter physics event, which flips the Arrived flag.
The Idle state automatically handles the transition out to Moving once a target is assigned, using the AssignedTarget predicate check (return agent.Target != null).

The foundation is solid, proving that the FSM Context Pattern is highly effective for managing AI state.

Next, we push to a high agent count, but this is where the new architectural challenge arises...

In the next article, we will reveal the performance optimization that allows us to run over 1,000 agents and introduce the subtle, yet critical, emergent behavior known as Agent Gridlock.

Support the Vision and See the Code!

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.

The Grand Finale: Orchestrating Complex Motion with Multi-Context FSMs

Wed, 15 Oct 2025 19:35:04 +0000

We've successfully established a reusable architectural pattern by isolating the data (Context) from the logic flow (Finite State Machine) for the three primitive motions: Rotation, Scaling, and Translation. We created three distinct, independent blueprints—"RotationFSM," "ScalarFSM," and "TranslationFSM"—each driving separate objects on various axes.

Now, for the grand finale: we will demonstrate the true power of this decoupled architecture by applying all three FSM blueprints simultaneously to the same three objects, achieving a perfectly synchronized, multi-dimensional motion effect.

This isn't about creating a new FSM; it's about proving the flexibility and reusability of the existing ones. We will show that one object can be driven by multiple, independently managed FSM contexts, eliminating the need for a monolithic, complex state machine.

The Power of Decoupled Contexts

The core principle remains the same: the FSM definition is the reusable logic (the how), and the Context is the unique data (the what).

In our previous demos, we created one Context per object. In the Combined Motion Demo, we create three Contexts per object.

Object	Rotation Demo	Scalar Demo	Translation Demo	Combined Demo
X-axis Cube	RotationContext	ScaleContext	TranslationContext	RotationFSM, ScalarFSM, TranslationFSM
Y-axis Cube	RotationContext	ScaleContext	TranslationContext	RotationFSM, ScalarFSM, TranslationFSM
Z-axis Cube	RotationContext	ScaleContext	TranslationContext	RotationFSM, ScalarFSM, TranslationFSM

The FSM framework handles each Context instance completely independently. When the Unity Update() loop runs, it executes the update for all nine individual FSM instances (three contexts * three objects), resulting in the compound motion.

The Entry Point: SimpleRotationScalarTranslationDemo.cs

The SimpleRotationScalarTranslationDemo.cs file is the orchestrator, instantiating the nine required Contexts in its main FSM's OnEnterExecuting method.

Instantiation Logic: Three-in-One

The code combines the instantiation logic from all three previous demos. For the XaxisCube, we instantiate a ScaleContext, a TranslationContext, and a RotationContext, all referencing the same demo.XaxisCube Transform.

private void OnEnterExecuting(IStateContext context)
{
    if (context is SimpleRotationScalarTranslationDemo demo)
    {
        // === X-AXIS CUBE ===
        // 1. Scale FSM (Uses ScaleContext/ScalarFSM)
        ScaleContext scX = new ScaleContext(demo.XaxisCube, new Vector3(1, 0, 0), 0.5f, 3f, 0.5f);
        // 2. Translation FSM (Uses TranslationContext/TranslationFSM)
        TranslationContext tcX = new TranslationContext(demo.XaxisCube, new Vector3(1, 0, 0), 1f, 2f, -2f);
        // 3. Rotation FSM (Uses RotationContext/RotationFSM)
        RotationContext rcX = new RotationContext(demo.XaxisCube, new Vector3(1, 0, 0), 90f, 45f, -45f);
       
        // === Y-AXIS CUBE ===
        // ... (Similar instantiation for Y-axis cube, using (0, 1, 0) for the axis)
        ScaleContext scY = new ScaleContext(demo.YaxisCube, new Vector3(0, 1, 0), 0.5f, 3f, 0.5f);
        TranslationContext tcY = new TranslationContext(demo.YaxisCube, new Vector3(0, 1, 0), 1f, 2f, -2f);
        RotationContext rcY = new RotationContext(demo.YaxisCube, new Vector3(0, 1, 0), 90f, 45f, -45f);
       
        // === Z-AXIS CUBE (Note: Scale is multi-axis for visual flair) ===
        // ... (Similar instantiation for Z-axis cube, using various axes)
        ScaleContext scZ = new ScaleContext(demo.ZaxisCube, new Vector3(1, 1, 0), 0.5f, 3f, 0.5f);
        TranslationContext tcZ = new TranslationContext(demo.ZaxisCube, new Vector3(0, 0, 1), 1f, 2f, -2f);
        RotationContext rcZ = new RotationContext(demo.ZaxisCube, new Vector3(0, 0, 1), 90f, 45f, -45f);
    }
}

The Decoupled FSMs in Action

Because each Context is an independent data container, the FSM framework executes them separately, resulting in simultaneous, non-interfering motion:

The RotationContext drives the TransformHandle.localRotation.
The ScaleContext drives the TransformHandle.localScale.
The TranslationContext drives the TransformHandle.localPosition.

Each FSM instance has its own independent state and transitions, yet they all operate on the same object's Transform. The result is a fascinating display: the Z-axis Cube, for instance, oscillates along the Z-axis (Translation), pulses in size along the X and Y axes (Scaling), and swings around the Z-axis (Rotation).

Conclusion: True Architectural Victory

This Combined Motion Demo is the ultimate proof of the FSM Context Pattern's power:

Separation of Concerns: We fully separated the primitive operations. Modifying the boundary check for rotation, for instance, has zero impact on the translation or scaling logic.
High Reusability: We did not write a single new state machine definition for this complex demo. We simply reused the "RotationFSM," "ScalarFSM," and "TranslationFSM" blueprints.
Scalable Complexity: An object's behavior is now a composition of independent FSM-driven movements. If we need to add a "Color Modulation FSM," we simply instantiate a fourth context for each object.

This decoupled architecture provides the foundation for robust, maintainable, and highly extensible game systems. You've escaped Update() spaghetti and unlocked the ability to compose complex behaviors from simple, reusable, and independent parts.

See it in action on YouTube (Don't forget to like and subscribe!):

https://youtu.be/1lKBINkTtYM

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.

️ Help Shape Our Next FSM_API Deep Dive! Take our Developer Poll on strawpoll

Wed, 15 Oct 2025 05:54:16 +0000

We're constantly striving to deliver the most valuable, actionable content for the Coder Legion community. Our FSM_API and the Unity Integration package cover a broad range of technical scenarios—from core C# logic to real-time game state—and we want your vote to decide where we dedicate our next major technical article and tutorial.

Whether you're building high-performance cloud backends or complex in-game AI, your vote directly prioritizes our content pipeline.

Please take a moment to cast your vote below!

FSM_API Developer Interest Poll

Patreon Page

Support Us

Completing the Motion Trilogy: The Reusable TranslationFSM

Tue, 14 Oct 2025 22:23:29 +0000

Completing the Motion Trilogy: The Reusable TranslationFSM

We've conquered Rotation and streamlined Scaling using our FSM Context Pattern. In this article, we tackle the final primitive motion—Translation (linear movement)—to complete our core motion trilogy.

The biggest takeaway here is the demonstration of true architectural reuse. We define a new Context class and a new FSM, but the logic flow remains 100% identical to the Rotation and Scaling demos.

1. The Context: Swapping Scale for Position Parameters

We isolate the specific data required for linear position change into the TranslationContext class.

The primary conceptual difference from the Scale/Rotation demos lies in how boundaries are established: Translation must calculate its absolute boundaries relative to the object's starting local position (OriginalPosition). This ensures the oscillation is centered around the object's initial placement.

Previous Context Parameters	Translation Context Parameters	Purpose
ScaleSpeed (float)	MoveSpeed (float)	Linear speed of position change.
ScaleAxis (Vector3)	MoveAxis (Vector3)	The axis (or axes) to apply the movement along.
MaxScale / MinScale	MaxPosition / MinPosition	The absolute position bounds, calculated from `OriginalPosition`.

TranslationContext.cs: Absolute Boundary Calculation

The TranslationContext calculates the precise MaxPosition and MinPosition by using the dot product to find the object's starting coordinate along the movement axis, and then adding/subtracting the desired displacement.

public class TranslationContext : IStateContext
{
    // The new parameters that define linear movement
    public float MoveSpeed = 1.0f;
    public float MaxPosition = 5.0f;
    public float MinPosition = -5.0f;
    
    public Vector3 MoveAxis;
    public Vector3 OriginalPosition = Vector3.zero;

    // ... Constructor logic
    // 2. Calculate the absolute Max/Min boundaries:
    this.MaxPosition = initialCoord + maxPos;
    this.MinPosition = initialCoord + minPos;
    // ...
}

2. The FSM Definition: The Same Engine, New States

The Finite State Machine flow is identical to the Rotation and Scalar demos (Move $\rightarrow$ Max $\rightarrow$ Move Back $\rightarrow$ Min). The blueprint name is now "TranslationFSM".

Scalar FSM	Translation FSM (Change)
States: ScalingUp	States: MovingForward
States: ScalingDown	States: MovingBackward
Predicate: Apex	Predicate: MaxReached
Predicate: Root	Predicate: MinReached

The Core Logic (Simple Vector Math)

The state updates are handled by direct vector math applied to localPosition using Time.deltaTime for smooth, framerate-independent movement.

// The OnUpdateMovingForward function within TranslationContext.cs
private void OnUpdateMovingForward(IStateContext context)
{
    if (context is TranslationContext tc)
    {
        // Add the movement vector based on speed and time
        tc.TransformHandle.localPosition += tc.MoveAxis * (tc.MoveSpeed * Time.deltaTime);
    }
}

The transition predicates, MaxReached and MinReached, use the Dot Product to extract the object's current coordinate along the axis, comparing it to the absolute MaxPosition/MinPosition boundary values calculated earlier.

3. The Entry Point: Final Proof of Reusability

The SimpleTranslationDemo.cs handles the instantiation. We simply provide three different MoveAxis vectors to three unique TranslationContext instances, all utilizing the same "TranslationFSM" definition.

private void OnEnterExecuting(IStateContext context)
{
    if (context is SimpleTranslationDemo std)
    {
        float moveSpeed = 1.0f;
        float maxDisplacement = 2.0f;
        float minDisplacement = -2.0f;
        
        // 1. X-axis: MoveAxis (1, 0, 0)
        TranslationContext xAxisContext = new TranslationContext(std.Xaxis, new Vector3(1, 0, 0), moveSpeed, maxDisplacement, minDisplacement);
        std.XaxisHandle = xAxisContext.Status; 

        // 2. Y-axis: MoveAxis (0, 1, 0)
        TranslationContext yAxisContext = new TranslationContext(std.Yaxis, new Vector3(0, 1, 0), moveSpeed, maxDisplacement, minDisplacement);
        std.YaxisHandle = yAxisContext.Status; 

        // 3. Z-axis: MoveAxis (0, 0, 1)
        TranslationContext zAxisContext = new TranslationContext(std.Zaxis, new Vector3(0, 0, 1), moveSpeed, maxDisplacement, minDisplacement);
        std.ZaxisHandle = zAxisContext.Status;
    }
}

Conclusion: Architectural Reusability Confirmed

With the implementation of the TranslationFSM, we have successfully completed our core motion trilogy, elegantly managing Rotation, Scaling, and Translation using a single, unified architectural approach.

The key takeaway is the profound level of architectural reuse we achieved. By isolating the unique data (the what) into the Context class and retaining the generic logic flow (the how) within the FSM blueprint, we were able to build three distinct motion systems with virtually identical FSM definitions. This pattern has proven its ability to handle different primitive operations—be it altering localRotation, localScale, or localPosition—simply by swapping out the specialized context. This kind of separation of concerns leads to robust, maintainable, and highly reusable code.

The final proof of concept in SimpleTranslationDemo.cs, simultaneously orchestrating three separate translation contexts with one FSM blueprint, underscores the pattern's efficiency and flexibility.

Up Next: The Grand Finale

We've mastered the primitives. In the final article of this series, we'll connect the three systems—RotationFSM, ScalingFSM, and TranslationFSM—to a single object. Get ready for the Combined Motion Demo, where we'll show an object spinning, pulsing, and oscillating all at once, driven by multiple, independently managed FSM contexts. This is where the true power of this decoupled architecture shines! Keep an eye out for the final installment.

See the demo in action:
YouTube Channel Video

Support the Vision and See the Code!

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.

Applying the FSM Context Pattern to Scaling: The Reusable ScalarFSM

Tue, 14 Oct 2025 21:23:15 +0000

Applying the FSM Context Pattern to Scaling: The Reusable ScalarFSM

In our previous article, we demonstrated how to eliminate Update() spaghetti by applying the FSM Context Pattern to complex Rotation logic. The result was a single, reusable blueprint ("RotationFSM") that drove three objects on different axes.

Here, we prove the true versatility of this pattern by applying it to Scale motion. The vast majority of the logic remains the same—only the Context data and the specific Unity functions change.

1. The Context: Swapping Angular for Linear Parameters

The core philosophy remains: isolate the specific data required for the motion. We move from the RotationContext to the ScaleContext.

Rotation Context Parameters	Scale Context Parameters	Purpose
RotationSpeed (float)	ScaleSpeed (float)	Linear speed of scale change.
RotationAxis (Vector3)	ScaleAxis (Vector3)	The axis (or axes) to apply the scale along.
MaxAngle / MinAngle	MaxScale / MinScale	The absolute min and max bounds for the object's local scale.

ScaleContext.cs: Data Encapsulation

The ScaleContext holds the new parameters and is what ultimately manipulates the TransformHandle.localScale.

public class ScaleContext : IStateContext
{
    // The new parameters that define scaling motion
    public float ScaleSpeed = 0.5f;
    public float MaxScale = 3.0f;
    public float MinScale = 0.5f;

    public Vector3 ScaleAxis;
    public Vector3 OriginalScale = Vector3.one;

    public Transform TransformHandle;
    // ...
}

2. The FSM Definition: Same Flow, New Names

The Finite State Machine flow is identical to the rotation demo (Move $\rightarrow$ Max $\rightarrow$ Move Back $\rightarrow$ Min) but uses domain-appropriate terminology.

The blueprint name changes from "RotationFSM" to "ScalarFSM".

Rotation FSM	Scalar FSM (Change)
States: RotatingForward	States: ScalingUp
States: RotatingBackward	States: ScalingDown
Predicate: MaxReached	Predicate: Apex
Predicate: MinReached	Predicate: Root

The Core Logic (The Only Update)

Instead of applying a Quaternion update using Quaternion.AngleAxis, the state update logic now directly modifies the localScale vector using the ScaleAxis vector stored in the Context.

// The OnUpdateScalingUp function within ScaleContext.cs
private void OnUpdateScalingUp(IStateContext context)
{
    if (context is ScaleContext sc)
    {
        // Linearly increase the scale along the specified axis(es)
        Vector3 scaleDelta = sc.ScaleAxis * (sc.ScaleSpeed * Time.deltaTime);
        sc.TransformHandle.localScale += scaleDelta; // The only movement line!
    }
}

The elegance here is that the state engine (the FSM) required zero changes. We only updated the specific motion logic inside the state functions of the new ScaleContext.

3. The Entry Point: Demonstrating Multi-Axis Motion

The SimpleScalarDemoFSM.cs acts as the entry point. This demo highlights a capability easily solved with scaling that was slightly more complex with rotation: multi-axis movement.

Notice how the third instance utilizes a ScaleAxis vector with multiple components set to 1 to drive a single FSM instance to scale along both the X and Y axes simultaneously.

private void OnEnterExecuting(IStateContext context)
{
    if (context is SimpleScalarDemoFSM ssd)
    {
        float speed = 0.5f;
        float maxScale = 3f;
        float minScale = 0.5f;
        
        // 1. X-axis Scale
        ScaleContext xAxisContext = new ScaleContext(ssd.Xaxis, new Vector3(1, 0, 0), speed, maxScale, minScale);
        
        // 2. Y-axis Scale
        ScaleContext yAxisContext = new ScaleContext(ssd.Yaxis, new Vector3(0, 1, 0), speed, maxScale, minScale);
        
        // 3. XY-axis Scale: Scales on X and Y using the *same* FSM definition
        ScaleContext xyAxisContext = new ScaleContext(ssd.XYaxis, new Vector3(1, 1, 0), speed, maxScale, minScale);
        
        // ... Instantiate all handles and transition to start state
    }
}

This demo proves that the FSM Context Pattern is an engine-agnostic architectural solution. Once you define the pattern, reusing it for any kind of movement—Rotation, Scale, or Translation (coming next!)—is as simple as defining a new Context class.

See the demo in action:
YouTube Channel Video

Support the Vision and See the Code!

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.

Building a Reusable State Machine for Oscillating Rotation in Unity

Tue, 14 Oct 2025 20:05:21 +0000

Escaping Update() Spaghetti: Reusable Oscillation with FSM & Context in Unity

If you’ve ever built a Unity object that needs to move or rotate between two points—like a swinging pendulum, a turret oscillating for patrol, or a security camera scanning an area—you’ve likely ended up with a tangle of booleans and if/else statements in your Update() loop.

// The typical mess you want to avoid
void Update()
{
    if (isMovingForward)
    {
        // Move Forward Logic
        if (transform.rotation.z > MaxAngle)
        {
            isMovingForward = false;
        }
    }
    else // isMovingBackward
    {
        // Move Backward Logic
        if (transform.rotation.z < MinAngle)
        {
            isMovingForward = true;
        }
    }
}

By leveraging the Finite State Machine (FSM) pattern with a distinct Context object (using the FSM_UnityIntegrationAdvanced package), we can create a single, clean definition for oscillating rotation that can be instantly reused across any number of objects and axes.

The Heart of the Demo: The FSM Context

The core idea is to separate the object's data (where it is, how fast it moves) from the logic (how it behaves). This is done via the RotationContext class, which acts as the data structure for each rotating object.

RotationContext.cs: Data Encapsulation

By implementing IStateContext, this class holds everything the FSM needs to operate on the specific object:

public class RotationContext : IStateContext
{
    // Object and parameters for THIS instance
    public Transform TransformHandle;
    public Vector3 RotationAxis;
    public float RotationSpeed;
    public float MaxAngle;
    public float MinAngle;
    // ... other data
}

The Universal FSM Definition

The beauty of this approach is that the Finite State Machine itself ("RotationFSM") is defined only once inside the RotationContext constructor, making it a reusable blueprint.

State Name	Logic (Update)
RotatingForward	Apply positive rotation to `TransformHandle`
RotatingBackward	Apply negative rotation to `TransformHandle`

Transition (What decides the change)	Condition (Predicate)
`RotatingForward` → `RotatingBackward`	`MaxReached()`: Checks if the current angle ≥ `MaxAngle`
`RotatingBackward` → `RotatingForward`	`MinReached()`: Checks if the current angle ≤ `MinAngle`

The logic in OnUpdateRotatingForward and OnUpdateRotatingBackward simply drives the object, relying entirely on the MaxReached and MinReached predicates to decide when the object's behavior must change.

The Entry Point: Instantiating Reusable Logic

The SimpleRotationDemo.cs is a standard Unity MonoBehaviour whose sole job is to kick off the system in its Awake() or OnEnterExecuting method.

Instead of writing three separate components (one for X, one for Y, one for Z), we instantiate three unique Context objects, each feeding the same shared FSM definition ("RotationFSM") with different parameters.

private void OnEnterExecuting(IStateContext context)
{
    if (context is SimpleRotationDemo srd)
    {
        float speed = 90.0f;
        float maxAngle = 45.0f;
        float minAngle = -45.0f;

        // 1. X-axis Rotation: Unique context, shared FSM logic
        RotationContext xAxisContext = new RotationContext(srd.Xaxis, new Vector3(1, 0, 0), speed, maxAngle, minAngle);
        srd.XaxisHandle = xAxisContext.Status;

        // 2. Y-axis Rotation: Same FSM logic, different object/axis
        RotationContext yAxisContext = new RotationContext(srd.Yaxis, new Vector3(0, 1, 0), speed, maxAngle, minAngle);
        srd.YaxisHandle = yAxisContext.Status;

        // 3. Z-axis Rotation: Same FSM logic, different object/axis
        RotationContext zAxisContext = new RotationContext(srd.Zaxis, new Vector3(0, 0, 1), speed, maxAngle, minAngle);
        srd.ZaxisHandle = zAxisContext.Status;
    }
}

The Result: Scalable Advanced Integration

With minimal setup, we achieve perfectly synchronized, bounded rotation across three distinct objects, all driven by a single, well-defined state machine. This pattern easily extends to more advanced scenarios:

Reusability: The same RotationFSM can be used to drive dozens of turrets, doors, or fans.
Maintainability: If you need to change the rotation logic (e.g., adding easing), you change one piece of code (OnUpdateRotatingForward), not three.
Extensibility: This blueprint instantly adapts to your Translation, Scale, or NavMeshAgentsDemo logic—simply define a new FSM and Context for those specific concerns.

This demo proves that advanced FSM integration doesn't mean complex setup, but rather intelligent architectural separation to keep your Unity code clean and highly reusable.

Coder Legion - Recent posts tagged thesingularityworkshop

The Weekend After: HeadlessAi Has Entered the Workshop

It’s the Weekend. The Workshop Has Toys. Come Play.

Where to Start: NuGet

The Toy Box

FSM_API

FSM_COS

MicroBundleDomain

MicroBundleRepository

GUI

FSM_Serialization

FSM_REST

ProtocolAI & GrammarAI

The Hosts

AnyApp

WebPage

You Don't Need to Understand All of This

The Workshop Is Open

ProtocolAI and GrammarAI: Giving AI a Language Software Can Actually Own

The Problem Starts With Probability

ProtocolAI: The WHAT

The Literal Escape Hatch

This Is Not Just About Compression

And Then I Ran Into the Next Problem

GrammarAI: The HOW

A Grammar Is a Relationship System

Why Integer-Backed Structure?

The AI Still Isn't the Authority

This Is the Same Boundary I Keep Finding Elsewhere

ProtocolAI and GrammarAI Are Deliberately Not an AI Framework

The Exchange Layer Comes Later

Context Is Not Authority

And This Is Where the Larger Workshop Architecture Appears

The Interesting Part Is the Separation

Where the Alpha Actually Stands

The Bigger Experiment

The Current Workshop Stack

That is where I want the architecture to live.

Resources

Support The Singularity Workshop

I Built a Serializer That Refuses to Own Your Data

I Built a Serializer That Refuses to Own Your Data

The Problem Wasn't Turning Objects Into Bytes

The First Design Decision

Why I Didn't Just Use System.IO.Stream

The Two Directions Matter

The Smallest Possible Example

Now Let's Actually Serialize Something

Installation

What About Real Files?

The Stream Adapter Is Supposed to Be Boring

Then I Ran Into a Very Important Detail

Serialization Is Not Storage

Serialization

Storage

Transport

Why Binary?

Deterministic Does Not Mean Magical

Versioning Gets Interesting

The Package Came From a Real Application

And This Is Where FSM_COS Enters the Story

The Tests Tell the Same Story

I Also Benchmarked It

The Benchmark Question I Actually Care About

What I Deliberately Did Not Build

So What Would You Actually Use It For?

A Serializer Shouldn't Become Your Architecture

The Boundary I Want to Preserve

Why I Think Small Infrastructure Is Worth Talking About

You Don't Have to Take My Word for It

Resources & Code:

NuGet Packages:

GitHub Repositories:

Benchmarking the FSM: Pure Strings, Already Fast — and About to Get Faster

Benchmarking the FSM: Pure Strings, Already Fast — and About to Get Faster

The Baseline

Fifty Groups. Fifteen Microseconds.

Why Fifty?

What This Benchmark Does — and Doesn't — Prove

But There's Something Important Hiding in That Table

Why I Didn't Just Use `System.IO.Stream`