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

# Controles na Tela

Configure os controles nativos de toque na tela para a sua scene.

No cliente móvel, os jogadores interagem com sua scene por meio de um conjunto de controles nativos na tela — um joystick virtual, uma mira e um gamepad de botões. O `TouchScreenControls` componente permite que sua scene reformule esse HUD: reduza a poluição visual, oculte o joystick ou a mira, altere o que o grande botão central faz, troque o glifo de um botão por seu próprio ícone ou oculte botões por completo e os substitua pela sua própria UI.

<figure><img src="https://2402076176-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>Os controles padrão na tela, antes de qualquer personalização</p></figcaption></figure>

{% hint style="info" %}
O componente é aplicado automaticamente enquanto o jogador estiver dentro da sua scene e volta aos padrões (nada oculto, pular como botão central) no momento em que ele sai — então scenes que não o usam não são afetadas. Ele afeta apenas plataformas com controles nativos na tela: não faz nada no desktop e não tem efeito em VR.
{% endhint %}

## Como o layout dos botões funciona

Os botões do gamepad formam uma única **pilha de prioridade**. A ordem é fixa:

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)

As posições na tela também são fixas. Os **botões visíveis** preenchem essas posições de cima da pilha para baixo — então o que você altera é *quais* botões ficam visíveis e *qual deles lidera*, não a ordem deles.

| Quando você…                                           | Os controles…                                                                                                                                  |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Oculta um botão** (qualquer botão, incluindo pular)  | Cada botão de menor prioridade sobe para preencher a lacuna. Oculte pular e `IA_POINTER` assume o lugar central.                               |
| **Deixe a pilha como está**                            | O primeiro botão (`IA_JUMP`) é o grande botão central; os próximos botões preenchem os slots ao redor.                                         |
| **Defina um botão principal** com `mainAction`         | Essa ação vai para a frente da pilha e se torna o botão central; os outros botões mantêm sua ordem normal.                                     |
| **Defina um botão principal que também esteja oculto** | Ocultar vence — o botão permanece oculto.                                                                                                      |
| **Mantenha 5 ou menos botões visíveis**                | Todos aparecem diretamente (o botão central mais até quatro ao redor); não há menu "+".                                                        |
| **Mantenha mais de 5 botões visíveis**                 | O "+" ocupa o último slot, então quatro aparecem diretamente (o botão central mais três) e o resto fica atrás do alternador de excedentes "+". |

<figure><img src="https://2402076176-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>Como os botões se reorganizam com a quantidade visível. <strong>Esquerda (7 botões):</strong> o botão principal, um arco de 1–3 e o "+" contendo o excedente (4–7) em uma coluna que sobe para cima. <strong>Centro (5 botões):</strong> o mesmo arco, com uma coluna de excedentes mais curta (4–5) atrás do "+". <strong>Direita (4 botões):</strong> todos os quatro aparecem diretamente e o "+" desaparece.</p></figcaption></figure>

{% hint style="info" %}
É também assim que você exibe os `1`/`2`/`3`/`4` botões, que caso contrário ficam escondidos atrás do "+": oculte botões de maior prioridade suficientes para reduzir a quantidade visível para cinco ou menos, e eles aparecerão diretamente.
{% endhint %}

## Tarefas comuns

`TouchScreenControls` vem com um conjunto de helpers práticos. Cada um escreve o componente no RootEntity da scene `RootEntity` (onde o cliente o lê) e faz merge com o valor atual, então você pode chamá-los de qualquer lugar.

**Altere o botão principal** — faça o grande botão central acionar uma ação diferente:

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

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

**Oculte o joystick ou a mira** — remova o stick de movimento e/ou o retículo de mira e traga-os de volta com seus `show` equivalentes:

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

