Actor Properties – Candy Dialogue Engine

Actor Properties

This page lists every property an Actor can be assigned in the actors dictionary.

A null value or a missing key is ignored. An empty String is a value like any other: on a text property, it means no text (an empty BoxSpeakerBBCode removes the wrap, for example); on a number or true/false property, it is reported as invalid and ignored.
An Actor's entry doesn't need every key: a missing property is ignored.
Custom keys are accepted, and some features can be configured to read them.
Most properties override Engine and UI settings, and Dialogue Commands override Actor properties in turn.

Most keys override an Engine setting for the Lines this Actor speaks. A null value (or a missing key) leaves the setting to the UI Element and the Engine. A value overrides both, and a Line's own key overrides the Actor's in turn. The Overrides row names the Engine setting each key overrides. Identity These keys describe the Actor. They are not settings, so there is no Engine setting to override. DisplayName

Type	String
Values	Any text.
Purpose	The name displayed on screen when the Actor speaks. If DisplayName is empty, the Actor Reference is displayed instead. Write it in the Default language: it is translated through the display_names table each time it is displayed (see Translating Names).

ShortName

Type	String
Values	Any text.
Purpose	The name displayed by a text variable whose reference is only an Actor Reference, with no property key: the ShortName is displayed rather than the Actor's entire dictionary. If ShortName is empty, the DisplayName is displayed instead; if that's also empty, the Actor Reference is displayed. Like DisplayName, it is written in the Default language and translated through display_names.

Gender

Type	String
Values	Any text.
Purpose	Selects the gendered Variations of a Spoken Line.

Disposition

Type	String
Values	Dispositions separated by commas (,).
Meaning	Makes Spoken Lines conditional. A disposition can represent anything: a relationship status, a mood, a need, a preference...

Variation tags These keys force Variation tags to pass or fail for the Lines this Actor speaks (see Variations). A Line's Passed_Tags and Disabled_Tags override them in turn. PassedTags

Type	Array
Values	Tag names, e.g. `["Shout"]`. An empty Array sets nothing.
Overrides	passed_tags
Meaning	Tags that pass whatever their value. A bare tag such as Shout only passes when it's listed here, on the Line or on the Engine.

DisabledTags

Type	Array
Values	Tag names, e.g. `["S"]`. An empty Array sets nothing.
Overrides	disabled_tags
Meaning	Tags that always fail: Variations containing them are never picked for this Actor's Lines.

All dialogue modes Settings that apply whichever Dialogue Mode the Actor's Line is displayed in. null leaves the setting to the UI Element and the Engine. DialogueMode

Type	String
Values	"Box", "Subtitles", "Chat", "Bubbles", "Barks", "Voice", or the name of a mode of your own (a script in Candy_DE/Scripts/Dialogue_Modes). "VN_Bubbles" is also accepted, but don't assign it: the Engine switches Bubbles lines to it in VN mode.
Overrides	dialogue_mode
Meaning	The mode this Actor's Lines are displayed in. Ignored if no UI Element can display that mode.

EnableVoice

Type	Bool
Values	true or false
Overrides	enable_voice
Meaning	Whether this Actor's Lines play a voice.

AwaitVoicePlayback

Type	Bool
Values	true or false
Overrides	await_voice_playback
Meaning	Whether the dialogue waits for the voice to finish before it can advance.

TTS

Type	String
Values	"Off", "Simple", "Advanced", or a TTS mode of your own (see TTS)
Overrides	text_to_speech
Meaning	How this Actor's Lines are spoken by text-to-speech.

TTSAdvancedFallback

Type	String
Values	"Off", "Simple", or a TTS mode of your own
Overrides	tts_advanced_fallback
Meaning	The text-to-speech mode used when "Advanced" is not available.

LLM

Type	Boolean
Values	true or false
Overrides	llm_mode
Meaning	Whether this Actor's Lines go through the LLM.

WritingSpeed

