Skip to content
AEOWUN
Docs Menu

UI

Look up ui calls and properties.

control.key

Read or set the Script key.

Arguments

No call arguments. Assign string to change it.

Returns

string. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.key.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.key)

control.anchor

Choose the point used for layout.

Arguments

No call arguments. Assign anchor name string to change it.

Returns

anchor name string. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.anchor.

Names: TopLeft, TopCenter, TopRight, CenterLeft, Center, CenterRight, BottomLeft, BottomCenter, BottomRight, Stretch. Stretch treats position as left/top margins and size as right/bottom margins.

const control = ui.new("Button")
debug.log(control.anchor)

control.position

Read or change position in viewport pixels.

Arguments

No call arguments. Assign [x, y] numbers to change it.

Returns

[x, y] numbers. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.position.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.position)

control.size

Read or change control size.

Arguments

No call arguments. Assign [width, height] numbers to change it.

Returns

[width, height] numbers. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.size.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.size)

control.visible

Show or hide the control.

Arguments

No call arguments. Assign bool to change it.

Returns

bool. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.visible.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.visible)

control.enabled

Enable or disable interaction.

Arguments

No call arguments. Assign bool to change it.

Returns

bool. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.enabled.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.enabled)

control.color

Read or change the control color.

Arguments

No call arguments. Assign [r, g, b, a] numbers to change it.

Returns

[r, g, b, a] numbers. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.color.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.color)

control.parent

Choose a parent control.

Arguments

No call arguments. Assign another Ui handle or nil.

Returns

Ui handle or nil. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.parent.

Use another Ui handle or nil. Parent cycles are rejected.

Parent handles

Ui handles returned by creation and lookup can be assigned directly to parent.

const control = ui.new("Button")
debug.log(control.parent)

control.z_index

Choose the drawing order.

Arguments

No call arguments. Assign number to change it.

Returns

number. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.z_index.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.z_index)

control.corner_radius

Round the control corners.

Arguments

No call arguments. Assign number to change it.

Returns

number. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.corner_radius.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.corner_radius)

control.border_width

Choose the border width.

Arguments

No call arguments. Assign number to change it.

Returns

number. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.border_width.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.border_width)

control.border_color

Choose the border color.

Arguments

No call arguments. Assign [r, g, b, a] numbers to change it.

Returns

[r, g, b, a] numbers. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.border_color.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.border_color)

control.text

Read or change the label text.

Arguments

No call arguments. Assign string to change it.

Returns

string. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.text.

Works on Text and Button controls.

const control = ui.new("Button")
debug.log(control.text)

control.font_size

Choose the font size.

Arguments

No call arguments. Assign number to change it.

Returns

number. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.font_size.

Works on Text and Button controls.

const control = ui.new("Button")
debug.log(control.font_size)

control.horizontal_align

Align text horizontally.

Arguments

No call arguments. Assign Left, Center, or Right string to change it.

Returns

Left, Center, or Right string. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.horizontal_align.

Works on Text and Button controls.

const control = ui.new("Button")
debug.log(control.horizontal_align)

control.vertical_align

Align text vertically.

Arguments

No call arguments. Assign Top, Center, or Bottom string to change it.

Returns

Top, Center, or Bottom string. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.vertical_align.

Works on Text and Button controls.

const control = ui.new("Button")
debug.log(control.vertical_align)

control.wrap

Choose whether text wraps.

Arguments

No call arguments. Assign bool to change it.

Returns

bool. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.wrap.

Works on Text and Button controls.

const control = ui.new("Button")
debug.log(control.wrap)

control.padding

Set space around the text.

Arguments

No call arguments. Assign [left, top, right, bottom] numbers to change it.

Returns

[left, top, right, bottom] numbers. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.padding.

Works on Text and Button controls.

const control = ui.new("Button")
debug.log(control.padding)

control.line_spacing

Set extra space between lines.

Arguments

No call arguments. Assign number to change it.

Returns

number. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.line_spacing.

Works on Text and Button controls.

const control = ui.new("Button")
debug.log(control.line_spacing)

control.on_click

Set the function called when a Button is clicked.

Arguments

No call arguments. Assign function or nil to change it.

Returns

function or nil. Readable and writable.

Works with

control handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.on_click.

Works on Buttons. The callback takes no arguments.

const control = ui.new("Button")
debug.log(control.on_click)

ui.find(key) or ui.find(document_key, key)

Find a UI control by Script key.

Arguments

key: string. Optional document_key: string matching the document loaded for Play.

Returns

Ui handle, or nil if missing.

Works with

Controls in the active Play document, including keyed runtime controls.

Missing values and errors

Missing keys return nil. Keys are case-sensitive. Display names are not Script keys. A different document key does not load that document.

const health = ui.find("health_text")
if health != nil {
    health.text = "75 / 100"
}

ui.get(key) or ui.get(document_key, key)

Find a UI control by Script key.

Arguments

key: string. Optional document_key: string matching the document loaded for Play.

Returns

Ui handle.

Works with

Controls in the active Play document, including keyed runtime controls.

Missing values and errors

Missing keys report an error. Keys are case-sensitive. Display names are not Script keys. A different document key does not load that document.

const health = ui.get("health_text")
health.text = "75 / 100"

ui.new(element_type)

Create a temporary UI control.

Arguments

element_type: "Panel", "Text", "Button", "Image", or "Video".

Returns

Ui handle.

Works with

Runtime UI.

Missing values and errors

