Copyright © 2025-2026 Candy ArtsChoice List
The Choice_List command displays a choice menu and pauses the Dialogue until the player picks a choice or a timer runs out. The menu is assembled from a menu scene, a category scene for each group of choices, and a button scene for each choice. A choice can switch to another category, bridge to a Block and return to the menu, jump elsewhere, or close the menu. Optional timers count down while the menu is open, and can pick a choice or bridge to a Block when they expire. See Choice Menus. Each time a choice is picked, the x_choice_selected() hook is called, so your code can respond to it. See Hook Functions.
Keys
Every key also accepts a ¢ expression instead of a fixed value, unless its description says otherwise. See CandyRef Expressions.
Menu Keys
The Command's top-level keys apply to the whole menu.
Menu_Scene
Description:
The scene of the choice menu.
Values:
• Scene name: A scene in choice_menus_folder (Candy_Properties.gd), such as Shop. The .tscn extension is added when missing.
• res:// or user:// path: Loaded from that path.
• Empty: Default.tscn.
Category_Scene
Description:
The scene instantiated for every category, unless a category specifies its own.
Values:
• Scene name: A scene in choice_categories_folder (Candy_Properties.gd), such as Shop. The .tscn extension is added when missing.
• res:// or user:// path: Loaded from that path.
• Empty: Default.tscn.
Button_Scene
Description:
The scene instantiated for every choice button, unless its category or the choice specifies its own.
Values:
• Scene name: A scene in choice_buttons_folder (Candy_Properties.gd), such as Shop. The .tscn extension is added when missing.
• res:// or user:// path: Loaded from that path.
• Empty: Default.tscn.
Title
Description:
A title, passed to the menu and to every category.
Values:
• Text
• Empty: No title.
Prompt
Description:
A prompt, passed to the menu and to every category.
Values:
• Text
• Empty: No prompt.
Tags
Description:
Tags by which Choice_Status and Timer_Status (with their Menu_Mode set to Tags) select this menu. They are matched whole and case-insensitively.
Values:
• Tags: A comma-separated list, such as shop, merchant.
• Empty: No tags.
Main
Description:
The category displayed first.
Values:
• Category name
• Empty, or a category that doesn't exist: The first category.
Mouse
Description:
The mouse mode applied while a category whose own Mouse is set to Menu is displayed. The value is case-insensitive.
Values:
• Default: The Engine's mouse_mode_choice.
• Visible: The cursor is visible and free.
• Hidden: The cursor is hidden but free.
• Captured or Locked: The cursor is hidden and locked to the window.
• Confined: The cursor is visible and confined to the window.
• Confined_Hidden: The cursor is hidden and confined to the window.
• Empty: The mouse mode is unchanged.
Hide_Menu
Description:
Whether the menu is hidden while the Lines of a Continue choice or of a timer's Timeout run. Otherwise the menu stays on screen during them, masked by its shield, which Blocks it. Every category, and every timer, uses this value unless it sets its own: a choice's Finish and a timer's Timeout can override it, and so can a category, for its choices. The menu is hidden through its deactivate() function and shown again through reactivate(), so their animations play (see Menu UI). While the Lines run, the menu stays hidden, even if they open and close other menus.
Values:
• 1: Hide the menu.
• 0: Leave it displayed, behind its shield (the default).
Setup
Description:
A Block run as a Bridge before the menu is built, to prepare it. It is skipped if Conversation, Block and Line are all empty.
Values:
• Conversation: The Conversation containing the Block to run. Empty for the current Conversation.
• Block: The Block to run. Empty for the current Block.
• Line: The Line to start from, as an index counted from 0 or an LM reference. Empty for the first Line.
• Type: How the Block runs. Only Bridge is accepted, which runs the Block and then returns.
Categories
Description:
The menu's groups of choices. Each entry is named after its category, which is also the category's node name, so the name can't contain . : @ / % or ". It contains the category's settings (see below).
Values:
• Category name: Such as Main or Items.
Timers
Description:
Countdowns that run while the menu is open. Each entry is named after its timer, which is also the timer's node name, and contains the timer's settings (see below).
Values:
• Timer name: Such as Hurry.
Category Settings
Each category in Categories accepts the following keys.
Category_Scene
Description:
The category's scene.
Values:
• Scene name: A scene in choice_categories_folder (Candy_Properties.gd), such as Shop. The .tscn extension is added when missing.
• res:// or user:// path: Loaded from that path.
• Empty: The menu's Category_Scene.
Button_Scene
Description:
The scene instantiated for this category's choice buttons, unless a choice specifies its own.
Values:
• Scene name: A scene in choice_buttons_folder (Candy_Properties.gd), such as Shop. The .tscn extension is added when missing.
• res:// or user:// path: Loaded from that path.
• Empty: The menu's Button_Scene.
Title
Description:
The category's title.
Values:
• Text
• Empty: No title.
Prompt
Description:
The category's prompt.
Values:
• Text
• Empty: No prompt.
Tags
Description:
Tags by which Choice_Status (with its Category_Mode set to Tags or All) selects this category. They are matched whole and case-insensitively.
Values:
• Tags: A comma-separated list, such as shop, merchant.
• Empty: No tags.
Mouse
Description:
The mouse mode applied while this category is displayed. The value is case-insensitive.
Values:
• Default: The Engine's mouse_mode_choice.
• Visible: The cursor is visible and free.
• Hidden: The cursor is hidden but free.
• Captured or Locked: The cursor is hidden and locked to the window.
• Confined: The cursor is visible and confined to the window.
• Confined_Hidden: The cursor is hidden and confined to the window.
• Menu: The menu's Mouse.
• Empty: The mouse mode is unchanged.
Hide_Menu
Description:
Whether the menu is hidden while the Lines of this category's Continue choices run, instead of the menu's Hide_Menu. Each choice uses this value unless its Finish sets its own.
Values:
• 1: Hide the menu.
• 0: Leave it displayed, behind its shield.
• null: The menu's Hide_Menu (the default).
Setup
Description:
A Block run as a Bridge before the menu is built, to prepare it. It is skipped if Conversation, Block and Line are all empty.
Values:
• Conversation: The Conversation containing the Block to run. Empty for the current Conversation.
• Block: The Block to run. Empty for the current Block.
• Line: The Line to start from, as an index counted from 0 or an LM reference. Empty for the first Line.
• Type: How the Block runs. Only Bridge is accepted, which runs the Block and then returns.
Choices
Description:
The category's choices. Each entry is named after its choice, which is also the name of the choice's button node and, when Label is empty, its text. It contains the choice's settings (see below).
Values:
• Choice name: Such as Buy.
Choice Settings
Each choice in Choices accepts the following keys.
Label
Description:
The button's text.
Values:
• Text
• Empty: The choice's name.
Tooltip
Description:
The button's tooltip.
Values:
• Text
• Empty: No tooltip.
Button_Scene
Description:
The choice's button scene.
Values:
• Scene name: A scene in choice_buttons_folder (Candy_Properties.gd), such as Shop. The .tscn extension is added when missing.
• res:// or user:// path: Loaded from that path.
• Empty: The category's Button_Scene.
Tags
Description:
Tags by which Choice_Status (with its Choice_Mode set to Tags or All) selects this choice. They are matched whole and case-insensitively.
Values:
• Tags: A comma-separated list, such as shop, merchant.
• Empty: No tags.
Enabled
Description:
Whether a button is created for the choice. It is evaluated when the menu is built; once the menu is open, use Choice_Status to change it.
Values:
• 1: Create the button.
• 0: Don't create a button. Choice_Status can enable the choice later.
• Empty: 1.
Active
Description:
Whether the button can be picked. It is evaluated when the button is created.
Values:
• 1: The button can be picked.
• 0: The button is displayed, but can't be picked.
• Empty: 1.
Invisible
Description:
Whether the button is hidden. It is evaluated when the button is created.
Values:
• 0: The button is visible.
• 1: The button is hidden.
• Empty: 0.
Navigate
Description:
A category to switch to when the choice is picked. The current category is hidden, and the new one is displayed with its own Mouse mode.
Values:
• Category name
• Empty: The current category remains displayed.
Setup
Description:
A Block run as a Bridge before the choice's button is created, either when the menu is built or, for a choice that starts disabled, when Choice_Status enables it, to prepare it. It is skipped if Conversation, Block and Line are all empty.
Values:
• Conversation: The Conversation containing the Block to run. Empty for the current Conversation.
• Block: The Block to run. Empty for the current Block.
• Line: The Line to start from, as an index counted from 0 or an LM reference. Empty for the first Line.
• Type: How the Block runs. Only Bridge is accepted, which runs the Block and then returns.
Finish
Description:
The effect of picking the choice: an action set in Type, and a target Block for the actions that need one. A choice whose action needs a target but doesn't have one only switches category (see Navigate), and the menu stays open.
Values:
• Type: The action (see below).
• Conversation: The Conversation containing the target Block. Empty for the current Conversation.
• Block: The target Block. Empty for the current Block.
• Line: The Line to start from, as an index counted from 0 or an LM reference. Empty for the first Line.
• Levels: For the Return action, how many bridged Blocks to unwind, as with the Return Command. Empty for 1.
• Hide_Menu: For the Continue action, whether the menu is hidden while the target runs (see below).
Type
Description:
The action performed when the choice is picked, set inside Finish. The value is case-insensitive.
Values:
• Continue: Bridge to the target, then return to the menu, which stays open.
• Bridge: Hide the menu and bridge to the target. When the target returns, close the menu and continue after the Choice_List.
• Jump: Close the menu and jump to the target.
• Return: Close the menu and return Levels Blocks. No target needed.
• End: Close the menu and end the Dialogue. No target needed.
• Close: Close the menu and continue after the Choice_List. No target needed.
• Empty: No action. The menu stays open, and only Navigate applies.
Hide_Menu (Finish)
Description:
For the Continue action, whether the menu is hidden while the target runs, set inside Finish. It overrides the category's Hide_Menu and the menu's. The other actions hide or close the menu anyway, so it does nothing for them.
Values:
• 1: Hide the menu.
• 0: Leave it displayed, behind its shield.
• Menu: The menu's Hide_Menu, whatever the category's.
• null: The category's Hide_Menu (the default), which is the menu's unless the category sets its own.
Timer Settings
Each timer in Timers accepts the following keys.
Time
Description:
The duration of the countdown. It is evaluated each time the timer starts.
Values:
• Number of seconds: Such as 10.
• Empty: 0.
Auto
Description:
Whether the timer starts when the menu opens. The value is case-sensitive.
Values:
• Start: Start the timer when the menu opens.
• Any other value, such as Hold: Wait for a Timer_Status to start the timer.
• Empty: Wait for a Timer_Status to start the timer.
Loops
Description:
The number of times the timer counts down and expires. It is evaluated once, when the menu opens. Each expiry decrements the count before the Timeout Block runs.
Values:
• Positive number: That many countdowns.
• -1: Repeat indefinitely.
• 0 or empty: 1.
Tags
Description:
Tags by which Timer_Status (with its Timer_Mode set to Tags or All) selects this timer. They are matched whole and case-insensitively.
Values:
• Tags: A comma-separated list, such as shop, merchant.
• Empty: No tags.
Setup
Description:
A Block run as a Bridge before the menu is built, to prepare it. It is skipped if Conversation, Block and Line are all empty.
Values:
• Conversation: The Conversation containing the Block to run. Empty for the current Conversation.
• Block: The Block to run. Empty for the current Block.
• Line: The Line to start from, as an index counted from 0 or an LM reference. Empty for the first Line.
• Type: How the Block runs. Only Bridge is accepted, which runs the Block and then returns.
Timeout
Description:
A Block run as a Bridge each time the timer expires. Optional.
Values:
• Conversation: The Conversation containing the Block to run. Empty for the current Conversation.
• Block: The Block to run. Empty for the current Block.
• Line: The Line to start from, as an index counted from 0 or an LM reference. Empty for the first Line.
• Hide_Menu: Whether the menu is hidden while the Block runs: 1 to hide it, 0 to leave it displayed behind its shield, or null or Menu (the default) for the menu's Hide_Menu. A timer belongs to the menu, not to a category, so no category's applies.
Timer_Choices
Description:
A choice picked automatically each time the timer expires. A disabled choice is skipped.
Values:
• Category, Choice: The category name and the choice name, separated by a comma, such as Main, Wait.
• [Category, Choice]: The same, enclosed in brackets.
• Empty: No choice is picked.