Candy Logo Copyright © 2025-2026 Candy Arts
Upgrades
An upgrade is distinct from an update: • Updating switches from one update to another, within a sub-version. For example: 1.1.2 to 1.1.3. • Upgrading switches from one sub-version to another. For example: 1.1.3 to 1.2.0. Updates consist of bug fixes and new features, and projects normally remain compatible. Upgrades involve deeper changes: • Dialogues may no longer work from one version to the next (conversion tools are always provided). • Some features may work differently, or use different configuration settings. • Custom code (hook functions, new Dialogue Modes and Commands...) may require editing to continue working. • Your game code may need edits where it refers to Candy Dialogue Engine's file paths, functions and variables. Upgrades are meant to be rare, and only happen when a feature requires deep changes. With 1.2.0, the entire code was redesigned to be more modular, so upgrades will be rarer and will require fewer edits to maintain project compatibility.
Before you proceed, be aware that the following will likely no longer work after you upgrade:
• Candy_UI.tscn: it should still work, but it has received improvements and minor bug fixes in 1.2.0. Paths to UI elements will need to be updated in the Inspector. • Custom UI and Media Player scenes: .tscn files will likely still work, some may need small adjustments, but .gd files will not work. • The Chat UI will no longer work: Chat mode has been remade entirely. • Hook functions: their arguments change, and their code may no longer work as before if it relied on Candy Dialogue Engine's code. • Modifications to the Candy Dialogue Engine code (including custom commands and dialogue modes). • References in your project code to Candy Dialogue Engine file paths, functions, signals and variables. • Data related to Candy Dialogue Engine in your save files (only applies if you shipped a game with Candy Dialogue Engine, and it depends on what data your game saved). • A few keys in the actors dictionary have been removed, renamed, replaced, or their values have changed meaning. • Roles in the roles dictionary have the role_symbol removed: °npc_1 → npc_1. • Some Engine settings have changed or been replaced and will need to be reconfigured. • A tool is provided to convert Dialogues to the new 1.2 format, but a few commands work differently and may need you to adjust one or two values. Some of these might work again with minor edits, others may require complete rework. To help you, the Candy DE Wizard will create a list of all the files you edited or created, and it will list some specific changes you must make. Candy Dialogue Engine 1.1 unfortunately required significant overhaul, so this could not be avoided. Candy Dialogue Engine 1.2 is a much more solid foundation, more modular and more future-proof: we don't think a 1.3 upgrade will be needed for a long time, and upgrading won't break as many things.
Upgrading As of 1.2.0, upgrades are performed by the Candy DE Wizard plugin. 1.1.3 → 1.2.0 If Candy Dialogue Engine 1.1.3 is installed in your project, follow these steps: 1. Back up your Godot project! 2. Download the Candy Wizard and place it in your project's addons folder. If the folder doesn't exist, create it. 3. Enable the Candy Wizard in Project > Project Settings > Plugins. Restart the Godot Editor. 4. A tab named "Candy Dialogue" is added to the bottom panel. Open it. 5. This is the Wizard. It reports that Candy Dialogue Engine 1.1.3 is installed in your project. 6. Click the "Upgrade to 1.2…" button, and follow the instructions. 7. Once the upgrade is done, restart the Godot Editor. The Wizard proceeds through these steps: 1) It asks for the 1.2.0 release, downloaded from GitHub or chosen as a zip file. 2) It displays the release's notes. Read them before you continue. 3) It requires another backup of your project, as a precaution. 4) It displays everything the upgrade is about to do, and what is left for you to do by hand. Nothing is changed before you click "Upgrade". The upgrade performs the following: 1) It copies everything in your 1.1.3 Candy_DE folder into the Candy_DE/.Install/Candy_DE_1.1.3 folder. Godot ignores this folder: open it in your file manager if you need to access it. 2) It replaces everything in the Candy_DE folder (except the Candy_DE_1.1.3 copy) with a fresh 1.2.0 installation. 3) It moves your Dialogues, media files, exports and UI resources back into the new Candy_DE 1.2.0. 4) It converts your 1.1.3 data from Candy_Localizations.gd, Candy_Database.gd and Candy_Properties.gd into 1.2.0's settings and tables. 5) It points the candy_de autoload to 1.2.0, and adds 1.2.0's input actions where they're missing. 6) It does not move your scenes and scripts from 1.1.3 into 1.2.0: they remain in the Candy_DE_1.1.3 copy. 7) It writes an Upgrade Report, which lists what was done and what is left to do by hand. Open it at any time with the "Upgrade Report" button, in the Wizard's Setup tool. If some of your folder settings pointed to folders outside Candy_DE (custom folders), those folders remain where they are. Their files receive 1.2.0's changes too, and their scenes and scripts are copied into the 1.1.3 copy, so their 1.1.3 versions are preserved while you update them. The upgrade installs 1.2.0. If a newer release is out, update to it afterwards (see Updates). Manual Tasks Several tasks remain after the upgrade: • Convert your Dialogues to the 1.2.0 format: see Dialogues. • Check your converted data, and configure a few new settings and variables: see Data. • Move your scenes from 1.1.3 into 1.2.0 by hand: see Scenes. • Rewrite your hook functions and your changes to Candy Dialogue Engine's code: see Custom Code. • Update the calls your game code makes to Candy Dialogue Engine: see Game Code. • Update the paths in your game code that refer to media folders the upgrade changed: see Media Files.