BillboardGui

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.

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

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:

• Colors match how they appear inside a ScreenGui.
• Text may appear sharper on high DPI devices.
• BillboardGui.LightInfluence is treated as though it was 0.
• BillboardGui.Brightness has no effect.

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.

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.

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.

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.

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.

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 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 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:

• ExtentsOffset, which works similarly except the offset orientation is relative to the Camera
• StudsOffsetWorldSpace, which works similarly except the units are studs

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.

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

-- Wait for default camera/control scripts to load
task.wait(5)

-- Declare and initialize objects
local camera = workspace.CurrentCamera
local part = Instance.new("Part")
local billboard = Instance.new("BillboardGui")
local label = Instance.new("TextLabel")

-- Set up camera type
camera.CameraType = Enum.CameraType.Scriptable

-- Set part's position and lock in place
part.CFrame = CFrame.new(0, 10, 0)
part.Anchored = true

-- Set up billboard
billboard.MaxDistance = 10
billboard.Adornee = part
billboard.AlwaysOnTop = true
billboard.Size = UDim2.fromOffset(50, 50)

-- Set up label
label.Size = UDim2.fromScale(1, 1)

-- Set parents of objects
label.Parent = billboard
billboard.Parent = part
part.Parent = workspace

-- Move camera next to part. Wait a bit and then move camera
local cameraPosition0 = part.Position + Vector3.new(0, 0, 10)
local cameraPosition1 = part.Position + Vector3.new(0, 0, 20)
camera.CFrame = CFrame.lookAt(cameraPosition0, part.Position)

-- Contents of billboard will be visible here
task.wait(2)
camera.CFrame = CFrame.lookAt(cameraPosition1, part.Position)
-- Contents of billboard will no longer be visible (outside MaxDistance)

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.

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.

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

See also:

• StudsOffset, StudsOffsetWorldSpace, ExtentsOffset, ExtentsOffsetWorldSpace, which are all other offset properties that work in 3D space instead

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 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