Candy Logo Copyright © 2025-2026 Candy Arts
Background Scenes
A Background Scene displays backgrounds: layers stacked on top of each other, each displaying an image, animation or video, and playing effects. How backgrounds are used in Dialogues is explained in Backgrounds.
  • Script: BG_UI.gd
  • Templates: Scenes/Background_Scenes
  • Updates: the script is 'unsafe', and so is every template except Default.tscn (see Customizing UI Elements, on the UI page)
  • Engine path: backgrounds_path in ui_elements_paths
  • Location: in Candy_UI.tscn, a child of BG_Layer, a CanvasLayer drawn behind the 2D game world (see Drawing Order, on the UI page)
  • Files: see Media Files
The BG_Scene command replaces the Background Scene with another one, looked up in bg_scenes_folder (Candy_Properties.gd). Save your Background Scenes there. The new scene is instantiated as a child of the parent node in backgrounds_path (BG_Layer in BG_Layer/Backgrounds), at the old scene's position in the scene tree, and receives the name of the path's last node. The parent node must exist even when no Background Scene is loaded yet. Nodes
VariableNode
bg_containerRequired. The node containing the layers.
Layers Each child of bg_container is a layer. Dialogues refer to a layer by its node name, which is also the name of its media folder: layers with the same name in different Background Scenes share their files. A layer can be any node type listed in Media Files that displays images or videos. Each layer can use a different one: for example, a TextureRect for the sky and a VideoStreamPlayer for animated water. Layers are drawn in their order in the scene tree: lower children appear on top. Sprite layers A Sprite2D or Sprite3D layer is scaled to the size set for it in bg_sizes: {"Layer Name": [height, width]}. Other node types retain the size set in the scene. Effects Effects play on AnimationPlayer children of their layer: one is created when none is free, so none has to be added. See Background Effects for when to add your own. Settings Files Each of these replaces the Engine setting of the same name, unless left at its inherit value (empty for extensions, 0 for frame rates, -1 for the cache and stream):
SettingPurpose
default_image_extensionExtension added to files named without one, on TextureRect, NinePatchRect and TextureButton layers.
default_sprite_extensionExtension added to spritesheet files named without one, on Sprite2D and Sprite3D layers.
default_animated_sprite_extensionExtension added to SpriteFrames files named without one, on AnimatedSprite2D and AnimatedSprite3D layers.
default_video_extensionExtension added to video files named without one, on VideoStreamPlayer layers.
default_animated_image_fpsFrame rate of frame-folder animations.
default_sprite_fpsFrame rate of spritesheets.
default_animated_sprite_fpsFrame rate of SpriteFrames animations saved with no speed of their own.
default_video_fpsThe frame rate used to count frames, for videos whose own frame rate can't be read.
default_effect_fpsThe frame rate used to count frames, for effects whose animation has no frames of its own to count.
animation_folder_cacheMemory budget (MB) of one animation folder: one that fits stays loaded, one that doesn't is streamed.
animation_folder_streamHow many frames are loaded ahead while an animation folder is streamed.
SettingPurpose
default_effect_extensionExtension added to AnimationLibrary files named without one (default .tres).
bg_sizesThe size of each Sprite2D or Sprite3D layer (see above).
default_zThe Background Scene's Z-order.
Access A Background Scene has the same Access settings as media players: Private or Public, Public Mode, and the command lists. See Media Players. A hold covers the whole scene, every layer included. When the holder applies its end-of-dialogue treatment to a held Background Scene, that treatment is the Engine's persistent_bg_on_end: the backgrounds are cleared when it's off (it's on by default). Hook Functions The hook functions of a UI Element are in its script, an 'unsafe' file. Write yours in a copy of the script, attached to your own scenes, or updates will overwrite them (see Customizing UI Elements, on the UI page).
HookCalled
x_playback_starting()Right before a layer or an effect starts playback.
x_playback_started()Right after a layer or an effect has started playback.
They're called when a BG_Play or BG_Effect_Play command starts playback. A playback started with a Loops of 0 only holds its first frame: its hooks run later, when a Resume command starts it. candy_args contains:
  • "caller": the Engine.
  • "node": the Background Scene.
  • "layer": the layer's name.
  • "effect": the effect's animation name, or "" when the layer itself starts playback.
custom_data is [[command values], [layer values]] for a layer, and [[command values], [layer values], [effect values]] for an effect. See UI Elements for how hook functions work.