# 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) ``` ### DistanceUpperLimit `number` 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="/pages/K1g0tEWDJhh6a6E4UURk" %} [GUI](/korean/manual/studio-manual/gui.md) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.overdare.com/korean/development/api-reference/classes/billboardgui.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.