> 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 a sua scene através de um conjunto de controlos nativos no ecrã — um joystick virtual, uma mira e um gamepad com botões. O `TouchScreenControls` component permite que a sua scene personalize esse HUD: simplifique-o, oculte o joystick ou a mira, altere a função do botão central grande, substitua o símbolo de um botão pelo seu próprio ícone ou oculte botões por completo e substitua-os 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-159783ecb607d990118c7221056653500fbc9be3%2Ftouch-controls-default.webp?alt=media" alt="The default mobile HUD: virtual joystick on the left, gamepad buttons on the right"><figcaption><p>Os controlos predefinidos no ecrã, antes de qualquer personalização</p></figcaption></figure>

{% hint style="info" %}
O component é aplicado automaticamente enquanto o jogador está dentro da sua scene e reverte para as predefinições assim que sai, pelo que as scenes que não o utilizam não são afetadas. Só afeta plataformas com controlos nativos no ecrã: não tem efeito no computador nem em VR.
{% endhint %}

## O que é apresentado por predefinição

A partir do SDK `7.32.0`, todas as scenes começam com três botões de gamepad visíveis:

* `IA_JUMP`, o botão central grande
* `IA_POINTER`, o botão de interação
* `IA_PRIMARY`, o botão E

`IA_SECONDARY` e `IA_ACTION_3` a `IA_ACTION_6` começam ocultos. Só precisa de `TouchScreenControls` se quiser algo diferente.

{% hint style="warning" %}
**📔 Nota**: A predefinição de três botões e o helper `showDefault()` requerem o SDK `7.32.0` ou posterior. Nas versões anteriores, os oito botões são apresentados, a menos que a sua scene oculte alguns, e `showDefault()` não existe, pelo que `showAll()` é a única forma de voltar a apresentar os botões.
{% endhint %}

O SDK aplica esse conjunto predefinido uma vez, no início da scene, imediatamente antes do primeiro frame, e ignora-o se a sua scene já tiver escolhido os próprios botões. Considera-se que a sua scene já fez uma escolha se ocorrer uma das seguintes situações:

* Já foi executado um dos helpers de visibilidade dos botões: `hideAll()`, `showAll()`, `showDefault()` ou `hide()`.
* O component na entidade raiz já lista pelo menos um botão, por exemplo, porque a sua scene o definiu com `createOrReplace` no nível superior de `index.ts`, fora de `main()`.

`hideJoystick()`, `showJoystick()`, `hideCrosshair()`, `showCrosshair()` e `setMainAction()` não contam: o conjunto predefinido de botões continua a ser aplicado juntamente com eles.

A sua `main()` função é executada após essa escrita, por isso tudo o que fizer aí fica por cima do conjunto predefinido. Um helper como `hide()` é combinado com ele, enquanto `createOrReplace` substitui toda a lista pela sua.

Para voltar a mostrar os botões ocultos, chame `showAll()` para mostrar os oito. `showDefault()` restaura o conjunto predefinido e mantém intactos os seus ícones, joystick, mira e ação principal.

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

