Menu UI
The Menu UI is the root scene of a choice menu: it contains the menu's title and prompt, its categories, and its timers. See Choice Menus for how menus are built.
- Script: Choice_Menu.gd
- Templates: Scenes/Choice_Menus
- Updates: the script is 'unsafe', and so is every template except Default.tscn (see Customizing UI Elements, on the UI page)
Nodes
| Variable | Node |
| category_list | Required. The parent node of the categories. |
| timer_list | Required for menus with timers. The parent node of the menu's Timer nodes. Any node is accepted: timers aren't visible. |
| title_node | Optional. A Label or RichTextLabel for the menu's title. |
| prompt_node | Optional. A Label or RichTextLabel for the menu's prompt. |
| shield | Optional. A node displayed over the menu once a choice is selected or a timer runs out (see below). |
| Setting | Purpose |
| never_hide | Leaves this menu visible when a nested menu opens over it. A Hide_Menu transition still hides it. |
| Hook | Called |
| x_initialization_finished() | Once the menu, its categories and its buttons are all initialized, before its timers start. |
| x_menu_closing() | When a selected choice is about to close the menu, while the menu is still shown. |
[[menu values]]: the Choice_List command's Custom Data. See UI Elements for how hook functions work.
x_menu_closing() also receives the choice that closes the menu: "category" and "choice" (their names), "button" (the choice's button) and "finish" (its Finish type, in lowercase).
Animating the Menu
The Engine waits for four functions of the menu to return. An animation played and awaited in one of them is therefore over before the Dialogue carries on:
| Animation | Where to play it |
| The menu appears | x_initialization_finished(). The menu's timers only start once it has returned. |
| The menu closes | x_menu_closing(). The choice's Finish transition only runs once it has returned. The menu is hidden right after, then deleted. |
| A nested menu opens over it | deactivate(). The nested menu is only built once it has returned. |
| A transition with Hide_Menu on hides it | deactivate(). The transition's Lines only run once it has returned. |
| The Dialogue returns to it | reactivate(). The menu's timers only resume once it has returned. This is also how the menu returns after a Hide_Menu transition's Lines. |
func x_menu_closing(candy_args: Dictionary, user_args: Array, custom_data: Array):
var tween := create_tween()
tween.tween_property(self, "modulate:a", 0.0, 0.3)
await tween.finished
- x_menu_closing() is called for the Finish types that close the menu: Bridge, Jump, Return, End and Close. Continue leaves the menu open, so it isn't called.
- While it runs, the menu's timers are paused, its buttons can't be focused, and a click on a button is ignored.
- A menu that ends with its Dialogue is deleted at once, with no animation: the Dialogue ends or is interrupted, or a Jump written in other Lines leaves the menu behind. The same applies to a menu behind its shield, when the Lines of a Continue or Timeout transition end the Dialogue or return from the Block.
- End deactivate() with visible set to false. A menu left visible is deactivated a second time by the same Choice_List.
- The shield is up while a choice's Lines run. Your deactivate() and reactivate() animations play under it.
Customizable Functions
These functions are in the UI Element's script, an 'unsafe' file. To change them, work in a copy of the script, attached to your own scenes, or updates will overwrite your changes (see Customizing UI Elements, on the UI page).
Candy Dialogue Engine calls these functions, whose default behavior is minimal. Modify them in the script to implement your own behavior:
| Function | Called / Default |
| deactivate(custom_data) | When a nested menu opens over this one (if the Engine's hide_choice_lists is on, and the menu's never_hide is off), and before the Lines of a transition with Hide_Menu on. Hides the menu. The Engine waits for it (see Animating the Menu). |
| reactivate(custom_data) | When the Dialogue returns to this menu, and once a Hide_Menu transition's Lines are done. Shows the menu. The Engine waits for it. |
| setup(custom_data) | Once the menu's data is assigned. Displays its title and prompt. |
| refresh_language() | When the Engine's refresh_language() is called while the menu is open. Displays its title and prompt again in the current language, then calls refresh_language() on each category (see Translating UI Texts). |
Copyright © 2025-2026 Candy Arts