> 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)

화면상의 위치도 고정되어 있습니다. 버튼은 **visible** 스택의 맨 위부터 아래로 그 위치를 채웁니다. 따라서 변경되는 것은 *어떤* 버튼이 보이는지와 *어떤 버튼이 앞에 오는지이지* 순서가 아닙니다.

| 무엇을…                            | 컨트롤은…                                                                        |
| ------------------------------- | ---------------------------------------------------------------------------- |
| **버튼을 숨기면** (점프를 포함한 모든 버튼)     | 우선순위가 낮은 모든 버튼이 위로 올라와 빈자리를 채웁니다. 점프를 숨기면  `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)
}
```

**조이스틱 또는 십자선을 숨기기** — 이동 스틱 및/또는 조준 레티클을 제거하고, 해당 `표시` 대응하는 메서드:

```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()` 해당 항목에는 이것들을 사용하세요.

**버튼 아이콘 바꾸기** — 완전히 제어하려면(사용자 지정 아이콘, 여러 변경을 한 번에), 원시 컴포넌트를 다음에 작성하세요: `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 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/sdk7/interactivity/touch-screen-controls.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.