API

The StateMachine component is the main interface between State Designer and your graph data. It is responsible for loading/running the graph at runtime, starting event branches, variable access, save/load, and (when used in Entity Subscenes) baking startup data for ECS execution. If the component is baked into a subscene, State Designer uses baked metadata (BakedStateMachine) plus a startup system to start the graph branch at runtime.

API

The StateMachine component exposes the following commonly-used API:

/// <summary>
/// Starts the state machine graph.
/// </summary>
/// <returns>True if the graph was started.</returns>
bool StartGraph()

/// <summary>
/// Returns the logic node of the specified type.
/// </summary>
/// <param name="type">The type of node to retrieve.</param>
/// <returns>The node of the specified type (can be null).</returns>
ILogicNode GetNode(Type type)

/// <summary>
/// Returns the event node of the specified type.
/// </summary>
/// <param name="type">The type of event node to retrieve.</param>
/// <returns>The event node and its index (node can be null).</returns>
(IEventNode, ushort) GetEventNode(Type type)

/// <summary>
/// Ticks the state machine. UpdateMode must be Manual.
/// </summary>
void Tick()

/// <summary>
/// Reevaluates SubgraphReference nodes by calling EvaluateSubgraphs.
/// </summary>
void ReevaluateSubgraphReferences()

/// <summary>
/// Stops or pauses the state machine.
/// </summary>
/// <param name="pause">Should the graph be paused?</param>
/// <returns>True if the graph was stopped or paused.</returns>
bool StopGraph(bool pause = false)

/// <summary>
/// Restarts the state machine.
/// </summary>
/// <returns>True if the graph was restarted.</returns>
bool RestartGraph()

/// <summary>
/// Returns the SharedVariable with the specified name (Graph scope).
/// </summary>
SharedVariable GetVariable(PropertyName name)

/// <summary>
/// Returns the SharedVariable with the specified name and scope.
/// </summary>
SharedVariable GetVariable(PropertyName name, SharedVariable.SharingScope scope)

/// <summary>
/// Returns the typed SharedVariable with the specified name (Graph scope).
/// </summary>
SharedVariable<T> GetVariable<T>(PropertyName name)

/// <summary>
/// Returns the typed SharedVariable with the specified name and scope.
/// </summary>
SharedVariable<T> GetVariable<T>(PropertyName name, SharedVariable.SharingScope scope)

/// <summary>
/// Sets a SharedVariable value (Graph scope).
/// </summary>
bool SetVariableValue<T>(PropertyName name, T value)

/// <summary>
/// Sets a SharedVariable value with explicit scope.
/// </summary>
bool SetVariableValue<T>(PropertyName name, T value, SharedVariable.SharingScope scope)

/// <summary>
/// Saves the state machine to the specified file path.
/// </summary>
/// <param name="filePath">Destination file path.</param>
/// <param name="variableSaveScope">Which variable scopes to save (Graph variables are always saved).</param>
/// <returns>True if save succeeded.</returns>
bool Save(string filePath, SaveManager.VariableSaveScope variableSaveScope = 0)

/// <summary>
/// Loads the state machine from a file path.
/// </summary>
/// <param name="filePath">Source file path.</param>
/// <param name="afterVariablesRestored">Optional callback after variable restore.</param>
/// <returns>True if load succeeded.</returns>
bool Load(string filePath, Action<StateMachine> afterVariablesRestored = null)

/// <summary>
/// Loads the state machine from SaveData.
/// </summary>
/// <param name="saveData">In-memory save data.</param>
/// <param name="afterVariablesRestored">Optional callback after variable restore.</param>
/// <returns>True if load succeeded.</returns>
bool Load(SaveManager.SaveData saveData, Action<StateMachine> afterVariablesRestored = null)

Manual Update Mode

If UpdateMode is set to Manual, the graph will not evaluate automatically each frame. You must tick it yourself:

using Opsive.StateDesigner.Runtime;
using UnityEngine;

public class ManualTickExample : MonoBehaviour
{
    [SerializeField] private StateMachine m_StateMachine;

    private void Start()
    {
        m_StateMachine.StartGraph();
    }

    public void AdvanceTurn()
    {
        m_StateMachine.Tick();
    }
}

This pattern is useful for turn-based or deterministic step-driven simulations.

Events Exposed by StateMachine

Flow lifecycle:

OnStateMachineStarted
OnStateMachineStopped
OnStateMachineDestroyed

Save/load lifecycle:

OnWillSave
OnDidSave
OnWillLoad
OnDidLoad

Execution Status

You can inspect graph execution with the StateMachine.Status property. It returns the runtime status (Inactive, Queued, Running, Finished) for the start branch’s active flow. This is useful for UI/debugging checks, for example “is the graph running right now?”