StarterGui

Show Deprecated
Not Creatable
Service

The StarterGui service is a container object designed to hold GUI objects such as ScreenGuis.

StarterGui as a container

When a Player.Character respawns, the contents of their PlayerGui are emptied. Children of the StarterGui are then copied along with their descendants into the PlayerGui.

GUI objects such as ScreenGuis with their ResetOnSpawn property set to false will only be placed into each Player's PlayerGui once and will not be deleted when the Player respawns.

StarterGui as an interface

The StarterGui also includes a range of functions allowing you to interact with the CoreGui. For example StarterGui:SetCoreGuiEnabled() can be used to disable elements of the CoreGui. StarterGui:SetCore() can perform a range of functions including creating notifications and system messages.

Summary

Properties

Allows the StarterGui service to process input like PlayerGui and CoreGui do.

HIDDEN
NOT REPLICATED

Sets the default screen orientation mode for users with mobile devices.

Determines whether the contents of StarterGui is visible in studio.

Events

Methods


Returns whether the given CoreGuiTypeis enabled or if it has been disabled using StarterGui:SetCoreGuiEnabled().

RegisterGetCore(parameterName: string, getFunction: function): void  


RegisterSetCore(parameterName: string, setFunction: function): void  


SetCore(parameterName: string, value: Variant): void  

Allows you to perform certain interactions with Roblox's CoreScripts.

SetCoreGuiEnabled(coreGuiType: CoreGuiType, enabled: boolean): void  

Sets whether the CoreGui element associated with the given CoreGuiType is enabled or disabled.

GetCore(parameterName: string): Variant  YIELDS

Returns a variable that has been specified by a Roblox CoreScript.

Properties

ProcessUserInput

Hidden
Not Replicated

Allows the StarterGui service to process input like PlayerGui and CoreGui do. The default value is false.

ScreenOrientation

This property sets the preferred orientation mode for users with mobile devices. For the different modes available, see ScreenOrientation.

When a Player joins the game, if they are using a mobile device, this property will determine the device's starting orientation. PlayerGui.ScreenOrientation will be set to this value for Players joining the game. For example, the following code would set the default to 'Portrait':


1game:GetService("StarterGui").ScreenOrientation = Enum.ScreenOrientation.Portrait
2

By default, this property is set to 'LandscapeSensor', meaning the viewport will rotate so it is always right-side-up in landscape.

Changing this property will not change the ScreenOrientation for Players already in the game. To change the orientation for an existing player use their PlayerGui.ScreenOrientation property.

You can also get the current screen orientation for a user's device using PlayerGui.CurrentScreenOrientation. This is useful when using the 'sensor' ScreenOrientation settings.

ShowDevelopmentGui

This property determines whether the contents of StarterGui is visible in studio

VirtualCursorMode

Not Scriptable

Events

CoreGuiChangedSignal

Roblox Script Security

Parameters

coreGuiType: CoreGuiType
enabled: boolean

Methods

GetCoreGuiEnabled

This function returns whether the given CoreGuiType is enabled or if it has been disabled using StarterGui:SetCoreGuiEnabled().

This function should be called on the client and is used by the core scripts to help determine which core GUI elements to show.

GetCoreGuiEnabled only returns false if the given CoreGuiType has been disabled using StarterGui:SetCoreGuiEnabled(). Setting TopbarEnabled to false using StarterGui:SetCore() hides all CoreGuiTypes and does not affect the result of function.

Parameters

coreGuiType: CoreGuiType

The given CoreGuiType.


Returns

Whether the given CoreGuiType is enabled.

Code Samples

Checking if a Core GUI is Enabled

1local StarterGui = game:GetService("StarterGui")
2
3print(StarterGui:GetCoreGuiEnabled("PlayerList"))

RegisterGetCore

void
Roblox Script Security

Parameters

parameterName: string
getFunction: function

Returns

void

RegisterSetCore

void
Roblox Script Security

Parameters

parameterName: string
setFunction: function

Returns

void

SetCore

void

SetCore (not to be confused with SetCoreGuiEnabled) exposes a variety of functionality defined by Roblox's CoreScripts, such as sending notifications, toggling notifications for badges/points, defining a callback for the reset button or toggling the topbar. The first parameter to SetCore is a string that selects the functionality with which the call will interact: a CoreScript must have registered such a string already (if one hasn't, an error is raised). It may be necessary to make multiple calls to SetCore using pcall in case the respective CoreScript has yet to load (or if it has been disabled entirely).

