Candy Logo Copyright © 2025-2026 Candy Arts
Playing Media
A Media_Play command plays a file on one or more media players. The player's type decides the kind of media: an audio player plays a sound, a video player a video, and an image player displays a still image or a frame animation. The Line lists its players under Players, each with its own settings, and starts them all at the same time. For example, a Line with two players, Music, with File set to Theme and Loops to -1, and Sound, with File set to Bell, starts the theme on a loop and rings the bell once. A player that can't be found is reported and skipped, and the others play. Every key is described in Media Play. By default, the Dialogue continues as soon as the players have started. To wait for a playback, see Waiting. The File File names a file in the player's folder: Candy_DE/Media/General/Audio/{player}, Videos/{player} or Images/{player}. A name written without an extension receives the player's default extension (.ogg, .ogv or .png by default). A file that doesn't exist, or an empty File, plays the folder's file named Default instead, if there is one. On an image player, a folder name plays a frame animation: the folder's images, in the order of their numbers. Sprite sheets and the other kinds of animated files are described in Media Files. A res:// or user:// path plays that file, with no Default fallback: a file outside the project's media folders, or outside the exported game, for a mod or a patch. A ¢ expression can also return a loaded resource. Loops and Duration Loops sets how many times the media plays, and Duration how long it continues after those loops, so that playback can stop partway through a loop. The media plays for Loops times its length, plus the Duration:
LoopsDurationA 2-second clip plays...
Empty or 1EmptyOnce: 2 seconds.
3EmptyThree times: 6 seconds.
10.52.5 seconds.
055 seconds: a duration longer than the clip continues into further loops.
-1AnyUntil it is stopped.
0EmptyNot at all: the first frame is displayed until a Media_Resume plays the clip once. Audio plays nothing.
The Duration is a number of seconds, a timestamp (01:30.5) or, on video and image players, a number of frames (f=48). It is counted on the playback itself: paused time doesn't count. A still image has no loops. It remains on screen for its Duration or, with none, until a Media_Stop. The End of a Playback Once the loops and the duration are over, the playback ends on its Stop_Frame, as a Media_Stop with the same value would end it:
  • Clear (the default): the file is unloaded, and a video or image player is hidden.
  • 0: the player stops on the frame it ends on, and a video or image remains on screen.
  • -1 or a frame number: the player stops on the last frame, or on that frame, counted from 1.
A video or image stopped on a frame isn't restarted by a Media_Resume. On an audio player, any number leaves the file loaded. Frame Rate A value in frames (f=N, in Duration, Wait_Time or a Media_Skip) is counted at the media's frame rate: a video's own, or default_video_fps when it can't be read, and a frame animation's playback rate. The FPS key overrides both, and for a frame animation also sets the rate it plays at. Audio has no frames, so an f= value is reported on an audio player. The Dialogue UI and the Media A video or image is drawn above or below the dialogue UI according to their z indexes. The Box key of a video or image player moves the dialogue box with its portrait, the subtitles, the chat and the barks together, relative to the player: +1 draws them in front of it, -1 behind it, a number sets their z index exactly, and Reset restores each UI Element's default. Left empty, the z indexes are unchanged, so that several players in one Line don't override each other. A Player Already Playing A Media_Play on a player that is still playing replaces its playback: the new file plays with the new settings, and a pause loop or a scheduled stop of the previous playback ends. The player's x_playback_finished() hook isn't called for the replaced playback (see Media Players).