Candy Logo Copyright © 2025-2026 Candy Arts
Dialogue Box
The Dialogue Box displays Lines in Box mode: the spoken text, with an optional speaker label and portrait.
  • Script: Box_UI.gd
  • Templates: Scenes/Dialogue_Boxes
  • Updates: the script is 'unsafe', and so is every template except Default.tscn (see Customizing UI Elements, on the UI page)
  • Engine path: dialogue_box_path in ui_elements_paths
  • Settings: see Box Mode
Nodes
VariableNode
dialogue_nodeRequired. RichTextLabel: the spoken text.
portrait_nodeRequired. The node that displays the portrait: any node type listed in Media Files that shows images or videos.
voice_nodeRequired. The voice player for this Dialogue Box (see Voice Players).
speaker_nodeOptional. RichTextLabel: the speaker's name label. Leave it empty for a Dialogue Box without one.
portrait_areaOptional. The node containing the portrait and its decorations. It is shown and hidden along with the portrait, so a frame or background doesn't stay on screen without it. When left empty, only portrait_node is shown and hidden.
portrait_bgOptional. A node behind the portrait, such as a background image.
portrait_fgOptional. A node over the portrait, such as a frame or overlay.
portrait_effect_playerOptional. An AnimationPlayer for effects on the portrait.
Candy Dialogue Engine doesn't modify portrait_bg, portrait_fg or portrait_effect_player itself: they're exported so that your own code, such as a hook function, can access those nodes. Speaker Name The speaker's name can be displayed in two places, independently:
  • In speaker_node, whenever one is assigned.
  • At the start of the spoken text, when box_show_speaker (or its overrides) is on.
The name displayed is the Actor's DisplayName (see Actor Properties), translated into the Engine's current language (see Translating Names). Portraits Which portrait file a Line displays, and how it plays, is decided by the Line (see Spoken Line) and the Actor's portrait folder (see Media Files). When no portrait is displayed (none set, or box_portrait_mode rules it out), the portrait is hidden: portrait_area if one is assigned, else portrait_node. A Sprite2D or Sprite3D portrait is scaled to the Dialogue Box's portrait_w and portrait_h. Other node types retain the size set in the scene. Hook Functions x_write_begun(), x_write_progress(), x_write_finished() and x_speech_advance(), called on the Dialogue Box: see Speech Display.