> 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/screengui.md).

# ScreenGui

ScreenGui : `LayerCollector`

## Overview

ScreenGui는 사용자의 화면에 표시되는 2D UI 요소(GuiObject)를 담는 컨테이너입니다. 실제로 화면에 나타나기 위해서는 해당 ScreenGui가 플레이어의 PlayerGui에 배치되어 있어야 하며, StarterGui에 넣어두면 플레이어가 게임에 입장하고 캐릭터가 처음 생성될 때 자동으로 각 플레이어의 PlayerGui로 복제됩니다.

ScreenGui에는 Frame, TextLabel, ImageButton 등 다양한 UI 구성 요소들을 자식으로 포함할 수 있습니다.

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

ScreenGui는 **클라이언트 환경에서만 제어**할 수 있습니다.

## Properties

### ClipToDeviceSafeArea

`boolean`

ScreenInsets로 정한 안전 영역 밖으로 벗어난 하위 UI 요소를 잘라서 표시할지 지정합니다.

#### Code Samples

```lua
local ScreenGui = script.Parent

ScreenGui.ClipToDeviceSafeArea = true
```

### DisplayOrder

`number`

여러 ScreenGui가 동시에 표시될 때 어떤 순서로 화면에 겹쳐 보일지를 정의합니다. DisplayOrder 값이 더 큰 ScreenGui는 값이 작은 ScreenGui보다 앞쪽에 배치되어, 시각적으로 위에 나타나게 됩니다.

0\~999,999,999 범위의 정수를 입력할 수 있습니다. 기본값은 0이며, 값이 클수록 다른 ScreenGui보다 우선적으로 표시됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent

ScreenGui.DisplayOrder = 2
```

### IgnoreGuiInset

`boolean`

시스템 UI 영역을 무시하고 화면 전체를 기준으로 하위 UI 요소를 배치할지 지정합니다.

ScreenInsets와 서로 연동됩니다. false로 설정하면 ScreenInsets가 CoreUISafeInsets로 바뀌고, ScreenInsets를 CoreUISafeInsets 외의 값으로 설정하면 이 속성은 true가 됩니다.

새로 작성하는 스크립트에서는 ScreenInsets를 사용하는 것을 권장합니다.

#### Code Samples

```lua
local ScreenGui = script.Parent

ScreenGui.IgnoreGuiInset = false
```

### ResetOnSpawn

`boolean`

플레이어의 캐릭터가 다시 생성될 때 이 ScreenGui를 초기 상태로 다시 만들지 지정합니다.

#### Code Samples

```lua
local ScreenGui = script.Parent

ScreenGui.ResetOnSpawn = false
```

### SafeAreaCompatibility

`Enum.SafeAreaCompatibility`

화면 전체를 채우도록 만든 UI가 안전 영역 안에 배치될 때 배경을 화면 끝까지 확장할지 지정합니다.

* `None`: 확장하지 않습니다.
* `FullscreenExtension`: ScreenInsets가 None이 아닐 때, 화면 전체 크기의 배경을 화면 끝까지 확장합니다.

#### Code Samples

```lua
local ScreenGui = script.Parent

ScreenGui.ScreenInsets = Enum.ScreenInsets.DeviceSafeInsets
ScreenGui.SafeAreaCompatibility = Enum.SafeAreaCompatibility.FullscreenExtension
```

### ScreenInsets

`Enum.ScreenInsets`

하위 UI 요소를 배치할 때 기준으로 삼을 화면 안전 영역을 지정합니다.

* `None`: 안전 영역을 적용하지 않고 화면 전체를 사용합니다.
* `DeviceSafeInsets`: 노치 등 기기의 표시 제한 영역을 제외한 영역을 사용합니다.
* `CoreUISafeInsets`: 기기의 표시 제한 영역과 시스템 UI 영역을 제외한 영역을 사용합니다.
* `TopbarSafeInsets`: 상단 바 영역을 고려한 안전 영역을 사용합니다.

버튼이나 텍스트처럼 반드시 보여야 하는 요소는 안전 영역 안에 배치하는 것을 권장합니다.

#### Code Samples

```lua
local ScreenGui = script.Parent

ScreenGui.ScreenInsets = Enum.ScreenInsets.DeviceSafeInsets
```

### TabKeyboardNavigation

`boolean`

이 ScreenGui 안의 버튼이 키보드 포커스를 받을 수 있게 할지 지정합니다.

#### Code Samples

```lua
local ScreenGui = script.Parent

ScreenGui.TabKeyboardNavigation = true
```

## Methods

### GetGuiObjectsAtPosition

지정한 화면 좌표에 있는 이 ScreenGui의 하위 UI 요소를 모두 찾아 배열로 반환하는 메서드입니다.

화면 앞쪽에 표시되는 요소부터 순서대로 반환하며, 다른 요소에 가려진 요소도 포함합니다. IsNotOccluded가 false인 요소와 클리핑으로 잘려 보이지 않는 위치의 요소는 제외됩니다.

#### Parameters

| `number` x | 화면상의 X 좌표(픽셀)입니다. |
| ---------- | ----------------- |
| `number` y | 화면상의 Y 좌표(픽셀)입니다. |

#### Return

| `Array` | 해당 좌표에 있는 GuiObject 배열입니다. |
| ------- | -------------------------- |

#### Code Samples

```lua
local ScreenGui = script.Parent

local PositionX = 150
local PositionY = 200
local GuiObjects = ScreenGui:GetGuiObjectsAtPosition(PositionX, PositionY)
for _, guiObject in ipairs(GuiObjects) do
    print(guiObject.Name)
end
```

## Events

## See also

{% content-ref url="/pages/K1g0tEWDJhh6a6E4UURk" %}
[GUI](/korean/manual/studio-manual/gui.md)
{% endcontent-ref %}