Variables Dictionary
The variables dictionary stores the values your Dialogues use often: the player's name, a score, the name of the next Block to jump to...
Its values are read anywhere with a short symbol (€ by default): ¢€gold instead of ¢candy_de.variables["gold"].
The dictionary is optional: your own autoloads serve the same purpose (¢globals.gold). Its advantage is the shortest reference to the values Dialogues read frequently.
The Dictionary
The dictionary is the variables variable, in the Variables.gd script (in User_Data/Data_Tables):
var variables = {
"player": "John",
"gold": 50,
"next_block": "Block_4",
"inventory": ["sword", "shield"],
"quests": {"dragon": "started"},
}
Each key is a variable's name, and its value can be of any type: a String, a number, a bool, an Array, a Dictionary...
Variables.gd is a 'safe' file: updates never overwrite it, so the variables added to it survive updates.
Naming Variables
- Plain names (letters, digits and _) are the shortest to reference:
¢€gold. - Other keys, such as keys with spaces, are written in quotes after the symbol:
¢€"high score". - Don't start a key with any of the symbols set in Candy_Properties.gd (¢, €, °...).
Reading Variables
In Expressions
Inside a CandyRef expression, € followed by a name reads that variable:
| Written as | Same as |
¢€gold | ¢candy_de.variables["gold"] |
¢€gold + 10 | ¢candy_de.variables["gold"] + 10 |
¢€inventory[0] | ¢candy_de.variables["inventory"][0] |
¢€quests.dragon | ¢candy_de.variables["quests"]["dragon"] |
¢€player.to_upper() | ¢candy_de.variables["player"].to_upper() |
¢€next_block, and an If command can test ¢€gold >= 100.
The symbol is only read inside an expression: €gold without ¢ is plain text. See CandyRef Expressions.
In Spoken Text
In a Spoken Line's text, a variable is displayed between the text variable symbols (¤ by default), without ¢:
Welcome back, ¤€player¤! You have ¤€gold¤ gold coins.
This is displayed as "Welcome back, John! You have 50 gold coins." See Displaying Variables.
In Code
In your own scripts, the dictionary is a property of the candy_de autoload:
candy_de.variables["gold"] += 10
print(candy_de.variables["player"])
Writing Variables
Expressions only read values. To modify a variable from a Dialogue, use the Set command, whose Variable field names the variable the same way, but without ¢:
| Variable | Operator | Expression |
€gold | += | ¢25 |
€player | = | Alice |
€quests.dragon | = | finished |
var variables = {
"base_price": 50,
"price": "¢€base_price * 2",
}
Here, ¢€price + 1 returns 101, and a change to base_price is reflected in price on its next reading.
To store text that starts with ¢ without it being evaluated, escape the symbol by doubling it: "¢¢50" is read as the text "¢50".
Saving Variables
The variables dictionary lives in memory: the changes made while playing are lost when the game closes, and the dictionary starts again from the values written in Variables.gd.
To preserve them, save candy_de.variables with the rest of your save data, and assign it back when a save is loaded:
# Saving:
save_data["candy_variables"] = candy_de.variables.duplicate(true)
# Loading:
candy_de.variables = save_data["candy_variables"]
Dialogues can also save and load variables themselves, with the Export and Import commands (exporting €gold, €player to a file in export_folder, for example).
Changing the Symbol
The symbol is set by vardict_symbol in Candy_Properties.gd:
var vardict_symbol = "€"
A symbol can be made of several characters, but it must not match or contain an operator or punctuation mark used in expressions. See 'Your Own Symbols' in CandyRef Expressions for the rules.
After changing the symbol, update the Dialogues that already use the old one.
No Match
Reading a variable that isn't in the dictionary is an error, not null: the Engine prints an error starting with "CandyRef failed:", naming the expression.
When a variable may not exist yet, read it with a default value instead:
¢candy_de.variables.get("gold", 0)
In spoken text, a variable that can't be read is left in the text as written.
Copyright © 2025-2026 Candy Arts