> 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/criar-para-mobile/safe-area.md).

# Área segura do mobile

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](#reserved-margins) 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](#device-hardware-insets-screeninsetarea).

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

{% hint style="info" %}
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](/creator/content-creator-pt/scenes-sdk7/criar-para-mobile/preview-on-mobile.md).
{% endhint %}

## 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 }
```

<figure><img src="/files/3a298bd99934de7d871efde0df0bac32484617b9" alt="Mobile screen with the reserved regions highlighted"><figcaption><p>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.</p></figcaption></figure>

## 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ã
}
```

<figure><img src="/files/8ce94a719800d37d9f9a0af1dc92381e25e1c85c" alt="Mobile screen with the safe area highlighted"><figcaption><p>A zona segura central: 720 × 605 px, de x 30%–75% e y 8%–92%.</p></figcaption></figure>

## 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:

```tsx
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.

{% hint style="info" %}
**📱 Apenas mobile:** `ScreenInsetArea` só altera alguma coisa no **cliente mobile**onde 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.
{% endhint %}

## Relacionado

* [Boas práticas de UI para mobile](/creator/content-creator-pt/scenes-sdk7/criar-para-mobile/ui-best-practices.md)
* [Detetar a plataforma a partir do código](/creator/content-creator-pt/scenes-sdk7/criar-para-mobile/detect-platform.md) — usa `isMobile()` para trocar layouts.
* [UI no ecrã](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md)
* [Guia de UX e UI](/creator/content-creator-pt/scenes-sdk7/desenhar-a-experiencia/ux-ui-guide.md)


---

# 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/criar-para-mobile/safe-area.md?ask=<question>
```

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.