> 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/fundamentos-de-conteudo-3d/materials.md).

# Materiais

Saiba como adicionar materiais e texturas a entities com formas primitivas.

## Materials

Os materiais podem ser aplicados a entidades que utilizem formas primitivas (cubo, esfera, plano, etc.) adicionando um `Material` componente. Este componente tem vários campos que permitem configurar as propriedades do material, adicionar uma textura, etc.

*glTF* Os modelos incluem os seus próprios materiais, que são importados implicitamente para uma cena juntamente com o modelo. Para modificar ou substituir estes materiais, utilize o `GltfNodeModifiers` componente. Consulte [Modificar materiais glTF](#modify-gltf-materials) para obter mais detalhes.

Ao importar um modelo 3D com materiais próprios, tenha em conta que o motor do Decentraland não suporta todos os shaders. Apenas são suportados materiais padrão e materiais PBR (renderização baseada em física). Consulte [considerações sobre modelos 3D externos](https://github.com/decentraland/docs/blob/main/creator/3d-modeling/materials.md) para obter mais detalhes.

Existem diferentes tipos de materiais suportados:

* PBR (renderização baseada em física): o tipo de material mais comum no Decentraland. Suporta cores lisas ou texturas, bem como diferentes propriedades, como metalicidade, emissão, transparência, etc. Saiba mais sobre [PBR](https://en.wikipedia.org/wiki/Physically_based_rendering).
* Materiais básicos: não respondem à luz nem às sombras, o que os torna ideais para apresentar imagens em billboard.

## Use o Scene Editor no Creator Hub

A forma mais fácil de atribuir um Material a uma entidade é utilizar o Scene Editor. Pode adicionar um componente **Material** à entidade e, em seguida, configurar todos os campos disponíveis na interface do Scene Editor. Consulte [Adicionar componentes](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/construir/components.md#add-components).

## Adicionar um material

O exemplo seguinte cria um material PBR e define alguns dos seus campos para lhe atribuir uma cor vermelha e propriedades metálicas. Este material é adicionado a uma entidade que também tem uma forma de caixa, pelo que irá colorir a caixa com este material.

```ts
//Criar entidade e atribuir forma
const meshEntity = engine.addEntity()
Transform.create(meshEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(meshEntity)

//Criar material e configurar os seus campos
Material.setPbrMaterial(meshEntity, {
	albedoColor: Color4.Red(),
	metallic: 0.8,
	roughness: 0.1,
})
```

Para alterar o material de uma entidade que já tenha um componente `Material` , execute `Material.setPbrMaterial()` ou qualquer uma das outras funções auxiliares, que irão substituir o material original. Não é necessário remover o original `Material` nem utilizar a sintaxe avançada.

```ts
//Criar entidade e atribuir forma
const meshEntity = engine.addEntity()
Transform.create(meshEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(meshEntity)

//Criar material e configurar os seus campos
Material.setPbrMaterial(meshEntity, {
	albedoColor: Color4.Red(),
})

//Substituir pelo novo componente de material
Material.setPbrMaterial(meshEntity, {
	albedoColor: Color4.Blue(),
})
```

{% hint style="warning" %}
**📔 Nota**: o componente `Material` tem de ser importado através de

> `import { Material } from "@dcl/sdk/ecs"`

Consulte [Imports](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com eles facilmente.
{% endhint %}

## Cores dos materiais

Atribua uma cor lisa a um material. Num Material PBR, defina o campo `albedoColor` . As cores de albedo respondem à luz e podem apresentar sombreados.

Os valores de cor são do tipo `Color4`, composto por *r*, *g* e *b* valores (vermelho, verde e azul). Cada um destes valores varia entre 0 e 1. Ao definir valores diferentes para estes componentes, pode compor qualquer cor visível. Para preto, defina os três como 0. Para branco, defina todos como 1.

{% hint style="warning" %}
**📔 Nota**: Se definir qualquer cor em `albedoColor` com um valor superior a *1*, será apresentada como *emissiva*, com maior intensidade quanto maior for o valor. Por exemplo, `{r: 15, g: 0, b: 0}` produz um brilho vermelho muito intenso.
{% endhint %}

Consulte [tipos de cor](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/color-types.md) para obter mais detalhes sobre como definir cores.

Também pode editar os seguintes campos num Material PBR para ajustar com precisão a forma como a cor é percecionada:

* *emissiveColor*: A cor emitida pelo material.
* *reflectivityColor*: Também conhecido como *Cor especular* noutra nomenclatura.

Para criar um material de cor uniforme que não seja afetado pela luz e pelas sombras do ambiente, crie um material básico em vez de um material PBR.

```ts
Material.setBasicMaterial(myEntity, {
	diffuseColor: Color4.Black(),
})
```

## Utilizar texturas

Defina um ficheiro de imagem como textura num material, definindo o parâmetro `texture` .

```ts
//Criar entidade e atribuir forma
const meshEntity = engine.addEntity()
Transform.create(meshEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(meshEntity)

//Criar material e configurar os seus campos
Material.setPbrMaterial(meshEntity, {
	texture: Material.Texture.Common({
		src: 'assets/materials/wood.png',
	}),
})
```

No exemplo acima, a imagem do material está localizada numa `assets/materials` pasta, que se encontra na raiz da pasta do projeto da Scene.

{% hint style="info" %}
**💡 Sugestão**: Recomendamos que mantenha os ficheiros de imagem das texturas numa pasta `/assets` dentro da sua Scene.
{% endhint %}

Ao criar uma textura, também pode passar parâmetros adicionais:

* `filterMode`: Determina como os píxeis da textura são esticados ou comprimidos durante a renderização. Aceita um valor do enum `TextureFilterMode` . Consulte [Escalamento de texturas](#texture-scaling).
* `wrapMode`: Determina como uma textura é aplicada em mosaico num objeto. Aceita um valor do enum `TextureWrapMode` enum. Consulte [Repetição da textura](#texture-wrapping).

```ts
Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'assets/materials/wood.png',
		filterMode: TextureFilterMode.TFM_BILINEAR,
		wrapMode: TextureWrapMode.TWM_CLAMP,
	}),
})
```

Para criar uma textura que não seja afetada pela luz e pelas sombras do ambiente, crie um material básico em vez de um material PBR.

```ts
Material.setBasicMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'assets/materials/wood.png',
	}),
})
```

### Texturas de um URL externo

Pode definir a textura do material através de um URL externo, em vez de usar um caminho interno no projeto da cena.

```ts
Material.setBasicMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'https://wearable-api.decentraland.org/v2/collections/community_contest/wearables/cw_tuxedo_tshirt_upper_body/thumbnail',
	}),
})
```

O URL tem de começar com `https`, `http` URLs não são suportados.

### Repetição da textura

Pode definir como uma textura se alinha com uma superfície. Por predefinição, a textura é esticada para cobrir a superfície uma vez, mas pode redimensioná-la e deslocá-la.

Os seguintes campos estão disponíveis em todas as texturas:

* `offset`: Desloca a textura para alterar o seu alinhamento. O valor é um Vector2, em que cada eixo varia de 0 a 1, sendo 1 a largura ou altura total da textura.
* `tiling`: Redimensiona a textura. O valor predefinido é o Vector2 `[1, 1]`, que faz com que a imagem se repita uma vez, cobrindo toda a superfície.
* `TextureWrapMode`: Determina o que acontece se a repetição da imagem não cobrir toda a superfície. Esta propriedade aceita valores da `TextureWrapMode` enum, que permite os seguintes valores:
  * `TextureWrapMode.TWM_CLAMP`: A textura é apresentada apenas uma vez, no tamanho especificado. O resto da superfície do Mesh fica transparente. O valor de `tiling` é ignorado.
  * `TextureWrapMode.TWM_REPEAT`: A textura repete-se tantas vezes quantas couber no Mesh, usando o tamanho especificado.
  * `TextureWrapMode.TWM_MIRROR`: Tal como no modo de repetição, a textura repete-se tantas vezes quantas couber, mas a orientação das repetições é espelhada.

```ts
Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'assets/materials/wood.png',
		wrapMode: TextureWrapMode.TWM_REPEAT,
		offset: Vector2.create(0, 0.2),
		tiling: Vector2.create(1, 1),
	}),
})
```

{% hint style="warning" %}
**📔 Nota**: As propriedades `offset` e `tiling` só são suportadas no cliente de desktop DCL 2.0.
{% endhint %}

Use esta funcionalidade para cobrir uma superfície grande com um padrão repetido. Por exemplo, repita a seguinte imagem:

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-9fc3c9552e1da78b7ab43f388bab8c2d91b010fd%2Ftiles.webp?alt=media)

```ts
Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'assets/materials/wood.png',
		wrapMode: TextureWrapMode.TWM_REPEAT,
		tiling: Vector2.create(8, 8),
	}),
})
```

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-b432accf316018a223e2902f5dd392b6d5d54c2c%2Ftiles-in-scene.webp?alt=media)

No exemplo abaixo, a textura usa um modo de repetição *espelhado* e cada repetição da textura ocupa apenas 1/4 da superfície. Isto significa que veremos 4 cópias da imagem, espelhadas entre si em ambos os eixos.

```ts
Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'materials/atlas.png',
		wrapMode: TextureWrapMode.TWM_MIRROR,
		tiling: Vector2.create(0.25, 0.25),
	}),
})
```

### Tweens de textura

Faça uma textura deslizar suavemente usando um `Tween` componente, configurado com o `TextureMove` mode. O tween altera gradualmente o valor de `offset` ou das propriedades `tiling` de uma textura ao longo de um período, de forma suave e otimizada.

{% hint style="warning" %}
**📔 Nota**: os Texture Tweens são um recurso compatível apenas com o cliente desktop DCL 2.0.
{% endhint %}

Use o componente `Tween` com a função `setTextureMove` para mover a textura entre duas posições.

```ts
Tween.setTextureMove(myEntity, Vector2.create(0, 0), Vector2.create(1, 0), 2000)
```

O tween de textura recebe as seguintes informações:

* `entity`: A entidade cuja textura será movida
* `start`: Um Vector2 para a posição inicial
* `end` : Um Vector2 para a posição final
* `duration`: O tempo, em milissegundos, necessário para mover entre as duas posições

Também está disponível este parâmetro opcional:

* `movementType`: define se o movimento será no campo `offset` ou no campo `tiling` . Por padrão, usa `offset`.
* `easingFunction`: a curva que define a taxa de mudança ao longo do tempo. O valor padrão é `EasingFunction.EF_LINEAR`. Outros valores fazem a mudança acelerar e/ou desacelerar em taxas diferentes.

```ts
const myEntity = engine.addEntity()

MeshRenderer.setPlane(myEntity)

Transform.create(myEntity, {
	position: Vector3.create(4, 1, 4),
})

Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'materials/water.png',
		wrapMode: TextureWrapMode.TWM_REPEAT,
	}),
})

Tween.setTextureMove(myEntity, Vector2.create(0, 0), Vector2.create(0, 1), 1000)
```

O exemplo acima executa um tween que dura 1 segundo e move a textura apenas uma vez. Para obter um movimento contínuo, por exemplo, para simular a queda de uma cascata, você precisa usar `setTextureMoveContinuous`.

```ts
const myEntity = engine.addEntity()

MeshRenderer.setPlane(myEntity)

Transform.create(myEntity, {
	position: Vector3.create(4, 1, 4),
})

Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'materials/water.png',
		wrapMode: TextureWrapMode.TWM_REPEAT,
	}),
})

Tween.setTextureMoveContinuous(myEntity, Vector2.create(0, 1), 1)
```

O exemplo acima usa `setTextureMoveContinuous`, com uma direção de `(0, 1)`e uma velocidade de 1 unidade por segundo.

O tween contínuo da textura recebe as seguintes informações:

* `entity`: A entidade cuja textura será movida
* `direction`: Um Vector2 para o movimento
* `speed`: Quantas unidades por segundo a entidade se moverá

Estes outros parâmetros opcionais também estão disponíveis:

* `movementType`: define se o movimento será no campo offset ou tiling. Por predefinição, usa offset.
* `duration`: Durante quantos milissegundos o movimento deve manter-se. Após esse período, o movimento irá parar.

**Sequências complexas de tweens**

Você também pode fazer com que os movimentos da textura sigam uma sequência complexa com quantas etapas quiser. Use o campo `sequence` para listar quantos tweens quiser; eles serão executados sequencialmente após o primeiro tween descrito no componente `Tween` .

```ts
//(...)
Tween.setTextureMove(myEntity, Vector2.create(0, 0), Vector2.create(0, 1), 1000)

TweenSequence.create(myEntity, {
	sequence: [
		{
			mode: Tween.Mode.TextureMove({
				start: Vector2.create(0, 1),
				end: Vector2.create(1, 1),
			}),
			duration: 1000,
			easingFunction: EasingFunction.EF_LINEAR,
		},
		{
			mode: Tween.Mode.TextureMove({
				start: Vector2.create(1, 1),
				end: Vector2.create(1, 0),
			}),
			duration: 1000,
			easingFunction: EasingFunction.EF_LINEAR,
		},
		{
			mode: Tween.Mode.TextureMove({
				start: Vector2.create(1, 0),
				end: Vector2.create(0, 0),
			}),
			duration: 1000,
			easingFunction: EasingFunction.EF_LINEAR,
		},
	],
	loop: TweenLoop.TL_RESTART,
})
```

Observe que, ao definir um tween dentro de um TweenSequence, é necessário usar o formato mais detalhado de `Tween.Mode.TextureMove` para definir o tween.

### Texturas com várias camadas

Pode usar vários ficheiros de imagem como camadas para compor texturas mais realistas, por exemplo, incluindo uma `bumpTexture` e uma `emissiveTexture`.

```ts
Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'materials/wood.png',
	}),
	bumpTexture: Material.Texture.Common({
		src: 'materials/woodBump.png',
	}),
	emissiveTexture: Material.Texture.Common({
		src: 'materials/glow.png',
	}),
})
```

A `bumpTexture` pode simular saliências e rugas numa superfície, modificando o comportamento das normais da superfície em cada píxel.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-c10fa878ba8f8a81fa0d124ec6680cde048f20b1%2Fwood-bump.webp?alt=media)

A `emissiveTexture` pode realçar o brilho em determinadas partes de um material, para obter efeitos muito interessantes.

**Definir UVs**

Outra alternativa para alterar a escala ou o alinhamento de uma textura é configurar as propriedades *uv* no componente [MeshRenderer](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/shape-components.md).

Define as coordenadas *u* e *v* na imagem 2D da textura para corresponderem aos vértices da forma. Quanto mais vértices a entidade tiver, mais coordenadas *uv* será necessário definir na textura. Por exemplo, um plano precisa de ter 8 *uv* pontos definidos, 4 para cada uma das duas faces.

```ts
const meshEntity = engine.addEntity()
Transform.create(meshEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setPlane(
	meshEntity,
	[
		0, 0.75,

		0.25, 0.75,

		0.25, 1,

		0, 1,

		0, 0.75,

		0.25, 0.75,

		0.25, 1,

		0, 1,
	]
)

Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'materials/wood.png',
		wrapMode: TextureWrapMode.TWM_REPEAT,
	}),
})
```

O exemplo seguinte inclui uma função que simplifica a definição de UVs. A função `setUVs` aqui definida recebe como parâmetros o número de linhas e colunas e define os UVs para que a imagem da textura se repita um número específico de vezes.

```ts
const meshEntity = engine.addEntity()
Transform.create(meshEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(meshEntity, setUVs(3, 3))

Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'materials/atlas.png',
		wrapMode: TextureWrapMode.TWM_REPEAT,
	}),
})

function setUVs(rows: number, cols: number) {
	return [
		// Lado norte do plano sem rotação
		0, // canto inferior esquerdo
		0,

		cols, // canto inferior direito
		0,

		cols, // canto superior direito
		rows,

		0, // canto superior esquerdo
		rows,

		// Lado sul do plano sem rotação
		cols, // canto inferior direito
		0,

		0, // canto inferior esquerdo
		0,

		0, // canto superior esquerdo
		rows,

		cols, // canto superior direito
		rows,
	]
}
```

Para definir os UVs de um `box` forma mesh, aplica-se a mesma estrutura. Cada uma das 6 faces do cubo recebe 4 pares de coordenadas, um para cada vértice. Todos estes 48 valores são apresentados num único array.

{% hint style="warning" %}
**📔 Nota**: as propriedades Uv estão atualmente disponíveis apenas em `plane` e em formas `box` . Além disso, os valores de *uv* afetam todas as camadas de textura da mesma forma, uma vez que são definidos na *forma*.
{% endhint %}

### Escala da textura

Quando as texturas são esticadas ou reduzidas para um tamanho diferente do da imagem de textura original, podem surgir artefactos. Num ambiente 3D, os efeitos da perspetiva provocam isto naturalmente. Existem vários algoritmos de [filtragem de texturas](https://en.wikipedia.org/wiki/Texture_filtering) que compensam este efeito de diferentes formas.

O objeto `Material` usa o algoritmo *bilinear* por predefinição, mas permite configurá-lo para usar os algoritmos *vizinho mais próximo* ou *trilinear* definindo a propriedade `filterMode` da textura. Esta propriedade recebe um valor do enum `TextureFilterMode` :

* `TextureFilterMode.TFM_POINT`: usa um algoritmo de «vizinho mais próximo». Esta definição é ideal para gráficos em estilo pixel art, pois os contornos permanecem bem definidos quando a textura é ampliada no ecrã, em vez de ficarem desfocados.
* `TextureFilterMode.TFM_BILINEAR`: usa um algoritmo bilinear para estimar a cor de cada pixel.
* `TextureFilterMode.TFM_TRILINEAR`: usa um algoritmo trilinear para estimar a cor de cada pixel.

```ts
Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'materials/atlas.png',
		filterMode: TextureFilterMode.TFM_BILINEAR,
	}),
})
```

## Materiais não iluminados

Na maioria das vezes, vai querer que os materiais na sua Scene sejam afetados pelas condições de iluminação, incluindo as sombras e as alterações de tonalidade causadas pelas diferentes horas do dia. Noutros casos, porém, poderá querer apresentar as cores no seu estado puro. Isto é útil ao reproduzir vídeos ou para marcadores abstratos que precisam de se destacar e que servem para dar indicações ao jogador.

Para criar um material não iluminado, use `Material.setBasicMaterial`. Os materiais básicos não têm todas as propriedades dos materiais PBR; incluem apenas as essenciais:

* `diffuseColor`: Color4 para a cor
* `texture`: textura
* `alphaTexture`: textura separada para a camada de transparência
* `alphaTest`: limite para obter transparência com base na cor da textura
* `castShadows`: se for false, não são projetadas sombras sobre outras Entities na Scene.

```ts
Material.setBasicMaterial(screen, {
	diffuseColor: Color4.Red(),
})
```

## Retratos de Avatar

Para apresentar uma imagem em miniatura de qualquer jogador, use `Material.Texture.Avatar` ao definir a textura do seu material, passando o endereço de um jogador existente. Isto cria uma textura a partir de uma imagem de 256x256 do jogador, mostrando a cabeça e os ombros. O jogador é apresentado com o conjunto de wearables que o servidor atual registou pela última vez.

```ts
Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Avatar({
		userId: '0x517....',
	}),
})
```

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-7d9533dc2cdb50a2250e230346b85e1b458c6cc3%2FavatarTexture.webp?alt=media)

Pode obter o retrato de qualquer jogador de Decentraland, mesmo que não esteja ligado neste momento e mesmo que não tenha um nome de Decentraland reivindicado.

O objeto que passar como argumento suporta as seguintes propriedades:

* `userId`: ID do utilizador cujo perfil pretende apresentar
* `filterMode`: Determina como os píxeis da textura são esticados ou comprimidos durante a renderização. Aceita um valor do enum `TextureFilterMode` . Consulte [Escalamento de texturas](#texture-scaling).
* `wrapMode`: Determina como uma textura é aplicada em mosaico num objeto. Aceita um valor do enum `TextureWrapMode` enum. Consulte [Repetição da textura](#texture-wrapping).

## Materiais transparentes

Para tornar transparente um material com uma cor uniforme, basta definir a cor como um `Color4`, e definir o 4.º valor com um valor entre *0* e *1*. Quanto mais próximo de *1*, mais opaco será.

```typescript
let transparentRed = Color4.create(1, 0, 0, 0.5)

Material.setPbrMaterial(meshEntity, {
	albedoColor: transparentRed,
})
```

Se um material usar uma textura .png que inclua transparência, será opaco por predefinição, mas pode ativar a transparência definindo `transparencyMode` como `MaterialTransparencyMode.MTM_ALPHA_BLEND`.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-4cfaaf2d24f923ceb5187b0b2d5039ec049085bf%2Ftransparent-image.webp?alt=media)

```typescript
Material.setPbrMaterial(floor, {
	texture: Material.Texture.Common({
		src: 'assets/scene/transparent-image.png',
	}),
	transparencyMode: MaterialTransparencyMode.MTM_ALPHA_BLEND,
})
```

O `transparencyMode` pode ter os seguintes valores:

* `MaterialTransparencyMode.MTM_OPAQUE`: Sem transparência
* `MaterialTransparencyMode.MTM_ALPHA_TEST`: Cada pixel é totalmente opaco ou totalmente transparente, consoante um limite.
* `MaterialTransparencyMode.MTM_ALPHA_BLEND`: São possíveis valores intermédios, consoante o valor de cada pixel.
* `MaterialTransparencyMode.MTM_ALPHA_TEST_AND_ALPHA_BLEND`: Utiliza uma combinação dos dois métodos.
* `MaterialTransparencyMode.MTM_AUTO`: Determina o método com base na textura fornecida.

{% hint style="warning" %}
**📔 Nota**: Defina sempre `transparencyMode` manualmente quando quiser que o canal alfa da própria textura seja visível. No cliente para computador, o modo predefinido `MTM_AUTO` ignora o alfa da textura e só mistura quando o alfa de `albedoColor` é inferior a 1. Por isso, um `.png` transparente fica totalmente opaco. Com `MTM_ALPHA_BLEND` ou `MTM_ALPHA_TEST`, a transparência é o alfa da textura multiplicado pelo `albedoColor` alfa.
{% endhint %}

Se definir o `transparencyMode` como `MaterialTransparencyMode.MTM_ALPHA_TEST`, pode ajustar com precisão o limite usado para determinar se cada píxel é transparente ou não. Defina a propriedade `alphaTest` entre *0* e *1*. O valor predefinido é *0.5*.

```ts
// Using alpha test
Material.setPbrMaterial(meshEntity1, {
	texture: Material.Texture.Common({
		src: 'images/myTexture.png',
	}),
	transparencyMode: MaterialTransparencyMode.MTM_ALPHA_TEST,
	alphaTest: 1,
})
```

Ao usar um [material não iluminado](#unlit-materials), pode adicionar uma `alphaTexture` para tornar transparentes apenas determinadas regiões do material, com base numa textura.

{% hint style="warning" %}
**📔 Nota**: Pinte a máscara de branco onde o material deve aparecer e de preto onde deve desaparecer. O cliente lê o brilho dos canais de cor da máscara, e não o respetivo canal alfa, por isso qualquer canal com valor máximo conta como opaco: uma máscara vermelha pura também é opaca. Não reutilize a textura de cor como máscara, pois todos os píxeis escuros ficarão transparentes, eliminando os contornos e o sombreado.
{% endhint %}

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-901568ee2ece2fed1734c93716d4c7069869c47c%2Fcircular-video-screen.webp?alt=media)

```ts
// Using alpha test
Material.setBasicMaterial(meshEntity1, {
	texture: Material.Texture.Common({
		src: 'images/myTexture.png',
	}),
	alphaTexture: Material.Texture.Common({
		src: 'assets/scene/circle_mask.png',
		wrapMode: TextureWrapMode.TWM_MIRROR,
	}),
})
```

Há mais duas coisas a saber sobre `alphaTexture` no cliente para computadores:

* **Só funciona com materiais não iluminados.** `Material.setPbrMaterial` aceita uma `alphaTexture` , mas nunca a utiliza. Para um material PBR, coloque a transparência no próprio canal alfa da textura de cor e defina `transparencyMode` em vez disso.
* **Um material não iluminado sem uma `alphaTexture` é totalmente opaco**, e `alphaTest` não tem qualquer efeito sobre ele. Uma `texture` mais `alphaTest` por si só desenha a cor dos píxeis transparentes, que normalmente é preto.

Isto pode ser usado de formas muito interessantes em conjunto com vídeos. Consulte [vídeo em reprodução](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/media/video-playing.md).

## Reprodução de vídeo

Para transmitir vídeo de um URL para um material ou reproduzir um vídeo a partir de um ficheiro armazenado na cena, consulte [vídeo em reprodução](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/media/video-playing.md).

O vídeo é usado como uma textura num material. Pode definir qualquer uma das outras propriedades dos materiais para alterar o aspeto do ecrã de vídeo.

## Sintaxe avançada

A sintaxe completa para criar um `Materials` component, sem quaisquer funções auxiliares para simplificar o processo, é a seguinte:

```ts
Material.create(myEntity, {
	material: {
		$case: 'pbr',
		pbr: {
			texture: {
				tex: {
					$case: 'texture',
					texture: {
						src: 'images/scene-thumbnail.png',
					},
				},
			},
		},
	},
})

Material.create(myEntity, {
	material: {
		$case: 'pbr',
		pbr: {
			texture: {
				tex: {
					$case: 'avatarTexture',
					avatarTexture: {
						userId: '0x517....',
					},
				},
			},
		},
	},
})
```

É assim que o protocolo base interpreta os componentes Materials. As funções auxiliares abstraem este processo e disponibilizam uma sintaxe mais simples, mas, nos bastidores, geram esta sintaxe.

Os campos `$case` permitem especificar um dos tipos permitidos. Cada tipo suporta um conjunto diferente de parâmetros. Existem dois níveis de `$case` aqui:

* O campo `material` suporta os valores `pbr` e `unlit`, para definir o tipo de material.
* O campo `tex` dentro de uma textura suporta os seguintes valores, que definem o tipo de textura:
  * `texture`
  * `avatarTexture`
  * `videoTexture`

Consoante o valor de `$case`, é válido definir o objeto do tipo correspondente, passando quaisquer propriedades relevantes.

Para adicionar um componente `Material` a uma entidade que já possa ter uma instância deste componente, use `Material.createOrReplace()`. As funções auxiliares, como `Material.setPbrMaterial()` tratam da substituição de instâncias existentes do componente, mas executar `Material.create()` numa entidade que já tenha este componente devolve um erro.

## Modificar materiais glTF

Use o componente `GltfNodeModifiers` para modificar os materiais de um *glTF* modelo. Este Component permite substituir os Materials de um *glTF* modelo pelos seus próprios Materials. Pode utilizar qualquer uma das propriedades do `Material` Component, incluindo textura, textura de vídeo, Materials sem iluminação, etc.

Existem duas formas de utilizar o Component `GltfNodeModifiers` :

* Modifique o Material do modelo inteiro deixando a propriedade `path` como uma string vazia.
* Modifique o Material de um nó específico do modelo (ou de vários nós) definindo a propriedade `path` com o caminho para o nó.

### Modificar o Material do modelo inteiro

O exemplo seguinte mostra como modificar o Material de um modelo *glTF* . Neste caso, o Material do modelo inteiro é alterado para vermelho.

```ts
import { GltfNodeModifiers, GltfContainer, Transform } from '@dcl/sdk/ecs'

const myEntity = engine.addEntity()

GltfContainer.create(myEntity, {
	src: 'models/myModel.glb',
})

Transform.create(myEntity, {
	position: Vector3.create(4, 0, 4),
})

GltfNodeModifiers.create(myEntity, {
	modifiers: [
		{
			path: '',
			material: {
				material: {
					$case: 'pbr',
					pbr: {
						albedoColor: Color4.Red(),
					},
				},
			},
		},
	],
})
```

O `GltfNodeModifiers` Component tem as seguintes propriedades:

* `modifiers`: Uma matriz de modificadores. Cada modificador tem as seguintes propriedades:
  * `path`: O caminho para o nó do modelo a modificar.
  * `material`: O Material a utilizar.

A propriedade `path` é uma string que representa o caminho para o nó do modelo *glTF* a modificar. Se quiser modificar o Material do modelo inteiro, pode utilizar uma string vazia. Se quiser modificar o Material de um nó específico, pode utilizar o caminho para esse nó. O caminho tem de apontar para um nó Mesh, não para um nó de vértice.

{% hint style="info" %}
**💡 Dica**: Pode utilizar a aplicação [Babylon Sandbox](https://sandbox.babylonjs.com/) para inspecionar o modelo *glTF* e encontrar o caminho para o nó que pretende modificar.

No entanto, em alguns modelos, o Babylon Sandbox pode apresentar caminhos que pertencem a vértices em vez de Meshes, e estes não funcionarão. Se tentar utilizar um caminho inválido, a consola da Scene apresentará uma mensagem de erro que inclui a lista completa dos caminhos válidos para esse modelo.
{% endhint %}

A propriedade `material` é um objeto que representa o Material a utilizar. Tem de ser escrita com a [sintaxe avançada](#advanced-syntax) para Materials, tal como mostrado no exemplo acima. Funções auxiliares como `Material.setPbrMaterial()` não pode ser utilizado aqui.

### Modificar o material de um nó específico do modelo

O exemplo seguinte mostra como modificar o material de um nó específico do modelo *glTF* . Neste caso, o material da cabeça é modificado para utilizar uma textura alternativa.

```ts
import { GltfNodeModifiers, GltfContainer, Transform } from '@dcl/sdk/ecs'

const myEntity = engine.addEntity()

GltfContainer.create(myEntity, {
	src: 'models/myModel.glb',
})

Transform.create(myEntity, {
	position: Vector3.create(4, 0, 4),
})

GltfNodeModifiers.create(myEntity, {
	modifiers: [
		{
			path: 'M_Head_BaseMesh',
			material: {
				material: {
					$case: 'pbr',
					pbr: {
						texture: Material.Texture.Common({
							src: 'assets/scene/images/blinking-head.png',
						}),
					},
				},
			},
		},
	],
})
```

Um `GltfNodeModifiers` pode conter vários modificadores, cada um modificando um nó diferente do modelo. O exemplo seguinte mostra como modificar o material da cabeça e do corpo de um modelo *glTF* .

```ts
import { GltfNodeModifiers, GltfContainer, Transform } from '@dcl/sdk/ecs'

const myEntity = engine.addEntity()

GltfContainer.create(myEntity, {
	src: 'models/myModel.glb',
})

Transform.create(myEntity, {
	position: Vector3.create(4, 0, 4),
})

GltfNodeModifiers.create(myEntity, {
	modifiers: [
		{
			path: 'M_Head_BaseMesh',
			material: {
				material: {
					$case: 'pbr',
					pbr: {
						albedoColor: Color4.Red(),
					},
				},
			},
		},
		{
			path: 'M_Body_BaseMesh',
			material: {
				material: {
					$case: 'pbr',
					pbr: {
						albedoColor: Color4.Blue(),
					},
				},
			},
		},
	],
})
```

### Modificar campos de um material existente

O componente Material fornece uma interface simplificada para aceder às propriedades do componente Material e modificá-las. Elimina a necessidade de navegar por estruturas de união profundamente aninhadas (`PBR` vs `Unlit`, `texture` vs `avatarTexture` vs `videoTexture`), tornando a manipulação de materiais mais intuitiva e menos propensa a erros.

Os métodos seguintes permitem manipular facilmente o componente `Material` :

* `Material.getFlat(entity: Entity): ReadonlyFlatMaterial`: Devolve um objeto acessor **só de leitura** `FlatMaterial` que permite o acesso direto às propriedades do material, apenas para leitura. Devolve um erro se a entidade não tiver um componente `Material` . Para evitar esta situação, podem utilizar-se os métodos seguintes como alternativa.

```ts
const src = Material.getFlat(entity).texture.src
```

* `Material.getFlatOrNull(entity: Entity): ReadonlyFlatMaterial | null`: Devolve um objeto **só de leitura ou null**, consoante a entidade tenha ou não um componente `Material` .

```ts
const src = Material.getFlatOrNull(entity)?.texture.src
```

* `Material.getFlatMutable(entity: Entity): FlatMaterial`: Devolve um objeto **de leitura e escrita** `FlatMaterial`que permite modificar as respetivas propriedades. Lança um erro se a entidade chamada não tiver o componente `Material` .

```ts
const src = Material.getFlatMutable(entity).texture.src
```

* `Material.getFlatMutableOrNull(entity: Entity): FlatMaterial | null`: Devolve um(a) **de leitura e escrita ou null** `FlatMaterial` objeto que permite modificar as respetivas propriedades. Se a entidade não tiver um `Material component`, devolve `null`.

```ts
const flatMaterial = Material.getFlatMutableOrNull(entity)
if (flatMaterial) {
	flatMaterial.texture.src = myNewTextureFile
}
```

### Remover sombras de um modelo glTF

Para remover sombras de um modelo *glTF* , pode definir a propriedade `castShadows` como `false` no objeto `GltfNodeModifiers` . Isto mantém o material original do modelo, mas impede-o de projetar sombras. Esta opção é útil para modelos que não devem projetar sombras, como feixes de luz.

```ts
import { GltfNodeModifiers } from '@dcl/sdk/ecs'

GltfNodeModifiers.create(myEntity, {
	modifiers: [
		{
			path: '',
			castShadows: false,
		},
	],
})
```

{% hint style="info" %}
**💡 Dica**: As texturas usadas em materiais também podem ser aplicadas a efeitos de partículas. Consulte [Particle System](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/particle-system.md) para obter detalhes sobre como usar texturas personalizadas e folhas de sprites com partículas.
{% endhint %}

{% hint style="info" %}
**💡 Dica**: Para ver exemplos práticos de materiais, consulte a [`52,-52-testing-gallery`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/52,-52-testing-gallery) cena de teste, que percorre combinações PBR de metálico/rugosidade/emissão/mapa de normais lado a lado, [`74,-8-gltfnodemodifier`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/74,-8-gltfnodemodifier), que substitui materiais PBR e não iluminados em nós GLTF individuais, e [`0,3-texture-movement`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0,3-texture-movement), que anima o deslocamento e a repetição da textura.
{% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/materials.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
