Learn how FSM_API uses decoupled state machines to run a "Fox and Dog" AI simulation.

Thu, 09 Oct 2025 22:17:48 +0000

Implementing Behavior Trees with FSM_API: The Quick Brown Fox and Lazy Sleeping Dog Demo

Finite State Machines (FSMs) are a foundational pattern for organizing complex logic in software, from game AI to business workflows. The FSM_API library provides a high-performance, engine-agnostic C# solution for building and managing these systems with clarity and efficiency.

This article dives into the Quick Brown Fox and Lazy Sleeping Dog demo, an excellent, practical example found in the FSM_API public repository. It showcases how to implement simple, interacting AI agents, effectively decoupling agent data from agent behavior logic using the library's core features.

FSM_API Core Concepts in the Demo

Every behavioral entity in this simulation—the Fox and the Dog—relies on three core FSM_API concepts:

The State Context (IStateContext): This is your actual game object (the Fox or the Dog), holding the data (e.g., Position, Speed, CollidedAgents) and implementing the transition methods. It must implement the IStateContext interface, which requires providing a Name and an IsValid property.
The FSM Definition: This is the reusable blueprint of states (e.g., "Sleeping", "Walking") and the rules for transitioning between them.
The FSM Instance: This is the live, active version of the blueprint, associated with a specific agent context. Both agents' FSMs are set up to run in the "Update" processing group.

The Lazy Sleeping Dog's Behavior

The LazySleepingDog class is initialized at Position = 3 and starts in the "Sleeping" state. Its FSM defines a classic threat response lifecycle:

State	OnUpdate Action	Transition Condition (to)	Transition Target
Sleeping	Console log: "...is sleeping!"	`IsAwake(context)`: `CollidedAgents.Any()`	Awake
Awake	Console log: "...is awake!"	`ShouldChase(context)`: `VisibleAgents.Any(s => s is QuickBrownFox)`	Chasing
Chasing	`Position` increases by `Speed` (set to 3 on enter)	`IsMangling(context)`: `CollidedAgents.Any(s => s is QuickBrownFox)`	Mangling
Mangling	Console log: "...is Mangling the fox!"	N/A	N/A

Crucially, in the "Mangling" state's OnEnterMangling handler, the dog directly uses the FSM_API to transition the collided agent's state (the Fox) to "Mangled":

// Inside OnEnterMangling for the dog
dog.CollidedAgents.FirstOrDefault()?.State.TransitionTo("Mangled");

The Quick Brown Fox's Behavior

The QuickBrownFox starts at Position = 0 and its FSM defines its attempts to flee the dog and reach a winning position:

State	OnUpdate Action	Transition Condition (to)	Transition Target
Walking	`Position` increases by `Speed` (1)	`ShouldJump(context)`: `VisibleAgents` within 2 units	Jumping
Jumping	`Position` increases by `Speed` (1)	`ShouldLand(context)`: `Position` reaches `JumpEnd` (initial position + 2)	Walking
Fleeing	`Position` increases by `Speed` (set to 2 on enter)	N/A	N/A
Mangled	Console log: "...is being mangled!"	N/A	N/A

The Fox's ultimate defensive move is the transition to "Fleeing", which is triggered by a direct collision with a LazySleepingDog. However, if the Dog catches it while fleeing, the Dog forces the Fox into the terminal "Mangled" state.

The Simulation Loop (`SimpleDemoContext`)

The SimpleDemoContext acts as the game manager, controlling the flow of the entire application. It sets up the following structure:

Processing Groups: It creates a "Main" group for the application's FSM (AppFSM) and an "Update" group where the agents' FSMs run.
Tick Logic: The core simulation runs in OnUpdateExecuting:
- It clears previous frame's agent data.
- It performs Vision and Collision checks based on the agents' current Position and Sight range, populating the VisibleAgents and CollidedAgents lists.
- It calls FSM_API.Interaction.Update("Update"). This single call iterates through and updates all FSM instances assigned to the "Update" group (the Fox and the Dog), triggering their onUpdate actions and checking their transition conditions.
Shutdown: The application's AppFSM transitions to "Shutdown" if a key is pressed, if the Fox reaches the WinPosition (10), or if any agent's state is "Mangled". The FSM_API then manages the cleanup.

The Program.cs file initiates the simulation and loops the main update call until the application context becomes invalid. This structure demonstrates how FSM_API cleanly separates an agent's Data (IStateContext properties) from its Behavioral Logic (the FSM Definition) and relies on a central Simulation Tick (FSM_API.Interaction.Update()) to drive complex, interactive AI.

Stay Tuned for the Advanced Demo

This simple, 1D simulation laid the groundwork, but the next step is building a true environment!

Stay tuned for a follow-up article where we'll use these exact same agent FSMs to create an advanced 2D environment with multiple dogs and foxes interacting simultaneously. This will highlight the true power of decoupled FSM definitions.

Follow us to stay informed! And for much more content, advanced articles, and discussions about our vision for the software for the singularity, check out our:

Patreon Page

Get the Code

You can explore the full implementation of this FSM-driven AI simulation and the FSM_API library structure by cloning the public repository:

https://github.com/TrentBest/SimpleDemos

Coder Legion - Recent posts tagged c#-ai