Candy Logo Copyright © 2025-2026 Candy Arts
Shared Players
Several Engines can share one media player, such as a music player every Dialogue of the game plays through, or an ambient player an NPC's barks turn down. Which Engines may control a player, and what happens to its playback when a Dialogue ends or is suspended, is decided by the player's Access settings and by the owner and holder rules below. The settings themselves are described in Media Players; parallel Dialogues in general in Parallel Dialogues. Owners An Engine lists its players by path in media_players_paths. A plain path designates the Engine as the player's owner; a path written as ["path", false] only names the player, without owning it. A player has one owner at most (see Owning or naming in UI Elements). Private and Public Players A Private player (the default) obeys only its owner. A Private player with no owner obeys no Engine at all. A Public player obeys any Engine, within its Public Mode. The Engine whose Line starts a playback on it becomes its holder until that playback ends or is stopped, and the Public Mode decides which Commands other Engines may send it meanwhile:
Public ModeOther Engines
ExclusiveTheir Lines are rejected.
Semi-ExclusiveThey may only send the Commands in the player's semi_exclusive_commands: by default, pause, resume, stop, volume and skip, but not a new playback.
FreeThey may send any Command, and the Engine that sends a Command that takes hold becomes the holder.
A rejected Line is reported in the Output panel, and the Dialogue continues. Media_Wait and Effect_Wait are accepted from any Engine on any player, since they only delay the Dialogue that runs them. For example, an Ambient player in Semi-Exclusive mode plays the forest sounds of the main Dialogue, and a bark Engine can lower its volume with a Media_Volume command, but can't replace the track. Taking Hold By default, the Commands in the player's hold_commands take hold: Media_Play alone. A Line overrides this with its Take_Hold key: 1 takes hold with any Command, such as a Media_Volume that should reserve the player, and -1 never takes hold, such as a Media_Play that leaves the player open to the next Dialogue. The End and Suspension of a Dialogue The owner of a Private player always pauses it when its Dialogue is suspended, and stops it when its Dialogue ends. For a Public player, the holder pauses and stops it when suspend_held_media and end_held_media say so, resolved in this order, each level overriding the previous: Candy_Properties.gd, then the Engine (when its enable_suspend_held_media or enable_end_held_media switch is on), then the player (under Held Player Overrides, when its own switch is on). A player the holder doesn't stop continues to play after the Dialogue, and is released: the next Engine to start a playback on it becomes its holder. For example, a Music player set to Public and Free, with end_held_media off in its Held Player Overrides, plays whatever the latest Dialogue started, and continues after that Dialogue ends until another Dialogue changes the music.