# inspiaaa/unityhfsm architecture

> Architecture diagram of the GitHub repository inspiaaa/unityhfsm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/inspiaaa/unityhfsm
- Repository: https://github.com/inspiaaa/unityhfsm

## Overview

##### Main components
- Core State Machine Engine – Represented in the src/StateMachine folder. This is the heart of the library that manages state transitions, activation, exit requests, and global versus local transitions. It also extends the base state class so that nested state machines can be used as states.
- Base Interfaces and Abstract Classes – Located in src/Base. They define essential interfaces such as IActionable, IStateMachine, ITriggerable, IStateTimingManager, and provide abstract classes like StateBase and TransitionBase that other components inherit from.
- State Implementations – Found under src/States. This includes built-in implementations such as ActionState, CoState (for coroutine support), DecoratedState, and ParallelStates – which show that the framework supports both standard and advanced (coroutine-based) states.
- Transition Implementations – In src/Transitions. Here you have classes like Transition, ReverseTransition, TransitionAfter, TransitionOnKey, and TransitionOnMouse, which encapsulate the rules for moving from one state to another (both through polling and event-based mechanisms).
- Exception Handling – In src/Exceptions. These classes (e.g., StateMachineException and related helpers) propagate detailed error information to assist developers debugging state configuration errors.
- Inspection and Debugging – In src/Inspection. Interfaces and utility classes (like IStateMachineHierarchyVisitor, StateMachinePath, StateMachineWalker) support diagnosing hierarchical state machine paths, essential for debugging.
- Utilities – Under src/Util. These provide necessary timing functionality (ITimer, Timer) that support “exit time” handling and delayed transitions.
- Visualization – In src/Visualization. This part facilitates integration with Unity’s Animator Graph (e.g., HfsmAnimatorGraph) to visually represent the state machine for runtime debugging.
- Documentation and Sample Projects – The Samples and docs directories include example scenes (like EnemyAI scenarios) and flowcharts that explain the intended use of the HFSM framework.

##### Relationships and interactions
- The Core State Machine Engine is central and directly interacts with State and Transition components. It processes OnEnter, OnLogic, and OnExit calls and handles the main control flow.
- States (both simple and hierarchical) maintain custom logic via lambda expressions or dedicated classes. They can themselves be state machines, showing a nested relationship.
- Transitions (both polling-based and trigger/event-based) evaluate conditions and, when met (potentially with support from exit conditions), signal the state machine to change states.
- Exception handlers intercept and format errors during state transitions.
- Debug and inspection components can traverse or extract current hierarchical paths for logging and visualization.
- Utility classes (like Timer) are used by states and transitions to implement delayed or controlled state changes.

