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

  • Read Parallel

    Controls whether the descendants will receive input events.

  • Read Parallel

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

  • Read Parallel

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

  • Read Parallel

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

  • Read Parallel

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

  • Read Only
    Not Replicated
    Read Parallel

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

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

  • Read Parallel

    Distance will be rounded to increments of this value.

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

  • Read Parallel

    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.

  • Read Parallel

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

  • Read Parallel

    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.

  • Read Parallel

    Controls the size that the BillboardGui will have on screen.

  • Read Parallel

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

  • Read Parallel

    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.

Properties inherited from LayerCollectorProperties inherited from GuiBase2d

Events

Events inherited from GuiBase2d

Properties

Active

Read Parallel

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

Read Parallel

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

Read Parallel

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

Read Parallel

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

Read Parallel

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

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

Read Parallel

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

Read Parallel

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

Read Parallel

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

Read Parallel

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

Read Parallel

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

Read Parallel

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

Read Parallel

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)

PlayerToHideFrom

Read Parallel

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

Read Parallel

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

Read Parallel

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

Read Parallel

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

Read Parallel

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

Methods

Events