-
Notifications
You must be signed in to change notification settings - Fork 20
The user interface library renders widgets over the game window using an immediate-mode GUI.
local ui = require('ui')The ui table has the following entries:
- 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
- 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
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 theui.displayfunction.
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, booleanid 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.location(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, checked : boolean = false, enabled : boolean = true) : booleanid string
Unique identifier for the widget.
text string
Text label to write on the button.
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 = nil, enabled : boolean = true) : booleanid string
Unique identifier for the widget.
text string
The text label attached to the checkbox.
checked boolean [default: nil]
Specifies the current state of the checkbox:
- true : The box is checked.
- false : The box is unchecked.
- nil : The box is indeterminate.
enabled boolean [default: true]
Specifies whether the checkbox is enabled and can be toggled.
checked boolean
The current state of the checkbox:
- true : The box is checked.
- false : The box is unchecked.
- nil : The box is indeterminate.
Renders a graphical color picker widget.
function ui.color_picker(id : string, color : color_value, enabled : boolean = true) : color_valueid string
Unique identifier for the widget.
color color_value
The integer value of the color currently selected in the color picker.
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 : edit_options = none, enabled : boolean = true) : stringid string
Unique identifier for the widget.
text string
The text currently entered in the edit box.
options edit_options [default: none]
The editing options that control the behavior of the edit box.
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, color : color_value = 'white')path string
The absolute path to the source image file.
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, color : color_value = 'accent')value number
Fractional number representing the percentage of the progress bar that is filled.
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, enabled : boolean = true) : booleanid 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.
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, min : number = 0, max : number = 1, color : color_value = 'accent', enabled : boolean = true) : numberid string
Unique identifier for the widget.
value number
The current value specified by the position of the slider.
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, color : color_value = 'white')text string
The string of text to render in the widget. The string may include basic Markdown formatting and formatting strings.
color color_value [default: ui.color[white]]
The integer value of the color for the text.
This function does not return any values.