wolfhacklua API 1.1 Forum

ui

Tabs, cards and controls on the Scripts page, floating windows, and draggable overlay widgets.

since 1.0no permission needed

A script's interface lives in three places. A tab (ui.tab) is a page on the Scripts page, built from cards that hold controls. A window (ui.window) is a floating panel shown while the menu is open. A widget (ui.widget) is a box on the overlay itself that you draw into and the user can drag.

Tab, window and card functions are immediate mode: the function you pass is called again every frame the page is visible, and controls return their current value each time. Control functions only work inside ui.card (or inside a window body); calling them anywhere else is an error. Cards cannot be nested. Register tabs, windows and widgets once, when the script loads (at most 8 of each).

A control with an id keeps its value in the store under that key, so the value survives reloads and restarts; read it anywhere with store.get(id, default). Pass nil as the id for a control that should not be saved.

Reference#

ui.tab#since 1.0

ui.tab(name: string, fn: function)

Adds a page to the Scripts page. Call ui.card inside.

ParameterTypeDescription
namestringThe tab's title.
fnfunctionBuilds the tab; called every frame it is visible.
lua
ui.tab("My script", function()
  ui.card("Options", function()
    ui.toggle("enabled", "Enabled", true)
  end)
end)

ui.window#since 1.0

ui.window(options: table)

Registers a floating window. It is shown only while the menu is open, like a tool. body is built like a tab and may call ui.card.

ParameterTypeDescription
optionstable{id, title, size = {w, h}, open, body = fn}. id is required (2 to 48 characters from a-z 0-9 - _); size defaults to a small panel; open is the starting state.
lua
ui.window{ id = "tool", title = "Tool", size = { 360, 200 }, body = function()
  ui.card("Hello", function() ui.text("inside a window") end)
end }

ui.window_open#since 1.0

ui.window_open(id: string, open?: boolean)

Opens or closes a window.

ParameterTypeDescription
idstringA window id.
open optionalbooleanShow or hide it. default toggles

ui.window_is_open#since 1.0

ui.window_is_open(id: string): boolean

Asks whether a window is open.

ParameterTypeDescription
idstringA window id.
ReturnsDescription
booleanWhether it is open.

ui.widget#since 1.0

ui.widget(options: table)

Registers an overlay widget. Draw into it with the draw.* functions in widget coordinates (0, 0 is its top left corner; drawing is clipped to its size). The user drags it by its top strip while the menu is open and its position is saved. With the menu closed the overlay lets the mouse through to the game, so interactive widgets can only be clicked while the menu is open.

ParameterTypeDescription
optionstable{id, name, size = {w, h}, pos = {fx, fy}, interactive, draw = fn(w)}. id is 2 to 48 characters from a-z 0-9 - _. pos is a fraction of the free space of the screen (0, 0 top left; 1, 1 bottom right), so it holds at any resolution. draw receives a WidgetContext.
lua
ui.widget{ id = "clock", name = "Clock", size = { 120, 36 }, pos = { 0.5, 0.02 }, draw = function(w)
  draw.rect(0, 0, w.w, w.h, 0x101418E0, 6)
  draw.text(w.w / 2, 8, 0xFFFFFFFF, os.date("%H:%M"), { align = "center", size = 18 })
end }

ui.widget_visible#since 1.0

ui.widget_visible(id: string, visible?: boolean)

Shows or hides a widget.

ParameterTypeDescription
idstringA widget id.
visible optionalbooleanShow or hide. default toggles

ui.card#since 1.0

ui.card(title: string, fn: function, options?: table)

A titled group of controls. Cannot be nested. Only inside a tab or window body.

ParameterTypeDescription
titlestringThe card's heading.
fnfunctionBuilds the card's controls.
options optionaltable{width = fraction} from 0.2 to 1 of the row; cards flow left to right and then wrap. default 1
lua
ui.card("Look", function() ui.color("accent", "Accent", 0xFF7A18FF) end, { width = 0.5 })

ui.toggle#since 1.0

ui.toggle(id: string | nil, label: string, default?: boolean, options?: table): boolean, boolean

A switch.

ParameterTypeDescription
idstring | nilStore key, or nil for an unsaved control.
labelstringText next to the switch.
default optionalbooleanStarting value. default false
options optionaltable{tip = "..."}.
ReturnsDescription
booleanThe current value.
booleantrue on the frame it changed.
lua
local on, changed = ui.toggle("show", "Show it", true)

ui.checkbox#since 1.0

ui.checkbox(id: string | nil, label: string, default?: boolean, options?: table): boolean, boolean

A checkbox; the same as ui.toggle with another look.

ParameterTypeDescription
idstring | nilStore key.
labelstringText.
default optionalbooleanStarting value. default false
options optionaltable{tip}.
ReturnsDescription
booleanThe current value.
booleanChanged this frame.

ui.slider#since 1.0

ui.slider(id: string | nil, label: string, min: number, max: number, default?: number, options?: table): number, boolean

A slider.

ParameterTypeDescription
idstring | nilStore key.
labelstringText.
minnumberSmallest value.
maxnumberLargest value; must be greater than min.
default optionalnumberStarting value. default min
options optionaltable{int = true} for whole numbers, {format = "%d px"} (a printf pattern; default %d for ints and %.2f otherwise), {tip}.
ReturnsDescription
numberThe current value (an integer when int is set).
booleanChanged this frame.
lua
local size = ui.slider("size", "Size", 8, 40, 16, { int = true, format = "%d px" })

ui.dropdown#since 1.0

ui.dropdown(id: string | nil, label: string, items: string[], default?: integer, options?: table): integer, boolean

A drop-down list.

