Candy Logo Copyright © 2025-2026 Candy Arts
Dialogue Advance
Once a Spoken Line has finished writing, the Dialogue waits before advancing to the next Line. The Dialogue advances in two ways: on player input, or automatically after a delay. Player Input The Engine's input_advance_dialogue setting (in the Inspector, under the Input category) names the input action that advances the Dialogue. By default, it names the Dialogue_Advance input action (from the Input Map, in Project Settings). The Wizard adds the Dialogue_Advance action when it installs Candy Dialogue Engine, without assigning a key to it. Non-Key Inputs The Engine's input settings only accept input actions. To advance the Dialogue another way, such as with an on-screen button, press the action from code: connect the button's pressed() signal to a function like this one:
func _on_advance_button_pressed() -> void: Input.action_press("Dialogue_Advance") await get_tree().process_frame Input.action_release("Dialogue_Advance")
Disabling Input The Engine's input_enabled setting disables input entirely: when it's false, the Engine ignores input_advance_dialogue. This is useful for cutscene videos or NPC barks. Auto Advance Auto-advance is configured through the Engine's auto_advance setting, under the Writing category. A value of 0 or more enables auto-advance: it is the delay, in seconds, between the end of the writing and the advance to the next Line. With 0, the Dialogue advances as soon as the text is fully written. A value of -1 disables auto-advance. The Engine's auto_advance setting can be overridden by the UI Elements that display speech (dialogue box, subtitles...), by Actor properties (in the actors dictionary) and by Spoken Line data. Time per Character To grant longer Lines more reading time, set auto_advance_per_character (Writing category): the seconds added to auto_advance for each character the Line displays. The Dialogue then waits auto_advance + auto_advance_per_character × characters.
auto_advance = 1 auto_advance_per_character = 0.05 "Hello." → 1 + 6 × 0.05 = 1.3 seconds A 100-character Line → 1 + 100 × 0.05 = 6 seconds
  • The characters are counted as the Line is displayed: variables, expressions and Lexicon keywords are replaced first. BBCode tags, text event markers, the speaker name and the end-of-line string don't count.
  • In Voice mode, where no text is displayed, the text the Line would display is counted.
  • The default, 0, adds nothing. When auto_advance is -1, the Line only advances on player input, whatever this setting.
  • A negative value shortens the wait on longer Lines; the wait never drops below 0.
Like auto_advance, it can be overridden by the UI Elements that display speech (enable_auto_advance_per_character), Actor properties (AutoAdvancePerCharacter), Spoken Line data (Auto_Advance_Per_Character), and the Engine_Writing command. Voice Wait The Engine's await_voice_playback setting, under the Writing category, blocks the advance while the voice is playing. When it's enabled, player input doesn't advance the Dialogue until the voice has finished playing. Auto-advance always waits for the voice to finish, whether this setting is enabled or not. Its countdown still starts as soon as the text has finished writing, even while the voice is playing: the Dialogue advances once both the countdown and the voice are over. The Engine's await_voice_playback setting can be overridden by the UI Elements that display speech (dialogue box, subtitles...), by Actor properties (in the actors dictionary) and by Spoken Line data.