Candy Logo Copyright © 2025-2026 Candy Arts
Upgrades - Custom Code
In 1.1.3, custom code was written inside Candy Dialogue Engine's own scripts: hook functions in Candy_Functions.gd, new Commands, Dialogue Modes, events and Variation tags as additions to Candy_Engine.gd. 1.2 replaces these scripts, so the upgrade doesn't carry this code over: rewrite it in the 1.2 scripts and folders described below. The Upgrade Report lists every 1.1.3 script you modified, with the functions you changed, added or removed. Your 1.1.3 versions remain in the 1.1.3 copy (Candy_DE/.Install/Candy_DE_1.1.3). In 1.2, custom code is written in scripts of its own, which updates never overwrite (see Code Modification). Hook Functions In 1.1.3, every hook function was declared in Candy_Functions.gd, with its own arguments. In 1.2: • Each hook function is a separate script in User_Data/Functions, such as X_New_Line.gd. Write the code of your 1.1.3 function in the function of the same name. • Every hook function receives the same three arguments: candy_args, user_args and custom_data. The values 1.1.3 passed as separate arguments are entries of candy_args, under the name of the 1.1.3 argument. The shipped functions read them into variables of the same names, so a 1.1.3 body written below these lines receives the values it expects.
# 1.1.3 func x_flag_changed(caller, flag, value): Quests.update(flag, value) # 1.2 func x_flag_changed(candy_args: Dictionary, user_args: Array, custom_data: Array): var caller = candy_args["caller"] var flag = candy_args["flag"] var value = candy_args["value"] Quests.update(flag, value)
A few values were renamed:
Function1.1.31.2
llm_query()line, chosen_variant_namecandy_args["text"], candy_args["variation"]
_on_lexicon_clicked()data["keyword_variant"]data["keyword_variation"]
"line_data" contains the Line in the 1.2 format. Code that reads its keys must use the 1.2 names of the Commands and their keys: line_data["Spoken Line"]["Variants"] becomes line_data["Spoken_Line"]["Variations"], for example. The Commands section of the Cheat Sheet links to the page of each Command. tts() can't be copied as it is. In 1.1.3, the function chose the TTS mode, applying the Engine's fallback, and read the text to speak from the Line. In 1.2, candy_args["mode"] is the mode already chosen, as a name ("Simple" or "Advanced"), and candy_args["text"] is the text to speak. Retain only the code of your 1.1.3 function that generates the voice. See TTS. To pass your own values to a hook function, list them in the hook_arguments table: the function receives them as user_args. See Hook Functions, which also lists the hook functions 1.2 adds. UI Element Hook Functions In 1.1.3, the x_write_begun() and x_write_finished() functions of the dialogue box, the subtitles, the chat, the portrait and the bubbles, and the x_initialization_finished() function of the choice menu, received no arguments. In 1.2, they receive the same three arguments as the other hook functions, and candy_args["node"] is the UI Element the function belongs to. The portrait's functions are now the dialogue box's: write the code of both in Box_UI.gd. The scripts of UI Elements are overwritten by updates. Write your functions in a copy of the 1.2 script, attached to your own scenes (see Customizing UI Elements, on the UI page). Commands In 1.1.3, every Command was a case of a match statement in Candy_Engine.gd, and a new Command was a case added to it. In 1.2, each Command is a script in Scripts/Commands, named after the Command. To move a Command you added, create its script, and write the code of its case in the script's execute() function. See Custom Commands. The code of a case must be adapted: • The Line's location is a CandyContext object, passed to execute(): current_conversation, current_block and line_index become ctx.conversation, ctx.block and ctx.line_index. • The Engine is the engine argument of execute(), instead of self. • execute() returns what the Engine does next: "Continue", "END" or "Return". • The Engine's functions for values were replaced: see Game Code. A script can't replace a built-in Command: if two scripts have the same name, the Engine prints a warning and loads only one of them. If you modified a built-in Command in 1.1.3, give your version another name, so that it becomes a Command of its own. Custom Command In 1.1.3, each value of the Custom command's Command key was a case of a match statement. In 1.2, each value is a script in Scripts/Custom_Events, named after the value. Write the code of each case in the handle() function of its script. See Custom Events, on the Custom Commands page. CS_Move In 1.1.3, the CS_Move command was an empty case of Candy_Engine.gd, for your movement code. In 1.2, each kind of movement is a script in Scripts/Move_Events, and the Movement key of each target names the script that moves it. The Command locates each target node and passes it to the script. The Dialogue Converter can't determine the Movement of a target: its report lists every CS_Move command to complete. See CS Move. Events In 1.1.3, the Input, Choice_List and Await commands decided what each event did in a match statement. In 1.2, each event is a script, named after the event:
CommandFolder
InputScripts/Input_Events
Choice_ListScripts/Choice_Events
AwaitScripts/Await_Events
The built-in events are already scripts: Finish.gd, Close.gd and Run_Lines.gd for Input menus, Choice.gd and Timer.gd for choice menus. Write each case you added in the handle() function of a script of its own. handle() returns "Wait" to continue waiting, or "Continue", "Return" or "END" to leave the Command. See Event Scripts. Dialogue Modes In 1.1.3, the Dialogue Modes were a fixed list, and adding one meant modifying Candy_Engine.gd. In 1.2, each Dialogue Mode is a script in Scripts/Dialogue_Modes, and the UI Element it displays Lines in has a display() function. See Custom Modes, on the Dialogue Modes page. Variation Tags In 1.1.3, the values of custom Variation tags were computed by code added to Candy_Engine.gd. In 1.2, each tag is a script in Scripts/Variation_Tags, named after the tag, which returns the tag's current value. See Tag Scripts, on the Variations page. Other Changes to the Engine In 1.2, most of the code of Candy_Engine.gd was moved into classes, in Scripts/Classes: CandyRef for references and expressions, CandyValues for the operations of the Set command, CandyWriting for text and the Lexicon... The Upgrade Report names each 1.1.3 function you modified: locate its counterpart in 1.2 before you reapply your change. These scripts are overwritten by updates. The Wizard lists modified files before an update, but doesn't merge your changes into the new versions: record them, to reapply them after each update.