// Mostrar todos os botões no ecrã, incluindo os botões 1 / 2 / 3 / 4
TouchScreenControls.showAll()
```

## Como funciona a disposição dos botões

Os botões do gamepad formam uma única **pilha de prioridades**. 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 no ecrã também são fixas. Os botões **visíveis** ocupam essas posições de cima para baixo na pilha — portanto, o que pode alterar é *quais* botões ficam visíveis e *qual fica em primeiro plano*, não a respetiva ordem.

| Quando…                                                    | Os controlos…                                                                                                                                                                       |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Oculta um botão** (qualquer botão, incluindo o de salto) | Todos os botões de prioridade inferior sobem para preencher o espaço. Oculte o botão de salto e `IA_POINTER` ocupa a posição central.                                               |
| **Não altera nada**                                        | Aplica-se o conjunto predefinido: `IA_JUMP` é o botão central grande, com `IA_POINTER` e `IA_PRIMARY` nas posições à sua volta.                                                     |
| **Definir um botão principal** com `mainAction`            | Essa ação passa para a frente e torna-se o botão central; todos os outros botões mantêm a ordem normal.                                                                             |
| **Definir um botão principal que também está oculto**      | A ocultação prevalece — o botão permanece oculto.                                                                                                                                   |
| **Deixar 5 ou menos botões visíveis**                      | Todos são apresentados diretamente (o botão central mais até quatro à sua volta); não há menu "+".                                                                                  |
| **Deixar mais de 5 botões visíveis**                       | O "+" ocupa o último espaço, por isso quatro botões são apresentados diretamente (o botão central mais três), e os restantes ficam atrás do botão de alternância de excedentes "+". |

<figure><img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-2c1bf3ebb2a4c72f91fbd85fd13e64e823f94260%2Fcontrol-ordering.webp?alt=media" alt="Three HUDs showing the gamepad reflowing as the number of visible buttons changes"><figcaption><p>Como os botões se reorganizam consoante a quantidade visível. <strong>Esquerda (7 botões):</strong> o botão principal, um arco de 1–3 e o "+" a conter os excedentes (4–7) numa coluna que sobe. <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> os quatro são apresentados diretamente e o "+" desaparece.</p></figcaption></figure>

{% hint style="info" %}
Os `1`/`2`/`3`/`4` botões começam ocultos. `showAll()` volta a apresentá-los, mas isso deixa oito botões visíveis, por isso os de prioridade mais baixa ficam atrás do "+". Para apresentar diretamente no ecrã um botão numerado, mantenha a quantidade visível em cinco ou menos: mostre apenas os botões que a sua cena realmente utiliza.
{% endhint %}

## Tarefas comuns

`TouchScreenControls` inclui um conjunto de funções auxiliares. Cada uma escreve o componente na `RootEntity` da cena (onde o cliente o lê) e combina-o com o valor atual, para que as possa chamar a partir de qualquer lugar.

**Alterar o botão principal** — faça com que o grande botão central acione outra ação:

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

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

**Ocultar o joystick ou a mira** — remova o controlo de movimento e/ou a mira e volte a apresentá-los com as funções `show` correspondentes:

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

// e para os voltar a apresentar:
TouchScreenControls.showJoystick()
TouchScreenControls.showCrosshair()
```

**Ocultar botões específicos** — indique as ações que quer ocultar (as restantes sobem):

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

**Ocultar todos os botões, mostrar todos os botões ou voltar ao conjunto predefinido:**

```ts
TouchScreenControls.hideAll()     // sem botões de gamepad
TouchScreenControls.showAll()     // os oito botões
TouchScreenControls.showDefault() // apenas salto, ponteiro e ação principal
```

Estas três funções afetam apenas os botões do gamepad. Não repõem um joystick ou uma mira ocultos, nem alteram os ícones personalizados ou a ação principal. Utilize `showJoystick()` / `showCrosshair()` para esses elementos.

**Substituir o ícone de um botão** — para ter controlo total (ícones personalizados, várias alterações de uma só vez), escreva o componente diretamente 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' } } },
			},
		],
	})
}
```

Resumo das funções auxiliares:

| Função auxiliar         | O que faz                                                                                                                                                                               |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setMainAction(action)` | Define a ação ativada pelo grande botão central.                                                                                                                                        |
| `hideJoystick()`        | Oculta o joystick virtual nativo.                                                                                                                                                       |
| `showJoystick()`        | Volta a apresentar o joystick virtual nativo.                                                                                                                                           |
| `hideCrosshair()`       | Oculta a mira no ecrã.                                                                                                                                                                  |
| `showCrosshair()`       | Volta a apresentar a mira no ecrã.                                                                                                                                                      |
| `hide(actions)`         | Oculta os botões de comando indicados (integrados na configuração atual).                                                                                                               |
| `hideAll()`             | Oculta todos os botões de comando.                                                                                                                                                      |
| `showAll()`             | Apresenta os oito botões de comando (limpa a lista de botões ocultos). Não **afeta** o joystick nem a mira.                                                                             |
| `showDefault()`         | Repõe o conjunto predefinido: salto, ponteiro e ação principal visíveis; ação secundária e ações 3 a 6 ocultas. Mantém os ícones, o joystick, a mira e a ação principal tal como estão. |

