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 Unreal Engine.

Variable Types

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

• Id — A generated hash identifier (e.g., var_A3F8B21C). This is the string you pass to getter/setter functions.
• Name — The human-readable display name (resolved via string table).
• Type — One of the EStoryFlowVariableType enum values.
• Value — The current value, stored as an FStoryFlowVariant.
• bIsArray — Whether this variable holds a single value or an array of values.
• EnumValues — For Enum-type variables, the list of valid option strings.

EStoryFlowVariableType Enum

The plugin defines the following variable types:

FStoryFlowVariant

FStoryFlowVariant 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:

Factory methods create a variant from a typed value:

// Create variants from typed values
FStoryFlowVariant BoolVal = FStoryFlowVariant::FromBool(true);
FStoryFlowVariant IntVal = FStoryFlowVariant::FromInt(42);
FStoryFlowVariant FloatVal = FStoryFlowVariant::FromFloat(3.14f);
FStoryFlowVariant StringVal = FStoryFlowVariant::FromString(TEXT("Hello"));

// Read values back
bool bValue = BoolVal.GetBool();     // true
int32 iValue = IntVal.GetInt();       // 42
float fValue = FloatVal.GetFloat();   // 3.14
FString sValue = StringVal.GetString(); // "Hello"

// ToString() for display / logging
FString Display = IntVal.ToString();  // "42"

// Array support
TArray<FStoryFlowVariant> Items;
Items.Add(FStoryFlowVariant::FromInt(1));
Items.Add(FStoryFlowVariant::FromInt(2));
FStoryFlowVariant ArrayVal;
ArrayVal.SetArray(Items);
TArray<FStoryFlowVariant> 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 bHasKey = StoryFlowComponent->GetBoolVariable("var_A3F8B21C", false);

// Reading a global variable (shared across all components)
int32 PlayerGold = StoryFlowComponent->GetIntVariable("var_7D2E9F01", true);

Reading Variables

The UStoryFlowComponent exposes typed getter functions for reading variable values. All functions are available in both Blueprint and C++ under the category StoryFlow|Variables.

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

// C++ examples
UStoryFlowComponent* SF = GetOwner()->FindComponentByClass<UStoryFlowComponent>();

// Local variables
bool bQuestComplete = SF->GetBoolVariable("var_A3F8B21C", false);
FString PlayerName = SF->GetStringVariable("var_B7C1D4E2", false);

// Global variables
int32 Gold = SF->GetIntVariable("var_7D2E9F01", true);
float Reputation = SF->GetFloatVariable("var_9E5F3A08", true);
FString Difficulty = SF->GetEnumVariable("var_C4D6E812", true);

Setting Variables

The component also exposes typed setter functions. Like the getters, these are available under the StoryFlow|Variables category in Blueprints.

Setting a variable updates the value in the appropriate scope and fires the OnVariableChanged delegate (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 Blueprint/C++ code.

// C++ examples
UStoryFlowComponent* SF = GetOwner()->FindComponentByClass<UStoryFlowComponent>();

// Set a local boolean (e.g., after player picks up a key)
SF->SetBoolVariable("var_A3F8B21C", true, false);

// Set a global integer (e.g., award gold for completing a quest)
SF->SetIntVariable("var_7D2E9F01", 500, true);

// Set a global enum (e.g., change difficulty at runtime)
SF->SetEnumVariable("var_C4D6E812", TEXT("Hard"), true);

OnVariableChanged Delegate

Every time a variable changes — whether from node execution inside the StoryFlow graph or from a direct Blueprint/C++ call — the OnVariableChanged delegate fires.

Signature:

DECLARE_DYNAMIC_MULTICAST_DELEGATE_ThreeParams(
    FOnVariableChanged,
    FString, VariableId,
    FStoryFlowVariant, NewValue,
    bool, bIsGlobal
);

Parameters:

• VariableId — The Id of the variable that changed.
• NewValue — The new value as an FStoryFlowVariant. Use the typed getters (GetBool(), GetInt(), etc.) to extract the value.
• bIsGlobal — Whether the change occurred in the global scope.

Binding in C++:

// In your actor's BeginPlay
UStoryFlowComponent* SF = FindComponentByClass<UStoryFlowComponent>();
SF->OnVariableChanged.AddDynamic(this, &AMyActor::HandleVariableChanged);

// Handler
void AMyActor::HandleVariableChanged(FString VariableId, FStoryFlowVariant NewValue, bool bIsGlobal)
{
    if (VariableId == "var_7D2E9F01") // playerGold
    {
        int32 NewGold = NewValue.GetInt();
        UpdateGoldUI(NewGold);
    }
}

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 delegate 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 (bIsArray = true). An array variable holds an ordered list of FStoryFlowVariant 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 functions 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
StoryFlowComponent->ResetVariables();

// Reset global variables across all components
UStoryFlowSubsystem* Subsystem = GetGameInstance()->GetSubsystem<UStoryFlowSubsystem>();
Subsystem->ResetGlobalVariables();

// Full state reset (globals + characters + once-only options)
Subsystem->ResetAllState();