Candy Logo Copyright © 2025-2026 Candy Arts
Displaying Variables
A Spoken Line's text can display the value of a variable, of an Actor property or of an expression. The reference is written between two symbols:
Welcome back, ¤€player¤! You have ¤¢globals.gold¤ gold coins.
If the player variable in the variables dictionary (Variables.gd) is "John" and globals.gold is 50, this displays: "Welcome back, John! You have 50 gold coins." Writing a Text Variable In a Spoken Line's text, a variable is written between the text_var_start_symbol and the text_var_end_symbol. By default, both symbols are set to ¤. The symbols can be customized (see Symbols). In Candy Dialogue Engine 1.1, their defaults were {) and }. A text variable is one of the following:
TypeWritten asDisplays
An Actor Reference¤Alice¤The name of the Actor "Alice" (see 'Actor Names' below).
An Actor Reference + Property¤Alice.Age¤The value of the Age property of the Actor "Alice".
A Role Reference¤°companion¤The name of the Actor currently assigned to the "companion" Role.
A Role Reference + Property¤°companion.Age¤The value of the Age property of the Actor assigned to the "companion" Role.
A variables dictionary entry¤€gold¤The value of gold in the variables dictionary.
A CandyRef expression¤¢Game.gold * 2¤The result of an expression.
Spaces directly inside the symbols are ignored: ¤ €gold ¤ is the same as ¤€gold¤. Actors Writing an Actor Reference (the Actor's key in the actors dictionary, in Actors.gd) displays that Actor's name. Actor Names The name displayed is the first that isn't empty among:
  • The Actor's ShortName property.
  • The Actor's DisplayName property.
  • The Actor Reference itself.
ShortName is useful when an Actor's DisplayName is too long to be repeated in dialogues. For example, an Actor with the DisplayName "Alice Turner" and the ShortName "Alice" is displayed as "Alice Turner" above the dialogue box, but as "Alice" in a text variable. The name is translated into the Engine's current language through the display_names table (see Translating Names). Actor Properties To display one of the Actor's properties, add its key after the Actor Reference, with a dot or with brackets:
Alice is ¤Alice.Age¤ years old. Alice is ¤Alice["Age"]¤ years old.
Both forms display the same value. Brackets are required for keys that aren't plain names, such as keys with spaces: ¤Alice["Favorite Food"]¤. Nested values are read by chaining keys or array indexes: ¤Alice.Stats.Strength¤, ¤Alice.Titles[0]¤. Properties are displayed as they are stored, without translation. This includes the name properties: ¤Alice.DisplayName¤ displays the Default name in every language. To display a translated name, write ¤Alice¤, or see 'Reading Names Directly' in Translating Names. Roles A Role Reference (starting with °) is read like an Actor Reference, for the Actor currently assigned to that Role (in Roles.gd):
You should talk to ¤°companion¤. ¤°companion¤ has known you for ¤°companion.Years¤ years.
The same Line then displays the name and values of whichever Actor the Role is assigned to. Roles can be reassigned during Dialogues with the Role command. Displayed Values Values are displayed as text, the way GDScript's str() writes them: 50 displays "50", true displays "true", and so on. A null value displays nothing. Arrays and dictionaries are displayed whole (e.g. ["sword", "shield"]). To display one of their values, reference that value instead. Text as an Expression A spoken text that starts with ¢ is a CandyRef expression: the Engine evaluates it when the Line runs, and displays its result.
¢globals.greetings[globals.time_of_day]
The result is then read like a written text: Text Event markers, text variables and Word Substitutions in it are resolved as usual. A failed expression is displayed as written, and the Engine prints an error. A result that is null or empty skips the Line, like an empty text. A _TTS Variation's text is evaluated the same way. To display a text that starts with ¢, escape the symbol by doubling it: ¢¢50 gold, no less. is displayed as "¢50 gold, no less." Compatibility Text variables are replaced before Word Substitutions and Lexicon keywords are resolved. A variable's value can therefore contain a substitution (•he¦Alice•) or a Lexicon keyword. Text Event markers are read once text variables are replaced too, so a value can contain markers of its own, and a doubled symbol in a value is displayed once (see Text Events). With TTS or the LLM, the variables are replaced before the text is passed to the TTS tool or the LLM. No Match If a text variable can't be resolved, it is left in the text as written, and the Engine prints an error naming the Conversation, Block and line it is in. This can happen when:
  • The Actor Reference isn't in the actors dictionary.
  • The Role doesn't exist, or its Actor isn't in the actors dictionary.
  • The property or key doesn't exist.
  • The expression has an error.
  • The text has no symbol and isn't an Actor Reference (e.g. ¤gold¤ instead of ¤€gold¤).
Escaping Symbols To display the ¤ symbol as a literal, escape it by doubling it: ¤¤ is displayed as ¤, and the text that follows isn't read as a variable. Escaping works the same with custom symbols, including symbols made of several characters.