Coder Legion - Recent posts tagged finitestatemachine

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.

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

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!

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.