Variables

Ibralogue has a flexible variable system with two scopes: global variables that persist across all dialogue files, and local variables scoped to a single file.

Variables are resolved at runtime, meaning changes to variable values are reflected immediately in any dialogue that references them, without reparsing.

Reading Variables in Dialogue

Reference any variable with the $ prefix. Variables work anywhere in dialogue -- text, speaker names, invocation arguments, metadata values, choices, and jump targets.

[NPC]
Hi, $PLAYERNAME.
[$PLAYERNAME]
Hi. What's up?

Setting Variables from Code

Register global variables through the VariableStore:

VariableStore.SetGlobal("PLAYERNAME", "Ibrahim");
VariableStore.SetGlobal("HEALTH", 100.0);
VariableStore.SetGlobal("QUEST_DONE", false);

Setting Variables from Dialogue

Use {{Set(...)}} to assign a variable from within a dialogue file:

{{Set($GOLD, 100)}}
{{Set($NAME, "Alice")}}
{{Set($QUEST_DONE, true)}}

The value can be any expression, including references to other variables and arithmetic:

{{Set($HEALTH, $HEALTH - 10)}}
{{Set($TOTAL, $BASE_PRICE * $QUANTITY)}}
{{Set($GREETING, "Hello " + $PLAYERNAME)}}

If the variable already exists in any scope, {{Set(...)}} updates it in place. If it does not exist, a new local variable is created, scoped to the current dialogue file.

Global vs Local Scope

Variables set from C# are always global. Variables created by {{Set(...)}} in a dialogue file are local by default.

To explicitly declare a variable as global from within dialogue, use {{Global(...)}}:

{{Global($PLAYER_SCORE, 0)}}

This creates (or updates) a global variable that persists across all dialogue files. If only a name is provided, the variable is registered without a value:

{{Global($PLAYER_SCORE)}}

Resolution Order

When a variable is referenced, Ibralogue checks scopes in this order:

1. Local (current dialogue file)
2. Global (set via VariableStore.SetGlobal or {{Global(...)}})

The first match wins. This means a local variable can shadow a global variable of the same name.

Variables in Invocation Arguments

Variables are resolved inside invocation arguments:

[NPC]
You received {{GiveItem($REWARD)}}.
The $TARGET takes {{FormatDamage($DMG)}} damage!

Variables in Metadata and Choices

Variables are also resolved in metadata values and choice text:

[NPC]
How do you feel? ## emotion:$MOOD
- Go to $LOCATION -> $LOCATION ## quest:$QUESTID

Managing Variables from Code

The VariableStore API provides full control:

// Set a global variable
VariableStore.SetGlobal("SCORE", 100.0);

// Set a file-local variable
VariableStore.SetLocal("myDialogue", "temp", "hello");

// Read a variable (checks local first, then global)
object value = VariableStore.Resolve("myDialogue", "SCORE");

// Clear local variables for a specific asset
VariableStore.ClearLocals("myDialogue");

// Clear all variables
VariableStore.ClearAll();

Reacting to Variable Changes

The OnVariableChanged event fires whenever a variable is set from any source (code or dialogue). The callback receives the variable name, old value, and new value:

VariableStore.OnVariableChanged += (name, oldValue, newValue) =>
{
    Debug.Log($"{name} changed from {oldValue} to {newValue}");
};

This is useful for reactive UI, quest state tracking, or achievement systems.

Saving and Loading Variable State

The VariableStore supports exporting and importing its entire state for save/load systems:

// Save
VariableSnapshot snapshot = VariableStore.ExportState();
string json = JsonUtility.ToJson(snapshot);

// Load
VariableSnapshot loaded = JsonUtility.FromJson<VariableSnapshot>(json);
VariableStore.ImportState(loaded);

ImportState clears all existing variables before restoring the snapshot.

Missing Variables

If a variable is referenced but has no entry in any scope, the $VARIABLE text is left as-is.