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 que você construa a interface na tela da sua cena arrastando widgets para um canvas, em vez de escrever o código de layout manualmente. Ele grava arquivos reais na sua cena, então tudo o que você criar aqui é UI normal do SDK7 que você pode continuar editando em código.

Abra-o

Use o 2D / 3D alternador no topo do painel esquerdo do editor. 3D é o canvas da cena que você já conhece. 2D é o Editor de UI.

O alternador das abas 2D e 3D, com 3D selecionado.

📔 Observação: O Editor de UI precisa @dcl/sdk da versão 7.26.0 ou mais recente na sua cena. Em uma cena mais antiga, a 2D aba mostra um Editor de UI indisponível aviso em vez do canvas, com um Atualizar SDK botão que atualiza a cena para você e um Talvez mais tarde botão para dispensá-lo.

O Creator Hub lembra se você deixou uma cena em 2D ou 3D e a reabre do mesmo jeito. Isso é armazenado por projeto e nunca é publicado com a sua cena.

Se você estiver usando o renderizador de cena Bevy, mudar para 2D pausa a cena em execução, e voltar para 3D a retoma se ela estava em execução antes.

Crie sua primeira UI

1. Mude para o 2D aba.

2. Clique em Nova GUI, seja o botão no meio do canvas vazio ou o + ao lado de GUIs no painel esquerdo. Uma GUI é um componente de UI, armazenado em seu próprio arquivo.

3. Arraste um widget da paleta na parte inferior para o canvas. Tela cheia é um bom primeiro widget; ele fornece uma raiz que cobre a tela. Depois solte outros widgets dentro dele.

4. Selecione um widget e defina suas propriedades no painel direito.

Não há botão de salvar. O editor grava suas alterações em disco à medida que você trabalha, e o selo à esquerda da barra de ferramentas mostra Todas as alterações salvas.

O Editor de UI no modo 2D: os painéis GUIs e Nodes à esquerda listam uma GUI chamada MainUI com um Container contendo um Label e um Button, o canvas no meio mostra o container com o Button selecionado e alças de redimensionamento ao redor dele, a aba Properties à direita mostra a posição e o layout do Button, e a paleta de widgets percorre a parte inferior.

Os painéis

• Esquerda: GUIs, a lista dos seus componentes de UI, e Nodes, a árvore do selecionado. Uma caixa de pesquisa filtra ambos. Passe o mouse sobre um nó para bloquear, ocultar ou excluir.

• Direita: um Propriedades aba do nó selecionado, e uma Logic aba.

• Inferior: a paleta de widgets. Arraste um cartão para o canvas para adicioná-lo.

• Centro: o canvas. Arraste os nós para movê-los, use as alças para redimensionar e navegue livremente com a roda do mouse ou arrastando.

Dois grupos flutuantes de controles ficam no canto inferior direito do canvas:

• O preview grupo alterna os guias do 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 indicador em porcentagem. Clique na porcentagem para redefinir a visão.

O painel esquerdo do Editor de UI, com as abas 2D e 3D, uma caixa de pesquisa, a lista GUIs contendo MainUI e a árvore Nodes mostrando um Container com um Label e um Button, a linha do Button mostrando ícones de bloquear, ocultar e excluir.

A aba Properties do Editor de UI para um Button selecionado, com Visibility, Interaction States, uma seção Position com Constraints, Position e Z-Index, e uma seção Layout com Size, Min Size, Max Size, Padding e Margin.

Widgets

A paleta de widgets ao longo da parte inferior do Editor de UI, com cartões para Full Screen, Container, Image, Label, Button, Input e Dropdown.

A paleta agrupa os widgets em três categorias:

• Containers: Tela cheia, Container, Image

• Text: Label, Button

• Input: Input, Dropdown

Tela cheia é um container que preenche qualquer coisa dentro da qual ele é colocado, o que o torna um bom ponto de partida para uma UI que deve cobrir a tela.

Mover e redimensionar

A barra de ferramentas tem três modos de ferramenta:

