# GUI

## 개요

GUI는 게임 내에서 플레이어와 상호작용할 수 있는 그래픽 요소를 의미합니다. GUI를 활용하면 버튼, 텍스트, 이미지, 진행 바 등 다양한 요소를 게임 화면에 추가할 수 있습니다.

## 종류

<table><thead><tr><th width="234">오브젝트</th><th>설명</th></tr></thead><tbody><tr><td>ScreenGui</td><td>2D 기반 오브젝트들을 화면에 보여주기 위한 오브젝트입니다. 2D 기반 오브젝트인 Frame, TextButton, ImageButton 등은 ScreenGui/SurfaceGui 등 Gui 오브젝트의 자식으로 존재해야만 화면에 표시됩니다. ScreenGui 자체는 화면에 어떠한 정보도 표시하지 않습니다.</td></tr><tr><td>SurfaceGui</td><td>Surface GUI는 3D 공간에서 2D UI를 보여주기 위한 오브젝트입니다. 게임 내의 표면이나 오브젝트에 GUI를 붙여서 상호작용을 가능하게 합니다.</td></tr><tr><td>BillboardGui</td><td>Billboard Gui는 2D UI를 3D 공간에서 항상 카메라를 향하도록 표시해주는 오브젝트입니다.<br>이 GUI는 항상 플레이어의 시선 방향을 향해 회전하므로 주로 이름표, 체력바, 대화창 등에 활용됩니다.</td></tr><tr><td>Frame</td><td>레이아웃을 디자인 하거나 TextLabel, TextButton, ImageLabel, ImageButton 등의 오브젝트를 그룹화할 수 있는 기능을 제공하는 2D 기반 오브젝트입니다.</td></tr><tr><td>ScrollingFrame</td><td>스크롤 가능한 레이아웃을 구성하는 2D 기반의 오브젝트입니다. 스크롤 기능을 통해 모든 오브젝트를 화면에 표시할 수 있도록 지원합니다.</td></tr><tr><td>TextLabel</td><td>텍스트를 표시할 수 있는 오브젝트입니다.</td></tr><tr><td>ImageLabel</td><td>이미지를 표시할 수 있는 오브젝트입니다.</td></tr><tr><td>TextButton</td><td>텍스트를 표시할 수 있는 버튼입니다.</td></tr><tr><td>ImageButton</td><td>이미지를 표시할 수 있는 버튼입니다.</td></tr><tr><td>UIAspectRatioConstraint</td><td>2D 기반 오브젝트들의 가로 세로 비율을 설정할 수 있는 기능을 제공하는 오브젝트입니다. Frame/ImageLabel/ImageButton/TextButton 등의 비율 설정을 원할 경우, 자식으로 UIAspectRatioConstraint를 두고 비율을 수정할 수 있습니다. 부모 오브젝트의 현재 Size를 기준으로 비율을 유지하게 됩니다.</td></tr><tr><td>UIListLayout</td><td>부모 오브젝트 내의 자식 오브젝트들을 일정한 간격으로 나열하여 리스트 형태로 정렬해주는 기능을 제공하는 오브젝트입니다.</td></tr><tr><td>UIGridLayout</td><td>부모 오브젝트 내의 자식 오브젝트들을 일정한 크기와 간격으로 행렬(Grid) 형태로 정렬해주는 기능을 제공하는 오브젝트입니다.</td></tr></tbody></table>

## ScreenGui의 프로퍼티

<table><thead><tr><th width="234">프로퍼티</th><th>설명</th></tr></thead><tbody><tr><td>Enabled</td><td>ScreenGui가 자식으로 하는 모든 오브젝트를 화면에서 보여줄 지 여부를 변경할 수 있습니다.</td></tr><tr><td>DisplayOrder</td><td>어떤 ScreenGui가 화면의 위쪽에 표시될지 결정합니다. 값이 클수록 우선순위가 높아지며, 위쪽에 표시됩니다.</td></tr></tbody></table>

## SurfaceGui의 프로퍼티

