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

Methods

Methods inherited from BasePlayerGui

Properties

ProcessUserInput

hidden
not replicated
read parallel

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

RtlTextSupport

not scriptable
read parallel

ScreenOrientation

read parallel

This property sets the preferred orientation mode for users with mobile devices. For the different modes available, see Enum.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':


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

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 Enum.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' Enum.ScreenOrientation settings.

ShowDevelopmentGui

read parallel

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

VirtualCursorMode

not scriptable
read parallel

Methods

GetCoreGuiEnabled

This function returns whether the given Enum.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 Enum.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: Enum.CoreGuiType

The given Enum.CoreGuiType.


Returns

Whether the given Enum.CoreGuiType is enabled.

Code Samples

Checking if a Core GUI is Enabled

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

SetCore

void

SetCore (not to be confused with SetCoreGuiEnabled) exposes a variety of functionality defined by Roblox's Class.CoreScript|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
FontEnum.FontSourceSansBoldThe 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
optionEnum.AvatarContextMenuOptionRequiredFriend (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.


-- Create the Bindable objects
local ChatConnections = {}
local function AddObjects(bindableClass,targetName,...)
local target = ChatConnections[targetName]
if not target then
target = {}
ChatConnections[targetName] = target
end
local names = {...}
for _,name in names do
local signal = Instance.new(bindableClass)
signal.Name = targetName .. "_" .. name
signal.Parent = script
target[name] = signal
end
end
AddObjects("BindableEvent","ChatWindow",
---------------------------
-- Fired from the CoreGui
---------------------------
"ToggleVisibility", -- Fired when the CoreGui chat button is pressed.
"SetVisible", -- Fired when the CoreGui wants to directly change the visibility state of the chat window.
"FocusChatBar", -- Fired when the CoreGui wants to capture the Chatbar's Focus.
"TopbarEnabledChanged", -- Fired when the visibility of the Topbar is changed.
"SpecialKeyPressed", -- Fired when the reserved ChatHotkey is pressed.
"CoreGuiEnabled", -- Fired when a user changes the SetCoreGuiEnabled state of the Chat Gui.
---------------------------
-- Fired to the CoreGui
---------------------------
"ChatBarFocusChanged",
-- ^ Fire this with 'true' when you want to assure the CoreGui that the ChatBar is being focused on.
"VisibilityStateChanged",
-- ^ Fire this with 'true' when the user shows or hides the chat.
"MessagesChanged",
-- ^ Fire this with a number to change the number of messages that have been recorded by the chat window.
-- If the CoreGui thinks the chat window isn't visible, it will display the recorded difference between
-- the number of messages that was displayed when it was visible, and the number you supply.
"MessagePosted"
-- ^ Fire this to make the player directly chat under Roblox's C++ API.
-- This will fire the LocalPlayer's Chatted event.
-- Please only fire this on the player's behalf. If you attempt to spoof a player's chat
-- to get them in trouble, you could face serious moderation action.
)
AddObjects("BindableFunction","ChatWindow",
"IsFocused" -- This will be invoked by the CoreGui when it wants to check if the chat window is active.
)
-- The following events are fired if the user calls StarterGui:SetCore(string name, Variant data)
-- Note that you can only hook onto these ones specifically.
AddObjects("BindableEvent","SetCore",
"ChatMakeSystemMessage",
"ChatWindowPosition",
"ChatWindowSize",
"ChatBarDisabled"
)
-- The following functions are invoked if the user calls StarterGui:GetCore(string name)
-- Note that you can only hook onto these ones specifically.
AddObjects("BindableFunction","GetCore",
"ChatWindowPosition", -- Should return a UDim2 representing the position of the chat window.
"ChatWindowSize", -- Should return a UDim2 representing the size of the chat window.
"ChatBarDisabled" -- Should return true if the chat bar is currently disabled.
)
-- Connect ChatConnections to the CoreGui.
local StarterGui = game:GetService("StarterGui")
local tries = 0
local maxAttempts = 10
while (tries < maxAttempts) do
local success,result = pcall(function ()
StarterGui:SetCore("CoreGuiChatConnections",ChatConnections)
end)
if success then
break
else
tries += 1
if tries == maxAttempts then
error("Error calling SetCore CoreGuiChatConnections: " .. result)
else
task.wait()
end
end
end
while task.wait(0.2) do
local isVisible = (math.random() > 0.5)
ChatConnections.ChatWindow.VisibilityStateChanged:Fire(isVisible)
if not isVisible then
local messageCount = math.random(1,120)
ChatConnections.ChatWindow.MessagesChanged:Fire(messageCount)
end
end

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).

value: Variant

Returns

void

Code Samples

StarterGui Setting Core GUI

local StarterGui = game:GetService("StarterGui")
StarterGui:SetCore("AvatarContextMenuTheme", {
BackgroundImage = "",
BackgroundTransparency = 0.5,
BackgroundColor = Color3.fromRGB(111, 145, 242),
NameTagColor = Color3.fromRGB(0, 0, 200),
NameUnderlineColor = Color3.fromRGB(213, 233, 255),
ButtonFrameColor = Color3.fromRGB(15, 24, 65),
ButtonFrameTransparency = 0.2,
ButtonUnderlineColor = Color3.fromRGB(213, 233, 255),
Font = Enum.Font.SciFi,
})

SetCoreGuiEnabled

void

This function sets whether the CoreGui element associated with the given Enum.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: Enum.CoreGuiType

The given Enum.CoreGuiType.

enabled: bool

Whether to enable or disable the given Enum.CoreGuiType.


Returns

void

Code Samples

StarterGui:SetCoreGuiEnabled

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

GetCore

Variant
yields

GetCore returns data set or made available by Roblox's Class.CoreScript|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 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.

DevConsoleVisible*

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

Variant

Code Samples

Using GetCore to Check ChatActive

local StarterGui = game:GetService("StarterGui")
if StarterGui:GetCore("ChatActive") then
print("Chat is active")
else
print("Chat is not active")
end

Events