docs/types/Screen

Screen

A user interface screen shown to players, which you get back from ui.mount and can change or listen to for clicks.

Fields

mountedboolean

Events

clickedEvent<(Player, string)>

submittedEvent<(Player, string, string)>

item_clickedEvent<(Player, string, number, any)>

You listen to these with :connect, which the Event page covers.

Screen:set

method#

Changes the props of one element on the screen, found by its id.

Screen:set(id: string, props: UiElement) -> ()

example

shop:set("gold", { text = "120 gold" })

Use it forupdating a token counter, or changing the label on a shop button.

idThe id of the element to change.

propsThe props to change; kind, id and children cannot change.

Build a set callkind · id · children · anchor · x · y · 22 more

id

kind
What kind of element it is, and hovering a choice tells you what it looks like.
id
A name of up to 40 letters, digits and underscores, unique in the screen, which buttons and text boxes need so clicked and submitted can tell you which one was used.
children
The elements placed inside a frame, panel or list.
anchor
Where the element sits in a free layout, where fill covers its parent and a root frame without an anchor fills the screen.
x
How many pixels to the right of its anchor the element sits, from -4096 to 4096.
y
How many pixels below its anchor the element sits, from -4096 to 4096.
width
The element's width in pixels from 0 to 4096, and leaving it out makes it fit the content.
height
The element's height in pixels from 0 to 4096, and leaving it out makes it fit the content.
layout
How a frame or panel arranges its children, where free places them by their anchors, and a list is always a column.
gap
The space in pixels between the children of a column, row, grid or list, from 0 to 256.
columns
How many columns a grid has, from 1 to 32.
padding
The space in pixels between the edge of a frame, panel or list and its children, from 0 to 256.
align
How text lines up, or where a column or row places its children, which is start when you leave it out.
text
What a text, button or text box shows, cut off after 1000 characters, and a text element keeps [b], [i] and [color=#RRGGBB] tags.
text_size
The font size in pixels, from 8 to 96.
color
The color of text, the tint of an image or the fill of a progress bar, depending on the kind.
#ffdc78
background
The background color of a panel, button, text box or progress bar.
#14141e
corner
How rounded the background's corners are, as a radius from 0 to 64 pixels.
opacity
How visible the element and everything inside it are, from 0 for invisible to 1 for fully shown, which is the default.
visible
Set it to false to hide the element and everything inside it once its exit transition has played.
enabled
Set it to false to grey out a button or text box, which then sends nothing when players use it.
image
The PNG an image element shows, given by its route on the USBX asset CDN, where an empty string shows nothing.
value
How full a progress bar is, from 0 up to its max.
maxdefault 100
The value that fills a progress bar completely, which must be above 0.
placeholder
The hint an empty text box shows, which is cut off after 100 characters.
max_lengthdefault 100
The most characters a player can type into a text box, from 1 to 1000.
enter
The animation used when the element appears, whether the screen mounts, it is added or it becomes visible.
Inside it: effect, duration, delay, easing
exit
The animation used when the element goes away, whether the screen unmounts, it is removed or it becomes hidden.
Inside it: effect, duration, delay, easing

Screen:add

method#

Adds a new element inside a frame, panel or list on the screen.

Screen:add(parent: string, element: UiElement, index: number?) -> ()

example

shop:add("items", { kind = "button", id = "buy_sword", text = "Sword" })

Use it foradding an item to a shop list or an inventory.

parentThe id of the frame, panel or list to add to.

elementThe element to add, with its children.

indexoptionalIts place among the children, from 1. The end by default.

Build a add callkind · id · children · anchor · x · y · 22 more

parent

kind
What kind of element it is, and hovering a choice tells you what it looks like.
id
A name of up to 40 letters, digits and underscores, unique in the screen, which buttons and text boxes need so clicked and submitted can tell you which one was used.
children
The elements placed inside a frame, panel or list.
anchor
Where the element sits in a free layout, where fill covers its parent and a root frame without an anchor fills the screen.
x
How many pixels to the right of its anchor the element sits, from -4096 to 4096.
y
How many pixels below its anchor the element sits, from -4096 to 4096.
width
The element's width in pixels from 0 to 4096, and leaving it out makes it fit the content.
height
The element's height in pixels from 0 to 4096, and leaving it out makes it fit the content.
layout
How a frame or panel arranges its children, where free places them by their anchors, and a list is always a column.
gap
The space in pixels between the children of a column, row, grid or list, from 0 to 256.
columns
How many columns a grid has, from 1 to 32.
padding
The space in pixels between the edge of a frame, panel or list and its children, from 0 to 256.
align
How text lines up, or where a column or row places its children, which is start when you leave it out.
text
What a text, button or text box shows, cut off after 1000 characters, and a text element keeps [b], [i] and [color=#RRGGBB] tags.
text_size
The font size in pixels, from 8 to 96.
color
The color of text, the tint of an image or the fill of a progress bar, depending on the kind.
#ffdc78
background
The background color of a panel, button, text box or progress bar.
#14141e
corner
How rounded the background's corners are, as a radius from 0 to 64 pixels.
opacity
How visible the element and everything inside it are, from 0 for invisible to 1 for fully shown, which is the default.
visible
Set it to false to hide the element and everything inside it once its exit transition has played.
enabled
Set it to false to grey out a button or text box, which then sends nothing when players use it.
image
The PNG an image element shows, given by its route on the USBX asset CDN, where an empty string shows nothing.
value
How full a progress bar is, from 0 up to its max.
maxdefault 100
The value that fills a progress bar completely, which must be above 0.
placeholder
The hint an empty text box shows, which is cut off after 100 characters.
max_lengthdefault 100
The most characters a player can type into a text box, from 1 to 1000.
enter
The animation used when the element appears, whether the screen mounts, it is added or it becomes visible.
Inside it: effect, duration, delay, easing
exit
The animation used when the element goes away, whether the screen unmounts, it is removed or it becomes hidden.
Inside it: effect, duration, delay, easing

Screen:remove

method#

Removes one element and everything inside it.

Screen:remove(id: string) -> ()

example

shop:remove("buy_sword")

Use it fortaking a sold out item off a shop list.

idThe id of the element to remove, with what is inside it. The root cannot be removed.

Screen:clear

method#

Removes everything inside a frame, panel or list, but keeps the frame itself.

Screen:clear(id: string) -> ()

example

shop:clear("items")

Use it foremptying an inventory list before filling it again.

idThe id of the frame, panel or list to empty.

Screen:unmount

method#

Takes the screen away from everyone it was shown to.

Screen:unmount() -> ()

example

shop:unmount()

Use it forclosing a shop or a menu once the player is done with it.

Screen:bind

method#

Changes the Bindings of a screen made from a UI Screen design, and sends only what changed.

Screen:bind(values: { [string]: any }) -> ()

example

shop:bind({ coins = 1300 })

Use it forupdating tokens or health on a HUD you designed in Studio.

valuesNew values of the UI Screen's Bindings, by name. Bindings left out keep theirs.