TheDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/pompom454/tea/llms.txt
Use this file to discover all available pages before exploring further.
UI API provides methods for opening the dialogs that Tea builds into every story—alert messages, the restart prompt, saves management, and settings—as well as a method for forcing a refresh of the dynamically rendered sections of the UI outside of normal passage navigation.
UI.alert()
Opens the built-in alert dialog and displays a message to the player.The message to display to the player inside the alert dialog.
Options passed through to
Dialog.open(). Pass null to skip. Supports a top property (pixels, default 50) to control vertical position.Top y-coordinate of the dialog in pixels, without a unit suffix.
A callback executed whenever the dialog is closed.
This method does not return a value.
UI.restart()
Opens the built-in restart dialog, which prompts the player to confirm they want to restart the story.Options passed through to
Dialog.open(). Pass null to skip.A callback executed whenever the dialog is closed.
This method does not return a value.
The restart dialog includes Cancel and OK buttons. The engine restart is deferred until after the dialog has fully closed to avoid display race conditions.
UI.saves()
Opens the built-in saves dialog, where players can create, load, and manage save files.Options passed through to
Dialog.open(). Pass null to skip.A callback executed whenever the dialog is closed.
This method does not return a value.
UI.settings()
Opens the built-in settings dialog, which is populated from entries registered with theSetting API.
Options passed through to
Dialog.open(). Pass null to skip.A callback executed whenever the dialog is closed.
This method does not return a value.
UI.update()
Triggers a:uiupdate event that causes all dynamically updated sections of the built-in UI to re-render. This includes sections populated by code passages such as StoryCaption and StoryMenu. It is called automatically during normal passage navigation.
This method does not return a value.
When to use UI.update()
When to use UI.update()
You typically only need
UI.update() when you change story variables or state that affects passages like StoryCaption, StoryMenu, or StoryBanner and you want those sections to reflect the change immediately—without navigating to a new passage. A common case is modifying a variable from a <<link>> macro and then calling UI.update() to reflect the change in the sidebar.