##### Architectural Patterns and Design Principles
- The design follows an object oriented pattern with a clear separation of concerns. There are distinct modules for state management, transition logic, debugging, visualization, and exception handling.
- Hierarchical composition is a core principle – state machines can be nested, and “ghost states” allow for immediate multi-transition flows.
- Generics are used to provide type safety (avoiding the pitfalls of using plain strings) and to improve performance.
- It combines both polling-based and event-based transition models.
- The framework is made extensible by allowing custom state and transition classes to be derived from common base classes and interfaces.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Base Interfaces & Abstract Classes
    subgraph "Base Interfaces & Abstract Classes"
        B1["IActionable"]:::base
        B2["IStateMachine"]:::base
        B3["IStateTimingManager"]:::base
        B4["ITriggerable"]:::base
        B5["StateBase"]:::base
        B6["TransitionBase"]:::base
    end

    %% Core State Machine Engine
    subgraph "Core State Machine Engine"
        C1["HybridStateMachine"]:::engine
        C2["StateMachine"]:::engine
        C3["StateMachineShortcuts"]:::engine
    end

    %% State Implementations
    subgraph "State Implementations"
        S1["ActionState"]:::states
        S2["CoState"]:::states
        S3["DecoratedState"]:::states
        S4["ParallelStates"]:::states
        S5["State"]:::states
        S6["StateDecorator"]:::states
    end

    %% Transition Implementations
    subgraph "Transition Implementations"
        T1["Transition"]:::transitions
        T2["ReverseTransition"]:::transitions
        T3["TransitionAfter"]:::transitions
        T4["TransitionAfterDynamic"]:::transitions
        T5["TransitionOnKey"]:::transitions
        T6["TransitionOnMouse"]:::transitions
        T7["DecoratedTransition"]:::transitions
        T8["TransitionDecorator"]:::transitions
    end

    %% Utilities
    subgraph "Utilities"
        U1["ITimer"]:::utilities
        U2["Timer"]:::utilities
    end

    %% Inspection and Debugging
    subgraph "Inspection and Debugging"
        I1["IStateMachineHierarchyVisitor"]:::inspection
        I2["IStateVisitor"]:::inspection
        I3["IVisitableState"]:::inspection
        I4["StateMachinePath"]:::inspection
        I5["StateMachineWalker"]:::inspection
    end

    %% Exception Handling
    subgraph "Exception Handling"
        E1["StateMachineException"]:::exceptions
        E2["Common"]:::exceptions
        E3["ExceptionFormatter"]:::exceptions
    end

    %% Visualization
    subgraph "Visualization"
        V1["HfsmAnimatorGraph"]:::visualization
        V2["VisualizationNamespace"]:::visualization
    end

    %% Documentation and Sample Projects
    subgraph "Documentation and Sample Projects"
        D1["GuardAI Sample Project"]:::documentation
    end

    %% Relationships
    C2 -->|"uses"| B2
    C2 -->|"manages"| S1
    C2 -->|"triggers"| T1
    S1 -->|"delayedCall"| U2
    T1 -->|"delayedCall"| U2
    C2 -->|"logs"| I4
    C2 -->|"handlesError"| E1
    C2 -->|"visualizes"| V1
    D1 -->|"demonstrates"| C2

    %% Styling
    classDef base fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef engine fill:#ffcc80,stroke:#e65100,stroke-width:2px;
    classDef states fill:#c5e1a5,stroke:#33691e,stroke-width:2px;
    classDef transitions fill:#b3e5fc,stroke:#01579b,stroke-width:2px;
    classDef utilities fill:#d1c4e9,stroke:#4a148c,stroke-width:2px;
    classDef inspection fill:#ffe082,stroke:#ff8f00,stroke-width:2px;
    classDef exceptions fill:#ffcdd2,stroke:#b71c1c,stroke-width:2px;
    classDef visualization fill:#d7ccc8,stroke:#3e2723,stroke-width:2px;
    classDef documentation fill:#f0f4c3,stroke:#827717,stroke-width:2px;

    %% Click Events for Base Interfaces & Abstract Classes
    click B1 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Base/IActionable.cs"
    click B2 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Base/IStateMachine.cs"
    click B3 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Base/IStateTimingManager.cs"
    click B4 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Base/ITriggerable.cs"
    click B5 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Base/StateBase.cs"
    click B6 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Base/TransitionBase.cs"

    %% Click Events for Core State Machine Engine
    click C1 "https://github.com/inspiaaa/unityhfsm/blob/master/src/StateMachine/HybridStateMachine.cs"
    click C2 "https://github.com/inspiaaa/unityhfsm/blob/master/src/StateMachine/StateMachine.cs"
    click C3 "https://github.com/inspiaaa/unityhfsm/blob/master/src/StateMachine/StateMachineShortcuts.cs"

    %% Click Events for State Implementations
    click S1 "https://github.com/inspiaaa/unityhfsm/blob/master/src/States/ActionState.cs"
    click S2 "https://github.com/inspiaaa/unityhfsm/blob/master/src/States/CoState.cs"
    click S3 "https://github.com/inspiaaa/unityhfsm/blob/master/src/States/DecoratedState.cs"
    click S4 "https://github.com/inspiaaa/unityhfsm/blob/master/src/States/ParallelStates.cs"
    click S5 "https://github.com/inspiaaa/unityhfsm/blob/master/src/States/State.cs"
    click S6 "https://github.com/inspiaaa/unityhfsm/blob/master/src/States/StateDecorator.cs"

    %% Click Events for Transition Implementations
    click T1 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Transitions/Transition.cs"
    click T2 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Transitions/ReverseTransition.cs"
    click T3 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Transitions/TransitionAfter.cs"
    click T4 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Transitions/TransitionAfterDynamic.cs"
    click T5 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Transitions/TransitionOnKey.cs"
    click T6 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Transitions/TransitionOnMouse.cs"
    click T7 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Transitions/DecoratedTransition.cs"
    click T8 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Transitions/TransitionDecorator.cs"

    %% Click Events for Utilities
    click U1 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Util/ITimer.cs"
    click U2 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Util/Timer.cs"

    %% Click Events for Inspection and Debugging
    click I1 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Inspection/IStateMachineHierarchyVisitor.cs"
    click I2 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Inspection/IStateVisitor.cs"
    click I3 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Inspection/IVisitableState.cs"
    click I4 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Inspection/StateMachinePath.cs"
    click I5 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Inspection/StateMachineWalker.cs"

    %% Click Events for Exception Handling
    click E1 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Exceptions/StateMachineException.cs"
    click E2 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Exceptions/Common.cs"
    click E3 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Exceptions/ExceptionFormatter.cs"

    %% Click Events for Visualization
    click V1 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Visualization/HfsmAnimatorGraph.cs"
    click V2 "https://github.com/inspiaaa/unityhfsm/blob/master/src/Visualization/VisualizationNamespace.cs"

    %% Click Events for Documentation and Sample Projects
    click D1 "https://github.com/inspiaaa/unityhfsm/tree/master/Samples~/GuardAI"
```