Type	Number
Values	Characters per second. 0 writes the line instantly
Overrides	writing_speed
Meaning	Typewriter speed.

ContinueFastSpeed

Type	Number
Values	Characters per second
Overrides	continue_fast_speed
Meaning	Typewriter speed while the player holds the speed-up input.

ContinueSlowSpeed

Type	Number
Values	Characters per second
Overrides	continue_slow_speed
Meaning	Typewriter speed while the player holds the slow-down input.

SyncWriteSpeedVoice

Type	Boolean
Values	true or false
Overrides	sync_write_speed_voice
Meaning	Whether the typewriter speed is matched to the length of the voice playback.

AutoAdvance

Type	Number
Values	Seconds. -1 for manual advance only
Overrides	auto_advance
Meaning	The delay before the dialogue advances on its own.

AutoAdvancePerCharacter

Type	Number
Values	Seconds per character. 0 for none
Overrides	auto_advance_per_character
Meaning	Seconds added to the auto-advance delay for each character the Line displays. Ignored when the auto-advance delay is -1.

WriteDialogueHistory

Type	Boolean
Values	true or false
Overrides	write_dialogue_history
Meaning	Whether this Actor's Lines are written to the dialogue history.

Box mode Read when the Line is displayed in the dialogue box. BoxPortraitMode

Type	Text
Values	"Off", "All", "Player", "NPC" or "VN"
Overrides	box_portrait_mode
Meaning	Which speakers receive a portrait.

BoxTextBBCode

Type	Text
Values	Opening BBCode tags
Overrides	box_text_bbcode
Meaning	Wraps the Line's text. Write the opening tags only, such as `[color=#ff8080][i]`: Candy Dialogue Engine adds the closing ones.

BoxSpeakerBBCode

Type	Text
Values	Opening BBCode tags
Overrides	box_speaker_bbcode
Meaning	Wraps the speaker's name. An empty text means no wrap, even if the Engine or the UI Element sets one.

BoxShowSpeaker

Type	Boolean
Values	true or false
Overrides	box_show_speaker
Meaning	Whether the speaker's name is written at the start of the text.

BoxSpeakerPrefix

Type	Text
Values	Any text
Overrides	box_speaker_prefix
Meaning	Written before the speaker's name.

BoxSpeakerSuffix

Type	Text
Values	Any text
Overrides	box_speaker_suffix
Meaning	Written after the speaker's name.

BoxEndOfLineString

Type	Text
Values	Any text. Supports BBCode
Overrides	box_end_of_line_string
Meaning	Displayed at the end of the Line, before the dialogue advances.

BoxAdvanceString

Type	Text
Values	Any text. Supports BBCode
Overrides	box_advance_string
Meaning	Displayed at the end of the Line, after the dialogue advances.

BoxSelfClear

Type	Boolean
Values	true or false
Overrides	box_self_clear
Meaning	Whether the dialogue box clears itself when the dialogue advances.

BoxPortraitSelfClear

Type	Boolean
Values	true or false
Overrides	box_portrait_self_clear
Meaning	Whether the portrait clears itself when the dialogue advances.

LexiconBoxMode

Type	Boolean
Values	true or false
Overrides	lexicon_box_mode
Meaning	Whether Lexicon terms are enabled in the dialogue box.

Subtitles mode Read when the Line is displayed as subtitles. SubtitlesTextBBCode

Type	Text
Values	Opening BBCode tags
Overrides	subtitles_text_bbcode
Meaning	Wraps the Line's text.

SubtitlesSpeakerBBCode

Type	Text
Values	Opening BBCode tags
Overrides	subtitles_speaker_bbcode
Meaning	Wraps the speaker's name.

SubtitlesShowSpeaker

Type	Boolean
Values	true or false
Overrides	subtitles_show_speaker
Meaning	Whether the speaker's name is written at the start of the text.

SubtitlesSpeakerPrefix

