Candy Logo Copyright © 2025-2026 Candy Arts
Visual Novels
Candy Dialogue Engine can present Dialogues the way Visual Novels do: characters displayed on screen as large images, called busts, who appear, move around, change expressions and leave as the story progresses. VN Mode Visual Novel features are turned on for each Engine by its vn_mode setting (in the Inspector, under Visual Novel Mode). While it's off, the VN commands have no effect. VN mode also changes how other features behave for Actors who have a bust on screen:
  • Portraits: with the "VN" portrait mode, the dialogue box displays no portrait for a speaker whose bust is on screen (see Box Mode).
  • Speech bubbles: Lines in Bubbles mode are displayed in a speech bubble on the speaker's bust (see VN Bubbles Mode).
  • Speaker highlight: the bust of the Actor who is speaking can be highlighted (see Speaker Highlight).
VN Scenes and Busts Busts are displayed in a VN Scene: a UI Element containing bust nodes, the places on screen where Actors can stand. The Engine locates it through busts_path in its ui_elements_paths. How to build a VN Scene, and its settings, are explained in VN Scenes (UI section). Bust nodes are positions, not characters: Dialogues place an Actor on a bust node, and the bust node displays that Actor's files. The same bust node can display Alice in one scene and Bob in the next. See Busts. Bust files Each Actor has a bust folder, named like the Actor Reference: Candy_DE/Media/Actors/Busts/{actor}. What a bust can display depends on its bust node's type: see Media Files. VN Commands Dialogues control busts with the VN commands. Each command can act on several Actors at once, each with its own settings. An Actor can be named directly, or through a Role (see Roles).
CommandPurpose
VN_PlayPlace an Actor on a bust node, or change what their bust displays, and play it.
VN_MoveMove an Actor to another bust node.
VN_SwapSwap the bust nodes of two Actors.
VN_RemoveRemove an Actor from the screen.
VN_WaitWait for a bust's playback.
VN_PausePause a bust.
VN_ResumeResume a paused bust.
VN_SkipMove a bust's playback to another point.
VN_MirrorFlip a bust horizontally or vertically.
VN_StopStop a bust's playback, leaving it on screen.
VN_SceneReplace the whole VN Scene with another one.
VN_Effect_ commandsPlay animations on busts: see Busts.
The UI_Clear command can also remove every Actor at once. Changing Scenes A VN Scene's layout is fixed: its bust nodes retain the size, position and order set in the scene. When a Dialogue needs a different arrangement, the VN_Scene command replaces the whole VN Scene with another one, saved in bust_scenes_folder (Candy_Properties.gd). The Actors on the old scene leave with it: the new scene starts empty. The Engine still locates the new scene at busts_path, and an Engine that owned the old scene owns the new one. A VN_Scene command with an empty Scene removes the VN Scene altogether, with its Actors. A later VN_Scene adds a new one. When the Dialogue Ends By default, every Actor is removed from the VN Scene when the Dialogue ends. The Engine's jml_on_end setting decides whether each one plays their Leave effect first (see JML Effects). To leave the Actors on screen after the Dialogue, turn on the Engine's persistent_busts_on_end setting. The Actors are then still in place for the next Dialogue, which can move or remove them like any other. To remove persistent busts later, from your own game code, call candy_de.clear_busts_ood(engine, method), with the Engine whose VN Scene should be cleared. method is 1 to remove every Actor at once, or 2 to play each one's Leave effect first. Suspension When a Dialogue is suspended (see Suspending Dialogues), its busts pause with it. The Engine's settings decide what pauses:
  • suspend_vn_busts: pause busts at all.
  • suspend_bust_animations: pause the busts' playback.
  • suspend_bust_effects: pause every AnimationPlayer of the VN Scene: effects, JML effects and speaker highlights.
Sharing VN Scenes Several Engines can share the same VN Scene. The scene itself records which Actor is on which bust node, so every Engine using it sees the same Actors. Its Access settings, the same as a media player's (see Media Players), decide which Engines may control it.