The following table describes the strings that may be accepted as the first parameter in a call to SetCore. The parameters that should follow are dependent on the functionality that will be used and are described in sub-tables.

ChatActive

Controls whether the chat is active

NameTypeDefaultDescription
activeboolRequiredDetermines whether the chat should be made active

PointsNotificationsActive

Controls whether notifications for earned player points will appear

NameTypeDefaultDescription
activeboolRequiredDetermines whether notifications for earned player points will appear

BadgesNotificationsActive

Controls whether notifications for earned badges will appear

NameTypeDefaultDescription
activeboolRequiredDetermines whether notifications for earned badges will appear

ResetButtonCallback

Determines the behavior, if any, of the reset button given a bool or a BindableEvent to be fired when a player requests to reset.

NameTypeDefaultDescription
enabledboolRequiredDetermines whether the reset button retains its default behavior
OR
callbackBindableEventRequiredA BindableEvent to be fired when the player confirms they want to reset

ChatMakeSystemMessage

Display a formatted message in the chat.

NameTypeDefaultDescription
configTabledictionaryRequiredA dictionary of information describing the message (see below)
NameTypeDefaultDescription
TextstringRequiredThe message to display
ColorColor3Color3.fromRGB(255, 255, 243)The TextColor3 of the message
FontFontSourceSansBoldThe TextLabel/Font|Font of the message
TextSizeInteger18The TextSize of the message

ChatWindowSize

Determines the size of the chat window.

NameTypeDefaultDescription
windowSizeUDim2RequiredDetermines the size of the chat window

ChatWindowPosition

Determines the position of the chat window.

NameTypeDefaultDescription
windowPositionUDim2RequiredDetermines the position of the chat window

ChatBarDisabled

Determines whether the player is able to type a message into the chat.

NameTypeDefaultDescription
disabledboolRequiredDetermines whether the chat's TextBox input is visible.

SendNotification

Causes a non-intrusive notification to appear at the bottom right of the screen. The notification may have up to two buttons.

NameTypeDefaultDescription
configTabledictionaryRequiredA dictionary of information describing the notification (see below)
NameTypeDefaultDescription
TitlestringRequiredThe title of the notification
TextstringRequiredThe main text of the notification
IconstringOptionalThe image to display with the notification
Durationnumber5Duration (in seconds) the notification should stay visible
CallbackBindableFunctionOptionalA BindableFunction that should be invoked with the text of the button pressed by the player.
Button1stringOptionalThe text to display on the first button
Button2stringOptionalThe text to display on the second button

TopbarEnabled

Determines whether the topbar is displayed. Disabling the topbar will also disable all CoreGuis, such as the chat, inventory and player list (i.e. those set with SetCoreGuiEnabled).

When disabled, the region the topbar once occupied will still capture mouse events; however, buttons placed there will not respond to clicks. The origin of GUI space will still be offset 36 pixels from the top of the screen.

NameTypeDefaultDescription
enabledboolRequiredDetermines whether the topbar should be visible

DevConsoleVisible

Determines whether the Developer Console is visible.

NameTypeDefaultDescription
visibilityboolRequiredDetermines whether the developer console is visible

PromptSendFriendRequest

Prompts the current player to send a friend request to the given Player.

NameTypeDefaultDescription
playerPlayerRequiredThe player to which the friend request should be sent

PromptUnfriend

Prompts the current player to remove a given Player from their friends list.

NameTypeDefaultDescription
playerPlayerRequiredThe player who should be unfriended

PromptBlockPlayer

Prompts the current player to block the given Player.

NameTypeDefaultDescription
playerPlayerRequiredThe player who should be blocked

PromptUnblockPlayer

Prompts the current player to unblock the given Player.

NameTypeDefaultDescription
playerPlayerRequiredThe player who should be unblocked

AvatarContextMenuEnabled

Determines whether the Avatar Context Menu is enabled.

NameTypeDefaultDescription
enabledboolRequiredDetermines whether the Avatar Context Menu is enabled

AvatarContextMenuTarget

Forcibly opens the Avatar Context Menu.

NameTypeDefaultDescription
playerPlayerRequiredThe player on whom the ACM will be opened.

AddAvatarContextMenuOption

Adds an option to the Avatar Context Menu.

