Copyright © 2025-2026 Candy ArtsCS Anim Play
The CS_Anim_Play command plays an animation on the AnimationPlayer of nodes in the game world, or sends their AnimationTree's state machine to a state. All targets start at the same time, and the Dialogue resumes once each one with a Wait_Loops or Wait_Time has played for that duration. For an AnimationTree, Loops and Wait_Loops count one loop each time the state is exited after playing. Cutscene playback belongs to the game world: it isn't paused when the Dialogue is suspended or stopped when the Dialogue ends, and media players' Private and Public rules don't apply to it.
Keys
Every key also accepts a ¢ expression instead of a fixed value, unless its description says otherwise. See CandyRef Expressions.
Targets
Description:
The nodes the command acts on. Each key identifies a node, and its value is a Dictionary of settings for that node (see below), or an empty Dictionary for none. The Engine reports an entry it can't find and skips it, without affecting the others.
Values:
• Container/Name: A node inside one of the containers listed in the Engine's cs_paths, such as Actors/Hero for the node Hero in the Actors container. The name can be a longer path, such as Actors/Hero/Hat.
• Container/°role: The node named after the Actor assigned to that Role, such as Actors/°guard. A Role always needs its container.
• Node path: A path relative to the Engine, or an absolute path such as /root/Game/Hero.
• ¢ expression: Can also return the node itself, such as ¢$Level/Hero (a path from the Engine).
Target Settings
Each target in Targets accepts the following keys.
Node
Description:
The node inside the target that the command controls.
Values:
• Internal node key: A key of the target's internal_node_dict.
• Node path: A path relative to the target.
• Empty: The target itself if it is an AnimationPlayer or an AnimationTree, otherwise its child named AnimationPlayer or AnimationTree.
Animation
Description:
The animation to play, or the AnimationTree state to travel to, which is required.
Values:
• Animation name: Such as Wave.
• State name: For an AnimationTree.
Loops
Description:
The number of times the animation 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 CS_Anim_Resume starts playback, which then plays once.
• -1 or any negative number: Loop indefinitely, whatever the Duration.
• Empty: 1.
Duration
Description:
How long the animation 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 animation retains the pose it reached; an AnimationTree state stops where it is. 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 keyframes, otherwise at FPS.
• 0, null or empty: No duration: Loops alone decides.
Stop_Frame
Description:
Where the animation stops once it has played its Loops and Duration, as CS_Anim_Stop would stop it there. On an AnimationTree, -1 travels to its Idle state, and Clear or a positive number deactivates it.
Values:
• 0: Stop on the frame 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: Stop on the last frame.
• Positive number: Stop on 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 keyframes, 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.