Copyright © 2025-2026 Candy ArtsCS Sprite Play
The CS_Sprite_Play command displays a file on sprite nodes in the game world: a texture or an animated sprite sheet on Sprite2D and Sprite3D nodes, or a SpriteFrames animation on AnimatedSprite2D and AnimatedSprite3D nodes. 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. 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 a Sprite2D, Sprite3D, AnimatedSprite2D or AnimatedSprite3D, otherwise its child with one of those names.
File
Description:
The file to display, loaded from {sprite_folder}/{target name}, or from its Sprite_Frames subfolder for AnimatedSprite nodes.
Values:
• File name: An image for Sprite2D and Sprite3D nodes, or a SpriteFrames file for AnimatedSprite nodes. When the name has no extension, the default extension for the node type is added.
• Name_CxR.png: A sprite sheet of C columns and R rows of frames, such as Fire_4x3.png. A suffix leaves frames empty at the end of the sheet: Fire_4x3-2.png has 10 frames.
• res:// or user:// path: Used as is.
• Empty: Remove the sprite and hide the node.
Animation
Description:
AnimatedSprite nodes 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 sprite 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_Sprite_Resume starts playback, which then plays once.
• -1 or any negative number: Loop indefinitely, whatever the Duration.
• Empty: 1.
Duration
Description:
How long the sprite 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 sprite stays on the frame 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 SpriteFrames frames, including their durations, or on the sprite sheet frames.
• 0, null or empty: No duration: Loops alone decides.
Stop_Frame
Description:
Where the sprite stops once it has played its Loops and Duration, as CS_Sprite_Stop would stop it there.
Values:
• 0: Stop on the frame it ends on.
• Clear or X (case-insensitive): Remove the sprite and hide the node.
• -1: Stop on the last frame.
• Positive number: Stop on that frame, counted from 1.
• 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 SpriteFrames frames, including their durations, or on the sprite sheet frames.
• 0 or empty: No additional wait.
FPS
Description:
For sprite sheets, the playback frame rate. For AnimatedSprites, read only when the SpriteFrames animation was saved without a speed. f= values are also counted at this rate.
Values:
• Frames per second: Such as 12.
• Empty: The default frame rate.