Candy Logo Copyright © 2025-2026 Candy Arts
Upgrades - Dialogues
Dialogues written for Candy Dialogue Engine 1.1.3 use a different format: in 1.2, Commands were renamed, merged and given new keys. The upgrade moves your Dialogue files into the new installation as they are, so 1.2 can't run them until they're converted. The conversion is performed by the Wizard's Dialogue Converter. It rewrites each Dialogue file for 1.2, Command by Command, and saves a backup of the original. Which Converter to Use Both Converters will convert Dialogues the same way. The only difference is that the Wizard can't convert Candy Dialogue Creator's saves and presets. Converting In the drop-down at the top of the Wizard's panel, choose the Dialogue Converter tool. It lists the Dialogues of your Dialogues folder that were written for 1.1.3. Click "Convert 1.1 Dialogues…". 1. Dialogues to convert Every Dialogue file is listed with its format. Tick the ones to convert. A file that can't be converted says why when you hover it. A file created with Candy Dialogue Creator 1.0 must first be converted to 1.1, with Candy Dialogue Creator 1.1's own converter. 2. Your 1.1 project What a 1.1 Line meant depended on a few things that aren't written in the Dialogue file. The Wizard fills them in from the copy of your 1.1.3 installation that the upgrade preserved. Correct anything your 1.1 project did differently:
SettingUsed for
1.1 symbolsThe symbols your Dialogues were written with, from 1.1.3's Candy_Properties.gd. The converter identifies the expressions, Roles, text variables and Word Substitutions in your Lines by these symbols.
Text to speechLines with TTS on. In 1.1, they were read in your Engine's TTS mode. In 1.2, each Line names its own mode, so this one is written into them.
Portrait nodeEvery Spoken Line. In 1.1, a portrait played differently depending on the node that displayed it. 1.2 counts loops instead, so the converter needs the node for each portrait to play as it did.
Dialogue UIThe Hide, V_Show and I_Show commands, which become UI_Z. 1.1 moved every UI Element the Engine had, while 1.2 names each one. Tick only the UI Elements your Engine has.
Background layersBackground commands with no Layers, which meant every layer in 1.1. 1.2 needs each layer named: list the layers of your background scenes, separated by commas.
Each setting is only used for the Lines it names: if your Dialogues have none, leave it as it is. The page also displays the 1.2 symbols the converted Dialogues are written with, from 1.2's Candy_Properties.gd: the expression, text variable, Word Substitution, Text Event and lexicon escape symbols. The variables dictionary, Role and separator symbols retain their 1.1 values, which the upgrade copied into Candy_Properties.gd. To use other symbols, change them in the Wizard's Symbols tool, before or after the conversion (see Symbols). Every converted Dialogue records the symbols it is written with, so the Wizard's Symbol Updater tool can rewrite it with the new symbols afterwards. A variables dictionary, Role or separator symbol changed before the conversion requires this update too, since the converter writes the 1.1 values of these symbols. 3. What the conversion does Every ticked file is converted in memory, and the Wizard displays the result: the files that can't be converted and why, and the Lines to check afterwards. Nothing is changed yet. 4. Convert Click the "Convert" button. For each file, the Wizard:
  • Saves a backup of the original, in a Conversion Backups/1.1 to 1.2 folder beside the file, in a folder named after the date and time.
  • Replaces the file with its converted version, which records the symbols it is written with.
A file is only replaced once its backup is written. The same folder contains a Conversion Log.txt file, which lists every Line to check, and why. The Wizard's tools ignore the Conversion Backups folders: the backups aren't read as Dialogues. What to Check Afterwards The converter preserves what your Lines did in 1.1.3 wherever it can. Where a Line can't be converted exactly, or needs something the Dialogue doesn't contain, the conversion log lists it. Open the log, and review each of those Lines in Candy Dialogue Creator. The most common cases: Symbols in spoken text 1.2 has symbols 1.1 didn't, such as ‡, which marks Text Events, and ¬, which excludes text from the Lexicon (see Text Events and Lexicon). Wherever your 1.1 text contains one of the 1.2 symbols as ordinary text, the converter writes it twice (‡‡, ¬¬, ¤¤...), so it's still displayed as it was. A spoken text that starts with ¢ is an expression in 1.2, so the converter writes that ¢ twice too. There's nothing to check: this note only explains the doubled symbols you may encounter in your converted Lines. Values your Lines display The converter can't reach the values your text variables display: the variables dictionary, Actor names, your game's own variables, save files. In 1.2, a displayed value is read like spoken text, so a value containing ‡ or ¬ as ordinary text is no longer displayed as it was: a pair of ‡ runs the Text Event it names, and ¬ isn't displayed. Double those symbols in your values (‡‡, ¬¬). The Upgrade Report lists the ones the Wizard found in your variables and actors dictionaries; your game's own data and its saves are yours to check (see Data). Lines that never showed in speech bubbles 1.2 has no "never bubbles" setting. Lines that had ForceBubbles set to -1 receive no Dialogue Mode of their own, so they use their Engine's, and may now be displayed in speech bubbles. Set a mode such as Box on those that must stay out of bubbles (see Mode Selection). Effects that stop In 1.2, stopping an effect can play its RESET animation, when Stop_Frame is Clear. Converted Lines retain 1.1.3's behavior: the effect stops on its current frame. Change their Stop_Frame for the new behavior. UI Clear In 1.1.3, the UI_Clear command never cleared backgrounds and busts, whatever the Line said. Converted Lines retain that: their Backgrounds and Busts keys are set to 0. Set them to 1 on the Lines that should clear them. Lines holding several Commands A 1.1 Line could contain several Commands, run one after the other. Most become Lines of their own, and the line numbers used by Jump, Bridge and choices in that Block are updated. Commands that 1.2 merges into a single one (for example, several media players in one Media_Play) now start together. Everything at once In 1.1.3, leaving Layers, Actors or Effects empty meant "all of them". 1.2 needs each one named. The background layers are filled in from the list you entered; Actors and Effects must be added by hand. Frames In 1.1.3, a time written in frames (f=) was counted at 30 frames per second. 1.2 counts the media's own frames. Variation names Tags are now written with an equals sign instead of a colon: Default_S:F becomes Default_S=F. Other broken Variation names are repaired and listed. A file with names that can't be repaired is left as it is: correct them in the file, then convert it again.