// e para trazê-los de volta:
TouchScreenControls.showJoystick()
TouchScreenControls.showCrosshair()
```

**Oculte botões específicos** — passe as ações que você quer remover (as demais sobem em cascata):

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

**Oculte ou mostre todos os botões** — limpe o HUD ou redefina-o:

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

`showAll()` afeta apenas os botões do gamepad — ele não restaura um joystick ou uma mira ocultos. Use `showJoystick()` / `showCrosshair()` para isso.

**Substitua o ícone de um botão** — para controle total (ícones personalizados, várias alterações de uma vez), escreva o componente bruto em `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' } } },
			},
		],
	})
}
```

Os helpers em resumo:

| Auxiliar                | O que faz                                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| `setMainAction(action)` | Define qual ação o grande botão central aciona.                                                              |
| `hideJoystick()`        | Oculta o joystick virtual nativo.                                                                            |
| `showJoystick()`        | Mostra o joystick virtual nativo novamente.                                                                  |
| `hideCrosshair()`       | Oculta a mira / retículo na tela.                                                                            |
| `showCrosshair()`       | Mostra a mira / retículo na tela novamente.                                                                  |
| `hide(actions)`         | Oculta os botões do gamepad indicados (mesclados com a configuração atual).                                  |
| `hideAll()`             | Oculta todos os botões do gamepad.                                                                           |
| `showAll()`             | Mostra todos os botões do gamepad (limpa a lista de botões ocultos). Não **não** afeta o joystick/crosshair. |

## Propriedades

Escreva isso diretamente quando você usar `createOrReplace`:

| Propriedade     | Tipo                                                                                                                     | Descrição                                                                                                                                                                                                                                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hideJoystick`  | *boolean*                                                                                                                | Oculta o joystick virtual nativo de movimento.                                                                                                                                                                                                                                                                       |
| `hideCrosshair` | *boolean*                                                                                                                | Oculta a mira / retículo na tela.                                                                                                                                                                                                                                                                                    |
| `mainAction`    | [*InputAction*](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) | Move essa ação para a frente da pilha, tornando-a o grande botão central; os outros botões mantêm sua ordem. Apenas ações do gamepad são válidas (veja abaixo). Quando não definido, o primeiro botão visível (`IA_JUMP` por padrão) lidera. Veja [Como o layout dos botões funciona](#how-the-button-layout-works). |
| `touchInputs`   | *array*                                                                                                                  | Substituições por botão. Um botão que não estiver listado mantém seu padrão (mostrado, com seu glifo padrão).                                                                                                                                                                                                        |

Cada `touchInputs` a entrada tem:

| Campo         | Tipo                                                                                                                     | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputAction` | [*InputAction*](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) | Qual botão na tela esta entrada configura.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `hide`        | *boolean*                                                                                                                | Oculta este botão. O padrão é `false` (mostrado). Qualquer botão pode ser ocultado, **incluindo `IA_JUMP`** — os demais sobem em cascata para preencher seu lugar.                                                                                                                                                                                                                                                                                                                             |
| `ícone`       | [*TextureUnion*](/creator/content-creator-pt/scenes-sdk7/ui-2d/ui_background.md#background) (opcional)                   | Substitui o glifo do botão por uma imagem da scene. Use a `texture` variante com um conteúdo mapeado `src` (uma imagem incluída na sua scene) — `{ tex: { $case: 'texture', texture: { src: 'images/grab.png' } } }`. Só caminhos de conteúdo da scene são suportados (não URLs externos, avatares ou texturas de vídeo). Para o botão de pular, isso substitui todos os seus estados dinâmicos (pular / pulo duplo / planar). Se o caminho não puder ser resolvido, o glifo embutido é usado. |

## Quais ações mapeiam para quais botões

O [`InputAction`](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) os valores aqui são os mesmos usados em [Input no mobile](/creator/content-creator-pt/criar-para-mobile/desenvolver/input-on-mobile.md) e [Eventos de clique](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md). Estas são as ações que mapeiam para botões na tela:

| InputAction                                                   | Botão na tela                   |
| ------------------------------------------------------------- | ------------------------------- |
| `IA_JUMP`                                                     | O grande botão central (padrão) |
| `IA_POINTER`                                                  | O botão de interação            |
| `IA_PRIMARY`                                                  | O botão E                       |
| `IA_SECONDARY`                                                | O botão F                       |
| `IA_ACTION_3` / `IA_ACTION_4` / `IA_ACTION_5` / `IA_ACTION_6` | Os botões 1 / 2 / 3 / 4         |

{% hint style="warning" %}
`IA_ANY` e `IA_MODIFIER` são valores meta — eles não mapeiam para um botão e não podem ser usados aqui.
{% endhint %}

## Exemplo

Para ocultar o joystick, guardar os botões numerados e dar ao botão central de pular um ícone personalizado incluído na sua scene:

```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://2402076176-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>O resultado: joystick removido, botões numerados ocultos (então o "+" desaparece) e o botão de pular com novo ícone</p></figcaption></figure>

Para substituir os controles nativos por completo, oculte-os aqui e crie seus próprios botões de toque com [Vinculação de entrada da UI](/creator/content-creator-pt/scenes-sdk7/ui-2d/ui_input_binding.md).

## Relacionados

* [Vinculação de entrada da UI](/creator/content-creator-pt/scenes-sdk7/ui-2d/ui_input_binding.md)
* [Input no mobile](/creator/content-creator-pt/criar-para-mobile/desenvolver/input-on-mobile.md)
* [Eventos de clique](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md)
* [Deteta a plataforma a partir do código](/creator/content-creator-pt/criar-para-mobile/desenvolver/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-pt/scenes-sdk7/interatividade/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.