Reference API Roblox

Engine API

Website

Related

Reference API Roblox

BillboardGui

A container for GuiObjects that renders in 3D space facing the camera.

Member index 19

HistoryMember
553Active: bool
553Adornee: Instance
553AlwaysOnTop: bool
553Brightness: float
553ClipsDescendants: bool
553CurrentDistance: float
553DistanceLowerLimit: float
553DistanceStep: float
553DistanceUpperLimit: float
553ExtentsOffset: Vector3
553ExtentsOffsetWorldSpace: Vector3
553LightInfluence: float
553MaxDistance: float
553PlayerToHideFrom: Instance
553Size: UDim2
553SizeOffset: Vector2
553StudsOffset: Vector3
553StudsOffsetWorldSpace: Vector3
490GetScreenSpaceBounds(): Variant
inherited from LayerCollector
553Enabled: bool
553ResetOnSpawn: bool
553ZIndexBehavior: ZIndexBehavior
648GetGuiObjectsAtPosition(x: int, y: int): Instances
462GetLayoutNodeTree(): Dictionary
inherited from GuiBase2d
553AbsolutePosition: Vector2
553AbsoluteRotation: float
553AbsoluteSize: Vector2
553AutoLocalize: bool
553RootLocalizationTable: LocalizationTable
553SelectionBehaviorDown: SelectionBehavior
553SelectionBehaviorLeft: SelectionBehavior
553SelectionBehaviorRight: SelectionBehavior
553SelectionBehaviorUp: SelectionBehavior
553SelectionGroup: bool
525SelectionChanged(amISelected: bool, previousSelection: GuiObject, newSelection: GuiObject)
inherited from Instance
553Archivable: bool
635Capabilities: SecurityCapabilities
553Name: string
553Parent: Instance
635Sandboxed: bool
616UniqueId: UniqueId
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
648GetChildren(): Instances
462GetDebugId(scopeLength: int = 4): string
486GetDescendants(): Array
486GetFullName(): string
641GetStyled(name: string): Variant
576GetTags(): Array
576HasTag(tag: 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
648children(): Instances
553clone(): Instance
573destroy(): null
553findFirstChild(name: string, recursive: bool = false): Instance
648getChildren(): Instances
553isDescendantOf(ancestor: Instance): bool
573remove(): null
462AncestryChanged(child: Instance, parent: Instance)
462AttributeChanged(attribute: string)
462ChildAdded(child: Instance)
462ChildRemoved(child: Instance)
462DescendantAdded(descendant: Instance)
462DescendantRemoving(descendant: Instance)
500Destroying()
553childAdded(child: Instance)
inherited from Object
647ClassName: string
647className: string
647GetPropertyChangedSignal(property: string): RBXScriptSignal
647IsA(className: string): bool
650isA(className: string): bool
647Changed(property: string)

Removed member index 1

HistoryMember
310Enabled: bool

Description

BillboardGui is a container for UI objects to appear in the 3D space but always face the camera. The container's position is relative to the parent BasePart or Attachment (or the Adornee). For BaseParts, the Position property is used, while for Attachments, the WorldPosition property is used.

BillboardGui with a TextLabel describing the screen console it floats above.

A billboard's Size property works slightly differently than GuiObject.Size. While the offset components work the same, the scale components are used as stud sizes in 3D space.

When creating a size-scaled BillboardGui that contains a TextLabel, it's useful to enable the label's TextScaled property so that its text scales along with the billboard canvas as the camera distance changes.

Note that interactive UI elements like ImageButtons and TextButtons inside a BillboardGui will only receive user input if they are parented to the PlayerGui, typically via placing the BillboardGui inside StarterGui. The Adornee property can be used to target a part or attachment in the 3D world while the BillboardGui itself remains in the PlayerGui.

See In-Experience UI for a guide on working with BillboardGui containers.

Caching Behavior

To help improve performance, the appearance of a BillboardGui is cached until one of the following occurs, after which its appearance will be recomputed on the next rendering frame.

History 83

Members 19

Active

TypeDefault
boolfalse

Controls whether the descendants will receive input events. If the BillboardGui contains a GuiButton, that button will become clickable only if Active is set to true on both the BillboardGui and the button.

Note that interactive UI elements like ImageButtons and TextButtons inside a BillboardGui will only receive user input if they are parented to the PlayerGui, typically via placing the BillboardGui inside StarterGui. The Adornee property can be used to target a part or attachment in the 3D world while the BillboardGui itself remains in the PlayerGui.

History 4

Adornee

TypeDefault
Instance

Sets the target BasePart or Attachment that the BillboardGui is positioned relative to, overriding the parent part or attachment.

History 5

AlwaysOnTop

TypeDefault
boolfalse

This property determines whether the BillboardGui will always render on top of other 3D objects.

When set to false (default), the BillboardGui renders like other 3D content and is occluded by other 3D objects. When set to true, the BillboardGui always renders on top of 3D content and the appearance changes significantly:

History 4

Brightness

TypeDefault
float1

This property determines the factor by which the BillboardGui container's light is scaled when LightInfluence is 0. By default, this property is 1 and can be set to any number between 0 and 1000. By modifying this property, the apparent brightness of a BillboardGui can be better matched to its environment. For instance, a video billboard can be brightened inside a dark room by increasing Brightness to 10.

Note that Brightness is inaccessible in Studio and has no effect when either LightInfluence is 1 or AlwaysOnTop is true.

History 4

ClipsDescendants

TypeDefault
boolfalse

When set to true (default), portions of GuiObjects that fall outside of the BillboardGui canvas borders will not be drawn.

Even when this property is false, GuiObjects that are completely outside of the canvas will not render.

History 4

CurrentDistance

TypeDefault
float0

The current distance in studs that the BillboardGui is from the player's camera. A changed event does not fire for this property unless DistanceStep is more than 0.

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.

History 4

Tags: [ReadOnly, NotReplicated]

DistanceLowerLimit

TypeDefault
float0

Determines the distance in studs at which the BillboardGui will stop scaling larger in size relative to the player's current camera, with a default of 0. If the CurrentDistance of the BillboardGui is below this value, it will not scale any larger than it would at this DistanceLowerLimit distance.

History 4

DistanceStep

TypeDefault
float0

Determines the size CurrentDistance increments and decrements in studs as the player's camera moves closer and further from the BillboardGui. The property defaults to 0 and rounds up starting from DistanceLowerLimit.

History 4

DistanceUpperLimit

TypeDefault
float-1

Determines the distance in studs at which the BillboardGui will stop scaling smaller in size relative to the player's current camera. If the CurrentDistance of the BillboardGui is above this value, it will not scale any smaller than it would at this DistanceUpperLimit distance.

This property is ignored if the value is less than 0. The default value is -1, meaning the property is ignored by default.

History 4

ExtentsOffset

TypeDefault
Vector30, 0, 0

This property determines how the BillboardGui is offset from its Adornee, relative to the Camera orientation, in units half the dimensions of the model's Camera-aligned bounding box.

See also StudsOffset which works similarly but uses stud units, or ExtentsOffsetWorldSpace which works similarly except the offset orientation is relative to the global axes.

History 4

ExtentsOffsetWorldSpace

TypeDefault
Vector30, 0, 0

This property determines how the BillboardGui is offset from its Adornee, relative to the global axes, in units half the dimensions of the model's axis-aligned bounding box.

See also StudsOffset which works similarly but uses stud units, or ExtentsOffset which works similarly except the offset orientation is relative to the Camera.

History 4

GetScreenSpaceBounds

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

History 1

LightInfluence

TypeDefault
float0

Controls how much the BillboardGui is influenced by environmental lighting, in a range from 0 to 1. Setting this to 1 means that surrounding lighting has complete control over the appearance, while setting it to 0 means that the lighting has no effect.

History 4

MaxDistance

TypeDefault
floatINF

This property controls how far from the camera the BillboardGui will be displayed before it stops rendering. A value of 0 or inf (default) means there is no limit and it will render infinitely far away.

For BillboardGuis that appear outdoors, it's recommended that MaxDistance is high enough to ensure that the container's UI is sufficiently small on the screen when it appears or disappears, minimizing the sudden pop‑in/out effect.

History 4

PlayerToHideFrom

TypeDefault
Instance

Used by scripts to hide the BillboardGui from a specific player.

To hide a BillboardGui from more than one player, place it into StarterGui and use a script to set the Enabled property according to whether the LocalPlayer should be able to see it. The Adornee property can be used to attach the BillboardGui to a BasePart or Attachment in the Workspace, instead of parenting it.

History 5

Size

TypeDefault
UDim2{0, 0}, {0, 0}

Controls the size that the BillboardGui will have on screen. Unlike GuiObject.Size, the scale components of this property set the billboard's stud size in 3D space.

History 4

  • 553 Change Default of Size from to UDim2({0, 0}, {0, 0})
  • 486 Change ThreadSafety of Size from ReadOnly to ReadSafe
  • 462 Change ThreadSafety of Size from to ReadOnly
  • 47 Add Size

SizeOffset

TypeDefault
Vector20, 0

A 2D offset in size-relative units that acts like an anchor point. This can be used similarly to the GuiObject.AnchorPoint property, but the values are different.

Size OffsetExplanation
0, 0The default in which UI will be anchored at its center.
0.5, 0.5UI will anchor at the bottom left.
0.5, -0.5UI will anchor at the top left.
-0.5, 0.5UI will anchor at the top right.
-0.5, -0.5UI will anchor at the bottom right.

See also StudsOffset, StudsOffsetWorldSpace, ExtentsOffset, and ExtentsOffsetWorldSpace which are offset properties that work in 3D space instead.

History 4

StudsOffset

TypeDefault
Vector30, 0, 0

This property determines how the BillboardGui is offset from its Adornee in studs, relative to the Camera orientation.

See also StudsOffsetWorldSpace which works similarly except the offset orientation is relative to the global axes.

History 4

StudsOffsetWorldSpace

TypeDefault
Vector30, 0, 0

This property determines how the BillboardGui is offset from its Adornee in studs, relative to the global axes.

See also StudsOffset which works similarly except the offset orientation is relative to the Camera.

History 4

Removed members 1

Enabled

TypeDefault
bool

History 4

Settings