> 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-15146380df30e490d11a9f8ddc16b25c14999586%2Ftouch-controls-default.webp?alt=media" alt="The default mobile HUD: virtual joystick on the left, and on the right the large jump button with the interaction and E buttons beside it"><figcaption><p>Os controlos predefinidos no ecrã, antes de qualquer personalização: saltar, interação e E</p></figcaption></figure>

{% hint style="info" %}
O component é aplicado automaticamente enquanto o jogador estiver na sua scene, e o cliente restaura os controlos próprios assim que o jogador sai. Só afeta as plataformas com controlos nativos no ecrã: não tem efeito no desktop 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` quando quiser algo diferente.

{% hint style="warning" %}
**📔 Nota**: O comportamento predefinido 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 define esse conjunto predefinido uma vez no início da scene, imediatamente antes do primeiro frame, e não o aplica se a sua scene já tiver escolhido os próprios botões. Considera-se que a sua scene já fez essa escolha se alguma destas condições se verificar:

* Já foi executado um dos helpers de visibilidade dos botões: `hideAll()`, `showAll()`, `showDefault()` ou `hide()`. Isto acontece quando chama um deles no nível superior de `index.ts`, fora de `main()`.
* O component na entidade raiz já inclui 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 aplicar-se em simultâneo.

A sua `main()` função é executada depois dessa escrita, por isso tudo o que fizer aí é acrescentado ao conjunto predefinido. Chame os helpers dentro de `main()` ou posteriormente, não no nível superior, caso contrário o conjunto predefinido é ignorado. Um helper como `hide()` combina-se com ele, enquanto `createOrReplace` substitui a lista inteira pela sua.

Para voltar a apresentar os botões ocultos, chame `showAll()` para apresentar os oito. `showDefault()` restaura o conjunto predefinido sem alterar os seus ícones, joystick, mira e ação principal.

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

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

{% hint style="warning" %}
Reagir a F ou a 1–4 através de `PointerEvents` ou de `inputSystem` não **faz** o botão aparecer. Se a sua cena os utilizar, ative-os com `TouchScreenControls`, caso contrário os jogadores em dispositivos móveis não poderão aceder-lhes.
{% endhint %}

{% hint style="info" %}
Uma cena que remova o componente (`TouchScreenControls.deleteFrom(engine.RootEntity)`) apresenta os oito botões.
{% endhint %}

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

Os botões do gamepad formam uma única **hierarquia 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 no ecrã também são fixas. Os botões **visíveis** ocupam essas posições, começando no topo da hierarquia — por isso, o que altera é *quais* botões estão visíveis e *qual deles fica*, não a ordem deles.

| Quando você…                                                | Os controles…                                                                                                                                                                                  |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ocultar um botão** (qualquer botão, incluindo o de salto) | Cada botão de prioridade inferior sobe para preencher o espaço. Oculte o botão de salto e `IA_POINTER` ocupa a posição central.                                                                |
| **Não alterar nada**                                        | O conjunto padrão é aplicado: `IA_JUMP` é o botão grande central, com `IA_POINTER` e `IA_PRIMARY` nos espaços ao redor.                                                                        |
| **Definir um botão principal** com `mainAction`             | Essa ação passa para a frente e se torna o botão central; todos os outros botões mantêm a ordem normal.                                                                                        |
| **Definir como principal um botão que também está oculto**  | Ocultar tem prioridade — o botão permanece oculto. Isso inclui F e 1–4, que começam ocultos: ative também o botão (consulte **Alterar o botão principal** em [Tarefas comuns](#common-tasks)). |
| **Deixar 5 botões ou menos visíveis**                       | Todos são exibidos diretamente (o botão central e até quatro ao redor); não há menu «+».                                                                                                       |
| **Deixar mais de 5 botões visíveis**                        | O «+» ocupa o último espaço, então quatro botões são exibidos diretamente (o central e mais três), enquanto os restantes ficam ocultos atrás do botão de expansão «+».                         |

<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 conforme a quantidade de botões visíveis. <strong>Esquerda (7 botões):</strong> o botão principal, um arco de 1–3 e o «+», que contém os botões excedentes (4–7) numa coluna que sobe. <strong>Centro (5 botões):</strong> o mesmo arco, com uma coluna de botões excedentes mais curta (4–5) atrás do «+». <strong>Direita (4 botões):</strong> os quatro são exibidos diretamente e o «+» desaparece.</p></figcaption></figure>

{% hint style="info" %}
Os botões `1`/`2`/`3`/`4` começam ocultos. `showAll()` faz com que voltem a aparecer, mas isso deixa oito botões visíveis, então os de menor prioridade acabam atrás do «+». Para exibir um botão numerado diretamente no ecrã, mantenha a quantidade de botões visíveis 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 grava o componente na `RootEntity` da cena (onde o cliente o lê) e combina-o com o valor atual. Chame-as dentro de `main()` ou mais tarde: no nível superior de `index.ts` são executados antes de o conjunto predefinido ser escrito, que é ignorado.

**Alterar o botão principal** — faça com que o botão central grande execute uma ação diferente:

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

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

`setMainAction()` não ativa um botão. Para usar F ou um botão numerado como botão principal, ative-o também; caso contrário, continuará oculto:

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

export function main() {
	TouchScreenControls.showAll()
	TouchScreenControls.hide([
		InputAction.IA_ACTION_3,
		InputAction.IA_ACTION_4,
		InputAction.IA_ACTION_5,
		InputAction.IA_ACTION_6,
	])
	TouchScreenControls.setMainAction(InputAction.IA_SECONDARY)
}
```

