@usbx/ui

Messages, HUD and screens

local ui = require("@usbx/ui")

chatfunction toastfunction announcefunction popupfunction close_popupfunction countdownfunction progressfunction scoreboardfunction mountfunction screenfunction

ui.chat

function#

Sends a System Message to the players.

ui.chat(target: Target?, options: { … }) -> ()

example

ui.chat(player, { text = "You found a coin!" })

Use it forannouncing rewards, round results or server news as a message in chat.

targetoptionalOne player, a list of players, or nil for every player in the game now.

optionsThe message and its color.

Build a chat calltext · color

target

textrequired
The text of the message that appears in the chat.
color
The color the text of the chat message is shown in.
#ffd700

ui.toast

function#

Shows a Toast, which closes by itself.

ui.toast(target: Target?, options: { … }) -> ()

example

ui.toast(player, { title = "Saved", text = "Your progress is saved.", variant = "success" })

Use it forquick notices like "Item bought" or "Progress saved" that close by themselves.

targetoptionalOne player, a list of players, or nil for every player in the game now.

optionsWhat the Toast says and how it looks.

Build a toast calltext · title · variant · duration

target

textrequired
The main message the toast shows below its title.
title
An optional title shown above the toast's message.
variant
The style of the toast, which is info when you leave it out.
duration
How many seconds the toast stays on screen, which is 5 when you leave it out and at most 60.

ui.announce

function#

Shows an Announcement at the top of the screen.

ui.announce(target: Target?, options: { … }) -> ()

example

ui.announce(players.all(), { text = "Round starts" })

Use it forbig messages at the top of the screen, like "Round starts" or "Red team wins".

targetoptionalOne player, a list of players, or nil for every player in the game now.

optionsWhat the Announcement says and how it looks.

Build a announce calltext · variant · duration

target

textrequired
The message the announcement shows to players.
variant
The style of the announcement, which is info when you leave it out.
duration
How many seconds the announcement stays on screen, which is 4 when you leave it out and at most 60.

ui.popup

functionwaits#

Shows a Popup and yields until the player answers. Gives nil when the player leaves, it times out, ui.close_popup or a newer Popup closes it, the script stops, or the answer does not fit the input.

ui.popup(player: Player, options: PopupOptions) -> PopupAnswer?

example

local answer = ui.popup(player, { title = "Ready?", text = "Start the round?", buttons = { "Yes", "No" } })

Use it forasking players a yes or no question, or letting them type in a name.

playerThe player who sees it.

optionsWhat the Popup says and asks.

Build a popup calltitle · text · buttons · variant · input · timeout

player

titlerequired
The title the popup shows to the player.
textrequired
The message the popup shows to the player.
buttons
The labels of the buttons, up to 3, and one OK button shows when you leave it out.
variant
The popup's style, which is info when you leave it out.
input
Adds a box for the player to type into, where kind sets whether it takes text or a number.
Inside it: kind, placeholder, max_length, min, max
timeout
How many seconds until the popup closes by itself and gives nil, where nil or 0 waits forever.

ui.close_popup

function#

Closes the player's open Popup; its ui.popup gives nil.

ui.close_popup(player: Player) -> ()

example

ui.close_popup(player)

Use it forclosing a question when the round ends or time runs out before the player answers.

playerThe player whose Popup closes.

ui.countdown

function#

Shows a countdown on the HUD. A nil target also reaches players who join later.

ui.countdown(target: Target?, options: { … }) -> Countdown

example

local countdown = ui.countdown(nil, { seconds = 30, label = "Round ends" })

Use it forround timers, lobby waits, or bomb countdowns that show on the HUD.

targetoptionalOne player, a list of players, or nil for everyone.

optionsThe time and the label.

Build a countdown callseconds · label · variant

target

secondsrequired
How many seconds to count down from, up to 86400, which is one day.
label
Text shown next to the time while it counts down.
variant
The style of the countdown, which is info when you leave it out.

ui.progress

function#

Shows a progress bar on the HUD. A nil target also reaches players who join later.

ui.progress(target: Target?, options: { … }) -> Progress

example

local bar = ui.progress(player, { label = "Loading", value = 0, max = 100 })

Use it forcapture point meters, loading bars, or showing how far along a quest is.

targetoptionalOne player, a list of players, or nil for everyone.

optionsThe label and how full the bar is.

Build a progress calllabel · value · max · variant

target

label
The text on the bar, and showing a bar with the same target and label updates that bar instead of adding another.
value
How full the bar is, from 0 up to max.
maxdefault 1
The number that counts as a completely full bar.
variant
The style of the bar, which is info when you leave it out.

ui.scoreboard

function#

Shows or hides the scoreboard of Leaderstats.

ui.scoreboard(target: Target?, options: { … }) -> ()

example

ui.scoreboard(nil, { visible = false })

Use it forhiding the scores during a cutscene or a surprise round, and showing them again after.

targetoptionalOne player, a list of players, or nil for everyone.

optionsWhether it shows.

Build a scoreboard callvisible

target

visible
Whether the scoreboard shows, so false hides it, and it is shown when you leave it out.

ui.mount

function#

Shows a screen built from UI elements: panels, text, images, buttons, text boxes, lists and bars. With the name of a UI Screen designed in Studio, the screen is built from the design and the values.

ui.mount(target: Target?, root: UiElement | string, values: { … }?) -> Screen

example

local shop = ui.mount(player, { kind = "panel", anchor = "center", children = { { kind = "button", id = "buy", text = "Buy" } } })

Use it forshops, inventories, menus or your own HUD, built from panels, text and buttons.

targetoptionalOne player, a list of players, or nil for everyone.

rootThe element at the top of the screen, with its children; or the name of a UI Screen designed in Studio, such as "Shop".

valuesoptionalFor a UI Screen: the values of its Bindings by name, such as { coins = 120 }. A Binding left out shows empty, or the value of the State it follows. An unknown name is an error.

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

target

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

ui.screen

function#

A UI Screen designed in Studio, by name or path, to hear the buttons of every screen shown from it. An unknown name is an error.

ui.screen(design: string) -> UiScreen

example

ui.screen("Shop").clicked:connect(function(player, element) print(element) end)

Use it forhandling one screen's button clicks for all players in one place.

designThe name or path of a UI Screen designed in Studio, such as "Shop".

ui.chat

ui.toast

ui.announce

ui.close_popup

ui.countdown

ui.progress

ui.scoreboard

ui.mount

ui.screen

Tip of the day

HOME Menu