<table><thead><tr><th width="234">프로퍼티</th><th>설명</th></tr></thead><tbody><tr><td>Enabled</td><td>SurfaceGui가 자식으로 하는 모든 오브젝트를 화면에서 보여줄 지 여부를 변경할 수 있습니다.</td></tr><tr><td>Always on Top</td><td>다른 3D 오브젝트 위에 항상 SurfaceGui가 렌더링되도록 설정합니다.</td></tr><tr><td>Light Influence</td><td>SurfaceGUI가 조명에 영향을 받는 정도를 설정합니다.</td></tr><tr><td>Max Distance</td><td>SurfaceGUI가 플레이어로부터 멀리 떨어져 있어도 보일 수 있는 최대 거리를 설정하는 데 사용됩니다.</td></tr><tr><td>Active</td><td>SurfaceGUI에 포함된 버튼, 텍스트 박스 등과 같은 UI 요소들이 클릭, 터치 또는 키보드 입력을 처리할 수 있는지 여부를 결정합니다.</td></tr><tr><td>Adornee</td><td>SurfaceGUI가 렌더링되는 오브젝트를 설정합니다.</td></tr><tr><td>Face</td><td>Part의 어느 면에 GUI가 표시될지를 설정합니다.</td></tr></tbody></table>

## BillboardGui의 프로퍼티

<table><thead><tr><th width="234">프로퍼티</th><th>설명</th></tr></thead><tbody><tr><td>Enabled</td><td>BillboardGui가 자식으로 하는 모든 오브젝트를 화면에서 보여줄 지 여부를 변경할 수 있습니다.</td></tr><tr><td>Always on Top</td><td>다른 3D 오브젝트 위에 항상 BillboardGui가 렌더링되도록 설정합니다.</td></tr><tr><td>Light Influence</td><td>BillboardGui가 조명에 영향을 받는 정도를 설정합니다.</td></tr><tr><td>Brightness</td><td>BillboardGui에 적용되는 밝기입니다. 숫자가 클수록 더 밝게 표시되며, 3D 조명과의 상호작용 없이 시각적으로 강조할 때 유용합니다.<br>(Light Influence가 1 미만이면 설정할 수 있습니다.)</td></tr><tr><td>Max Distance</td><td>BillboardGui가 플레이어로부터 멀리 떨어져 있어도 보일 수 있는 최대 거리를 설정하는 데 사용됩니다.</td></tr><tr><td>Distance Lower Limit</td><td>BillboardGui가 플레이어의 카메라에 너무 가까워졌을 때, 더 이상 확대되지 않도록 제한하는 거리입니다.</td></tr><tr><td>Distance Upper Limit</td><td>BillboardGui가 플레이어의 카메라로부터 멀어질 때, 더 이상 작아지지 않도록 제한하는 거리입니다.</td></tr><tr><td>Active</td><td>BillboardGui에 포함된 버튼, 텍스트 박스 등과 같은 UI 요소들이 클릭, 터치 또는 키보드 입력을 처리할 수 있는지 여부를 결정합니다.</td></tr><tr><td>Adornee</td><td>BillboardGui가 렌더링되는 오브젝트를 설정합니다.</td></tr><tr><td>Clips Descendants</td><td>하위 UI 요소들이 부모 GUI의 경계를 벗어났을 때 잘릴지 여부를 설정합니다. true일 경우 경계를 벗어난 요소는 보이지 않습니다.</td></tr><tr><td>Size</td><td>BillboardGui의 크기를 설정합니다.</td></tr><tr><td>Position Offset</td><td>렌더링되는 오브젝트로부터의 오프셋을 카메라 기준으로 설정합니다.</td></tr><tr><td>Position Offset World Space</td><td>렌더링되는 오브젝트로부터의 오프셋을 대상 오브젝트 기준으로 설정합니다.</td></tr><tr><td>Extents Offset World Space</td><td><p>렌더링되는 오브젝트로부터의 오프셋을 월드 좌표 기준으로 설정합니다. (값 단위는 모델 크기의 절반 기준)<br>대상의 크기(Extents)를 기준으로 BillboardGui의 위치를 보정합니다. 캐릭터와 같은 모델 크기에 따라 체력바 UI를 자연스럽게 머리 위에 배치할 때 유용합니다.</p><p>대상(부모 Part 또는 Adornee)의 축을 기준으로, 바운드 박스의 각 축 길이의 절반(Extents)에 입력 값(Vector3)을 곱한 만큼 오프셋이 적용됩니다.</p></td></tr><tr><td>Size Offset</td><td>렌더링되는 오브젝트로부터의 오프셋을 스크린 평면 기준으로 설정합니다.</td></tr></tbody></table>

## Gui 요소의 프로퍼티

### 공통 프로퍼티