• Free: mover e redimensionar, o modo de uso geral.

• Mover: apenas arrastar.

• Redimensionar: apenas alças.

As posições aderem a uma grade de 10 pixels. Segure Shift enquanto arrasta para mover livremente, ignorando a grade. A pequena seta ao lado dos botões de ferramenta abre uma caixa de seleção Snap que desativa completamente o ajuste.

A barra de ferramentas 2D, com o selo Todas as alterações salvas, desfazer e refazer, as ferramentas Free, Move e Resize, e o menu suspenso Snap aberto mostrando uma opção Snap marcada, seguido dos botões de play e stop.

Layout: flow e posicionamento livre

Duas propriedades separadas decidem onde um nó acaba ficando. Entender isso direito evita muita confusão.

Flow é definido em um container e decide como ele organiza seus filhos:

• Free: os filhos ficam onde você os colocou.

• Row / Row reverse: os filhos são dispostos da esquerda para a direita, ou da direita para a esquerda.

• Column / Column reverse: os filhos são empilhados de cima para baixo, ou de baixo para cima.

• Quebrar filhos: permite que os filhos continuem em mais de uma linha quando não couberem.

Ignorar fluxo do layout é definido em um filho e decide se esse nó individual sai da organização do pai. Desativado, o pai o posiciona. Ativado, você o fixa manualmente com valores de Anchor e Position.

Duas consequências decorrem disso:

• Solte um widget em um Free container e ele permanece exatamente onde você o soltou.

• Solte-o em um container com uma direção e ele entra no fluxo, ocupando seu lugar na linha.

Ao mudar um container para Free seus filhos existentes ficam fixados onde já estão, então nada salta.

A raiz de uma GUI é sempre posicionada livremente.

Outras propriedades que valem a pena conhecer

• Opacidade: 100% é totalmente opaco, 0% totalmente transparente. O padrão é 100%.

• Scene Inset: em que parte da tela a GUI fica.

  • Tela cheia usa toda a tela renderizável.

  • Área Segura Interagível mantém-se longe da própria interface do cliente, como chat, minimapa e indicadores do HUD.

  • Área Segura do Dispositivo também evita obstruções físicas, como um notch ou barras do sistema. Essa opção é oferecida quando o canvas está em pré-visualização mobile.

  No código que o editor escreve, essas três opções se tornam screenInset: 'none', 'interactable' e 'device'. Veja Área de screenInset.

Se você der à raiz de uma GUI uma largura e uma altura em pixels fixos, o canvas a enquadra como um artboard exatamente desse tamanho, em vez de como uma tela.

Verifique sua UI em um telefone

Os controles no canto inferior direito do canvas alternam a pré-visualização entre uma tela de desktop e um telefone. Na pré-visualização mobile, o canvas é desenhado dentro de uma moldura de telefone, completa com notch, para que você possa ver onde as bordas da tela realmente ficam.

Dois conjuntos de guias ajudam a colocar as coisas onde os jogadores podem vê-las e alcançá-las:

• Guias da área segura contornam a parte da tela à qual sua GUI fica confinada, correspondendo à Scene Inset que você escolheu. Enquanto o Scene Inset estiver Área Segura do Dispositivo ou Área Segura Interagível o contorno fica sempre ligado, porque é a ele que a GUI é recortada. Defina o Scene Inset como Tela cheia e você pode ligar ou desligar o contorno com o botão de ícone de moldura.

• Guias do HUD desenham os próprios controles do cliente mobile, como o joystick, os botões de pulo e ação, a roda de emotes, o perfil, o chat e a bússola. Eles servem apenas como referência; você não pode selecioná-los ou movê-los. O botão do controle de jogo liga e desliga esses elementos, ele só aparece na pré-visualização mobile, e as guias aparecem por padrão quando o Scene Inset é uma área segura.

O conteúdo colocado fora da área segura não fica oculto; ele é desenhado além do contorno. Esse excesso é o aviso: no cliente real ele ficaria sob o HUD do próprio jogo.