## Propriedades

Escreva estes campos diretamente quando utilizar `createOrReplace`:

| Propriedade     | Tipo                                                                                                                                                  | Descrição                                                                                                                                                                                                                                                                                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hideJoystick`  | *boolean*                                                                                                                                             | Oculta o joystick virtual nativo de movimento.                                                                                                                                                                                                                                                                                                              |
| `hideCrosshair` | *boolean*                                                                                                                                             | Oculta a mira no ecrã.                                                                                                                                                                                                                                                                                                                                      |
| `mainAction`    | [*InputAction*](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) | Coloca esta ação no início da sequência, tornando-a o grande botão central; os restantes botões mantêm a ordem. Só são válidas ações de comando (consulte abaixo). Se não estiver definido, é o primeiro botão visível (`IA_JUMP` por predefinição) que ocupa essa posição. Consulte [Como funciona a disposição dos botões](#how-the-button-layout-works). |
| `touchInputs`   | *array*                                                                                                                                               | Substituições por botão. Ao escrever neste campo, a lista inteira é substituída; por isso, qualquer botão omitido é apresentado com o respetivo ícone predefinido, incluindo os que estão ocultos inicialmente.                                                                                                                                             |

Cada `touchInputs` entrada contém:

| Campo         | Tipo                                                                                                                                                  | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputAction` | [*InputAction*](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) | Identifica o botão no ecrã configurado por esta entrada.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `hide`        | *boolean*                                                                                                                                             | Oculta este botão. Por predefinição, está `false` (visível). É possível ocultar qualquer botão, **incluindo `IA_JUMP`** — os restantes sobem em cascata para ocupar o seu lugar.                                                                                                                                                                                                                                                                                                                   |
| `icon`        | [*TextureUnion*](https://docs.decentraland.org/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 variante `texture` com um `src` mapeado para conteúdo (uma imagem incluída na sua Scene) — `{ tex: { $case: 'texture', texture: { src: 'images/grab.png' } } }`. Só são suportados caminhos para conteúdo da Scene (não URLs externas, texturas de Avatar ou de vídeo). No botão de salto, isto substitui todos os estados dinâmicos (salto / salto duplo / deslize). Se não for possível resolver o caminho, é usado o glifo integrado. |

## Que ações correspondem a cada botão

Os valores [`InputAction`](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) aqui são os mesmos usados em [Input em dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/input-on-mobile.md) e [Eventos de clique](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md). Estas são as ações que correspondem aos botões no ecrã:

| InputAction                                                   | Botão no ecrã                         |
| ------------------------------------------------------------- | ------------------------------------- |
| `IA_JUMP`                                                     | O botão central grande (predefiniçã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 — não correspondem a um botão e não podem ser usados aqui.
{% endhint %}

## Exemplo

Para ocultar o joystick, mantenha ocultos os botões F e numerados e atribua ao botão central de salto 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: [
			// Esta lista substitui a predefinida, por isso os botões que normalmente começam
			// ocultos também têm de ser listados aqui
			{ inputAction: InputAction.IA_SECONDARY, hide: true },
			{ 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-e8fa39c0bb21eb9c2ff7949a101321cc1549f937%2Fcustom-main-action.webp?alt=media" alt="A mobile HUD with the joystick hidden and the central jump button showing a custom banana icon"><figcaption><p>Resultado: joystick oculto, botões numerados ocultos (o «+» desaparece) e o ícone do botão de salto substituído</p></figcaption></figure>

Para substituir completamente os controlos nativos, oculte-os aqui e crie os seus próprios botões táteis com [UI Input Binding](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/ui_input_binding.md).

## Relacionados

* [Vinculação de entrada da UI](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/ui_input_binding.md)
* [Entrada em dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/input-on-mobile.md)
* [Eventos de clique](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md)
* [Detetar a plataforma a partir do código](https://docs.decentraland.org/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.
