Candy Logo Copyright © 2025-2026 Candy Arts
VN Scenes
A VN Scene displays Visual Novel busts: Actors shown on screen, at positions called bust nodes. How busts are used in Dialogues is explained in Visual Novels.
  • Script: VN_UI.gd
  • Templates: Scenes/VN_Scenes
  • Updates: the script is 'unsafe', and so is every template except Default.tscn (see Customizing UI Elements, on the UI page)
  • Engine path: busts_path in ui_elements_paths
  • Location: in Candy_UI.tscn, a child of VN_Layer, a CanvasLayer drawn in front of the 2D game world and behind the other UI Elements (see Drawing Order, on the UI page)
  • Files: see Media Files
The VN_Scene command replaces the VN Scene with another one, looked up in bust_scenes_folder (Candy_Properties.gd). Save your VN Scenes there. The new scene is instantiated as a child of the parent node in busts_path (VN_Layer in VN_Layer/Busts), at the old scene's position in the scene tree, and receives the name of the path's last node. The parent node must exist even when no VN Scene is loaded yet. Nodes
VariableNode
busts_containerRequired. The node containing the bust nodes.
highlight_player_1Optional. An AnimationPlayer for the "Animation_1" speaker highlight (see Speaker Highlight).
Bust Nodes Each child of busts_container is a bust node: a place on screen where an Actor can be shown. Dialogues refer to a bust node by its name (the templates use 1 to 9). Unlike background layers, a bust node has no files of its own: it displays the files of the Actor placed on it, from that Actor's bust folder. A bust node can be any node type listed in Media Files that displays images or videos. A Sprite2D or Sprite3D bust node is scaled to the size set for it in bust_sizes: {"Bust Name": [height, width]}. Bust nodes are drawn in their order in the scene tree: lower children appear on top. Children of a bust node Each bust node can hold these children, all optional:
ChildPurpose
An AnimationPlayer named JMLPlays the Join, Move and Leave animations (see JML Effects). Its name is set by jml_player_name.
A speech bubble named SpeechBubbleDisplays the Lines of the Actor on this bust, in VN Bubbles mode. Its name is set by speech_bubbles_name. See Speech Bubbles.
A Label or RichTextLabel named NameTagUsed by the "NameTag" speaker highlight.
A node named OutlineUsed by the "Outline" speaker highlight.
Effects VN effects play on AnimationPlayer children of the bust node: one is created when none is free, so none has to be added. Every AnimationPlayer child of a bust node, except the JML one, may be used for effects: don't add AnimationPlayers there for other purposes. See Busts. JML effects and speaker highlight How the JML AnimationPlayer, highlight_player_1 and the NameTag and Outline nodes are used is explained in JML Effects and Speaker Highlight. Settings Files These behave as on Background Scenes, for busts instead of layers: default_image_extension, default_sprite_extension, default_animated_sprite_extension, default_video_extension, default_animated_image_fps, default_sprite_fps, default_animated_sprite_fps, default_video_fps, default_effect_fps, animation_folder_cache, animation_folder_stream and default_effect_extension. Other
SettingPurpose
bust_sizesThe size of each Sprite2D or Sprite3D bust node.
jml_player_nameThe name of the JML AnimationPlayer in bust nodes.
speech_bubbles_nameThe name (or path) of the speech bubble in bust nodes.
vn_join_effect, vn_move_from_effect, vn_move_to_effect, vn_leave_effectJoin, Move and Leave effects (see JML Effects).
speaker_highlightThe speaker highlights to use (see Speaker Highlight).
billboard_on, billboard_offThe billboard modes used by the "Billboard" highlight.
default_zThe VN Scene's Z-order.
Access A VN Scene has the same Access settings as media players: Private or Public, Public Mode, and the command lists. See Media Players. A hold covers the whole scene, every bust included. When the holder applies its end-of-dialogue treatment to a held VN Scene, that treatment is the Engine's persistent_busts_on_end (the busts are removed unless it's on) and jml_on_end (whether their Leave effects play first). Hook Functions The hook functions of a UI Element are in its script, an 'unsafe' file. Write yours in a copy of the script, attached to your own scenes, or updates will overwrite them (see Customizing UI Elements, on the UI page).
HookCalled
x_playback_starting()Right before a bust or an effect starts playback.
x_playback_started()Right after a bust or an effect has started playback.
They're called when a VN_Play or VN_Effect_Play command starts playback. A playback started with a Loops of 0 only holds its first frame: its hooks run later, when a Resume command starts it. candy_args contains:
  • "caller": the Engine.
  • "node": the VN Scene.
  • "actor": the Actor whose bust is playing.
  • "effect": the effect's animation name, or "" when the bust itself starts playback.
custom_data is [[command values], [actor values]] for a bust, and [[command values], [actor values], [effect values]] for an effect. See UI Elements for how hook functions work.