> 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/build-for-mobile/develop/ui-best-practices.md).

# UI 모범 사례

모바일에서 잘 작동하는 씬 UI를 디자인하기 위한 권장 사항과 금지 사항입니다.

Decentraland 모바일 UI에 대해 아직 검증된 단일 레시피는 없습니다 — 플랫폼은 새롭고 우리는 아직 반복 개선 중입니다. 이 페이지의 권장 사항은 실제 씬 작업에서 얻은 현재의 모범 사례를 추린 것입니다. 이를 출발점으로 삼고 실제 기기에서 테스트하세요.

{% embed url="<https://www.youtube.com/watch?v=5OmTTzpPdDc>" %}

## 권장 사항

* **모바일 전용 UI를 디자인하세요**, 또는 화면 크기와 플랫폼에 따라 UI를 다르게 만드세요. 사용 [`isMobile()`](/creator/content-creator-ko/build-for-mobile/develop/detect-platform.md) 하여 분기하세요.
* **중요한 UI는** [**안전 영역**](/creator/content-creator-ko/build-for-mobile/develop/safe-area.md)**.** 기기의 하드웨어 여백(노치, 상태 표시줄, 홈 인디케이터)은 기본적으로 자동으로 확보됩니다 — 다만 `screenInset: 'none'`를 사용해 옵트아웃하지 마세요. `screenInset: 'interactable'` 클라이언트 자체의 컨트롤은 별도의 영역이며, 이 작업의 일부는  [그 모서리들](/creator/content-creator-ko/build-for-mobile/develop/safe-area.md#where-the-client-controls-live) 을 염두에 두세요. `'interactable'` 모바일 클라이언트 필요 `1.12.1` 이상 — 이전 클라이언트는 여백을 전혀 보고하지 않아서 UI가 화면 전체를 덮습니다.
* **옵션을 최소화하세요.** 플레이어가 지금 당장 필요한 것만 보여 주고 나머지는 점진적으로 공개하세요.
* **실행 가능한 대화상자는 화면 중앙에 배치하세요** — 플레이어가 읽고 응답해야 하는 모든 곳에.
* **실행이 필요 없는 메시지는 상단 중앙에 배치하세요** — 상태, 알림, 주변 정보.
* **전체 화면 UI 뒤에 터치 컨트롤을 숨기세요.** 점수판, 상점, 또는 결과 패널이 열려 있는 동안에는 플레이어가 점프하거나 E를 누를 필요가 없습니다. 참조: [액션 버튼 위에 전체 화면 UI](#full-screen-ui-over-the-action-buttons).

## 금지 사항

* **가상 화면을 고려하지 않고 UI 요소 크기를 픽셀만으로 정하지 마세요.** 픽셀 값은 `virtualWidth` / `virtualHeight` 에 설명된 기준 해상도를 기준으로 스케일됩니다 [화면 UI](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md#screen-virtual-scale) — `1600x720` 모바일에서는 기본적으로, `1920x1080` 데스크톱과 웹에서는. 픽셀 값이 어떤 기준 해상도를 기준으로 작성되었는지 파악하고, 기본값이 아니라면 명시적으로 전달한 뒤 플랫폼을 고려한 크기 조정과 함께 사용하세요. 가상 화면은 (크기를 `0`)을 정말로 원시 캔버스 픽셀로 사용하고 싶을 때만 비활성화하세요.
* **안전 영역 밖에 요소를 배치하지 마세요.** 클라이언트의 컨트롤과 충돌합니다.
* **UI를 왼쪽 상단이나 왼쪽 가장자리에 고정하지 마세요.** 그 위치에는 클라이언트가 채팅, 프로필, 가상 조이스틱을 모두 장면 UI 위에 그립니다. 대신 오른쪽이나 중앙에 고정하거나, `screenInset: 'interactable'`. 참고: [UI를 절대 좌측 상단에 고정하지 마세요](/creator/content-creator-ko/sdk7/designing-the-experience/ux-ui-guide.md#never-anchor-your-ui-to-the-top-left).
* **상호작용 요소를 오른쪽 아래 모서리에 두지 마세요.** 그 영역 위에는 액션 버튼이 그려지므로 그곳을 탭하면 장면이 아니라 클라이언트의 버튼으로 전달됩니다.
* **작은 버튼에 의존하지 마세요.** 작은 대상은 터치스크린에서 탭하기 어렵습니다.
* **키 동작을 `IA_ACTION_3`–`IA_ACTION_6`** (데스크톱의 `1`/`2`/`3`/`4` 키보드의 키)에 연결하지 마세요. 모바일에서는 쉽게 닿기 어렵습니다. 참조: [모바일에서의 입력](/creator/content-creator-ko/build-for-mobile/develop/input-on-mobile.md).

## 액션 버튼 위에 전체 화면 UI

`screenInset: 'interactable'` UI를 왼쪽 컨트롤과 겹치지 않게 하지만, 오른쪽 아래의 액션 버튼은 설계상 그 영역 위에 그려집니다. 그 영역을 채우는 패널도 여전히 그곳에서 가려지며, 그 구역을 탭하면 UI가 아니라 클라이언트 버튼이 실행됩니다.

다음의 경우 **게임플레이 HUD** 플레이어가 움직이는 동안에도 사용할 수 있어야 하므로 오른쪽 아래 모서리에서 벗어나게 두세요: 오른쪽 상단이나 상단 중앙에 고정하세요.

다음의 경우 **게임플레이를 방해하는 UI**, 예를 들어 점수판, 상점, 결과 화면 같은 경우, 열려 있는 동안 터치 컨트롤을 숨기고 닫을 때 복원하세요:

```ts
import { TouchScreenControls } from '@dcl/sdk/ecs'

function openScoreboard() {
  TouchScreenControls.hideAll()
  TouchScreenControls.hideJoystick()
  // ... UI를 표시
}

function closeScoreboard() {
  TouchScreenControls.showAll()
  TouchScreenControls.showJoystick()
  // ... UI를 숨기기
}
```

`showAll()` 게임패드 버튼만 복원하므로 다음과 함께 사용하세요 `showJoystick()`. 두 도우미는 데스크톱에서는 아무 작업도 하지 않으므로 플랫폼에 따라 분기할 필요가 없습니다. 참조: [화면 컨트롤](/creator/content-creator-ko/sdk7/interactivity/touch-screen-controls.md) 전체 컴포넌트는

패널이 열려 있는 동안 아바타도 이동을 멈춰야 한다면, [입력 수정자](/creator/content-creator-ko/sdk7/interactivity/avatars/locomotion.md#freeze-the-player) 를 추가로 적용하세요.

## 크기 조정

예전 경험칙 — *데스크톱에서 디자인한 다음 모바일용 UI 크기를 3배로 키우기* — 는 두 가지 SDK 변경 이전의 규칙이며 더 이상 맹목적으로 적용해서는 안 됩니다. 이제 그 3배 중 대부분은 자동으로 적용됩니다:

* **`devicePixelRatio` UI 레이아웃에 관여하지 않습니다.** 픽셀 단위 UI는 이제 렌더링됩니다 `devicePixelRatio` 예전보다 더 크게 — 일반적으로 **휴대폰에서는 2\~3배**, 리트나 노트북에서도 마찬가지입니다. 비활성화 옵션은 없습니다.
* **가상 화면의 기본값은 플랫폼별로**, `1600x720` 모바일에서는 `1920x1080` 데스크톱과 웹에서는, 따라서 동일한 픽셀 값이 휴대폰에서는 이미 화면의 약 1.2배 더 넓은 영역을 차지합니다.

데스크톱 크기를 그대로 시작점으로 삼고 실제 기기에서 측정하세요 — 참조: [모바일에서 미리보기](/creator/content-creator-ko/build-for-mobile/develop/preview-on-mobile.md) — 그리고 탭 대상이나 텍스트가 실제로 부족한 부분에서만 확대하세요. 다음으로 분기하세요 [`isMobile()`](/creator/content-creator-ko/build-for-mobile/develop/detect-platform.md) 둘이 정말로 달라야 할 때만.

## 관련 항목

* [누락된 기능](/creator/content-creator-ko/build-for-mobile/mobile-client/missing-features.md)
* [모바일 안전 영역](/creator/content-creator-ko/build-for-mobile/develop/safe-area.md)
* [코드에서 플랫폼을 감지하세요](/creator/content-creator-ko/build-for-mobile/develop/detect-platform.md)
* [화면 UI](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md)
* [UX 및 UI 가이드](/creator/content-creator-ko/sdk7/designing-the-experience/ux-ui-guide.md)


---

# 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/build-for-mobile/develop/ui-best-practices.md?ask=<question>&goal=<user_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.