Copyright © 2025-2026 Candy ArtsFeatures
A Dialogue is a file of Conversations, each made of Blocks of Lines. Every Line is a Command: speech, media, choices, cutscene direction, logic. Actors are the characters who speak and act. Dialogues are written in Candy Dialogue Creator and are run in your game by Candy Dialogue Engine.
Speech
- Roles: a Line's speaker can be assigned a Role ("companion", "rival") rather than a fixed character. Let your game assign Actors to Roles at runtime.
- Dispositions: Lines can be conditional on the speaker's attitude, relationship or mood.
- Variations: a Line holds several versions of its text. Translations, conditional wording (speaker gender, player class, weather, reputation, any game state), weighted random alternatives, and a text-to-speech version. Conditions combine; the most specific match plays.
- LLM generation: Lines can be generated or rewritten by a language model, which is given the speaker, their dispositions and the written text as context.
- Text variables: display the value of a variable, or the result of an expression, inside the text.
- Word Substitution: replace words based on a character's properties ("he/she", "sorcerer/sorceress"), with a syntax that stays readable in the text:
•He¦°NPC1• said •he¦°NPC2• is coming.→"He said she is coming."Rules can differ per language. - Lexicon: define glossary terms once (names, places, game mechanics), and have them styled, tooltipped or clickable wherever they appear in the text, as whole words in any language, with a plain version for when the Lexicon is off, and text that it leaves alone.
- Rich text: format text with BBCode (colors, fonts, effects, inline images), and write right-to-left languages.
- Settings overrides: Actors, UI Elements and Lines can override display settings.
- Typewriter effect: text can be written progressively at a configurable speed, or displayed instantly.
- Player controls: players can use inputs to speed up, slow down or skip the typewriter effect.
- Voice sync: the writing speed can be fitted to the length of the voice clip.
- Auto-advance: Lines can advance automatically after a configurable delay that can grow with the length of the text, or wait for the voice to finish.
- Text Events: Commands can run when the writing reaches a given point of the text: a pause, a change of speed, a portrait change, a sound effect.
- Indicators: display customizable end-of-line and advance indicators.
- Inline speaker names: the speaker's name can be written inside the text, with its own formatting.
- Box: a dialogue box with name and portrait.
- Subtitles: captions, with the speaker's name inline.
- Chat: a messaging-style history, with channels.
- Bubbles: speech bubbles anchored to characters, in 2D or 3D.
- VN Bubbles: speech bubbles on visual novel sprites.
- Barks: ambient one-liners over NPCs.
- Voice: audio only, nothing displayed.
- Custom modes can be added.
- Channels: a chat can hold several channels, like a messaging app.
- History: the full message history stays scrollable.
- Auto-scroll: the chat follows new messages unless the player has scrolled up.
- Layout: messages can be aligned left, right or alternating, with configurable name and portrait display.
- Persistence: a chat can keep its history across Dialogues, or clear between them.
- Voice files are found automatically for translations and variations, saving the need for tedious manual assignment.
- Positional voice: voices can play from the speaker's position, in 2D or 3D.
- Text-to-speech can be used through the TTS solution of your choice, with an optional dedicated TTS text per Line for precise pronunciation/tone/pace.
- External voice files: voice files can be loaded from outside the build, for DLC, patches or fan dubs.
- Categories: navigable choice categories.
- Outcomes: choices can branch the Dialogue, play a sub-conversation and return to the menu, or end the Dialogue.
- Conditional choices: choices can be hidden, deactivated or disabled based on conditions.
- Timers: countdowns can auto-select a choice or trigger Commands when they run out.
- Live menus: while a menu is open, choices can be shown, hidden, activated, deactivated or relabeled, and timers can be changed.
- Nested menus: menus can nest, with open and close animations.
- Localization: choice texts are localized, and update when the language changes.
- Formats: portraits can be images, animations or videos, in any of the supported display nodes (see Media and Effects below).
- Portrait rules: configure which speakers get a portrait: everyone, the player, or NPCs.
- Speech sync: an animated portrait can play for exactly as long as the Line is spoken, then hold on a chosen frame.
- Animation control: portraits can also play a set number of times, or change mid-Line at a given point of the text.
- Framing: a background, a foreground and effects can be placed around the portrait.
- Playback: play, pause, resume, stop, seek, loop, and change the volume with fades.
- Lines that wait for media: a Line can wait for a sound to end, a video to reach a timestamp, or an animation to complete a number of loops.
- Media that wait for Lines: media can pause while a number of Lines run, then resume on their own.
- Pause loops: paused media can keep looping a segment of themselves (a few bars of music, a breathing animation) instead of freezing.
- Layering: the dialogue UI can be placed above or below the media.
- Display nodes: visual media can be displayed by TextureRect, NinePatchRect, TextureButton (supports hover, pressed and disabled textures), Sprite2D/3D, AnimatedSprite2D/3D and VideoStreamPlayer nodes. This applies to portraits, media players, background layers and VN sprites alike.
- Image sequences and sprite sheets can be played as animations, with no video encoding needed.
- External media: media files can be loaded from outside the build, for DLC or mods.
- Layers: display backgrounds composed of multiple layers, each an image, an animation or a video, with full playback control over every layer.
- Effects: play animated effects on any layer.
- Persistence: backgrounds can stay on screen after the Dialogue ends.
- Character sprites can be shown, animated, moved, swapped, mirrored and removed.
- Join, move and leave effects can play for one character, or for a group of characters entering, moving or leaving together.
- Speaker highlight: the speaking character can be marked with a name tag, an outline, a scale change or an animation.
- Persistence: characters can stay on screen after the Dialogue ends.
- Animations: play animations, or send an animation state machine to a given state.
- Cameras: switch the active camera.
- Lighting: change a light's color and intensity, instantly or over time.
- Staging: move characters and objects to marker nodes, or turn them to face a target, instantly or over time.
- Movement: move characters through your game's own movement systems.
- Scene edits: add scenes to the world, and show, hide or toggle objects (lights, doors, anything with an on/off state).
- Flow control: branch the Dialogue, play a sub-conversation and return to where it left off, or end the Dialogue early.
- Conditions and loops: branch with If, Elif and Else, and repeat with For and While, directly in the Dialogue.
- Game state: read and modify your game's variables and flags, with about 100 operations (arithmetic, text, lists, random values...).
- Code integration: call functions, emit signals, and await signals.
- Actor changes: Actors can be renamed, assigned to Roles, or given new dispositions mid-Dialogue.
- Scoped settings: Engine settings such as the language or display mode can be changed mid-Dialogue, and revert when the Dialogue ends.
- Expressions: any field of any Line can hold a GDScript-style expression instead of a fixed value, evaluated when the Line runs:
¢globals.gold + 10. - File values: Dialogues can read and write values stored in files, which persist between play sessions.
- Character data: keep each character's name, gender, dispositions and any custom properties in one place, available to Lines, conditions and Word Substitution.
- Localization: Lines, names, choices, input prompts and UI texts can be localized, and the language can change at runtime.
- Import and export: Dialogues can export and import data in common formats (JSON, CSV, INI...).
- Dialogue history: keep a log of everything said, for the player to read back.
- Any scene as input: a Dialogue can hand control to any scene and wait for its answer: a text field, a virtual keypad, a lock-picking puzzle, a mini-game, or the game world itself (a duel the player must win before the conversation goes on).
- Two-way communication: the scene can store results in variables, trigger Lines of the Dialogue, suspend the Dialogue, or close itself when done.
- Text input included: a ready-made text input scene, with length limits, allowed characters, per-language word filters and localized error messages.
- Sanitized input: what the player types is displayed exactly as typed, never read as formatting, a keyword, a Text Event or an expression, and any other value from outside the game can be sanitized the same way.
- Entry point: Dialogues can start from any Line.
- Parallel Dialogues: several Dialogues can run at once (main story, ambient barks, a phone chat), each with its own settings, history and language.
- Suspend and resume: Dialogues can be suspended, choosing what freezes with them: writing, timers, voice, media, animations.
- Interruption: Dialogues can be interrupted cleanly at any point, including mid-choice or mid-input.
- Signals are emitted on Dialogue start, end and resume, and on choices and input.
- Default UI: a complete dialogue UI is included: dialogue box, subtitles, chat, choice menus, history, input, backgrounds, VN scenes, 2D and 3D bubbles and barks.
- Customization: every UI element can be redesigned in the Godot editor, without code: only a handful of nodes are required, and the layout and hierarchy around them are free.
- Testing scene: run any Dialogue from any Line in the Godot editor, without playing through the game to reach it.
- Hook functions: run custom code when a Dialogue starts or ends, on each Line, on each choice, as text is written, as media plays, or at many other steps of the dialogue process.
- Custom data: any Line can carry your own data, passed through to your code.
- Drop-in scripts: new Commands, display modes, menu events and data tables are added as scripts, with no registration, and survive updates.
- Fault tolerance: errors in a Dialogue are reported with their Line, and the Dialogue keeps running.
- Self-contained: a single folder, with no plugin dependencies, that works in exported builds.
- Candy Wizard: guided install and update from the Godot editor.
- Safe updates: your data and scenes are never overwritten, modified files are listed before anything changes, and everything is backed up.