Copyright © 2025-2026 Candy ArtsEffect Play
The Effect_Play command plays an animation on one or more effect players, which are AnimationPlayers listed in the Engine's media_players_paths. The animation belongs to an AnimationLibrary loaded by the Line, or to the player itself. All players 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.
Players
Description:
The effect players (AnimationPlayers) to act on. Each key is a player's name, and its value is a Dictionary of settings for that player (see below), or an empty Dictionary for none. A single Line can control several players, each with its own settings. An entry that can't be found is reported and skipped, without affecting the others.
Values:
• Player name: A key of the Engine's media_players_paths, such as Effect.
• ¢ expression: Can also return the player node itself, such as ¢$UI/Radio.
Player Settings
Each player in Players accepts the following keys.
Library
Description:
The AnimationLibrary to load into the player, from {effects_folder}/Animation_Libraries, a folder shared by every effect player. It replaces the library loaded by a previous Line, while the player's own animations (those built into its scene, including RESET) are always retained.
Values:
• Library name: Such as UI_FX. The player's default_effect_extension (.tres by default) is added when the name has no extension.
• res:// or user:// path: Loaded from that path.
• Empty: The library already loaded is retained.
• ¢ expression: Can also return a loaded AnimationLibrary, such as ¢load("res://FX/UI_FX.tres").
Animation
Description:
The animation to play. The player searches the loaded library first, then its own animations. This key is required.
Values:
• Animation name: Such as Flash.
• Library/Name: An animation named with its library; only the loaded library and the player's own animations are available.
Loops
Description:
The number of times the animation plays.
Values:
• Positive number: Play that many times.
• 0: Hold the first frame without playing, unless a Duration is set. There is nothing to wait for until a Effect_Resume starts playback, which then plays once. The animation always restarts from the beginning.
• -1 or any negative number: Loop indefinitely, whatever the Duration.
• Empty: 1.
Duration
Description:
The time the animation continues to play after its Loops, so that it 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 time runs out, the playback ends as if its last loop had finished, on its Stop_Frame. The animation 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:
The frame the animation stops on once it has played its Loops and Duration, as an Effect_Stop with the same value would stop it.
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 have a wait, the Dialogue resumes once all of them have reached it.
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 used to count f= values 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 player, if it is Public. While an Engine holds it, its Public Mode determines what other Engines can do with it: nothing (Exclusive), only the commands it lists (Semi-Exclusive), or anything (Free). The hold lasts until the playback ends or is stopped.
Values:
• Empty: The player decides, from its own list of commands that take hold.
• 1: Take hold, even if the player doesn't list this command.
• -1: Never take hold.