Candy Logo Copyright © 2025-2026 Candy Arts
Backgrounds
Dialogues can display backgrounds behind the dialogue UI: a room, a landscape, a sky with clouds drifting by, a flickering fire... A background is composed of layers, stacked on top of each other. Each layer displays its own file (an image, an animation or a video) and is controlled separately, so a scene can combine a still landscape, an animated sky and a video of rippling water, and change any of them without affecting the others. Background Scenes Layers belong to a Background Scene: a UI Element whose layers are nodes you place yourself, at any size and position. The Engine locates it through backgrounds_path in its ui_elements_paths. How to build one, and its settings, are explained in Background Scenes (UI section). Layer files Each layer has its own media folder, named like the layer node: Candy_DE/Media/General/Backgrounds/{layer}. What a layer can display depends on its node type: see Media Files. Layers with the same name in different Background Scenes share the same folder. With general layer names (Sky, Ground, Foreground), one set of files serves every scene. Background Commands Dialogues control backgrounds with the BG commands. Each command can act on several layers at once, each with its own settings.
CommandPurpose
BG_PlayDisplay a file on a layer, and play it.
BG_WaitWait for a layer's playback.
BG_PausePause a layer.
BG_ResumeResume a paused layer.
BG_SkipMove a layer's playback to another point.
BG_MirrorFlip a layer horizontally or vertically.
BG_StopStop a layer's playback, leaving it on screen.
BG_RemoveEmpty a layer.
BG_SceneReplace the whole Background Scene with another one.
BG_Effect_ commandsPlay animations on layers: see Background Effects.
How layers play their files (once, several times, forever), and how to wait for them, pause them or stop them on a frame, is explained in Animated Layers. The UI_Clear command can also empty every layer at once. Changing Scenes A Background Scene's layout is fixed: its layers retain the size, position and order set in the scene. When a Dialogue needs a different layout, such as a close-up after a wide shot, the BG_Scene command replaces the whole Background Scene with another one, saved in bg_scenes_folder (Candy_Properties.gd). The new scene replaces the old one: the Engine still locates it at backgrounds_path, and an Engine that owned the old scene owns the new one. A BG_Scene command with an empty Scene removes the Background Scene altogether. A later BG_Scene adds a new one. When the Dialogue Ends By default, backgrounds stay on screen when the Dialogue ends: the Engine's persistent_bg_on_end setting is on. The layers continue to display and play their files, so the next Dialogue can continue in the same place. To clear the backgrounds when the Dialogue ends instead, turn persistent_bg_on_end off. To clear persistent backgrounds later, from your own game code, call candy_de.clear_bg_layers_ood(engine), with the Engine whose Background Scene should be cleared. Suspension When a Dialogue is suspended (see Suspending Dialogues), its backgrounds pause with it. The Engine's settings decide what pauses:
  • suspend_backgrounds: pause backgrounds at all.
  • suspend_bg_animations: pause the layers' playback.
  • suspend_bg_effects: pause the effects.
Sharing Backgrounds Several Engines can share the same Background Scene, for example when parallel Dialogues share one screen. Its Access settings, the same as a media player's (see Media Players), decide which Engines may control it. An Engine that controls the scene controls all of its layers.