> 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/ui_background.md).

# Fundo da UI

Defina um fundo e borda de uma UI entity.

As seguintes propriedades são usadas para definir um background e uma borda em uma entidade de UI.

## Fundo

Um `uiBackground` componente fornece cor ou uma textura à área de uma entidade. Ele usa o tamanho e a posição definidos pela entidade's `uiTransform`.

Os seguintes campos podem ser configurados, e todos são opcionais:

* `color`: A cor a ser usada na entidade, como um valor de [Color4](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/color-types.md) .

{% hint style="info" %}
**💡 Dica**: Torne uma entidade semitransparente definindo o 4º valor do `Color4` para menos de 1.
{% endhint %}

* `texture`: A textura a ser exibida na entidade; isso recebe um objeto com vários parâmetros sobre a textura. As mesmas propriedades estão disponíveis como em texturas em [materiais em entidades 3D](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/materials.md#using-textures).

  * `src`: O caminho para o arquivo de imagem a ser usado como textura. (string)

  * `filterMode`: *(opcional)* Determina como os pixels na textura são esticados ou comprimidos quando renderizados. Veja [Escalonamento de Textura](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/materials.md#texture-scaling). (FilterMode = 'point' | 'bi-linear' | 'tri-linear')

  * `wrapMode`: *(opcional)* Determina como uma textura é aplicada em mosaico a uma entidade. Isso usa um valor do `TextureWrapMode` enum. Veja \[Texture Wrapping]\(([Veja a documentação](https://github.com/decentraland/docs/tree/main/creator/sdk7/README.md)). (WrapMode = 'repeat' | 'clamp' | 'mirror')

  > Dica: Você pode combinar ambas as `texture` e `color` propriedades em um único `uiBackground` componente para produzir uma textura com tonalidade.
* `textureMode`: Seleciona como você quer que a textura se adapte ao tamanho da entidade à qual ela é aplicada. (TextureMode = 'nine-slices' | 'center' | 'stretch')enum, que suporta os seguintes valores:
  * `center`: A textura não é esticada; ela é posicionada centralizada na entidade e partes dela podem ser cortadas dependendo do tamanho da entidade.
  * `stretch`: A textura é esticada para corresponder a toda a superfície da entidade.
  * `nine-slices`: Partes da textura são esticadas para corresponder a toda a superfície da entidade, deixando as margens sem esticar. Veja [texturas nine-slice](#nine-slice-textures).
* `avatarTexture`: Exibe uma miniatura do perfil de um avatar, com base em um avatar ID. Veja \[Avatar Portraits]\(([Veja a documentação](https://github.com/decentraland/docs/tree/main/creator/sdk7/README.md)).
* `textureSlices`: Determine as margens a serem usadas ao utilizar o modo de textura nine-slice, veja [texturas nine-slice](#nine-slice-textures). Defina um número menor que 1, como uma fração da largura ou altura total da imagem.

Cor simples:

***ficheiro ui.tsx:***

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400
    }}
    uiBackground={{
		color: Color4.create(0.5, 0.8, 0.1, 0.6)
	}}
  />
)
```

***ficheiro index.ts:***

```ts
import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
import { uiMenu } from './ui'

export function main() {
    ReactEcsRenderer.setUiRenderer(uiMenu, { virtualWidth: 1920, virtualHeight: 1080 })
}
```

{% hint style="warning" %}
**📔 Nota**: Todos os snippets seguintes nesta página assumem que você tem um `.ts` semelhante ao acima, a executar a `ReactEcsRenderer.setUiRenderer()` função.
{% endhint %}

Padrão de textura repetida:

```ts
import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400
    }}
    uiBackground={{
		textureMode: 'center',
		texture: {
			src: "images/brick-wall-texture.png",
			wrapMode: 'repeat'
		}
	}}
  />
)
```

## Bordas

Algumas propriedades são usadas para definir uma borda ao redor de uma entidade de UI. Essas propriedades existem no componente. `uiTransform` Elas permitem definir um único valor para todos os lados da borda, ou valores diferentes para cada lado.

* `borderColor`: A cor a ser usada na entidade, como um valor de [Color4](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/color-types.md) .
* `borderWidth`: A largura da borda, como um número em pixels. Também suporta valores em porcentagem, por exemplo `borderWidth: '2%'` definirá a largura da borda como 2% da largura da entidade.
* `borderRadius`: Use esta propriedade para dar aos cantos da entidade uma borda arredondada. Ela define o raio dos cantos em pixels.

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400,
      borderColor: Color4.Red(),
      borderWidth: 4,
      borderRadius: 10
    }}
  />
)
```

`borderWidth`, `borderColor` e `borderRadius` também pode ser definida com valores diferentes para cada lado da entidade.

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400,
      borderColor: { top: Color4.White(), left: Color4.Red(), right: Color4.Blue(), bottom: Color4.Gray() },
      borderRadius: { topLeft: 20, topRight: 20, bottomLeft: 20, bottomRight:0 },
      borderWidth: { top: 3, left: 2, right: 3, bottom: 4 }
    }}
  />
)
```

## Opacidade

Use a `opacity` property no `uiTransform` de um `UiEntity` para adicionar transparência à entidade e a todos os seus filhos. A propriedade opacity é um valor de 0 a 1, onde 0 é totalmente transparente e 1 é totalmente opaca.

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400,
      opacity: 0.7
    }}
    uiBackground={{ color: Color4.Green() }}
  >
    <UiEntity
        uiTransform={{
          width: 100,
          height: 30,
        }}
        uiText={{
          value: "Este texto também é transparente",
          fontSize: 40
        }}
      />
   </UiEntity>
)
```

O valor de opacity afeta todos os filhos de um UiEntity, aplicando transparência às cores de fundo, cores de texto e imagens de fundo. Quando tanto o pai quanto um filho têm valores de opacity, a opacity final do filho é o produto do seu próprio valor pelo valor do pai.

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400,
      opacity: 0.7
    }}
    uiBackground={{ color: Color4.Green() }}
  >
    <UiEntity
      uiTransform={{
        width: 100,
        height: 30,
        opacity: 0.7
      }}
      uiText={{
        value: "Este texto é ainda mais transparente",
        fontSize: 40
      }}
    />
  </UiEntity>
)
```

## Texturas nine-slice

Você pode usar [escala 9-slice](https://en.wikipedia.org/wiki/9-slice_scaling) com as suas texturas, para garantir que os cantos e as margens não sejam esticados de forma desigual.

Com esta técnica popular, você divide uma imagem em 9 segmentos, que serão esticados de maneiras diferentes para preservar as proporções das margens e dos cantos. Por exemplo, use isto para definir fundos com cantos arredondados que se adaptem facilmente a qualquer tamanho. Considere a seguinte imagem (emprestada de [Wikipedia](https://en.wikipedia.org/wiki/9-slice_scaling#/media/File:Traditional_scaling_vs_9-slice_scaling.svg)):

![
](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-e2ac050bd4fa39a8b191cd36e282279f43613058%2F9-slice.png?alt=media)

Nesta imagem vemos a textura original (superior esquerda) e o resultado de escalá-la de forma tradicional (superior direita); observe como os cantos ficam deformados. Abaixo disso, vemos a textura segmentada em 9 fatias (inferior esquerda) e depois o resultado de esticar a imagem de acordo com o método de 9 fatias (inferior direita).

Veja como cada segmento é afetado, usando a imagem acima como referência.

* O segmento 5 é a única parte da imagem que é totalmente esticada nos eixos x e y.
* Os segmentos 1, 3, 7 e 9 (os cantos) não são esticados de forma alguma.
* Os segmentos 2 e 8 são esticados apenas horizontalmente
* Os segmentos 4 e 6 são esticados apenas verticalmente.

Para usar a escala nine-slice em uma entidade, defina o `textureMode` para `'nine-slices'`. Você também pode definir opcionalmente uma largura para a margem em cada lado em `textureSlices`.

```ts
import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'