NameTypeDefaultDescription
optionAvatarContextMenuOptionRequiredFriend (send friend request), Chat (start private chat), or Emote (wave)
OR
optiontableRequiredA two-element table, where the first is the name of the custom action, and the second is a BindableEvent which will be fired with a player was selected when the option was activated.

RemoveAvatarContextMenuOption

Removes an option to the Avatar Context Menu. The option argument must be the same as what was used with AddAvatarContextMenuOption (see above).

NameTypeDefaultDescription
optionVariantRequiredThe same value provided to AddAvatarContextMenuOption

AvatarContextMenuTheme

Configures the customizable Avatar Context Menu (ACM) which is an opt-in feature that allows easy player-to-player social interaction via custom actions, such as initiating trades, battles, and more.

For more info on the ACM including how to customize its theme and use it in your game, see the Avatar Context Menu article.

CoreGuiChatConnections

Sets up a bindable gateway connection between the CoreGui topbar's chat button and the Lua Chat System. The second parameter must be a table of BindableEvents and BindableFunctions. See the example below for more clarification.


1-- Create the Bindable objects
2local ChatConnections = {}
3
4local function AddObjects(bindableClass,targetName,...)
5 local target = ChatConnections[targetName]
6 if not target then
7 target = {}
8 ChatConnections[targetName] = target
9 end
10 local names = {...}
11 for _,name in pairs(names) do
12 local signal = Instance.new(bindableClass)
13 signal.Name = targetName .. "_" .. name
14 signal.Parent = script
15 target[name] = signal
16 end
17end
18
19AddObjects("BindableEvent","ChatWindow",
20 ---------------------------
21 -- Fired from the CoreGui
22 ---------------------------
23 "ToggleVisibility", -- Fired when the CoreGui chat button is pressed.
24 "SetVisible", -- Fired when the CoreGui wants to directly change the visiblity state of the chat window.
25 "FocusChatBar", -- Fired when the CoreGui wants to capture the Chatbar's Focus.
26 "TopbarEnabledChanged", -- Fired when the visibility of the Topbar is changed.
27 "SpecialKeyPressed", -- Fired when the reserved ChatHotkey is pressed.
28 "CoreGuiEnabled", -- Fired when a user changes the SetCoreGuiEnabled state of the Chat Gui.
29
30 ---------------------------
31 -- Fired to the CoreGui
32 ---------------------------
33 "ChatBarFocusChanged",
34 -- ^ Fire this with 'true' when you want to assure the CoreGui that the ChatBar is being focused on.
35
36 "VisibilityStateChanged",
37 -- ^ Fire this with 'true' when the user shows or hides the chat.
38
39 "MessagesChanged",
40 -- ^ Fire this with a number to change the number of messages that have been recorded by the chat window.
41 -- If the CoreGui thinks the chat window isn't visible, it will display the recorded difference between
42 -- the number of messages that was displayed when it was visible, and the number you supply.
43
44 "MessagePosted"
45 -- ^ Fire this to make the player directly chat under Roblox's C++ API.
46 -- This will fire the LocalPlayer's Chatted event.
47 -- Please only fire this on the player's behalf. If you attempt to spoof a player's chat
48 -- to get them in trouble, you could face serious moderation action.
49)
50
51AddObjects("BindableFunction","ChatWindow",
52 "IsFocused" -- This will be invoked by the CoreGui when it wants to check if the chat window is active.
53)
54
55-- The following events are fired if the user calls StarterGui:SetCore(string name, Variant data)
56-- Note that you can only hook onto these ones specifically.
57AddObjects("BindableEvent","SetCore",
58 "ChatMakeSystemMessage",
59 "ChatWindowPosition",
60 "ChatWindowSize",
61 "ChatBarDisabled"
62)
63
64-- The following functions are invoked if the user calls StarterGui:GetCore(string name)
65-- Note that you can only hook onto these ones specifically.
66AddObjects("BindableFunction","GetCore",
67 "ChatWindowPosition", -- Should return a UDim2 representing the position of the chat window.
68 "ChatWindowSize", -- Should return a UDim2 representing the size of the chat window.
69 "ChatBarDisabled" -- Should return true if the chat bar is currently disabled.
70)
71
72-- Connect ChatConnections to the CoreGui.
73local StarterGui = game:GetService("StarterGui")
74local tries = 0
75local maxAttempts = 10
76
77while (tries < maxAttempts) do
78 local success,result = pcall(function ()
79 StarterGui:SetCore("CoreGuiChatConnections",ChatConnections)
80 end)
81 if success then
82 break
83 else
84 tries = tries + 1
85 if tries == maxAttempts then
86 error("Error calling SetCore CoreGuiChatConnections: " .. result)
87 else
88 wait()
89 end
90 end
91end
92
93while wait(0.2) do
94 local isVisible = (math.random() > 0.5)
95 ChatConnections.ChatWindow.VisibilityStateChanged:Fire(isVisible)
96 if not isVisible then
97 local messageCount = math.random(1,120)
98 ChatConnections.ChatWindow.MessagesChanged:Fire(messageCount)
99 end
100end
101

