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