BillboardGui

Show Deprecated

BillboardGuis are containers for GuiObjects that appear in the 3D space. BillboardGuis always face the camera, and can either change size with distance or remain the same size on the screen based on the BillboardGui.Size property.

Their position is relative to the BillboardGui.Adornee. If no Adornee is set, then the parent of the BillboardGui will be used as the adornee. For BaseParts, the Position property will be used. For Attachments, the WorldPosition property will be used.

The Size property of a BillboardGui works slightly differently than GuiObject.Size. The Offset portion works the same, but the Scale portion is used as a size in studs in 3D space.

A size of UDim2.fromScale(4, 5) is 4x5 studs, and scales the UI larger and smaller depending on distance from the camera. A size of UDim2.fromOffset(200, 100) is always 200x100 on the screen, and does not change size with distance. Scale and Offset values can also be combined together, like with GuiObject.Size.

When creating size-scaled BillboardGuis, it's important to make sure all the UI objects within are using Scale sizing and all text has TextLabel.TextScaled enabled, to ensure correct scaling.

The AbsolutePosition property of a BillboardGui and all of its descendants is relative to the top left corner of its canvas, and so is always 0, 0 for the BillboardGui instance.

Caching Static UI for Performance

A Gui's appearance is cached until one of the following events occurs:

  • A descendant is added to the Gui.
  • A descendant is removed from the Gui.
  • A property of a descendant of the Gui changes.
  • A property of the Gui changes.

If any of these events occur, the Gui's appearance will be recomputed the next frame it gets rendered.

Summary

Properties

Controls whether the descendants will receive input events.

Sets the target part or attachment that the BillboardGui is positioned relative to.

Determines whether the BillboardGui will render in front of 3D content or behind it.

Determines the factor by which the GUI's light is scaled when LightInfluence is 0.

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

The current distance in studs that the BillboardGui is from the player's camera.

READ ONLY
NOT REPLICATED

Determines the distance in studs that a BillboardGui will stop scaling larger in size at.

Distance will be rounded to increments of this value.

Determines the distance in studs that a BillboardGui will stop scaling smaller in size at.

Determines how the BillboardGui is offset from its Adornee, relative to the Camera orientation and units are half the dimensions of the model's Camera-aligned bounding box.

Determines how the BillboardGui is offset from its Adornee, relative to the global axes and units are half the dimensions of the model's axis-aligned bounding box.

Controls how much the BillboardGui is influenced by the lighting in the environment.

Sets the maximum distance a billboard can be from the camera and still be drawn.

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

Controls the size that the BillboardGui will have on screen.

A 2D offset in size-relative units that acts like an anchor point.

Determines how the BillboardGui is offset from its Adornee, relative to the Camera orientation and units in studs.

Determines how the BillboardGui is offset from its Adornee, relative to the global axes and units in studs.

Events

Methods

Properties

Active

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

BillboardGuis will only receive user input if they are parented to the PlayerGui. The BillboardGui.Adornee property can be used to target a Part in the workspace while the UI itself is in the PlayerGui.

Adornee

Sets the target part or attachment that the BillboardGui is positioned relative to. If no Adornee is set, then the Parent is used instead.

AlwaysOnTop

Determines whether the BillboardGui will render over top of 3D content, or be occluded by it.

When set to false, the BillboardGui will render like other 3D content, and will be occluded by other 3D objects.

When set to true, it always renders on top of 3D content, and the appearance changes significantly:

Brightness

Brightness determines the factor by which the GUI's emitted light is scaled. By default, this property is 1 and can be set to any number on the range [0, 1000].

By modifying this property, the apparent brightness of a GUI can be better matched to its environment. For instance, a video billboard like those found in Times Square can be made brighter to be clearly visible on a bright day.

This property won't produce any effect in the following scenarios wherein the GUI does not emit light.:

  • When AlwaysOnTop is true, the color of each pixel is the color shown on-screen.
  • When LightInfluence is 1, all light from the GUI is reflected from the environment instead of being emit.

ClipsDescendants

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

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

CurrentDistance

Read Only
Not Replicated

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

DistanceLowerLimit

Determines the distance in studs that a BillboardGui will stop scaling larger in size at relative to the player's current camera. If the distance of the gui is below this value, it will not be scaled any larger than it would be at this distance. The value of this property defaults to 0 studs.

