5.9 KiB
| title | description |
|---|---|
| On-screen UI containers | Learn how to display UI objects on a user's screen. |
import DefaultUI from '../includes/ui/default-ui.md' import ScreenInsets from '../includes/ui/screen-insets.md'
The Class.ScreenGui container holds Class.GuiObject|GuiObjects to display on a player's screen, including frames, labels, buttons, and more. All on‑screen UI objects and code are stored and changed on the client.
For UI containers that hold `Class.GuiObject|GuiObjects` that you want to display **within** the 3D world, such as on the face of a part, see [In-Experience UI Containers](../ui/in-experience-containers.md).
To display a Class.ScreenGui and its child Class.GuiObject|GuiObjects to every player who joins the experience, place it inside the Class.StarterGui container. When a player joins an experience and their character first spawns, the Class.ScreenGui and its contents clone into the Class.PlayerGui container for that player, located within the Class.Players container.
By default, `Class.GuiObject|GuiObjects` inside a `Class.ScreenGui` within `Class.StarterGui` appear as an overlay of the [3D viewport](../studio/ui-overview.md#3d-viewport), simulating their appearance and position in a running experience. To hide all such screen overlays, toggle off **GUI overlay** from the [Visualization Options](../studio/ui-overview.md#visualization-options) widget in the upper‑right corner of the 3D viewport.
If `Class.Players.CharacterAutoLoads` is disabled, the contents of `Class.StarterGui` will not be cloned until `Class.Player:LoadCharacter()` is called.
As an experience grows in scope, you may require multiple screen interfaces such as a title screen, settings menu, shop interface, and more. In such cases, you can place multiple unique Class.ScreenGui containers inside Class.StarterGui and toggle each container's Class.ScreenGui.Enabled|Enabled property depending on whether it should be visible and active (while false, contents will not render, process user input, or update in response to changes).
The Class.ScreenGui.Enabled|Enabled property can be initially toggled through the Properties window and/or you can set it during playtime from a client‑side script by accessing the player's Class.PlayerGui and setting it to true or false for the desired container(s).
Container properties
The following properties let you customize the screen insets across multiple devices, the display order when using multiple screen containers, and more.
Screen insets
Display order
When using multiple Class.ScreenGui interfaces, you can layer them by Z‑index through their Class.ScreenGui.DisplayOrder|DisplayOrder property. For example, to display a modal settings menu on one Class.ScreenGui in front of the experience's main user interface on another Class.ScreenGui, assign a higher Class.ScreenGui.DisplayOrder|DisplayOrder to the modal's than the underlying interface's.
Reset on spawn
The Class.ScreenGui.ResetOnSpawn|ResetOnSpawn boolean property determines if the Class.ScreenGui resets (deletes itself and re‑clones into the player's Class.PlayerGui) every time the player's character respawns.
| Condition | Resets |
|---|---|
| `Class.ScreenGui.ResetOnSpawn|ResetOnSpawn` is `true` (default). | |
| The `Class.ScreenGui` is an **indirect** descendant of `Class.StarterGui`; for example it's placed inside a `Class.Folder` located within `Class.StarterGui`. | |
| `Class.ScreenGui.ResetOnSpawn|ResetOnSpawn` is `false` **and** the `Class.ScreenGui` is a **direct** descendant of `Class.StarterGui`. |
Access player UI
As noted, parenting a Class.ScreenGui to Class.StarterGui clones it and its child Class.GuiObject|GuiObjects into a player's Class.PlayerGui container when they join the experience and their character first spawns.
If you need to control a player's UI container during playtime, for example to show/hide a specific Class.ScreenGui or any of its children, access it as follows from a Class.LocalScript:
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local playerGui = player.PlayerGui
local titleScreen = playerGui:WaitForChild("TitleScreen")
local settingsMenu = playerGui:WaitForChild("SettingsMenu")
titleScreen.Enabled = false -- Hide title screen
settingsMenu.Enabled = true -- Show settings menu