> 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/sdk7/interactivity/touch-screen-controls.md).

# 화면 내 컨트롤

씬의 기본 화면 터치 컨트롤을 설정합니다.

모바일 클라이언트에서는 플레이어가 가상 조이스틱, 십자선, 그리고 버튼들로 이루어진 게임패드 같은 기본 화면 컨트롤을 통해 씬과 상호작용합니다. 이 `TouchScreenControls` 컴포넌트를 사용하면 씬에서 해당 HUD를 다시 구성할 수 있습니다. 요소를 정리하고, 조이스틱이나 십자선을 숨기고, 중앙의 큰 버튼이 하는 일을 바꾸고, 버튼의 글리프를 직접 만든 아이콘으로 바꾸거나, 버튼을 완전히 숨기고 직접 만든 UI로 대체할 수 있습니다.

<figure><img src="https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-0a69ce0ba0199fe829376ff409c7ffa02c679b0a%2Ftouch-controls-default.jpg?alt=media" alt="The default mobile HUD: virtual joystick on the left, gamepad buttons on the right"><figcaption><p>커스터마이징 전의 기본 화면 컨트롤</p></figcaption></figure>

{% hint style="info" %}
이 컴포넌트는 플레이어가 씬 안에 있는 동안 자동으로 적용되며, 떠나는 순간 기본값(숨겨진 것 없음, 중앙 버튼은 점프)으로 되돌아갑니다. 따라서 이 컴포넌트를 사용하지 않는 씬에는 영향을 주지 않습니다. 기본 화면 컨트롤이 있는 플랫폼에만 영향을 주며, 데스크톱에서는 아무 동작도 하지 않고 VR에서도 효과가 없습니다.
{% endhint %}

## 버튼 레이아웃 작동 방식

게임패드 버튼은 하나의 **우선순위 스택**. 순서는 고정되어 있습니다:

1. `IA_JUMP`
2. `IA_POINTER`
3. `IA_PRIMARY` (E)
4. `IA_SECONDARY` (F)
5. `IA_ACTION_3` (1)
6. `IA_ACTION_4` (2)
7. `IA_ACTION_5` (3)
8. `IA_ACTION_6` (4)

화면상의 위치도 고정되어 있습니다.  **표시되는** 버튼들은 스택의 맨 위에서 아래로 그 위치를 채웁니다. 따라서 바꾸는 것은 *어떤* 버튼이 보이는지와 *어느 버튼이 앞에 오는지이지*순서 자체는 아닙니다.

| 다음과 같이 하면…                     | 컨트롤은…                                                                    |
| ------------------------------ | ------------------------------------------------------------------------ |
| **버튼 숨기기** (점프를 포함한 모든 버튼)     | 우선순위가 더 낮은 모든 버튼이 위로 이동해 빈자리를 채웁니다. 점프를 숨기면 `IA_POINTER` 가 중앙 자리를 차지합니다. |
| **스택을 그대로 두기**                 | 첫 번째 버튼 (`IA_JUMP`)이 중앙의 큰 버튼이고, 다음 버튼들이 주변 슬롯을 채웁니다.                    |
| **메인 버튼 설정** 와 함께 `mainAction` | 그 동작이 맨 앞으로 이동해 중앙 버튼이 되며, 다른 모든 버튼은 원래 순서를 유지합니다.                       |
| **숨겨진 메인 버튼 설정**               | 숨김이 우선됩니다. 버튼은 계속 숨겨진 상태로 유지됩니다.                                         |
| **표시되는 버튼을 5개 이하로 유지하기**       | 모두 바로 표시됩니다(중앙 버튼과 그 주변의 최대 4개 버튼). "+" 메뉴는 없습니다.                        |
| **표시되는 버튼을 5개 초과로 유지하기**       | "+"가 마지막 슬롯을 차지하므로, 4개가 바로 표시되고(중앙 버튼과 3개), 나머지는 "+" 오버플로 토글 뒤에 놓입니다.    |

<figure><img src="https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-67ed40e222e68d9b13997d0b2fec7e399fc57de0%2Fcontrol-ordering.jpg?alt=media" alt="Three HUDs showing the gamepad reflowing as the number of visible buttons changes"><figcaption><p>표시 개수에 따라 버튼이 다시 배치되는 방식. <strong>왼쪽(버튼 7개):</strong> 메인 버튼, 1–3번의 호 형태 배치, 그리고 위로 올라가는 열에서 오버플로(4–7번)를 담고 있는 "+". <strong>가운데(버튼 5개):</strong> 같은 호 형태이며, 더 짧은 오버플로 열(4–5번)이 "+" 뒤에 있습니다. <strong>오른쪽(버튼 4개):</strong> 4개 모두 바로 표시되고 "+"는 사라집니다.</p></figcaption></figure>

