UI Elements
Each page of this section describes one UI Element: the nodes it requires, its hook functions, and what to know when building or customizing one. For what UI Elements are and how they fit together, see the UI overview.
The settings that shape spoken Lines are listed for each Dialogue Mode, in Dialogue Modes. What each command does with a UI Element is explained on that command's page.
Connecting UI Elements to an Engine
An Engine locates its UI Elements through two dictionaries in its Inspector, under the Paths category:
- ui_elements_paths: the UI Elements that display speech, menus, backgrounds and VN busts.
- media_players_paths: the media and effect players. Their names are the ones Dialogues use to refer to them (see Media Players).
Each value is a node path, relative to the Engine node or absolute. A UI Element doesn't have to be a child of the Engine: any node in the scene tree is accepted.
The keys of ui_elements_paths are fixed. Each one serves a specific feature:
An Engine doesn't need every key: leave out the UI Elements its Dialogues never use. A Line that needs a missing UI Element reports it in the Output panel.
Speech bubbles are the exception: they belong to Actors, not to the Engine, and are located through the speaker's node (see Bubbles Mode).
Owning or naming
A plain path designates the Engine as the UI Element's owner. An entry written as ["path", false] only names the UI Element in this Engine, without owning it.
Ownership only matters for UI Elements with an Access setting (media players, Background Scenes and VN Scenes): see Media Players. A UI Element must never be owned by two Engines.
Mandatory and Optional Nodes
A UI Element's script accesses the nodes it controls through exported variables. Assign them in the Inspector, on the UI Element's root node.
Each page in this section lists those variables:
- Required nodes must be assigned: the UI Element can't function without them. Some UI Elements report a missing required node when the game starts; others only fail once a Dialogue uses them.
- Optional nodes can be left empty: the feature they serve is skipped.
Apart from these nodes, the node types, layout and hierarchy are free.
Text nodes
Nodes that display spoken text or speaker names must be RichTextLabels, with bbcode_enabled turned on. Otherwise BBCode wraps, Lexicon keywords and end-of-line strings are displayed as raw text: UI Elements report a label with BBCode turned off when the game starts.
Customizing UI Elements
The scenes in the Scenes folder are templates. To create your own, duplicate one, rename it, and modify it freely while retaining its script and required nodes.
Safe and unsafe files
Updates never overwrite a 'safe' file. They replace every 'unsafe' file with its new version, and overwrite your modifications to it. Candy Wizard lists your changed files first, but your changes and the update's can't be merged automatically (see Updates).
- Safe: the Default.tscn scene of each folder in Scenes, Candy_UI.tscn, and every scene and script you add.
- Unsafe: every other scene that ships, such as the Candy_Default.tscn templates, and the script of every UI Element and media player, such as Box_UI.gd.
Instructions:
- Modify the Default.tscn scenes, or create new scenes with their own names.
- Do not modify the Candy_Default.tscn scenes: they are overwritten by updates.
- Do not modify UI Element and media player .gd scripts: they are overwritten by updates. Duplicate these scripts or create your own.
- If you edit files that updates overwrite, record your modifications and save a copy of them, to apply them again after each update.
Scene folders
Some UI Elements are loaded by file name rather than placed in your scene: choice menus, categories and buttons, Input scenes, chat Lines and separators, and the scenes BG_Scene and VN_Scene switch to. The folder each kind is loaded from is set in Candy_Properties.gd (e.g. choice_menus_folder). Save your own scenes of those kinds in the matching folder.
Drawing Order
Canvas layers
In Candy_UI.tscn, the UI Elements are children of three CanvasLayers, so that backgrounds are drawn behind the 2D game world and the other UI Elements in front of it:
| CanvasLayer | Layer | UI Elements |
BG_Layer | -1 | The Background Scene. |
VN_Layer | 1 | The VN Scene. |
UI_Layer | 2 | The dialogue box, subtitles, chat, choice menus, Input Menus, History Display and media players. |
VN_Layer to -1 and that of BG_Layer to -2.
The Engine node, at the root of the scene, is a plain Node: it draws nothing, and doesn't affect how its children are drawn. In a Dialogue UI of your own, the Engine node can be any node type.
Z-order
Most UI Elements have a default_z setting: the z_index they receive when the game starts. The UI_Z command changes it during a Dialogue.
A z_index only orders nodes within the same CanvasLayer: a node on a lower layer is drawn behind every node on a higher layer, whatever their z_index. In Candy_UI.tscn, the default_z of the Background Scene and the VN Scene only orders them within their own CanvasLayer, and UI_Z can't draw either of them in front of the dialogue box. To draw the VN Scene in front of the dialogue box, set the layer of VN_Layer above that of UI_Layer.
The Z-order only decides what is drawn on top, not what receives the mouse: Godot delivers a click to the last node in the scene tree, whatever the z_index. A UI Element drawn on top can't be clicked where a node after it stops the mouse, even one drawn under it (a choice menu's shield, a full-screen panel). A UI Element meant to be clicked on top of another must therefore also follow it in the scene tree. In Candy_UI.tscn, the Input Menus' node follows the choice menus' node, since Input Menus can open over choice menus.
3D games
Godot draws every CanvasLayer in front of the 3D view, whatever its layer value, so the Background Scene covers the 3D world. To draw it behind the 3D world, set the background mode of your WorldEnvironment's Environment to Canvas, and its Canvas Max Layer to -1: CanvasLayers up to layer -1 are then drawn as the background of the 3D view.
Hook Functions
Hook functions are empty functions in a UI Element's script, which the Engine calls at specific moments: when writing begins, when playback starts, when a menu is ready... Write your own code in them to add behavior to the UI Element, such as changing a dialogue box's colors for each speaker or playing an animation.
Each UI Element page lists its hook functions and when they're called.
A UI Element's script is an 'unsafe' file: updates overwrite the hook functions you write in it. Write them in a copy of the script, attached to your own scenes (see Customizing UI Elements, above).
Arguments
Every hook function receives the same three arguments:
func x_write_begun(candy_args: Dictionary, user_args: Array, custom_data: Array):
var engine = candy_args["caller"]
var ui_element = candy_args["node"]
- candy_args: Candy Dialogue Engine's own values, by name. "caller" is always the Engine running the Line, and "node" the UI Element the hook belongs to. Some hooks add more keys: their page lists them.
- user_args: your own values, read from the hook's entry in the hook_arguments table (Hook_Arguments.gd). Entries are passed as written, unless they start with the CandyRef symbol (default ¢): those are evaluated each time the hook runs. A hook with no entry receives an empty Array.
- custom_data: the Custom Data of the Line that triggered the hook (see below).
Custom Data
In Candy Dialogue Creator, every Line, and every entry inside it, can carry numbered Custom Data values (Custom_1, Custom_2...). Candy Dialogue Engine never reads them itself: they're reserved for your own code.
custom_data contains one Array of values per level, from the Line down to the entry the hook works on: [[line values]], or [[line values], [entry values]]. Custom_1 is index 0 of its level. Values are passed as written: a ¢ expression isn't evaluated.
Waiting
The Engine waits for a hook function to return before it carries on. A hook that awaits (for example, an animation's end) delays the Line until it returns.
Copyright © 2025-2026 Candy Arts