Reference API Roblox

Engine API

Website

Related

Reference API Roblox

PlayerGui

A container for a Player's currently rendered ScreenGuis.

This class is not creatable. Instances of this class cannot be created with Instance.new.
This class is player-replicated. Its data is replicated between the server and only a single client.
Memory categoryInstances
Tags: [NotCreatable, PlayerReplicated]

Member index 6

HistoryMember
553CurrentScreenOrientation: ScreenOrientation
553ScreenOrientation: ScreenOrientation
553SelectionImageObject: GuiObject
462GetTopbarTransparency(): float
573SetTopbarTransparency(transparency: float): null
462TopbarTransparencyChangedSignal(transparency: float)
inherited from BasePlayerGui
462GetGuiObjectsAtPosition(x: int, y: int): Objects
462GetGuiObjectsInCircle(position: Vector2, radius: float): Objects
inherited from Instance
553Archivable: bool
635Capabilities: SecurityCapabilities
553ClassName: string
553Name: string
553Parent: Instance
635Sandboxed: bool
616UniqueId: UniqueId
553className: string
576AddTag(tag: string): null
573ClearAllChildren(): null
462Clone(): Instance
573Destroy(): null
486FindFirstAncestor(name: string): Instance
486FindFirstAncestorOfClass(className: string): Instance
486FindFirstAncestorWhichIsA(className: string): Instance
486FindFirstChild(name: string, recursive: bool = false): Instance
486FindFirstChildOfClass(className: string): Instance
486FindFirstChildWhichIsA(className: string, recursive: bool = false): Instance
486FindFirstDescendant(name: string): Instance
563GetActor(): Actor
486GetAttribute(attribute: string): Variant
462GetAttributeChangedSignal(attribute: string): RBXScriptSignal
631GetAttributes(): Dictionary
486GetChildren(): Objects
462GetDebugId(scopeLength: int = 4): string
486GetDescendants(): Array
486GetFullName(): string
462GetPropertyChangedSignal(property: string): RBXScriptSignal
641GetStyled(name: string): Variant
576GetTags(): Array
576HasTag(tag: string): bool
486IsA(className: string): bool
486IsAncestorOf(descendant: Instance): bool
486IsDescendantOf(ancestor: Instance): bool
580IsPropertyModified(name: string): bool
573Remove(): null
576RemoveTag(tag: string): null
580ResetPropertyToDefault(name: string): null
573SetAttribute(attribute: string, value: Variant): null
462WaitForChild(childName: string, timeOut: double): Instance
553children(): Objects
553clone(): Instance
573destroy(): null
553findFirstChild(name: string, recursive: bool = false): Instance
553getChildren(): Objects
462isA(className: string): bool
553isDescendantOf(ancestor: Instance): bool
573remove(): null
462AncestryChanged(child: Instance, parent: Instance)
462AttributeChanged(attribute: string)
462Changed(property: string)
462ChildAdded(child: Instance)
462ChildRemoved(child: Instance)
462DescendantAdded(descendant: Instance)
462DescendantRemoving(descendant: Instance)
500Destroying()
553childAdded(child: Instance)

Description

The PlayerGui object is a container that holds a player's user GUI. If a ScreenGui is a descendant of a PlayerGui, then any GuiObject inside of the ScreenGui will be drawn to the player's screen. Any LocalScript will run as soon as it is inserted into a PlayerGui.

When a player first joins a game, their PlayerGui is automatically inserted into their Player object. When the player's Player.Character spawns for the first time all of the contents of StarterGui are automatically copied into the player's PlayerGui. Note that if Players.CharacterAutoLoads is set to false the character will not spawn and StarterGui contents will not be copied until Player:LoadCharacter() is called. If StarterGui.ResetPlayerGuiOnSpawn is set to true then every time the player's character respawns all of the contents of that player's PlayerGui is cleared and replaced with the contents of StarterGui.

1
2

-- Accessing PlayerGui from a LocalScript:
game:GetService("Players").LocalPlayer:WaitForChild("PlayerGui")

History 31

Members 6

CurrentScreenOrientation

TypeDefault
ScreenOrientationLandscapeLeft

Describes the user's current screen orientation.

This property is not replicated. Its interface does not cross the network boundary.
This property is read-only. Its value can be read, but it cannot be modified.
Thread safetyReadSafe
CategoryData
Loaded/Savedfalse

History 4

Tags: [ReadOnly, NotReplicated]

GetTopbarTransparency

Parameters (0)
No parameters.
Returns (1)
float

Returns the transparency of the Topbar.

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.
Thread safetyUnsafe

History 5

Tags: [Deprecated]

ScreenOrientation

TypeDefault
ScreenOrientationLandscapeSensor

Sets the preferred screen orientation mode for this user, if the user is on a mobile device.

Thread safetyReadSafe
CategoryData
Loaded/Savedtrue

History 4

SelectionImageObject

TypeDefault
GuiObject

Overrides the default selection adornment (used for gamepads). For best results, this should point to a GuiObject.

Thread safetyReadSafe
CategoryAppearance
Loaded/Savedtrue

History 5

SetTopbarTransparency

Parameters (1)
transparencyfloat
Returns (1)
null

SetTopbarTransparency sets the transparency of the Topbar CoreGui. A value of 0 is completely opaque, and a value of 1 is completely transparent. Values outside of the range [0, 1] are clamped. The default transparency of the topbar is 0.5. The current transparency can be retrieved using the similarly-named GetTopbarTransparency function.

Comparison of Values

The screenshots below show the topbar at 1.0, 0.5 and 0.0 transparency. The TopBar with a transparency of 1.0 (completely hidden)] The TopBar with a transparency of 0.5 (50% transparency)] The TopBar with a transparency of 0.0 (completely opaque)

Usage

This method is often used when re-styling the topbar to match the visual aesthetic of a game. By hiding the topbar, you can create your own custom topbar. See the code samples for an example.

Alternative

Using the StarterGui:SetCore() method with the TopbarEnabled option allows you to enable/disable the entire topbar and all of its features (player list, health, etc). By contrast, this method only affects how the topbar is displayed.

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.
Thread safetyUnsafe

History 6

Tags: [Deprecated]

TopbarTransparencyChangedSignal

Parameters (1)
transparencyfloat

Fires when the transparency of the Topbar CoreGui changes.

This event is deprecated. It exists only for backward compatibility, and should not be used for new work.
Thread safetyUnsafe

History 5

Tags: [Deprecated]

Settings