<table><thead><tr><th width="234">프로퍼티</th><th>설명</th></tr></thead><tbody><tr><td>Position</td><td><p>화면 상 위치를 변경할 수 있는 속성 입니다.</p><p>UDim2 형식을 사용하며, ScaleX, OffsetX, ScaleY, OffsetY 값을 순서대로 입력할 수 있습니다.</p><ul><li>Scale: 0.0 ~ 1.0 사이의 비율 단위이며, 0.1은 10%를 의미합니다.</li><li>Offset: Pixel 단위이며, 10은 10Pixel을 의미합니다.</li></ul><p>Scale과 Offset 값은 합산하여 화면에 표현 됩니다. 예를 들어 ScaleX 값이 0.25이고 OffsetX 값이 10이면, 설정된 Anchor Point(Frame의 중심점)을 기준으로 좌측으로부터 25% 만큼 우측으로 이동하고 OffsetX인 10Pixel 만큼 추가로 우측으로 이동 됩니다.</p></td></tr><tr><td>Rotation</td><td>회전 각도를 변경할 수 있는 속성 입니다. 360.0은 360도를 의미합니다.</td></tr><tr><td>Size</td><td>크기를 변경할 수 있는 속성 입니다. Position과 마찬가지로 UDim2 형식을 사용합니다.</td></tr><tr><td>Visible</td><td>보이거나 보이지 않게 설정하는 속성 입니다.</td></tr><tr><td>Anchor Point</td><td>중심점을 의미합니다. Vector2 형식을 사용하며 기본값 0.0, 0.0이면 Frame의 좌측 상단이 중심점 입니다.</td></tr><tr><td>ZIndex</td><td>UI 요소의 스택 순서를 정의하는 속성 입니다. FrameA가 FrameB와 위치 상 FrameB에 가려지는 경우 ZIndex 값에 따라 FrameB 보다 위에 FrameA가 보이도록 할 수 있습니다.</td></tr><tr><td>Clips Descendants</td><td>자식 UI 요소가 부모 UI의 영역을 초과할 경우, 초과한 영역소를 화면에 표시할지 설정하는 속성입니다.</td></tr></tbody></table>

### Frame

<table><thead><tr><th width="234">프로퍼티</th><th>설명</th></tr></thead><tbody><tr><td>Border Pixel Size</td><td>Frame의 테두리 두께를 설정할 수 있는 속성 입니다.</td></tr><tr><td>Border Mode</td><td>테두리를 Frame의 가장자리 기준으로 insert(안쪽)/middle(중앙)/Outline(바깥쪽) 중 어느 기준으로 보여줄 지 설정할 수 있는 속성 입니다.</td></tr><tr><td>Border Color 3</td><td>테두리 색을 변경할 수 있는 속성 입니다.</td></tr><tr><td>Background Color 3</td><td>Frame의 배경 색을 변경할 수 있는 속성 입니다.</td></tr><tr><td>Background Trnasparency</td><td>Frame의 배경 투명도를 변경할 수 있는 속성 입니다.</td></tr></tbody></table>

### TextLabel

<table><thead><tr><th width="234">프로퍼티</th><th>설명</th></tr></thead><tbody><tr><td>Text</td><td>보여줄 텍스트를 입력할 수 있는 속성 입니다.</td></tr><tr><td>TextScaled</td><td>보여줄 텍스트의 크기를 Text Size 값을 무시하고 오브젝트의 Size 값에 맞게 자동으로 변화할 수 있도록 기능을 제공하는 속성 입니다.</td></tr><tr><td>Bold</td><td>보여줄 텍스트의 두께를 변경할 수 있는 속성 입니다.</td></tr><tr><td>Text Size</td><td>보여줄 텍스트의 크기를 Pixel 단위로 변경할 수 있는 속성 입니다.</td></tr><tr><td>Text Color 3</td><td>보여줄 텍스트의 색상을 변경할 수 있습니다.</td></tr><tr><td>Text Transparency</td><td>보여줄 텍스트의 투명도를 변경할 수 있습니다.</td></tr><tr><td>Background Color 3</td><td>배경 색을 변경할 수 있는 속성 입니다.</td></tr><tr><td>Background Transparency</td><td>배경 투명도를 변경할 수 있는 속성 입니다.</td></tr></tbody></table>

### ImageLabel

