> 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/scene-editor/construir/ui-editor.md).

# Editor de UI

Projete visualmente a UI na tela da sua scene no Creator Hub, em um canvas em vez de no código.

O Editor de UI permite criar a interface apresentada no ecrã da sua cena, arrastando widgets para uma tela, em vez de escrever o código do layout manualmente. Ele cria ficheiros reais na sua cena, por isso tudo o que fizer aqui é UI normal do SDK7, que pode continuar a editar no código.

## Abrir

Use o seletor **2D** / **3D** na parte superior do painel esquerdo do editor. **3D** é a tela da cena que já conhece. **2D** é o Editor de UI.

![Seletor das abas 2D e 3D, com 3D selecionado.](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-fb4fb6e43151dd767062e73185c969e04d3a2549%2Fui-editor-mode-switch.webp?alt=media)

{% hint style="warning" %}
**📔 Nota**: o Editor de UI requer a versão `@dcl/sdk` 7.26.0 ou posterior na sua cena. Numa cena com uma versão anterior, a aba **2D** mostra o aviso **Editor de UI indisponível** em vez da tela, com um botão **Atualizar SDK** que atualiza a cena por si e um botão **Talvez mais tarde** para dispensar o aviso.
{% endhint %}

O Creator Hub lembra-se de se deixou uma cena em 2D ou 3D e volta a abri-la da mesma forma. Esta preferência é guardada por projeto e nunca é publicada com a sua cena.

Se estiver a usar o renderizador de cenas Bevy, mudar para **2D** coloca a cena em execução em pausa; voltar a **3D** retoma-a, caso estivesse em execução.

## Crie a sua primeira UI

1. Mude para a aba **2D** .
2. Clique em **Nova GUI**, no botão no centro da tela vazia ou no botão **+** junto a **GUIs** no painel esquerdo. Uma GUI é um componente de UI, guardado num ficheiro próprio.
3. Arraste um widget da paleta na parte inferior para a tela. **Ecrã inteiro** é um bom primeiro widget: cria uma raiz que cobre o ecrã. Em seguida, coloque outros widgets dentro dela.
4. Selecione um widget e defina as respetivas propriedades no painel direito.

Não existe um botão para guardar. O editor grava as alterações no disco à medida que trabalha, e o indicador à esquerda da barra de ferramentas mostra **Todas as alterações foram guardadas**.

![O Editor de UI no modo 2D: os painéis GUIs e Nodes à esquerda mostram uma GUI chamada MainUI, com um Container que contém um Label e um Button; a tela ao centro mostra o Container, com o Button selecionado e os controlos de redimensionamento à sua volta; a aba Properties à direita mostra a posição e o layout do Button; e a paleta de widgets aparece na parte inferior.](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-40492e70e382bf3d872ba4708513427abf6601a3%2Fui-editor-overview.webp?alt=media)

## Os painéis

* **À esquerda**: **GUIs**, a lista dos seus componentes de UI, e **Nodes**, a árvore do componente selecionado. Uma caixa de pesquisa filtra ambos. Passe o cursor sobre um nó para o bloquear, ocultar ou eliminar.
* **Direita**: um separador de **Propriedades** para o nó selecionado, e um separador de **Lógica** .
* **Inferior**: a paleta de widgets. Arraste um cartão para a tela para o adicionar.
* **Central**: a tela. Arraste os nós para os mover, use as pegas para os redimensionar e desloque a vista livremente com a roda do rato ou arrastando.

Dois grupos flutuantes de controlos encontram-se no canto inferior direito da tela:

* O grupo de **pré-visualização** ativa e desativa as guias do HUD para dispositivos móveis e as guias da área segura, e alterna entre a **pré-visualização para computador** e a **pré-visualização para dispositivos móveis**.
* O grupo de **zoom** tem um botão de menos e um de mais, bem como um campo de percentagem. Clique na percentagem para introduzir um nível de zoom exato entre 10 e 200 e, em seguida, prima Enter ou clique fora do campo para o aplicar, ou Escape para cancelar. O botão de mais é desativado quando o zoom chega aos 200%.

