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

# Controlos no Ecrã

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

No client móvel, os jogadores interagem com a sua scene por meio de um conjunto de controles nativos na tela — um joystick virtual, uma mira e um gamepad de botões. O `para ocultar os controlos nativos e substituí-los pela sua própria UI tátil — a forma recomendada de disponibilizar um esquema de controlos totalmente personalizado.` componente permite que sua scene reformule esse HUD: reduza a desordem, oculte o joystick ou a mira, altere o que o grande botão central faz, troque o glifo 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-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 reverte para os padrões (nada oculto, pulo como botão central) no momento em que ele sair — então as scenes que não o usam não são afetadas. Ele afeta apenas plataformas com controles nativos na tela: no desktop ele não faz nada 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 **visíveis** botões preenchem essas posições do topo 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 o pulo) | Cada botão de menor prioridade sobe para preencher o espaço. Oculte o pulo e `IA_POINTER` assume o lugar central.                              |
| **Não altere a pilha**                                 | O primeiro botão (`IA_JUMP`) é o grande botão central; os botões seguintes preenchem os slots ao redor.                                        |
| **Defina um botão principal** com `mainAction`         | Essa ação vai para a frente e se torna o botão central; todos os outros botões mantêm sua ordem normal.                                        |
| **Defina um botão principal que também esteja oculto** | A ocultação vence — o botão permanece oculto.                                                                                                  |
| **Deixe 5 ou menos botões visíveis**                   | Todos eles aparecem diretamente (o botão central mais até quatro ao redor); não há menu "+".                                                   |
| **Deixe 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 restante fica atrás do alternador de excesso "+". |

<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 contagem visível. <strong>Esquerda (7 botões):</strong> o botão principal, um arco de 1–3 e o "+" segurando o excesso (4–7) em uma coluna que sobe para cima. <strong>Centro (5 botões):</strong> o mesmo arco, com uma coluna de excesso 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" %}
É assim também que você exibe os `1`/`2`/`3`/`4` botões, que de outra forma ficariam escondidos atrás do "+": oculte botões suficientes de maior prioridade para reduzir a contagem visível para cinco ou menos, e eles aparecerão diretamente.
{% endhint %}

## Tarefas comuns

`para ocultar os controlos nativos e substituí-los pela sua própria UI tátil — a forma recomendada de disponibilizar um esquema de controlos totalmente personalizado.` traz um conjunto de helpers práticos. Cada um grava o componente no `RootEntity` da scene (onde o client o lê) e faz a mesclagem com o valor atual, então você pode chamá-los de qualquer lugar.

**Alterar o botão principal** — faça o grande botão central disparar uma ação diferente:

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

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

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

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

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

**Ocultar botões específicos** — passe as ações que você quer remover (o restante sobe em cascata):

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

**Ocultar ou mostrar 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.

**Substituir o ícone de um botão** — para controle total (ícones personalizados, várias alterações ao mesmo tempo), 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:

| Helper                  | O que faz                                                                                             |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `setMainAction(action)` | Define qual ação o grande botão central dispara.                                                      |
| `hideJoystick()`        | Oculta o joystick virtual nativo.                                                                     |
| `showJoystick()`        | Mostra novamente o joystick virtual nativo.                                                           |
| `hideCrosshair()`       | Oculta a mira / retículo na tela.                                                                     |
| `showCrosshair()`       | Mostra novamente a mira / retículo na tela.                                                           |
| `hide(actions)`         | Oculta os botões de gamepad fornecidos (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 **afeta** o joystick/a mira. |

## Propriedade

Escreva isso diretamente quando usar `createOrReplace`:

| Tipo            | Descrição                                                                                                             | actions                                                                                                                                                                                                                                                                                                              |
| --------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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/button-events/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 de 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` entrada tem:

| Campo         | Descrição                                                                                                             | actions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputAction` | [*InputAction*](/creator/content-creator-pt/scenes-sdk7/interatividade/button-events/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`** — o restante sobe em cascata para preencher o lugar dele.                                                                                                                                                                                                                                                                                                                                     |
| `icon`        | [*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 variante `texture` com um `src` mapeado para conteúdo (uma imagem incluída na sua scene) — `{ tex: { $case: 'texture', texture: { src: 'images/grab.png' } } }`. Apenas caminhos de conteúdo da scene são suportados (não URLs externos, avatar ou texturas de vídeo). Para o botão de pulo isso substitui todos os seus estados dinâmicos (pulo / pulo duplo / deslizamento). Se o caminho não puder ser resolvido, o glifo integrado é usado. |

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

O [`InputAction`](/creator/content-creator-pt/scenes-sdk7/interatividade/button-events/click-events.md#pointer-buttons) os valores aqui são os mesmos usados em toda [Input on mobile](/creator/content-creator-pt/criar-para-dispositivos-moveis/desenvolver/input-on-mobile.md) e [para a lista completa de](/creator/content-creator-pt/scenes-sdk7/interatividade/button-events/click-events.md). Estas são as ações que se mapeiam para os 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 se 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 pulo 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 pulo com novo ícone</p></figcaption></figure>

Para substituir os controles nativos por completo, oculte-os aqui e construa seus próprios botões de toque com [UI Input Binding](/creator/content-creator-pt/scenes-sdk7/ui-2d/ui_input_binding.md).

## Relacionados

* [UI Input Binding](/creator/content-creator-pt/scenes-sdk7/ui-2d/ui_input_binding.md)
* [Input on mobile](/creator/content-creator-pt/criar-para-dispositivos-moveis/desenvolver/input-on-mobile.md)
* [para a lista completa de](/creator/content-creator-pt/scenes-sdk7/interatividade/button-events/click-events.md)
* [Detectar a plataforma pelo código](/creator/content-creator-pt/criar-para-dispositivos-moveis/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 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-pt/scenes-sdk7/interatividade/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.