For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

DistanceStep

number

Specifies, in cm, the distance interval at which the CurrentDistance value is updated.

With the default of 0, CurrentDistance is updated whenever the distance to the camera changes. If greater than 0, it is updated only when the distance changes by this value or more, so you can reduce the update frequency of scripts that change the UI based on distance.

Code Samples

DistanceUpperLimit

number

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

Code Samples

ExtentsOffset

Vector3

Moves the display position of the BillboardGui based on the size of the object being rendered.

A value of 1 means half the length of each axis of the target's bounding box. The direction of movement is calculated based on the current orientation of the camera.

Code Samples

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

Offset

Vector3

Specifies, in cm, how far from the object being rendered the BillboardGui is displayed.

The direction of movement is calculated based on the current orientation of the camera. It uses the same reference as PositionOffset, and if both properties are specified, their values are added together.

Code Samples

OffsetWorldSpace

Vector3

Specifies, in cm, how far from the object being rendered the BillboardGui is displayed.

The direction of movement is calculated based on the world coordinate axes, so the direction does not change even when the target object rotates. To move based on the axes of the target object, use PositionOffsetWorldSpace.

Code Samples

PlayerToHideFrom

Player

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

Code Samples

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

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

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

Methods

GetScreenSpaceBounds

A method that returns, as a rectangle in pixels, the area the BillboardGui currently occupies on screen.

If the BillboardGui cannot be projected onto the screen, such as when it is behind the camera, it returns a rectangle with a size of 0.

Parameters

Return

Rect

The area occupied on screen.

Code Samples

Events

See also

Last updated