> 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 UI Editor permite-te construir a interface no ecrã da tua scene arrastando widgets para um canvas, em vez de escreveres código de layout à mão. Ele escreve ficheiros reais na tua scene, por isso tudo o que criares aqui é UI normal do SDK7 que podes continuar a editar em código.
## Abrir
Use o **2D** / **3D** interruptor no topo do painel esquerdo do editor. **3D** é o canvas da scene que já conheces. **2D** é o UI Editor.
{% hint style="warning" %}
**📔 Nota**: O UI Editor precisa de `@dcl/sdk` versão 7.26.0 ou mais recente na tua scene. Numa scene mais antiga, o **2D** separador mostra um **UI Editor Indisponível** aviso em vez do canvas, com um **Atualizar SDK** botão que atualiza a scene por ti e um **Talvez mais tarde** botão para o dispensar.
{% endhint %}
O Creator Hub lembra-se se deixaste uma scene em 2D ou 3D e volta a abri-la da mesma forma. Isto é guardado por projeto e nunca é publicado com a tua scene.
Se estiveres a usar o renderizador de scene Bevy, mudar para **2D** pausa a scene em execução, e voltar para **3D** retoma-a se já estava em execução antes.
## Cria a tua primeira UI
1. Muda para o **2D** separador.
2. Clica em **New GUI**, quer seja o botão no centro do canvas vazio ou o **+** ao lado de **GUIs** no painel esquerdo. Uma GUI é um componente de UI, guardado no seu próprio ficheiro.
3. Arrasta um widget da paleta na parte inferior para o canvas. **Full Screen** é um bom primeiro widget; dá-te uma root que cobre o ecrã. Depois, solta outros widgets dentro dela.
4. Seleciona um widget e define as suas propriedades no painel direito.
Não há botão de guardar. O editor escreve as tuas alterações para o disco à medida que avanças, e o distintivo à esquerda da barra de ferramentas diz **Todas as alterações guardadas**.
## Os painéis
* **Esquerda**: **GUIs**, a lista dos teus componentes de UI, e **Nodes**, a árvore da selecionada. Uma caixa de pesquisa filtra ambos. Passa o cursor sobre um node para o bloquear, ocultar ou eliminar.
* **Direita**: uma opção de renderizador zIndex decide qual módulo de UI é desenhado na frente de qual. Sem ela, os módulos se empilham na ordem em que aparecem pela primeira vez, com a UI principal ao fundo. Veja **Properties** separador para o node selecionado, e um **Logic** separador.
* **Inferior**: a paleta de widgets. Arrasta um cartão para o canvas para o adicionar.
* **Centro**: o canvas. Arrasta nodes para os mover, usa as alças para redimensionar e faz pan livremente com a roda do rato ou arrastando.
Dois grupos flutuantes de controlos ficam no canto inferior direito do canvas:
* O **pré-visualização** grupo alterna os guias da HUD móvel e os guias da área segura, e alterna entre **pré-visualização Desktop** e **pré-visualização Mobile**.
* O **zoom** grupo tem um botão de menos e um de mais, e um campo de percentagem. Clica na percentagem para escreveres um nível de zoom exato entre 10 e 200, depois prime Enter ou clica fora para o aplicar, ou Escape para cancelar. O botão de mais desliga-se quando chegas a 200%.
## Widgets
A paleta agrupa os widgets em três categorias:
* **Containers**: **Full Screen**, **Container**, **Image**
* **Text**: **Label**, **Button**
* **Input**: **Input**, **Dropdown**
**Full Screen** é um container que preenche tudo aquilo em que é colocado, o que o torna um bom ponto de partida para uma UI que deva cobrir o ecrã.
## Mover e redimensionar
A barra de ferramentas tem três modos de ferramentas:
* **Free**: mover e redimensionar, o modo de uso geral.
* **Move**: apenas arrastar.
* **Resize**: apenas alças.
As posições ajustam-se a uma grelha de 10 pixels. Mantém premido **Shift** enquanto arrastas para mover livremente, ignorando a grelha. A pequena seta ao lado dos botões das ferramentas abre um **Snap** checkbox que desativa totalmente o ajuste.
## Layout: fluxo e posicionamento livre
Duas propriedades separadas decidem onde um node acaba por ficar. Perceber isto evita muita confusão.
**Flow** é definido num **container** e decide como organiza os seus children:
* **Free**: os children ficam onde os colocares.
* **Row** / **Row reverse**: os children são dispostos da esquerda para a direita, ou da direita para a esquerda.
* **Column** / **Column reverse**: os children são empilhados de cima para baixo, ou de baixo para cima.
* **Wrap children**: permite que os children passem para mais do que uma linha quando não cabem.
**Ignore Layout Flow** é definido num **child** e decide se esse node individual opta por sair da organização do seu pai. Desligado, o pai posiciona-o. Ligado, fixas-lo tu com valores de Anchor e Position.
Duas consequências resultam disto:
* Larga um widget dentro de um **Free** container e ele fica exatamente onde o largaste.
* Larga-o num container com uma direção e ele entra no fluxo, tomando o seu lugar na linha.
Mudar um container para **Free** fixa os seus children existentes onde já estão, por isso nada salta.
A root de uma GUI é sempre posicionada livremente.
## Outras propriedades que vale a pena conhecer
* **Opacity**: 100% é totalmente opaco, 0% totalmente transparente. O valor predefinido é 100%.
* **Scene Inset**: em que parte do ecrã a GUI fica.
* **Full Screen** usa todo o ecrã renderizável.
* **Interactable Safe Area** mantém-se afastada da interface própria do client, como chat, o minimapa e os indicadores da HUD.
* **Device Safe Area** também evita obstruções físicas como um notch ou barras do sistema. Esta opção é oferecida quando o canvas está em mobile preview.
No código que o editor escreve, estas três escolhas tornam-se `screenInset: 'none'`, `'interactable'` e `'device'`. Veja [Área de inserção do ecrã](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-inset-area).
Se deres à root de uma GUI uma largura e uma altura em pixels fixos, o canvas enquadra-a como um artboard exatamente desse tamanho, em vez de como um ecrã.
## Ver a tua UI num telemóvel
Os controlos no canto inferior direito do canvas alternam a pré-visualização entre um ecrã de desktop e um telemóvel. Na mobile preview, o canvas é desenhado dentro de uma moldura de telemóvel, completa com notch, para poderes ver onde os limites do ecrã realmente ficam.
Dois conjuntos de guias ajudam-te a colocar as coisas onde os jogadores as podem ver e alcançar:
* **Guias da área segura** contornam a parte do ecrã à qual a tua GUI está confinada, correspondendo à **Scene Inset** que escolheste. Enquanto o Scene Inset está **Device Safe Area** ou **Interactable Safe Area** o contorno está sempre ligado, porque é a área à qual a GUI é recortada. Define o Scene Inset para **Full Screen** e podes ligar ou desligar o contorno com o botão do ícone de moldura.
* **Guias da HUD** desenham os controlos próprios do client móvel, como o joystick, os botões de saltar e de ação, a roda de emotes, o perfil, o chat e a bússola. Servem apenas de referência; não os podes selecionar nem mover. O botão do comando de jogo liga-os e desliga-os, só aparece em mobile preview, e os guias aparecem por predefinição quando o Scene Inset é uma área segura.
O conteúdo colocado fora da área segura não fica oculto; é desenhado para além do contorno. Esse excedente é o aviso: no client real ficaria por baixo da HUD própria do jogo.
**Interactable Safe Area** limpa a coluna esquerda de controlos do client 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 ela de propósito. Mantém esses cantos livres. Ver [Onde vivem os controlos do client](/creator/content-creator-pt/criar-para-mobile/desenvolver/safe-area.md#where-the-client-controls-live).
{% hint style="warning" %}
**📔 Nota**: Estes guias são apenas uma aproximação para o editor. As áreas reais são reportadas pelo client em runtime e variam consoante o dispositivo, por isso confirma sempre num telemóvel real. Ver [Prévia no mobile](/creator/content-creator-pt/criar-para-mobile/desenvolver/preview-on-mobile.md).
{% endhint %}
## Personalize os controles móveis
No client móvel, os jogadores movem-se e agem através de um conjunto de controlos nativos no ecrã: um joystick, uma mira e uma linha de botões de ação. A **MobileHUD** entrada permite-te reorganizar essa HUD sem escrever código, e mostra o resultado no canvas à medida que avanças.
Quando a tua scene tiver pelo menos uma GUI, **MobileHUD** aparece como a primeira linha da **GUIs** lista, acima das tuas próprias GUIs. Seleciona-o para abrir o seu painel à direita.
Três checkboxes no topo ocultam partes inteiras da HUD:
* **Hide Joystick**: remove o stick de movimento.
* **Hide Crosshair**: remove a mira de pontaria.
* **Hide Input Actions**: remove todos os botões de ação de uma vez.
Abaixo deles, a secção **Input Actions** lista os oito botões, pela ordem em que preenchem os espaços no ecrã:
| Action | Button on screen |
| ---------------------------------------- | ---------------------------------------- |
| `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)` para `IA_ACTION_6 (4)` | Os botões numerados |
Cada linha dá-te três coisas:
* **Main**: um botão de opção que faz desta ação o grande botão central. `IA_JUMP` é Main por predefinição, e só uma ação pode ser Main de cada vez.
* Um **ícone de olho** que mostra ou oculta esse botão. Quando ocultas um, os botões inferiores sobem para preencher a lacuna.
* **Custom Icon**: substitui o glyph do botão por uma `.png`, `.jpg` ou `.jpeg` imagem da tua scene.
Por predefinição nada está oculto e `IA_JUMP` é o botão principal, que é exatamente o que os jogadores obtêm numa scene que não mexe na HUD.
{% hint style="info" %}
**💡 Dica**: Os botões numerados normalmente ficam atrás de um alternador de overflow "+". Oculta botões superiores suficientes e eles aparecem diretamente. Ver [Controles na tela](/creator/content-creator-pt/scenes-sdk7/interatividade/touch-screen-controls.md#how-the-button-layout-works) para perceber como os espaços são preenchidos.
{% endhint %}
### O ficheiro que escreve
As tuas alterações são escritas em `src/mobile-hud.ts`, que exporta uma `setupMobileHud()` função construída com base no [`TouchScreenControls`](/creator/content-creator-pt/scenes-sdk7/interatividade/touch-screen-controls.md) componente da 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 o import e a chamada ao teu `src/index.ts`:
```ts
import { setupMobileHud } from './mobile-hud'
setupMobileHud()
```
O ficheiro só existe enquanto tiver algo a dizer. Se repuseres tudo para o valor predefinido, ou eliminares a tua última GUI, o Creator Hub elimina `src/mobile-hud.ts` e remove essas duas linhas novamente.
{% hint style="warning" %}
**📔 Nota**: Enquanto **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 a HUD é apenas mobile. Seleciona uma das tuas próprias GUIs para os voltares a ter.
{% endhint %}
## Para onde vão os ficheiros
O UI Editor edita os ficheiros reais de origem da tua scene. Não existe um formato guardado separado.
* Cada GUI é um ficheiro `.tsx` sob `src/ui/`.
* `src/ui/index.tsx` é gerado pelo editor para os reunir. Não o edites à mão.
* `src/mobile-hud.ts` contém os teus [controlos móveis](#customize-the-mobile-controls), se alteraste algum. Fica fora de `src/ui/` de propósito, para nunca ser tratado como uma GUI.
Se a tua scene tiver um ficheiro único e mais antigo `src/ui.tsx` o editor faz uma cópia de segurança como `src/ui.tsx.bak` da primeira vez que abres o UI Editor.
Como estes são ficheiros normais, podes abri-los no teu [editor de código](/creator/content-creator-pt/scene-editor/expandir-com-codigo/overview.md) a qualquer momento. Ver [UI](https://github.com/decentraland/docs/tree/main/creator/sdk7/2d-ui/README.md) para saberes o que o código subjacente faz.
## Código que o editor não consegue editar
O editor entende uma determinada forma de código de UI. Um node escrito de outra maneira, por exemplo construído dentro de um loop ou de uma condicional, ou usando um componente personalizado ou spread props, é desenhado no canvas como um bloco cinzento com um distintivo **não standard, editar em código** . Os seus children não são mostrados, e em vez disso editas-no em 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 UI da scene em código.
* [Combinar com código](/creator/content-creator-pt/scene-editor/expandir-com-codigo/overview.md): abre a tua scene num editor de código.
* [Entities and Components](/creator/content-creator-pt/scene-editor/construir/components.md): o lado 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=&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.
