BillboardGui¶
A container for GuiObjects that renders in 3D space facing the camera.
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.
Inheritance¶
Object → Instance → GuiBase → GuiBase2d → LayerCollector → BillboardGui
Nova inheritance: Instance → GuiBase → GuiBase2d → LayerCollector → BillboardGui
Properties¶
Active Supported Property Controls whether the descendants will receive input events.
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.
Adornee Supported Property Sets the target part or attachment that the BillboardGui is positioned relative to.
Sets the target part or attachment that the BillboardGui is positioned relative to.
Sets the target BasePart or Attachment that the BillboardGui is positioned relative to, overriding the parent part or attachment.
AlwaysOnTop Supported Property Renders the billboard on top of world geometry when enabled.
Renders the billboard on top of world geometry when enabled.
Nova's billboard render path checks this property directly.
Brightness Supported Property Scales billboard lighting when LightInfluence is 0.
Scales billboard lighting when LightInfluence is 0.
The property is consumed by the billboard renderer; like modern Roblox,
it only has a visible effect when LightInfluence is zero.
ClipsDescendants Supported Property Whether portions of GuiObjects that fall outside of the BillboardGui canvas borders will be drawn.
Whether portions of GuiObjects that fall outside of the BillboardGui canvas borders will be drawn.
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.
DistanceLowerLimit Supported Property Deprecated Determines the distance in studs at which the BillboardGui will stop scaling larger in size.
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 distance.
DistanceStep Supported Property Determines the size CurrentDistance increments and decrements in studs as the player's camera moves closer and further from the BillboardGui.
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.
DistanceUpperLimit Supported Property Deprecated Determines the distance in studs at which the BillboardGui will stop scaling smaller in size.
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 distance.
This property is ignored if the value is less than 0. The default value
is -1, meaning the property is ignored by default.
Enabled Supported Property Toggles the visibility of this LayerCollector.
Toggles the visibility of this LayerCollector. When false, the
UI contents will not render, process user input, or update in response to
changes.
ExtentsOffset Supported 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-al…
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.
ExtentsOffsetWorldSpace Supported 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 bou…
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.
LightInfluence Supported Property Controls how much world lighting affects the billboard.
Controls how much world lighting affects the billboard.
Nova's billboard renderer consumes this value.
MaxDistance Supported Property Controls how far away the BillboardGui can be displayed before it stops rendering.
Controls how far away the BillboardGui can be displayed before it stops rendering.
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.
PlayerToHideFrom Supported Property Used by scripts to hide the BillboardGui from a specific player.
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.
Size Supported Property Controls the size that the BillboardGui will have on screen.
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.
SizeOffset Supported Property A 2D offset in size-relative units that acts like an anchor point.
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.
StudsOffset Supported Property Determines how the BillboardGui is offset from its Adornee in studs, relative to the Camera orientation.
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.
StudsOffsetWorldSpace Supported Property Determines how the BillboardGui is offset from its Adornee in studs, relative to the global axes.
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.
Inherited members¶
Inherited from LayerCollector: 20 properties, 36 methods, 7 events. They are documented on the base class page.
2 modern Roblox member(s) are not implemented yet — expand to inspect
Members declared by Roblox's BillboardGui class (or by a missing base class) that Nova does not expose. Use this list to scope a migration; the compatibility guide has the recommended workaround.
Properties¶
| Member | Signature | Status | Notes | Flags |
|---|---|---|---|---|
CurrentDistance |
CurrentDistance: float |
Not yet | The current distance in studs that the BillboardGui is from the player's camera. | ReadOnly, NotReplicated |
Methods¶
| Member | Signature | Status | Notes | Flags |
|---|---|---|---|---|
GetScreenSpaceBounds |
BillboardGui:GetScreenSpaceBounds(): Variant |
Not yet | — | RobloxScriptSecurity |
Roblox reference: BillboardGui
Generated from Nova's API dump and Roblox creator-docs. Nova-only members come from the engine's reflection metadata.