Copyright © 2025-2026 Candy ArtsBG Play
The BG_Play command displays and plays a file on one or more layers of the Background Scene. Depending on the layer's node type, the file can be an image, a frame animation, a sprite sheet, a SpriteFrames animation or a video. All layers start at the same time, and the Dialogue resumes once each one with a Wait_Loops or Wait_Time has played for that duration. When the playback finishes, the layer remains on screen, on the frame it stopped on. See Backgrounds.
Keys
Every key also accepts a ¢ expression instead of a fixed value, unless its description says otherwise. See CandyRef Expressions.
Layers
Description:
The layers of the Background Scene to act on. Each key is a layer's name, and its value is a Dictionary of settings for that layer (see below), or an empty Dictionary for none. Every layer must be listed by name; there is no shorthand for all layers. An entry that can't be found is reported and skipped, without affecting the others.
Values:
• Layer name: The name of a layer node in the Background Scene's bg_container, such as Sky. It also names the subfolder of background_folder that the layer's files are loaded from.
• ¢ expression: Can also return the layer node itself.
Layer Settings
Each layer in Layers accepts the following keys.
File
Description:
The file to display on the layer, loaded from {background_folder}/{layer}. Which files are supported depends on the layer'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: Loaded from that path.
• Empty: Default.
Animation
Description:
AnimatedSprite layers 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 layer 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 BG_Resume starts playback, which then plays once. A static image has nothing to play or wait for.
• -1 or any negative number: Loop indefinitely, whatever the Duration.
• Empty: 1.
Duration
Description:
The time the layer 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 layer stays on the frame it reached. 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 layer stops on once it has played its Loops and Duration, as a BG_Stop with the same value would stop it. The layer remains on screen: to clear it, use BG_Remove.
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 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 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.
Take_Hold
Description:
Whether this command takes hold of the background scene, 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 applies to the whole scene, and lasts until the holding Engine's Dialogue ends. Setting Take_Hold on any layer of the Line applies it to the whole scene.
Values:
• Empty: The background scene decides, from its own list of commands that take hold.
• 1: Take hold, even if the background scene doesn't list this command.
• -1: Never take hold.