Build on-screen UI

On-screen UI, like a coin counter, a menu or a round timer, lives in StarterGui. Every player gets their own copy when they join. Studio draws StarterGui’s UI on top of the viewport so you can place and size it by hand, the same way you build the world. While you edit, the viewport stands in for the player’s screen.

How UI is organized

• A ScreenGui is one layer of UI. Put ScreenGuis directly in StarterGui, and put UI objects inside them.
• UI objects can hold other UI objects. A child is positioned relative to its parent and is cut off at its parent’s edges.

Object	What it is
Frame	A plain rectangle, for panels, bars and backgrounds.
TextLabel	Text on screen.
TextButton	A clickable text button.
TextBox	A text input field.
ImageLabel	An image on screen.

A coin counter might look like this in the Explorer:

• StarterGui
  • HUD (ScreenGui)
    • Counter (Frame)
      • Count (TextLabel)

Add UI

1. Make sure UI is showing: the toolbar’s Show UI / Hide UI button should be on. It is when Studio opens.

2. Choose Insert > UI > ScreenGui. It goes into StarterGui. Rename it so you can find it later, for example HUD.

3. With the ScreenGui selected, choose Insert > UI and pick an object, such as TextLabel. It goes inside the selected ScreenGui or UI object.

4. Drag it into place and set its text and colors in Properties.

If you insert a UI object while nothing suitable is selected, Studio puts it in the first ScreenGui in StarterGui, and creates a ScreenGui for it if there isn’t one yet.

Select, move and resize

Do this	To
Click	Select the topmost UI object under the cursor. UI is picked before anything in the world behind it.
Shift or Ctrl/⌘ + click	Add to or remove from the selection.
Drag a selected object	Move it, along with anything else selected.
Drag one of the eight handles	Resize. Handles appear when exactly one object is selected.
Hold Shift while resizing	Resize from the center.
Hold Ctrl/⌘ while resizing	Keep the width-to-height ratio.
Hold Alt while dragging	Turn off guide snapping.
Esc during a drag	Cancel and put it back.

As you drag, edges and centers snap to the edges and centers of the parent and of neighboring objects, and pink guide lines show what lined up.

Each drag is one undo step. You can also select UI objects in the Explorer, which is the only way to reach objects that are hidden (visible off) or inside a disabled ScreenGui, since Studio doesn’t draw those.

Position and size: scale and offset

Every UI object places itself with five properties:

Property	Meaning
positionScale	Where it sits, as a fraction of its parent’s size (0 to 1).
position	An extra offset, in pixels.
sizeScale	Its size, as a fraction of its parent’s size (0 to 1).
size	An extra size, in pixels.
anchorPoint	Which point of the object sits at its position. (0, 0) is the top-left corner; (0.5, 0.5) centers it.

Scale and pixels add up. For example, sizeScale (1, 0) with size (0, 40) is a bar that spans the full width of its parent and is 40 pixels tall.

When you move or resize an object in the viewport, Studio keeps your choice of units for each axis. If an axis uses scale only (a scale value and a pixel value of 0), dragging changes the scale. Otherwise dragging changes the pixel value, in whole pixels.

Tip

Players’ screens come in many sizes, and while you edit, the viewport is the screen. Use scale for UI that should stretch or stay put relative to the screen. To center a panel, for example, set its anchorPoint and positionScale to (0.5, 0.5).

Style UI with properties

All UI objects have these properties:

Property	What it does
backgroundColor	The fill color.
backgroundTransparency	0 is solid, 1 is fully see-through.
cornerRadius	Rounds the corners, in pixels.
visible	Shows or hides the object and everything inside it.
zIndex	Among objects with the same parent, higher numbers draw on top.

Text objects (TextLabel, TextButton and TextBox) add:

Property	What it does
text	The text to show.
textColor	The text’s color.
textSize	The text size, from 6 to 200.
fontWeight	normal, medium or bold.
textAlign	left, center or right.
textWrapped	Wraps long text onto more lines.
placeholderText	TextBox only: the hint shown while the box is empty.

ImageLabel has image, the image’s URL, and scaleType: fit, fill or stretch.

A ScreenGui has enabled, which shows or hides the whole layer, and displayOrder: layers with a higher number draw on top of the others.

Make UI do something

UI is driven by LocalScripts, which run on each player’s device. Put a LocalScript inside your ScreenGui: when the game runs, script.parent is that player’s own copy of the ScreenGui.

This LocalScript sits inside a ScreenGui named Menu that contains a TextButton named PlayButton:

StarterGui/Menu/MenuScript.client.ts

import { getChild, print, ScreenGui, script, TextButton } from '@rally/sdk';

const menu = script.parent;
if (!(menu instanceof ScreenGui)) throw new Error('Put this script inside the Menu ScreenGui');

const play = getChild(menu, 'PlayButton', TextButton);
play.activated.connect(() => {
  print('Play was pressed');
});

A TextButton’s activated event fires when it’s clicked or tapped, and a TextBox’s focusLost event fires when the player leaves the field. Learn more in User interface and Write scripts.

Show or hide UI while you build

Select Hide UI in the toolbar to hide the UI layer while you work on the world behind it. Hidden UI doesn’t take clicks, so you can select parts underneath. Select Show UI to bring it back.