# 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 Store에 등록된 이미지의 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 Store에 등록된 이미지의 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>


---

# 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/manual/studio-manual/gui.md?ask=<question>
```

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.