UnityHFSM Documentation

UnityHFSM supports generics to allow using types other than string for state identifiers (TStateId) and events (TEvent). Using enum or int instead of string can improve type safety (preventing typos) and improve performance by up to 50% in internal mechanics.

When building a hierarchy, every nested state machine can use its own TStateId type. However, all state machines in a given hierarchy must share the same TEvent type so that triggers can be passed down the hierarchy.

enum PlayerStates {
    IDLE, MOVE, JUMP
}

enum MoveStates {
    WALK, DASH
}

enum Events {
    ON_DAMAGE, ON_WIN
}

// Root FSM: Uses PlayerStates for its own ID, Events for triggers
var fsm = new StateMachine<PlayerStates, Events>();

// Nested FSM: Uses PlayerStates as its parent ID, MoveStates for its own ID, and Events for triggers
var moveFsm = new StateMachine<PlayerStates, MoveStates, Events>();

// Adding states and transitions
fsm.AddState(PlayerStates.IDLE, new State<PlayerStates, Events>());
fsm.AddState(PlayerStates.MOVE, moveFsm);

moveFsm.AddState(MoveStates.WALK);
moveFsm.AddState(MoveStates.DASH);
moveFsm.AddTransition(MoveStates.WALK, MoveStates.DASH);

UnityHFSM provides three primary ways to manage state transitions, allowing you to mix polling-based, event-based, and direct logic approaches:

1. Transition Objects (Polling): Define Transition objects that are checked automatically during every OnLogic call. This is useful for continuous condition checking.
2. Direct State Change Requests: States can manually trigger a transition by calling RequestStateChange. This bypasses the need for a formal Transition object.
3. Trigger Transitions (Event-based): These are transitions that only evaluate when a specific trigger name is activated via fsm.Trigger(triggerName). This is more efficient than polling for discrete events.

Additionally, you can define Global Transitions (using AddTransitionFromAny or AddTriggerTransitionFromAny) which have the highest priority and can be triggered from any state in the machine.

The needsExitTime property determines how strictly a state must finish its logic before a transition can occur.

• needsExitTime = false (Default): The state can exit immediately when a transition condition is met, regardless of its internal progress.
• needsExitTime = true: The state machine will not exit the state immediately. Instead, the transition becomes "pending." The state machine waits until the active state explicitly signals it is ready to exit.

To signal that a state with needsExitTime = true is ready to exit, call fsm.StateCanExit() within the state's logic or use the declarative canExit property.

// Option 1: Manual exit signaling in onLogic
extractIntel.AddState("SendData",
    onLogic: state => {
        if (state.timer.Elapsed > 5)
            state.fsm.StateCanExit();
    },
    needsExitTime: true
);

// Option 2: Declarative canExit property
extractIntel.AddState("SendData",
    onLogic: state => RotateAtSpeed(100f),
    canExit: state => state.timer.Elapsed > 5,
    needsExitTime: true
);

The OnLogic method of a StateMachine follows a strict execution order to ensure predictable behavior and prevent infinite loops. Only one transition can occur per OnLogic call (unless using Ghost States).

Execution Order:

1. Global Transitions: The FSM checks all transitions defined with AddTransitionFromAny. If one triggers, the FSM moves to the new state and immediately calls that new state's OnLogic.
2. Direct Transitions: If no global transition triggers, the FSM checks transitions specific to the current active state. If one triggers, it moves to the new state and calls its OnLogic.
3. Active State Logic: If no transitions trigger, the FSM executes the OnLogic function of the currently active state.

Priority Rule: Global transitions always have the highest priority. This is ideal for critical states like Dead that should be reachable regardless of the current state.

Ghost States: To perform multiple transitions in a single OnLogic call, mark a state as a "ghost state" using isGhostState: true. When the FSM enters a ghost state, it immediately evaluates its outbound transitions. If one succeeds, it transitions again instantly, effectively

A basic state machine in UnityHFSM involves creating a StateMachine instance, adding states (using either the State class or shortcut methods), adding transitions, initializing, and then calling OnLogic() in your update loop.

Core Workflow

1. Instantiate: fsm = new StateMachine();
2. Add States: Use fsm.AddState(id, state) or shortcuts like fsm.AddState(id, onLogic: ...).
3. Add Transitions: Use fsm.AddTransition(from, to, condition) or fsm.AddTwoWayTransition(id1, id2, condition).
4. Initialize: fsm.SetStartState(id); followed by fsm.Init();.
5. Update: Call fsm.OnLogic(); inside a Unity Update() method.

using UnityEngine;
using UnityHFSM;

public class EnemyController : MonoBehaviour
{
    private StateMachine fsm;

    void Start()
    {
        fsm = new StateMachine();

        // Adding states using shortcuts
        fsm.AddState("ExtractIntel");
        fsm.AddState("FollowPlayer", onLogic: state => MoveTowardsPlayer(1));
        fsm.AddState("FleeFromPlayer", onLogic: state => MoveTowardsPlayer(-1));

        fsm.SetStartState("FollowPlayer");

        // Adding two-way transitions using shortcuts
        fsm.AddTwoWayTransition("ExtractIntel", "FollowPlayer",
            transition => DistanceToPlayer > ownScanningRange);
        fsm.AddTwoWayTransition("ExtractIntel", "FleeFromPlayer",
            transition => DistanceToPlayer < playerScanningRange);

        fsm.Init();
    }

    void Update()
    {
        fsm.OnLogic();
    }
}