Copyright © 2025-2026 Candy ArtsAdvanced Menus
Beyond a list of choices, a Choice_List command can contain several categories the player navigates between, choices that depend on the game state, Blocks that prepare the menu, and a scene of its own at each level. Every key is described in Choice List.
Navigation
Categories group choices, and one category is displayed at a time. The menu's Main key names the category displayed first; when it's empty, the first category is displayed. A choice's Navigate key names the category displayed when the choice is picked: the current category is hidden, and the named one is displayed in its place.
This builds a menu with sub-menus. For example, a Main category whose Trade choice has Trade in its Navigate key and no Finish type, and a Trade category whose Back choice navigates to Main the same way. The Buy and Sell choices of the Trade category lead to Blocks, as usual.
A choice can navigate and lead to a Block at once: the category switches first, then the action runs. With a Continue action, the Dialogue returns to the new category.
Each category has a Title and a Prompt of its own, displayed by its category scene. The menu's Title and Prompt are passed to every category as well.
Conditional Choices
Three keys of a choice accept a ¢ expression (see CandyRef Expressions), evaluated when the menu is built:
| Key | Effect |
| Enabled | When false, the choice has no button: it is left out of the menu. |
| Active | When false, the button is displayed, but can't be picked. |
| Invisible | When true, the button is hidden. |
¢globals.gold >= 50 in its Active key is displayed, but can only be picked with enough gold, and a choice with ¢candy_de.flags.met_alice in its Enabled key is offered only once the flag is set (see Flags).
The expressions are evaluated once, when the button is created. To change a choice while the menu is open, use a Choice_Status command (see Modifying Open Menus).
Setup Blocks
The menu, each category, each choice and each timer accept a Setup key: a Block run as a Bridge before the menu is built, to prepare it. A Setup computes the values the choices' conditions read, or assigns the variables their labels display, for example. The Block is named by the Conversation, Block and Line keys of the Setup; a Setup with all three empty is skipped.
A choice's Setup runs before its button is created. For a choice whose Enabled is false, that is when a Choice_Status command enables it, not when the menu is built.
Scenes
The Menu_Scene, Category_Scene and Button_Scene keys of the menu name the scenes it's built from, by file name in the folders set in Candy_Properties.gd (choice_menus_folder, choice_categories_folder and choice_buttons_folder). Each category can name a Category_Scene and a Button_Scene of its own, and each choice a Button_Scene: the most specific level applies, and an empty key defers to the level above. A single menu can therefore mix button scenes: a plain button for most choices and a highlighted one for the choice that ends the conversation.
When every scene key is empty, the shipped Default.tscn scenes serve at every level. Designing scenes of your own is explained in Choice Menus.
Nested Menus
The Block a choice leads to can open another Choice_List. The first menu is hidden while the new one is open, and displayed again when the Dialogue returns to it: after a Continue choice of the first menu whose Block opened the second, for example.
The Engine's hide_choice_lists setting decides whether older menus are hidden, and a menu scene's never_hide setting leaves that menu visible regardless (see Menu UI).
The Shield
Two transitions run Lines while the menu stays open: a Continue choice's Block, and a timer's Timeout Block. During those Lines, the menu is masked by its shield, a node of the menu scene that blocks clicks and keyboard focus, so a Spoken Line can play in front of the menu without the player picking another choice meanwhile. The shield is removed when the Dialogue returns to the menu.
To hide the menu altogether during those Lines, set Hide_Menu to 1. The key exists at three levels, the most specific applying: the choice's Finish or the timer's Timeout, the category, and the menu. Left at null, a level defers to the next; a Finish set to Menu skips the category and applies the menu's value. A hidden menu is displayed again when the Dialogue returns to it.
Mouse Modes
A menu usually needs a visible cursor, while the game around it may capture the mouse. The category's Mouse key sets the mouse mode applied while the category is displayed: Visible, Hidden, Captured, Confined or Confined_Hidden; Default applies the Engine's mouse_mode_choice setting, and Menu applies the menu's own Mouse key. When the menu closes, the mouse mode from before it opened is restored.
Tags
The menu, each category, each choice and each timer accept a Tags key: a comma-separated list of words, such as shop, merchant. Tags have no effect on the menu itself. They designate what a Choice_Status or Timer_Status command modifies (see Modifying Open Menus): a tag shared by several choices selects them all at once. Tags are matched whole, case-insensitively.