Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 37 ยท UI and Events

GUI Basics: ScreenGui, Frames, Labels and Buttons

Build your first Roblox interface with ScreenGui, Frame, TextLabel and TextButton, learn where GUIs live, and change them from a LocalScript.

Almost every experience needs some kind of interface: a score at the top of the screen, a shop menu, a health bar, a button that says "Play". Roblox calls these GUIs (graphical user interfaces). A GUI is built from instances, just like the 3D world, but instead of living in the Workspace they are drawn flat on top of the player's screen.

In this lesson you will learn which objects make up a GUI, where they must be stored so that players see them, and how a script changes them while the game runs. Because the real Roblox engine cannot run on this site, the code that talks to Roblox is shown read-only, and the runnable examples are small JavaScript stand-ins that model the same ideas.

The main GUI classes

Every GUI starts with a container. The container decides where the interface is drawn. After that you add GUI objects inside it.

Class What it is for
ScreenGui The container for a flat 2D interface on the player's screen
SurfaceGui A container that draws the interface on the face of a part
BillboardGui A container that floats above a part and always faces the camera
Frame An empty rectangle, used for backgrounds and grouping
TextLabel Shows text that the player cannot click
TextButton Shows text and can be clicked or tapped
ImageLabel / ImageButton Show a picture, with or without click support
TextBox Lets the player type text
ScrollingFrame A frame whose content can scroll

Most of the time you will use a ScreenGui full of Frame, TextLabel and TextButton objects.

Where GUIs live

A GUI only shows up for a player if it sits in that player's PlayerGui folder. You almost never put it there yourself. Instead you place the ScreenGui in StarterGui (in the Explorer window). When a player's character spawns, Roblox copies everything in StarterGui into that player's own PlayerGui.

From Studio to the player's screen

StarterGui You build the GUI here in Studio.
Copied on spawn Each player gets their own copy.
PlayerGui The copy the player really sees.

Changing StarterGui while playing does not change a copy that already exists.

1 / 2

This copy step matters. If a script edits the version in StarterGui while the game is running, players who already spawned do not see the change. Scripts that change the interface must work on the copy inside PlayerGui.

Creating a GUI in Studio

  1. Open the Explorer and hover over StarterGui. Click the + button and insert a ScreenGui. Rename it HUD.
  2. Inside HUD, insert a Frame and a TextLabel.
  3. Select the label. In the Properties window set Text to Coins: 0, TextSize to 28, and pick a Font.
  4. Press Play. The text appears on the screen.

Useful properties you will reuse on nearly every GUI object:

  • Text, TextColor3, TextSize, Font, TextScaled: control the lettering.
  • BackgroundColor3, BackgroundTransparency: the fill behind the object (1 means invisible).
  • Visible: hides or shows the object and everything inside it.
  • Size, Position, AnchorPoint: where the object is and how big. See UI layout and UDim2.
  • ZIndex and LayoutOrder: which object draws on top, and the order in a layout.

ScreenGui.ResetOnSpawn is true by default. Every time the character respawns, Roblox deletes the GUI and copies a fresh one. If your menu should stay open after the player dies, set ResetOnSpawn to false.

Changing a GUI from a script

A script that edits a player's own interface is a LocalScript, because the interface exists only on that player's device. Put the LocalScript inside the ScreenGui, and it can reach its neighbours through the script.Parent property.

LUA
-- LocalScript inside StarterGui > HUD
local gui = script.Parent
local label = gui:WaitForChild("CoinLabel")

local coins = 0

while true do
	task.wait(1)
	coins += 1
	label.Text = "Coins: " .. coins
end

Two details are worth noticing. WaitForChild pauses until the child exists, which avoids a common bug: the GUI is still being copied, and plain gui.CoinLabel would return nil. And Luau supports += as a shortcut for coins = coins + 1.

To find the interface from a different script, go through the player:

LUA
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local playerGui = player:WaitForChild("PlayerGui")
local hud = playerGui:WaitForChild("HUD")

Players.LocalPlayer is only set in a LocalScript. In a normal server Script it is nil.

A runnable stand-in: an instance tree

The runnable code below is not Roblox. It is a tiny JavaScript model of how instances form a tree with a Name, a ClassName, properties and children. It prints the tree like the Explorer window does. Use it to get used to the parent and child idea before you open Studio.

JS Model a GUI tree (JavaScript stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Simulate copying StarterGui to PlayerGui

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second example shows why per-player interfaces are safe: Ana's change never reaches Ben, and the template in StarterGui stays untouched.

Common mistakes

  • Putting a ScreenGui in Workspace. It never appears. Always use StarterGui.
  • Using a server Script to edit one player's interface. It may not replicate the way you expect. Use a LocalScript, and ask the server for anything that must be shared.
  • Forgetting WaitForChild. The GUI may not exist yet when your script starts.
  • Hard-coding pixel sizes. The interface then looks wrong on phones. The next lesson shows how scale fixes this.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where should you place a ScreenGui so that every player sees it?

    Objects in StarterGui are copied into each player's PlayerGui when they spawn.
  2. 2. Which class shows text that the player can click?

    A TextButton is a label that can be clicked or tapped. A TextLabel is display only, and a TextBox is for typing.
  3. 3. Why is WaitForChild used when a LocalScript looks for a GUI object?

    The copy into PlayerGui can finish after the script starts, so asking directly can return nil.
  4. 4. What does setting ResetOnSpawn to false on a ScreenGui do?

    With ResetOnSpawn off, the existing GUI stays and keeps its current state across respawns.

Summary

  • A GUI is a tree of instances: a container (ScreenGui) plus objects like Frame, TextLabel and TextButton.
  • Build it in StarterGui; Roblox copies it into each player's PlayerGui on spawn.
  • Scripts that change the player's own interface are LocalScripts; use WaitForChild to reach children safely.
  • ResetOnSpawn controls whether the GUI is rebuilt after every respawn.
  • Prefer scale-based sizing so interfaces work on every screen.

Next: UI Layout, UDim2 and Responsive Design