Candy Logo Copyright © 2025-2026 Candy Arts
Cheat Sheet
What is looked up most often, on one page. Each section links to the page that explains it in full. The meaning of each term is in the Glossary. Symbols The defaults, which can be modified in Candy_Properties.gd (see Symbols).
SymbolMeaningExample
¢The value is an expression, evaluated when the Line runs.¢globals.gold + 10
¢¢A value that starts with a literal ¢.¢¢50
°A Role: the Actor currently assigned to it.°companion
€In an expression, a value of the variables dictionary.¢€score
¤ … ¤In spoken text, displays a variable.You have ¤¢globals.gold¤ coins.
• … ¦ … •In spoken text, a Word Substitution: keyword, then Actor.Have you seen •him¦Alice•?
‡ … ‡In spoken text, a Text Event: runs Commands when the writing reaches it.Wait‡boom‡... what?
¬ … ¬In spoken text, text the Lexicon never formats. The symbols aren't displayed.¬Alice¬ is just a name here.
In spoken text, ¤¤, ••, ‡‡ and ¬¬ display a single ¤, •, ‡ or ¬. A spoken text that starts with ¢ is an expression as a whole. See CandyRef Expressions, Roles, Variables Dictionary, Displaying Variables, Word Substitution, Text Events and Lexicon. Values
ValueMeaning
1 / 0On / off.
nullNo override: the Actor, the UI Element or the Engine decides. Used by the settings of a Spoken Line and of the Engine Commands.
EmptyA value of its own, not "no override": an empty text, no effect, the default language...
¢...An expression, accepted by almost every key.
globals.hpA variable to write to, a signal or a function is named without ¢ (Set, Call, Emit, Await...).
Command names aren't case-sensitive. Keys are, and so are Actor References, Variation names, Dispositions and Line Marks. Settings are decided from the most general to the most specific, the most specific winning: Candy_Properties.gd → Engine → UI Element → Actor → Line. The Engine's settings are the exported variables of the Engine node (the one with Candy_Engine.gd), in the Inspector; a UI Element's are those of its root node. Speakers and Targets
WrittenMeaning
AliceAn Actor Reference: a key of the actors dictionary.
°companionThe Actor assigned to the companion Role.
¢globals.current_npcAn expression that returns an Actor Reference.
Variation Names Parts are separated by underscores, the language first (see Variations).
NameDisplayed when
DefaultThe current language is the original one, and nothing more specific fits.
FrenchThe current language is French.
Default_P=FThe player character's Gender is F.
Default_S=FThe speaker's Gender is F.
Default_ShoutShout is listed as a passed tag (Engine, Actor or Line).
Default_#2Picked at random among the numbered alternatives.
Default_TTSNever displayed: the text read by text-to-speech. Always the last part.
A Line with no Variation in the current language is skipped. A Variation with an empty text is ignored. Dispositions A Spoken Line's Disposition is checked against the speaker's dispositions (see Dispositions).
ConditionPasses when
EmptyAlways.
Friendly, HappyThe speaker has at least one of them.
+Friendly, HappyThe speaker has all of them.
-Friendly, HappyThe speaker has no disposition outside the list.
=Friendly, HappyThe speaker has exactly the list.
!Angry, SadThe speaker has none of them.
(2)Friendly, Tired, HappyThe speaker has exactly 2 of them. +(2): 2 or more. -(2): fewer than 2.
Time
WrittenMeaning
2.5Seconds.
01:30.5A timestamp: SS.xx, MM:SS.xx or HH:MM:SS.xx.
f=120A frame, where the media has frames (not audio).
+2, -00:01.5Relative, in the Skip commands and pause loops: forward or back by that much.
f+10, f-10Relative, in the same places: forward or back by that many frames.
Playing and Waiting These keys work the same way in the Play, Wait, Pause and Stop commands of every family (Media, Effect, BG, VN, CS).
KeyValues
Loops1 or empty: play once. N: play N times. 0: hold the first frame without playing. Negative: loop forever.
DurationA time played on top of the loops, so playback can end part-way through one. Empty or 0: Loops alone decides.
Wait_LoopsThe number of completed loops the Dialogue waits for before moving on.
Wait_TimeExtra time the Dialogue waits, into the next loop. With both at 0, the Dialogue doesn't wait.
Lines (Pause)N: resume by itself after N Lines. 0 or less: stay paused until the Resume command.
All (Pause)0: only displayed Spoken Lines count. 1: every Line counts.
Stop_Frame (Stop)0: stop on the current frame. -1: the last frame. N: frame N, counted from 1. Clear: clear the media (not on BG_Stop and VN_Stop: use the Remove commands).
Stop_Frame (Play)Where playback ends by itself, once its Loops and Duration are played, with the same values.
Loops, Duration (Stop)Stop once the playback has played that long, counted from its start, rather than at once. Both empty: stop at once.
Z-Order
WrittenMeaning
150Exactly that Z index.
+1, -1The reference node's Z index, plus or minus that number.
ResetBack to the node's default_z.
EmptyLeft as it is.
Transitions Jump, Bridge and choices name their target with three keys:
KeyValues
ConversationEmpty: the current one.
BlockEmpty: the current one.
LineA Line index, counted from 0, or the Reference of an LM command in the target Block.
A target that doesn't exist ends the Dialogue. Return's Levels: N returns from N Bridges, 0 from all of them, to the main Block, and -N ends the Dialogue if there are fewer than N. A Dialogue ends after the last Line of a Block: it doesn't continue to the next Block by itself. Files
WrittenMeaning
HappyA file name, looked up in the folder of its kind, with the default extension (see Media Files).
res://..., user://...A full path, for a file stored anywhere else.
Commands
GroupCommands
SpeechSpoken_Line: an Actor speaks.
EngineEngine_Language, Dialogue_Mode, Engine_Writing: change the Engine's language, Dialogue Mode and typewriter settings.
UIWait (pause for a time), UI_Clear (hide and clear UI Elements), UI_Z (change a UI Element's Z-order).
ControlCall (function), Emit and Await (signal), Set (variable), Flag, Name, Role, Disposition, Export and Import (variables to and from a file).
TransitionJump (move to a Line), Bridge (move, then return), Return (return early), End, LM (a named Line to target).
Text EventWrite_Speed (writing speed), Write_Pause (pause the writing), Line_Portrait (the Line's portrait): only inside a Text Event, while a Line is written.
ConditionIf, Elif, Else, For, While: run one Command when a condition is true, or repeatedly.
InputPlayer_Advance (wait for the advance input), Mouse (mouse mode), Input (open an Input Menu).
ChoiceChoice_List (display a choice menu), Choice_Status and Timer_Status (change the choices and timers of an open menu).
MediaMedia_Play, Media_Wait, Media_Pause, Media_Resume, Media_Skip, Media_Volume, Media_Stop: images, audio and video in media players.
EffectEffect_Play, Effect_Wait, Effect_Pause, Effect_Resume, Effect_Skip, Effect_Stop: animations in effect players.
BackgroundBG_Scene, BG_Play, BG_Wait, BG_Pause, BG_Resume, BG_Skip, BG_Mirror, BG_Stop, BG_Remove, and the same six as Effect, named BG_Effect_: background layers and their effects.
Visual NovelVN_Scene, VN_Play, VN_Move, VN_Swap, VN_Wait, VN_Pause, VN_Resume, VN_Skip, VN_Mirror, VN_Stop, VN_Remove, and the same six as Effect, named VN_Effect_: Actor busts and their effects.
CutsceneCS_Scene, CS_Visible, CS_Position, CS_Look, CS_Cam, CS_Light, CS_Toggle, CS_Move, and Play, Wait, Pause, Resume, Skip and Stop for CS_Sprite_ and CS_Anim_: nodes of your game.
OtherCustom (run your own code), Comment (a note, which does nothing).
Code Called on an Engine node, such as the candy_ui autoload:
CodeEffect
load_scripted_dialogue("dialogue_1")Loads dialogue_1.txt from the Dialogues folder.
start_dialogue("Conversation_1", "Block_1", 0)Starts the loaded Dialogue. The Line can also be a Line Mark's Reference.
suspend_dialogue(), resume_dialogue()Freezes the Dialogue, and resumes it.
await interrupt_dialogue()Ends the Dialogue at once.
dialogue_fully_endedThe signal emitted once a Dialogue has ended and everything is cleaned up.
The Database is read and written through the candy_de autoload: candy_de.actors, candy_de.roles, candy_de.flags, candy_de.variables... See Running Dialogues, Suspending Dialogues, Interrupting Dialogues and Ending Dialogues.