> 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 Editor를 사용하면 레이아웃 코드를 손으로 작성하는 대신 위젯을 캔버스로 끌어다 놓아 장면의 화면 인터페이스를 만들 수 있습니다. 이 도구는 실제 파일을 장면 안에 기록하므로, 여기서 만든 모든 것은 코드로 계속 편집할 수 있는 일반적인 SDK7 UI입니다.
## 열기
다음을 사용하세요. **2D** / **3D** 편집기 왼쪽 패널 상단의 전환기. **3D** 는 이미 알고 있는 장면 캔버스입니다. **2D** 는 UI Editor입니다.
{% hint style="warning" %}
**📔 참고**: UI Editor에는 `@dcl/sdk` 장면에 7.26.0 버전 이상이 필요합니다. 이전 장면에서는 **2D** 탭에 **UI Editor 사용할 수 없음** 알림이 캔버스 대신 표시되며, **SDK 업데이트** 버튼으로 장면을 업그레이드할 수 있고 **나중에** 버튼으로 닫을 수 있습니다.
{% endhint %}
Creator Hub는 장면을 2D 또는 3D 중 어느 모드로 두고 나갔는지 기억했다가 같은 방식으로 다시 엽니다. 이는 프로젝트별로 저장되며 장면과 함께 게시되지 않습니다.
Bevy 장면 렌더러를 사용하는 경우, **2D** 로 전환하면 **3D** 실행 중인 장면이 일시 중지되고, 이전에 실행 중이었다면
## 첫 UI 만들기
1. 다음으로 전환하세요. **2D** 탭.
2. 클릭 **새 GUI**, 비어 있는 캔버스 중앙의 버튼이나 **+** 옆의 **GUI** 왼쪽 패널에 있습니다. GUI는 하나의 UI 구성 요소로, 자체 파일에 저장됩니다.
3. 아래쪽 팔레트에서 위젯 하나를 캔버스로 끌어다 놓으세요. **전체 화면** 은 좋은 첫 위젯으로, 화면 전체를 덮는 루트를 제공합니다. 그런 다음 그 안에 다른 위젯을 놓으세요.
4. 위젯을 선택한 다음 오른쪽 패널에서 속성을 설정하세요.
저장 버튼은 없습니다. 편집기는 작업하는 대로 변경 내용을 디스크에 기록하며, 툴바 왼쪽의 배지는 **모든 변경 사항 저장됨**.
## 패널
* **왼쪽**: **GUI**, UI 구성 요소 목록이며, **노드**, 선택한 항목의 트리입니다. 검색 상자는 둘 다를 필터링합니다. 노드에 마우스를 올리면 잠금, 숨기기 또는 삭제할 수 있습니다.
* **오른쪽**: 하나의 **속성** 탭과 **로직** 탭.
* **아래쪽**: 위젯 팔레트입니다. 카드를 캔버스로 끌어다 놓아 추가하세요.
* **가운데**: 캔버스입니다. 노드를 끌어 이동하고, 핸들로 크기를 조정하며, 마우스 휠이나 드래그로 자유롭게 이동할 수 있습니다.
캔버스 오른쪽 아래 모서리에는 두 개의 떠 있는 컨트롤 그룹이 있습니다:
* 해당 **미리보기** 그룹은 모바일 HUD 가이드와 안전 영역 가이드를 토글하고, **데스크톱 미리보기** 와 **모바일 미리보기**.
* 해당 **확대/축소** 그룹에는 빼기 버튼과 더하기 버튼, 그리고 퍼센트 필드가 있습니다. 퍼센트를 클릭해 10에서 200 사이의 정확한 확대/축소 수준을 입력한 다음 Enter를 누르거나 다른 곳을 클릭해 적용하고, Escape를 누르면 취소됩니다. 더하기 버튼은 200%에 도달하면 꺼집니다.
## 위젯
팔레트는 위젯을 세 가지 범주로 나눕니다:
* **컨테이너**: **전체 화면**, **Container**, **Image**
* **텍스트**: **Label**, **Button**
* **Input**: **Input**, **Dropdown**
**전체 화면** 는 내부에 배치된 무엇이든 채우는 컨테이너이므로, 화면 전체를 덮어야 하는 UI의 시작점으로 좋습니다.
## 이동 및 크기 조정
툴바에는 세 가지 도구 모드가 있습니다:
* **자유**: 이동 및 크기 조정, 범용 모드입니다.
* **이동**: 드래그만.
* **크기 조정**: 핸들만.
위치는 10픽셀 그리드에 맞춰 스냅됩니다. **Shift** 를 누른 채로 드래그하면 그리드를 무시하고 자유롭게 이동할 수 있습니다. 도구 버튼 옆의 작은 화살표를 누르면 **스냅** 체크박스가 열리며, 스냅을 완전히 끌 수 있습니다.
## 레이아웃: 흐름 배치와 자유 배치
노드가 어디에 놓일지는 두 개의 별도 속성이 결정합니다. 이것들을 정확히 이해하면 혼란을 많이 줄일 수 있습니다.
**Flow** 는 **컨테이너** 에 설정되며 자식 요소를 어떻게 배치할지 결정합니다:
* **자유**: 자식은 배치한 곳에 그대로 남습니다.
* **행** / **행 반전**: 자식은 왼쪽에서 오른쪽으로, 또는 오른쪽에서 왼쪽으로 배치됩니다.
* **열** / **열 반전**: 자식은 위에서 아래로, 또는 아래에서 위로 쌓입니다.
* **자식 줄바꿈**: 자식이 맞지 않을 때 여러 줄로 넘겨 배치할 수 있게 합니다.
**레이아웃 흐름 무시** 는 **자식** 에 설정되며, 해당 노드가 부모의 배치에서 제외될지 여부를 결정합니다. 끄면 부모가 위치를 정합니다. 켜면 Anchor 및 Position 값으로 직접 고정합니다.
이로부터 두 가지 결과가 따릅니다:
* 위젯을 **자유** 컨테이너에 넣으면 정확히 떨어뜨린 위치에 그대로 남습니다.
* 방향이 있는 컨테이너에 넣으면 흐름에 합류해 줄에서 자신의 자리를 차지합니다.
컨테이너를 **자유** 로 전환하면 기존 자식들이 현재 위치에 고정되므로 아무것도 튀지 않습니다.
GUI의 루트는 항상 자유 배치됩니다.
## 알아두면 좋은 다른 속성
* **투명도**: 100%는 완전히 불투명하고, 0%는 완전히 투명합니다. 기본값은 100%입니다.
* **Scene Inset**: GUI가 자리하는 화면의 어느 부분인지입니다.
* **전체 화면** 전체 렌더 가능한 화면을 사용합니다.
* **상호작용 가능 안전 영역** 채팅, 미니맵, HUD 표시기 같은 클라이언트 자체 인터페이스를 피합니다.
* **기기 안전 영역** 노치나 시스템 바 같은 물리적 가림도 피합니다. 이 옵션은 캔버스가 모바일 미리보기일 때 제공됩니다.
편집기가 작성하는 코드에서는 이 세 가지 선택이 `screenInset: 'none'`, `'interactable'` 와 `'device'`. 참조 [화면 인셋 영역](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md#screen-inset-area).
GUI의 루트에 고정 픽셀 단위의 너비와 높이를 지정하면, 캔버스는 이를 화면이 아니라 정확히 그 크기의 아트보드로 프레임 처리합니다.
## 휴대폰에서 UI 확인하기
캔버스 오른쪽 아래 모서리의 컨트롤로 데스크톱 화면과 휴대폰 사이의 미리보기를 전환할 수 있습니다. 모바일 미리보기에서는 노치가 포함된 휴대폰 프레임 안에 캔버스가 그려져 화면 가장자리가 실제로 어디에 오는지 볼 수 있습니다.
플레이어가 보고 도달할 수 있는 위치에 요소를 배치하는 데 도움이 되는 두 종류의 가이드가 있습니다:
* **안전 영역 가이드** 는 GUI가 제한되는 화면 부분의 윤곽을 그리며, **Scene Inset** 선택한 값과 일치합니다. Scene Inset이 **기기 안전 영역** 또는 **상호작용 가능 안전 영역** 비어 있으면 윤곽선은 항상 켜져 있습니다. 이는 GUI가 잘리는 영역이기 때문입니다. Scene Inset을 **전체 화면** 로 설정하면 프레임 아이콘 버튼으로 윤곽선을 켜거나 끌 수 있습니다.
* **HUD 가이드** 는 조이스틱, 점프 및 행동 버튼, 이모트 휠, 프로필, 채팅, 나침반과 같은 모바일 클라이언트 자체 컨트롤을 그립니다. 참고용일 뿐이며 선택하거나 이동할 수는 없습니다. 게임 컨트롤러 버튼으로 켜고 끌 수 있으며, 모바일 미리보기에서만 나타나고, Scene Inset이 안전 영역일 때 기본적으로 가이드가 표시됩니다.
안전 영역 밖에 배치된 콘텐츠는 숨겨지지 않고 윤곽선 너머로 그려집니다. 그 넘침이 경고입니다. 실제 클라이언트에서는 게임 자체의 HUD 아래에 놓일 것입니다.
**상호작용 가능 안전 영역** 는 모바일 클라이언트의 왼쪽 열 컨트롤을 비우지만, 오른쪽 가장자리는 기기 영역과 공유하므로 오른쪽 아래 모서리의 액션 버튼은 의도적으로 그 위에 그려집니다. 그 모서리들은 비워 두세요. 참조 [클라이언트 컨트롤이 위치하는 곳](/creator/content-creator-ko/build-for-mobile/develop/safe-area.md#where-the-client-controls-live).
{% hint style="warning" %}
**📔 참고**: 이 가이드는 편집기 전용 근사치입니다. 실제 영역은 런타임에 클라이언트가 보고하며 기기에 따라 다르므로, 실제 휴대폰에서 항상 확인하세요. 참조 [모바일에서 미리보기](/creator/content-creator-ko/build-for-mobile/develop/preview-on-mobile.md).
{% endhint %}
## 모바일 조작 사용자 지정
모바일 클라이언트에서 플레이어는 조이스틱, 조준점, 그리고 한 줄의 액션 버튼으로 이루어진 네이티브 화면 컨트롤 세트를 통해 이동하고 행동합니다. 그 **MobileHUD** 항목을 사용하면 코드를 작성하지 않고도 HUD를 재구성할 수 있으며, 진행하면서 그 결과를 캔버스에 표시합니다.
장면에 GUI가 하나 이상 있으면, **MobileHUD** 목록의 첫 번째 행으로 표시되며 **GUI** 자신의 GUI 위에 있습니다. 오른쪽에서 패널을 열려면 선택하세요.
HUD 전체를 숨기는 체크박스가 위쪽에 세 개 있습니다:
* **조이스틱 숨기기**: 이동 스틱을 제거합니다.
* **조준점 숨기기**: 조준 레티클을 제거합니다.
* **입력 액션 숨기기**: 모든 액션 버튼을 한 번에 제거합니다.
그 아래의 **입력 액션** 섹션에는 화면상의 슬롯을 채우는 순서대로 8개의 버튼이 나열됩니다:
| 액션 | 화면의 버튼 |
| ------------------------------------- | ------------- |
| `IA_JUMP` | 기본적으로 큰 중앙 버튼 |
| `IA_POINTER` | 상호작용 버튼 |
| `IA_PRIMARY (E)` | E 버튼 |
| `IA_SECONDARY (F)` | F 버튼 |
| `IA_ACTION_3 (1)` 를 `IA_ACTION_6 (4)` | 숫자 버튼 |
각 행에는 세 가지가 있습니다:
* **메인**: 이 액션을 큰 중앙 버튼으로 만드는 라디오 버튼입니다. `IA_JUMP` 은 기본적으로 메인이며, 한 번에 하나의 액션만 메인이 될 수 있습니다.
* 하나의 **눈 아이콘** 으로 해당 버튼을 보이거나 숨깁니다. 하나를 숨기면 아래 버튼이 위로 올라와 빈칸을 채웁니다.
* **사용자 지정 아이콘**: 버튼의 글리프를 `.png`, `.jpg` 또는 `.jpeg` 형식의 이미지로 장면에서 바꿉니다.
기본적으로는 아무것도 숨겨지지 않으며 `IA_JUMP` 이 메인 버튼입니다. 이는 HUD를 건드리지 않는 장면에서 플레이어가 받는 것과 정확히 같습니다.
{% hint style="info" %}
**💡 팁**: 숫자 버튼은 보통 "+" 오버플로 토글 뒤에 있습니다. 상위 버튼을 충분히 숨기면 직접 표시됩니다. 슬롯이 어떻게 채워지는지는 [화면상 컨트롤](/creator/content-creator-ko/sdk7/interactivity/touch-screen-controls.md#how-the-button-layout-works) 를 참조하세요.
{% endhint %}
### 작성하는 파일
변경 사항은 `src/mobile-hud.ts`에 기록되며, `setupMobileHud()` 함수를 내보냅니다. 이 함수는 SDK의 [`TouchScreenControls`](/creator/content-creator-ko/sdk7/interactivity/touch-screen-controls.md) 구성 요소를 기반으로 합니다:
```ts
import { engine, InputAction, TouchScreenControls } from '@dcl/sdk/ecs'
export function setupMobileHud() {
TouchScreenControls.createOrReplace(engine.RootEntity, {
hideJoystick: true,
hideCrosshair: false,
mainAction: InputAction.IA_PRIMARY,
touchInputs: [
{ inputAction: InputAction.IA_ACTION_3, hide: true },
],
})
}
```
편집기는 또한 import와 호출을 당신의 `src/index.ts`:
```ts
import { setupMobileHud } from './mobile-hud'
setupMobileHud()
```
이 파일은 말할 내용이 있을 때만 존재합니다. 모든 것을 기본값으로 되돌리거나 마지막 GUI를 삭제하면, Creator Hub가 삭제합니다 `src/mobile-hud.ts` 그리고 그 두 줄을 다시 제거합니다.
{% hint style="warning" %}
**📔 참고**: 동안 **MobileHUD** 선택되어 있으면 위젯 팔레트가 비활성화되고 미리보기 컨트롤이 숨겨집니다. 배치할 것이 없고 HUD는 모바일 전용이기 때문입니다. 직접 만든 GUI 중 하나를 선택하면 다시 나타납니다.
{% endhint %}
## 파일이 저장되는 위치
UI 편집기는 씬의 실제 소스 파일을 편집합니다. 별도의 저장 형식은 없습니다.
* 각 GUI는 하나의 `.tsx` 아래의 파일 `src/ui/`.
* `src/ui/index.tsx` 는 편집기가 이들을 모으기 위해 생성합니다. 수동으로 편집하지 마세요.
* `src/mobile-hud.ts` 여기에 들어 있는 [모바일 컨트롤](#customize-the-mobile-controls), 변경한 것이 있다면 그렇습니다. 이는 바깥에 위치합니다 `src/ui/` 의도적으로 그렇게 되어 있어, GUI로 취급되지 않습니다.
씬에 이전의 단일 `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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.decentraland.org/creator/content-creator-ko/scene-editor/build/ui-editor.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.
