The user interface library renders widgets over the game window using an immediate-mode GUI.

local ui = require('core.ui')

✔️ Dependency Not Required

This library does not require an explicit dependency in the manifest.xml file for your package.

The ui table has the following entries:

General Functions

• ui.display : Registers a function with the immediate-mode GUI
• ui.window : Renders a window widget that contains other widgets
• ui.location : Sets the position of the next widget
• ui.size : Sets the size of the next widget
• ui.space : Inserts a blank space before the next widget
• ui.indent : Indents the next widget
• ui.unindent : Unindents the next widget

Widget Functions

• ui.button : Renders a button
• ui.check : Renders a three-state checkbox
• ui.color_picker : Renders an interactive color picker
• ui.edit : Renders an interactive edit box
• ui.image : Renders a graphical image
• ui.progress : Renders a progress bar
• ui.radio : Renders a radio button
• ui.slider : Renders an interactive slider
• ui.text : Renders optionally-formatted text

Tables

• ui.color : A collection of color-related helper functions and named color constants.
• ui.draw : A collection of functions for drawing basic graphical primitives.

Registers a function containing user interface widgets and logic with the immediate-mode GUI handler.

function ui.display(fn : function)

fn function

A function that contains UI widget calls and other supporting logic.

Note: Performance Considerations
All code included in this function is called every time a frame is rendered. Consider the performance impact and move logic that does not really need to run that frequently outside the ui.display function.

This function does not return any values.

Renders a graphical window that contains other widgets and is configured based on optional configuration parameters defined in the state table.

function ui.window(id : string, state : window_state, fn : function) : window_state, boolean

id string

Unique string identifier for the window.

state window_state

A table containing the configuration state of the window.

fn function

The function that defines the UI widgets drawn within the window.

Note: Relative Positioning
Widgets created inside a window are positioned relative to the extents of the window, rather than relative to the entire game screen as with widgets created directly inside the ui.display function.

state window_state

A table containing the configuration state of the window.

closed boolean

Specifies whether the window is closed.

Explicitly specifies the position of the next widget to be rendered.

Note: Relative Positioning
For widgets defined inside the main ui.display function, the position set by this function is relative to the full game window. For widgets inside a window, the position is relative to the extents of the window.

function ui.location(x : number, y : number)

x number

The x-coordinate position for the next widget.

y number

The y-coordinate position for the next widget.

This function does not return any values.

Specifies the dimensions of the next widget to be rendered.

function ui.size(width : number, height : number)

width number

The width of the next widget, in pixels.

height number

The height of the next widget, in pixels.

This function does not return any values.

Inserts a blank space before the next widget to be rendered.

function ui.space()

This function has no parameters.

This function does not return any values.

Indents the next widget to be rendered.

function ui.indent()

This function has no parameters.

This function does not return any values.

Unindents the next widget to be rendered.

function ui.unindent()

This function has no parameters.

This function does not return any values.

Renders a clickable button widget.

function ui.button(id : string, text : string, options : table = nil) : boolean

id string

Unique identifier for the widget.

text string

Text label to write on the button.

options table [default: nil]

A table containing optional widget parameters:

checked boolean [default: false]
Specifies whether the button is pressed; used to create a toggle button.

enabled boolean [default: true]
Specifies whether the button is enabled and can be clicked.

pressed boolean

Returns the state of the button: true for pressed, false for not pressed.

Renders a three-state checkbox widget.

function ui.check(id : string, text : string, checked : boolean?, options : table = nil) : boolean

id string

Unique identifier for the widget.

text string

The text label attached to the checkbox.

checked boolean

Specifies the current state of the checkbox:

• true : The box is checked.
• false : The box is unchecked.
• nil : The box is indeterminate.

options table [default: nil]

A table containing optional widget parameters:

enabled boolean [default: true]
Specifies whether the checkbox is enabled and can be toggled.

clicked boolean

Returns whether or not the checkbox has been clicked.

Renders a graphical color picker widget.

function ui.color_picker(id : string, color : color_value, options : table = nil) : color_value

id string

Unique identifier for the widget.

color color_value

The integer value of the color currently selected in the color picker.

options table [default: nil]

A table containing optional widget parameters:

enabled boolean [default: true]
Specifies whether the color picker is enabled and can be manipulated.

color color_value

The integer value of the color currently selected in the color picker.

Renders an interactive edit box widget.

function ui.edit(id : string, text : string, options : table = nil) : string

id string

Unique identifier for the widget.

text string

The text currently entered in the edit box.

options table [default: nil]

A table containing optional widget parameters:

need to add missing edit params

enabled boolean [default: true]
Specifies whether the edit box is enabled and can be interacted with.

text string

The text currently entered in the edit box.

Renders an image from a source file.

function ui.image(path : string, options : table = nil)

path string

The absolute path to the source image file.

options table [default: nil]

A table containing optional widget parameters:

color color_value [default: ui.color.white]
The color to overlay on the rendered image.

This function does not return any values.

Renders a progress bar widget.

function ui.progress(value : number, options : table = nil)

value number

Fractional number representing the percentage of the progress bar that is filled.

options table [default: nil]

A table containing optional widget parameters:

color color_value [default: ui.color.accent]
The color used to fill the progress bar.

This function does not return any values.

Renders a radio button widget.

function ui.radio(id : string, text : string, checked : boolean, options : table = nil) : boolean

id string

Unique identifier for the widget.

text string

The text label attached to the radio button.

checked boolean

Specifies the current state of the radio button:

• true : The radio button is selected.
• false : The radio button is not selected.

options table [default: nil]

A table containing optional widget parameters:

enabled boolean [default: true]
Specifies whether the radio button is enabled and can be toggled.

checked boolean

The current state of the radio button:

• true : The radio button is selected.
• false : The radio button is not selected.

Renders an interactive slider widget.

function ui.slider(id : string, value : number, options : table = nil) : number

id string

Unique identifier for the widget.

value number

The current value specified by the position of the slider.

options table [default: nil]

A table containing optional widget parameters:

min number [default: 0]
The minimum value for the slider.

max number [default: 1]
The maximum value for the slider.

color color_value [default: ui.color.accent]
The integer value of the color used to fill the slider.

enabled boolean [default: true]
Specifies whether the radio button is enabled and can be toggled.

value number

The current value specified by the position of the slider.

Renders a widget containing optionally-formatted text.

function ui.text(text : string, options : table = nil)

text string

The string of text to render in the widget. The string may include basic Markdown formatting and formatting strings.

options table [default: nil]

A table containing optional widget parameters:

color color_value [default: ui.color.white]
The integer value of the color for the text.

This function does not return any values.