Docs · ui

ui

18 ui commands, generated from the engine's own registry — signatures, parameters and a worked example each. A does something command acts on the game; a needs x() one answers a confident wrong answer when its client hooks are missing.

uiButton
uiButton(label: string, fun: string)

Upserts a button. Clicking it runs the named fun on the script thread, between passes - never during on loop and never on the launcher's own thread. At most 8 clicks wait at once; extra ones are dropped with a trace.

ParameterTypeWhat it does
labelrequired string what the button says - buttons upsert by their label
funrequired string the name of a zero-argument fun in this script, written as a literal so the checker can prove it exists
Example
uiButton("Drop all", "onDrop")
uiChoice
uiChoice(key: string, label: string, initial: enum)

Upserts a dropdown over every member of the initial's enum. Read the pick with uiChosen, which answers the same enum.

ParameterTypeWhat it does
keyrequired string which row this is, written as a literal so uiChosen can be checked against it
labelrequired string what the dropdown is for
initialrequired enum the member it starts on, written out like Mode.POWER. Its enum is the dropdown's whole option list. Counts only when the row is created
Example
uiChoice("mode", "Mode", Mode.POWER)
uiChosen returns enum
uiChosen(key: string) -> enum

The dropdown's current pick, as a value of the same enum uiChoice was given. Safe to ask at any moment, and it answers the declared initial until the user picks.

ParameterTypeWhat it does
keyrequired string the dropdown's key, written as a literal - the checker types the answer from the uiChoice that shares it
Example
uiChoice("mode", "Mode", Mode.POWER)
if uiChosen("mode") == Mode.BANK { become banking }
uiClear
uiClear()

Takes every row off the tab and forgets all their state. The tab itself stays until the script stops.

Example
uiClear()
uiHas returns bool
uiHas(key: string) -> bool

True when a row with this key exists right now. The existence check that makes dynamically-keyed rows safe to read: uiToggled and uiText refuse a key nothing created, and this is how to ask first. Never throws, and answers false before any row is drawn - including on a run with no UI host at all.

ParameterTypeWhat it does
keyrequired string the row to look for
Example
if uiHas("banking") { if uiToggled("banking") { become banking } }
uiHeader
uiHeader(text: string)

Appends a section header row to the tab. Headers append rather than update, so one belongs in on start, not in on loop.

ParameterTypeWhat it does
textrequired string the section's heading
Example
uiHeader("Totals")
uiInput
uiInput(key: string, label: string, initial: string)

Upserts a one-line text field the user can type into. Read it with uiText, which follows every keystroke - there is no Enter to wait for.

ParameterTypeWhat it does
keyrequired string which row this is - the same key updates the same row
labelrequired string what the field is for
initialrequired string what it starts holding. Counts only when the row is created; a later call with the same key changes the label and leaves the text alone
Example
uiInput("search", "Search", "")
uiLabel
uiLabel(key: string, text: string)

Upserts a text row: the first call with a key appends it, every later call updates it in place. The row keeps the position its first call gave it.

ParameterTypeWhat it does
keyrequired string which row this is - the same key updates the same row
textrequired string what the row says
Example
uiLabel("status", "warming up")
uiNote
uiNote(key: string, text: string)

Upserts a paragraph that wraps — instructions or an explanation, where a label would run off the edge.

ParameterTypeWhat it does
keyrequired string which row this is - the same key updates the same row
textrequired string the paragraph to show; it wraps to the tab's width
Example
uiNote("how", "Stand by the bank with a pickaxe and press start.")
uiNumber returns int
uiNumber(key: string, fallback: int) -> int

The field's current text read as a whole number, or the fallback while it is empty or not numeric — the typed-in-amount pattern in one call. Refuses a key no uiInput made, the same as uiText.

ParameterTypeWhat it does
keyrequired string the field's key, as given to uiInput
fallbackrequired int the answer while the field is empty or not a number
Example
uiInput("amount", "How many", "28")
print(uiNumber("amount", 28))
uiProgress
uiProgress(key: string, value: int, max: int)

Upserts a progress bar drawn as value/max. The value is clamped between 0 and max, so a count that overshoots draws full rather than strange.

ParameterTypeWhat it does
keyrequired string which row this is - the same key updates the same row
valuerequired int how far along it is
maxrequired int what full is
Example
uiProgress("trip", 12, 28)
uiRemove
uiRemove(key: string)

Takes one row off the tab and forgets its state, so re-creating it starts from its initial again. A key that was never drawn is quietly ignored.

ParameterTypeWhat it does
keyrequired string the row to take off
Example
uiRemove("status")
uiSeparator
uiSeparator(key: string)

Upserts a thin dividing line, for splitting a tab into parts without a header's words.

ParameterTypeWhat it does
keyrequired string which line this is - the same key keeps the same line
Example
uiSeparator("split1")
uiStat
uiStat(key: string, label: string, value: string, colour: string)

Upserts a readout row: a name on the left and a coloured value on the right. The row every stats tab is made of — pair it with commas() and blendColours().

ParameterTypeWhat it does
keyrequired string which row this is - the same key updates the same row
labelrequired string the stat's name, on the left
valuerequired string the stat's value, on the right
colourrequired string the value's colour - a name or hex string, as paint takes
Example
uiStat("xp", "Xp gained", commas(12500), "lime")
uiTab
uiTab(title: string)

Names the script's tab on the launcher rail, creating it if this is the run's first ui command. Without it the tab takes the script's name. Calling it again renames.

ParameterTypeWhat it does
titlerequired string what the tab is called
Example
uiTab("Miner")
uiText returns string
uiText(key: string) -> string

The field's current text. Safe to ask at any moment - it reads the engine's own copy, not the control - and it answers the declared initial until the user types. It follows every keystroke, so a search box filters as the user writes rather than when they press Enter.

ParameterTypeWhat it does
keyrequired string the field's key, as given to uiInput
Example
uiInput("search", "Search", "")
if contains(lower(rockName), lower(uiText("search"))) { print("match") }
uiToggle
uiToggle(key: string, label: string, initial: bool)

Upserts an on/off toggle the user can flip. Read it with uiToggled.

ParameterTypeWhat it does
keyrequired string which row this is - the same key updates the same row
labelrequired string what the toggle is for
initialrequired bool how it starts. Counts only when the row is created; a later call with the same key changes the label and leaves the state alone
Example
uiToggle("banking", "Bank the ores", true)
uiToggled returns bool
uiToggled(key: string) -> bool

The toggle's current state. Safe to ask at any moment - it reads the engine's own copy, not the control - and it answers the declared initial until the user flips it. Legal in a wait until, which is the idiomatic way to hand control to the person at the keyboard.

ParameterTypeWhat it does
keyrequired string the toggle's key, as given to uiToggle
Example
if uiToggled("banking") { become banking }