- For a tutorial on how to create GUIs, see Tutorial:GUI.
An example of a custom user interface on Roblox.
The Roblox engine features a set of GUI classes used for graphical user interfaces (GUIs). GUI classes are used to customize user interfaces. The engine also has its own built-in user interfaces designed for the end user known as core GUIs which cannot be directly accessed or edited by scripts.
There are two types of GUI: 2D, in which UI elements such as 
Frames and 
TextButtons are visible elements of 2D user interfaces and must be a descendant of a UI container in order to be displayed; 3D, in which most UI elements such as a 
SelectionBox are linked to a 3D object.
In 2D GUI, a 
ScreenGui is a UI container rendered apart from the 3D world and must be parented to a PlayerGui in order to display, while UI containers such as 
SurfaceGui are rendered within the 3D world. The engine also features UI components which affect the properties and appearance of other UI objects around them, reducing the need for scripting and additional images.
The 
StarterGui service serves two functions: As a container, UI containers can be parented to the service. When a 
Player joins or respawns, the service's contents are cloned by the server and parented to the Player's PlayerGui. As an interface, the service is used by client-sided scripts to toggle (hide/show) core GUIs.
In Roblox Studio, UI objects can be created through the UI menu which is opened by selecting the StarterGui or any descendant UI object thereof. Any UI container in the StarterGui are also displayed onto the Roblox Studio's render window if toggled on.
History[]
GUIs were added as a feature on September 24, 2009.[1] Previously, 
Messages and Hints were a primary way of displaying text on-screen.
Core GUIs[]
The engine has its own built-in user interfaces designed for the end user known as core GUIs, many of which can be toggled by passing a CoreGuiType enum through the SetCoreGuiEnabled function of the StarterGui service. Core GUIs are mostly found in the CoreGui service and cannot be directly accessed or edited by scripts other than CoreScripts.
Distinctively, there are six core GUIs: the player list, the health bar, the backpack, the chat, the Emotes menu, and the menu (which cannot be disabled).
2D[]
| Text | Image | |
|---|---|---|
| Label |   TextLabel
|
  ImageLabel
|
| Button | TextButton
|
  ImageButton