**Ocultar o joystick ou a mira** — remova o joystick de movimento e/ou a mira e volte a mostrá-los com os respetivos métodos `show` correspondentes:

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

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

**Ocultar botões específicos** — indique as ações que pretende ocultar (as restantes sobem na hierarquia). A chamada acrescenta botões aos que já estão ocultos; assim, com o conjunto predefinido, o botão de interação fica como botão central e E ao lado:

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

export function main() {
	TouchScreenControls.hide([InputAction.IA_JUMP])
}
```

**Usar F ou os botões numerados** — estão ocultos por predefinição. Mostre todos os botões e, em seguida, oculte os que a sua scene não utiliza. `showAll()` também limpa os ícones personalizados. Se definir ícones com `createOrReplace`, faça-o depois de `showAll()` e antes de `hide()`, porque `createOrReplace` substitui toda a lista de botões, incluindo os ocultos:

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

export function main() {
	// Mostrar F e 1, manter 2–4 ocultos
	TouchScreenControls.showAll()
	TouchScreenControls.hide([InputAction.IA_ACTION_4, InputAction.IA_ACTION_5, InputAction.IA_ACTION_6])
}
```

**Oculte todos os botões, mostre todos os botões ou volte ao conjunto predefinido:**

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

export function main() {
	// Escolha uma opção:
	TouchScreenControls.hideAll()     // nenhum botão de gamepad
	TouchScreenControls.showAll()     // os oito botões
	TouchScreenControls.showDefault() // apenas salto, ponteiro e botão principal
}
```

Estes três métodos afetam apenas os botões do gamepad. Não restauram um joystick ou uma mira ocultos, nem alteram a ação principal; para isso, use `showJoystick()` / `showCrosshair()`  . `hideAll()` e `showDefault()` mantêm os ícones personalizados, mas `showAll()` remove-os.

**Substituir o ícone de um button** — para um controlo completo (ícones personalizados, várias alterações em simultâneo), escreva o Component diretamente em `engine.RootEntity`. Isto substitui o conjunto predefinido, pelo que todos os buttons que não indicar são apresentados; chame `showDefault()` em seguida para voltar a ocultar F e 1–4, mantendo os seus ícones:

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

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

Resumo das funções auxiliares:

| Função auxiliar         | O que faz                                                                                                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `setMainAction(action)` | Define a Action que o button central grande ativa.                                                                                                                                         |
| `hideJoystick()`        | Oculta o joystick virtual nativo.                                                                                                                                                          |
| `showJoystick()`        | Volta a mostrar o joystick virtual nativo.                                                                                                                                                 |
| `hideCrosshair()`       | Oculta a mira no ecrã.                                                                                                                                                                     |
| `showCrosshair()`       | Volta a mostrar a mira no ecrã.                                                                                                                                                            |
| `hide(actions)`         | Oculta os buttons do comando indicados, integrando-os na Config atual.                                                                                                                     |
| `hideAll()`             | Oculta todos os buttons do comando.                                                                                                                                                        |
| `showAll()`             | Mostra os oito buttons do comando, removendo todas as entradas individuais dos buttons, incluindo os ícones personalizados. **Não** afeta o joystick nem a mira.                           |
| `showDefault()`         | Repõe o conjunto predefinido: salto, Pointer e Action primária visíveis; Action secundária e Actions 3 a 6 ocultas. Mantém os ícones, o joystick, a mira e a Action principal inalterados. |

## Propriedades

Escreva estas propriedades diretamente quando usar `createOrReplace`. `hideJoystick`, `hideCrosshair`, `touchInputs` e, de cada entrada, o campo `hide` são obrigatórios no tipo TypeScript:

| 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) | Move esta ação para o início da pilha, tornando-a o botão central grande; os outros botões mantêm a ordem. Só são válidas ações de gamepad (ver abaixo). Se não for definido, a primeira ação visível (`IA_JUMP` por predefinição) fica em primeiro lugar. Não apresenta um botão oculto, incluindo F e 1–4. 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 que não incluir é apresentado com o respetivo glifo predefinido, incluindo os que começam ocultos.                                                                                                                                                                                 |

Cada entrada de `touchInputs` tem:

| 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) | Indica que botão no ecrã esta entrada configura.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `hide`        | *boolean*                                                                                                                                             | Oculta este botão. O valor predefinido é `false` (visível). É possível ocultar qualquer botão, **incluindo `IA_JUMP`** — os restantes sobem 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 cena. Use a variante `texture` com um `src` mapeado para conteúdo (uma imagem incluída na cena) — `{ tex: { $case: 'texture', texture: { src: 'images/grab.png' } } }`. Só são suportados caminhos para conteúdo da cena (não URLs externas nem texturas de avatar ou vídeo). No caso do botão de salto, isto substitui todos os estados dinâmicos (salto / salto duplo / planar). Se não for possível resolver o caminho, é usado o glifo integrado. |

## Que ações correspondem a que botões

Os valores de [`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 utilizados em [Entrada 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, mostrar o botão F, manter ocultos os botões numerados e atribuir 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,
		hideCrosshair: false,
		touchInputs: [
			// Esta lista substitui a lista predefinida, por isso os botões numerados têm de ser
			// listados aqui para permanecerem ocultos
			{ inputAction: InputAction.IA_SECONDARY, hide: false },
			{ 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,
				hide: false,
				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, the E and F buttons beside the interaction button, and the central jump button showing a custom banana icon"><figcaption><p>Resultado: joystick oculto, botão F visível, botões numerados ocultos (para o "+" desaparecer) e ícone do botão de salto substituído</p></figcaption></figure>

Para substituir totalmente 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

* [UI Input Binding](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/ui_input_binding.md)
* [Input 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.
