Área Segura no Mobile

Onde a UI da scene pode ficar com segurança no mobile — fora das margens de hardware do dispositivo e dos próprios controles do client.

Num telemóvel, duas coisas independentes consomem o espaço do ecrã que a tua UI pode usar com segurança:

• As margens de hardware do dispositivo — o notch ou corte da câmara, a barra de estado, o indicador de início e os cantos arredondados. A UI desenhada por baixo deles fica parcialmente oculta ou é difícil de tocar.

• Os controlos próprios do cliente Decentraland — joystick, chat, perfil, controlos da câmara, botões de ação. A UI da scene colocada por baixo deles entra em conflito visualmente e compete pelos mesmos toques.

Não tens de medir nenhum dos dois. O cliente reporta ambas as áreas em runtime e o SDK posiciona a tua UI dentro da que escolheste, com a screenInset opção do renderer:

O que queres	O que passar
Livre das margens de hardware	nada — screenInset: 'device' é o predefinido
Livre das margens de hardware e os controlos do cliente	screenInset: 'interactable'
O ecrã inteiro, as margens são da tua responsabilidade	screenInset: 'none'

// Recomendado para UI da scene que não deve entrar em conflito com os controlos móveis
ReactEcsRenderer.setUiRenderer(uiComponent, { screenInset: 'interactable' })

Suporte do cliente: 'interactable' requer cliente móvel 1.12.1 ou mais recente. Em clientes mais antigos, a área é reportada como zero e a UI passa a cobrir o ecrã inteiro. Essa mesma versão normaliza a 'device' área entre Android e iOS.

Não é um no-op no desktop — o cliente desktop reserva cerca de 25% do lado esquerdo do ecrã para a sua própria UI, por isso 'interactable' também altera o teu layout no desktop. Faz branching com isMobile() se só quiseres o inset nos telemóveis.

Veja Área de screenInset para a referência completa: as três áreas lado a lado num dispositivo real, o comportamento por renderer e a forma como se relacionam com o ecrã virtual.

Onde vivem os controlos do cliente

'interactable' dá-te a área que cada explorer designa para UI da scene — isto não é de propósito uma promessa de que todos os controlos do cliente ficam fora dela. No cliente móvel, é a área segura do dispositivo menos a coluna do lado esquerdo (chat, perfil, joystick, emotes); os botões de ação no canto inferior direito são desenhados por cima da área por design.

screenInset: 'interactable' no cliente móvel 1.12.1. O retângulo magenta é a UI da scene, o contorno verde delimita a área interactable. A coluna do lado esquerdo é excluída; os botões de ação no canto inferior direito ficam sobre a área.

Portanto, mesmo com 'interactable', trata estas zonas como cheias:

• Canto inferior direito — os botões de ação e o botão de interação são desenhados por cima. Tudo o que colocares aqui continua acessível, mas compete pelos toques.

• Canto superior direito — os controlos de perfil e da câmara ficam mesmo fora da área, por isso a UI encostada a esse canto parece fazer parte do HUD do cliente.

O que a área cobre é uma decisão de cada explorer e pode mudar entre versões. Lê-a em runtime, nunca a codifiques fixamente, e verifica-a nas plataformas que pretendes.

Onde colocar a UI da scene

• Centro do ecrã — diálogos acionáveis, qualquer coisa que o jogador precise de ler e responder.

• Topo-centro — mensagens não acionáveis, estado e notificações.

• Centro inferior, acima do botão de interação — sugestões sensíveis ao contexto.

• Não no canto inferior direito — mesmo dentro da área interactable, isso pertence aos botões de ação.

Envolve antes parte da tua UI

Se optaste por não usar com screenInset: 'none' e quiseres proteger apenas parte da tua UI, envolve-a no componente ScreenInsetArea ou no InteractableArea Cada um lê a sua área correspondente e aplica-a aos seus filhos. Importa-os de @dcl/sdk/react-ecs:

import ReactEcs, { ReactEcsRenderer, UiEntity, ScreenInsetArea } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export function setupUi() {
  ReactEcsRenderer.setUiRenderer(() => (
    <ScreenInsetArea>
      {/* Um filho com 100% × 100% ocupa exatamente a área segura do inset */}
      <UiEntity
        uiTransform={{ width: '100%', height: '100%' }}
        uiBackground={{ color: Color4.create(0, 0, 0, 0.5) }}
      />
    </ScreenInsetArea>
  ), { screenInset: 'none' })
}

Ambos os componentes posicionam-se de forma absoluta usando os valores reportados pelo cliente, por isso os positionType e position campos dos seus uiTransform ficam reservados — qualquer valor que definas para eles é ignorado. Todas as outras uiTransform propriedades (padding, flexDirection, alignItems, …) e componentes de UI (uiBackground, onMouseDown, …) funcionam normalmente. Reagem automaticamente quando a área muda, por exemplo ao rodar o dispositivo ou quando as barras do sistema aparecem ou desaparecem, e compensam o fator de escala da UI, por isso as margens ficam corretamente, independentemente do tamanho do teu ecrã virtual.

📔 Não apliques o inset duas vezes: o screenInset: 'none' no excerto acima é importante. Envolver a tua UI num componente enquanto o renderer também aplica o inset correspondente empurra a tua UI para dentro com o dobro da margem. Escolhe um ou outro.

📱 Apenas móvel: os insets do dispositivo só têm valores reais no cliente móvel. No cliente desktop são (0, 0, 0, 0)nulos, screenInset: 'device' quanto a ScreenInsetArea por isso os componentes não têm efeito aí e a tua UI é renderizada exatamente como seria sem eles. A área interactable, ao contrário dos insets do dispositivo, é não é zero no desktop.

Porque é importante

A UI da scene que se sobrepuser aos controlos do cliente vai:

• Ficar parcialmente oculta atrás do joystick, do botão de interação ou dos controlos da câmara.

• Competir por toques com esses controlos — os jogadores vão ativar acidentalmente um ou outro.

• Fazer com que a tua scene pareça avariada no móvel, o que prejudica o destaque e a retenção.

Verifica sempre num dispositivo real usando o código QR de preview.

Relacionados

• Área de screenInset — a screenInset referência completa.

• Boas práticas de UI para mobile

• Deteta a plataforma a partir do código — usa isMobile() para trocar layouts.

• UI no ecrã

• Guia de UX & UI