> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/scene-editor/build/ui-editor.md).

# UI 편집기

코드 대신 캔버스에서 Creator Hub 안의 시각적 도구로 씬의 화면 UI를 디자인하세요.

UI 편집기를 사용하면 레이아웃 코드를 직접 작성하지 않고도 위젯을 캔버스로 끌어다 놓아 장면의 화면 UI를 만들 수 있습니다. 실제 파일을 장면에 기록하므로 여기서 만드는 것은 모두 나중에 코드에서 계속 편집할 수 있는 일반 SDK7 UI입니다.

UI 편집기는 실험적인 기능이며 기본적으로 꺼져 있습니다.

## 켜기

1. 설정(오른쪽 상단의 톱니바퀴 아이콘)을 엽니다.
2. 다음으로 이동: **실험적** 탭.
3. 켜기 **UI 편집기 활성화**.

하나의 **2D** / **3D** 그러면 편집기에 탭 전환이 나타납니다. **3D** 는 이미 알고 있는 장면 캔버스입니다. **2D** 는 UI 편집기입니다.

{% hint style="warning" %}
**📔 참고**: UI 편집기에는 `@dcl/sdk` 장면에 7.26.0 버전 이상이 필요합니다. 더 오래된 장면에서는 **UI 편집기를 사용할 수 없음** 알림과 **SDK 업데이트** 버튼이 있어 장면을 대신 업그레이드합니다.
{% endhint %}

크리에이터 허브는 장면을 2D로 열었는지 3D로 열었는지 기억하고 같은 방식으로 다시 엽니다. 이는 프로젝트별로 저장되며 장면과 함께 게시되지 않습니다.

Bevy 장면 렌더러를 사용하는 경우, **2D** 실행 중인 장면이 일시 중지되고, 다시 **3D** 로 돌아가면 이전에도 실행 중이었다면 다시 이어서 실행됩니다.

## 첫 UI 만들기

1. 다음으로 전환하세요 **2D** 탭.
2. 왼쪽 패널에서 **새 GUI**. GUI는 하나의 UI 구성 요소이며, 자체 파일에 저장됩니다.
3. 하단 팔레트에서 위젯을 캔버스로 끌어다 놓습니다.
4. 선택한 다음 오른쪽 패널에서 속성을 설정합니다.

저장 버튼은 없습니다. 편집기는 작업하면서 변경 사항을 디스크에 기록하고, 도구 모음에는 **모든 변경 사항 저장됨**.

## 패널

* **왼쪽**: **GUI**, UI 구성 요소 목록, 그리고 **노드**, 선택한 항목의 트리입니다. 검색 상자가 둘 다 필터링합니다.
* **오른쪽**:  **속성** 선택한 노드의 탭, 그리고 **로직** 탭.
* **아래쪽**: 위젯 팔레트입니다. 카드를 캔버스로 끌어다 놓아 추가하세요.
* **가운데**: 캔버스입니다. 노드를 끌어 이동하고, 핸들을 사용해 크기를 조절하며, 마우스 휠이나 드래그로 자유롭게 이동할 수 있습니다. **보기 초기화** 중앙으로 다시 맞춥니다.

## 위젯

팔레트는 위젯을 세 가지 범주로 나눕니다:

* **컨테이너**: **전체 화면**, **컨테이너**, **이미지**
* **텍스트**: **Label**, **버튼**
* **Input**: **Input**, **드롭다운**

**전체 화면** 자신이 들어간 공간을 가득 채우는 컨테이너로, 화면을 덮어야 하는 UI의 좋은 시작점입니다.

## 이동 및 크기 조절

도구 모음에는 세 가지 도구 모드가 있습니다:

* **자유**: 이동 및 크기 조절, 범용 모드입니다.
* **이동**: 드래그만 가능합니다.
* **크기 조절**: 핸들만 사용합니다.

위치는 10픽셀 격자에 맞춰 붙습니다. Hold **Shift** 드래그하는 동안 격자를 무시하고 자유롭게 이동하려면. 그 **스냅** 드롭다운은 도구 모음에서 스냅을 완전히 끕니다.

## 레이아웃: 흐름 및 자유 배치

두 개의 별도 속성이 노드가 어디에 놓일지를 결정합니다. 이것들을 명확히 이해하면 혼란을 크게 줄일 수 있습니다.

