Copyright © 2025-2026 Candy ArtsGlossary
The terms this documentation uses, each with the page that explains it. Capitalized terms (Engine, Dialogue, Line, Actor...) are Candy Dialogue Engine's own; in running text, "dialogue" in lowercase means a conversation in the ordinary sense.
Parts of Candy Dialogue Engine
| Term | Meaning |
| Engine | A node with the Candy_Engine.gd script, which loads and runs Dialogues. Its exported variables are the Engine settings. A game can have several Engines. See Engine. |
| Dialogue UI | A scene whose root is an Engine, containing the UI Elements that Engine displays Dialogues in. The default one is Candy_UI.tscn, added to your project as the candy_ui autoload. See UI. |
| UI Element | A scene with one job in a Dialogue UI, with a Candy Dialogue Engine script attached: a dialogue box, subtitles, a chat, a choice menu, an Input Menu, a media player, a Background Scene, a VN Scene. An Engine locates them through its ui_elements_paths and media_players_paths. See UI Elements. |
| Database | The scripts in Scripts/User_Data that contain your game's dialogue data: the Data Tables (actors, roles, flags...), the Localization Tables, and the settings in Candy_Properties.gd. Reached in code through the candy_de autoload. See Database. |
| Candy Wizard | The Godot editor plugin that installs, updates and removes Candy Dialogue Engine, and provides its editor tools (Data, Folders, Test...). See Installation. |
| Candy Dialogue Creator | The standalone application Dialogues are written in, then exported to your project as TXT files. See Candy Dialogue Creator. |
| Safe / unsafe file | A safe file is never overwritten by an update: your own files, and the shipped files meant to be edited (Candy_Properties.gd, the tables, the hook functions, the Default.tscn scenes). Every other shipped file is unsafe: an update replaces it. See Updates. |
| Term | Meaning |
| Dialogue | A TXT file in the Dialogues folder, containing Conversations. An Engine loads one Dialogue at a time. See Dialogue Structure. |
| Conversation | A named part of a Dialogue, containing Blocks. Conversation names are unique within a Dialogue. |
| Block | A named list of Lines inside a Conversation. Lines run in order, and the Dialogue ends after a Block's last Line unless a Transition Command sends it elsewhere. |
| Line | One entry of a Block: a Command with its keys. Lines are counted from 0 within their Block. |
| Command | What a Line does: Spoken_Line, Choice_List, Jump, Media_Play... Each Command is a script in Scripts/Commands. See Lines and Cheat Sheet. |
| Data Key | One setting of a Command, such as a Spoken Line's Portrait. Each Command's page lists its keys and their values. Used interchangeably with 'data field'. |
| Spoken Line | The Command through which an Actor speaks. See Spoken Line. |
| Transition | A move to another Line, Block or Conversation. Jump moves without returning; Bridge runs the target Block and returns, like a function call; Return returns early; End ends the Dialogue. Choices and Conditions transition the same way. See Transition Commands. |
| Line Mark (LM) | A Line with a Reference name, which transitions can target instead of a Line index. See LM. |
| Entry point | The Conversation, Block and Line a Dialogue starts at, passed to start_dialogue(). See Running Dialogues. |
| Parallel Dialogues | Dialogues run at the same time by different Engines. See Parallel Dialogues. |
| Suspend / Interrupt | Suspending freezes a Dialogue until it's resumed; interrupting ends it at once. See Suspending Dialogues and Interrupting Dialogues. |
| Testing Scene | A scene that runs a Dialogue from a chosen Line when it starts, for testing without playing through the game. See Testing Dialogues. |
| Term | Meaning |
| Actor | Anyone or anything that speaks or acts in Dialogues: a character, a narrator, an object. See Actors. |
| Actor Reference | An Actor's key in the actors dictionary (Actors.gd): the name Dialogues use for that Actor, which also names the Actor's media folders. Distinct from the DisplayName shown on screen. |
| Actor property | A value in an Actor's entry: DisplayName, Gender, Disposition, settings that override the Engine's for that Actor's Lines, and any property of your own. See Actor Properties. |
| Player | The Actors listed in player_refs (Player_Refs.gd), where Candy Dialogue Engine treats players and NPCs differently; current_player is the one whose properties Variations check. See Data. |
| Role | A stand-in for an Actor you don't know in advance, such as °companion; the roles dictionary records which Actor currently fills it. See Roles. |
| Disposition | A word describing an Actor's mood, relationship or state ("Friendly", "Hostile"). A Spoken Line with a Disposition condition only plays when the speaker's dispositions match. See Dispositions. |
| Variation | One version of a Spoken Line's text. A Line has one per language, and can have more for conditions (the speaker's gender, a passed tag, a tag script) or random alternatives. See Variations. |
| Tag | A condition in a Variation's name: Default_S=F (the speaker's Gender is F), Default_Shout (the Shout tag is passed). See Variations. |
| Dialogue Mode | How a Spoken Line is displayed: Box, Subtitles, Chat, Bubbles, Barks, Voice, or a mode of your own. Set on the Engine, an Actor or a Line. See Dialogue Modes. |
| Portrait | The image, animation or video displayed beside a Spoken Line in Box and Chat modes, from the speaker's portrait folder. See Dialogue Box. |
| Bust | An Actor's visual novel sprite, displayed in a VN Scene by the VN Commands. See Busts. |
| Bark | A one-liner displayed over an NPC without pausing the Dialogue, in Barks mode. See NPC Barks. |
| Typewriter | The progressive writing of spoken text, at writing_speed characters per second. See Typewriter Effect. |
| Advance | Moving on from a Spoken Line once it's written: on the player's input, or automatically after auto_advance. See Dialogue Advance. |
| End-of-line string | Text appended once a Line is fully written, such as a blinking arrow. See End-Of-Line String. |
| Text variable | A value displayed inside spoken text, between ¤ symbols: ¤¢globals.gold¤. See Displaying Variables. |
| Word Substitution | A word replaced according to an Actor's properties, written •he¦Alice•, with the rules of the substitution_table. See Word Substitution. |
| Lexicon | Keywords of the lexicon dictionary, styled, tooltipped or made clickable wherever they appear in spoken text. See Lexicon. |
| Text Event | A marker in spoken text, ‡boom‡, that runs Commands when the typewriter reaches it. See Text Events. |
| Voice | The audio file, or text-to-speech output, played with a Spoken Line. See Voice. |
| Dialogue history | The log of the Lines spoken so far, which the player can read back. See Dialogue History. |
| Term | Meaning |
| Symbol | A character that designates a kind of value: ¢ an expression, ° a Role, € the variables dictionary, ¤ a text variable, • a Word Substitution, ‡ a Text Event, ¬ a lexicon escape. Set in Candy_Properties.gd. See Symbols. |
| CandyRef expression | A value starting with ¢, written like GDScript and evaluated when the Line runs: ¢globals.gold >= 100. Accepted by almost every key. See CandyRef Expressions. |
| Condition | A ¢ expression that decides whether an If, Elif or While runs its Command. See Condition Commands. |
| Flag | A progression value in the flags dictionary (Flags.gd), set by the Flag command or your code, and tested in conditions. See Flags. |
| Variables dictionary | The variables dictionary (Variables.gd), whose values expressions read with the € symbol: ¢€gold. Optional. See Variables Dictionary. |
| null | In a Line's or an Engine Command's setting, "not set": the Actor, the UI Element or the Engine decides. An empty value is a value of its own. See Cheat Sheet. |
| Override | A setting written at a more specific level than the Engine's: on a UI Element, an Actor or a Line. The most specific level wins. See Cheat Sheet. |
| Term | Meaning |
| Choice menu | The menu a Choice_List line displays, built from a menu scene, category scenes and button scenes. See Choice Menus. |
| Category | A group of choices in a choice menu, with its own title and prompt; a choice can navigate to another category. |
| Input Menu | Any scene an Input line opens and waits for: a text field, a keypad, a mini-game. See Input Menus. |
| Media player | A node that plays images, audio or video for the Media Commands, named in the Engine's media_players_paths. See Media Players. |
| Effect | An animation of an Animation Library, played by an effect player, a background layer or a bust: a screen shake, a fade. See Effect Commands. |
| Background Scene / layer | A scene of layers, each showing an image, animation or video, controlled by the BG Commands. See Background Scenes. |
| VN Scene | A scene of bust nodes, where the VN Commands display Actors' busts. See VN Scenes. |
| Cutscene (CS) Commands | Commands that act on nodes of your game rather than on UI Elements: animations, cameras, lights, positions, movement. See Cutscene Commands. |
| Private / Public | A media player's, Background Scene's or VN Scene's access: Private obeys only the Engine that owns it, Public obeys any Engine. See Media Players. |
| Animation Folder | A folder of numbered images played as an animation, without video encoding. See Media Files. |
| Term | Meaning |
| Hook function | A function Candy Dialogue Engine calls at a given step (a Dialogue starts, a Line is written, a choice is picked...), empty until you write code in it. Global ones are scripts in User_Data/Functions; UI Element ones are in the UI Element's script. See Hook Functions. |
| candy_args, user_args, custom_data | The three arguments of every hook function: Candy Dialogue Engine's values, your own from the hook_arguments table, and the Line's Custom Data. |
| Custom Data | Numbered values (Custom_1, Custom_2...) that every Line and entry can carry in Candy Dialogue Creator, which Candy Dialogue Engine never reads and passes to your code. See UI Elements, under Hook Functions. |
| Drop-in script | A script that becomes a Command, Dialogue Mode, event, tag or table by being saved in the right folder, with no registration. See Code Modification. |
| Game state | Your game's own notion of what the player is doing, which the change_game_state() hook switches to a dialogue state while a Dialogue runs. See Game State. |