Chat Mode – Candy Dialogue Engine

Chat Mode

Chat mode stacks Spoken Lines one under the other, like a messaging app. The player can scroll back through them, up to the first Line. The Chat consists of three UI Elements: - Chat_Box (Chat_Box.gd): lays out one or more Chat_Channels, and is displayed while one of them is visible. It has no settings of its own. - Chat_Channel (Chat_Channel.gd): runs the Lines (voice, typewriter, advance) and retains every Line. The Engine's chat_path (in ui_elements_paths) points at a Chat_Channel, not at the Chat_Box. - Chat_Line (Chat_Line.gd): displays one Line, with a portrait and a speaker label on each side of the text. When a Dialogue's Lines are retained after it ends, a Chat_Separator scene is placed between them and the next Dialogue's Lines. Engine Settings The following settings are available in the Engine (Candy_Engine.gd):

Setting	Purpose
chat_portrait_mode	The 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.
chat_text_bbcode	BBCode tags wrapped around the spoken text. Write the opening tags only: the Engine adds the closing tags.
chat_speaker_bbcode	BBCode tags wrapped around the speaker name. Write the opening tags only: the Engine adds the closing tags.
chat_show_speaker	Write the speaker's name at the start of the spoken text.
chat_speaker_prefix	Text added before the speaker's name, when chat_show_speaker is true.
chat_speaker_suffix	Text added after the speaker's name, when chat_show_speaker is true.
chat_end_of_line_string	The end-of-line string before advancing to the next Line.
chat_advance_string	The end-of-line string after advancing to the next Line.
lexicon_chat_mode	Enable Lexicon formatting in the spoken text.
chat_line_scene	The scene each Line is displayed in (a Chat_Line): a path, or a file name in chat_lines_folder (Candy_Properties.gd).
chat_speaker_display	When a Line displays the speaker's name label: "Every_Line": On every Line. "Speaker_Change": Only on the first of several Lines in a row from the same speaker.
chat_portrait_display	When a Line displays the speaker's portrait (if chat_portrait_mode allows one at all): "Every_Line": On every Line. "Speaker_Change": Only on the first of several Lines in a row from the same speaker. "Speaker_Or_Portrait_Change": Also when the same speaker's portrait changes.
chat_alignment	Which side of the text a Line's portrait and name are on. The text aligns to the same side. "Left" / "Right": Always that side. "Alternate": The side opposite the previous Line's when the speaker changes, the same side while the same speaker continues. A Dialogue's first Line starts on the left.
chat_keep_portrait_space	Reserve the space of a portrait that isn't displayed on a Line, so that texts line up.
chat_keep_speaker_space	Reserve the space of a name label that isn't displayed on a Line.
chat_keep_alternate_portrait_space	Reserve the space of the portrait on the other side of the text.
chat_keep_alternate_speaker_space	Reserve the space of the name label on the other side of the text.
writing_speed	Typewriter speed, in characters per second. 0 displays the whole Line at once.
continue_fast_speed	Typewriter speed while the speed-up input is held.
continue_slow_speed	Typewriter speed while the slow-down input is held.
sync_write_speed_voice	Match the typewriter's speed to the voice file's length. The synchronization is lost if the player accelerates or slows down the writing.
auto_advance	Seconds to wait before automatically advancing to the next Line. -1: Disable (manual advance only). 0: Advance immediately when writing is finished.
auto_advance_per_character	Seconds 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_voice	Play voice files or TTS for Spoken Lines.
await_voice_playback	Disable advancing until voice playback has finished.
text_to_speech	Text-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_fallback	The 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_mode	Query an LLM to write the text to display.
write_dialogue_history	Log Spoken Lines in the Dialogue History.

These Chat settings apply to the whole chat rather than to each Line, so Actors and Spoken Lines can't override them:

Setting	Purpose
persistent_chat	Leave the chat visible when the Dialogue Mode changes between Spoken Lines.
chat_clear_on_start	Clear the chat's Lines when a Dialogue starts.
chat_clear_on_end	Clear the chat's Lines when a Dialogue ends.
chat_hide_on_end	Hide the chat when a Dialogue ends.
chat_separator_scene	The scene placed between two Dialogues' Lines when they aren't cleared (a Chat_Separator): a path, or a file name in chat_separators_folder (Candy_Properties.gd).

