Candy Logo Copyright © 2025-2026 Candy Arts
Chat
The Chat displays Lines in Chat mode: Lines stacked one under the other, which the player can scroll back through to the very first one. It's composed of four scenes, each with its own role:
SceneRole
Chat_BoxLays out one or more Chat_Channels.
Chat_ChannelRuns the Lines (typewriter, voice, advance) and retains every one of them. This is the UI Element the Engine communicates with.
Chat_LineDisplays one Line: its text, with a portrait and a speaker label on each side.
Chat_SeparatorSeparates two Dialogues' Lines, when the first Dialogue's Lines are retained.
Settings: see Chat Mode. Chat_Box
  • Script: Chat_Box.gd
  • Templates: Scenes/Chat_Boxes
  • Updates: the script is 'unsafe', and so is every template except Default.tscn (see Customizing UI Elements, on the UI page)
VariableNode
channelsRequired. The Chat_Channels the Chat_Box lays out.
The Chat_Box is displayed while at least one of the Chat_Channels in channels is visible. A Chat_Channel missing from channels has no effect on the Chat_Box's visibility. The Chat_Box has no settings. Engines never address the Chat_Box: chat_path in ui_elements_paths must point at a Chat_Channel inside it. Chat_Channel
  • Script: Chat_Channel.gd
  • Templates: Scenes/Chat_Channels
  • Updates: the script is 'unsafe', and the Default.tscn template is 'safe' (see Customizing UI Elements, on the UI page)
  • Engine path: chat_path in ui_elements_paths
VariableNode
lines_areaRequired. The Control the Lines are drawn in. Its width is the Lines' width.
voice_nodeRequired. The voice player for this chat (see Voice Players).
scroll_barOptional. A VScrollBar to scroll the chat with.
The lines area The Chat_Channel places the Lines itself, so lines_area must be a plain Control, not a Container. It turns on the area's clip_contents, so Lines scrolled out of view aren't displayed. Scrolling The mouse wheel scrolls the chat while the pointer is over the lines area, with or without a scroll bar. While the player is scrolled up, new Lines don't scroll the chat back down. Once the player scrolls back to the bottom, the chat follows new Lines again. Many Lines Every Line is retained, but only the Lines in view are displayed: the Chat_Channel creates only enough Chat_Line nodes to fill its view, and reuses them as the chat scrolls. A long conversation costs no more nodes than a short one. Chat_Line
  • Script: Chat_Line.gd
  • Templates: Scenes/Chat_Lines
  • Updates: the script is 'unsafe', and the Default.tscn template is 'safe' (see Customizing UI Elements, on the UI page)
The scene each Line uses is chosen by the chat_line_scene setting (and its overrides), so different speakers or Lines can use different Chat_Line scenes.
VariableNode
text_nodeRequired. RichTextLabel: the spoken text. Turn on its fit_content, so the Line grows with its text.
portrait_leftOptional. The portrait on the left of the text: any node type listed in Media Files that shows images or videos.
portrait_rightOptional. The portrait on the right of the text.
speaker_leftOptional. RichTextLabel: the speaker's name, on the left.
speaker_rightOptional. RichTextLabel: the speaker's name, on the right.
A Line uses the portrait and name on one side only, chosen by chat_alignment. Leave out a side's nodes if no Line is ever displayed on that side. Building a Chat_Line
  • The Chat_Channel sets the Line's width and reads its minimum height: use a Container that grows with its text as the root.
  • Reserving a hidden portrait's space (chat_keep_portrait_space) relies on the portrait node's minimum size: set one.
  • A Sprite2D portrait is scaled to the Chat_Line's portrait_w and portrait_h.
Reused nodes Since Chat_Line nodes are reused as the chat scrolls, one node displays many different Lines over its life. If you add code to a Chat_Line, don't store anything about the Line it displays: the next time the node is displayed, it may display another Line. Chat_Separator
  • Templates: Scenes/Chat_Separators
  • Updates: the Default.tscn template is 'safe'
Any scene can be a Chat_Separator: it needs no script and no nodes. The Chat_Channel sets its width to the Lines' width, and its height to its own minimum height. Which scene is used is chosen by chat_separator_scene. Hook Functions x_write_begun(), x_write_progress(), x_write_finished() and x_speech_advance(), called on the Chat_Channel (not on the Chat_Line): see Speech Display.