Copyright © 2025-2026 Candy ArtsSpoken Line
The Spoken_Line command displays and voices a Line spoken by an Actor. It selects the version of the text that matches the current language and conditions, checks the speaker's dispositions, inserts text variables and word substitutions, then sends the Line to the UI element of its Dialogue mode, such as the dialogue box or a speech bubble. Most of its keys override, for this Line only, settings defined on the speaker, the UI element and the Engine.
Keys
Every key also accepts a ¢ expression instead of a fixed value, unless its description says otherwise. See CandyRef Expressions.
Reference
Description:
The Actor who speaks the Line. It determines the displayed name, the portrait and voice folders, the dispositions tested, and the bust and speech bubble the Line is spoken from.
Values:
• Actor Reference: A key of the actors dictionary, such as Alice.
• °role: The Actor currently assigned to that Role, such as °guard. See Roles.
Disposition
Description:
A test on the speaker's dispositions; if it fails, the Line is skipped. The test is written as optional prefix characters, an optional count in parentheses, and a comma-separated list of dispositions. See Dispositions.
Values:
• a, b: The speaker has at least one of the listed dispositions.
• +a, b: The speaker has all of them.
• -a, b: The speaker has no dispositions outside the list.
• =a, b: The speaker's dispositions are exactly the list.
• !a, b: The speaker has none of them.
• (n)a, b: Exactly n of them match. Use +(n) for n or more, and -(n) for fewer than n.
• =(n)a, b: Exactly n of them match, and the speaker has no other dispositions.
• !(n)a, b: Exactly n of them don't match. Use !+(n) for n or more, !-(n) for fewer than n, and =!(n) for exactly n with no other dispositions.
• Empty: The Line always plays.
Portrait
Description:
The portrait displayed with the Line, loaded from {portraits_folder}/{actor}. Box and Chat modes only; in Chat mode, it is displayed on the Line's Chat_Line.
Values:
• File name: An image, frame folder or video, such as Smile. When the name has no extension, the UI element's default extension is added.
• Animation name: For an AnimatedSprite portrait node, an animation of the SpriteFrames set in Sprite_Frames_File.
• res:// or user:// path: Loaded from that path.
• Empty: Default.
Sprite_Frames_File
Description:
For AnimatedSprite portrait nodes only. The SpriteFrames file containing the Portrait animation; an Actor can have any number of them.
Values:
• File name: A file in {portraits_folder}/{actor}/Sprite_Frames. The UI element's default_animated_sprite_extension (.tres by default) is added when the name has no extension.
• res:// or user:// path: Loaded from that path.
• Empty: The speaker's own SpriteFrames, named after the Actor ({actor}.tres).
Portrait_Play
Description:
How many times an animated portrait plays; a still image has nothing to play. In Chat mode, a Line's portrait plays while the Line is being written; afterwards, a positive number finishes its loops and -2 continues playing.
Values:
• Positive number: Play that many times, then stop on the Portrait_Stop frame.
• 0: Display the first frame without playing.
• -1: Loop until the Dialogue moves on to the next Line, then stop on the Portrait_Stop frame.
• -2: Continue looping after the Dialogue moves on, until another Line replaces the portrait.
• -3: Loop until the Line's voice ends, or until the Dialogue moves on if that comes first, then stop on the Portrait_Stop frame. A Line without a voice stops on that frame at once.
• -3/n: As -3, but a Line without a voice plays as n instead (a positive number, 0, -1 or -2). For example, -3/-1 loops until the voice ends, or until the Dialogue moves on when the Line has no voice.
• Empty: 1.
Portrait_Stop
Description:
The frame an animated portrait stops on once its Portrait_Play loops are over. A video stops at that frame's timestamp.
Values:
• Positive number: That frame, counted from 1 and clamped to the available frames.
• -1: The last frame.
• 0: No frame; the portrait is removed, and the dialogue box hides its portrait area.
• Empty: 1.
Voice
Description:
The voice file played with the Line. See Voice.
Values:
• File name: Resolved according to voice_logic in Candy_Properties.gd. With the Folder logic, the file is searched for in voice_folder, in the subfolders described by voice_path ({actor}/{Dialogue}/{Conversation}/{Block} by default), then in a subfolder named after the Variation, except for the default Variation.
• res:// or user:// path: Loaded from that path, except that a subfolder named after the Variation is inserted before the file name, unless it is the default Variation.
• Empty: Default.
Variations
Description:
The versions of the Line's text. Each entry is named after its Variation and contains its text and settings (see below). The Variation whose name matches the current conditions is displayed. When several match, the most specific one wins, so a Variation without tags is only used when no tagged Variation matches. When the Engine's random_variations is enabled, the Variation is picked at random among the matching Variation and its numbered alternatives, weighted by Weight. If no Variation matches, the Line is skipped. A Variation's name is made of the following parts, separated by underscores:
Values:
• Language: The first part, which is required. It must match the current language, such as Default or French.
• tag=value: Must match the attribute of the speaker or the player (the Engine's speaker_tags and player_tags), or be accepted by the tag's script in Candy_DE/Scripts/Variation_Tags, such as S=Female or Weather=Rain. A name can contain any number of them.
• Bare tag: Only matches when the Line, the speaker or the Engine lists it as a passed tag, such as Shout. A name can contain any number of them.
• #N: A numbered alternative of the same Variation, such as Default_#2, only picked when random_variations is enabled.
• TTS: The last part. The text sent to text-to-speech in Advanced mode, which is never displayed, such as Default_TTS or French_TTS. The Lexicon never applies to it.
Passed_Tags
Description:
Variation tags that match on this Line regardless of their value, even if the speaker or the Engine disables them. Each entry (Tag_1, Tag_2...) contains one tag. For each tag, the most specific level that lists it takes precedence: the Line, then the speaker (PassedTags), then the Engine (passed_tags).
Values:
• Tag name: A bare tag such as Shout, or the name of a tag with values, such as S, which covers both S=F and S=M.
• ¢ expression: Can also return an Array of tag names, such as ¢["Shout", "S"].
Disabled_Tags
Description:
Variation tags that never match on this Line, even if the speaker or the Engine passes them, so Variations containing them are never picked. Each entry (Tag_1, Tag_2...) contains one tag. If a level lists a tag as both passed and disabled, it is disabled.
Values:
• Tag name: A bare tag such as Shout, or the name of a tag with values, such as S, which covers both S=F and S=M.
• ¢ expression: Can also return an Array of tag names, such as ¢["Shout", "S"].
Text_Events
Description:
The Line's own Text Events: Commands run while the Line is written, when the writing reaches their markers in the text. They are sorted by Variation like the Lexicon ("*", "Default*", "Default"...), each Variation key containing its Events under an Events key. For each marker, the Line's own Events are used first, then those of the Text Events dictionary (Text_Events.gd). In Candy Dialogue Creator, they are made in the Text Event Editor widget. See Text Events.
Values:
• Variation keys, each holding Events: Each Event contains Lines (the Commands it runs), Run_On_Skip, Pause_Voice and Resync_Voice.
• Empty: The Line has no Events of its own; its markers use the dictionary's.
Variation Settings
Each Variation in Variations accepts the following keys.
Text
Description:
The text the speaker says. To display values in it, use text variables; a text that starts with ¢ is an expression as a whole, whose result is displayed. To display one of the symbols literally, write it twice: ¤¤ displays ¤, and ¢¢ at the start displays ¢.
Values:
• Text: May contain BBCode.
• ¤Variable¤: A text variable, such as an Actor's name (¤Alice¤), an Actor's property (¤Alice.Age¤ or ¤°guard.Age¤), a variable from the variables dictionary (¤€gold¤) or any expression, such as a value from your game (¤¢globals.gold¤). See Displaying Variables.
• •word¦Actor•: A word substitution, with an optional category (•word¦Actor¦category•). See Word Substitution.
• ‡name‡: A Text Event marker: the Event of that name runs when the writing reaches it, and the marker isn't displayed. See Text Events.
• ¬text¬: Text the Lexicon never formats. The symbols aren't displayed. See Lexicon.
• ¢ expression: The whole text, evaluated when the Line runs; its result is then read like a written text. See Displaying Variables.
• Empty: The Variation is ignored.
Direction
Description:
The direction the text is written in. The value is case-insensitive.
Values:
• LtR: Left to right.
• RtL: Right to left.
• Empty: Left to right.
Weight
Description:
The Variation's relative probability of being picked at random among its alternatives. It isn't evaluated.
Values:
• Positive number: The relative weight, such as 3.
• Empty: 1.
Line Settings
These keys override a setting for this Line only. Each setting can be defined at several levels, from general to specific: the Engine, the UI element displaying the Line, the speaker (in the actors dictionary) and the Line itself; the most specific level that sets it takes precedence. All of them default to null, which leaves the setting to the other levels. Invalid values are reported and ignored, and mode names are case-insensitive. In the names below, <Mode> and <mode> stand for the Dialogue mode: Box, Subtitles, Chat, Bubbles, Barks or Voice.
Dialogue_Mode
Description:
How the Line is displayed. A mode that nothing in the scene can display, such as Subtitles without a subtitles UI element, is skipped in favor of the speaker's mode, then the Engine's. See Dialogue Modes.
Values:
• Box: The dialogue box.
• Subtitles: The subtitles.
• Chat: The chat.
• Bubbles: The speaker's speech bubble, or the bubble of their VN bust when the Engine is in VN mode.
• VN_Bubbles: The speech bubble of the speaker's VN bust. Don't assign it yourself: the Engine switches Bubbles Lines to it in VN mode (see VN Bubbles Mode).
• Barks: A bark, which is displayed without pausing the Dialogue.
• Voice: Voice playback only, without displaying any text.
• Custom mode name: The name of a script in Candy_DE/Scripts/Dialogue_Modes, for a mode of your own.
• null: Not set; the speaker's DialogueMode applies, otherwise the Engine's dialogue_mode.
Bubbles_Exempt_Mode
Description:
How the Line is displayed when the Dialogue mode is Bubbles but the speaker has no speech bubble.
Values:
• Box: The dialogue box.
• Subtitles: The subtitles.
• Chat: The chat.
• Bubbles: The speaker's speech bubble, or the bubble of their VN bust when the Engine is in VN mode.
• VN_Bubbles: The speech bubble of the speaker's VN bust. Don't assign it yourself: the Engine switches Bubbles Lines to it in VN mode (see VN Bubbles Mode).
• Barks: A bark, which is displayed without pausing the Dialogue.
• Voice: Voice playback only, without displaying any text.
• Custom mode name: The name of a script in Candy_DE/Scripts/Dialogue_Modes, for a mode of your own.
• null: Not set; the speaker's BubblesExemptMode applies, otherwise the Engine's bubbles_exempt_mode.
Portrait_Mode
Description:
Which speakers display a portrait. Box and Chat modes only.
Values:
• Off: No speaker.
• All: Every speaker.
• Player: Only the player.
• NPC: Every speaker except the player.
• VN: Only speakers who aren't on a VN bust.
• null: Not set; the speaker's <Mode>PortraitMode applies, otherwise the UI element's, otherwise the Engine's <mode>_portrait_mode.
Enable_Voice
Description:
Whether the Line's voice file is played.
Values:
• 1 or true: Play it.
• 0 or false: Don't play it.
• null: Not set; the speaker's EnableVoice applies, otherwise the UI element's, otherwise the Engine's enable_voice.
Await_Voice_Playback
Description:
Whether advancing to the next Line waits for the voice to finish playing.
Values:
• 1 or true: Wait.
• 0 or false: Don't wait.
• null: Not set; the speaker's AwaitVoicePlayback applies, otherwise the UI element's, otherwise the Engine's await_voice_playback.
TTS
Description:
How text-to-speech reads the Line. See TTS.
Values:
• Off: Disable text-to-speech.
• Simple: Read the Line's displayed text.
• Advanced: Read the Line's TTS Variation, such as Default_TTS, or use TTS_Advanced_Fallback when there is none.
• Custom mode name: A text-to-speech mode of your own, implemented by your tts() function.
• null: Not set; the speaker's TTS applies, otherwise the UI element's, otherwise the Engine's text_to_speech.
TTS_Advanced_Fallback
Description:
The text-to-speech mode applied when Advanced mode finds no TTS Variation.
Values:
• Off: Disable text-to-speech.
• Simple: Read the Line's displayed text.
• Custom mode name: A text-to-speech mode of your own, implemented by your tts() function.
• Advanced: Treated as Off, since there is no TTS Variation to read.
• null: Not set; the speaker's TTSAdvancedFallback applies, otherwise the UI element's, otherwise the Engine's tts_advanced_fallback.
LLM
Description:
Whether the Line is passed to the llm_query hook to be rewritten before it is displayed. See LLM.
Values:
• 1 or true: Pass it.
• 0 or false: Don't.
• null: Not set; the speaker's LLM applies, otherwise the UI element's, otherwise the Engine's llm_mode.
Writing_Speed
Description:
The typewriter speed at which the text is written. See Typewriter Effect.
Values:
• Characters per second: Such as 30.
• 0: Display the whole Line instantly.
• null: Not set; the speaker's WritingSpeed applies, otherwise the UI element's, otherwise the Engine's writing_speed.
Continue_Fast_Speed
Description:
The typewriter speed while the player holds the speed-up input.
Values:
• Characters per second: Such as 90.
• null: Not set; the speaker's ContinueFastSpeed applies, otherwise the UI element's, otherwise the Engine's continue_fast_speed.
Continue_Slow_Speed
Description:
The typewriter speed while the player holds the slow-down input.
Values:
• Characters per second: Such as 10.
• null: Not set; the speaker's ContinueSlowSpeed applies, otherwise the UI element's, otherwise the Engine's continue_slow_speed.
Sync_Write_Speed_Voice
Description:
Whether the typewriter speed adapts to the length of the voice file, so that the text finishes with the voice.
Values:
• 1 or true: Adapt it.
• 0 or false: Don't.
• null: Not set; the speaker's SyncWriteSpeedVoice applies, otherwise the UI element's, otherwise the Engine's sync_write_speed_voice.
Auto_Advance
Description:
The delay after which the Line advances on its own, once it is fully written. See Dialogue Advance.
Values:
• Number of seconds: Such as 2.5.
• -1: Only advance when the player does.
• null: Not set; the speaker's AutoAdvance applies, otherwise the UI element's, otherwise the Engine's auto_advance.
Auto_Advance_Per_Character
Description:
Seconds added to the Auto_Advance delay for each character the Line displays. With Auto_Advance 2 and 0.05, a 100-character Line waits 2 + 5 seconds. Ignored when Auto_Advance is -1. See Dialogue Advance.
Values:
• Number of seconds: Such as 0.05.
• 0: Nothing added.
• null: Not set; the speaker's AutoAdvancePerCharacter applies, otherwise the UI element's, otherwise the Engine's auto_advance_per_character.
Write_Dialogue_History
Description:
Whether the Line is recorded in the dialogue history.
Values:
• 1 or true: Record it.
• 0 or false: Don't.
• null: Not set; the speaker's WriteDialogueHistory applies, otherwise the UI element's, otherwise the Engine's write_dialogue_history.
Text_BBCode
Description:
BBCode tags applied to the Line's text, such as [color=#ff8080][i]. Only write the opening tags; Candy Dialogue Engine adds the matching closing tags. The end-of-line string isn't affected.
Values:
• Opening BBCode tags
• Empty: No tags, even if the speaker, the UI element or the Engine defines some.
• null: Not set; the speaker's <Mode>TextBBCode applies, otherwise the UI element's, otherwise the Engine's <mode>_text_bbcode.
Speaker_BBCode
Description:
BBCode tags applied to the speaker's name, including its prefix and suffix. Only write the opening tags. Box, Subtitles and Chat modes only.
Values:
• Opening BBCode tags
• Empty: No tags.
• null: Not set; the speaker's <Mode>SpeakerBBCode applies, otherwise the UI element's, otherwise the Engine's <mode>_speaker_bbcode.
Show_Speaker
Description:
Whether the speaker's name is displayed. Box, Subtitles and Chat modes only.
Values:
• 1 or true: Show it.
• 0 or false: Hide it.
• null: Not set; the speaker's <Mode>ShowSpeaker applies, otherwise the UI element's, otherwise the Engine's <mode>_show_speaker.
Speaker_Prefix
Description:
Text displayed before the speaker's name. Box, Subtitles and Chat modes only.
Values:
• Text
• Empty: No prefix.
• null: Not set; the speaker's <Mode>SpeakerPrefix applies, otherwise the UI element's, otherwise the Engine's <mode>_speaker_prefix.
Speaker_Suffix
Description:
Text displayed after the speaker's name, such as a colon. Box, Subtitles and Chat modes only.
Values:
• Text
• Empty: No suffix.
• null: Not set; the speaker's <Mode>SpeakerSuffix applies, otherwise the UI element's, otherwise the Engine's <mode>_speaker_suffix.
End_Of_Line_String
Description:
Text appended once the Line is fully written. All modes except Voice. See End-Of-Line String.
Values:
• Text: May contain BBCode.
• Empty: No text.
• null: Not set; the speaker's <Mode>EndOfLineString applies, otherwise the UI element's, otherwise the Engine's <mode>_end_of_line_string.
Advance_String
Description:
Text displayed while the Line waits for the player to advance. All modes except Voice.
Values:
• Text: May contain BBCode.
• Empty: No text.
• null: Not set; the speaker's <Mode>AdvanceString applies, otherwise the UI element's, otherwise the Engine's <mode>_advance_string.
Self_Clear
Description:
Whether the text is cleared when the Dialogue moves on to the next Line. Box and Subtitles modes only.
Values:
• 1 or true: Clear it.
• 0 or false: Retain it until another Line replaces it.
• null: Not set; the speaker's <Mode>SelfClear applies, otherwise the UI element's, otherwise the Engine's <mode>_self_clear.
Portrait_Self_Clear
Description:
Whether the portrait is cleared when the Dialogue moves on to the next Line. Box mode only.
Values:
• 1 or true: Clear it.
• 0 or false: Retain it until another Line replaces it.
• null: Not set; the speaker's BoxPortraitSelfClear applies, otherwise the UI element's, otherwise the Engine's box_portrait_self_clear.
Lexicon_Mode
Description:
Whether the Lexicon is enabled for this Line. See Lexicon.
Values:
• 1 or true: Enable it.
• 0 or false: Disable it.
• null: Not set; the speaker's Lexicon<Mode>Mode applies, otherwise the UI element's, otherwise the Engine's lexicon_<mode>_mode.
Line_Scene
Description:
The Chat_Line scene the Line is displayed in. Chat mode only.
Values:
• Scene name: A scene in chat_lines_folder (Candy_Properties.gd). The .tscn extension is added when missing.
• res:// or user:// path: Loaded from that path.
• null: Not set; the speaker's ChatLineScene applies, otherwise the UI element's, otherwise the Engine's chat_line_scene.
Speaker_Display
Description:
When the Line displays its speaker's name. Chat mode only. The speaker counts as changed when it differs from the previous Line's speaker, when the previous Line came from another Engine or Dialogue, and on the first Line after a separator.
Values:
• Every_Line: On every Line.
• Speaker_Change: Only when the speaker changes.
• null: Not set; the speaker's ChatSpeakerDisplay applies, otherwise the UI element's, otherwise the Engine's chat_speaker_display.
Portrait_Display
Description:
When the Line displays its portrait. Chat mode only.
Values:
• Every_Line: On every Line.
• Speaker_Change: Only when the speaker changes.
• Speaker_Or_Portrait_Change: When the speaker or the portrait changes.
• null: Not set; the speaker's ChatPortraitDisplay applies, otherwise the UI element's, otherwise the Engine's chat_portrait_display.
Alignment
Description:
The side of the Line where the portrait and name are displayed, which also sets the text alignment. Chat mode only.
Values:
• Left
• Right
• Alternate: The opposite side from the previous Line when the speaker changes, and the same side otherwise. A Dialogue's first Line starts on the left.
• null: Not set; the speaker's ChatAlignment applies, otherwise the UI element's, otherwise the Engine's chat_alignment.
Keep_Portrait_Space
Description:
Whether the space of a portrait that isn't displayed is preserved. Chat mode only.
Values:
• 1 or true: Preserve it.
• 0 or false: Don't.
• null: Not set; the speaker's ChatKeepPortraitSpace applies, otherwise the UI element's, otherwise the Engine's chat_keep_portrait_space.
Keep_Speaker_Space
Description:
Whether the space of a name that isn't displayed is preserved. Chat mode only.
Values:
• 1 or true: Preserve it.
• 0 or false: Don't.
• null: Not set; the speaker's ChatKeepSpeakerSpace applies, otherwise the UI element's, otherwise the Engine's chat_keep_speaker_space.
Keep_Alternate_Portrait_Space
Description:
Whether the portrait space on the opposite side of the Line is preserved. Chat mode only.
Values:
• 1 or true: Preserve it.
• 0 or false: Don't.
• null: Not set; the speaker's ChatKeepAlternatePortraitSpace applies, otherwise the UI element's, otherwise the Engine's chat_keep_alternate_portrait_space.
Keep_Alternate_Speaker_Space
Description:
Whether the name space on the opposite side of the Line is preserved. Chat mode only.
Values:
• 1 or true: Preserve it.
• 0 or false: Don't.
• null: Not set; the speaker's ChatKeepAlternateSpeakerSpace applies, otherwise the UI element's, otherwise the Engine's chat_keep_alternate_speaker_space.