Busts
A bust is an Actor displayed on screen, on one of the VN Scene's bust nodes.
Building the VN Scene and its bust nodes is explained in VN Scenes.
Actors and Bust Nodes
A bust node is a place on screen. Dialogues place an Actor on it, and the bust node displays that Actor's files, from their bust folder (Candy_DE/Media/Actors/Busts/{actor}).
- A bust node displays one Actor at a time: placing an Actor on a bust node that another Actor occupies is refused.
- An Actor is on one bust node at a time.
The VN Scene records which Actor is on which bust node. Commands therefore name the Actor, not the bust node: once Alice is on screen, a Line only needs to name "Alice" to change her expression, move her or remove her.
Appearing and Changing
VN_Play places an Actor on a bust node and displays one of their files. For an Actor already on screen, it changes what their bust displays (a new expression, a new animation), without moving them.
An Actor new to the scene plays their Join effect as they appear (see JML Effects).
What a bust can display depends on its bust node's type, as for a background layer, and a bust plays its file in the same way: once, several times, forever, or holding its first frame; with waits, pauses, pause loops, skips and stops. See Animated Layers, where everything said about layers applies to busts, with the VN commands in place of the BG ones.
Moving and Swapping
- VN_Move moves an Actor to a free bust node, playing their Move effects. The Actor continues to display and play the same file, effects included.
- VN_Swap exchanges the bust nodes of two Actors, playing both their Move effects.
Both require bust nodes of the same node type, since the file one displays must be displayable by the other. To move an Actor between bust nodes of different types, use VN_Play with the new bust node and a file it can show: the Actor leaves their old bust node at once, without a Move effect.
Leaving
VN_Remove plays an Actor's Leave effect, then empties their bust node: its file, playback and effects. The bust node is free again.
VN_Stop only stops a bust's playback: the Actor stays on screen.
Actors are also removed by the UI_Clear command, at the end of the Dialogue, and by clear_busts_ood() (see Visual Novels).
Bust Effects
The VN_Effect commands play animations on busts: a jump of surprise, a shiver, a blush overlay... They behave like Background Effects, with these differences:
- AnimationLibrary files are saved in Candy_DE/Media/Actors/Busts/Animation_Libraries.
- Lines name the Actor, not the bust node, and effects follow the Actor when they move or swap bust nodes.
- Effects never play on a bust node's JML AnimationPlayer, which is reserved for JML effects.
Busts in Your Own Code
To locate an Actor's bust from your own code (for example, in a hook function), call CandyUI rather than reading the VN Scene's internals:
if CandyUI.get_shared().has_bust(engine, self, "Alice"):
var bust_node = CandyUI.get_shared().actor_bust(engine, self, "Alice")
Both only locate busts while the Engine's vn_mode is on.
Copyright © 2025-2026 Candy Arts