export const uiMenu = () => (
  <UiEntity
    uiTransform={{ width: 700, height: 400 }}
    uiBackground={{
      textureMode: 'nine-slices',
      texture: {
        src: 'images/rounded_alpha_square.png'
      },
      textureSlices: {
        top: 0.2,
        bottom: 0.2,
        left: 0.2,
        right: 0.2
      }
	}}
  />
)
```

## UVs da textura

Use a `uvs` propriedade em um `uiBackground` componente para exibir uma região específica de uma textura. Isso é útil para selecionar sprites individuais de uma sprite sheet ou para girar uma imagem.

O `uvs` o campo recebe um array de 8 números, representando 4 pares de coordenadas UV para os quatro cantos da região da textura. A ordem é: **inferior esquerdo**, **superior esquerdo**, **superior direito**, **inferior direito**. Cada valor varia de 0 a 1, onde `(0, 0)` é o canto inferior esquerdo da imagem e `(1, 1)` é o superior direito.

{% hint style="info" %}
**💡 Dica**: Ao usar UVs personalizadas `uvs`, defina `textureMode` para `'stretch'` para que a região selecionada preencha a área da entidade.
{% endhint %}

### Sprites de uma sprite sheet

Para exibir uma parte de uma imagem maior (por exemplo, uma carta de uma sprite sheet que contém várias), defina a `uvs` para as coordenadas dessa região.

```ts
import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'

