Candy Logo Copyright © 2025-2026 Candy Arts
Code Modification
Candy Dialogue Engine is designed to be extended with your own code, without rewriting its scripts. Most customizations are done in one of two ways:
  • Hook functions: functions Candy Dialogue Engine calls at specific moments, which are empty until you write code in them.
  • Drop-in scripts: a script you add to a folder becomes a new Command, Dialogue Mode, event or tag. Nothing needs registering.
Customizations
GoalHowSee
Run code at a specific Dialogue step.Write it in a hook function, in User_Data/FunctionsHook Functions
Change how a UI Element or media player behaves.Write it in the hook functions of its script.UI
Create a Command.Add a script in Scripts/Commands, or one in Scripts/Custom_Events for the Custom commandCustom Commands
Decide what an Input Menu's events do.Add a script in Scripts/Input_EventsEvent Scripts
Decide what a Choice Menu's events do.Add a script in Scripts/Choice_EventsEvent Scripts
Run code when the Await Command detects a signal.Add a script in Scripts/Await_EventsEvent Scripts
Create a Dialogue Mode.Add a script in Scripts/Dialogue_ModesDialogue Modes, under Custom Modes, and write a script for the UI Element your Dialogue Mode displays Lines in.
Create a custom Variation tag.Add a script in Scripts/Variation_TagsVariations, under Tag Scripts
Add a data table.Add a script in User_Data/Data_TablesDatabase
Generate speech with text-to-speech or an LLM.Write it in the tts() and llm_query() functionsTTS, LLM
Move characters in cutscenes.Add a script in Scripts/Move_Events for the CS_Move commandCS Move
All these folders are inside Candy_DE/Scripts. Every script you add to these folders is 'safe', and so are the scripts that ship in User_Data/Functions and User_Data/Data_Tables. The script of a UI Element or media player is 'unsafe': see Updates, below. How Drop-In Scripts Work Each Engine reads the folders above once, when it runs its first Line, and loads every script in them. The same rules apply to all of them:
  • The file name is the name. Give_Item.gd is the Give_Item command, Phone.gd the Phone mode, Door_Opened.gd handles the door_opened signal. Names aren't case-sensitive.
  • The script extends the folder's base class: CandyCommand, CandyDialogueMode, CandyInputEvent... A script that extends something else is reported and left out.
  • Sub-folders only sort. Your scripts can be placed in a sub-folder of your own, such as Scripts/Commands/My_Commands.
  • Names must be unique. If two scripts of a folder have the same file name, even in different sub-folders, a warning names them and only one is loaded.
No state in the script Each Engine creates a single instance of each script, and runs it for every Line. Don't store anything about the running Dialogue in the script's member variables: two Lines, or two nested Commands, would overwrite each other's values. Use local variables, or store what must last on the Engine or in your own game code. Waiting The functions of these scripts can use await. The Engine waits for them to return before it carries on. Updates An update never modifies the files you add, and never overwrites the files that are meant to be edited, such as the hook function scripts of User_Data/Functions (see Updates, which lists them all). These files are deemed 'safe'. All other Candy Dialogue Engine files are 'unsafe': updates overwrite them. The Wizard detects modified files by comparing their hashes, and lists them before the update proceeds. To edit an 'unsafe' script anyway, record your changes and copy them back after each update.