UI

Retained mode and DOM-style API to render interactive user-interfaces, with a Solid.js-inspired UI framework built on top.

It's recommended to either use the out-of-the-box UI framework (or build your own) instead of working with the retained mode API directly. Retained mode has been chosen to significantly reduce the overhead of communicating between Lua and the engine for mostly static UIs.

Constants

UI.SCREEN

Root DOM element rendered to the screen in 2D. Shared by all screenspace UI, so you'll want to further restrict/abstract this if exposed to addons in your game.

UI.SCREEN: Element

Functions

UI.createElement

Creates a new containing element element.

UI.createElement(): Element

Returns

Name	Type	Description
element	Element	No description

UI.createTextElement

Creates a new text element.

UI.createTextElement(textContent: string): TextElement

Parameters

Name	Type	Default Value	Description
textContent	string	Required	Initial text content of the element.

Returns

Name	Type	Description
element	TextElement	No description

UI.isTextElement

Returns whether the given parameter is a text UI element.

UI.isTextElement(value: any): boolean

Parameters

Name	Type	Default Value	Description
value	any	Required	The value to check.

Returns

Name	Type	Description
isTextElement	boolean	Whether the value is a text element.

UI.removeElement

Removes the element from its parent. No-op if the element has no parent.

UI.removeElement(child: Element | TextElement)

Parameters

Name	Type	Default Value	Description
child	Element | TextElement	Required	No description

UI.appendElement

Appends an element to the end of another element's children. Removes the child element from its current parent if it has one.

UI.appendElement(parent: Element, child: Element | TextElement)

Parameters

Name	Type	Default Value	Description
parent	Element	Required	Element to append to.
child	Element | TextElement	Required	Element to be appended.

UI.getChildren

Returns a list of the element's children. This is a copy, so will not update if the children of the element change (nor will the element's children change if this list is modified).

UI.getChildren(element: Element): (Element | TextElement)[]

Parameters

Name	Type	Default Value	Description
element	Element	Required	No description

Returns

Name	Type	Description
children	(Element | TextElement)[]	No description

UI.getElementName

Returns the debug name of the element.

UI.getElementName(element: Element): string

Parameters

Name	Type	Default Value	Description
element	Element	Required	No description

Returns

Name	Type	Description
name	string	No description

UI.setElementName

Sets the debug name of the element.

UI.setElementName(element: Element, name: string)

Parameters

Name	Type	Default Value	Description
element	Element	Required	No description
name	string	Required	No description

UI.getTextContent

Returns the contents of a text element.

UI.getTextContent(element: TextElement): string

Parameters

Name	Type	Default Value	Description
element	TextElement	Required	No description

Returns

Name	Type	Description
textContent	string	No description

UI.setTextContent

Updates the contents of a text element.

UI.setTextContent(element: TextElement, textContent: string)

Parameters

Name	Type	Default Value	Description
element	TextElement	Required	No description
textContent	string	Required	No description

UI.setStyle

Sets a style on the element when in the specified state.

Styles are used in the order Clicked -> Hovered -> Always -> Engine Defaults. The first state as per the order above which has a style set will be used.

UI.setStyle(element: Element, style: UI.Style, value: boolean | number | string | Colour | UI.SizeMode | UI.ChildAlignment | UI.Direction | UI.TextWrapping | UI.TextAlignment | UI.Display, when: UI.StyleMode)

Parameters

Name	Type	Default Value	Description
element	Element	Required	No description
style	UI.Style	Required	No description
value	boolean | number | string | Colour | UI.SizeMode | UI.ChildAlignment | UI.Direction | UI.TextWrapping | UI.TextAlignment | UI.Display	Required	Accepted type depends on the style being set.
when	UI.StyleMode	Required	In which state the style will be used.

UI.removeStyle

Removes the style from the element when in the specified state.

Styles are used in the order Clicked -> Hovered -> Always -> Engine Defaults. Removing a style from one of the layers means the first set style in a lower state (as above) will be used instead.

UI.removeStyle(element: Element, style: UI.Style, when: UI.StyleMode)

Parameters

Name	Type	Default Value	Description
element	Element	Required	No description
style	UI.Style	Required	No description
when	UI.StyleMode	Required	In which state the style will be removed.

