Copyright © 2025-2026 Candy ArtsVN Play
The VN_Play command places one or more Actors on busts of the VN Scene, then displays and plays a file on each. For an Actor already on screen, it changes what their bust displays without moving them; an Actor joining the scene plays their Join effect as they appear. The Dialogue resumes once every Actor has appeared and each one with a Wait_Loops or Wait_Time has played for that duration. Like every VN command, it requires the Engine's vn_mode to be enabled. See Busts.
Keys
Every key also accepts a ¢ expression instead of a fixed value, unless its description says otherwise. See CandyRef Expressions.
Actors
Description:
The Actors the command acts on, each on a bust of the VN Scene. Each key is an Actor, and its value is a Dictionary of settings for that Actor (see below), or an empty Dictionary for none. List every Actor by name: there is no shorthand for all Actors. The Engine reports an entry it can't find and skips it, without affecting the others.
Values:
• Actor Reference: A key of the actors dictionary, such as Alice. It also names the subfolder of busts_folder that the Actor's files are loaded from.
• °role: The Actor currently assigned to that Role, such as °guard.
Actor Settings
Each Actor in Actors accepts the following keys.
Bust
Description:
The bust node the Actor is placed on. Required for an Actor who isn't on a bust yet. It is refused if another Actor occupies it. Moving an Actor to a new bust this way clears the old bust without playing a Move effect.
Values:
• Bust node name: Such as Left.
• Empty: The Actor's current bust.
File
Description:
The file to display on the bust, loaded from {busts_folder}/{actor}. Which files are supported depends on the bust's node type; see Media Files.
Values:
• File name: An image for TextureRect, NinePatchRect, TextureButton, Sprite2D and Sprite3D nodes, a video for VideoStreamPlayer nodes, or a SpriteFrames file in the Sprite_Frames subfolder for AnimatedSprite2D and AnimatedSprite3D nodes. When the name has no extension, the scene's default extension for the node type is added.
• Name_CxR.png: On Sprite2D and Sprite3D nodes, a sprite sheet of C columns and R rows of frames, such as Fire_4x2.png. A suffix leaves frames empty at the end of the sheet: Fire_4x2-1.png has 7 frames.
• Folder name: On TextureRect, NinePatchRect and TextureButton nodes, a frame-by-frame animation.
• res:// or user:// path: Used as is.
• Empty: The file named Default.
Animation
Description:
AnimatedSprite busts only. The animation of the SpriteFrames to play.
Values:
• Animation name
• Empty: The animation named after File, otherwise the first animation that has frames.
Loops
Description:
The number of times the bust plays.
Values:
• Positive number: Play that many times.
• 0: Display the first frame without playing, unless a Duration is set. There is nothing to wait for until a VN_Resume starts playback, which then plays once.
• -1 or any negative number: Loop indefinitely, whatever the Duration.
• Empty: 1.
Duration
Description:
How long the bust continues playing after its Loops, so that playback can stop partway through a loop. It plays for Loops × its length + Duration: with a Loops of 0, it plays for the Duration alone. A duration longer than one loop carries over into additional loops. When the duration runs out, playback ends as if its last loop had finished, on its Stop_Frame. The bust stays on the frame it reached. The duration continues to count through VN_Move and VN_Swap. A static image has nothing to play, so a Duration has no effect. Paused time doesn't count.
Values:
• Number of seconds: Such as 2.5.
• Timestamp: In the format SS.xx, MM:SS.xx or HH:MM:SS.xx, such as 01:30.5.
• f=N: N frames, counted at FPS when the media has no frames of its own.
• 0, null or empty: No duration: Loops alone decides.
Stop_Frame
Description:
The frame the bust stops on once it has played its Loops and Duration, as VN_Stop would stop it there. It remains on screen; use VN_Remove to clear it.
Values:
• 0: Stop on the frame it ends on.
• -1: Stop on the last frame.
• Positive number: Stop on that frame, counted from 1 and clamped to the available frames.
• Empty: 0.
Wait_Loops
Description:
The number of completed loops the Dialogue waits for before resuming. The Dialogue resumes after Wait_Loops loops plus Wait_Time into the following loop, or earlier if playback ends or is stopped. When several entries of the Line set a wait, the Dialogue resumes once every one of them has reached its wait.
Values:
• 0: Don't wait for any loops. If Wait_Time is also 0, the Dialogue doesn't wait at all.
• Positive number: The number of loops to wait for.
Wait_Time
Description:
The additional time the Dialogue waits after Wait_Loops, measured into the following loop. A time longer than the media carries over into additional loops. Playback starts before the Join effect, so the wait is counted from that point.
Values:
• Number of seconds: Such as 2.5.
• Timestamp: In the format SS.xx, MM:SS.xx or HH:MM:SS.xx, such as 01:30.5.
• f=N: N frames, counted at FPS when the media has no frames of its own.
• 0 or empty: No additional wait.
FPS
Description:
The playback frame rate of frame folders, sprite sheets, and SpriteFrames saved without a speed. f= values are also counted at this rate.
Values:
• Frames per second: Such as 12.
• Empty: The file's own frame rate (set in a frame folder's config.txt), otherwise the default frame rate.
JML_Order
Description:
Groups the Line's Actors, which are processed in ascending order of group: the Actors of a group appear, move or leave together, and the next group starts once all of them have finished. See JML Effects.
Values:
• Number: The Actor's group.
• Empty: 0.
Join_Effect
Description:
Overrides the Actor's Join effect for this Line. It only plays when the Actor joins the scene. When not set, the effect comes from the Actor's VNJoinEffect in the actors dictionary, otherwise from the VN Scene, otherwise from the Engine.
Values:
• Animation name: An animation of the bust's JML player, such as Fade_In.
• Empty: No effect on this Line.
• null: Not set; the Actor, the VN Scene or the Engine decides.
Take_Hold
Description:
Whether this command takes hold of the bust scene, if it is Public. While an Engine holds it, its Public Mode determines which commands other Engines may send it: none (Exclusive), only the commands it lists (Semi-Exclusive), or any (Free). The hold applies to the whole scene, and lasts until the holding Engine's Dialogue ends. Setting Take_Hold on any Actor of the Line applies it to the whole scene.
Values:
• Empty: The bust scene decides, from its own list of commands that take hold.
• 1: Take hold, even if the bust scene doesn't list this command.
• -1: Never take hold.