Copyright © 2025-2026 Candy ArtsUpgrades - Game Code
Your game code calls Candy Dialogue Engine to start Dialogues, read its data and react to its signals. Most of these calls work in 1.2 as they did in 1.1.3. This page lists the ones that changed, and how to update them.
The changes to data (the actors and roles dictionaries, the Engine's settings, saved games) are listed on the Data page.
Unchanged
These are called as in 1.1.3:
• On an Engine: load_scripted_dialogue(), start_dialogue(), jump_start_dialogue(), suspend_dialogue() and resume_dialogue().
• On the candy_de autoload: open_instance_history(), open_general_history(), clear_busts_ood() and clear_bg_layers_ood().
• The Data Tables and Localization Tables, through the candy_de autoload: candy_de.actors, candy_de.flags...
• The Engine's input_received, choice_list_event and killswitch_off signals.
The candy_de autoload points to another script in 1.2, which the upgrade sets in your project settings. Its name is unchanged, so the code that refers to it needs no edit.
Engine Functions
In 1.2, most helper functions of the Engine were moved into classes. The functions of these classes accept the Engine and the calling object as their first two arguments:
| 1.1.3 | 1.2 |
engine.resolve_value(value) | engine.candy_ref.resolve_value(engine, self, value, candy_de.candy_ref_symbol) |
| decode_variable_name(), get_variable_value(), set_variable_value() | resolve_value(), above, reads a variable. To write one, engine.candy_ref.resolve_target(engine, self, target, candy_de.candy_ref_symbol) locates it: it returns a Dictionary whose "container" and "key" entries designate the variable. |
| calculate_variable_value() | CandyValues.get_shared().calculate_value() |
| candy_to_dict(), candy_to_array(), candy_to_string() | CandyLiteral.get_shared()'s to_dict(), to_array() and to_text() |
| translate(), bbcode_strip_tags(), apply_lexicon_tags() | The functions of the same name of CandyWriting.get_shared() |
| pause_backgrounds(), pause_busts(), resume_backgrounds(), resume_busts() | pause_ui_elements(), resume_ui_elements() |
commands(key, value, conversation, block, line_index) | commands(key, value, ctx), where ctx is a CandyContext (see Custom Commands) |
| display_line(), wait_for_player_advance() | Removed: each UI Element displays its Lines itself. |
"res://Music/Theme.ogg" returned the AudioStream. In 1.2, the path remains a String. Load the resource in your code, or with load() in the expression: ¢load("res://Music/Theme.ogg").
Hook Functions
In 1.2, hook functions are no longer methods of the candy_de autoload (see Custom Code). has_method() returns false for them, and calling one as a method fails:
| 1.1.3 | 1.2 |
candy_de.has_method("x_new_line") | candy_de.has_user_function("x_new_line") |
candy_de.x_new_line(engine, line_data) | candy_de.run_hook("x_new_line", {"caller": engine, "line_data": line_data}) |
candy_de.run_user_function("give_reward", [50]) (see Functions of Your Own, on the Hook Functions page).
Stopping Dialogues
1.2 adds interrupt_dialogue(), which stops a running Dialogue at any point, even in the middle of a Line, and ends it cleanly. It can be awaited, to start another Dialogue once the first has ended (see Interrupting Dialogues).
If your code sets the Engine's killswitch to true, call raise_killswitch() instead. Setting the variable still stops the Lines, but doesn't stop an Await command that waits for a signal.
Dialogue Modes and TTS Modes
The Engine's DialogueModes and TtsModes enums are removed. dialogue_mode, bubbles_exempt_mode, text_to_speech and tts_advanced_fallback contain names: compare them with "Box", "Bubbles", "Simple"... instead of enum values.
clear_previous_dialogue() accepts the Line's CandySpeech object as its second argument, instead of the speaker.
New Signals
1.2 adds signals to the Engine, which your game can connect to:
• dialogue_resumed: emitted when a suspended Dialogue resumes (see Suspending Dialogues).
• dialogue_fully_ended: emitted when the Engine has finished ending a Dialogue (see Ending Dialogues).