> 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/ui-2d/onscreen-ui.md). # UI na tela Você pode criar uma UI para a sua Scene, para ser exibida no espaço 2D fixo da tela, em vez de no espaço do mundo 3D. Os elementos de UI só ficam visíveis quando o jogador está dentro das parcelas de LAND da Scene, pois Scenes vizinhas podem ter sua própria UI para exibir. Partes da UI também podem ser acionadas para abrir quando certos eventos ocorrem no world-space, por exemplo, se o jogador clicar em um local específico. Crie uma UI definindo uma estrutura de objetos aninhados `UIEntity` objetos em JSX. A sintaxe usada para UIs é muito semelhante à de [React](https://reactjs.org/) (uma biblioteca muito popular baseada em JavaScript para criar UIs web). {% hint style="warning" %} **📔 Nota**: Você só pode definir a sintaxe de UI em arquivos que tenham uma `.tsx` extensão. `.tsx` arquivos suportam tudo o que `.ts` arquivos suportam, além da sintaxe de UI. Recomendamos criar um `ui.tsx` arquivo e definir sua UI lá. Lembre-se de chamar o método de renderização da sua UI a partir de `index.ts` com `ReactEcsRenderer.setUiRenderer(yourUiMethodName)`, veja o exemplo abaixo. {% endhint %} Uma UI simples com elementos estáticos pode se parecer bastante com HTML, mas, ao adicionar elementos dinâmicos que respondem a uma mudança de estado, você pode fazer coisas muito mais poderosas. A UI padrão do Explorer do Decentraland inclui um widget de chat, um mapa e outros elementos. Esses elementos de UI são sempre exibidos na camada superior, acima de qualquer UI específica da Scene. Portanto, se a sua Scene tiver elementos de UI que ocupem o mesmo espaço da tela que eles, esses elementos serão ocultados. Veja [UX guidelines](/creator/content-creator-pt/scenes-sdk7/desenhar-a-experiencia/ux-ui-guide.md) para dicas sobre como projetar a aparência e a sensação da sua UI. {% hint style="info" %} **📱 Projetando para mobile**: O [client mobile](/creator/content-creator-pt/scenes-sdk7/criar-para-mobile/building-for-mobile.md) reserva o lado esquerdo, o canto superior direito e o canto inferior direito da tela para os controles do sistema (joystick, chat, profile, camera, botão de interação). A UI da Scene nessas regiões entrará em conflito com os controles. Antes de publicar, revise o [Mobile safe area](/creator/content-creator-pt/scenes-sdk7/criar-para-mobile/safe-area.md) e as [UI best practices for mobile](/creator/content-creator-pt/scenes-sdk7/criar-para-mobile/ui-best-practices.md). Um bom ponto de partida é projetar sua UI no desktop e depois **dimensionar os tamanhos em 3×** para melhorar a legibilidade no mobile. {% endhint %} {% hint style="info" %} **📱 Evite margens reservadas pelo hardware**: No mobile, os dispositivos reservam espaço na tela para o notch, a barra de status, o indicador de início e os cantos arredondados. Envolva sua UI no [`ScreenInsetArea` component](/creator/content-creator-pt/scenes-sdk7/criar-para-mobile/safe-area.md#device-hardware-insets-screeninsetarea) para mantê-la automaticamente afastada dessas áreas. Isso afeta apenas o client mobile — no desktop, não tem efeito, então é seguro deixá-lo em UI multiplataforma. {% endhint %} Quando o jogador clica no botão *close UI* no canto inferior direito da tela, todos os elementos de UI são ocultados. ## Renderizar uma UI Para exibir uma UI na sua Scene, use a `ReactEcsRenderer.setUiRenderer()` função, passando a ela uma estrutura válida de entities, descrita em um `.tsx` arquivo. Cada entity é definida como um nó semelhante a HTML, com propriedades para cada um de seus components. ***arquivo ui.tsx:*** ```ts import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const uiMenu = () => ( ) ``` ***arquivo index.ts:*** ```ts import { ReactEcsRenderer } from '@dcl/sdk/react-ecs' import { uiMenu } from './ui' export function main() { ReactEcsRenderer.setUiRenderer(uiMenu, { virtualWidth: 1920, virtualHeight: 1080 }) } ``` Você também pode definir uma estrutura de entity e renderizá-la, tudo em um único comando em um `.tsx` arquivo. ***arquivo ui.tsx:*** ```tsx import ReactEcs, { ReactEcsRenderer, UiEntity } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export function setupUI() { ReactEcsRenderer.setUiRenderer(() => ( ), { virtualWidth: 1920, virtualHeight: 1080 }) } ``` ***arquivo index.ts:*** ```ts import { setupUI } from './ui' export function main() { setupUI() } ``` {% hint style="warning" %} **📔 Nota**: Todos os seus elementos de UI precisam estar aninhados na mesma estrutura e ter um único elemento pai na raiz da estrutura. Você só pode chamar `ReactEcsRenderer.setUiRenderer()` uma vez na Scene. {% endhint %} ## UI Entities Cada elemento da UI deve ser definido como uma `UiEntity`, seja uma imagem, texto, fundo, uma caixa invisível de alinhamento etc. Assim como no espaço 3D da Scene, cada `UiEntity` tem seus próprios components para lhe dar posição, cor etc. A sintaxe semelhante à do React permite especificar cada component como uma propriedade dentro do `UiEntity`, isso torna o código mais curto e legível. Os components usados em uma `UiEntity` são diferentes daqueles usados em entities regulares. Você não pode aplicar um component de UI a uma entity regular, nem um component regular a uma UI entity. Os seguintes components estão disponíveis para uso em uma `UiEntity`: * `uiTransform` * `uiBackground` * `uiText` * `onClick` Assim como com tags HTML, você pode definir components como self-closing ou aninhar um dentro do outro. ***arquivo ui.tsx:*** ```tsx import ReactEcs, { ReactEcsRenderer, UiEntity } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const uiMenu = () => ( // entity pai // entity filho self-closing // declaração de fechamento para a entity pai ) ``` ***arquivo index.ts:*** ```ts import { ReactEcsRenderer } from '@dcl/sdk/react-ecs' import { uiMenu } from './ui' export function main() { ReactEcsRenderer.setUiRenderer(uiMenu, { virtualWidth: 1920, virtualHeight: 1080 }) } ``` Uma definição de um UI module pode ter apenas uma entity de nível pai. Você pode definir quantas outras entities quiser, mas todas elas devem caber em uma estrutura com um único parent no topo. ## Escala virtual da tela Defina uma largura e altura virtuais para a UI. Isso é recomendado para garantir que sua UI tenha a mesma aparência em diferentes tamanhos de tela, independentemente do tamanho real da tela em pixels. ```ts export function setupUi() { ReactEcsRenderer.setUiRenderer(uiComponent, { virtualWidth: 1920, virtualHeight: 1080 }) } ``` Se você definir uma largura virtual de 1920 e uma altura virtual de 1080, a UI será redimensionada para caber no tamanho da tela. Se a tela for 1920x1080, a UI será exibida no mesmo tamanho da dimensão virtual. Se a tela for maior ou menor, qualquer valor em pixels será redimensionado para caber na dimensão virtual. Por exemplo, se a tela for 3840x2160, um item definido com 100 pixels de largura será exibido com 200 pixels reais. O cálculo real do fator de escala da Ui que é multiplicado nos valores em pixels é [`Math.min(realWidth / virtualWidth, realHeight / virtualHeight)`](https://github.com/decentraland/js-sdk-toolchain/blob/fbf4826ef686982ca1e60d368186e8e10c02a6e6/packages/%40dcl/react-ecs/src/system.ts#L124) ## Vários módulos de UI Se a sua Scene contiver vários systems ou modules que definem sua própria UI, você pode renderizar cada UI module com `ReactEcsRenderer.addUiRenderer()`. Isso é especialmente útil ao trabalhar em uma Scene complexa com vários components de UI, ou ao definir UIs para um [smart item](https://github.com/decentraland/docs/blob/main/creator/sdk7/smart-items/smart-items.md), que deve poder ser usado independentemente do que estiver no código do restante da Scene. A `ReactEcsRenderer.addUiRenderer()` function exige que você forneça uma entity como proprietária da UI. Pode ser qualquer entity, até mesmo uma dummy entity criada apenas para ser usada como proprietária da UI. ```ts export function setupUi() { // Crie uma dummy entity para ser a proprietária da UI const dummyEntity = engine.addEntity() // Defina o UI module como uma function que retorna um array de UI modules const uiComponent = () => [ // Function que retorna um UI module, // Function que retorna um UI module // ... ] // Renderize o UI module com a dummy entity como proprietária ReactEcsRenderer.addUiRenderer(dummyEntity, uiComponent) } ``` Este trecho pode existir independentemente de qualquer outro código de UI na Scene. O restante da Scene pode incluir um `ReactEcsRenderer.setUiRenderer()`, ou nenhum, e a UI ainda assim será renderizada. Uma `addUiRenderer()` também pode incluir uma largura e altura virtuais, assim como `setUiRenderer()`. No entanto, se a Scene tiver uma `setUiRenderer()` chamada que também defina uma largura e altura virtuais, a largura e altura virtuais da `addUiRenderer()` chamada serão ignoradas. ```tsx ReactEcsRenderer.addUiRenderer(dummyEntity, uiComponent, { virtualWidth: 1920, virtualHeight: 1080 }) ``` Essa UI pode ser removida com `ReactEcsRenderer.removeUiRenderer(dummyEntity)` , além disso, se a entity que possui a UI for destruída, a UI também será removida. Se `ReactEcsRenderer.addUiRenderer()` for chamada novamente para a mesma entity, mas com um UiRenderer diferente, o anterior será limpo e o novo o substituirá. ### Compartilhando uma única instrução setUiRenderer Em vez de chamar `ReactEcsRenderer.addUiRenderer()` para cada UI module, você pode chamar `ReactEcsRenderer.setUiRenderer()` uma vez com um array de UI modules, que podem ficar em arquivos diferentes. ```ts const uiComponent = () => [ // Function que retorna um UI module, // Function que retorna um UI module // ... ] ReactEcsRenderer.setUiRenderer(uiComponent, { virtualWidth: 1920, virtualHeight: 1080 }) ``` Abaixo está um exemplo mais completo: ***arquivo ui.tsx:*** ```ts export function UIModule1() { return ( ) } export function UIModule2() { return ( ) } ``` ***arquivo index.ts:*** ```ts import { ReactEcsRenderer } from '@dcl/sdk/react-ecs' import { UIModule1, UIModule2 } from './ui' export function main() { ReactEcsRenderer.setUiRenderer([ UIModule1(), UIModule2(), // ... // A linha abaixo é para usar a biblioteca DCL UI Toolkit // https://github.com/decentraland-scenes/dcl-ui-toolkit ui.render(), ], { virtualWidth: 1920, virtualHeight: 1080 }) } ``` --- # 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: ``` GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.