Candy Logo Copyright © 2025-2026 Candy Arts
Animated Layers
A background layer can display a still image, an animation or a video. VN busts play their files in the same way (see Busts). What a Layer Can Play What a layer can play depends on its node type:
Layer nodeCan play
TextureRect, NinePatchRectStill images, and Animation Folders.
TextureButtonStill images and Animation Folders, with a texture (or an animation) for each button state.
Sprite2D, Sprite3DStill images, and sprite sheets.
AnimatedSprite2D, AnimatedSprite3DSpriteFrames resources.
VideoStreamPlayerVideos.
How to prepare each kind of file is explained in Media Files. A layer's node type can't change during a Dialogue. To display a video where a layer displays an image, use another layer, or a Background Scene with the suitable node types (see Backgrounds). Frame Rate Animation Folders and sprite sheets have no frame rate of their own. The frame rate is decided in this order, each overriding the previous:
  • Candy_Properties.gd (default_animated_image_fps, default_sprite_fps).
  • The Engine's setting of the same name, unless left at 0.
  • The Background Scene's setting of the same name, unless left at 0.
  • A config.txt in the layer's folder, then in the Animation Folder itself (see Media Files).
  • The FPS field of the BG_Play command.
SpriteFrames play at the speed they were saved with, and videos at their own frame rate: these settings only apply when they have none. Playing BG_Play displays a file on a layer and starts playing it. An animation or video can play once, a set number of times, or loop forever. It can also display its first frame without playing, until a BG_Resume starts it, so a layer can be set in place early and started at the right moment. When an animation finishes playing, the layer continues to display its last frame. A still image has nothing to play: it stays on the layer. Several layers One BG_Play command can start several layers. They all start at the same time. Waiting By default, the Dialogue moves on as soon as a layer starts playing, and the layer continues to play behind the next Lines. A Line can instead block the Dialogue until a layer has played a number of times, or for a length of time (or both): for example, so that a sunrise animation finishes before anyone speaks. BG_Play can wait for the layers it starts; BG_Wait waits for layers that are already playing. When a Line waits for several layers, the Dialogue moves on once all of them are done. Pausing and Resuming BG_Pause pauses a layer, until a BG_Resume resumes it. A pause can also end on its own after a number of Lines. Pause loops Rather than freezing, a paused layer can continue to play a short segment of itself on repeat, such as a few seconds of a flickering fire, while the Dialogue continues. The segment and how playback resumes are set on the BG_Pause Line. For a video layer, the pause loop can also play at a lower volume. Other Controls
  • BG_Skip moves a layer's playback forward or backward, by time or by frames.
  • BG_Stop stops a layer's playback on a frame of your choice, and leaves it on screen.
  • BG_Mirror flips a layer horizontally, vertically or both, or restores it.
  • BG_Remove empties a layer: its file, its playback and its effects.
Video Sound A video layer plays its sound through its VideoStreamPlayer's bus property. Set it in the Background Scene, like any other audio node.