|
| Box |   TextBox
|
For 2D user interfaces, the GuiObject serves as a base class for UI elements, Frame being the most basic with only one functionality (Frame.FrameStyle). A GuiObject can be parented to another GuiObject, which will copy its Position and Size properties. There are different types of GuiObjects:
- Frames;
Frame itself, ScrollingFrame, CanvasGroup, ViewportFrame - Text elements that have the Text property; TextLabel, TextButton, TextBox
- Image elements that link to an image file; ImageLabel, ImageButton
- Video element that link to a video file; VideoFrame
In Roblox Studio, UI objects can be created through the UI menu which is opened by selecting the StarterGui or any descendant UI object thereof.
Display[]
In order to display UI elements, they must be parented to a UI container (ScreenGui) which is rendered on-screen, apart from the 3D world. ScreenGuis must be parented to a PlayerGui in order to display. ScreenGuis can also be parented to the StarterGui to be viewed from the Roblox Studio's render window, which can be toggled.
UI elements can also be parented to a SurfaceGui or 
BillboardGui which is rendered within the 3D world. BillboardGuis always face the camera, while SurfaceGuis are rendered onto a part's surface.
Cloning[]
UI containers can be parented to the StarterGui service. When a Player joins or respawns, the StarterGui contents are cloned by the server and parented to the Player's PlayerGui. When the Player respawns, the PlayerGui is emptied first before cloning the contents. This can be avoided for a UI container by setting its ResetOnSpawn property to false.
Ordering[]
Every GuiObject has a ZIndex property. ZIndex orders GuiObjects from back to front (similar to a Z axis). The ZIndex property is an integer, and can be positive, negative or zero. ScreenGui have a ZIndexBehavior property which is set to either of the two ZIndexBehaviors that change how ZIndex is treated:
- Global – The default behavior that sorts all descendant elements in a ScreenGui by their raw ZIndex value.
- Sibling – Sorts all elements that have the same parent. Elements are always rendered on top of their parent.
For ScreenGuis, the DisplayOrder property is used instead.
Text[]
TextLabel, TextButton, and TextBox has a Text property which is a string displayed in the UI element, as well as other properties such as Font which affect how the text is rendered.
Image[]
ImageLabel, and ImageButton has an Image property which is Content that links to an image file displayed in the UI element, as well as other properties such as ResampleMode which affect how the image is rendered.
9-slice[]
The engine supports 9-slice scaling. To avoid aspect ratio distortion, an image is split into nine parts: four corners, four sides, and the center. Corners will have the same aspect ratio, top-bottom sides will scale horizontality, left-right sides will scale vertically and the center will fit to the surrounding four sides. To enable 9-slice scaling for an image element, the ScaleType property must be set to Slice. The Rect (pair of Vector2s) SliceCenter property defines the center part of an image based on the its resolution.
Video[]
Similar to an image element, 
VideoFrame has a Video property which is Content that links to a video file displayed in the UI element. The current supported video format is VP8/VP9, resolution lower than or equal to 720p, and Opus/Vorbis audio.[2]
Button[]
TextButton, and ImageButton have the following events related to mouse inputs:
| Events |
|---|
|
ViewportFrame[]
ViewportFrame allows displaying of descendant parts inside a UI object. No other effects such as shadows, particles and nested UI are supported, so they are not rendered. ViewportFrame can be linked to a 
Camera instance to manipulate its renderer, including the camera represented by the CurrentCamera property of 
Workspace. ViewportFrame's lighting can be changed through its properties. 
WorldModel provides raycasting and motor animation features to its descendant parts, if parented to the ViewportFrame.
Components[]
UI components are used to change the properties and appearance of other UI objects around them automatically, reducing the need for scripting and additional images. There are several sub-classes of the UI component class, collectively split into two categories:
- one where components affects the properties of a UI element (e.g. position and size):
- UIPadding – Adds padding to the parent UI element, effectively adding spacing to borders.
- UIScale – Automatically scales the parent UI element along with all of its descendants. This can be used to fit UI for different screen sizes.
- UIConstraints (used for maintaining sizes for different screen sizes):
- UIAspectRatioConstraint – Locks the aspect ratio to a certain ratio.
- UISizeConstraint – Sets limits to the Size property.
- UITextSizeConstraint – Sets limits to the TextSize property.
- UILayouts (UIGridStyleLayouts which sorts the UI parent's elements onto a grid):
- UIGridLayout – Sets sibling UI elements into uniform cells with the same size.
- UIListLayout – Sorts sibling UI elements into a row while retaining their sizes.
- UITableLayout – Sorts sibling UI elements into a row and sorts each sibling's child elements into a column. Each cell of the row has the same height while each cell of a column have the same width.
- UIPageLayout – Turns sibling UI elements into pages. The Next and Previous functions of the UIPageLayout can be called to switch view to another page.
- another where components affect the appearance of the UI element being rendered:
- UICorner – Changes the corners of the parent UI element to be rounded.
- UIStroke – Applies an outline to text or borders of the parent UI element.
- UIGradient – Applies gradient to the parent UI element, based on the size. This can also be parented to a UIStroke to apply gradient to the outline.
Plugins[]
Roblox Studio allows creating custom widgets through the DockWidgetPluginGui object, which can be created through the CreateDockWidgetPluginGui function of Plugin.
3D[]
Besides 2D interfaces, the engine introduces another set of classes used for 3D interfaces. Most classes use an Adornee property, which is set to an instance.
Selection boxes[]
SelectionBox is used to display a visible selection of a 3D instance, such as a 
Model or a 
Part through the Adornee property.
Selection lassos[]
SelectionPartLasso and SelectionPointLasso renders a line representing a lasso from 
Humanoid to a BasePart and a Vector3 point, respectively. These classes are often used in conjunction with SelectionBox for selecting a part or a point by a user's character.
Parts[]
The PartAdornment abstract class has a BasePart Adornee property:
- SurfaceSelection is used to display a visible selection of a surface of a part, specified by the TargetSurface property which is a NormalId.
- Handles is used to display handles of a part, and ArcHandles is used to display arc handles around the part. Both of these classes belong to the HandlesBase class and must be parented to PlayerGui or the CoreGui in order to be interactive as well as to be able to fire their events.
PVInstance[]
Similar to the PartAdornment class, the PVAdornment abstract class has an Adornee property that is set to a PVInstance object (Model or BasePart):
- SelectionSphere renders a 3D sphere around its Adornee.
- HandleAdornment is an abstract class that represents a handle:
FloorWire[]
FloorWire is a deprecated class that renders a line from a part to another part representing a wire. FloorWire is used by the stamper tool for visualizing wire connections. The line attempts to not intersect with another part:
- From the starting point, the line initially extends downward or upwards until it hits a ground or ceiling where it will then extend in the X axis.
- If it hits a part, it will turn and extend in the Z axis. If it hits another part, it will turn and extend in the X axis. If it hits a corner or has turned 5 times, it will go back to the point where it hit a ground or ceiling and extend in the Z axis instead.
- If it hits another corner or has turned 5 times again, it will give up and render a straight line between both points instead.
- The process repeats until the line extends to the destination point of its axis where it will then turn to the destination.
- If the line also hits another part, it will give up and render a straight line between both points instead.
- If the line reaches the destination, the line's path is rendered.
References[]
- ↑ Shedletsky, John (2009, September 25). "Scriptable GUIs… the coolest Roblox feature since sliced bricks". From Roblox Blog. Accessed February 15, 2023. Archived from the original on September 19, 2020.
- ↑ HereIsRich (2022, February 8). "What type of files/codecs do VideoFrames support?". From DevForum. Archived from the original on February 12, 2023.
External links[]
- User interfaces guide in the Roblox Creator Documentation
Article quality evaluation
⚠️ This article is potentially overdue for a new Article Quality evaluation.
| Programming |
| ||||||
|---|---|---|---|---|---|---|---|
| Design | |||||||
| Assets | |||||||
| Tools | |||||||
| Monetization | |||||||
| Analytics | Developer Stats · Monthly active users (MAU) | ||||||
| Advertising | |||||||
| Resources | |||||||