> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/korean/development/api-reference/classes/billboardgui.md). # BillboardGui BillboardGui : `SurfaceGuiBase` ## Overview BillboardGui는 3D 공간에 2D UI 요소(GuiObject)를 배치하면서도 항상 카메라를 향하도록 표시해 주는 UI 컨테이너입니다. 이 컨테이너의 위치는 연결된 BasePart 또는 지정된 Adornee를 기준으로 상대적으로 결정됩니다. 또한 성능 최적화를 위해 BillboardGui는 내부적으로 렌더링 결과를 캐싱하여 변화가 없을 때는 이를 재사용합니다. 그러나 BillboardGui 자체의 속성 변화, 자식 요소의 속성 변경, 또는 자식 요소의 추가/삭제가 발생하면 캐시가 무효화되며, 다음 렌더링 프레임에서 화면 정보가 다시 계산됩니다. PlayerToHideFrom를 제외한 속성은 **클라이언트 환경에서만 제어**할 수 있습니다. ## Properties ### CurrentDistance `number` 카메라에서 BillboardGui가 렌더링되는 오브젝트까지의 현재 거리를 나타내는 읽기 전용 속성입니다. #### Code Samples ### DistanceLowerLimit `number` BillboardGui가 플레이어의 카메라에 너무 가까워졌을 때, 더 이상 확대되지 않도록 제한하는 거리입니다. #### Code Samples ```lua local BillboardGui = script.Parent print(BillboardGui.DistanceLowerLimit) ``` ### DistanceStep `number` CurrentDistance 값을 갱신하는 거리 간격을 cm 단위로 지정합니다. 기본값 0이면 카메라와의 거리가 바뀔 때마다 CurrentDistance가 갱신됩니다. 0보다 크면 거리가 이 값 이상 바뀔 때만 갱신되므로, 거리에 따라 UI를 바꾸는 스크립트의 갱신 빈도를 줄일 수 있습니다. #### Code Samples ```lua local BillboardGui = script.Parent BillboardGui.DistanceStep = 100 ``` ### DistanceUpperLimit `number` BillboardGui가 플레이어의 카메라로부터 멀어질 때, 더 이상 작아지지 않도록 제한하는 거리입니다. #### Code Samples ```lua local BillboardGui = script.Parent print(BillboardGui.DistanceUpperLimit) ``` ### ExtentsOffset `Vector3` 렌더링되는 오브젝트의 크기를 기준으로 BillboardGui의 표시 위치를 보정하는 오프셋을 지정합니다. 값 1은 대상 바운딩 박스의 각 축 길이 절반만큼을 의미합니다. 이동 방향은 카메라의 현재 방향을 기준으로 계산됩니다. #### Code Samples ```lua local BillboardGui = script.Parent BillboardGui.ExtentsOffset = Vector3.new(0, 1, 0) ``` ### ExtentsOffsetWorldSpace `Vector3` BillboardGui가 렌더링되는 오브젝트로부터 얼마나 떨어져 표시될지를 지정하는 속성입니다. 대상의 크기(Extents)를 기준으로 BillboardGui의 위치를 보정합니다. 캐릭터와 같은 모델 크기에 따라 체력바 UI를 자연스럽게 머리 위에 배치할 때 유용합니다. 대상(부모 Part 또는 Adornee)의 축을 기준으로, 바운드 박스의 각 축 길이의 절반(Extents)에 입력 값(Vector3)을 곱한 만큼 오프셋이 적용됩니다. #### Code Samples ```lua local BillboardGui = script.Parent BillboardGui.ExtentsOffsetWorldSpace = Vector3.new(0, 5, 0) ``` ### Offset `Vector3` BillboardGui가 렌더링되는 오브젝트로부터 얼마나 떨어져 표시될지를 cm 단위로 지정합니다. 이동 방향은 카메라의 현재 방향을 기준으로 계산됩니다. PositionOffset과 같은 기준을 사용하며, 두 속성을 함께 지정하면 값이 합산됩니다. #### Code Samples ```lua local BillboardGui = script.Parent BillboardGui.Offset = Vector3.new(0, 100, 0) ``` ### OffsetWorldSpace `Vector3` BillboardGui가 렌더링되는 오브젝트로부터 얼마나 떨어져 표시될지를 cm 단위로 지정합니다. 이동 방향은 월드 좌표축을 기준으로 계산되므로, 대상 오브젝트가 회전해도 방향이 바뀌지 않습니다. 대상 오브젝트의 축을 기준으로 이동하려면 PositionOffsetWorldSpace를 사용합니다. #### Code Samples ```lua local BillboardGui = script.Parent BillboardGui.OffsetWorldSpace = Vector3.new(0, 100, 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 ### GetScreenSpaceBounds BillboardGui가 현재 화면에서 차지하는 영역을 픽셀 단위 사각형으로 반환하는 메서드입니다. BillboardGui가 카메라 뒤에 있는 등 화면에 투영할 수 없으면 크기가 0인 사각형을 반환합니다. #### Parameters #### Return | `Rect` | 화면에서 차지하는 영역입니다. | | ------ | ---------------- | #### Code Samples ```lua local BillboardGui = script.Parent local Bounds = BillboardGui:GetScreenSpaceBounds() print("Min : ", Bounds.Min, "Max : ", Bounds.Max) ``` ## Events ## See also {% content-ref url="/pages/K1g0tEWDJhh6a6E4UURk" %} [GUI](/korean/manual/studio-manual/gui.md) {% endcontent-ref %}