// Exiba a metade esquerda de uma textura (por exemplo, a primeira carta em uma sprite sheet de 2 colunas)
export const uiMenu = () => (
  <UiEntity
    uiTransform={{ width: 200, height: 300 }}
    uiBackground={{
      textureMode: 'stretch',
      texture: { src: 'images/card-atlas.png' },
      uvs: [
        // inferior esquerdo, superior esquerdo, superior direito, inferior direito
        0, 0,
        0, 1,
        0.5, 1,
        0.5, 0
      ]
    }}
  />
)
```

Para uma sprite sheet com uma grade de frames (por exemplo, uma de 4 colunas por 2 linhas), calcule os UVs com base na coluna e na linha do frame que você quer:

```ts
import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'

// Escolha um único frame de uma sprite sheet em grade
function getFrameUVs(col: number, row: number, totalCols: number, totalRows: number): number[] {
  const stepU = 1 / totalCols
  const stepV = 1 / totalRows
  const left = col * stepU
  const right = (col + 1) * stepU
  const top = 1 - row * stepV
  const bottom = 1 - (row + 1) * stepV
  return [
    left, bottom,
    left, top,
    right, top,
    right, bottom
  ]
}

// Exiba a coluna 2, linha 0 de uma sprite sheet 4x2
export const uiMenu = () => (
  <UiEntity
    uiTransform={{ width: 128, height: 128 }}
    uiBackground={{
      textureMode: 'stretch',
      texture: { src: 'images/spritesheet.png' },
      uvs: getFrameUVs(2, 0, 4, 2)
    }}
  />
)
```

### Girando uma imagem com UVs

Você pode girar uma textura aplicando uma rotação 2D às coordenadas UV. Isso é útil para spinners ou indicadores de carregamento sem precisar de rotação baseada em transform.

```ts
import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
import { engine } from '@dcl/sdk/ecs'

// Gire um ponto 2D ao redor de um centro
function rotate2D(angle: number, x: number, y: number, cx: number, cy: number): number[] {
  const cos = Math.cos(angle)
  const sin = Math.sin(angle)
  return [
    cos * (x - cx) - sin * (y - cy) + cx,
    sin * (x - cx) + cos * (y - cy) + cy
  ]
}

// Construa coordenadas UV rotacionadas
function rotateUVs(angle: number): number[] {
  const uv00 = rotate2D(angle, 0, 0, 0.5, 0.5)
  const uv01 = rotate2D(angle, 0, 1, 0.5, 0.5)
  const uv11 = rotate2D(angle, 1, 1, 0.5, 0.5)
  const uv10 = rotate2D(angle, 1, 0, 0.5, 0.5)
  return [uv00[0], uv00[1], uv01[0], uv01[1], uv11[0], uv11[1], uv10[0], uv10[1]]
}

let spinnerAngle = 0

// Sistema que atualiza o ângulo a cada frame
engine.addSystem((dt: number) => {
  spinnerAngle += dt * 5
})

export const uiMenu = () => (
  <UiEntity
    uiTransform={{ width: 128, height: 128 }}
    uiBackground={{
      textureMode: 'stretch',
      texture: { src: 'images/spinner.png' },
      uvs: rotateUVs(spinnerAngle)
    }}
  />
)
```

O `rotateUVs` função que gira os quatro cantos UV ao redor do ponto central `(0.5, 0.5)` pelo ângulo dado em radianos. Como isso é chamado a cada frame pelo renderizador semelhante ao React, o spinner é atualizado suavemente.

{% hint style="info" %}
**💡 Dica**: Veja um exemplo completo e funcional com sprites, sprite sheets animadas, spinners e mais no [Animações de UI](https://github.com/decentraland/sdk7-goerli-plaza/tree/main/ui-animations) cena de exemplo.
{% endhint %}


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/ui_background.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.