Type	Text
Values	Any text
Overrides	subtitles_speaker_prefix
Meaning	Written before the speaker's name.

SubtitlesSpeakerSuffix

Type	Text
Values	Any text
Overrides	subtitles_speaker_suffix
Meaning	Written after the speaker's name.

SubtitlesEndOfLineString

Type	Text
Values	Any text. Supports BBCode
Overrides	subtitles_end_of_line_string
Meaning	Displayed at the end of the Line, before the dialogue advances.

SubtitlesAdvanceString

Type	Text
Values	Any text. Supports BBCode
Overrides	subtitles_advance_string
Meaning	Displayed at the end of the Line, after the dialogue advances.

SubtitlesSelfClear

Type	Boolean
Values	true or false
Overrides	subtitles_self_clear
Meaning	Whether the subtitles clear themselves when the dialogue advances.

LexiconSubtitlesMode

Type	Boolean
Values	true or false
Overrides	lexicon_subtitles_mode
Meaning	Whether Lexicon terms are enabled in subtitles.

Chat mode Read when the Line is displayed in the Chat. ChatPortraitMode

Type	Text
Values	"Off", "All", "Player", "NPC" or "VN"
Overrides	chat_portrait_mode
Meaning	Which speakers receive a portrait.

ChatLineScene

Type	Text
Values	A scene path, or a file name in the chat lines folder
Overrides	chat_line_scene
Meaning	The Chat_Line scene this Actor's Lines use, e.g. res://My_Game/Chat_Lines/Alice.tscn.

ChatSpeakerDisplay

Type	Text
Values	"Every_Line" or "Speaker_Change"
Overrides	chat_speaker_display
Meaning	When a Line displays the speaker's name: on every Line, or only on the first of several Lines in a row from the same speaker.

ChatPortraitDisplay

Type	Text
Values	"Every_Line", "Speaker_Change" or "Speaker_Or_Portrait_Change"
Overrides	chat_portrait_display
Meaning	When a Line displays the speaker's portrait: on every Line, when the speaker changes, or also when the same speaker's portrait changes.

ChatAlignment

Type	Text
Values	"Left", "Right" or "Alternate"
Overrides	chat_alignment
Meaning	Which side of the text the portrait and name are on; the text aligns to the same side. "Alternate" switches sides when the speaker changes.

ChatKeepPortraitSpace

Type	Boolean
Values	true or false
Overrides	chat_keep_portrait_space
Meaning	Reserves the space of a portrait that isn't displayed on this Line, so that texts line up.

ChatKeepSpeakerSpace

Type	Boolean
Values	true or false
Overrides	chat_keep_speaker_space
Meaning	Reserves the space of a name label that isn't displayed on this Line.

ChatKeepAlternatePortraitSpace

Type	Boolean
Values	true or false
Overrides	chat_keep_alternate_portrait_space
Meaning	Reserves the space of the portrait on the other side of the text.

ChatKeepAlternateSpeakerSpace

Type	Boolean
Values	true or false
Overrides	chat_keep_alternate_speaker_space
Meaning	Reserves the space of the name label on the other side of the text.

ChatTextBBCode

Type	Text
Values	Opening BBCode tags
Overrides	chat_text_bbcode
Meaning	Wraps the Line's text.

ChatSpeakerBBCode

Type	Text
Values	Opening BBCode tags
Overrides	chat_speaker_bbcode
Meaning	Wraps the speaker's name.

ChatShowSpeaker

Type	Boolean
Values	true or false
Overrides	chat_show_speaker
Meaning	Whether the speaker's name is written at the start of the text.

ChatSpeakerPrefix

Type	Text
Values	Any text
Overrides	chat_speaker_prefix
Meaning	Written before the speaker's name.

ChatSpeakerSuffix

Type	Text
Values	Any text
Overrides	chat_speaker_suffix
Meaning	Written after the speaker's name.

ChatEndOfLineString