<div align="left"><img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-273ec384021ab5302407e39f93a3447f428cc330%2Fui-editor-left-panel.webp?alt=media" alt="Painel esquerdo do UI Editor, com os separadores 2D e 3D, uma caixa de pesquisa, a lista GUIs com MainUI e a árvore Nodes, que mostra um Container com um Label e um Button. A linha Button apresenta ícones para bloquear, ocultar e eliminar." width="220"> <img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-c1dec5a1959d553e46396edde5d2c883ed5dda7f%2Fui-editor-properties.webp?alt=media" alt="Separador Properties do UI Editor para um Button selecionado, com Visibility, Interaction States, uma secção Position com Constraints, Position e Z-Index, e uma secção Layout com Size, Min Size, Max Size, Padding e Margin." width="360"></div>

## Widgets

![Paleta de widgets na parte inferior do UI Editor, com cartões para Full Screen, Container, Image, Label, Button, Input e Dropdown.](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-01699808ce61d1d70370bd4f8757260dbd1f622d%2Fui-editor-palette.webp?alt=media)

A paleta agrupa os widgets em três categorias:

* **Contentores**: **Ecrã inteiro**, **Contentor**, **Imagem**
* **Texto**: **Etiqueta**, **Botão**
* **Entrada**: **Entrada**, **Lista pendente**

**Ecrã inteiro** é um contentor que preenche o elemento onde é colocado, o que o torna um bom ponto de partida para uma UI que deve cobrir o ecrã.

## Mover e redimensionar

A barra de ferramentas tem três modos:

* **Livre**: mover e redimensionar; é o modo de utilização geral.
* **Mover**: apenas arrastar.
* **Redimensionar**: apenas através das pegas.

As posições ajustam-se a uma grelha de 10 píxeis. Mantenha premida a tecla **Shift** enquanto arrasta para mover livremente, sem respeitar a grelha. A pequena seta junto aos botões das ferramentas abre uma caixa de verificação **Ajustar à grelha** que desativa completamente o ajuste à grelha.

![Barra de ferramentas 2D, com o indicador All changes saved, os botões para anular e refazer, as ferramentas Free, Move e Resize, e o menu pendente de ajuste à grelha aberto, com a opção Snap selecionada, seguido dos botões de reprodução e paragem.](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-23f6fe0d9251f744171a32fd0aec44199edaaace%2Fui-editor-toolbar.webp?alt=media)

## Layout: fluxo e posicionamento livre

Duas propriedades distintas determinam onde um nó fica. Compreendê-las evita muita confusão.

**Fluxo** é definido num **container** e determina como os seus filhos são organizados:

* **Livre**: os filhos ficam onde os colocar.
* **Linha** / **Linha inversa**: os filhos são organizados da esquerda para a direita ou da direita para a esquerda.
* **Coluna** / **Coluna inversa**: os filhos são empilhados de cima para baixo ou de baixo para cima.
* **Quebrar linha dos filhos**: permite que os filhos ocupem mais de uma linha quando não cabem numa só.

**Ignorar fluxo do layout** é definido num **filho** e determina se esse nó fica de fora da organização definida pelo elemento pai. Desativado, o elemento pai posiciona-o. Ativado, fixa-o manualmente com os valores de Anchor e Position.

Daqui resultam duas consequências:

* Arraste um widget para um container **Livre** e ele fica exatamente onde o largou.
* Arraste-o para um container com uma direção e ele passa a fazer parte do fluxo, ocupando o seu lugar na linha.

Ao mudar um container para **Livre** os filhos existentes ficam fixos onde estão, sem que nada salte de posição.

A raiz de uma GUI é sempre posicionada livremente.

## Outras propriedades que convém conhecer

* **Opacidade**: 100% é totalmente opaco; 0%, totalmente transparente. O valor predefinido é 100%.
* **Área de inserção da cena**: a parte do ecrã onde a GUI fica posicionada.

  * **Ecrã inteiro** usa toda a área do ecrã disponível para renderização.
  * **Área segura para interação** evita sobrepor-se à interface do próprio cliente, como o chat, o minimapa e os indicadores do HUD.
  * **Área segura do dispositivo** evita também obstruções físicas, como um entalhe ou as barras do sistema. Esta opção está disponível quando a canvas está na pré-visualização para dispositivos móveis.

  No código gerado pelo editor, estas três opções correspondem a `screenInset: 'none'`, `'interactable'` e `'device'`. Consulte [Área de inserção do ecrã](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-inset-area).

