Upgrades - Data
During the upgrade, the Wizard copies your 1.1.3 data into the new 1.2 installation, and converts it to the 1.2 format. This data is:
• The settings in Candy_Properties.gd: symbols, folders, frame rates...
• The tables in Candy_Database.gd: Actors, Roles, variables, flags, the Lexicon, the Substitution Table...
• The tables in Candy_Localizations.gd: the translations of names and UI texts.
The Checking Your Data section lists the data the Wizard converted on assumptions, to verify after the upgrade. The All Changes section lists every change to this data between 1.1.3 and 1.2: the Wizard doesn't convert your game code, so wherever your code reads or writes this data, update it from that list. The same applies to your players' saved games, if they store any of this data.
Checking Your Data
Some 1.1.3 data has no exact equivalent in 1.2. In those cases, the Wizard converts it in the way closest to how your game behaved in 1.1.3. Check this data after upgrading: the Wizard's assumptions may not match what your game needs.
At the end of the upgrade, the Wizard writes the Upgrade Report: a text file listing what it did and the tasks left to you, including every value this section is about. Open it with the "Upgrade Report" button in the Wizard's Setup tool.
The Wizard also retains a copy of your original 1.1.3 installation, for reference, in the Candy_DE/.Install/Candy_DE_1.1.3 folder. Godot's FileSystem dock hides this folder: open it in your file manager (its name starts with a dot, so hidden files may have to be shown). This page refers to it as "the 1.1.3 copy".
Actors Dictionary (Actors.gd)
In 1.2, many keys of an Actor are overrides: each one replaces an Engine setting for the Lines this Actor speaks. Set to null, such a key means "not set": the Actor follows the Engine's setting. See Actor Properties.
• TTS: in 1.1.3, an Actor's TTS key could be set to 1 so that every one of their Lines used text-to-speech (TTS). The type of TTS, Simple or Advanced, wasn't set on the Actor: it was read from the text_to_speech setting of the Engine running the Line.
In 1.2, the Actor's TTS key sets the type directly: "Off", "Simple" or "Advanced" (see TTS). Therefore, for each Actor whose TTS was 1, the Wizard has to choose a type: it reads the text_to_speech setting of the Candy_UI.tscn scene in your 1.1.3 installation. Check these Actors, and set their TTS key to the intended type.
• BubblesOverride: in 1.1.3, an Actor's BubblesOverride key decided whether their Lines were displayed in speech bubbles: 1 for always, -1 for never, 0 to follow the Engine.
1.2 replaces it with a new key, DialogueMode, which sets the Dialogue Mode in which the Actor's Lines are displayed: "Box", "Subtitles", "Chat", "Bubbles" and so on (see Dialogue Modes). The Wizard converts 1 to "Bubbles", and 0 to null.
DialogueMode names a mode, so it can't express "never use speech bubbles". The Wizard converts -1 to null too: the Actor follows the Engine's Dialogue Mode, and their Lines are displayed in speech bubbles whenever the Engine uses the Bubbles mode. If an Actor must never use speech bubbles, set their DialogueMode to the mode that replaces it, such as "Box". Their Lines are then displayed in that mode rather than the Engine's.
• SpeakerBBCode: in 1.1.3, an Actor's SpeakerBBCode key formatted their name when they spoke, in every Dialogue Mode. It contained two strings: the opening BBCode tags and the closing ones, such as ["[b]", "[/b]"] to display the name in bold.
1.2 replaces it with three new keys, one for each Dialogue Mode that displays the speaker's name: BoxSpeakerBBCode, SubtitlesSpeakerBBCode and ChatSpeakerBBCode. Each one contains a single string with only the opening tags, such as "[b]": Candy Dialogue Engine adds the matching closing tags itself.
The Wizard writes the opening tags into all three keys. In 1.1.3, an Actor could also have a colour for their name (BoxSpeakerColor, SubtitleSpeakerColor, ChatSpeakerColor). 1.2 has no colour keys, so the Wizard converts the colour into a [color] tag, placed before the other tags. For example, ["[b]", "[/b]"] with a red BoxSpeakerColor becomes a BoxSpeakerBBCode of "[color=#ff0000ff][b]".
The closing tags are discarded. Check the Actors whose closing string contained something other than closing tags. For example, ["[b]", "[/b]:"] displayed "Alice:", with a colon after the name: 1.2 doesn't display that colon.
• Short Name: in 1.1.3, text variables, which display a value inside a Spoken Line's text, could display an Actor's short name (for example, {)Alice}), but a bug made them search for a key written Short Name, with a space, instead of ShortName. If your Actors dictionary contained the Short Name key, it is now renamed to ShortName, and text variables read that key (see Displaying Variables).
If an Actor had both keys in 1.1.3, the Wizard retains the ShortName value, unless it was empty: the Short Name value then replaces it. Short Name is deleted either way: check that the right name was retained.
Lexicon Dictionary (Lexicon.gd)
The Lexicon formats chosen keywords in Spoken Lines, for example to display a character's name in green with a tooltip. The keywords are defined in the lexicon dictionary (see Lexicon).
• BBCode: in 1.1.3, each keyword's BBCode key contained two strings, the opening tags and the closing tags, like an Actor's SpeakerBBCode. In 1.2, it contains a single string with only the opening tags. The Wizard retains the opening tags and discards the closing ones. Check the keywords whose closing string contained something other than closing tags: that part is no longer displayed.
• Variation keys: a Variation is a version of a Spoken Line's text, such as its translation into another language. Each Variation has a name, such as "Default" or "French" (see Variations). The lexicon dictionary is filtered by Variation: each of its top-level keys, such as "Default", "French*" or "*", indicates which Variations its keywords apply to.
In 1.1.3, the Lexicon dictionary Variation filters were case-insensitive: a filter named "french" could apply to the French Variation. In 1.2, a filter must match the Variation's name exactly, case included. The Wizard doesn't rename the filters in the Lexicon dictionary: check that each one is spelled exactly like your Variation names in your Dialogues.
Substitution Table Dictionary (Substitution_Table.gd)
Word Substitution replaces a word in a Spoken Line according to an Actor's properties, for example "he" or "she" according to their Gender. Its rules are defined in the substitution_table dictionary (see Word Substitution).
• Variation keys: the substitution_table dictionary is organized by Variation too, and its top-level keys must also match the Variation names exactly. Check them as for the Lexicon.
• Rules with extra values: a Property Rule names one or more Actor properties, and each of its rules lists one value per property. For example, under the properties "Class, Gender", the rule "Sorcer, M" matches an Actor whose Class is "Sorcer" and whose Gender is "M".
In 1.1.3, a rule with more values than there are properties ignored the extra values: under the single property "Class", the rule "Sorcer, M" matched every Actor whose Class is "Sorcer". In 1.2, such a rule never matches. Remove the extra values from these rules.
• Types: a value in a rule can be followed by a type, after the separator symbol (¦ by default): "18¦int" means the integer 18. In 1.1.3, the type only applied to the rule's value. In 1.2, the Actor's property must also be of that type: an Age stored as the text "18" no longer matches "18¦int", but an Age stored as the integer 18 does. Check these rules, and store the Actor's property with the right type, or remove the type from the rule.
Variables Dictionary (Variables.gd)
The variables dictionary contains values Dialogues reference through the variables symbol (€ by default), such as €player (see Variables Dictionary).
In 1.1.3, a variable could also contain a reference to another value, such as "£globals.hp", which Dialogues followed with the super symbols (€€, ££, $$). 1.2 removes the super symbols and the £ symbol: references are now written as CandyRef expressions, which start with ¢ (see CandyRef Expressions).
The Wizard copies the variables dictionary as it was, without converting these references, because it can't distinguish a reference from ordinary text that starts with the same symbol (such as "$50"). Rewrite your references as CandyRef expressions, as shown under Variables Dictionary in All Changes.
Settings (Candy_Properties.gd)
• Frame rates: an animation consists of image files in a folder (a frame folder), or of a single image containing every frame (a spritesheet). In 1.1.3, animated_image_fps (1 frame per second by default) only set the speed of frame folders played by the Image command, and cs_sprite_fps (30 by default) only the speed of spritesheets played by CS commands. Backgrounds, busts and portraits had their own speeds, set on their scenes.
In 1.2, these two settings are renamed default_animated_image_fps and default_sprite_fps, and the Wizard copies your values into them, but they now apply to every frame folder and every spritesheet without a speed of its own, including those of backgrounds, busts and portraits. If an animation no longer plays at the right speed, modify these settings, or set a speed on the scene concerned.
• Text variable symbols: text variables display a value inside a Spoken Line's text, between two symbols: {)€player} in 1.1.3. If your installation still had 1.1.3's default symbols ({) and }), the Wizard replaces them with 1.2's default symbols (¤ and ¤). The Wizard's Dialogue Converter tool then rewrites your Dialogues to match: {)€player} becomes ¤€player¤. If you had set your own symbols, the Wizard retains them.
• Symbols containing ¢, ‡ or ¬: 1.2 adds new symbols: ¢, which designates CandyRef expressions (the new candy_ref_symbol setting), ‡, which designates Text Events (the new text_event_start_symbol and text_event_end_symbol settings, see Text Events), and ¬, which excludes text from the Lexicon (the new lexicon_escape_start_symbol and lexicon_escape_end_symbol settings, see Lexicon). If one of the symbols you had set in Candy_Properties.gd (such as role_symbol) contains one of them, Candy Dialogue Engine can't distinguish them: the Upgrade Report lists it. Change either your symbol or the new one, in the Wizard's Symbols tool, which checks your symbols for such conflicts. Then rewrite the Dialogues converted before the change with the Wizard's Symbol Updater tool (see Dialogues).
• Scene folders: some settings name the folder of each kind of scene, such as bust_scenes_folder for VN bust scenes. The Wizard doesn't copy your 1.1.3 scenes into 1.2: they are moved back by hand (see Scenes). If one of these settings pointed to a folder you created inside the Candy_DE folder, that folder stays in the 1.1.3 copy, so the Wizard resets the setting to 1.2's default folder. Once you've moved your scenes back, set the setting to their folder again.
• Voice files: voice_path is a new setting that decides how voice files are organized in folders. The Wizard sets it to the 1.1.3 layout, so your voice files stay where they are (see Media Files).
Comments, Constants and Unreadable Tables
• Comments: to convert the actors dictionary, the Wizard rebuilds it from scratch. It does the same with the lexicon and substitution_table dictionaries, when they need converting. Rebuilding a dictionary removes the comments you wrote inside it. They remain in the 1.1.3 copy's Candy_Database.gd.
• Constants: the Wizard doesn't copy the constants (const) you added to Candy_Properties.gd, Candy_Database.gd or Candy_Localizations.gd, since 1.2's table scripts only declare variables. They remain in the 1.1.3 copy.
• Unreadable tables: to convert the actors, lexicon and substitution_table dictionaries, the Wizard reads them as GDScript values. If it can't (for example, because a value uses one of your own constants or functions), it copies the dictionary unconverted. Convert it yourself, using All Changes below.
All Changes
This section lists every change to Candy Dialogue Engine data between 1.1.3 and 1.2, including the ones above. Wherever your game code reads or writes this data, update it to match.
Data and Localization Tables
In 1.1.3, the tables were variables of Candy_Database.gd and Candy_Localizations.gd. In 1.2, each table is declared in its own script: data tables in the User_Data/Data_Tables folder, translation tables in the User_Data/Localization_Tables folder (see Database).
Your code still accesses the tables the same way, through the candy_de autoload: candy_de.actors, candy_de.flags and so on still work. Each variable you added to the 1.1.3 data scripts is moved into a script of its own, and retains its name, so your code accesses it the same way too.
Other changes:
• general_dialogue_history, the history of the Lines spoken in every Dialogue, has moved to Candy_Properties.gd. candy_de.general_dialogue_history still works.
• creator_flag_list, creator_disposition_list, creator_actor_list and creator_role_list are removed. They were lists for Candy Dialogue Creator, and are no longer part of Candy Dialogue Engine.
• hook_arguments is a new table. Hook functions are functions Candy Dialogue Engine calls at given steps of a Dialogue, such as the start of a Line, so that your code can react. This table passes your own arguments to them.
• text_events is a new table, in Text_Events.gd. It contains the Text Events available to every Spoken Line: Commands run while a Line is written (see Text Events). It starts empty.
• lexicon_word_rules is a new table, in Lexicon_Word_Rules.gd. It defines which characters may touch a Lexicon keyword, for each language (see Lexicon).
• The translation tables (display_names, choice_button_labels...) are unchanged.
Roles Dictionary (Roles.gd)
A Role stands in for a character your game chooses, such as °companion. The roles dictionary assigns an Actor to each Role (see Roles).
Its keys no longer start with the role symbol (° by default). Dialogues still write Roles with the symbol.
# 1.1.3
candy_de.roles["°companion"] = "Alice"
# 1.2
candy_de.roles["companion"] = "Alice"
Actors Dictionary (Actors.gd)
Several keys of each Actor are renamed, or accept different values:
| 1.1.3 key | 1.2 key | Changes |
| PortraitOverride | BoxPortraitMode | Whether the dialogue box displays the Actor's portrait. 1 (always) becomes "All", -1 (never) becomes "Off", 0 becomes null. |
| BubblesOverride | DialogueMode | The Dialogue Mode of the Actor's Lines, any mode rather than only Bubbles. 1 becomes "Bubbles", 0 and -1 become null. |
| TTS | TTS | The type of TTS the Actor's Lines use: "Off", "Simple" or "Advanced". -1 becomes "Off", 0 becomes null, 1 becomes the type set on an Engine (see Checking Your Data). |
| LLM | LLM | Whether the Actor's Lines are generated by an LLM (AI). 1 becomes true, -1 becomes false, 0 becomes null. |
| BoxTextColor | BoxTextBBCode | A BBCode string instead of a Color (see below). |
| BoxSpeakerColor | BoxSpeakerBBCode | A BBCode string instead of a Color. |
| BubbleTextColor | BubblesTextBBCode | A BBCode string instead of a Color. |
| SubtitleTextColor | SubtitlesTextBBCode | A BBCode string instead of a Color. |
| SubtitleSpeakerColor | SubtitlesSpeakerBBCode | A BBCode string instead of a Color. |
| ChatTextColor | ChatTextBBCode | A BBCode string instead of a Color. |
| ChatSpeakerColor | ChatSpeakerBBCode | A BBCode string instead of a Color. |
| BarkTextColor | BarksTextBBCode | A BBCode string instead of a Color. |
| SpeakerBBCode | Removed | Replaced by BoxSpeakerBBCode, SubtitlesSpeakerBBCode and ChatSpeakerBBCode (see Checking Your Data). |
| Short Name | ShortName | Same value. |
null means "not set": the Actor follows the setting of the UI Element or the Engine. TTS no longer accepts numbers: a number there causes an error on each of the Actor's Lines.
BBCode strings: text and speaker colours are no longer Color values. They're BBCode strings that contain only opening tags, such as "[color=#ff8080]", or "[color=#ff8080][b]" for a bold name in that colour. Candy Dialogue Engine adds the closing tags itself. "" means no formatting.
Display names: DisplayName and ShortName must contain the name in the Default language. Candy Dialogue Engine translates them through the display_names translation table each time they're displayed (see Translating Names). In 1.1.3, the Name command, which changes an Actor's name during a Dialogue, stored the name already translated. If your code translates a name before writing it into the actors dictionary, change it to write the Default name instead.
New keys: 1.2 adds many Actor keys, which override Engine settings for the Lines the Actor speaks. A missing key is read as null, so your code needn't add them. See Actor Properties.
Lexicon Dictionary (Lexicon.gd)
• Each keyword's BBCode key is a string of opening tags, like the Actors' BBCode strings, instead of two strings for the opening and closing tags. For example, ["[b][color=green]", "[/color][/b]"] becomes "[b][color=green]".
• Variation names can include tags, which make a Variation depend on a condition: S=F in "Default_S=F" means "when the speaker's Gender is F". 1.1.3 wrote these tags with : instead of =. In the top-level keys, "Default_S:F" becomes "Default_S=F".
• Top-level keys must match the Variation names exactly, capital letters included: "french" no longer applies to the French Variation.
• Keywords are found as whole words in every language. 1.1.3 only counted the letters A to Z as part of a word, so a keyword was also found next to an accented or non-Latin letter: "ric" inside "Éric". 1.2 counts every letter by default. To restore 1.1.3's behavior, or to define other rules for a language, see Word Rules on the Lexicon page.
• A keyword accepts a new Disabled key: the text it's displayed as when the Lexicon is off, and in the Dialogue History. Without it, the keyword is displayed as written, as in 1.1.3.
Substitution Table Dictionary (Substitution_Table.gd)
• Its top-level keys follow the same rules as the Lexicon's: Variation tags are written with = instead of :, and keys must match the Variation names exactly.
• A rule with more values than there are properties never matches.
• A rule value with a type, such as "18¦int", only matches if the Actor's property is of that type.
Variables Dictionary (Variables.gd)
1.1.3's super symbols (€€, ££, $$) followed a reference stored in a variable. They're removed in 1.2. Instead, a stored value that starts with ¢ is evaluated as a CandyRef expression when a Dialogue reads it. If your code stores references for your Dialogues to read, write them as CandyRef expressions:
| 1.1.3 | 1.2 |
"€score" | "¢€score" |
"£globals.hp" | "¢globals.hp" |
"$Game/Player.hp" | "¢$/root/Game/Player.hp" |
/root/ to reach the same node.
A value a text variable displays is read like spoken text, in 1.2: a pair of ‡ in it runs the Text Event it names, and ¬ isn't displayed. Wherever a value contains one of these symbols as ordinary text, double it: "A dagger ‡" becomes "A dagger ‡‡". This applies to every value your Lines display, in any dictionary or in your game's own variables. The Upgrade Report lists the ones found in the variables and actors dictionaries.
Settings (Candy_Properties.gd)
These settings were renamed or removed:
| 1.1.3 | 1.2 |
| text_var_symbol_start | text_var_start_symbol |
| text_var_symbol_end | text_var_end_symbol |
| substitution_symbol | substitution_start_symbol, and the new substitution_end_symbol (the symbols around a Word Substitution) |
| animated_image_fps | default_animated_image_fps, which applies to every frame folder |
| cs_sprite_fps | default_sprite_fps, which applies to every spritesheet |
| singleton_symbol (£), node_symbol ($), super_singleton_symbol, super_node_symbol, super_vardict_symbol, file_var_symbol | Removed: CandyRef expressions replace them. Their symbol is set by the new candy_ref_symbol setting (¢ by default). |
| 1.1.3 | 1.2 |
| portrait_mode | box_portrait_mode |
| bubble_exempt_mode | bubbles_exempt_mode |
| lexicon_bark_mode | lexicon_barks_mode |
| mp_count_variants | mp_count_variations |
| random_variants | random_variations |
| media_players_locations | media_players_paths |
| cs_locations | cs_paths |
"Box", "Subtitles", "Chat", "Bubbles", "VN_Bubbles", "Barks" or "Voice". In 1.1.3, they contained values of the DialogueModes enum, which is removed. For example, engine.dialogue_mode = engine.DialogueModes.Bubbles becomes engine.dialogue_mode = "Bubbles".
• text_to_speech (the Engine's type of TTS) and tts_advanced_fallback (the type applied when a Line has no Advanced TTS Variation) contain names too: "Off", "Simple" or "Advanced". In 1.1.3, they contained values of the TtsModes enum, which is removed.
• In 1.1.3, each Dialogue Mode had a colour setting for the text, and one for the speaker's name, each with a switch to turn it on: enable_box_font_color and box_font_color, enable_box_speaker_color and box_speaker_color, and the same for subtitles, chat, bubbles and barks. In 1.2, each pair is replaced by a BBCode string, like the Actors' ones: box_text_bbcode, box_speaker_bbcode, subtitles_text_bbcode, chat_speaker_bbcode and so on. "" means no formatting.
• The voice player, which plays the voice files of Spoken Lines in the Voice Dialogue Mode, is no longer listed with the media players: media_players_locations["Voice"] becomes ui_elements_paths["voice_player_path"].
• The "PEffect" entry of media_players_locations, which played effects on the portrait, is removed. The portrait is now part of the dialogue box, and its effect player is set on the dialogue box's portrait_effect_player setting.
Dialogue History
Each Engine records the Lines it runs in its dialogue_history, and every Engine records them in candy_de.general_dialogue_history (see Dialogue History). The entries retain the same structure, with a few differences in their contents:
• A Return is recorded as {"Return": ""}, instead of a dictionary containing the Conversation it returned to.
• display_name contains the plain name, without the Actor's SpeakerBBCode tags.
• In Box mode, speech no longer ends with the end-of-line string (the symbol displayed at the end of a Line, such as ▼).
• Lexicon keywords in speech are written as their Disabled text, when they have one.
Player Input
The template Input Menu sanitizes what the player types before storing it (see Sanitization): the stored value is enclosed in the lexicon escape symbols, ¬Bob¬ for a player who typed "Bob", and Candy Dialogue Engine symbols and BBCode in it are escaped. Spoken Lines display it as typed. If your game code compares or displays the stored value itself, remove the escape first: CandySanitizer.remove_lexicon_escapes(globals.player_name) == "Bob". To store the raw text instead, disable the sanitize_ options in an Input mode of your own (see Input Menus).
Saved Games
If your game saves Candy Dialogue Engine data, and players have saved games from the version of your game that used 1.1.3, your game must convert that data when it loads an old save:
• Roles dictionary: remove the role symbol from each key.
• Actors dictionary: rename and convert the keys listed under Actors Dictionary above. If the Name command changed an Actor's DisplayName or ShortName, the save contains the translated name: replace it with the Default name.
• Variables dictionary, and any other data holding 1.1.3 references: write the references as CandyRef expressions, as shown under Variables Dictionary above.
• Displayed values: escape the ‡ and ¬ symbols (by doubling them) in the values your Lines display, such as a name the player typed, as shown under Variables Dictionary above.
• Export files: the Export command saves chosen values in a file, and the Import command loads them back. The file stores each value under the name it was listed with in the Export command, such as £globals.hp. In 1.2, these names are written without £, and $ paths start from the Engine, so Import no longer matches the old names. Rename the keys of these files: £globals.hp becomes globals.hp, and $Game/Player.hp becomes $/root/Game/Player.hp. Keys that start with € don't change.
History entries saved by 1.1.3 can be displayed by 1.2 as they are.
Copyright © 2025-2026 Candy Arts