UI.enableDebugger

Enables the Clay debugger.

UI.enableDebugger()

UI.disableDebugger

Disables the Clay debugger.

UI.disableDebugger()

UI.isDebuggerEnabled

Returns whether the Clay debugger is enabled.

UI.isDebuggerEnabled(): boolean

Returns

Name	Type	Description
debuggerEnabled	boolean	No description

UI.addEventListener

Listen to events raised on the element to support user interaction.

UI.addEventListener(element: Element, eventName: 'mouseDown' | 'mouseUp', callback: function): function

Parameters

Name	Type	Default Value	Description
element	Element	Required	No description
eventName	'mouseDown' | 'mouseUp'	Required	No description
callback	function	Required	No description

Returns

Name	Type	Description
callback	function	Callback that was passed in.

UI.removeEventListener

Remove an event listener from the element.

UI.removeEventListener(element: Element, eventName: 'mouseDown' | 'mouseUp', callback: function)

Parameters

Name	Type	Default Value	Description
element	Element	Required	No description
eventName	'mouseDown' | 'mouseUp'	Required	No description
callback	function	Required	Callback that was passed to addEventListener.

UI.createComponent

Creates a component from the given function. This sets up the component function as stateful and normalises its parameters.

UI.createComponent(componentFn: fun(props: table, children: fun(): (Element | TextElement)[]): function): fun(props?: table, children?: fun(): array): fun(): (Element | TextElement)[]

Parameters

Name	Type	Default Value	Description
componentFn	fun(props: table, children: fun(): (Element | TextElement)[]): function	Required	No description

Returns

Name	Type	Description
component	fun(props?: table, children?: fun(): array): fun(): (Element | TextElement)[]	The normalised component function.

UI.render

Resolves the component tree and appends all root nodes to the given element. Should be called only once when initialising the UI.

UI.render(component: fun(props?: table, children?: (fun(): (Element | TextElement)[])[]): fun(): (Element | TextElement)[], element: Element)

Parameters

Name	Type	Default Value	Description
component	fun(props?: table, children?: (fun(): (Element | TextElement)[])[]): fun(): (Element | TextElement)[]	Required	Root component of the application.
element	Element	Required	UI element to mount the components to.

UI.toString

Stringifies the element and its children into a format resembling HTML/XML Useful for debugging and snapshot testing.

UI.toString(element: Element | TextElement, indent?: integer): string

Parameters

Name	Type	Default Value	Description
element	Element | TextElement	Required	No description
indent	integer?	nil	Number of spaces to indent all lines by. Defaults to 0.

Returns

Name	Type	Description
elementMarkup	string	No description

Enums

Style

Style properties of Elements.

Value
Width
MinWidth
MaxWidth
WidthMode
Height
MinHeight
MaxHeight
HeightMode
PaddingLeft
PaddingRight
PaddingTop
PaddingBottom
Gap
AlignmentX
AlignmentY
Direction
BackgroundColour
BackgroundImage
CornerRadiusTopLeft
CornerRadiusTopRight
CornerRadiusBottomLeft
CornerRadiusBottomRight
BorderColour
BorderLeft
BorderRight
BorderTop
BorderBottom
BorderBetween
TextColour
FontSize
LetterSpacing
LineHeight
TextWrapping
TextAlignment

StyleMode

When to apply a given style. Styles apply in the order Clicked -> Hovered -> Always -> Engine Defaults.

Value
Always
Hovered
Clicked

SizeMode

Determines how the Element will respond to changes in width/height by its parent and children. FixedPercent fixes the Element's width/height to a percentage (0-1) of the parent's size, using the first of Width, MaxWidth or MinWidth which is defined (and *Height for height).

Value
Shrink
Grow
FixedPercent

ChildAlignment

Alignment of children on a given axis relative to this Element's content box.

Value
Start
Centre
End

Direction

Direction that children are laid out in this Element.

Value
Horizontal
Vertical

TextWrapping

Where in the string it's valid to insert line breaks in order to prevent overflow.

Value
Words
Newlines
None

TextAlignment

Alignment of TextElements which are the immediate child of this Element.

Value
Left
Centre
Right

Display

Determines the visibility of the element and its children.

Value
Visible
ContentsHidden
Contents