**흐름** 는 **컨테이너** 에 설정되며 자식들을 어떻게 배치할지 결정합니다:

* **자유**: 자식들은 당신이 놓은 곳에 그대로 남습니다.
* **행** / **행 역순**: 자식들은 왼쪽에서 오른쪽으로, 또는 오른쪽에서 왼쪽으로 배치됩니다.
* **열** / **열 역순**: 자식들은 위에서 아래로, 또는 아래에서 위로 쌓입니다.
* **자식 줄바꿈**: 자식이 맞지 않을 때 여러 줄로 넘어가게 합니다.

**레이아웃 흐름 무시** 는 **자식** 그리고 해당 노드가 부모의 배치에서 제외될지 결정합니다. 끄면 부모가 배치합니다. 켜면 Anchor와 Position 값으로 직접 고정합니다.

이로 인해 두 가지 결과가 생깁니다:

* 위젯을 **자유** 컨테이너에 놓으면 그대로 놓은 위치에 머뭅니다.
* 방향이 있는 컨테이너에 놓으면 흐름에 합류해 줄에서 제자리를 차지합니다.

컨테이너를 **자유** 로 바꾸면 기존 자식들을 현재 있는 위치에 고정하므로 아무것도 튀지 않습니다.

GUI의 루트는 항상 자유 배치됩니다.

## 알아둘 만한 다른 속성들

* **투명도**: 100%는 완전히 불투명하고 0%는 완전히 투명합니다. 기본값은 100%입니다.
* **씬 인셋**: GUI가 화면의 어느 부분에 놓일지입니다.
  * **전체 화면** 렌더링 가능한 전체 화면을 사용합니다.
  * **게임플레이 안전 영역** 채팅, 미니맵, HUD 표시 등 클라이언트 자체 인터페이스를 피합니다.
  * **기기 안전 영역** 노치나 시스템 바와 같은 물리적 가림도 피합니다. 이 옵션은 캔버스가 모바일 미리보기일 때 제공됩니다.

GUI의 루트에 고정 픽셀 단위의 너비와 높이를 주면, 캔버스는 이를 화면이 아니라 정확히 그 크기의 아트보드로 표시합니다.

## 파일이 저장되는 위치

UI 편집기는 장면의 실제 소스 파일을 편집합니다. 별도의 저장 형식은 없습니다.

* 각 GUI는 하나의 `.tsx` 아래의 파일입니다 `src/ui/`.
* `src/ui/index.tsx` 는 편집기가 이들을 모으기 위해 생성합니다. 직접 수정하지 마세요.

장면에 이전 단일 `src/ui.tsx` 파일이 있으면 편집기는 이를 백업하여 `src/ui.tsx.bak` 로 UI 편집기를 처음 열 때

이것들은 일반 파일이므로, 언제든지 [코드 편집기](/creator/content-creator-ko/scene-editor/extend-with-code/overview.md) 에서 열 수 있습니다. 다음을 참조하세요 [UI](https://github.com/decentraland/docs/tree/main/creator/sdk7/2d-ui/README.md) 기반 코드가 하는 일을 보려면.

## 편집기가 편집할 수 없는 코드

편집기는 특정 형태의 UI 코드를 이해합니다. 예를 들어 루프나 조건문 안에서 만들어지거나 사용자 지정 컴포넌트나 spread props를 사용해 다른 방식으로 작성된 노드는, 캔버스에 회색 블록으로 표시되며 **비표준, 코드에서 편집** 배지가 붙습니다. 그 자식들은 표시되지 않으며, 대신 코드에서 편집합니다.

그 주변의 나머지 GUI는 계속 정상적으로 작동합니다.

## 관련 페이지

* [UI](https://github.com/decentraland/docs/tree/main/creator/sdk7/2d-ui/README.md): 코드로 장면 UI를 작성합니다.
* [코드와 결합](/creator/content-creator-ko/scene-editor/extend-with-code/overview.md): 코드 편집기에서 씬을 엽니다.
* [엔터티 및 컴포넌트](/creator/content-creator-ko/scene-editor/build/components.md): 편집기의 3D 측면입니다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-ko/scene-editor/build/ui-editor.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.