Copyright © 2025-2026 Candy ArtsDialogue Modes
A Dialogue Mode decides how a Spoken Line is displayed: in a dialogue box, as subtitles, in a chat, in a speech bubble, or not at all.
Standard Modes
Candy Dialogue Engine ships with these modes:
Box mode - Displays the spoken text inside a dialogue box, with an optional portrait and speaker label.
Subtitles mode - Displays the spoken text alone, without a portrait or a dedicated speaker label.
Chat mode - Appends the spoken text to a chat box, with an optional portrait and speaker label.
Bubbles mode - Displays the spoken text inside a speech bubble, near the Actor's sprite or mesh or in the game environment, without a portrait or a dedicated speaker label.
Barks mode - Like Bubbles mode, for NPC barks.
Voice mode - Plays the voice only: no text, portrait or speaker label.
Alternate Modes
An alternate mode is a Dialogue Mode the Engine switches to on its own. Never assign an alternate mode yourself, anywhere.
One alternate mode is included:
VN Bubbles mode - like Bubbles mode, for Visual Novel speakers who have a Bust on screen.
Common Features
Every Dialogue Mode that displays written text:
- plays voice files.
- formats the text with BBCode.
- writes the text with the typewriter effect.
- displays the end-of-line string.
Box, Subtitles and Chat modes can also write the speaker's name at the start of the spoken text.
Settings & Overrides
The settings of a Dialogue Mode are configured in two places, through the Inspector:
- in the Engine that runs the Dialogue.
- in the UI Elements the Dialogue Mode displays Lines with, whose settings override the Engine's.
Both are overridden by:
- Actor properties (in the actors dictionary).
- Spoken Lines (through their override data fields).
Portrait files are located and played according to their own settings (extension, frame rate, memory use), which a config.txt file in the portrait's folder overrides (see Media Files).
Custom Modes
Every Dialogue Mode is a script in the Candy_DE/Scripts/Dialogue_Modes folder, named after the mode: Box.gd is Box mode, Subtitles.gd is Subtitles mode, and so on.
To create a mode of your own, add a script to that folder. Its file name is the mode's name: a Phone.gd script creates a "Phone" mode, usable wherever a Dialogue Mode is set: the Engine's dialogue_mode and bubbles_exempt_mode, an Actor's DialogueMode, a Spoken Line's Dialogue_Mode, or the Dialogue_Mode command. Mode names aren't case-sensitive. Nothing needs registering. The scripts you add are 'safe': updates never modify them. The built-in ones, such as Box.gd, are 'unsafe'.
The script extends CandyDialogueMode and requires one function: display_node(), which returns the node that displays the Line. That node requires a display() function, like the UI Elements Candy Dialogue Engine ships with: a mode can therefore reuse a Dialogue Box, Subtitles or Chat scene, or a UI Element of your own.
extends CandyDialogueMode
func display_node(engine: CandyEngine, _speech: CandySpeech) -> Node:
return engine.get_node_or_null("/root/Game/Phone_UI")| Function | Purpose |
| is_available() | Whether the mode has something to display Lines with. An Actor's or Line's mode that isn't available is passed over for the next one (e.g. the Engine's). |
| prepare() | Prepares a Line before it's displayed. It can also hand the Line to another mode, by returning that mode's name, or to the bubbles exempt mode, by returning "". Bubbles mode uses it to switch to VN Bubbles mode, and to fall back when the speaker has no speech bubble. |
| start_line() | Called as a Line starts in this mode, once the previous Line was cleared. |
| clear_line() | Clears what this mode's Line left on screen, as the next Line starts. It receives the next Line's mode, so a mode can clear only when the mode changes. |
| settings_prefix() | The name the mode's settings are named after (by default, the mode's name in lowercase). See below. |
"bubbles", so it reads the Bubbles settings.