Se definir a largura e a altura da raiz de uma GUI em píxeis fixos, a canvas apresenta-a como uma prancheta com exatamente essas dimensões, em vez de a apresentar como um ecrã.

## Verifique a sua UI num telemóvel

Os controlos no canto inferior direito da canvas alternam a pré-visualização entre um ecrã de computador e um telemóvel. Na pré-visualização para dispositivos móveis, a canvas é apresentada dentro da moldura de um telemóvel, incluindo um entalhe, para que possa ver exatamente onde ficam os limites do ecrã.

Dois conjuntos de guias ajudam a posicionar elementos onde os jogadores os possam ver e alcançar:

* **Guias da área segura** delimitam a parte do ecrã à qual a sua GUI está confinada, correspondendo à **Inserção da cena** que selecionou. Enquanto a Inserção da cena for **Área segura do dispositivo** ou **Área segura interativa** o contorno está sempre visível, porque é aos seus limites que a GUI é recortada. Defina a Inserção da cena como **Ecrã inteiro** e pode ativar ou desativar o contorno com o botão do ícone de moldura.
* **Guias do HUD** mostram os controlos do próprio cliente móvel, como o joystick, os botões de salto e ação, a roda de emotes, o perfil, o chat e a bússola. Servem apenas como referência: não é possível selecioná-los nem movê-los. O botão do comando de jogo ativa-os e desativa-os; só aparece na pré-visualização para dispositivos móveis. Por predefinição, as guias são apresentadas quando a Inserção da cena está definida para uma área segura.

O conteúdo colocado fora da área segura não fica oculto: é desenhado para lá do contorno. Esse extravasamento é o aviso: no cliente real, o conteúdo ficaria por baixo do HUD do próprio jogo.