{% hint style="info" %}
이 방식으로 다음도 표시할 수 있습니다: `1`/`2`/`3`/`4` 기본적으로는 "+" 뒤에 숨어 있는 버튼들입니다. 우선순위가 더 높은 버튼을 충분히 숨겨 표시 개수를 5개 이하로 만들면, 이 버튼들이 바로 표시됩니다.
{% endhint %}

## 자주 하는 작업

`TouchScreenControls` 편의용 헬퍼 세트를 제공합니다. 각 헬퍼는 씬의 `RootEntity` (클라이언트가 이를 읽는 곳)에 쓰고 현재 값과 병합하므로, 어디서든 호출할 수 있습니다.

**메인 버튼 변경** — 중앙의 큰 버튼이 다른 동작을 실행하도록 하세요:

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

export function main() {
	TouchScreenControls.setMainAction(InputAction.IA_PRIMARY)
}
```

**조이스틱 또는 십자선 숨기기** — 이동 스틱 및/또는 조준 십자선을 제거하고, 해당하는 `show` 복원 함수로 다시 표시합니다:

```ts
TouchScreenControls.hideJoystick()
TouchScreenControls.hideCrosshair()

// 다시 표시하려면:
TouchScreenControls.showJoystick()
TouchScreenControls.showCrosshair()
```

**특정 버튼 숨기기** — 없애고 싶은 동작을 전달하세요(나머지는 위로 계단식으로 올라갑니다):

```ts
TouchScreenControls.hide([InputAction.IA_SECONDARY, InputAction.IA_JUMP])
```

**모든 버튼 숨기기 또는 표시하기** — HUD를 지우거나 초기화하세요:

```ts
TouchScreenControls.hideAll()
TouchScreenControls.showAll()
```

`showAll()` 은 게임패드 버튼에만 영향을 줍니다. 숨겨진 조이스틱이나 십자선을 복원하지는 않습니다. 다음을 사용하세요: `showJoystick()` / `showCrosshair()` 해당 항목에는 이를 사용하세요.

**버튼 아이콘 바꾸기** — 완전히 제어하려면(사용자 지정 아이콘, 여러 변경을 한 번에 적용), raw 컴포넌트를 다음에 작성하세요: `engine.RootEntity`:

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

export function main() {
	TouchScreenControls.createOrReplace(engine.RootEntity, {
		hideCrosshair: true,
		mainAction: InputAction.IA_PRIMARY,
		touchInputs: [
			{
				inputAction: InputAction.IA_PRIMARY,
				icon: { tex: { $case: 'texture', texture: { src: 'images/grab.png' } } },
			},
		],
	})
}
```

헬퍼 한눈에 보기:

| 헬퍼                      | 기능                                                                  |
| ----------------------- | ------------------------------------------------------------------- |
| `setMainAction(action)` | 중앙의 큰 버튼이 어떤 동작을 실행할지 설정합니다.                                        |
| `hideJoystick()`        | 기본 가상 조이스틱을 숨깁니다.                                                   |
| `showJoystick()`        | 기본 가상 조이스틱을 다시 표시합니다.                                               |
| `hideCrosshair()`       | 화면의 십자선 / 조준선을 숨깁니다.                                                |
| `showCrosshair()`       | 화면의 십자선 / 조준선을 다시 표시합니다.                                            |
| `hide(actions)`         | 지정한 게임패드 버튼을 숨깁니다(현재 설정과 병합됨).                                      |
| `hideAll()`             | 모든 게임패드 버튼을 숨깁니다.                                                   |
| `showAll()`             | 모든 게임패드 버튼을 표시합니다(버튼 숨김 목록을 지웁니다). **아닙니다** 조이스틱/십자선에는 영향을 주지 않습니다. |

## 속성

다음 헬퍼를 사용할 때는 이를 직접 작성하세요: `createOrReplace`:

