# thefuntastic/unity3d-finite-state-machine architecture

> Architecture diagram of the GitHub repository thefuntastic/unity3d-finite-state-machine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thefuntastic/unity3d-finite-state-machine
- Repository: https://github.com/thefuntastic/unity3d-finite-state-machine

## Overview

##### Main Components
- Core StateMachine Library:
- This is the heart of the package. Include modules for:
- StateMachine (the core FSM controller)
- StateDriverRunner and StateDriverUnity (which help manage method invocations)
- StateMapping and StateEvent, including Data-Driven State Events.
- Unity Integration:
- MonoBehaviour-based usage and how the state logic integrates into Unity’s event lifecycle (i.e., Update, FixedUpdate, and coroutine-based Enter/Exit methods).
- Custom Driver/Subscribers Layer:
- This is clearly delineated by the “Driver” concept in the README, where state events (like OnCollisionEnter, OnHealthPickup, etc.) are wrapped in a driver class.
- Testing and Samples:
- The samples directory shows practical use cases (prefabs, scripts such as ExampleAdvanced.cs and ExampleBasic.cs).
- The Tests folder contains both Editor and Runtime tests validating basic transitions, custom drivers, and additional event handling.
- Support Components:
- Assets (like MonsterLove meta files) and ProjectSettings indicate the Unity-specific configuration necessary for the library.

##### Relationships and Data Flow
- The game’s main MonoBehaviour, launching the state machine.
- The StateMachine Controller invoking state methods (e.g., Play_Enter, Play_Update, etc.) based on state transitions.
- The Driver’s role in representing additional events and how they are invoked from Unity event functions (Update, OnCollisionEnter) to drive the state transitions.
- How asynchronous transitions operate (Safe vs. Overwrite) and how the ‘Finally’ method is conceptually used for safe cleanup.

##### Architectural Patterns and Design Principles
- Convention over Configuration:
- How the naming convention (StateName_Method) ties state definitions to specific methods.
- Encapsulation:
- The library encapsulates state transitions, event invocation, and coroutine handling, minimizing side effects in external code.
- Layered Architecture:
- Different layers can be visually separated: the FSM core, Unity integration layer, and test/examples usage.

##### Technologies / Libraries
- Unity 2019.4 (or later) as the overall runtime environment.
- C#, utilising reflection (only at initialization) to reduce boilerplate.
- Use of coroutines (IEnumerator) for asynchronous state transition handling.
- Testing frameworks (likely Unity Test Runner) for both Editor and Runtime tests.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Unity Integration Layer
    subgraph "Unity Integration"
        U1["MonoBehaviour Lifecycle"]:::unity
        U2["StateDriverUnity"]:::unity
    end

    %% Core FSM Layer
    subgraph "Core StateMachine Library"
        FSM["StateMachine"]:::core
        Runner["StateMachineRunner"]:::core
        Mapping["StateMapping"]:::core
        Event["StateEvent"]:::core
    end

    %% Custom Driver/Subscribers Layer
    subgraph "Custom Drivers"
        Driver["StateDriverRunner"]:::driver
    end

    %% Testing & Samples Layer
    subgraph "Testing & Samples"
        Test["Tests"]:::testing
        Sample["Samples"]:::testing
    end

    %% Support Components Layer
    subgraph "Support Components"
        Config1["Unity Meta Configuration"]:::support
        Config2["ProjectSettings"]:::support
    end

    %% Connections between layers
    U1 -->|"ChangeState()"| FSM
    FSM -->|"Executes"| Runner
    Runner -->|"Maps State-to-Method"| Mapping
    Mapping -->|"Triggers"| Event
    Runner -->|"Invokes custom events"| Driver
    U2 -->|"Integrates with"| Driver
    Driver -->|"Feedback for asynchronous transitions"| FSM
    U1 -->|"Drives Unity events"| U2
    Test -->|"Validates transitions"| FSM
    Sample -->|"Demonstrates usage"| FSM
    Config1 -->|"Provides configuration"| FSM
    Config2 -->|"Enables runtime settings"| FSM

    %% Click Events
    click FSM "https://github.com/thefuntastic/unity3d-finite-state-machine/blob/master/StateMachine/Assets/MonsterLove/Runtime/StateMachine.cs"
    click Runner "https://github.com/thefuntastic/unity3d-finite-state-machine/blob/master/StateMachine/Assets/MonsterLove/Runtime/StateMachineRunner.cs"
    click Mapping "https://github.com/thefuntastic/unity3d-finite-state-machine/blob/master/StateMachine/Assets/MonsterLove/Runtime/StateMapping.cs"
    click Event "https://github.com/thefuntastic/unity3d-finite-state-machine/blob/master/StateMachine/Assets/MonsterLove/Runtime/Events/StateEvent.cs"
    click U2 "https://github.com/thefuntastic/unity3d-finite-state-machine/blob/master/StateMachine/Assets/MonsterLove/Runtime/Drivers/StateDriverUnity.cs"
    click Driver "https://github.com/thefuntastic/unity3d-finite-state-machine/blob/master/StateMachine/Assets/MonsterLove/Runtime/Drivers/StateDriverRunner.cs"
    click Test "https://github.com/thefuntastic/unity3d-finite-state-machine/tree/master/StateMachine/Assets/MonsterLove/Tests"
    click Sample "https://github.com/thefuntastic/unity3d-finite-state-machine/tree/master/StateMachine/Assets/MonsterLove/Samples"
    click Config1 "https://github.com/thefuntastic/unity3d-finite-state-machine/blob/master/StateMachine/Assets/MonsterLove.meta"
    click Config2 "https://github.com/thefuntastic/unity3d-finite-state-machine/tree/master/StateMachine/ProjectSettings"

    %% Styles
    classDef unity fill:#FFDDCC,stroke:#333,stroke-width:2px;
    classDef core fill:#CDE8CC,stroke:#333,stroke-width:2px;
    classDef driver fill:#FFEFB0,stroke:#333,stroke-width:2px;
    classDef testing fill:#D1E8FF,stroke:#333,stroke-width:2px;
    classDef support fill:#E2E2E2,stroke:#333,stroke-width:2px;
```