<table><thead><tr><th width="234">프로퍼티</th><th>설명</th></tr></thead><tbody><tr><td>Image</td><td>이미지를 보여주기 위한 AssetId를 입력하는 속성 입니다. Asset Manager 또는 Asset Drawer에 등록된 이미지의 AssetId 값을 사용할 수 있습니다.</td></tr><tr><td>Image Transparency</td><td>이미지의 투명도를 변경할 수 있는 속성 입니다.</td></tr><tr><td>Background Color 3</td><td>배경 색을 변경할 수 있는 속성 입니다.</td></tr><tr><td>Background Transparency</td><td>배경 투명도를 변경할 수 있는 속성 입니다.</td></tr></tbody></table>

### TextButton

<table><thead><tr><th width="234">프로퍼티</th><th>설명</th></tr></thead><tbody><tr><td>Text</td><td>보여줄 텍스트를 입력할 수 있는 속성 입니다.</td></tr><tr><td>TextScaled</td><td>보여줄 텍스트의 크기를 Text Size 값을 무시하고 오브젝트의 Size 값에 맞게 자동으로 변화할 수 있도록 기능을 제공하는 속성 입니다.</td></tr><tr><td>Bold</td><td>보여줄 텍스트의 두께를 변경할 수 있는 속성 입니다.</td></tr><tr><td>Text Size</td><td>보여줄 텍스트의 크기를 Pixel 단위로 변경할 수 있는 속성 입니다.</td></tr><tr><td>Text Color 3</td><td>보여줄 텍스트의 색상을 변경할 수 있습니다.</td></tr><tr><td>Text Transparency</td><td>보여줄 텍스트의 투명도를 변경할 수 있습니다.</td></tr><tr><td>Background Color 3</td><td>배경 색을 변경할 수 있는 속성 입니다.</td></tr><tr><td>Background Transparency</td><td>배경 투명도를 변경할 수 있는 속성 입니다.</td></tr></tbody></table>

### ImageButton

<table><thead><tr><th width="234">프로퍼티</th><th>설명</th></tr></thead><tbody><tr><td>Image</td><td>이미지를 보여주기 위한 AssetId를 입력하는 속성 입니다. Asset Manager 또는 Asset Drawer에 등록된 이미지의 AssetId 값을 사용할 수 있습니다.</td></tr><tr><td>Image Transparency</td><td>이미지의 투명도를 변경할 수 있는 속성 입니다.</td></tr><tr><td>Background Color 3</td><td>배경 색을 변경할 수 있는 속성 입니다.</td></tr><tr><td>Background Transparency</td><td>배경 투명도를 변경할 수 있는 속성 입니다.</td></tr></tbody></table>

### UIAspectRatioConstraint

ImageLabel의 Size가 { 0.5, 0, 0.5, 0 }으로 X축과 Y축 모두 클라이언트 기기의 50% 크기로 설정되어 있을 때, UIAspetRatioConstraint를 자식으로 두고 Aspect Ratio 속성을 1.0으로 설정하면 ImageLabel의 Size에 1:1 비율이 적용되어 좌우 또는 상하로 이미지가 늘어나지 않도록 할 수 있습니다.

<table><thead><tr><th width="234">프로퍼티</th><th>설명</th></tr></thead><tbody><tr><td>Aspect Ratio</td><td>부모 오브젝트에 대해 보여주고 싶은 비율을 설정할 수 있습니다. 기본값은 1.0이며, x, y가 각각 1:1 비율을 갖습니다.</td></tr><tr><td>Aspect Type</td><td><p>UI 요소의 비율을 어떻게 유지할지를 결정하는 속성입니다.</p><ul><li>FitWithinMaxSize : UI 요소가 최대 크기 내에서 비율을 유지하며 축소됨</li><li>ScaleWithParentSize : 부모 UI 요소의 크기에 맞춰 비율을 유지하며 조정됨</li><li>SizeRelativeXY : X, Y 방향 모두 상대적인 크기를 유지함</li></ul></td></tr><tr><td>Dominant Axis</td><td><p>UI의 크기가 변경될 때 어느 축을 기준으로 비율을 유지할지를 결정합니다.</p><ul><li>Width : 가로 기준으로 높이 조정</li><li>Height : 세로 기준으로 너비 조정</li></ul></td></tr></tbody></table>

### ScrollingFrame

