> 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'` 은 그 작업의 일부를 처리합니다. 즉, 익스플로러가 씬 UI용으로 지정한 사각형 안에 UI를 배치합니다. 모바일에서는 왼쪽 컨트롤 영역이 비워집니다. 오른쪽 아래의 액션 버튼은 설계상 해당 영역 위에 표시되므로 [그 모서리](/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_SECONDARY` 또는 `IA_ACTION_3`–`IA_ACTION_6`** (키보드의 `F` 및 `1`/`2`/`3`/`4` 키). 단, 장면에 해당 버튼이 표시되는 경우는 예외입니다. 모바일에서는 기본적으로 숨겨져 있습니다(SDK 7.32.0 이상). 자세한 내용은 [모바일 입력](/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.showDefault()
  TouchScreenControls.showJoystick()
  // ... UI 숨기기
}
```

버튼을 복원할 때는 `showDefault()` 대신 `showAll()` 을 사용하세요. 장면을 시작할 때는 점프, 포인터, 기본 버튼만 표시되므로 `showAll()` 를 사용하면 플레이어에게 처음부터 표시되지 않았던 버튼 5개까지 다시 나타납니다. 기본 버튼 3개를 표시하는 기능과 `showDefault()` 를 사용하려면 SDK 7.32.0 이상이 필요합니다. 이전 SDK에서는 버튼 8개가 모두 표시되며, `showAll()` 만이 버튼을 복원하는 유일한 방법입니다. `showDefault()` 는 게임패드 버튼만 복원하므로 `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.
