Copyright © 2025-2026 Candy ArtsMedia Files
Media files are displayed by many different Commands, which all follow the rules below.
Nodes
Media files are displayed by the following nodes:
- TextureRect
- TextureButton
- NinePatchRect
- Sprite2D/3D
- AnimatedSprite2D/3D
- VideoStreamPlayer
- AudioStreamPlayer
- AudioStreamPlayer2D/3D
- AnimationPlayer
Formats
A media file can be of any format the node that displays it accepts: .png, .jpg, .ogv, .ogg, .mp3...
A default extension is set in Candy_Properties.gd, in the Engine settings, in the UI Element settings and in the folder settings (config.txt, explained further down), each level overriding the previous one.
The default extension is appended when a Command's data field names a file without an extension (image instead of image.png). A file name written with its extension is read as written.
There is one default extension per kind of node, since each kind displays different files:
default_image_extension: TextureRect, NinePatchRect, TextureButton
default_sprite_extension: Sprite2D/3D
default_animated_sprite_extension: AnimatedSprite2D/3D (SpriteFrames files, .tres by default)
default_video_extension: VideoStreamPlayer
default_audio_extension: AudioStreamPlayer, AudioStreamPlayer2D/3D
default_voice_extension: voice files
File Names
A media file's name is free, apart from the special cases below.
In some Commands, when no file is named, or when the named file isn't found, the Engine plays a file named Default with the default extension instead, if that file exists.
Folders
The media files you add are 'safe': updates never overwrite or delete them. The Animation Libraries that ship in the Animation_Libraries folders are 'safe' too.
Media files are placed in the following folders:
- Images: Candy_DE/Media/General/Images/{media player}
- Audio: Candy_DE/Media/General/Audio/{media player}
- Video: Candy_DE/Media/General/Videos/{media player}
- Effects: Candy_DE/Media/General/Effects/Animation_Libraries
- Backgrounds: Candy_DE/Media/General/Backgrounds/{bg layer}
- Background Effects: Candy_DE/Media/General/Backgrounds/Animation_Libraries
- Portraits: Candy_DE/Media/Actors/Portraits/{actor}
- VN Busts: Candy_DE/Media/Actors/Busts/{actor}
- VN Effects: Candy_DE/Media/Actors/Busts/Animation_Libraries
- Sprites: Candy_DE/Media/Actors/Sprites/{node}
- Voice Files: Candy_DE/Media/Actors/Voices/{actor}/{dialogue}/{conversation}/{block}
{media player} indicates a folder that is named the same as a key in the Engine's media_players_paths dictionary.
{bg layer} indicates a folder named the same as a Layer node inside a Background Scene. Layers with the same name in different Background Scenes share the same folder.
{actor} indicates a folder named the same as an Actor Reference.
{node} indicates a folder named the same as the node a CS_Sprite_Play line targets, such as Hero for Actors/Hero. Name the node after its Actor, so that each Actor's sprites are stored in one folder.
For voice files, the {actor}, {dialogue}, {conversation} and {block} folders are optional and can be ordered differently, and a {line} folder, named by the Line's number in its Block, can be added: their layout follows voice_path, in Candy_Properties.gd. Voice files for a language or variation other than "Default" go in a folder of their own inside the last one, named like that language or variation.
Some of these folders contain sub-folders of their own, for the special cases explained below: Sprite_Frames, Button_Textures and Animated.
Custom Folders
Other folders are set in Candy_Properties.gd, in the ..._folder variables.
Prefer the default folders: they are more predictable when Candy Dialogue Engine is updated.
A data field also accepts a full res:// or user:// path instead of a file name. The path is read as written, and the folders above are ignored.
Special Cases
Texture Buttons
A TextureButton displays a different texture for each of its states: hovered, pressed, disabled... When a TextureButton displays an image, the Engine searches for these state textures in a Button_Textures folder, placed beside the image.
Inside Button_Textures, each image has its own sub-folder, named after the image's name and extension, joined with an underscore. For example, the extra textures of happy.png go in Button_Textures/happy_png.
Inside that sub-folder, each file is named after the image, followed by its state:
happy_pressed.png: displayed while the button is pressed.
happy_hover.png: displayed while the mouse hovers over the button.
happy_disabled.png: displayed while the button is disabled.
happy_focused.png: displayed over the button while it has focus.
happy_mask.png: the button's click mask (also accepted: happy_click_mask).
Every file is optional: a state without its own file uses the button's normal texture. Names aren't case-sensitive, and the underscore can also be a hyphen or a space.
A click mask must be a BitMap resource. For an image inside your project, select it in the FileSystem dock and set "Import As" to "BitMap" in the Import dock. An image in user:// is converted to a BitMap automatically.
Button_Textures is for still images. A TextureButton displaying an Animation Folder reads its state textures from the Animation Folder instead (see Animated Texture Buttons below).
Animation Folders
An Animation Folder is a folder of image files, displayed in sequence as the frames of an animation. It animates still images without a video or a SpriteFrames resource.
An Animation Folder is displayed by TextureRect, NinePatchRect and TextureButton nodes: image players, background layers, VN busts and portraits.
To create one, place the frames in a folder inside an Animated folder of the media folder they're played from. For example: Candy_DE/Media/General/Images/{media player}/Animated/Fire. Then write the folder's name (Fire) in the data fields that name a media file.
Frames play in the order of the number at the end of their names: 1.png, 2.png ... 10.png play in that order, so 0-padding (001.png) is unnecessary. The other files in the folder, such as config.txt, and the folders inside it are ignored. Frames can therefore be named Fire_1.jpg, Fire_2.jpg...
The first frame is loaded when the line starts, and the others are loaded in the background as the animation plays. A large animation occupies a lot of memory, so an animation larger than animation_folder_cache (in MB) is streamed instead: only the next few frames are loaded (animation_folder_stream), and each frame is released once displayed. Both settings are in Candy_Properties.gd, which explains them in detail.
An animation's frame rate is set by default_animated_image_fps, by the folder settings, or by a config.txt containing a line such as fps = 12 inside the animation folder itself. The FPS field of a line overrides them all.
Animated Texture Buttons
When a TextureButton displays an Animation Folder, each of its states can be animated too. The state textures are then placed in folders inside the Animation Folder itself, one per state, instead of Button_Textures:
Fire/1.png, Fire/2.png ...: the normal animation.
Fire/pressed/: frames displayed while the button is pressed.
Fire/hover/: frames displayed while the mouse hovers over the button.
Fire/disabled/: frames displayed while the button is disabled.
Fire/focused/: frames displayed over the button while it has focus.
Fire/mask/: the button's click mask (also accepted: click_mask).
Every state folder is optional: a state without its own folder uses the button's normal texture. Folder names aren't case-sensitive.
Each state plays in step with the normal animation: when the button displays frame 5, its hover texture is frame 5 of the hover folder, so a state folder contains as many frames as the animation. A state folder containing a single frame displays that frame for the whole animation, for a state that doesn't move. A state folder with any other number of frames is reported in the Output, and loops over its own frames.
A click mask can't be animated: the mask folder contains one file, the click mask, which must be a BitMap (see Texture Buttons above).
Each state folder is loaded like an Animation Folder of its own: it is cached or streamed according to its own size, measured against animation_folder_cache. A button with every state animated can therefore occupy several times the memory of a single animation. To set a state's own budget, use the Animation Folder's config.txt (see Folder Settings below).
Every state continues to play while hidden, so that the right frame is ready the moment the button changes state. The choice is between memory and loading time:
A cached state loads each frame once: after its first loop, it costs nothing more. This suits the states players see often, such as hover.
A streamed state occupies only a few frames at a time, but reloads them on every loop, even while hidden. This suits large states players rarely see, such as disabled or focused: assign them a cache of 0 and a small stream.
Sprite Sheets
Sprite2D and Sprite3D nodes can display a sprite sheet: a single image that contains every frame of an animation, laid out in a grid.
The grid's layout is written at the end of the file's name, before the extension: {name}_{columns}x{rows}.png. For example, Fire_4x3.png has 4 columns and 3 rows, so 12 frames. Frames play left to right, then top to bottom.
If the last cells of the grid are empty, add their number after a hyphen: Fire_4x3-2.png has 10 frames, and its last 2 cells are skipped.
An image whose name doesn't end with a layout is displayed as a single, still image.
A sprite sheet's frame rate is set by default_sprite_fps and by the folder settings. The FPS field of a line overrides them.
AnimatedSprite2D/3D
AnimatedSprite2D and AnimatedSprite3D nodes display SpriteFrames resources (.tres files), which can each contain several named animations.
SpriteFrames files are placed in a Sprite_Frames folder, inside the media folder they're used from. For example: Candy_DE/Media/Actors/Sprites/{actor}/Sprite_Frames, or Candy_DE/Media/General/Backgrounds/{bg layer}/Sprite_Frames.
In the BG_Play, VN_Play and CS_Sprite_Play commands, the File field names the SpriteFrames file, and the Animation field names the animation to play. When no animation is named, the animation named after the file is played, or else the first animation that contains frames.
For portraits, the Sprite_Frames_File field names the SpriteFrames file (by default, the one named after the actor, e.g. Alice.tres), and the portrait's name is the animation to play. If the SpriteFrames has no such animation, its "default" animation is played.
A SpriteFrames animation plays at the speed it was saved with: the FPS field of a line doesn't change it. An animation saved with a speed of 0 plays at default_animated_sprite_fps instead.
Folder Settings
A folder media files are played from can contain a config.txt file, which sets defaults for the files in it. They override the settings of Candy_Properties.gd, the Engine and UI Elements.
extension = png
fps = 12
Files: {
sprite_sheet_4x2-1.png: {fps = 8}
Fire: {fps = 4, cache = 0, stream = 12}
}} is written on its own line.
Every setting is optional, and each is only read where it applies: audio files ignore fps, and videos and SpriteFrames play at their own frame rate when they have one. Lines starting with # are comments. A mistake in the file is reported in the Output, with its line number.
An animation folder can also contain a config.txt of its own, containing a line such as fps = 12. It sets that animation's frame rate, and overrides the config.txt of the folder it's in.
For an animated TextureButton, the animation folder's own config.txt also sets the memory use of its state folders: cache and stream apply to every state folder, and a Files entry, named after a state folder, applies to that state only. State folders always play at the animation's frame rate, so their fps is ignored.
fps = 12
Files: {
disabled: {cache = 0, stream = 2}
focused: {cache = 0, stream = 2}
}*.txt to your export filters (Project > Export > Resources > "Filters to export non-resource files/folders").