UI Properties

Below is a list of properties that can be defined in Lua UI Elements. If any of these are left nil, they have relatively sensible default values that can be found and configured in propertyDefaults.

position
A normalised vector where (0,0) is the top-left corner of the screen and (1,1) is the bottom-right.
Represents the top-left corner of the texture or solid color.

Type: table.

Fields:

• x - should be a number
• y - should be a number

dimensions
A normalised vector where (0,0) is the top-left corner and (1,1) is the bottom-right.
Represents how far (as a percentage of the width or height of the screen) to extend the texture or solid color. i.e. position + dimensions = the bottom-right corner of the texture or solid color.

Type: table.

Fields:

• x - should be a number
• y - should be a number

textPos
A normalised vector where (0,0) is the top-left corner of the screen and (1,1) is the bottom-right.
Represents the top-left corner of the first character of text.

Type: table.

Fields:

• x - should be a number
• y - should be a number

color
An RGBA color representing the color of the rectangle, or the tint of the texture.
If texture points to a valid texture path, the color of each pixel of the image will be multiplied by this property.

Type: table.

Fields:

• r - should be a number between 0 and 255
• g - should be a number between 0 and 255
• b - should be a number between 0 and 255
• a - should be a number between 0 and 255

text
A string that is rendered as glyphs if font is a valid font path.

Type: string.

Fields: none.

texture
A string that contains a path to the image file for this element's texture, relative to the current working directory of the program.

Type: string.

Fields: none.

font
A string that contains a path to the font file for this element's text, relative to the current working directory of the program.
The current accepted font file types are those accepted by freetype, with the exception of fixed-size font types.

Type: string.

Fields: none.

textSize
An integer representing the size of the text, in pixels, to be rendered.
Note that this only changes the size of the vertices, not the pixel width and height of the glyph textures themselves.

Type: integer.

Fields: none.

fontColor
An RGBA color representing the color of the text, if this element has any.

Type: string.

Fields: none.

layer
The z-layer of the UI Element. A signed integer where elements with larger values are rendered on top of elements with smaller values.
Text is always rendered one z-index above layer, to ensure it is shown above the color or texture.

Type: integer.

Fields: none.

Shared Globals

Shared Globals are values and tables that are updated typically every frame with information to pass between UI scripts and your C++ app, handling input and functionality that depends on Lua and C++ interoperability.

VUI_nextScript
A filepath specifying the Lua script VUI should run for the UI on the next frame.
It is relative to the current working directory of the program. This can be used to define UI elements once, then use another script for how the elements are updated every frame, for example.

VUI_winX, VUI_winY
The width and height respectively of the window VUI is running in, in pixels.
This shouldn't be edited on the Lua side.

Type: number.

Fields: none.

VUI_dt
The time that has passed since the last frame, in seconds (i.e. deltaTime).
This shouldn't be edited on the Lua side.

Type: number.

Fields: none.

VUI_mouse
A table containing the mouse's state in the current frame.
This shouldn't be edited on the Lua side.

Type: table.

Fields:

• down - a boolean variable specifying whether the mouse is down or not on this frame.
• onPress - a boolean variable specifying whether the mouse has just started to be pressed this frame.
• onRelease - a boolean variable specifying whether the mouse has just been released this frame.
• x - the mouse's x position, where 0 is the left side of the window, and 1 is the right.
• y - the mouse's y position, where 0 is the top of the window, and 1 is the bottom.

VUI_signal
Sends boolean flags from Lua to C++, allowing conditional code to be executed based on the state of the UI.
On the C++ side, signals can be collected with CollectLuaSignals() in the update loop, checked with HasSignalled("<yoursignal>") and disabled with DisableSignal("<yoursignal>"). On the Lua side, signals are enabled by setting the field of VUI_signal to true, e.g. VUI_signal.quit = true.

Type: table.

VUI_key
Stores down, onPress and onRelease state for keys, similar to VUI_mouse.
The keys currently supported are all printable UTF8 keys, and some non-printable keys. The current non-printable keys supported by the GLFW poller are Super, Ctrl, Alt, Shift, Tab Space and Enter. The keys that can either be left or right such as Shift only respond to key presses for the left key. Key state is accessed by using the key as the field and the key state as its subfield, e.g. VUI_key.Super.down or VUI_key["S"].onRelease.

Type: table.