Unsupported element types report an error. Controls are discarded when Play stops.

Images and Videos expose media source and fit. Video controls also expose playback properties; see the UI media guide.

const label = ui.new("Text")
label.text = "Hello"
label.position = [20, 20]
label.size = [200, 40]

ui.delete(handle)

Remove a control during Play.

Arguments

handle: Ui handle.

Returns

nil.

Works with

Runtime and instantiated authored UI controls.

Missing values and errors

Other handle kinds and invalid IDs report an error. This does not delete the saved authored control.

const label = ui.new("Text")
ui.delete(label)

ui.get_viewport_size()

Read the playable viewport size.

Arguments

No arguments.

Returns

[width, height] in pixels.

Works with

The current gameplay viewport.

Missing values and errors

Wrong argument counts or types report an error.

debug.log(ui.get_viewport_size())

control.source

Read or set an Image or Video control's media source.

Arguments

Assign a project media source string.

Returns

Source string. Readable and writable.

Works with

Image and Video controls.

Missing values and errors

A source on a non-media control reports an error. Missing or unreadable media cannot display.

Use a media file imported into the project.

const image = ui.new("Image")
image.source = "Media/title.png"

control.fit

Choose how Image or Video content fits inside its control.

Arguments

Assign a supported media fit mode string.

Returns

Media fit mode string. Readable and writable.

Works with

Image and Video controls.

Missing values and errors

An unrecognized fit mode or unsupported control type reports an error.

const image = ui.new("Image")
image.fit = "Contain"

control.playing

Read or control whether a Video is playing.

Arguments

Assign true or false.

Returns

Boolean. Readable and writable.

Works with

Video controls.

Missing values and errors

Using this property on a non-Video control reports an error.

const video = ui.new("Video")
video.playing = true

control.looped

Read or set whether a Video loops.

Arguments

Assign true or false.

Returns

Boolean. Readable and writable.

Works with

Video controls.

Missing values and errors

Using this property on a non-Video control reports an error.

const video = ui.new("Video")
video.looped = true

control.playback_rate

Read or set the playback speed of a Video.

Arguments

Assign a positive playback speed as a number.

Returns

Playback speed number. Readable and writable.

Works with

Video controls.

Missing values and errors

Using this property on a non-Video control reports an error. Playback behavior depends on decoder support.

const video = ui.new("Video")
video.playback_rate = 1.0

ui.get_z_index_behavior() [BETA]

Read the UI z-index behavior.

Arguments

No arguments.

Returns

String mode.

Works with

Active game UI.

Missing values and errors

Invalid modes or values report errors.

const mode = ui.get_z_index_behavior()

ui.set_z_index_behavior(mode) [BETA]

Set UI z-index behavior.

Arguments

Supported mode string.

Returns

nil.

Works with

Active game UI.

Missing values and errors

Invalid modes or values report errors.

ui.set_z_index_behavior("Global")

ui.get_display_order() [BETA]

Read the global UI display order.

Arguments

No arguments.

Returns

Integer number.

Works with

Active game UI.

Missing values and errors

Invalid modes or values report errors.

const order = ui.get_display_order()

ui.set_display_order(order) [BETA]

Set the UI display order.

Arguments

Finite 32-bit integer.

Returns

nil.

Works with

Active game UI.

Missing values and errors

Invalid modes or values report errors.

ui.set_display_order(5)

control.background_color [BETA]

Read or set the background color.

Arguments

Supported color value.

Returns

The property value when read; assignment updates the control.

Works with

Supported Text, Button, or Panel controls.

Missing values and errors

Unsupported types or target handles report errors.

panel.background_color = [0, 0, 0, 1]

control.font [BETA]

Select a supported UI font family.

Arguments

Font name string.

Returns

The property value when read; assignment updates the control.

Works with

Supported Text, Button, or Panel controls.

Missing values and errors

Unsupported types or target handles report errors.

label.font = "monospace"

control.bold [BETA]

Set bold type.

Arguments

Boolean.

Returns

The property value when read; assignment updates the control.

Works with

Supported Text, Button, or Panel controls.

Missing values and errors

Unsupported types or target handles report errors.

label.bold = true

control.italic [BETA]

Set italic type.

Arguments

Boolean.

Returns

The property value when read; assignment updates the control.

Works with

Supported Text, Button, or Panel controls.

Missing values and errors

Unsupported types or target handles report errors.

label.italic = true

control.rich_text [BETA]

Read or set formatted Text spans.

Arguments

Supported rich text value.

Returns

The property value when read; assignment updates the control.

Works with

Supported Text, Button, or Panel controls.

Missing values and errors

Unsupported types or target handles report errors.

const spans = label.rich_text

control.text_scaled [BETA]

Size text to the control bounds.

Arguments

Boolean.

Returns

The property value when read; assignment updates the control.

Works with

Supported Text, Button, or Panel controls.

Missing values and errors

Unsupported types or target handles report errors.

label.text_scaled = true

control.proportional [BETA]

Select the proportional font setting.

Arguments

Supported font value.

Returns

The property value when read; assignment updates the control.

Works with

Supported Text, Button, or Panel controls.

Missing values and errors

Unsupported types or target handles report errors.

label.font = "proportional"

control.monospace [BETA]

Select the monospace font setting.

Arguments

Supported font value.

Returns

The property value when read; assignment updates the control.

Works with

Supported Text, Button, or Panel controls.

Missing values and errors

Unsupported types or target handles report errors.

label.font = "monospace"