ui
Windows, overlays, notifications, hotkeys, themes and icons: everything under ui.
ui
The GUI library: the menu (windows you click), overlays (panels you only read) and notifications.
Type name: WaxUI.
| Member | Type | Description |
|---|---|---|
Icons | WaxIcons | Icon names: the bundled Lucide set ("shield", "wrench", "map-pin" ...) plus images that mods register. |
Notifications | WaxNotifications | |
Debug | WaxDebugPanel | The in-game debug panel. |
| Signal | Handler receives | Description |
|---|---|---|
Opened | nothing | Fires when the menu opens. |
Closed | nothing | Fires when the menu closes. |
KeyChanged | key: string? | Fires with the new menu key. |
ThemeChanged | name: string | Fires with the theme's name after SetTheme or ResetTheme. |
ui.Open()
Opens the menu: windows appear and the mouse is freed to use them.
ui.Open()Returns nothing.
ui.Close()
Closes the menu and gives the mouse back to the game.
ui.Close()Returns nothing.
ui.Toggle()
Opens the menu when it is closed, and closes it when it is open.
ui.Toggle()Returns nothing.
ui.Copy(text)
Puts text on the clipboard, for pasting anywhere.
ui.Copy(text: any)| Parameter | Type |
|---|---|
text | any |
Returns nothing.
ui.IsOpen()
True while the menu is open.
ui.IsOpen(): booleanReturns boolean
ui.SetPreview(on)
Shows the windows without taking the mouse (for screenshots and for looking while you play).
ui.SetPreview(on: boolean)| Parameter | Type |
|---|---|
on | boolean |
Returns nothing.
ui.IsPreview()
True while the windows are shown in preview.
ui.IsPreview(): booleanReturns boolean
ui.SetToggleKey(key)
Sets the key that opens and closes the menu, by the engine's key name ("F8"). nil leaves the menu without a key.
ui.SetToggleKey(key: string?)| Parameter | Type |
|---|---|
key | string? |
Returns nothing.
ui.GetToggleKey()
The key that opens and closes the menu.
ui.GetToggleKey(): string?Returns string?
ui.Window(options?)
Creates a window in the menu. It is removed again when the mod reloads.
ui.Window(options?: WaxWindowOptions): WaxWindow| Parameter | Type |
|---|---|
options (optional) | WaxWindowOptions |
Returns WaxWindow
ui.Overlay(options?)
Creates a panel pinned to the screen that stays up during play and lets clicks through.
ui.Overlay(options?: WaxOverlayOptions): WaxOverlay| Parameter | Type |
|---|---|
options (optional) | WaxOverlayOptions |
Returns WaxOverlay
ui.Tag(target, options?)
Puts a line of text over an actor, over one part of an actor, or on a spot in the world. It follows what it is on, shows through walls, and tags that would cover each other pile up. The tag goes away by itself when the actor does.
ui.Tag(target: WaxInstance|{ X: number, Y: number, Z: number }, options?: WaxTagOptions): WaxTag| Parameter | Type |
|---|---|
target | WaxInstance | { X: number, Y: number, Z: number } |
options (optional) | WaxTagOptions |
Returns WaxTag
ui.Notify(text, options?)
Shows a short message in a corner of the screen. Sending the same message again restarts the one already showing.
ui.Notify(text: any, options?: WaxNotifyOptions): WaxNotification| Parameter | Type |
|---|---|
text | any |
options (optional) | WaxNotifyOptions |
Returns WaxNotification
ui.Windows()
A list of every window.
ui.Windows(): WaxWindow[]Returns WaxWindow[]
ui.Hotkey(key, callback, options?)
Runs callback when the key is pressed during play. The hotkey is removed when the mod reloads.
ui.Hotkey(key: string, callback: fun(), options?: WaxHotkeyOptions): WaxHotkey| Parameter | Type | Description |
|---|---|---|
key | string | An engine key name such as "F6", "K" or "MiddleMouseButton" (a Keybind control gives you these). |
callback | fun() | |
options (optional) | WaxHotkeyOptions |
Returns WaxHotkey
ui.MinScale()
The smallest scale that still draws text at a readable size on this screen.
ui.MinScale(): numberReturns number
ui.SetScale(scale)
Sets the interface size, where 1 is normal. The size is kept between ui.MinScale() and 2, and the size applied is returned.
ui.SetScale(scale: number): number| Parameter | Type |
|---|---|
scale | number |
Returns number (applied)
ui.GetScale()
The interface size in use.
ui.GetScale(): numberReturns number
ui.SetTheme(theme)
Switches to a named theme, or changes single settings from a table. Everything on screen takes the new colours in place, so no window is rebuilt and no mod is reloaded. Sizes and shapes apply to what is built afterwards.
ui.SetTheme(theme: WaxThemeName|WaxThemeSettings)| Parameter | Type |
|---|---|
theme | WaxThemeName | WaxThemeSettings |
Returns nothing.
ui.ResetTheme()
Puts every theme setting back to the "Midnight" defaults.
ui.ResetTheme()Returns nothing.
ui.Themes()
The names of the built-in themes, then of the ones added with AddTheme.
ui.Themes(): string[]Returns string[]
ui.AddTheme(name, colors)
Adds a theme: a table with any of the colour settings (window, panel, raised, text, accent ...) as "#RRGGBB".
ui.AddTheme(name: string, colors: WaxThemeSettings)| Parameter | Type |
|---|---|
name | string |
colors | WaxThemeSettings |
Returns nothing.
ui.ThemeName()
The name of the theme in use.
ui.ThemeName(): stringReturns string
ui.Color(hex, alpha?)
Makes a colour from "#RRGGBB" or 0xRRGGBB, with an optional alpha of 0..1.
ui.Color(hex: string|integer, alpha?: number): WaxColor| Parameter | Type |
|---|---|
hex | string | integer |
alpha (optional) | number |
Returns WaxColor
ui.Theme()
The table of the theme in use. Its colours follow the theme, so pass them as they are (color = ui.Theme().accent).
ui.Theme(): WaxThemeReturns WaxTheme
ui.AddSettings(container)
Adds the menu's own settings (key, theme, accent, animation, size) to a container, such as a "Settings" page.
ui.AddSettings(container: WaxContainer)| Parameter | Type |
|---|---|
container | WaxContainer |
Returns nothing.
ui.Notifications
Type name: WaxNotifications.
ui.Notifications.SetCorner(name)
Moves notifications to another corner of the screen, closing the ones showing.
ui.Notifications.SetCorner(name: WaxCorner)| Parameter | Type |
|---|---|
name | WaxCorner |
Returns nothing.
ui.Notifications.SetLimit(count)
Sets how many notifications show at once (at least 1).
ui.Notifications.SetLimit(count: number)| Parameter | Type |
|---|---|
count | number |
Returns nothing.
ui.Notifications.Clear()
Closes every notification.
ui.Notifications.Clear()Returns nothing.
ui.Notifications.Count()
How many notifications are showing.
ui.Notifications.Count(): integerReturns integer
ui.Icons
Icon names: the bundled Lucide set ("shield", "wrench", "map-pin" ...) plus images that mods register.
Type name: WaxIcons.
ui.Icons.Names()
Every icon name, sorted. The menu's Icons page shows them.
ui.Icons.Names(): string[]Returns string[]
ui.Icons.Has(name)
True when there is an icon with this name.
ui.Icons.Has(name: string): boolean| Parameter | Type |
|---|---|
name | string |
Returns boolean
ui.Icons.Find(text?, limit?)
Names containing the text, at most limit of them (every name when the text is empty).
ui.Icons.Find(text?: string, limit?: integer): string[]| Parameter | Type |
|---|---|
text (optional) | string |
limit (optional) | integer |
Returns string[]
ui.Icons.Register(name, file)
Adds an icon from a PNG file. White on transparent works best, because the icon is tinted when drawn.
ui.Icons.Register(name: string, file: string)| Parameter | Type |
|---|---|
name | string |
file | string |
Returns nothing.
ui.Debug
The in-game debug panel.
Type name: WaxDebugPanel.
ui.Debug.Page(name, options?)
Adds a page to the debug panel for the calling mod. The page is removed when the mod reloads.
ui.Debug.Page(name: string, options?: WaxPageOptions): WaxPage| Parameter | Type |
|---|---|
name | string |
options (optional) | WaxPageOptions |
Returns WaxPage
ui.Debug.Window()
The debug panel's window, or nil while the panel is not running.
ui.Debug.Window(): WaxWindow?Returns WaxWindow?
ui.Debug.Show()
Shows the debug panel and opens the menu.
ui.Debug.Show()Returns nothing.
WaxPage
A page of a window that has navigation. It is a container for controls.
It can also do everything WaxContainer can. You get one from window:Page, ui.Debug.Page.
| Signal | Handler receives | Description |
|---|---|---|
NearEnd | nothing | Fires while the end of the page is in view: when the user scrolls close to the bottom, and a few times a second while the page is not full. Add more content in the handler, or do nothing when there is no more. |
WaxWindow
A window in the menu. Controls added to it go into its body, or into a first page called "Main" when it has pages.
It can also do everything WaxContainer can. You get one from ui.Debug.Window, ui.Window, ui.Windows. Below, window stands for one of these.
| Signal | Handler receives | Description |
|---|---|---|
Opened | nothing | Fires when the window is shown. |
Closed | nothing | Fires when the window is hidden. |
PageChanged | name: string | Fires with the name of the page that was selected. |
window:SetTitle(title)
Changes the text in the title bar.
window:SetTitle(title: string)| Parameter | Type |
|---|---|
title | string |
Returns nothing.
window:SetPosition(x, y)
Moves the window, keeping it on the screen.
window:SetPosition(x: number, y: number)| Parameter | Type |
|---|---|
x | number |
y | number |
Returns nothing.
window:SetSize(width, height)
Resizes the window, no smaller than its minimum size.
window:SetSize(width: number, height: number)| Parameter | Type |
|---|---|
width | number |
height | number |
Returns nothing.
window:SetNavWidth(width)
Sets the width of the navigation column of a window made with nav = "side".
window:SetNavWidth(width: number)| Parameter | Type |
|---|---|
width | number |
Returns nothing.
window:Show()
Shows the window, in front of the others.
window:Show()Returns nothing.
window:Hide()
Hides the window. Hiding the last one closes the menu.
window:Hide()Returns nothing.
window:SetVisible(shown)
Shows or hides the window.
window:SetVisible(shown: boolean)| Parameter | Type |
|---|---|
shown | boolean |
Returns nothing.
window:IsVisible()
True while the window is shown.
window:IsVisible(): booleanReturns boolean
window:SetMinimized(minimized)
Minimises the window to its title bar, or restores it.
window:SetMinimized(minimized: boolean)| Parameter | Type |
|---|---|
minimized | boolean |
Returns nothing.
window:IsMinimized()
True while the window is minimised.
window:IsMinimized(): booleanReturns boolean
window:StatusBar(text?)
Adds a status line along the bottom of the window, or returns the one the window already has. text sets its message.
window:StatusBar(text?: any): WaxStatusBar| Parameter | Type |
|---|---|
text (optional) | any |
Returns WaxStatusBar
window:Destroy()
Removes the window and everything on it.
window:Destroy()Returns nothing.
window:Page(name, options?)
Adds a page to a window made with nav = "side" or "top". The first page added is selected.
window:Page(name: string, options?: WaxPageOptions): WaxPage| Parameter | Type |
|---|---|
name | string |
options (optional) | WaxPageOptions |
Returns WaxPage
window:RemovePage(page)
Removes a page made with Page, with everything on it.
window:RemovePage(page: WaxPage)| Parameter | Type |
|---|---|
page | WaxPage |
Returns nothing.
window:SelectPage(name)
Switches to the page with this name.
window:SelectPage(name: string)| Parameter | Type |
|---|---|
name | string |
Returns nothing.
WaxStatusBar
The line along the bottom of a window that Window:StatusBar returns.
You get one from window:StatusBar. Below, statusBar stands for one of these.
statusBar:Set(message?, options?)
Shows a message and removes the busy indicator.
statusBar:Set(message?: any, options?: WaxStatusOptions)| Parameter | Type |
|---|---|
message (optional) | any |
options (optional) | WaxStatusOptions |
Returns nothing.
statusBar:Busy(message?)
Shows a message with a turning indicator beside it, until the next Set.
statusBar:Busy(message?: any)| Parameter | Type |
|---|---|
message (optional) | any |
Returns nothing.
statusBar:Progress(amount?)
Shows a thin progress line across the top of the bar. amount is 0..1, and nil hides the line.
statusBar:Progress(amount?: number)| Parameter | Type |
|---|---|
amount (optional) | number |
Returns nothing.
statusBar:Right(message?)
Shows text at the right-hand end of the bar.
statusBar:Right(message?: any)| Parameter | Type |
|---|---|
message (optional) | any |
Returns nothing.
statusBar:Clear()
Empties the message and hides the progress line.
statusBar:Clear()Returns nothing.
WaxOverlay
A panel pinned to the screen that stays up during play and never takes the mouse.
It can also do everything WaxContainer can. You get one from ui.Overlay. Below, overlay stands for one of these.
overlay:SetVisible(shown)
Shows or hides the overlay.
overlay:SetVisible(shown: boolean)| Parameter | Type |
|---|---|
shown | boolean |
Returns nothing.
overlay:IsVisible()
True while the overlay is shown.
overlay:IsVisible(): booleanReturns boolean
overlay:SetAnchor(anchor, x?, y?)
Pins the overlay somewhere else. x and y keep their values when omitted.
overlay:SetAnchor(anchor: WaxAnchor, x?: number, y?: number)| Parameter | Type |
|---|---|
anchor | WaxAnchor |
x (optional) | number |
y (optional) | number |
Returns nothing.
overlay:Destroy()
Removes the overlay and everything on it.
overlay:Destroy()Returns nothing.
WaxNotification
You get one from ui.Notify. Below, notification stands for one of these.
notification:SetText(text)
Replaces the text.
notification:SetText(text: any)| Parameter | Type |
|---|---|
text | any |
Returns nothing.
notification:SetTitle(title)
Replaces the title. Does nothing on a notification made without one.
notification:SetTitle(title: string)| Parameter | Type |
|---|---|
title | string |
Returns nothing.
notification:SetProgress(amount)
Shows how far a task is, 0..1, in place of the countdown. The notification then stays until closed.
notification:SetProgress(amount: number)| Parameter | Type |
|---|---|
amount | number |
Returns nothing.
notification:Close()
Closes the notification.
notification:Close()Returns nothing.
WaxTag
A line of text that stays over something in the world.
You get one from ui.Tag. Below, tag stands for one of these.
| Property | Type | Description |
|---|---|---|
Instance | WaxInstance? | What the tag is on. nil for a tag on a spot. |
tag:Set(text)
tag:Set(text: string)| Parameter | Type |
|---|---|
text | string |
Returns nothing.
tag:SetColor(color)
tag:SetColor(color: WaxColor|string)| Parameter | Type |
|---|---|
color | WaxColor | string |
Returns nothing.
tag:SetRange(metres)
tag:SetRange(metres: number)| Parameter | Type |
|---|---|
metres | number |
Returns nothing.
tag:Remove()
Takes the tag off. Safe to call twice, and after the thing it was on is gone.
tag:Remove()Returns nothing.
WaxHotkey
You get one from ui.Hotkey. Below, hotkey stands for one of these.
hotkey.Disconnect()
Stops the hotkey.
hotkey.Disconnect()Returns nothing.
hotkey:SetKey(key)
Changes the key it reacts to.
hotkey:SetKey(key: string)| Parameter | Type |
|---|---|
key | string |
Returns nothing.
WaxUnknownOption
Stands for any key an options table does not list, so that the editor reports a misspelt option.
WaxOptions
The base of every options table.
| Option | Type | Description |
|---|---|---|
any other key ([string]) | WaxUnknownOption | Stands for any key an options table does not list, so that the editor reports a misspelt option. |
WaxColor
A colour in the linear form the engine uses. Make one with ui.Color.
Returned by ui.Color. Used by tag:SetColor, label:SetColor, progress:SetColor, field:SetColor.
| Field | Type |
|---|---|
R | number |
G | number |
B | number |
A | number |
WaxTheme
The theme in use. Its colours change in place when the theme changes, so a colour taken from here (ui.Theme().good) follows the theme wherever you used it. Change the theme with ui.SetTheme, not by writing to this table.
Returned by ui.Theme.
| Field | Type | Description |
|---|---|---|
window | WaxColor | Window background. |
outline | WaxColor | Window outline. |
panel | WaxColor | Text boxes, dropdown lists and consoles. |
card | WaxColor | Section background. |
card_line | WaxColor | Section outline. |
raised | WaxColor | Buttons and tracks. |
hover | WaxColor | A colour in the linear form the engine uses. Make one with ui.Color. |
press | WaxColor | A colour in the linear form the engine uses. Make one with ui.Color. |
line | WaxColor | Separators. |
text | WaxColor | A colour in the linear form the engine uses. Make one with ui.Color. |
dim | WaxColor | Secondary text. |
accent | WaxColor | A colour in the linear form the engine uses. Make one with ui.Color. |
accent_hover | WaxColor | A colour in the linear form the engine uses. Make one with ui.Color. |
good | WaxColor | A colour in the linear form the engine uses. Make one with ui.Color. |
warn | WaxColor | A colour in the linear form the engine uses. Make one with ui.Color. |
bad | WaxColor | A colour in the linear form the engine uses. Make one with ui.Color. |
clear | WaxColor | Fully transparent. |
on_accent | WaxColor | Text and knobs drawn on top of the accent colour. |
font_size | number | |
title_size | number | |
small_size | number | |
spacing | number | Gap between controls. |
padding | number | |
row_height | number | |
bar_height | number | Height of a window's title bar. |
nav_width | number | Default width of a side navigation column. |
window_shape | WaxShape | |
control_shape | WaxShape | |
animation | number | Seconds for open, close and expand animations. 0 turns animation off. |
WaxThemeSettings
Theme settings to change. Colours may be given as "#RRGGBB" or 0xRRGGBB.
Used by ui.SetTheme, ui.AddTheme.
| Option | Type |
|---|---|
window | WaxColor | string | integer |
outline | WaxColor | string | integer |
panel | WaxColor | string | integer |
card | WaxColor | string | integer |
card_line | WaxColor | string | integer |
raised | WaxColor | string | integer |
hover | WaxColor | string | integer |
press | WaxColor | string | integer |
line | WaxColor | string | integer |
text | WaxColor | string | integer |
dim | WaxColor | string | integer |
accent | WaxColor | string | integer |
accent_hover | WaxColor | string | integer |
good | WaxColor | string | integer |
warn | WaxColor | string | integer |
bad | WaxColor | string | integer |
clear | WaxColor | string | integer |
on_accent | WaxColor | string | integer |
font_size | number |
title_size | number |
small_size | number |
spacing | number |
padding | number |
row_height | number |
bar_height | number |
nav_width | number |
window_shape | WaxShape |
control_shape | WaxShape |
animation | number |
WaxWindowOptions
Used by ui.Window.
| Option | Type | Description |
|---|---|---|
title | string | "Window" when omitted. |
icon | string | Icon name shown before the title. The menu's Icons page lists the names. |
width | number | Default 340, or 520 with side navigation. |
height | number | Default 420, or 380 with pages. |
x | number | |
y | number | |
closable | boolean | False leaves out the close button. |
visible | boolean | False creates the window hidden. |
nav | WaxNav | Gives the window pages, listed down the side or along the top. |
nav_width | number | Width of the side navigation column. |
remember | boolean | False stops Wax remembering the window's position and size between sessions. |
WaxPageOptions
Used by window:Page, ui.Debug.Page.
| Option | Type | Description |
|---|---|---|
icon | string | Icon name shown before the page's name. The menu's Icons page lists the names. |
bottom | boolean | Lists the page at the bottom of a side navigation column. |
scroll | boolean | False makes a page that does not scroll. Its controls stack from the top, and a Grid or Console with no height takes the space left. |
WaxStatusOptions
Used by statusBar:Set.
| Option | Type | Description |
|---|---|---|
kind | WaxKind | Sets the colour of the text and the icon. "info" when omitted. |
icon | string | Icon name shown before the text. The menu's Icons page lists the names. |
WaxOverlayOptions
Used by ui.Overlay.
| Option | Type | Description |
|---|---|---|
anchor | WaxAnchor | Where on the screen the panel is pinned. "top-right" when omitted. |
x | number | Distance in from the anchor's edge. Default 16. |
y | number | Distance in from the anchor's edge. Default 16. |
width | number | Default 240. |
title | string | Adds a heading. |
background | boolean | False leaves out the panel behind the controls. |
movable | boolean | False stops the player dragging it while the menu is open. Where it was dragged to is remembered. |
WaxNotifyOptions
Used by ui.Notify.
| Option | Type | Description |
|---|---|---|
title | string | A bold line above the text. |
kind | WaxKind | Sets the colour and the icon. "info" when omitted. |
icon | string | Icon name used in place of the kind's own. The menu's Icons page lists the names. |
seconds | number | Time on screen. Default 4, and 0 keeps it until closed. |
progress | number | 0..1. Shows progress in place of the countdown and keeps the notification until closed. |
WaxTagOptions
Used by ui.Tag.
| Option | Type | Description |
|---|---|---|
text | string | |
color | WaxColor | string | |
size | number | |
within | number | Metres. Farther away than this the tag is not shown. Default 100. |
lift | number | How far above the thing's middle the tag sits, in centimetres. Worked out from the thing when omitted. |
WaxHotkeyOptions
Used by ui.Hotkey.
| Option | Type | Description |
|---|---|---|
in_menu | boolean | Also reacts while the menu is open (off by default, so that typing in a box does not trigger it). |
Named values
Short names for a fixed set of values. Where a function asks for one of these, pass one of the values listed.
WaxKind
One of "info", "good", "warn", "bad".
WaxCorner
One of "top-left", "top-right", "bottom-left", "bottom-right".
WaxAnchor
One of "top-left", "top", "top-right", "left", "center", "right", "bottom-left", "bottom", "bottom-right".
WaxNav
One of "side", "top".
WaxFontFamily
One of "ui", "mono", "plain".
WaxThemeName
One of "Midnight", "Graphite", "Abyss", "Dune", "Daylight", or any other string.
WaxShape
One of "frame6", "frame8", "frame12", "top8", "glow12", "glow12_soft", "round2", "round3", "round4", "round5", "round6", "round7", "round8", "round9", "round10", "round12".