ParameterTypeDescription
idstring | nilStore key.
labelstringText.
itemsstring[]The choices.
default optionalintegerStarting index, 1-based. default 1
options optionaltable{tip}.
ReturnsDescription
integerThe chosen index, 1-based.
booleanChanged this frame.
lua
local corner = ui.dropdown("corner", "Corner", { "Top left", "Top right" }, 2)

ui.color#since 1.0

ui.color(id: string | nil, label: string, default?: integer, options?: table): integer, boolean

A colour picker with alpha.

ParameterTypeDescription
idstring | nilStore key.
labelstringText.
default optionalintegerStarting colour 0xRRGGBBAA.
options optionaltable{tip}.
ReturnsDescription
integerThe colour.
booleanChanged this frame.

ui.keybind#since 1.0

ui.keybind(id: string | nil, label: string, default?: integer, options?: table): integer, boolean

A key picker. It only records which key the user chose; to react to the key being held, read it with input.key_down (needs the input permission). See input for the code table.

ParameterTypeDescription
idstring | nilStore key.
labelstringText.
default optionalintegerA Windows virtual-key code, or 0 for none. default 0
options optionaltable{tip}.
ReturnsDescription
integerThe key's virtual-key code.
booleanChanged this frame.

ui.input#since 1.0

ui.input(id: string | nil, hint: string, default?: string): string, boolean

A one-line text box. It has no tip option.

ParameterTypeDescription
idstring | nilStore key.
hintstringPlaceholder text.
default optionalstringStarting text. default ""
ReturnsDescription
stringThe text.
booleanChanged this frame.
lua
local name = ui.input("name", "Your name", "wolfhack")

ui.button#since 1.0

ui.button(label: string, options?: table): boolean

A button.

ParameterTypeDescription
labelstringText.
options optionaltable{variant = "primary"|"secondary"|"danger"|"ghost", width = pixels}.
ReturnsDescription
booleantrue on the frame it was clicked.
lua
if ui.button("Reset", { variant = "danger" }) then store.set("count", 0) end

ui.text#since 1.0

ui.text(s: string, col?: integer)

A line of text.

ParameterTypeDescription
sstringText.
col optionalintegerColour. default the menu's text colour

ui.note#since 1.0

ui.note(s: string, col?: integer)

A smaller, dimmed line for explanations.

ParameterTypeDescription
sstringText.
col optionalintegerColour. default a dimmed text colour

ui.label#since 1.0

ui.label(s: string)

A small heading above a control.

ParameterTypeDescription
sstringText.

ui.spacer#since 1.0

ui.spacer(h?: number)

Empty vertical space.

ParameterTypeDescription
h optionalnumberHeight in pixels. default a small gap

ui.same_line#since 1.0

ui.same_line(gap?: number)

Puts the next control on the same line as the previous one.

ParameterTypeDescription
gap optionalnumberGap in pixels. default the menu's default

ui.progress#since 1.0

ui.progress(fraction: number, label?: string)

A progress bar.

ParameterTypeDescription
fractionnumber0 to 1.
label optionalstringText drawn on the bar.

ui.image#since 1.0

ui.image(tex: Texture, w: number, h: number)

Shows a texture in a card. A texture that is not ready yet draws nothing.

ParameterTypeDescription
texTextureA texture from assets.
wnumberWidth.
hnumberHeight.

ui.last_rect#since 1.0

ui.last_rect(): number, number, number, number

The screen rectangle of the control made last. Useful for placing your own drawing next to it.

ReturnsDescription
numberx
numbery
numberwidth
numberheight

ui.canvas#since 1.0

ui.canvas(w: number, h: number, fn: function)

An area of a card you draw on and read the mouse and keys in. Keys are delivered while the canvas is hovered or was clicked last.

ParameterTypeDescription
wnumberWidth in pixels.
hnumberHeight in pixels.
fnfunctionCalled each frame with a CanvasContext; draw with draw.* in canvas coordinates.
lua
ui.canvas(300, 120, function(c)
  draw.rect(0, 0, c.w, c.h, 0x202020FF)
  if c.hovered then draw.circle(c.mouse_x - c.x, c.mouse_y - c.y, 6, 0xFFFFFFFF) end
end)

ui.model#since 1.0

ui.model(w: number, h: number, options?: table)

The built-in player model preview in a card.

ParameterTypeDescription
wnumberWidth.
hnumberHeight.
options optionaltable{yaw = degrees, team = "ct" | "t"}.

WidgetContext#

The table a widget's draw receives.

FieldTypeDescription
wnumberWidget width.
hnumberWidget height.
xnumberScreen x of the widget.
ynumberScreen y of the widget.
dtnumberSeconds since the last frame.
editingbooleantrue while the menu is open (the widget can be dragged).
mouse_xnumberWith interactive, menu open: pointer x in widget coordinates.
mouse_ynumberPointer y.
hoveredbooleanThe pointer is over the widget.
downbooleanThe button is held.
clickedbooleanClicked this frame.

CanvasContext#

The table a ui.canvas callback receives.

FieldTypeDescription
wnumberCanvas width.
hnumberCanvas height.
xnumberScreen x of the canvas.
ynumberScreen y of the canvas.
mouse_xnumberPointer x (screen).
mouse_ynumberPointer y (screen).
hoveredbooleanThe pointer is over it.
downbooleanButton held.
clickedbooleanClicked this frame.
releasedbooleanReleased this frame.
right_clickedbooleanRight button clicked this frame.
focusedbooleanThe canvas was clicked last and gets keys.
wheelnumberMouse wheel movement.
dtnumberSeconds since the last frame.
timenumberSeconds on the script clock.
key_down(name)functionWhether a key is held. Names: a-z, 0-9, left, right, up, down, space, enter, escape, shift, ctrl, tab.
key_pressed(name)functionWhether a key went down this frame.
API 1.1 · source docs-src/api/ui.json