default_image_extension	Default file extension to use when an image file name is provided without one.
default_sprite_extension	Default file extension to use when a spritesheet file name is provided without one.
default_animated_sprite_extension	Default file extension to use when a SpriteFrames file name is provided without one.
default_video_extension	Default file extension to use when a video file name is provided without one.
default_animated_image_fps	Default frame rate to use for frame-folder animations.
default_sprite_fps	Default frame rate to use for Sprite2D/3D animations.
default_animated_sprite_fps	Default frame rate to use for SpriteFrames animations saved with no speed of their own.
default_video_fps	Frame rate a Portrait_Stop frame counts at, for videos whose frame rate can't be read.
animation_folder_cache	Memory budget (MB) for animation folders.
animation_folder_stream	How many frames to load while an animation folder is streamed.

UI Settings The following settings are available in the Chat_Channel (Chat_Channel.gd): Overrides Each of these replaces the Engine setting of the same purpose while its enable_ switch is on (e.g. enable_writing_speed):

Setting	Overrides
portrait_mode	chat_portrait_mode
text_bbcode	chat_text_bbcode
speaker_bbcode	chat_speaker_bbcode
show_speaker	chat_show_speaker
speaker_prefix	chat_speaker_prefix
speaker_suffix	chat_speaker_suffix
end_of_line_string	chat_end_of_line_string
advance_string	chat_advance_string
lexicon_mode	lexicon_chat_mode
line_scene	chat_line_scene
speaker_display	chat_speaker_display
portrait_display	chat_portrait_display
alignment	chat_alignment
keep_portrait_space	chat_keep_portrait_space
keep_speaker_space	chat_keep_speaker_space
keep_alternate_portrait_space	chat_keep_alternate_portrait_space
keep_alternate_speaker_space	chat_keep_alternate_speaker_space
clear_on_start	chat_clear_on_start
clear_on_end	chat_clear_on_end
hide_on_end	chat_hide_on_end
separator_scene	chat_separator_scene
writing_speed	writing_speed
continue_fast_speed	continue_fast_speed
continue_slow_speed	continue_slow_speed
sync_write_speed_voice	sync_write_speed_voice
auto_advance	auto_advance
auto_advance_per_character	auto_advance_per_character
enable_voice	enable_voice
await_voice_playback	await_voice_playback
text_to_speech	text_to_speech
tts_advanced_fallback	tts_advanced_fallback
llm_mode	llm_mode
write_dialogue_history	write_dialogue_history

Other

Setting	Purpose
channel_name	A name for this channel. Not displayed yet.
scroll_step	How far one turn of the mouse wheel scrolls, in pixels.
follow_margin	How close to the bottom the chat must be scrolled to continue following new Lines, in pixels.
view_margin	Extra room above and below the view where Lines are already displayed, in pixels, so that they don't pop in while scrolling.
default_z	The chat's Z-order.

The following settings are available in the Chat_Line scene (Chat_Line.gd): 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):

Setting	Purpose
default_image_extension	Extension appended to portrait files named without one (TextureRect, NinePatchRect, TextureButton).
default_sprite_extension	Extension appended to spritesheet files named without one (Sprite2D, Sprite3D).
default_animated_sprite_extension	Extension appended to SpriteFrames files named without one (AnimatedSprite2D, AnimatedSprite3D).
default_video_extension	Extension appended to video files named without one (VideoStreamPlayer).
default_animated_image_fps	Frame rate of frame-folder animations (TextureRect, NinePatchRect).
default_sprite_fps	Frame rate of spritesheets (Sprite2D, Sprite3D).
default_animated_sprite_fps	Frame rate of SpriteFrames animations saved with no speed of their own.
default_video_fps	Frame rate a Portrait_Stop frame counts at, for videos whose frame rate can't be read.
animation_folder_cache	Memory budget (MB) of one animation folder: one that fits stays loaded, one that doesn't is streamed.
animation_folder_stream	How many frames are loaded ahead while an animation folder is streamed.
portrait_w	The width Sprite2D and Sprite3D portraits are scaled to.
portrait_h	The height Sprite2D and Sprite3D portraits are scaled to.

Actor Overrides The following overrides can be assigned to Actors (actors dictionary):