<table><thead><tr><th width="234">프로퍼티</th><th>설명</th></tr></thead><tbody><tr><td>AutomaticCanvasSize</td><td><p>자식 객체의 크기에 따라 CanvasSize를 자동 조절할지 여부를 설정합니다.</p><ul><li>None : 자동 조절 없음</li><li>X : 가로 방향 자동 조절</li><li>Y : 세로 방향 자동 조절</li><li>XY : 가로와 세로 모두 자동 조절</li></ul></td></tr><tr><td>CanvasSize</td><td>스크롤 가능한 내부 영역의 크기를 설정하는 속성입니다.</td></tr><tr><td>CanvasPosition</td><td>스크롤 위치를 직접 설정하거나 확인할 수 있는 속성입니다.</td></tr><tr><td>ScrollBarImageColor3</td><td>스크롤 바의 이미지 색상을 설정할 수 있습니다.</td></tr><tr><td>ScrollBarImageTransparency</td><td>스크롤 바의 이미지의 투명도를 설정할 수 있습니다.</td></tr><tr><td>ScrollBarThickness</td><td>스크롤 바의 두께를 Pixel 단위로 설정할 수 있는 속성입니다.</td></tr><tr><td>ScrollingDirection</td><td><p>스크롤 방향을 설정하는 속성입니다.</p><ul><li>X : 가로 방향 스크롤</li><li>Y : 세로 방향 스크롤</li><li>XY : 가로와 세로 모두 스크롤 가능</li></ul></td></tr><tr><td>ScrollingEnabled</td><td>스크롤 기능의 사용 여부를 설정할 수 있는 속성입니다.</td></tr></tbody></table>

### UIListLayout

<table><thead><tr><th width="234">프로퍼티</th><th>설명</th></tr></thead><tbody><tr><td>Padding</td><td>UI 요소 사이에 들어갈 간격입니다.</td></tr><tr><td>Wraps</td><td>자동으로 줄바꿈할지 여부를 설정하는 속성입니다.</td></tr><tr><td>FillDirection</td><td><p>UI 요소들을 나열하는 방향입니다.</p><ul><li>Horizontal : 수평으로 나열</li><li>Vertical : 수직으로 나열</li></ul></td></tr><tr><td>SortOrder</td><td><p>UI 요소의 정렬 기준입니다.</p><ul><li>LayoutOrder : 각 인스턴스의 LayoutOrder 값을 기준으로 정렬</li><li>Name : 이름을 기준으로 정렬</li></ul></td></tr><tr><td>HorizontalAlignment</td><td><p>수평 정렬 방식입니다.</p><ul><li>Left : 왼쪽 정렬</li><li>Center : 가운데 정렬</li><li>Right : 오른쪽 정렬</li></ul></td></tr><tr><td>VerticalAlignment</td><td><p>수직 정렬 방식입니다.</p><ul><li>Top : 위쪽 정렬</li><li>Center : 가운데 정렬</li><li>Bottom : 아래쪽 정렬</li></ul></td></tr></tbody></table>

### UIGridLayout

<table><thead><tr><th width="234">프로퍼티</th><th>설명</th></tr></thead><tbody><tr><td>CellPadding</td><td>셀 간의 간격을 의미합니다.</td></tr><tr><td>CellSize</td><td>셀 하나의 크기를 의미합니다.</td></tr><tr><td>FillDirectionMaxCells</td><td>지정된 방향으로 채워질 셀의 최대 개수를 의미합니다.</td></tr><tr><td>FillDirection</td><td><p>UI 요소들을 나열하는 방향입니다.</p><ul><li>Horizontal : 수평으로 나열</li><li>Vertical : 수직으로 나열</li></ul></td></tr><tr><td>SortOrder</td><td><p>UI 요소의 정렬 기준입니다.</p><ul><li>LayoutOrder : 각 인스턴스의 LayoutOrder 값을 기준으로 정렬</li><li>Name : 이름을 기준으로 정렬</li></ul></td></tr><tr><td>HorizontalAlignment</td><td><p>셀의 수평 정렬입니다.</p><ul><li>Left : 왼쪽 정렬</li><li>Center : 가운데 정렬</li><li>Right : 오른쪽 정렬</li></ul></td></tr><tr><td>VerticalAlignment</td><td><p>셀의 수직 정렬입니다.</p><ul><li>Top : 위쪽 정렬</li><li>Center : 가운데 정렬</li><li>Bottom : 아래쪽 정렬</li></ul></td></tr></tbody></table>