Candy Logo Copyright © 2025-2026 Candy Arts
Voice Players
Voice Players speak Spoken Lines: they play voice files, and the output of Text-To-Speech. Unlike other media players, they aren't controlled by commands and have no Access settings: each one belongs to a single UI Element.
  • Scripts: Voice_Player.gd (AudioStreamPlayer), Voice_Player_2D.gd (AudioStreamPlayer2D), Voice_Player_3D.gd (AudioStreamPlayer3D)
  • Updates: the scripts are 'unsafe' (see Customizing UI Elements, on the UI page)
  • Files: see Voice and Media Files
Voice Player Location In Speech Display UI Elements Each Speech Display UI Element has its own Voice Player, assigned to its voice_node variable (see Speech Display):
  • Dialogue Box, Subtitles and Chat_Channel: an AudioStreamPlayer, with Voice_Player.gd.
  • Speech and bark bubbles: an AudioStreamPlayer2D or AudioStreamPlayer3D, with Voice_Player_2D.gd or Voice_Player_3D.gd, so the voice is emitted from the bubble's position.
For Voice mode Voice mode displays nothing on screen, so it has no Speech Display UI Element. Its Lines are spoken by a standalone Voice Player, at voice_player_path in the Engine's ui_elements_paths. This player is the only one that uses its setting overrides (listed on the Voice Mode page). Setting Up Assign each Voice Player the audio bus for voices (e.g. a Voice bus), in the node's bus property, so the voice volume can be adjusted separately from music and sounds. An audio node without a Voice Player script can still be used as a voice_node: it plays voices, but its hook functions and default_voice_extension are lost. Settings
SettingPurpose
default_voice_extensionExtension added to voice files named without one, for the Lines this player speaks. Leave empty to use the Engine's.
Hook Functions The hook functions of a media player are in its script, an 'unsafe' file. Write yours in a copy of the script, attached to your own nodes, or updates will overwrite them (see Customizing UI Elements, on the UI page).
HookCalled
x_playback_starting()Right before voice playback starts.
x_playback_started()Right after voice playback has started.
They're called in every Dialogue Mode, on the Voice Player speaking the Line, whenever a Line plays a voice file or Text-To-Speech. candy_args contains "caller" (the Engine) and "node" (the Voice Player). custom_data is [[line values], [Variation values]]. See UI Elements for how hook functions work. In Voice mode, the Voice Player runs the Line by itself, since no UI Element displays it. There, a third hook function is called on it: x_speech_advance(), when the Line is advanced by the player or by auto-advance. It receives the same arguments. In the other Dialogue Modes, x_speech_advance() is called on the UI Element that displays the Line (see Speech Display).