Candy Logo Copyright © 2025-2026 Candy Arts
Lines
Lines decide what a Dialogue does. Each Line is one kind of action or event, among the following: Spoken Lines A Spoken Line makes an Actor speak. Its data contains: - The speaker. - The spoken text to display, or an expression whose result is displayed. - A portrait to display (in the Dialogue Modes that display one), with animation options. - A voice file to play. - A disposition, which makes the Line conditional on the speaker's own disposition. Override options also allow a Spoken Line to decide the Dialogue Mode it's displayed in, the color of its text, and more. A Spoken Line can also contain Variations: alternate texts, displayed according to the game's language, to speaker or player properties (customizable), or picked at random for variety. Engine Commands Engine Commands modify the Engine's own settings: - Engine Language: modifies the Engine's language. - Dialogue Mode: modifies the Engine's Dialogue Mode. - Engine Writing: modifies the typewriter settings. An Engine Command offers to revert its change when the Dialogue ends, so that the Engine returns to its previous values for the next Dialogue. Engine Language modifies the Engine's language, not the general language of Candy_Properties.gd. UI Commands UI Commands act on the Dialogue UI: - Wait: pauses the processing of Lines for a duration. - UI Clear: hides UI Elements and clears their content. - UI Z: modifies the Z order of a UI Element, to layer it above or below other UI Elements or nodes. The Wait command doesn't pause the media or animations previously started by other Commands: it only delays the next Line. For a real pause, see Suspending Dialogues. Control Commands Control Commands act on your game code: - Call: calls functions. - Emit: emits signals. - Await: awaits signals. - Set: modifies variables. - Flag: modifies progression flags. - Name: modifies Actor names (or other properties). - Role: assigns Actors to Roles. - Disposition: modifies Actor Dispositions. - Export: exports variables to external files. - Import: imports variable values from external files. Call, Emit, Await and Set reach any function, signal or variable of your code, native Godot functions, signals and properties included. Together, they allow a Dialogue to do anything your game can. Flag, Name, Role and Disposition are shorter forms of what Set already does. Export and Import save and load game data: a minimal save and load system driven from Dialogues. They also serve to declare new variables at runtime. Transition Commands Transition Commands move the Dialogue from Line to Line: - Jump: moves the Dialogue permanently to another Conversation, Block or Line. - Bridge: moves the Dialogue temporarily to another Conversation, Block or Line. - Line Mark (LM): marks a Line, so that transitions target it by name instead of by index. - Return: returns from one or more Bridge commands. - End: ends the Dialogue. Condition Commands Condition Commands come in two kinds: - If/Elif/Else conditions. - For/While loops. Their conditions are CandyRef Expressions, so almost any condition GDScript accepts is accepted here. When its condition is true, a Condition Command runs one Command of your choice instead of code. To run several Commands, have the Condition Command run a Bridge or a Jump to a Block that contains them. Input Commands Input Commands handle player input: - Mouse: changes the current mouse mode. - Player Advance: pauses the processing of Lines until the player provides an input (a key or a button). - Input: opens an Input Menu, which accepts any kind of input and reports back to the Engine through a signal. The Input command works with any scene and any input. A few examples: - A text prompt that asks the player to type their name. - A virtual keypad, where the player enters a code by clicking buttons. - A UI with buttons, sliders, rotating knobs or drag-and-drop elements. - A puzzle or a mini-game. - The game itself, where player actions and game events report back to the Dialogue. The signals carry any arguments, and your own code decides how the Dialogue reacts to them. Some examples: - Store the player's chosen name, and close the Input Menu. - Play music when a puzzle is solved. - Have a character congratulate the player when they score points in a mini-game. A basic Input Menu template is provided, which acts as a text input prompt, but Input Menus are meant to be designed by you - both their UI and their code. Choice Commands Choice Commands display choices to the player, and configure them: - Choice List: displays a Choice Menu, with its choices. - Choice Status: modifies the choices of an open Menu. - Timer Status: modifies the timers of an open Choice Menu. A Choice Menu is entirely built within the Choice List command, without extra code. A simple menu with a few choices is written in a minute, and advanced options are available: - Choices sorted into categories, which the player navigates. - A different scene for each category and choice. - Hidden or inactive conditional choices. - Timers, which trigger effects or auto-select a choice. - Repeatable choices, and multiple choice selection. - And more. A selected choice moves the Dialogue to another Conversation, Block or Line, where Commands produce its effects. A choice also calls customizable hook functions, for effects written in code. Lastly, a choice reports back to the Engine through a signal, which can be customized to add any behaviour your code provides. Effect Commands Effect Commands play and control animations, through AnimationPlayers: - Effect Play: plays effects. - Effect Wait: makes the Dialogue wait until effects reach a frame or timestamp. - Effect Pause: pauses effects until a number of Lines have run, or until an Effect Resume command. - Effect Resume: resumes paused effects. - Effect Skip: moves effects to a frame or timestamp. - Effect Stop: stops effects. Effects are meant for visual effects on screen, but they can animate anything an AnimationPlayer animates, characters included. Media Commands Media Commands play, display and control image, audio and video media, through several kinds of nodes: - Media Play: plays media. - Media Wait: makes the Dialogue wait until media reach a frame or timestamp. - Media Pause: pauses media until a number of Lines have run, or until a Media Resume command. - Media Resume: resumes paused media. - Media Skip: moves media to a frame or timestamp. - Media Volume: adjusts the media volume. - Media Stop: stops media. Background Commands Background Commands display and control backgrounds. A background is displayed by a Background Scene: a scene made of nodes that display images or videos, so that a background can be composed of several layers. Background Commands resemble Media Commands: - BG Scene: loads, replaces or removes a Background Scene. - BG Play: displays an image in a layer, and optionally animates it. - BG Wait: makes the Dialogue wait until animated layers reach a frame or timestamp. - BG Pause: pauses layers until a number of Lines have run, or until a BG Resume command. - BG Resume: resumes paused layers. - BG Skip: moves layers to a frame or timestamp. - BG Mirror: mirrors layers on any of their axes. - BG Stop: stops animated layers. - BG Remove: removes the image or video of layers. Background layers are also animated by AnimationPlayers, for visual effects, through a second set of Commands: - BG Effect Play: plays effects on layers. - BG Effect Wait: makes the Dialogue wait until effects reach a frame or timestamp. - BG Effect Pause: pauses effects until a number of Lines have run, or until a BG Effect Resume command. - BG Effect Resume: resumes paused effects. - BG Effect Skip: moves effects to a frame or timestamp. - BG Effect Stop: stops effects. Visual Novel Commands Visual Novel Commands display and control Actor Busts (visual novel sprites) on screen. Busts are displayed by a VN Scene: a scene made of nodes that display the images or videos of Actor Busts. VN Scenes and Commands resemble Backgrounds, with a few additions: - A Bust node is assigned an Actor (and which of its Bust images to display), rather than an image. - A VN Command names the Actors it acts on, and the Engine locates their Bust nodes, so Bust node names and assignments needn't be remembered. - When an Actor speaks, their portrait can be left out if they already have a Bust on screen. - Visual effects can mark the Bust of the speaking Actor. - Tweens or animations can play automatically when an Actor's Bust appears, moves to another node, or is removed from the Scene (see JML Effects). VN Commands resemble Background Commands: - VN Scene: loads, replaces or removes a VN Scene. - VN Play: displays an image in a Bust node, and optionally animates it. - VN Move: moves an Actor from one Bust node to another. The Actor continues to display and play what it was. - VN Swap: swaps the Bust nodes of two Actors. Both continue to display and play what they were. - VN Wait: makes the Dialogue wait until animated Busts reach a frame or timestamp. - VN Pause: pauses Busts until a number of Lines have run, or until a VN Resume command. - VN Resume: resumes paused Busts. - VN Skip: moves Busts to a frame or timestamp. - VN Mirror: mirrors Busts on any of their axes. - VN Stop: stops animated Busts. - VN Remove: removes the image or video of Busts. Busts are also animated by AnimationPlayers, for visual effects, through a second set of Commands: - VN Effect Play: plays effects on Busts. - VN Effect Wait: makes the Dialogue wait until effects reach a frame or timestamp. - VN Effect Pause: pauses effects until a number of Lines have run, or until a VN Effect Resume command. - VN Effect Resume: resumes paused effects. - VN Effect Skip: moves effects to a frame or timestamp. - VN Effect Stop: stops effects. Cutscene Commands Cutscene Commands act on nodes anywhere in your game, typically in the game world, to direct live cutscenes: - CS Scene: instantiates scenes as children of any node. - CS Visible: changes the visible property of nodes. - CS Position: moves and rotates nodes to the position and rotation of marker nodes. - CS Look: rotates nodes to face other nodes, or to face away from them. - CS Cam: changes the active camera. - CS Light: changes the energy and color of Light nodes. - CS Toggle: calls a method of your own on nodes, such as one that turns their properties on or off. - CS Move: sets nodes in motion. Each movement is a script of your own: Candy Dialogue Engine can't know how your game moves its characters. A second set of Commands animates Sprites and AnimatedSprites, such as the characters of a 2D game: - CS Sprite Play: assigns a sprite file, and optionally plays an animation. - CS Sprite Wait: makes the Dialogue wait until animated sprites reach a frame or timestamp. - CS Sprite Pause: pauses sprites until a number of Lines have run, or until a CS Sprite Resume command. - CS Sprite Resume: resumes paused sprites. - CS Sprite Skip: moves sprite animations to a frame or timestamp. - CS Sprite Stop: stops sprite animations. A third set animates nodes through AnimationPlayers, such as the character meshes of a 3D game: - CS Anim Play: plays an animation. - CS Anim Wait: makes the Dialogue wait until an animation reaches a frame or timestamp. - CS Anim Pause: pauses animations until a number of Lines have run, or until a CS Anim Resume command. - CS Anim Resume: resumes paused animations. - CS Anim Skip: moves animations to a frame or timestamp. - CS Anim Stop: stops animations. CS Commands target the game world, not the UI Elements of the Engine running the Dialogue. The Dialogue therefore controls the nodes CS Commands target less closely than it controls its own UI Elements.