Área Segura Interagível limpa a coluna esquerda de controles do cliente mobile, mas compartilha sua borda direita com a área do dispositivo, então os botões de ação no canto inferior direito são desenhados sobre ela por design. Mantenha esses cantos livres. Veja Onde vivem os controlos do cliente.

📔 Observação: Essas guias são apenas uma aproximação para o editor. As áreas reais são informadas pelo cliente em runtime e variam conforme o dispositivo, então sempre confirme em um telefone real. Veja Prévia no mobile.

Personaliza os controlos móveis

No cliente mobile, os jogadores se movem e agem por meio de um conjunto de controles nativos na tela: um joystick, uma mira e uma fileira de botões de ação. A MobileHUD entrada permite que você redesenhe esse HUD sem escrever código e mostra o resultado no canvas conforme você trabalha.

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

Três caixas de seleção no topo ocultam partes inteiras do HUD:

• Ocultar joystick: remove o stick de movimento.

• Ocultar mira: remove a mira de apontamento.

• Ocultar ações de entrada: remove todos os botões de ação de uma vez.

Abaixo delas, a Ações de entrada seção lista os oito botões, na ordem em que ocupam os espaços na tela:

Action	Botão na tela
IA_JUMP	O grande botão central, por padrã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) como IA_ACTION_6 (4)	Os botões numerados

Cada linha lhe dá três coisas:

• Principal: um botão de opção que faz desta ação o grande botão central. IA_JUMP é Principal por padrão, e apenas uma ação pode ser Principal por vez.

• Um ícone de olho que mostra ou oculta esse botão. Quando você oculta um, os botões abaixo sobem para preencher o espaço.

• Ícone personalizado: substitui o símbolo do botão por uma .png, .jpg ou .jpeg imagem da sua cena.

Por padrão, nada fica oculto e IA_JUMP é o botão principal, que é exatamente o que os jogadores recebem em uma cena que não mexe no HUD.

💡 Dica: Normalmente, os botões numerados ficam atrás de um alternador de expansão +. Oculte botões suficientes dos níveis superiores e eles aparecem diretamente. Veja On-screen Controls para saber como os espaços se preenchem.

O arquivo que ele escreve

Suas alterações são gravadas em src/mobile-hud.ts, que exporta uma setupMobileHud() função construída sobre o TouchScreenControls component:

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 src/index.ts:

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

setupMobileHud()

O arquivo só existe enquanto tiver algo a dizer. Se você devolver tudo aos valores padrão, ou excluir sua última GUI, o Creator Hub exclui src/mobile-hud.ts e remove essas duas linhas novamente.

📔 Observação: Enquanto MobileHUD estiver selecionado, a paleta de widgets fica desativada e os controles de pré-visualização ficam ocultos, já que não há nada para colocar e o HUD é apenas mobile. Selecione uma de suas próprias GUIs para trazê-los de volta.

Onde os arquivos vão

O Editor de UI edita os arquivos de origem reais da sua cena. Não há um formato salvo separado.

• Cada GUI é um .tsx arquivo em src/ui/.

• src/ui/index.tsx é gerado pelo editor para reuni-los. Não edite-o manualmente.

• src/mobile-hud.ts contém seus controles mobile, se você alterou algum. Ele fica fora de src/ui/ de propósito, então nunca é tratado como uma GUI.

Se sua cena tiver um único src/ui.tsx arquivo mais antigo, o editor faz um backup dele como src/ui.tsx.bak na primeira vez que você abre o Editor de UI.

Como estes são arquivos comuns, você pode abri-los no seu editor de código a qualquer momento. Veja UI para saber o que o código subjacente faz.

Código que o editor não consegue editar

O editor entende uma forma específica de código de UI. Um nó 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 cinza com um não padrão, edite em código selo. Seus filhos não são mostrados, e você o edita em código em vez disso.

O resto da GUI ao redor continua funcionando normalmente.

Páginas relacionadas

• UI: escrevendo UI da cena em código.

• Combinar com código: abra a sua scene num editor de código.

• Entities and Components: o lado 3D do editor.