Property	Overrides
ChatPortraitMode	chat_portrait_mode
ChatTextBBCode	chat_text_bbcode
ChatSpeakerBBCode	chat_speaker_bbcode
ChatShowSpeaker	chat_show_speaker
ChatSpeakerPrefix	chat_speaker_prefix
ChatSpeakerSuffix	chat_speaker_suffix
ChatEndOfLineString	chat_end_of_line_string
ChatAdvanceString	chat_advance_string
LexiconChatMode	lexicon_chat_mode
ChatLineScene	chat_line_scene
ChatSpeakerDisplay	chat_speaker_display
ChatPortraitDisplay	chat_portrait_display
ChatAlignment	chat_alignment
ChatKeepPortraitSpace	chat_keep_portrait_space
ChatKeepSpeakerSpace	chat_keep_speaker_space
ChatKeepAlternatePortraitSpace	chat_keep_alternate_portrait_space
ChatKeepAlternateSpeakerSpace	chat_keep_alternate_speaker_space
DialogueMode	dialogue_mode
WritingSpeed	writing_speed
ContinueFastSpeed	continue_fast_speed
ContinueSlowSpeed	continue_slow_speed
SyncWriteSpeedVoice	sync_write_speed_voice
AutoAdvance	auto_advance
AutoAdvancePerCharacter	auto_advance_per_character
EnableVoice	enable_voice
AwaitVoicePlayback	await_voice_playback
TTS	text_to_speech
TTSAdvancedFallback	tts_advanced_fallback
LLM	llm_mode
WriteDialogueHistory	write_dialogue_history

The Actor's DisplayName is the name displayed in the Line's speaker label and at the start of the text, translated into the Engine's current language (see Translating Names). A Line retained in the Chat retains the name it arrived with, even if the language changes later. Portrait Overrides A config.txt file in a portrait file's folder overrides the UI and Engine settings for the files of that folder:

Key	Overrides
extension	The extension settings (default_image_extension, default_sprite_extension, default_animated_sprite_extension, default_video_extension).
fps	The frame rate settings (default_animated_image_fps, default_sprite_fps, default_animated_sprite_fps, default_video_fps).
cache	animation_folder_cache
stream	animation_folder_stream
Files	Settings 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:

Key	Overrides
Portrait_Mode	chat_portrait_mode
Text_BBCode	chat_text_bbcode
Speaker_BBCode	chat_speaker_bbcode
Show_Speaker	chat_show_speaker
Speaker_Prefix	chat_speaker_prefix
Speaker_Suffix	chat_speaker_suffix
End_Of_Line_String	chat_end_of_line_string
Advance_String	chat_advance_string
Lexicon_Mode	lexicon_chat_mode
Line_Scene	chat_line_scene
Speaker_Display	chat_speaker_display
Portrait_Display	chat_portrait_display
Alignment	chat_alignment
Keep_Portrait_Space	chat_keep_portrait_space
Keep_Speaker_Space	chat_keep_speaker_space
Keep_Alternate_Portrait_Space	chat_keep_alternate_portrait_space
Keep_Alternate_Speaker_Space	chat_keep_alternate_speaker_space
Dialogue_Mode	dialogue_mode
Writing_Speed	writing_speed
Continue_Fast_Speed	continue_fast_speed
Continue_Slow_Speed	continue_slow_speed
Sync_Write_Speed_Voice	sync_write_speed_voice
Auto_Advance	auto_advance
Auto_Advance_Per_Character	auto_advance_per_character
Enable_Voice	enable_voice
Await_Voice_Playback	await_voice_playback
TTS	text_to_speech
TTS_Advanced_Fallback	tts_advanced_fallback
LLM	llm_mode
Write_Dialogue_History	write_dialogue_history

Cookie	Duration	Description
cookielawinfo-checkbox-analytics	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Analytics".
cookielawinfo-checkbox-functional	11 months	The cookie is set by GDPR cookie consent to record the user consent for the cookies in the category "Functional".
cookielawinfo-checkbox-necessary	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookies is used to store the user consent for the cookies in the category "Necessary".
cookielawinfo-checkbox-others	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Other.
cookielawinfo-checkbox-performance	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Performance".
viewed_cookie_policy	11 months	The cookie is set by the GDPR Cookie Consent plugin and is used to store whether or not user has consented to the use of cookies. It does not store any personal data.