Candy Logo Copyright © 2025-2026 Candy Arts
Timers
A menu can contain timers, under the Timers key of its Choice_List command. A timer counts down while the menu is open, and when it expires it runs a Block, picks a choice, or both. This is useful for a decision under time pressure: an answer the player must provide within ten seconds, or a hesitation the NPC comments on. Timers aren't visible: a timer is a Timer node, a child of the menu scene's timer_list node. To display a countdown, read the timer from the menu scene (see Menu UI). A Timer Each timer is named, like a category, and has these keys:
KeyEffect
TimeThe duration of the countdown, in seconds. It is evaluated each time the timer starts, so a ¢ expression can read the game state.
AutoStart: the timer starts when the menu opens. Any other value, empty included: the timer waits for a Timer_Status command to start it.
LoopsThe number of countdowns: 1 by default, -1 for a timer that repeats until the menu closes.
TimeoutA Block run as a Bridge each time the timer expires, named by its Conversation, Block and Line keys. Optional.
Timer_ChoicesA choice picked each time the timer expires, written as the category name and the choice name separated by a comma: Main, Stay_Silent. Optional.
SetupA Block run as a Bridge before the menu is built, as for a choice (see Advanced Menus).
TagsTags by which a Timer_Status command selects the timer.
For example, a timer with a Time of 10, Auto set to Start and Timer_Choices set to Main, Stay_Silent picks the Stay_Silent choice of the Main category ten seconds after the menu opens, as if the player had picked it. Expiry When a timer expires, the Engine performs these steps in order:
  • The remaining Loops are decremented.
  • The Timeout Block runs, as a Bridge, with the menu behind its shield (or hidden, with the Timeout's Hide_Menu set to 1).
  • The timer restarts, if countdowns remain.
  • The choice in Timer_Choices is picked, and its action runs as if the player had picked it.
A Timeout Block that ends the Dialogue, or returns from the Block containing the menu, closes the menu without the choice being picked. A choice picked by a timer calls the x_choice_selected() hook function like any pick (see Reacting to Choices). A choice that is disabled when the timer expires is skipped, and the menu stays open. Several Timers A menu can contain any number of timers, each with its own duration, loops and effect. For example, a repeating timer whose Timeout Block has the NPC grow impatient every five seconds, and a single timer that picks a choice after thirty. Timers count down while the menu is displayed. They are paused while the Lines of a pick or of a Timeout run, with the menu behind its shield or hidden, and while the Dialogue is suspended; they resume when the Dialogue returns to the menu. Changing Timers A Timer_Status command, from a Block the menu bridges to, starts, pauses or stops timers, and changes their duration and remaining loops: see Modifying Open Menus. A timer whose Auto isn't Start waits for such a Line: a countdown that only starts once the player has asked a particular question, for example.