UI Systems

What In-Experience UI Is

In-experience UI is the interface you build for the people using your Space: a score in the corner, a status panel, a name floating over a machine. It is made of GUI objects that live in the Space alongside parts. This page is about those objects; the panels, ribbon and tabs of the editor itself are covered on the Studio page.

Screen UI

A ScreenGui in StarterGui draws its elements over the viewport.

Billboards

A BillboardGui inside a part draws a camera-facing card above it.

Scripted

Rune scripts change text, colors and visibility while you play.

The GUI Classes

The classes carry Roblox's names and properties, so imported places keep their interface. Containers hold other elements; leaves draw content.

Scale and Offset

A UDim2 describes a position or size on two axes, each as a scale plus an offset. The scale is a fraction of the parent's size, the offset is a fixed number of pixels, and the two add up. A top-level element measures against the viewport; an element inside a Frame or BillboardGui measures against that container.

In a file a UDim2 is four numbers in the order X scale, X offset, Y scale, Y offset:

The table form { x = { scale = 1.0, offset = 0.0 }, y = { scale = 0.0, offset = 40.0 } } is read too. A two-number [w, h] value is rejected, so a file using it fails to load instead of guessing.

Anchor Point

The anchor point chooses which point of the element sits on its position, as fractions of the element's own size. [0, 0] (the default) hangs the element from its top-left corner, [0.5, 0.5] centers it on the position, and [1, 1] puts its bottom-right corner there.

Layering and Visibility

• z_index orders elements: a higher value draws on top of a lower one.
• visible = false hides that element. On a ScreenGui it hides everything inside; on a Frame it hides only the Frame, not the elements inside it.
• Clipping: a ScrollingFrame on a billboard cuts off anything inside it that extends past its edges.

One Folder per Element

Each GUI element is a folder with an _instance.toml inside it, and nesting the folders nests the elements. The UI tab of the ribbon and the Insert Object dialog (Ctrl+I) create elements this way, inside the ScreenGui, BillboardGui or Frame you have selected, or in StarterGui when nothing is selected.

StarterGui/
  HUD/
    _instance.toml        class_name = "ScreenGui"
    Score/
      _instance.toml      class_name = "TextLabel"
    Panel/
      _instance.toml      class_name = "Frame"
      Status/
        _instance.toml    class_name = "TextLabel"

Single files named by class also load, such as Score.textlabel.toml, Panel.frame.toml or Logo.imagelabel.toml, in StarterGui and in Workspace.

The TOML Format

A GUI file has up to four sections: [metadata] for the class, [instance] for the name, [gui] for layout and appearance, and [text] for anything that shows text. This label sits centered at the top of the screen:

[metadata]
class_name = "TextLabel"
archivable = true

[instance]
name = "Score"

[gui]
position = [0.5, 0.0, 0.0, 24.0]
size = [0.0, 240.0, 0.0, 48.0]
anchor_point = [0.5, 0.0]
background_color = [20, 24, 32]
background_transparency = 0.2
corner_radius = 8.0
z_index = 10

[text]
text = "Score: 0"
text_color = [255, 255, 255]
font_size = 28.0

Colors take three or four numbers. When every number is a whole number they are read as 0 to 255, otherwise as 0.0 to 1.0, so [255, 128, 0] and [1.0, 0.5, 0.0] are the same orange. Keys written in PascalCase, such as BackgroundColor, are read as their snake_case names.

A text element without [instance] name is called _instance

Text, button, box and image elements take their name from [instance] name; frames, ScreenGuis and BillboardGuis take the folder's name. Scripts find elements by name, so give every element a unique name and use the same name for its folder.

Keys Reference

On billboards, a font name containing Bold draws bold and one containing Light or Thin draws light. Changes to a BillboardGui's file apply while the Space is open; the other GUI files are read when the Space opens. Billboard keys are listed in Readable Labels.

Building a HUD

1. On the ribbon's UI tab, click Screen. A ScreenGui appears in StarterGui.
2. Select it in the Explorer, then click Text, Frame, Image or Button. Each new element is created inside the selected container.
3. Style each element in its _instance.toml using the keys above.

Screen UI draws in the viewport while you edit and while you play. A ScreenGui belongs in StarterGui, and an element draws on the screen only when it sits inside one. Set visible = false under [gui] in the ScreenGui's own file to hide the whole overlay.

