BillboardGui

BillboardGui : SurfaceGuiBase

Overview

BillboardGui is a UI container used to make the 2D UI elements (GuiObject) placed in 3D space face the camera at all times. The position of this container is determined relatively by the connected BasePart or a specified Adornee.

In addition, BillboardGui internally caches rendering results and reuse them when there are no changes to optimize performance. However, if the properties of BillboardGui itself are changed, the properties of child elements are changed, or child elements are added or removed, the screen information is recalculated in the next rendering frame.

properties except PlayerToHideFrom can be controlled only in client environment.

Properties

CurrentDistance

number

A read-only property that shows the current distance from the camera to the object on which the BillboardGui is rendered.

Code Samples

DistanceLowerLimit

number

The distance at which the BillboardGui stops scaling up when it gets too close to the player's camera.

Code Samples

local BillboardGui = script.Parent

print(BillboardGui.DistanceLowerLimit)

DistanceUpperLimit

number

The distance at which the BillboardGui stops scaling down when it gets too far from the player's camera.

Code Samples

local BillboardGui = script.Parent

print(BillboardGui.DistanceUpperLimit)

ExtentsOffsetWorldSpace

Vector3

A property that can be used to specify the distance between BillboardGui and rendering object when displaying BillboardGui.

Adjusts the position of the BillboardGui based on the target's size (Extents). This is useful for naturally placing UI elements such as health bars above characters, as the position automatically adapts to different model sizes.

The offset is applied along the target's axes (the parent Part or Adornee) by multiplying the input value (Vector3) with half of the bounding box length (Extents) on each axis.

Code Samples

local BillboardGui = script.Parent

BillboardGui.ExtentsOffsetWorldSpace = Vector3.new(0, 5, 0)

PlayerToHideFrom

Player

Specifies BillboardGui so that it will not be displayed to specific players.

Code Samples

local BillboardGui = script.Parent

BillboardGui.PlayerToHideFrom = player

PositionOffset

Vector3

A property that can be used to specify the distance between BillboardGui and rendering object in centimeters when displaying BillboardGui.

Moving direction is calculated based on the direction to which camera is currently facing.

Code Samples

local BillboardGui = script.Parent

BillboardGui.PositionOffset = Vector3.new(0, 100, 0)

PositionOffsetWorldSpace

Vector3

A property that can be used to specify the distance between BillboardGui and rendering object in centimeters when displaying BillboardGui.

Moving direction is calculated based on target object.

Code Samples

local BillboardGui = script.Parent

BillboardGui.PositionOffsetWorldSpace = Vector3.new(0, 100, 0)

SizeOffset

Vector2

A property that can be used to specify the distance between BillboardGui and rendering object in centimeters when displaying BillboardGui.

Moving direction is calculated based on screen plane.

Code Samples

local BillboardGui = script.Parent

BillboardGui.SizeOffset= Vector2.new(0, 100)

Methods

Events

See aslo