Parameters

parameterName: string

Selects the functionality with which the call will interact: a CoreScript must have registered such a string already (if one hasn't, an error is raised).


Returns

void

No return.

Code Samples

StarterGui Setting Core GUI

1local StarterGui = game:GetService("StarterGui")
2
3StarterGui:SetCore("AvatarContextMenuTheme", {
4 BackgroundImage = "",
5 BackgroundTransparency = 0.5,
6 BackgroundColor = Color3.fromRGB(111, 145, 242),
7 NameTagColor = Color3.fromRGB(0, 0, 200),
8 NameUnderlineColor = Color3.fromRGB(213, 233, 255),
9 ButtonFrameColor = Color3.fromRGB(15, 24, 65),
10 ButtonFrameTransparency = 0.2,
11 ButtonUnderlineColor = Color3.fromRGB(213, 233, 255),
12 Font = Enum.Font.SciFi,
13})

SetCoreGuiEnabled

void

This function sets whether the CoreGui element associated with the given CoreGuiType is enabled or disabled.

The top bar can not be disabled using this function. To disable the top bar, set TopbarEnabled to false using StarterGui:SetCore(). This will also disable the element associated with all CoreGuiTypes.

Parameters

coreGuiType: CoreGuiType

The given CoreGuiType.

enabled: boolean

Whether to enable or disable the given CoreGuiType.


Returns

void

Code Samples

StarterGui:SetCoreGuiEnabled

1local StarterGui = game:GetService("StarterGui")
2StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.All, false)

GetCore

Yields

GetCore returns data set or made available by Roblox's CoreScripts. The first and only parameter is a string that selects the information to be fetched. The following sections describe the strings and the data they return by this function.

Each of these is registered by a CoreScript and calling this function may yield. Many of these also register an equivalent SetCore function (these are marked with an asterisk).

PointsNotificationsActive*

Returns true if player point notifications are enabled.

BadgesNotificationsActive*

Returns true if badge notifications are enabled.

AvatarContextMenuEnabled*

Returns true if the Avatar Context Menu is enabled.

ChatActive*

Returns whether the chat is active or not. This is indicated by the selection state of the top bar's chat icon.

ChatWindowSize*

Returns the size of the chat window as a UDim2.

ChatWindowPosition*

Returns the size of the chat window as a UDim2.

ChatBarDisabled*

Returns true if the chat bar is disabled.

GetBlockedUserIds

Returns a list of Player.UserIds associated with users that have been blocked by the local player.

PlayerBlockedEvent

Returns a BindableEvent that is fired whenever a player is blocked by the local player.

PlayerUnblockedEvent

Returns a BindableEvent that is fired whenever a player is unblocked by the local player.

PlayerMutedEvent

Returns a BindableEvent that is fired whenever a player is muted by the local player.

PlayerUnmutedEvent

Returns a BindableEvent that is fired whenever a player is unmuted by the local player.

PlayerFriendedEvent

Returns a BindableEvent that is fired whenever a player is friended by the local player.

PlayerUnfriendedEvent

Returns a BindableEvent that is fired whenever a player is unfriended by the local player.

DeveloperConsoleVisible*

Returns true if the developer console is visible.

VRRotationIntensity

Returns a string describing the camera rotation sensitivity in VR: Low, High and Smooth. This will not be available unless VRService.VREnabled is true.

Parameters

parameterName: string

Returns

Code Samples

Using GetCore to Check ChatActive

1local StarterGui = game:GetService("StarterGui")
2
3if StarterGui:GetCore("ChatActive") then
4 print("Chat is active")
5else
6 print("Chat is not active")
7end