Copyright © 2025-2026 Candy ArtsVN Effect Play
The VN_Effect_Play command plays one or more effects on Actors' busts, such as a shake or a flash. An effect is an animation from an AnimationLibrary, played by an AnimationPlayer that Candy Dialogue Engine adds to the bust or reuses, and it follows the Actor when they move to another bust. All effects start at the same time, and the Dialogue resumes once each one with a Wait_Loops or Wait_Time has played for that duration.
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.
• °role: The Actor currently assigned to that Role, such as °guard.
Actor Settings
Each Actor in Actors lists its effects under the following key.
Effects
Description:
The effects the command acts on, for this Actor. Each key is the name of the animation the effect plays, and its value is a Dictionary of settings for that effect (see below), or an empty Dictionary for none.
Values:
• Animation name: An animation of the AnimationLibrary set in Library, such as Shake.
• Library/Name: When Library is empty, an animation already available on one of the Actor's AnimationPlayers.
Effect Settings
Each effect in Effects accepts the following keys.
Library
Description:
The AnimationLibrary containing the effect's animation, whose name is the effect's key in Effects. Loading a library replaces any library that earlier effects loaded onto the same AnimationPlayer; the player's own animations, including RESET, are retained.
Values:
• Library name: A file in {busts_folder}/Animation_Libraries. The scene's default_effect_extension (.tres by default) is added when the name has no extension.
• res:// or user:// path: Used as is.
• Empty: The effect's key names an animation already available on one of the bust's AnimationPlayers, either as Library/Name or as one of the player's own animations.
Loops
Description:
The number of times the effect 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_Effect_Resume starts playback, which then plays once. The effect always restarts from the beginning.
• -1 or any negative number: Loop indefinitely, whatever the Duration.
• Empty: 1.
Duration
Description:
How long the effect 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 effect retains the pose it reached. 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 on the animation's own frames, otherwise at FPS.
• 0, null or empty: No duration: Loops alone decides.
Stop_Frame
Description:
Where the effect stops once it has played its Loops and Duration, as VN_Effect_Stop would stop it there.
Values:
• 0: Retain the pose it ends on.
• Clear or X (case-insensitive): Play the RESET animation of the animation's library, or the player's own RESET animation, if one exists, then stop.
• -1: Retain the pose of the last frame.
• Positive number: Retain the pose of that frame, counted from 1. An animation's frames are its keyframes.
• 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.
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 on the animation's own frames, otherwise at FPS.
• 0 or empty: No additional wait.
FPS
Description:
The frame rate at which f= values are counted in animations that have no frames of their own. An animation's frames are the keys of its most-keyed discrete track, or its step value.
Values:
• Frames per second: Such as 12.
• Empty: The default frame rate, default_effect_fps.
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 effect 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.