Candy Logo Copyright © 2025-2026 Candy Arts
Choice Menus
Choice menus display the choices of a Choice_List command. Each menu is built from three kinds of scenes, nested inside each other:
SceneContains
MenuThe whole menu: its title, prompt, categories and timers.
CategoryA group of choices, with its own title and prompt.
ButtonOne choice.
Unlike most UI Elements, these scenes aren't placed in your scene in advance: Choice_List creates them for each menu, and removes them once the menu is done. Which scene is used for the menu, each category and each choice is chosen by the Choice_List command, so a single menu can mix different category and button scenes.
  • The menu is instantiated as a child of the node at choices_path, in the Engine's ui_elements_paths. Usually a plain Control covering the screen.
  • Each category is instantiated as a child of its menu's category_list node.
  • Each button is instantiated as a child of its category's button_list node.
Scenes are looked up by file name in the folders set in Candy_Properties.gd: choice_menus_folder, choice_categories_folder and choice_buttons_folder. Menus in Dialogues A Choice_List command follows the same nesting as the scenes: the menu contains categories under its Categories key, and each category contains choices under its Choices key. The shipped Default.tscn scenes are used for the menu, the category and the buttons whenever a scene key is left empty. Writing menus, their choices, conditions and timers is covered in Choices. Layout Since categories and buttons are added at runtime, category_list and button_list are usually Containers (VBoxContainer, HBoxContainer, GridContainer...), which lay them out automatically. Add a ScrollContainer around them if a menu may contain more than fits on screen. Translations Menu titles and prompts, category titles and prompts, and button labels and tooltips are translated through Localization Tables, in User_Data/Localization_Tables:
TextTable
Menu title / promptchoice_menu_titles / choice_menu_prompts
Category title / promptchoice_category_titles / choice_category_prompts
Button label / tooltipchoice_button_labels / choice_button_tooltips
The text written in the Choice_List command is looked up in the table. If the table has an entry for it in the Engine's current language, that entry is displayed; otherwise the text is displayed as written. Nested Menus A choice can open another Choice_List. By default, the older menu is hidden while the newer one is open, and shown again when the Dialogue returns to it. This is decided by the Engine's hide_choice_lists setting, and by each menu's never_hide setting and deactivate() / reactivate() functions (see Menu UI). The Engine waits for both functions, so a menu can play an animation when it's hidden and when it's displayed again.