Variables

StoryFlow variables are the backbone of dynamic storytelling. They store state that persists throughout your story - tracking player choices, inventory, stats, and any other data your narrative depends on. This guide covers how to interact with them from Unity using C#.

Variable Types

Every variable in a StoryFlow project carries a set of core properties:

• Id - A generated hash identifier (e.g., var_A3F8B21C). Used internally by the runtime.
• Name - The human-readable display name. This is the string you pass to getter/setter methods from C#.
• Type - One of the StoryFlowVariableType enum values.
• Value - The current value, stored as a StoryFlowVariant.
• IsArray - Whether this variable holds a single value or an array of values.
• EnumValues - For Enum-type variables, the list of valid option strings.

StoryFlowVariableType Enum

The plugin defines the following variable types:

StoryFlowVariant

StoryFlowVariant is the type-safe value container used throughout the plugin. It holds one value at a time along with its type tag, so you always know what kind of data you are working with.

Getter methods return a default if the variant holds a different type:

Setter methods update the value and its type tag:

• SetBool(bool value)
• SetInt(int value)
• SetFloat(float value)
• SetString(string value)
• SetEnum(string value)

Factory methods create a variant from a typed value:

// Create variants from typed values
StoryFlowVariant boolVal  = StoryFlowVariant.Bool(true);
StoryFlowVariant intVal   = StoryFlowVariant.Int(42);
StoryFlowVariant floatVal = StoryFlowVariant.Float(3.14f);
StoryFlowVariant strVal   = StoryFlowVariant.String("Hello");
StoryFlowVariant enumVal  = StoryFlowVariant.Enum("Hard");

// Read values back
bool  b = boolVal.GetBool();       // true
int   i = intVal.GetInt();         // 42
float f = floatVal.GetFloat();     // 3.14
string s = strVal.GetString();     // "Hello"

// ToString() for display / logging
string display = intVal.ToString(); // "42"

// Array support
var items = new List<StoryFlowVariant>();
items.Add(StoryFlowVariant.Int(1));
items.Add(StoryFlowVariant.Int(2));
StoryFlowVariant arrayVal = new StoryFlowVariant();
arrayVal.ArrayValue = items;
List<StoryFlowVariant> retrieved = arrayVal.GetArray();

Local vs Global Scope

StoryFlow variables exist in one of two scopes, and the scope determines their lifetime and visibility:

// Reading a local variable (scoped to this component's current script)
bool hasKey = component.GetBoolVariable("hasKey", global: false);

// Reading a global variable (shared across all components)
int playerGold = component.GetIntVariable("playerGold", global: true);

Reading Variables

The StoryFlowComponent exposes typed getter methods for reading variable values:

Each method looks up the variable by its display name in either the local (component) or global (manager) store, then returns the value cast to the appropriate type. If the variable is not found, the type's default value is returned.

StoryFlowComponent sf = GetComponent<StoryFlowComponent>();

// Local variables
bool questComplete = sf.GetBoolVariable("questComplete", global: false);
string playerName  = sf.GetStringVariable("playerName", global: false);

// Global variables
int gold           = sf.GetIntVariable("playerGold", global: true);
float reputation   = sf.GetFloatVariable("reputation", global: true);
string difficulty  = sf.GetEnumVariable("difficulty", global: true);

Setting Variables

The component also exposes typed setter methods:

Setting a variable updates the value in the appropriate scope and fires the OnVariableChanged event (see below). This means your game logic can react immediately to any change, whether triggered by a node in the StoryFlow graph or by your own C# code.

StoryFlowComponent sf = GetComponent<StoryFlowComponent>();

// Set a local boolean (e.g., after player picks up a key)
sf.SetBoolVariable("hasKey", true, global: false);

// Set a global integer (e.g., award gold for completing a quest)
sf.SetIntVariable("playerGold", 500, global: true);

// Set a global enum (e.g., change difficulty at runtime)
sf.SetEnumVariable("difficulty", "Hard", global: true);

OnVariableChanged Event

Every time a variable changes - whether from node execution inside the StoryFlow graph or from a direct C# call - the OnVariableChanged event fires on the component.

Signature:

public event Action<StoryFlowVariable, bool> OnVariableChanged;

Parameters:

• StoryFlowVariable - The full variable object containing Id, Name, Type, Value, and other metadata.
• bool isGlobal - Whether the change occurred in the global scope.

Subscribing in C#:

void Start()
{
    var sf = GetComponent<StoryFlowComponent>();
    sf.OnVariableChanged += HandleVariableChanged;
}

void OnDestroy()
{
    var sf = GetComponent<StoryFlowComponent>();
    if (sf != null)
        sf.OnVariableChanged -= HandleVariableChanged;
}

void HandleVariableChanged(StoryFlowVariable variable, bool isGlobal)
{
    if (variable.Name == "playerGold")
    {
        int newGold = variable.Value.GetInt();
        UpdateGoldUI(newGold);
    }

    // You can also check by type or internal Id:
    // variable.Id    - internal hash identifier
    // variable.Type  - StoryFlowVariableType enum
}

Variable Interpolation in Dialogue

Dialogue text in StoryFlow can reference variables using the {varname} syntax. When the runtime builds the dialogue state, it automatically replaces these tokens with the current variable values.

// In the StoryFlow Editor dialogue node text:
"You have {playerGold} gold coins, {playerName}."

// At runtime, if playerGold = 500 and playerName = "Alice":
"You have 500 gold coins, Alice."

Interpolation is resolved automatically when the OnDialogueUpdated event fires. You do not need to perform any manual string replacement - the text in the dialogue state is already fully resolved.

Arrays

Variables can be arrays (IsArray = true). An array variable holds an ordered list of StoryFlowVariant values, all of the same type. Arrays are supported for all variable types: Bool, Int, Float, String, Image, Character, and Audio.

Array Operations

The StoryFlow node graph provides a full set of array manipulation nodes. These operations execute as part of the story flow and update the variable automatically:

The forEach loop node iterates over all elements in an array, executing the connected subgraph once per element. This is useful for processing inventories, applying effects to party members, or evaluating a list of quest objectives.

Resetting Variables

The plugin provides methods to reset variables back to their initial values as defined in the StoryFlow project. This is useful for restarting a story, resetting a scene, or clearing state for a new game.

// Reset just this component's local variables
component.ResetVariables();

// Reset global variables across all components
StoryFlowManager.Instance.ResetGlobalVariables();

// Full state reset (globals + characters + once-only options)
StoryFlowManager.Instance.ResetAllState();