| 속성              | 유형                                                                                                            | 설명                                                                                                                                                                                       |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hideJoystick`  | *불리언*                                                                                                         | 기본 가상 이동 조이스틱을 숨깁니다.                                                                                                                                                                     |
| `hideCrosshair` | *불리언*                                                                                                         | 화면의 십자선 / 조준선을 숨깁니다.                                                                                                                                                                     |
| `mainAction`    | [*InputAction*](/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#pointer-buttons) | 이 동작을 스택 맨 앞으로 이동시켜 중앙의 큰 버튼으로 만듭니다. 다른 버튼들은 순서를 유지합니다. 게임패드 동작만 유효합니다(아래 참조). 설정하지 않으면 첫 번째로 보이는 버튼(`IA_JUMP` 이 기본적으로 앞에 옵니다. 다음을 참조하세요: [버튼 레이아웃 작동 방식](#how-the-button-layout-works). |
| `touchInputs`   | *배열*                                                                                                          | 버튼별 재정의 항목입니다. 목록에 없는 버튼은 기본값(표시됨, 기본 글리프 사용)을 유지합니다.                                                                                                                                    |

각 `touchInputs` 각 항목에는 다음이 있습니다:

| 필드            | 유형                                                                                                            | 설명                                                                                                                                                                                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputAction` | [*InputAction*](/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#pointer-buttons) | 이 항목이 어떤 화면 버튼을 구성하는지.                                                                                                                                                                                                                                                           |
| `hide`        | *불리언*                                                                                                         | 이 버튼을 숨깁니다. 기본값은 `false` (표시됨)입니다. 어떤 버튼이든 숨길 수 있으며, **포함: `IA_JUMP`** 나머지는 위로 계단식으로 올라가 그 자리를 채웁니다.                                                                                                                                                                             |
| `아이콘`         | [*TextureUnion*](/creator/content-creator-ko/sdk7/2d-ui/ui_background.md#background) (선택 사항)                  | 버튼 글리프를 씬 이미지로 덮어씁니다. 다음을 사용하세요. `텍스처` 콘텐츠에 매핑된 `src` (씬에 포함된 이미지) 변형을 — `{ tex: { $case: 'texture', texture: { src: 'images/grab.png' } } }`. 씬 콘텐츠 경로만 지원됩니다(외부 URL, 아바타 또는 비디오 텍스처는 지원되지 않음). 점프 버튼의 경우 이것이 모든 동적 상태(점프 / 이중 점프 / 활공)를 대체합니다. 경로를 확인할 수 없으면 기본 내장 글리프가 사용됩니다. |

## 어떤 동작이 어떤 버튼에 매핑되는지

이 [`InputAction`](/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#pointer-buttons) 여기서의 값은 다음 전반에서 사용하는 값과 동일합니다: [모바일에서의 입력](/creator/content-creator-ko/build-for-mobile/develop/input-on-mobile.md) 과 [클릭 이벤트](/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md). 이들은 화면 버튼에 매핑되는 동작입니다:

| InputAction                                                   | 화면 버튼            |
| ------------------------------------------------------------- | ---------------- |
| `IA_JUMP`                                                     | 중앙의 큰 버튼(기본값)    |
| `IA_POINTER`                                                  | 상호작용 버튼          |
| `IA_PRIMARY`                                                  | E 버튼             |
| `IA_SECONDARY`                                                | F 버튼             |
| `IA_ACTION_3` / `IA_ACTION_4` / `IA_ACTION_5` / `IA_ACTION_6` | 1 / 2 / 3 / 4 버튼 |

{% hint style="warning" %}
`IA_ANY` 과 `IA_MODIFIER` 는 메타 값입니다. 버튼에 매핑되지 않으며 여기서는 사용할 수 없습니다.
{% endhint %}

## 예시

조이스틱을 숨기고, 번호가 매겨진 버튼들을 감춘 뒤, 씬에 포함된 사용자 지정 아이콘을 중앙 점프 버튼에 적용하려면:

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

export function main() {
	TouchScreenControls.createOrReplace(engine.RootEntity, {
		hideJoystick: true,
		touchInputs: [
			{ inputAction: InputAction.IA_ACTION_3, hide: true },
			{ inputAction: InputAction.IA_ACTION_4, hide: true },
			{ inputAction: InputAction.IA_ACTION_5, hide: true },
			{ inputAction: InputAction.IA_ACTION_6, hide: true },
			{
				inputAction: InputAction.IA_JUMP,
				icon: { tex: { $case: 'texture', texture: { src: 'images/banana.png' } } },
			},
		],
	})
}
```

<figure><img src="https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-0eef110595612782808b16d7733171deeb560f16%2Fcustom-main-action.jpg?alt=media" alt="A mobile HUD with the joystick hidden and the central jump button showing a custom banana icon"><figcaption><p>결과: 조이스틱이 사라지고, 번호 버튼이 숨겨져("+"도 사라짐), 점프 버튼의 아이콘이 바뀝니다</p></figcaption></figure>

기본 컨트롤을 완전히 대체하려면, 여기서 그것들을 숨기고 다음을 사용해 직접 터치 버튼을 만드세요 [UI 입력 바인딩](/creator/content-creator-ko/sdk7/2d-ui/ui_input_binding.md).

## 관련 항목

* [UI 입력 바인딩](/creator/content-creator-ko/sdk7/2d-ui/ui_input_binding.md)
* [모바일에서의 입력](/creator/content-creator-ko/build-for-mobile/develop/input-on-mobile.md)
* [클릭 이벤트](/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md)
* [코드에서 플랫폼을 감지하세요](/creator/content-creator-ko/build-for-mobile/develop/detect-platform.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/sdk7/interactivity/touch-screen-controls.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.