BillboardGui
A container for GuiObjects that renders in 3D space facing the camera.
Memory category | Instances |
---|
Member index 19
Removed member index 1
History | Member | |
---|---|---|
310 | Enabled: 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.
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.
- A descendant is added to or removed from the BillboardGui.
- A property of a descendant of the BillboardGui changes.
- A property of the BillboardGui itself changes.
History 83
- 553 Change Default of StudsOffsetWorldSpace from to Vector3(0, 0, 0)
- 553 Change Default of StudsOffset from to Vector3(0, 0, 0)
- 553 Change Default of SizeOffset from to Vector2(0, 0)
- 553 Change Default of Size from to UDim2({0, 0}, {0, 0})
- 553 Change Default of PlayerToHideFrom from to
- 553 Change Default of MaxDistance from to INF
- 553 Change Default of LightInfluence from to 0
- 553 Change Default of ExtentsOffsetWorldSpace from to Vector3(0, 0, 0)
- 553 Change Default of ExtentsOffset from to Vector3(0, 0, 0)
- 553 Change Default of DistanceUpperLimit from to -1
- 553 Change Default of DistanceStep from to 0
- 553 Change Default of DistanceLowerLimit from to 0
- 553 Change Default of CurrentDistance from to 0
- 553 Change Default of ClipsDescendants from to false
- 553 Change Default of Brightness from to 1
- 553 Change Default of AlwaysOnTop from to false
- 553 Change Default of Adornee from to
- 553 Change Default of Active from to false
- 490 Add GetScreenSpaceBounds
- 486 Change ThreadSafety of StudsOffsetWorldSpace from ReadOnly to ReadSafe
- 486 Change ThreadSafety of StudsOffset from ReadOnly to ReadSafe
- 486 Change ThreadSafety of SizeOffset from ReadOnly to ReadSafe
- 486 Change ThreadSafety of Size from ReadOnly to ReadSafe
- 486 Change ThreadSafety of PlayerToHideFrom from ReadOnly to ReadSafe
- 486 Change ThreadSafety of MaxDistance from ReadOnly to ReadSafe
- 486 Change ThreadSafety of LightInfluence from ReadOnly to ReadSafe
- 486 Change ThreadSafety of ExtentsOffsetWorldSpace from ReadOnly to ReadSafe
- 486 Change ThreadSafety of ExtentsOffset from ReadOnly to ReadSafe
- 486 Change ThreadSafety of DistanceUpperLimit from ReadOnly to ReadSafe
- 486 Change ThreadSafety of DistanceStep from ReadOnly to ReadSafe
- 486 Change ThreadSafety of DistanceLowerLimit from ReadOnly to ReadSafe
- 486 Change ThreadSafety of CurrentDistance from ReadOnly to ReadSafe
- 486 Change ThreadSafety of ClipsDescendants from ReadOnly to ReadSafe
- 486 Change ThreadSafety of Brightness from ReadOnly to ReadSafe
- 486 Change ThreadSafety of AlwaysOnTop from ReadOnly to ReadSafe
- 486 Change ThreadSafety of Adornee from ReadOnly to ReadSafe
- 486 Change ThreadSafety of Active from ReadOnly to ReadSafe
- 481 Change Category of Brightness from Appearance to Data
- 480 Add Brightness
- 462 Change ThreadSafety of StudsOffsetWorldSpace from to ReadOnly
- 462 Change ThreadSafety of StudsOffset from to ReadOnly
- 462 Change ThreadSafety of SizeOffset from to ReadOnly
- 462 Change ThreadSafety of Size from to ReadOnly
- 462 Change ThreadSafety of PlayerToHideFrom from to ReadOnly
- 462 Change ThreadSafety of MaxDistance from to ReadOnly
- 462 Change ThreadSafety of LightInfluence from to ReadOnly
- 462 Change ThreadSafety of ExtentsOffsetWorldSpace from to ReadOnly
- 462 Change ThreadSafety of ExtentsOffset from to ReadOnly
- 462 Change ThreadSafety of DistanceUpperLimit from to ReadOnly
- 462 Change ThreadSafety of DistanceStep from to ReadOnly
- 462 Change ThreadSafety of DistanceLowerLimit from to ReadOnly
- 462 Change ThreadSafety of CurrentDistance from to ReadOnly
- 462 Change ThreadSafety of ClipsDescendants from to ReadOnly
- 462 Change ThreadSafety of AlwaysOnTop from to ReadOnly
- 462 Change ThreadSafety of Adornee from to ReadOnly
- 462 Change ThreadSafety of Active from to ReadOnly
- 382 Add DistanceUpperLimit
- 382 Add DistanceStep
- 382 Add DistanceLowerLimit
- 382 Add CurrentDistance
- 340 Add ClipsDescendants
- 329 Change ValueType of PlayerToHideFrom from Object to Instance
- 329 Change ValueType of Adornee from Object to Instance
- 310 Remove Enabled
- 295 Add MaxDistance
- 291 Add LightInfluence
- 281 Add StudsOffsetWorldSpace
- 281 Add ExtentsOffsetWorldSpace
- 257 Add Enabled
- 258 Remove Enabled
- 87 Change Superclass of BillboardGui from GuiBase2d to LayerCollector
- 85 Change Superclass of BillboardGui from GuiBase to GuiBase2d
- 55 Change Tags of BillboardGui from [preliminary] to []
- 50 Add PlayerToHideFrom
- 47 Add StudsOffset
- 47 Add SizeOffset
- 47 Add Size
- 47 Add ExtentsOffset
- 47 Add Enabled
- 47 Add AlwaysOnTop
- 47 Add Adornee
- 47 Add Active
- 47 Add BillboardGui
Members 19
Active
Type | Default | |
---|---|---|
bool | false |
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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
Adornee
Type | Default | |
---|---|---|
Instance |
Sets the target BasePart or Attachment that the BillboardGui is positioned relative to, overriding the parent part or attachment.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
AlwaysOnTop
Type | Default | |
---|---|---|
bool | false |
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:
- Colors match how they appear inside a ScreenGui.
- Text may appear sharper on high DPI devices.
- LightInfluence is treated as though it's
0
. - Brightness has no effect.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of AlwaysOnTop from to false
- 486 Change ThreadSafety of AlwaysOnTop from ReadOnly to ReadSafe
- 462 Change ThreadSafety of AlwaysOnTop from to ReadOnly
- 47 Add AlwaysOnTop
Brightness
Type | Default | |
---|---|---|
float | 1 |
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
.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of Brightness from to 1
- 486 Change ThreadSafety of Brightness from ReadOnly to ReadSafe
- 481 Change Category of Brightness from Appearance to Data
- 480 Add Brightness
ClipsDescendants
Type | Default | |
---|---|---|
bool | false |
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.
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
History 4
- 553 Change Default of ClipsDescendants from to false
- 486 Change ThreadSafety of ClipsDescendants from ReadOnly to ReadSafe
- 462 Change ThreadSafety of ClipsDescendants from to ReadOnly
- 340 Add ClipsDescendants
CurrentDistance
Type | Default | |
---|---|---|
float | 0 |
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
.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | false |
History 4
- 553 Change Default of CurrentDistance from to 0
- 486 Change ThreadSafety of CurrentDistance from ReadOnly to ReadSafe
- 462 Change ThreadSafety of CurrentDistance from to ReadOnly
- 382 Add CurrentDistance
DistanceLowerLimit
Type | Default | |
---|---|---|
float | 0 |
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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of DistanceLowerLimit from to 0
- 486 Change ThreadSafety of DistanceLowerLimit from ReadOnly to ReadSafe
- 462 Change ThreadSafety of DistanceLowerLimit from to ReadOnly
- 382 Add DistanceLowerLimit
DistanceStep
Type | Default | |
---|---|---|
float | 0 |
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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of DistanceStep from to 0
- 486 Change ThreadSafety of DistanceStep from ReadOnly to ReadSafe
- 462 Change ThreadSafety of DistanceStep from to ReadOnly
- 382 Add DistanceStep
DistanceUpperLimit
Type | Default | |
---|---|---|
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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of DistanceUpperLimit from to -1
- 486 Change ThreadSafety of DistanceUpperLimit from ReadOnly to ReadSafe
- 462 Change ThreadSafety of DistanceUpperLimit from to ReadOnly
- 382 Add DistanceUpperLimit
ExtentsOffset
Type | Default | |
---|---|---|
Vector3 | 0, 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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of ExtentsOffset from to Vector3(0, 0, 0)
- 486 Change ThreadSafety of ExtentsOffset from ReadOnly to ReadSafe
- 462 Change ThreadSafety of ExtentsOffset from to ReadOnly
- 47 Add ExtentsOffset
ExtentsOffsetWorldSpace
Type | Default | |
---|---|---|
Vector3 | 0, 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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of ExtentsOffsetWorldSpace from to Vector3(0, 0, 0)
- 486 Change ThreadSafety of ExtentsOffsetWorldSpace from ReadOnly to ReadSafe
- 462 Change ThreadSafety of ExtentsOffsetWorldSpace from to ReadOnly
- 281 Add ExtentsOffsetWorldSpace
GetScreenSpaceBounds
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
Variant |
Security | RobloxScriptSecurity |
---|---|
Thread safety | Unsafe |
History 1
LightInfluence
Type | Default | |
---|---|---|
float | 0 |
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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of LightInfluence from to 0
- 486 Change ThreadSafety of LightInfluence from ReadOnly to ReadSafe
- 462 Change ThreadSafety of LightInfluence from to ReadOnly
- 291 Add LightInfluence
MaxDistance
Type | Default | |
---|---|---|
float | INF |
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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of MaxDistance from to INF
- 486 Change ThreadSafety of MaxDistance from ReadOnly to ReadSafe
- 462 Change ThreadSafety of MaxDistance from to ReadOnly
- 295 Add MaxDistance
PlayerToHideFrom
Type | Default | |
---|---|---|
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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 5
- 553 Change Default of PlayerToHideFrom from to
- 486 Change ThreadSafety of PlayerToHideFrom from ReadOnly to ReadSafe
- 462 Change ThreadSafety of PlayerToHideFrom from to ReadOnly
- 329 Change ValueType of PlayerToHideFrom from Object to Instance
- 50 Add PlayerToHideFrom
Size
Type | Default | |
---|---|---|
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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
SizeOffset
Type | Default | |
---|---|---|
Vector2 | 0, 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 Offset | Explanation |
---|---|
0, 0 | The default in which UI will be anchored at its center. |
0.5, 0.5 | UI will anchor at the bottom left. |
0.5, -0.5 | UI will anchor at the top left. |
-0.5, 0.5 | UI will anchor at the top right. |
-0.5, -0.5 | UI will anchor at the bottom right. |
See also StudsOffset, StudsOffsetWorldSpace, ExtentsOffset, and ExtentsOffsetWorldSpace which are offset properties that work in 3D space instead.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of SizeOffset from to Vector2(0, 0)
- 486 Change ThreadSafety of SizeOffset from ReadOnly to ReadSafe
- 462 Change ThreadSafety of SizeOffset from to ReadOnly
- 47 Add SizeOffset
StudsOffset
Type | Default | |
---|---|---|
Vector3 | 0, 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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of StudsOffset from to Vector3(0, 0, 0)
- 486 Change ThreadSafety of StudsOffset from ReadOnly to ReadSafe
- 462 Change ThreadSafety of StudsOffset from to ReadOnly
- 47 Add StudsOffset
StudsOffsetWorldSpace
Type | Default | |
---|---|---|
Vector3 | 0, 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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of StudsOffsetWorldSpace from to Vector3(0, 0, 0)
- 486 Change ThreadSafety of StudsOffsetWorldSpace from ReadOnly to ReadSafe
- 462 Change ThreadSafety of StudsOffsetWorldSpace from to ReadOnly
- 281 Add StudsOffsetWorldSpace