Área segura mobile

Onde a UI da cena pode ficar com segurança no mobile — fora do HUD do sistema e das margens reservadas pelo hardware do dispositivo.

Num telemóvel, há duas coisas que consomem o espaço de ecrã que a tua UI pode usar em segurança:

• O HUD do sistema do Decentraland — a app sobrepõe os seus próprios controlos (joystick, chat, perfil, controlos da câmara, o botão de interação). A UI da Scene colocada por baixo entra em conflito visualmente e compete pelos toques. Estas regiões são assinaladas em Margens reservadas abaixo.

• As margens reservadas do hardware do dispositivo — o notch ou recorte da câmara, a barra de estado, o indicador de início e os cantos arredondados. O SDK mantém a UI afastada automaticamente destas com o ScreenInsetArea componente.

A área segura móvel é o que sobra — onde a UI da Scene pode existir sem entrar em conflito com nenhuma das duas.

Todos os valores abaixo usam coordenadas normalizadas [0.0 – 1.0] com base numa resolução de referência 1600 × 720 px em paisagem . Usa sempre valores normalizados para que o teu layout se adapte a qualquer tamanho de ecrã. Verifica sempre num dispositivo real usando o código QR de preview.

Margens reservadas

O HUD do sistema ocupa as extremidades exteriores nos quatro lados. Não coloques UI da Scene dentro destas regiões:

Extremidade	Reservado para	Tamanho
Esquerda	Chat, joystick, emotes	480 px — 30% da largura
Direita	Perfil, botões de ação	400 px — 25% da largura
Topo	Barra do sistema	58 px — 8% da altura
Fundo	Barra do sistema	58 px — 8% da altura

// Margens mínimas seguras (normalizadas)
margin: { left: 0.30, right: 0.25, top: 0.08, bottom: 0.08 }

As regiões reservadas no cliente mobile: o lado esquerdo, o canto superior direito e o canto inferior direito são propriedade dos controlos do sistema.

Zona segura central

A área recomendada para toda a UI da Scene é a faixa central do ecrã. Dá-te 720 × 605 px de espaço utilizável:

	Pixels	Normalizado
início x	480 px	0.30
fim x	1200 px	0.75
início y	58 px	0.08
fim y	662 px	0.92

// Zona segura central (normalizada)
safeArea: {
  x: [ 0.30, 0.75 ],  // 480 – 1200 px  →  45% da largura do ecrã
  y: [ 0.08, 0.92 ]   // 58 – 662 px    →  84% da altura do ecrã
}

A zona segura central: 720 × 605 px, de x 30%–75% e y 8%–92%.

Espaço à direita (apenas elementos pequenos)

Entre o avatar do Perfil (canto superior direito) e o grupo de botões de ação (canto inferior direito) existe um espaço estreito onde pequenos elementos de UI — ícones, contadores, indicadores de estado — podem ficar. Mantém aqui elementos com um máximo de 48 × 48 px para evitar sobrecarregar os controlos.

	Pixels	Normalizado
intervalo x	1200 – 1600 px	0.75 – 1.0
intervalo y	158 – 360 px	0.22 – 0.50

// Espaço à direita (normalizado)
rightGap: {
  x: [ 0.75, 1.0  ],  // 1200 – 1600 px
  y: [ 0.22, 0.50 ]   // 158 – 360 px
}

Onde colocar a UI da Scene

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

• Centro superior — mensagens não acionáveis, estado e notificações.

• Centro inferior (acima do botão de interação) — dicas sensíveis ao contexto.

• Espaço à direita — apenas ícones pequenos ou contadores (máx. 48 × 48 px).

Porque é importante

A UI da Scene que se sobrepõe às regiões reservadas irá:

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

• Competir pelos toques com os controlos do sistema — os jogadores vão acionar um ou outro sem querer.

• Fazer a tua Scene parecer avariada no telemóvel, o que prejudica a promoção e a retenção.

Inserções de hardware do dispositivo (ScreenInsetArea)

As margens reservadas acima pertencem ao HUD do sistema. Separadamente, o hardware do dispositivo reserva espaço no ecrã para o notch ou recorte da câmara, a barra de estado, o indicador de início e os cantos arredondados. A UI desenhada por baixo disto fica parcialmente escondida ou é difícil de tocar.

A ScreenInsetArea O componente mantém a tua UI afastada destas margens de hardware automaticamente, lendo as inserções atuais que o dispositivo reporta. Importa-o de @dcl/sdk/react-ecs e envolve a UI que queres proteger:

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 tamanho 100% × 100% preenche exatamente a área de inserção segura */}
      <UiEntity
        uiTransform={{ width: '100%', height: '100%' }}
        uiBackground={{ color: Color4.create(0, 0, 0, 0.5) }}
      />
    </ScreenInsetArea>
  ))
}

ScreenInsetArea posiciona-se absolutamente usando os valores de inserção que o dispositivo reporta, por isso o positionType e position dos seus campos uiTransform estão reservados — qualquer valor que definas para eles é ignorado. Todas as outras uiTransform propriedades (padding, flexDirection, alignItems , …) e componentes de UI (uiBackground, onMouseDown , …) funcionam normalmente. O componente reage automaticamente quando as inserções mudam, por exemplo na rotação ou quando as barras do sistema aparecem ou desaparecem.

📱 Apenas mobile: ScreenInsetArea só altera alguma coisa no cliente mobileonde o dispositivo reporta valores reais de inserção. No cliente desktop as inserções são (0, 0, 0, 0)zero, por isso o componente não tem efeito e a tua UI é renderizada exatamente como seria sem ele. É seguro deixá-lo no código de UI multiplataforma.

Relacionado

• Boas práticas de UI para mobile

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

• UI no ecrã

• Guia de UX e UI