**Área segura interativa** deixa livre a coluna esquerda de controlos do cliente móvel, mas partilha a margem direita com a área do dispositivo. Por isso, os botões de ação no canto inferior direito são desenhados sobre essa área intencionalmente. Mantenha esses cantos desimpedidos. Consulte [Onde ficam os controlos do cliente](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/safe-area.md#where-the-client-controls-live).

{% hint style="warning" %}
**📔 Nota**: estas guias são apenas uma aproximação no editor. As áreas reais são comunicadas pelo cliente durante a execução e variam consoante o dispositivo, por isso confirme sempre num telemóvel real. Consulte [Pré-visualizar em dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/preview-on-mobile.md).
{% endhint %}

## Personalizar os controlos para dispositivos móveis

No cliente móvel, os jogadores movem-se e executam ações através de um conjunto de controlos nativos no ecrã: um joystick, uma mira e uma fila de botões de ação. A entrada **MobileHUD** permite ajustar esse HUD sem escrever código e mostra o resultado na tela à medida que faz alterações.

Quando a cena tiver pelo menos uma GUI, **MobileHUD** aparece como a primeira linha da lista **GUIs** , acima das suas próprias GUIs. Selecione-a para abrir o respetivo painel à direita.

As três caixas de verificação no topo ocultam partes inteiras do HUD:

* **Ocultar joystick**: remove o joystick de movimento.
* **Ocultar mira**: remove a mira.
* **Ocultar ações de entrada**: remove todos os botões de ação de uma só vez.

Abaixo, a secção **Ações de entrada** apresenta os oito botões, pela ordem em que ocupam as posições no ecrã:

| Ação                                  | Botão no ecrã                            |
| ------------------------------------- | ---------------------------------------- |
| `IA_JUMP`                             | O grande botão central, por predefinição |
| `IA_POINTER`                          | O botão de interação                     |
| `IA_PRIMARY (E)`                      | O botão E                                |
| `IA_SECONDARY (F)`                    | O botão F                                |
| `IA_ACTION_3 (1)` a `IA_ACTION_6 (4)` | Os botões numerados                      |

Cada linha oferece três opções:

* **Principal**: um botão de opção que define esta ação como o botão central grande. `IA_JUMP` é Principal por predefinição, e só pode haver uma ação Principal de cada vez.
* Um **ícone de olho** que mostra ou oculta esse botão. Quando oculta um botão, os botões abaixo sobem para preencher o espaço.
* **Ícone personalizado**: substitui o glifo do botão por uma imagem `.png`, `.jpg` ou `.jpeg` da sua Scene.

Neste painel, todos os botões começam visíveis e `IA_JUMP` é o botão principal.

{% hint style="warning" %}
**📔 Nota**: uma Scene que nunca interage com o HUD mostra apenas três botões: saltar, pointer e principal. O painel só grava `src/mobile-hud.ts` quando altera algo, por isso, se não tocar no painel, mantém-se essa predefinição. Assim que o ficheiro existe, o respetivo código substitui o conjunto predefinido pelo que configurar aqui. Por exemplo, ocultar apenas o joystick também coloca os cinco botões adicionais no ecrã do jogador. Oculte os botões que a sua Scene não utiliza. Consulte [O que é apresentado por predefinição](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/touch-screen-controls.md#what-shows-by-default).
{% endhint %}

{% hint style="info" %}
**💡 Sugestão**: com mais de cinco botões visíveis, os últimos ficam atrás de um botão de alternância de excesso «+». Oculte botões suficientes das posições superiores para que os restantes sejam apresentados diretamente. Consulte [Controlos no ecrã](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/touch-screen-controls.md#how-the-button-layout-works) para saber como são preenchidas as posições.
{% endhint %}

### O ficheiro que é criado

As suas alterações são gravadas em `src/mobile-hud.ts`, que exporta uma função `setupMobileHud()` baseada no componente [`TouchScreenControls`](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/touch-screen-controls.md) do SDK:

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

export function setupMobileHud() {
  TouchScreenControls.createOrReplace(engine.RootEntity, {
    hideJoystick: true,
    hideCrosshair: false,
    mainAction: InputAction.IA_PRIMARY,
    touchInputs: [
      { inputAction: InputAction.IA_ACTION_3, hide: true },
    ],
  })
}
```

O editor também adiciona a importação e a chamada ao seu ficheiro `src/index.ts`:

```ts
import { setupMobileHud } from './mobile-hud'

setupMobileHud()
```

O ficheiro só existe enquanto tiver algo a definir. Se repuser tudo nas predefinições ou eliminar o último elemento da GUI, o Creator Hub elimina `src/mobile-hud.ts` e remove novamente essas duas linhas.

{% hint style="warning" %}
**📔 Nota**: quando **MobileHUD** está selecionado, a paleta de widgets fica desativada e os controlos de pré-visualização ficam ocultos, uma vez que não há nada para colocar e o HUD é apenas para dispositivos móveis. Selecione uma das suas próprias GUIs para os voltar a mostrar.
{% endhint %}

## Onde ficam os ficheiros

O Editor de UI edita os ficheiros de origem reais da sua cena. Não existe um formato de gravação separado.

* Cada GUI é um ficheiro `.tsx` na pasta `src/ui/`.
* `src/ui/index.tsx` é gerado pelo editor para os reunir. Não o edite manualmente.
* `src/mobile-hud.ts` contém os seus [controlos móveis](#customize-the-mobile-controls), caso tenha alterado algum. Fica fora de `src/ui/` propositadamente, para nunca ser tratado como uma GUI.

Se a sua cena tiver um único ficheiro `src/ui.tsx` mais antigo, o editor cria uma cópia de segurança com o nome `src/ui.tsx.bak` na primeira vez que abrir o Editor de UI.

Como estes são ficheiros comuns, pode abri-los no seu [editor de código](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/expandir-com-codigo/overview.md) a qualquer momento. Consulte [UI](https://github.com/decentraland/docs/tree/main/creator/sdk7/2d-ui/README.md) para saber o que faz o código subjacente.

## Código que o editor não consegue editar

O editor reconhece uma estrutura específica de código de UI. Um nó escrito de outra forma — por exemplo, criado dentro de um ciclo ou de uma condição, ou que use um componente personalizado ou propriedades propagadas — é apresentado na tela como um bloco cinzento com o emblema **não padrão, edite no código**  . Os elementos filhos não são apresentados; em vez disso, edite o nó no código.

O resto da GUI à sua volta continua a funcionar normalmente.

## Páginas relacionadas

* [UI](https://github.com/decentraland/docs/tree/main/creator/sdk7/2d-ui/README.md): escrever a UI da cena em código.
* [Combinar com código](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/expandir-com-codigo/overview.md): abrir a sua cena num editor de código.
* [Entidades e componentes](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/construir/components.md): a parte 3D do editor.


---

# 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/scene-editor/construir/ui-editor.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.
