Accessing Variables

Export

Access a Shared Variable when an Action or another component needs to read or update a value used by the state machine. Assigning the same variable to multiple Action fields lets them work with one value, while the StateMachine API lets your own scripts initialize or inspect that value.

Assign a Shared Variable to an Action

  1. Create a Shared Variable in the Shared Variables pane. For this example, create a GameObject variable named Target.
  2. Add a SharedVariable<GameObject> field to the custom Action.
  3. Select the Action in the graph and assign Target to that field in the Inspector.
  4. Read or update the assigned variable through its Value property.

This Action excerpt reads the current target and assigns the Player GameObject when the value is empty:

using Opsive.GraphDesigner.Runtime.Variables;
using Opsive.StateDesigner.Runtime.Actions;
using Opsive.StateDesigner.Runtime.States;
using UnityEngine;

public class FindTarget : Action
{
    [Tooltip("The object that the agent is searching for.")]
    [SerializeField] protected SharedVariable<GameObject> m_Target;

    public override StateStatus OnUpdate()
    {
        GameObject targetGameObject = m_Target.Value;
        if (targetGameObject == null) {
            m_Target.Value = GameObject.Find("Player");
        }

Assign Target to each compatible field that should share this value. Those fields then refer to the same Shared Variable instead of keeping separate GameObject values.

Access a Graph variable from a component

Get a reference to the StateMachine component, look up the variable by its name and type, and use the returned SharedVariable.Value property:

using Opsive.GraphDesigner.Runtime.Variables;
using Opsive.StateDesigner.Runtime;
using UnityEngine;

public class AccessVariable : MonoBehaviour
{
    public StateMachine m_StateMachine;

    public void Start()
    {
        SharedVariable<GameObject> target = m_StateMachine.GetVariable<GameObject>("Target");
        target.Value = gameObject;
    }
}

This example gets the Graph-scope GameObject variable named Target and assigns the component’s GameObject to it.

Access a variable in another scope

GetVariable uses Graph scope when no scope is supplied. Add the SharingScope parameter when the variable belongs to another scope:

SharedVariable target = m_StateMachine.GetVariable("Target", SharedVariable.SharingScope.Scene);

You can also access the component or asset that owns a GameObject-, Scene-, or Project-scope variable and call its typed GetVariable method directly:

using Opsive.GraphDesigner.Runtime.Variables;
using Opsive.GraphDesigner.Runtime;
using UnityEngine;

public class AccessVariable : MonoBehaviour
{
    public StateMachine m_StateMachine;
    public GameObjectSharedVariables m_GameObjectSharedVariables;
    public SceneSharedVariables m_SceneSharedVariables;

    public void Start()
    {
        var target = m_StateMachine.GetVariable<GameObject>("Target"); // Graph Scope.
        target = m_GameObjectSharedVariables.GetVariable<GameObject>("Target"); // GameObject Scope.
        target = m_SceneSharedVariables.GetVariable<GameObject>("Target"); // Scene Scope.
        target = ProjectSharedVariables.Instance.GetVariable<GameObject>("Target"); // Project Scope.
    }
}

How it runs

An Action field assigned in the Inspector holds a reference to the selected Shared Variable. Reading or writing Value therefore reads or updates the value used by every other compatible field assigned to that same variable.

At runtime, StateMachine.GetVariable<T>("Target") searches Graph scope. The overload with SharedVariable.SharingScope searches the requested scope instead. A lookup returns null when the name, type, and scope do not identify a matching variable, so confirm the result before using Value in code that may run with different graph setups.

Important choices

  • Match the variable name used in code with the name shown in the Shared Variables pane.
  • Use the same value type in the Shared Variable, Action field, and generic GetVariable<T> call.
  • Keep a value in Graph scope when only one graph needs it. Choose GameObject, Scene, or Project scope only when that wider set of state machines must share it.
  • Use the scoped StateMachine.GetVariable overload when the state machine should select the scope. Use a GameObjectSharedVariables, SceneSharedVariables, or ProjectSharedVariables reference when your script already has the owning container.

Verify in Play Mode

Enter Play Mode with Target visible in the Shared Variables pane. Run the Action or component that assigns the Player or current GameObject, then confirm that Target changes to that object. Select another state that uses the same variable and confirm that its assigned field shows the same runtime value.

If the value does not change, verify the variable name, value type, selected scope, and Inspector assignment. A code lookup that does not match those details returns null.

  • Variables introduces Shared Variables and their supporting workflows.
  • Blackboard shows how to create and assign Shared Variables in the editor.
  • Scope explains Graph, GameObject, Scene, Project, and Dynamic variables.
  • Property Binding connects a Shared Variable to a component property.
  • Creating a GameObject Action shows Shared Variable fields in a custom Action.