A new ScreenGui shows its contents after the Space reopens

A ScreenGui created during the session starts drawing its elements the next time the Space is opened; until then they stay hidden. The files are written the moment you insert them, so close and reopen the Space once after adding a ScreenGui.

How It Draws

Screen elements are drawn by the same overlay that draws the editor, above the 3D view, measured in the viewport's logical pixels. Billboards use their own rasterizer, and the two support different subsets of the properties:

In Studio a click on a screen element also reaches the scene, so the part behind a HUD element can still be selected.

Labels over Parts

A BillboardGui is a card in the world that turns to face the camera. It follows whatever it is placed inside, so keep it in the folder of the part it labels. To add one in Studio, select the part, open Insert Object (Ctrl+I), choose BillboardGui, then select the new BillboardGui and add a Text element from the UI tab.

[metadata]
class_name = "BillboardGui"
archivable = true

[gui]
size = [4.0, 0.0, 1.0, 0.0]                 # 4 m x 1 m
units_offset_world_space = [0.0, 2.0, 0.0]  # 2 m above the part's center
always_on_top = true
max_distance = 150.0

[metadata]
class_name = "TextLabel"
archivable = true

[instance]
name = "BeaconText"

[gui]
size = [1.0, 0.0, 1.0, 0.0]     # fill the billboard
background_transparency = 1.0

[text]
text = "Beacon"
text_color = [255, 220, 120]
text_scaled = true
font = "GothamBold"
text_stroke_transparency = 0.0

Saving a BillboardGui's file while the Space is open resizes and moves the live billboard. A BillboardGui placed directly in a Folder is not drawn, because a folder has no position to follow.

Size in Meters

A billboard's size is a UDim2 whose scale is in meters: one meter is 50 pixels of canvas, so a size resolves to scale x 50 + offset pixels, and the world quad is that many pixels divided by 50 meters across. The default, 200 x 50 px, is a card 4 m wide and 1 m tall. Elements inside the billboard lay out against that canvas.

Every billboard is drawn on the CPU into a 192 x 192 px tile of a shared texture. A billboard wider or taller than 3.84 m keeps its full size in the world, but its content is drawn into the same tile and stretched, so large cards look softer than small ones. Billboards farther than 300 m from the camera are not drawn at all.

Readable Labels

With text_scaled = true, a label on a billboard picks the largest font that fits its box, searching from 1 px up to the box's height or 72 px, whichever is larger. Otherwise it uses font_size. An outline (text_stroke_transparency = 0.0) keeps text legible against busy scenes, and a tight max_distance keeps distant labels from crowding the view.

Let the text fill the card

Size the TextLabel [1, 0, 1, 0] so it covers the whole billboard, and put the label at the part's center with always_on_top = true, or lift it with a small z_index when it should still hide behind other parts.

Changing Elements from Rune

Rune scripts change GUI elements by name while you play, for screen elements and billboard contents alike. If two elements share a name, the change goes to one of them.

use eustress::{get_sim_value, set_sim_value, gui_set_text, gui_set_text_color};

pub fn on_init() {
    set_sim_value("hud.time", 0.0);
}

pub fn on_update(dt) {
    let t = get_sim_value("hud.time") + dt;
    set_sim_value("hud.time", t);
    gui_set_text("Score", `Time: ${t}`);
    if t > 30.0 {
        gui_set_text_color("Score", 1.0, 0.3, 0.3, 1.0);
    }
}

The lifecycle of on_init and on_update is covered on the Scripting page.

Play and Stop

When Play starts, Studio records how every GUI element looks. When you stop, it puts every element back and drops any change a script queued in the last frame, so a session never leaves its text or colors behind. Script changes affect only what is drawn; the element's file is not touched.

Buttons and Text Input

Clicking a ScreenGui TextButton during Play will call on_button_click(name) in every Rune script that defines it, with the button's name, so one handler can serve a whole menu. The dispatcher is already in place; the button test that feeds it will be matched to the element type the loader records. TextBox typing, ScrollingFrame scrolling and ImageButton hover and pressed images will follow.

Layouts and Surfaces

UIListLayout, UIGridLayout, UIPadding, UICorner, UIStroke and the other modifiers already load with their settings; a layout pass will apply them. SurfaceGui will draw onto the face of its part, billboards will show real images and honor brightness and light_influence, and a billboard's adornee will attach it to a part named anywhere in the Space.