# BillboardGui

BillboardGui : `SurfaceGuiBase`

## Overview

BillboardGui는 3D 공간에 2D UI 요소(GuiObject)를 배치하면서도 항상 카메라를 향하도록 표시해 주는 UI 컨테이너입니다. 이 컨테이너의 위치는 연결된 BasePart 또는 지정된 Adornee를 기준으로 상대적으로 결정됩니다.

또한 성능 최적화를 위해 BillboardGui는 내부적으로 렌더링 결과를 캐싱하여 변화가 없을 때는 이를 재사용합니다. 그러나 BillboardGui 자체의 속성 변화, 자식 요소의 속성 변경, 또는 자식 요소의 추가/삭제가 발생하면 캐시가 무효화되며, 다음 렌더링 프레임에서 화면 정보가 다시 계산됩니다.

PlayerToHideFrom를 제외한 속성은 **클라이언트 환경에서만 제어**할 수 있습니다.

## Properties

### DistanceLowerLimit

`float`

BillboardGui가 플레이어의 카메라에 너무 가까워졌을 때, 더 이상 확대되지 않도록 제한하는 거리입니다.

#### Code Samples

```lua
local BillboardGui = script.Parent

print(BillboardGui.DistanceLowerLimit)
```

### DistanceUpperLimit

`float`

BillboardGui가 플레이어의 카메라로부터 멀어질 때, 더 이상 작아지지 않도록 제한하는 거리입니다.

#### Code Samples

```lua
local BillboardGui = script.Parent

print(BillboardGui.DistanceUpperLimit)
```

### ExtentsOffsetWorldSpace

`Vector3`

BillboardGui가 렌더링되는 오브젝트로부터 얼마나 떨어져 표시될지를 지정하는 속성입니다.

대상의 크기(Extents)를 기준으로 BillboardGui의 위치를 보정합니다. 캐릭터와 같은 모델 크기에 따라 체력바 UI를 자연스럽게 머리 위에 배치할 때 유용합니다.

대상(부모 Part 또는 Adornee)의 축을 기준으로, 바운드 박스의 각 축 길이의 절반(Extents)에 입력 값(Vector3)을 곱한 만큼 오프셋이 적용됩니다.

#### Code Samples

```lua
local BillboardGui = script.Parent

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

### PlayerToHideFrom

`Player`

BillboardGui를 특정 플레이어에게 표시하지 않도록 지정합니다.

#### Code Samples

```lua
local BillboardGui = script.Parent

BillboardGui.PlayerToHideFrom = player
```

### PositionOffset

`Vector3`

BillboardGui가 렌더링되는 오브젝트로부터 얼마나 떨어져 표시될지를 cm 단위로 지정하는 속성입니다.

이동 방향은 카메라의 현재 방향을 기준으로 계산됩니다.

#### Code Samples

```lua
local BillboardGui = script.Parent

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

### PositionOffsetWorldSpace

`Vector3`

BillboardGui가 렌더링되는 오브젝트로부터 얼마나 떨어져 표시될지를 cm 단위로 지정하는 속성입니다.

이동 방향은 대상 오브젝트를 기준으로 계산됩니다.

#### Code Samples

```lua
local BillboardGui = script.Parent

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

### SizeOffset

`Vector2`

BillboardGui가 렌더링되는 오브젝트로부터 얼마나 떨어져 표시될지를 cm 단위로 지정하는 속성입니다.

이동 방향은 스크린 평면을 기준으로 계산됩니다.

#### Code Samples

```lua
local BillboardGui = script.Parent

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

## Methods

## Events

## See aslo

{% content-ref url="../../../manual/studio-manual/gui" %}
[gui](https://docs.overdare.com/korean/manual/studio-manual/gui)
{% endcontent-ref %}