Type	Text
Values	Any text. Supports BBCode
Overrides	chat_end_of_line_string
Meaning	Displayed at the end of the Line, before the dialogue advances.

ChatAdvanceString

Type	Text
Values	Any text. Supports BBCode
Overrides	chat_advance_string
Meaning	Displayed at the end of the Line, after the dialogue advances.

LexiconChatMode

Type	Boolean
Values	true or false
Overrides	lexicon_chat_mode
Meaning	Whether Lexicon terms are enabled in the Chat.

Bubbles mode Read when the Line is displayed in speech bubbles, VN_Bubbles included. BubblesExemptMode

Type	Text
Values	"Box", "Subtitles", "Chat", "Bubbles", "Barks", "Voice", or the name of a mode of your own (a script in Candy_DE/Scripts/Dialogue_Modes). "VN_Bubbles" is also accepted, but don't assign it: the Engine switches Bubbles lines to it in VN mode.
Overrides	bubbles_exempt_mode
Meaning	The mode used when this Actor has no speech bubble, or isn't present on screen.

BubblesTextBBCode

Type	Text
Values	Opening BBCode tags
Overrides	bubbles_text_bbcode
Meaning	Wraps the Line's text.

BubblesEndOfLineString

Type	Text
Values	Any text. Supports BBCode
Overrides	bubbles_end_of_line_string
Meaning	Displayed at the end of the Line, before the dialogue advances.

BubblesAdvanceString

Type	Text
Values	Any text. Supports BBCode
Overrides	bubbles_advance_string
Meaning	Displayed at the end of the Line, after the dialogue advances.

LexiconBubblesMode

Type	Boolean
Values	true or false
Overrides	lexicon_bubbles_mode
Meaning	Whether Lexicon terms are enabled in speech bubbles.

Barks mode Read when the Line is displayed as a bark. BarksTextBBCode

Type	Text
Values	Opening BBCode tags
Overrides	barks_text_bbcode
Meaning	Wraps the Line's text.

BarksEndOfLineString

Type	Text
Values	Any text. Supports BBCode
Overrides	barks_end_of_line_string
Meaning	Displayed at the end of the Line, before the dialogue advances.

BarksAdvanceString

Type	Text
Values	Any text. Supports BBCode
Overrides	barks_advance_string
Meaning	Displayed at the end of the Line, after the dialogue advances.

LexiconBarksMode

Type	Boolean
Values	true or false
Overrides	lexicon_barks_mode
Meaning	Whether Lexicon terms are enabled in barks.

Voice mode Read when the Line is only voiced. LexiconVoiceMode

Type	Boolean
Values	true or false
Overrides	lexicon_voice_mode
Meaning	Whether Lexicon terms are enabled in Voice mode.

VN busts The animation played on this Actor's bust. It overrides the general and VN scene settings, unless it is ["", ""]. VNJoinEffect

Type	Array
Values	An array of two texts: `["Method", "Value"]`, e.g. `["Animation", "Fade Out"]`. `["", ""]` sets nothing.
Overrides	Nothing: not a setting.
Meaning	Played when the Actor joins the scene.

VNMoveFromEffect

Type	Array
Values	An array of two texts: `["Method", "Value"]`, e.g. `["Animation", "Fade Out"]`. `["", ""]` sets nothing.
Overrides	Nothing: not a setting.
Meaning	Played on the bust the Actor moves away from.

VNMoveToEffect

Type	Array
Values	An array of two texts: `["Method", "Value"]`, e.g. `["Animation", "Fade Out"]`. `["", ""]` sets nothing.
Overrides	Nothing: not a setting.
Meaning	Played on the bust the Actor moves to.

VNLeaveEffect

Type	Array
Values	An array of two texts: `["Method", "Value"]`, e.g. `["Animation", "Fade Out"]`. `["", ""]` sets nothing.
Overrides	Nothing: not a setting.
Meaning	Played when the Actor leaves the scene.