Candy Logo Copyright © 2025-2026 Candy Arts
Next Steps - Symbols
In Dialogues, a symbol designates what kind of value follows it, in the way $ designates a node path in GDScript: a value written after ¢ is an expression, a name written after ° is a Role, and so on. Symbols are stored in Candy_Properties.gd and can be customized. Symbol List candy_ref_symbol (default ¢) Designates a value as a CandyRef expression, evaluated when the Line runs. An expression reads variables, tests a condition or computes a value, in GDScript syntax: ¢globals.gold + 10. See CandyRef Expressions. role_symbol (default °) Designates a Role: a stand-in for an Actor chosen at runtime, such as the player's current companion. When the Line runs, the Role is replaced by the Actor assigned to it: °companion. See Roles. vardict_symbol (default €) Inside an expression, reads a key of the variables dictionary: ¢€gold reads variables["gold"]. Using the variables dictionary is optional: its purpose is shorter variable references. An empty symbol disables the dictionary. See Variables Dictionary. text_var_start_symbol and text_var_end_symbol (default ¤) Enclose a value to display inside a Spoken Line's text: You have ¤¢globals.gold¤ coins. See Displaying Variables. substitution_start_symbol and substitution_end_symbol (default •) Enclose a Word Substitution inside a Spoken Line's text: Have you seen •him¦Alice•? See Word Substitution. separator_symbol (default ¦) Separates the parts of a Word Substitution, in the text (•him¦Alice•) and in the comparisons of the Substitution Table (">=¦18"). text_event_start_symbol and text_event_end_symbol (default ‡) Enclose the name of a Text Event inside a Spoken Line's text. The event runs when the writing reaches its marker: Wait‡boom‡... what was that? See Text Events. lexicon_escape_start_symbol and lexicon_escape_end_symbol (default ¬) Enclose text the Lexicon never formats, inside a Spoken Line's text. The symbols aren't displayed: ¬Alice¬ is just a name here. See Lexicon. Customizing Symbols
The Wizard's Symbols tool guides you through customizing the symbols and checks your choices against the rules below. If you use it, this section can be skipped: the rules are given here for completeness. The Candy Dialogue Creator can batch-update symbols in exported dialogues, saves and presets if you decide to modify the symbols later. The Wizard's Symbol Updater tool updates the Dialogues in your project the same way, to the symbols of Candy_Properties.gd and CandyRef_Shortcuts.gd. It only updates Dialogues that record the symbols they were written with, which Candy Dialogue Creator writes into every export, and the Wizard's Dialogue Converter into every converted Dialogue. For a Dialogue that doesn't, such as one written by hand, the tool's Record Symbols button records the symbols you enter.
The Engine identifies every occurrence of a symbol and will treat it as a marker wherever the symbol appears: in a value, in a name, in spoken text. If a symbol is written where it's not meant to act as a marker, it will create issues: text may be displayed incorrectly, a name may not be found, an expression may fail... To avoid this, follow the rules below when choosing symbols: All Symbols
  • Choose symbols that are quick to type, or bind them to macro keys.
  • A symbol can be made of several characters: ¢§ is a valid symbol.
  • Never let one symbol contain another: don't use ¢ and ¢§ together.
  • Don't use letters, digits, underscores or spaces in a symbol, nor any character that has a meaning in expressions: + - * / % < > = ! & | ^ ~ ( ) [ ] { } , . : $ and quotes.
  • Don't use the symbols, or their characters, in Actor names, Role names, variable names, function names, signal names or dictionary keys. The values of variables may contain them.
  • Avoid characters that occur in your Dialogues' ordinary text, in any language the game is translated into: such symbols will need to be escaped every time they're meant to display literally.
candy_ref_symbol CandyRef evaluates every value that starts with this symbol as an expression, so choose a symbol that no ordinary value starts with. For example, with # as the symbol, CandyRef would misinterpret a color code such as "#ff0000" as an expression. To write a value that starts with the symbol as a literal, escape the symbol by doubling it: "¢¢50" is read as the text "¢50", and is not evaluated. role_symbol and vardict_symbol The Engine registers these two with CandyRef as a Lookup symbol and a Shortcut symbol, alongside the symbols declared in CandyRef_Shortcuts.gd and any that another add-on using CandyRef registers. Keep all of these symbols different from one another. Text Variable, Word Substitution, Text Event and Lexicon Escape Symbols The Engine identifies these symbols anywhere in a Spoken Line's text. A start symbol and its corresponding end symbol can be identical. Don't write the Text Event or lexicon escape symbols inside a BBCode tag, and don't use brackets as either: the Engine reads both before BBCode (see Text Events and Lexicon). To display one of these symbols as a literal, escape it by doubling it: ¤¤ is displayed as ¤, •• as •, ‡‡ as ‡, ¬¬ as ¬, and •••• as ••. separator_symbol The separator divides the keys and values of the Substitution Table, so don't use it in a keyword, a property name or a rule value.