Candy Logo Copyright © 2025-2026 Candy Arts
Box Mode
Box mode displays the spoken text inside an RPG-style dialogue box, with a portrait and a speaker label. Engine Settings The following settings are available in the Engine (Candy_Engine.gd):
SettingPurpose
box_portrait_modeThe logic for displaying the speaker's portrait: "Off": Display no portrait. "All": Display a portrait for every speaker. "Player": Display a portrait only when the Actor is in the player_refs array (Player_Refs.gd). "NPC": Display a portrait only when the Actor is NOT in the player_refs array (Player_Refs.gd). "VN": Display no portrait when the Actor has a VN bust on screen.
box_text_bbcodeBBCode tags wrapped around the spoken text. Write the opening tags only: the Engine adds the closing tags.
box_speaker_bbcodeBBCode tags wrapped around the speaker name. Write the opening tags only: the Engine adds the closing tags.
box_show_speakerWrite the speaker's name at the start of the spoken text.
box_speaker_prefixText added before the speaker's name, when box_show_speaker is true.
box_speaker_suffixText added after the speaker's name, when box_show_speaker is true.
box_end_of_line_stringThe end-of-line string before advancing to the next Line.
box_advance_stringThe end-of-line string after advancing to the next Line.
box_self_clearClear the dialogue box when dialogue advances to the next Line.
box_portrait_self_clearClear the portrait when dialogue advances to the next Line.
lexicon_box_modeEnable Lexicon formatting in the spoken text.
writing_speedTypewriter speed, in characters per second. 0 displays the whole Line at once.
continue_fast_speedTypewriter speed while the speed-up input is held.
continue_slow_speedTypewriter speed while the slow-down input is held.
sync_write_speed_voiceMatch the typewriter's speed to the voice file's length. The synchronization is lost if the player accelerates or slows down the writing.
auto_advanceSeconds to wait before automatically advancing to the next Line. -1: Disable (manual advance only). 0: Advance immediately when writing is finished.
auto_advance_per_characterSeconds added to auto_advance for each character the Line displays (e.g. 0.05 adds 5 seconds to a 100-character Line). Ignored when auto_advance is -1.
enable_voicePlay voice files or TTS for Spoken Lines.
await_voice_playbackDisable advancing until voice playback has finished.
text_to_speechText-To-Speech: "Off": Don't use Text-To-Speech. "Simple": Use the spoken text (without BBCode tags) for Text-To-Speech. "Advanced": Use the _TTS Variation for Text-To-Speech. Additional TTS modes are created in the tts() hook function (Tts.gd).
tts_advanced_fallbackThe TTS mode to use instead of "Advanced" when a Line has no "_TTS" Variation. Without TTS modes of your own, the only values are "Simple" and "Off".
llm_modeQuery an LLM to write the text to display.
write_dialogue_historyLog Spoken Lines in the Dialogue History.
default_image_extensionDefault file extension to use when an image file name is provided without one.
default_sprite_extensionDefault file extension to use when a spritesheet file name is provided without one.
default_animated_sprite_extensionDefault file extension to use when a SpriteFrames file name is provided without one.
default_video_extensionDefault file extension to use when a video file name is provided without one.
default_animated_image_fpsDefault frame rate to use for frame-folder animations.
default_sprite_fpsDefault frame rate to use for Sprite2D/3D animations.
default_animated_sprite_fpsDefault frame rate to use for SpriteFrames animations saved with no speed of their own.
default_video_fpsFrame rate a Portrait_Stop frame counts at, for videos whose frame rate can't be read.
animation_folder_cacheMemory budget (MB) for animation folders.
animation_folder_streamHow many frames to load while an animation folder is streamed.
UI Settings The following settings are available in the dialogue box itself (Box_UI.gd): Overrides Each of these replaces the Engine setting of the same purpose while its enable_ switch is on (e.g. enable_writing_speed):
SettingOverrides
portrait_modebox_portrait_mode
text_bbcodebox_text_bbcode
speaker_bbcodebox_speaker_bbcode
show_speakerbox_show_speaker
speaker_prefixbox_speaker_prefix
speaker_suffixbox_speaker_suffix
end_of_line_stringbox_end_of_line_string
advance_stringbox_advance_string
self_clearbox_self_clear
portrait_self_clearbox_portrait_self_clear
lexicon_modelexicon_box_mode
writing_speedwriting_speed
continue_fast_speedcontinue_fast_speed
continue_slow_speedcontinue_slow_speed
sync_write_speed_voicesync_write_speed_voice
auto_advanceauto_advance
auto_advance_per_characterauto_advance_per_character
enable_voiceenable_voice
await_voice_playbackawait_voice_playback
text_to_speechtext_to_speech
tts_advanced_fallbacktts_advanced_fallback
llm_modellm_mode
write_dialogue_historywrite_dialogue_history
Portrait Files These replace the Engine setting of the same name, unless left at their inherit value (empty for extensions, 0 for frame rates, -1 for the cache and stream):
SettingPurpose
default_image_extensionExtension appended to portrait files named without one (TextureRect, NinePatchRect, TextureButton).
default_sprite_extensionExtension appended to spritesheet files named without one (Sprite2D, Sprite3D).
default_animated_sprite_extensionExtension appended to SpriteFrames files named without one (AnimatedSprite2D, AnimatedSprite3D).
default_video_extensionExtension appended to video files named without one (VideoStreamPlayer).
default_animated_image_fpsFrame rate of frame-folder animations (TextureRect, NinePatchRect).
default_sprite_fpsFrame rate of spritesheets (Sprite2D, Sprite3D).
default_animated_sprite_fpsFrame rate of SpriteFrames animations saved with no speed of their own.
default_video_fpsFrame rate a Portrait_Stop frame counts at, for videos whose frame rate can't be read.
animation_folder_cacheMemory budget (MB) of one animation folder: one that fits stays loaded, one that doesn't is streamed.
animation_folder_streamHow many frames are loaded ahead while an animation folder is streamed.
portrait_wThe width Sprite2D and Sprite3D portraits are scaled to.
portrait_hThe height Sprite2D and Sprite3D portraits are scaled to.
Other
SettingPurpose
default_zThe dialogue box's Z-order.
Actor Overrides The following overrides can be assigned to Actors (actors dictionary):
PropertyOverrides
BoxPortraitModebox_portrait_mode
BoxTextBBCodebox_text_bbcode
BoxSpeakerBBCodebox_speaker_bbcode
BoxShowSpeakerbox_show_speaker
BoxSpeakerPrefixbox_speaker_prefix
BoxSpeakerSuffixbox_speaker_suffix
BoxEndOfLineStringbox_end_of_line_string
BoxAdvanceStringbox_advance_string
BoxSelfClearbox_self_clear
BoxPortraitSelfClearbox_portrait_self_clear
LexiconBoxModelexicon_box_mode
DialogueModedialogue_mode
WritingSpeedwriting_speed
ContinueFastSpeedcontinue_fast_speed
ContinueSlowSpeedcontinue_slow_speed
SyncWriteSpeedVoicesync_write_speed_voice
AutoAdvanceauto_advance
AutoAdvancePerCharacterauto_advance_per_character
EnableVoiceenable_voice
AwaitVoicePlaybackawait_voice_playback
TTStext_to_speech
TTSAdvancedFallbacktts_advanced_fallback
LLMllm_mode
WriteDialogueHistorywrite_dialogue_history
The Actor's DisplayName is the name displayed in the speaker label and at the start of the text, translated into the Engine's current language (see Translating Names). Portrait Overrides A config.txt file in a portrait file's folder overrides the UI and Engine settings for the files of that folder:
KeyOverrides
extensionThe extension settings (default_image_extension, default_sprite_extension, default_animated_sprite_extension, default_video_extension).
fpsThe frame rate settings (default_animated_image_fps, default_sprite_fps, default_animated_sprite_fps, default_video_fps).
cacheanimation_folder_cache
streamanimation_folder_stream
FilesSettings for one file each, named as it is in the folder: fps, cache and stream override the folder's own.
For example: extension = png fps = 12 Files: { sprite_sheet_4x2-1.png: {fps = 8} } A frame-folder animation can also contain its own config.txt, with a single fps = <number> line. Line Overrides The following overrides can be assigned to Spoken Lines:
KeyOverrides
Portrait_Modebox_portrait_mode
Text_BBCodebox_text_bbcode
Speaker_BBCodebox_speaker_bbcode
Show_Speakerbox_show_speaker
Speaker_Prefixbox_speaker_prefix
Speaker_Suffixbox_speaker_suffix
End_Of_Line_Stringbox_end_of_line_string
Advance_Stringbox_advance_string
Self_Clearbox_self_clear
Portrait_Self_Clearbox_portrait_self_clear
Lexicon_Modelexicon_box_mode
Dialogue_Modedialogue_mode
Writing_Speedwriting_speed
Continue_Fast_Speedcontinue_fast_speed
Continue_Slow_Speedcontinue_slow_speed
Sync_Write_Speed_Voicesync_write_speed_voice
Auto_Advanceauto_advance
Auto_Advance_Per_Characterauto_advance_per_character
Enable_Voiceenable_voice
Await_Voice_Playbackawait_voice_playback
TTStext_to_speech
TTS_Advanced_Fallbacktts_advanced_fallback
LLMllm_mode
Write_Dialogue_Historywrite_dialogue_history