DistanceStep

Determines the size BillboardGui.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 BillboardGui.DistanceLowerLimit.

For example, if this property is set to 0.5 and the player's camera is moving away from the gui starting from 0 then CurrentDistance will increase 0 -> 0.5 -> 1 -> 1.5 -> ... and so forth.

DistanceUpperLimit

Determines the distance in studs that a BillboardGui will stop scaling smaller in size at relative to the player's current camera. If the distance of the gui is above this value, it will not be scaled any smaller than it would be 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.

ExtentsOffset

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

See also:

  • ExtentsOffsetWorldSpace, which works similarly except the offset orientation is relative to the global axes
  • StudsOffset, which works similarly except the units are studs

ExtentsOffsetWorldSpace

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

See also:

LightInfluence

Controls how much the BillboardGui is influenced by the lighting in the environment.

When set to 0, the UI behaves similarly to an LCD screen, acting as its own light source and appearing the same regardless of the surrounding lighting.

When set to 1, the UI behaves similarly to a piece of paper, only reflecting the light from another source.

MaxDistance

The MaxDistance property of a BillboardGui sets how far away in studs that billboard can be from the camera and still be drawn. If the camera and billboard are moved further apart than the maximum distance, then the billboard will not be visible regardless of any other properties of the billboard or any GUI objects it contains. The default value of this property is infinity

If this value is set to less than or equal to 0 then the maximum distance will be treated as infinite and the billboard will always be drawable.

Example


1-- Wait for default camera/control scripts to load
2wait(5)
3
4-- Declare and initialize objects
5local camera = game.Workspace.CurrentCamera
6local part = Instance.new("Part")
7local billboard = Instance.new("BillboardGui")
8local label = Instance.new("TextLabel")
9
10-- Set up camera type
11camera.CameraType = Enum.CameraType.Scriptable
12
13-- Set part's position and lock in place
14part.CFrame = CFrame.new(0, 10, 0)
15part.Anchored = true
16
17-- Set up billboard
18billboard.MaxDistance = 10
19billboard.Adornee = part
20billboard.AlwaysOnTop = true
21billboard.Size = UDim2.new(0, 50, 0, 50)
22
23-- Set up label
24label.Size = UDim2.new(1, 0, 1, 0)
25
26-- Set partents of objects
27label.Parent = billboard
28billboard.Parent = part
29part.Parent = game.Workspace
30
31-- Move camera next to part. Wait a bit and then move camera
32local cameraPosition0 = part.Position + Vector3.new(0, 0, 10)
33local cameraPosition1 = part.Position + Vector3.new(0, 0, 20)
34camera.CFrame = CFrame.new(cameraPosition0, part.Position)
35-- Contents of billboard will be visible here
36wait(2)
37camera.CFrame = CFrame.new(cameraPosition1, part.Position)
38-- Contents of billboard will no longer be visible (outside MaxDistance)
39

PlayerToHideFrom

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

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

Size

Controls the size that the BillboardGui will have on screen.

The Scale component of the Size is interpreted as a size in studs, and the UI will automatically scale with distance if Scale values are used.

The Scale and Offset portions of the size are added together, and can be used at the same time.

SizeOffset

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.

Common Values

SizeOffsetExplanation
0.0, 0.0The default. The UI will be anchored at its center.
0.5, 0.5The UI will anchor at the bottom left.
0.5, -0.5The UI will anchor at the top left.
-0.5, 0.5The UI will anchor at the top right.
-0.5, -0.5The UI will anchor at the bottom right.

See also:

StudsOffset

StudsOffset determines how the BillboardGui is offset from its Adornee, relative to the Camera orientation with units in studs.

See also:

  • StudsOffsetWorldSpace, which works similarly except the offset orientation is relative to the global axes
  • ExtentsOffset, which works similarly except the units are half the dimensions of the model's Camera-aligned bounding box

StudsOffsetWorldSpace

StudsOffsetWorldSpace determines how the BillboardGui is offset from its Adornee, relative to the global axes with units in studs.

See also:

  • StudsOffset, which works similarly except the offset orientation is relative to the Camera
  • ExtentsOffsetWorldSpace, which works similarly except the units are half the dimensions of the model's axis-aligned bounding box

Events

Methods

GetScreenSpaceBounds

Roblox Script Security

Returns