> 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-es/scenes-sdk7/fundamentos-del-contenido-3d/materials.md).

# Materiales

Aprende cómo añadir materiales y texturas a entidades con formas primitivas.

## Materials

Los materiales se pueden aplicar a entidades que usan formas primitivas (cubo, esfera, plano, etc.) agregando un `Material` component. Este componente tiene varios campos que permiten configurar las propiedades del material, agregar una textura, etc.

*glTF* Los modelos incluyen sus propios materiales, que se importan implícitamente a una escena junto con el modelo. Para modificar o sobrescribir estos materiales, usa el `GltfNodeModifiers` component. Consulta [Modificar materiales glTF](#modify-gltf-materials) para obtener más información.

Al importar un modelo 3D con sus propios materiales, ten en cuenta que el motor de Decentraland no admite todos los shaders. Solo admite materiales estándar y materiales PBR (renderizado basado en la física). Consulta [Consideraciones sobre modelos 3D externos](https://github.com/decentraland/docs/blob/main/creator/3d-modeling/materials.md) para obtener más información.

Hay distintos tipos de materiales compatibles:

* PBR (renderizado basado en la física): el tipo de material más común en Decentraland. Admite colores sólidos o texturas, y distintas propiedades como metalicidad, emisión, transparencia, etc. Obtén más información sobre [PBR](https://en.wikipedia.org/wiki/Physically_based_rendering).
* Materiales básicos: no responden a las luces ni a las sombras, por lo que son ideales para mostrar imágenes de tipo billboard.

## Usa Scene Editor en Creator Hub

La forma más sencilla de asignar un Material a una entidad es usar el Scene Editor. Puedes agregar un **Material** component a tu entidad y configurar todos los campos disponibles en la UI del Scene Editor. Consulta [Agregar componentes](https://docs.decentraland.org/creator/content-creator-es/scene-editor/construir/components.md#add-components).

## Agregar un material

El siguiente ejemplo crea un material PBR y configura algunos de sus campos para darle un color rojo y propiedades metálicas. Este material se agrega a una entidad que también tiene una forma de caja, por lo que coloreará la caja con este material.

```ts
//Crear entidad y asignar forma
const meshEntity = engine.addEntity()
Transform.create(meshEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(meshEntity)

//Crear material y configurar sus campos
Material.setPbrMaterial(meshEntity, {
	albedoColor: Color4.Red(),
	metallic: 0.8,
	roughness: 0.1,
})
```

Para cambiar el material de una entidad que ya tiene un `Material` component, ejecuta `Material.setPbrMaterial()` o cualquiera de las otras funciones auxiliares para sobrescribir el material original. No es necesario quitar el original `Material` ni usar la sintaxis avanzada.

```ts
//Crear entidad y asignar forma
const meshEntity = engine.addEntity()
Transform.create(meshEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(meshEntity)

//Crear material y configurar sus campos
Material.setPbrMaterial(meshEntity, {
	albedoColor: Color4.Red(),
})

//Sobrescribir con un nuevo componente de material
Material.setPbrMaterial(meshEntity, {
	albedoColor: Color4.Blue(),
})
```

{% hint style="warning" %}
**📔 Nota**: el componente `Material` debe importarse mediante

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

Consulta [Importaciones](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/primeros-pasos/coding-scenes.md#imports) para saber cómo gestionarlas fácilmente.
{% endhint %}

## Colores de los materiales

Asigna un color sólido a un material. En un Material PBR, configura el campo `albedoColor` . Los colores albedo responden a la luz y pueden incluir sombras.

Los valores de color son de tipo `Color4`, compuesto por *r*, *g* y *b* valores (rojo, verde y azul). Cada uno de estos valores puede estar entre 0 y 1. Al asignarles distintos valores, puedes componer cualquier color visible. Para el negro, asigna 0 a los tres. Para el blanco, asígnales 1 a todos.

{% hint style="warning" %}
**📔 Nota**: Si asignas a cualquier color de `albedoColor` un valor superior a *1*, aparecerá como *emissive*, con mayor intensidad cuanto más alto sea el valor. Por ejemplo, `{r: 15, g: 0, b: 0}` produce un resplandor rojo muy intenso.
{% endhint %}

Consulta [tipos de color](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/color-types.md) para obtener más detalles sobre cómo asignar colores.

También puedes editar los siguientes campos de un Material PBR para ajustar con precisión cómo se percibe su color:

* *emissiveColor*: El color que emite el material.
* *reflectivityColor*: también conocido como *Color especular* en otras nomenclaturas.

Para crear un material de color uniforme que no se vea afectado por la luz ni las sombras del entorno, crea un material básico en lugar de un material PBR.

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

## Usar texturas

Asigna un archivo de imagen como textura de un material configurando el parámetro `texture` .

```ts
//Crear entidad y asignar forma
const meshEntity = engine.addEntity()
Transform.create(meshEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(meshEntity)

//Crear material y configurar sus campos
Material.setPbrMaterial(meshEntity, {
	texture: Material.Texture.Common({
		src: 'assets/materials/wood.png',
	}),
})
```

En el ejemplo anterior, la imagen del material se encuentra en la carpeta `assets/materials` , ubicada en el nivel raíz de la carpeta del proyecto de la escena.

{% hint style="info" %}
**💡 Consejo**: Recomendamos guardar los archivos de imagen de las texturas en la carpeta `/assets` dentro de la escena.
{% endhint %}

Al crear una textura, también puedes pasar parámetros adicionales:

* `filterMode`: Determina cómo se estiran o comprimen los píxeles de la textura al renderizarla. Este parámetro acepta un valor del enum `TextureFilterMode` . Consulta [Escalado de texturas](#texture-scaling).
* `wrapMode`: Determina cómo se repite una textura sobre un objeto. Este parámetro acepta un valor del enum `TextureWrapMode` enumeración. Consulta [Repetición de texturas](#texture-wrapping).

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

Para crear una textura que no se vea afectada por la luz ni las sombras del entorno, crea un material básico en lugar de un material PBR.

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

### Texturas desde una URL externa

Puedes asignar a la textura de tu material una URL externa en lugar de una ruta interna del proyecto de la escena.

```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',
	}),
})
```

La URL debe comenzar con `https`, `http` no son compatibles.

### Repetición de texturas

Puedes definir cómo se alinea una textura con una superficie. De forma predeterminada, la textura se estira para ocupar la superficie una vez, pero puedes escalarla y desplazarla.

Los siguientes campos están disponibles en todas las texturas:

* `offset`: desplaza la textura para cambiar su alineación. El valor es un Vector2, cuyos dos ejes van de 0 a 1, donde 1 representa el ancho o el alto total de la textura.
* `tiling`: escala la textura. El valor predeterminado es el Vector2 `[1, 1]`, que hace que la imagen se repita una vez y cubra toda la superficie.
* `TextureWrapMode`: determina qué ocurre si el mosaico de la imagen no cubre toda la superficie. Esta propiedad acepta valores de la `TextureWrapMode` enumeración, que ofrece los siguientes valores:
  * `TextureWrapMode.TWM_CLAMP`: la textura se muestra una sola vez con el tamaño especificado. El resto de la superficie del Mesh queda transparente. Se ignora el valor de `tiling` .
  * `TextureWrapMode.TWM_REPEAT`: la textura se repite tantas veces como quepa en el Mesh, usando el tamaño especificado.
  * `TextureWrapMode.TWM_MIRROR`: al igual que en el modo de repetición, la textura se repite tantas veces como quepa, pero la orientación de las repeticiones se refleja.

```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**: las propiedades `offset` y `tiling` solo son compatibles con el cliente de escritorio DCL 2.0.
{% endhint %}

Usa esta función para cubrir una superficie grande con un patrón repetido. Por ejemplo, repite la siguiente imagen:

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

En el ejemplo siguiente, la textura usa un modo de repetición *en espejo* y cada repetición de la textura ocupa solo 1/4 de la superficie. Esto significa que veremos 4 copias de la imagen, reflejadas entre sí en ambos ejes.

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

Haz que una textura se desplace suavemente usando un `Tween` componente, configurado con el `TextureMove` modo. El tween cambia gradualmente el valor de las propiedades `offset` o `tiling` de una textura a lo largo del tiempo, de forma fluida y optimizada.

{% hint style="warning" %}
**📔 Nota**: los Texture Tweens solo son compatibles con el cliente de escritorio DCL 2.0.
{% endhint %}

Usa el componente `Tween` con la función `setTextureMove` para mover la textura entre dos posiciones.

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

El tween de textura recibe la siguiente información:

* `entity`: La Entity cuya textura se moverá
* `start`: Un Vector2 para la posición inicial
* `end`: Un Vector2 para la posición final
* `duration`: Cuántos milisegundos tarda en moverse entre las dos posiciones

También está disponible este otro parámetro opcional:

* `movementType`: define si el movimiento se aplicará al campo `offset` o al campo `tiling` . De forma predeterminada, usa `offset`.
* `easingFunction`: la curva que determina la tasa de cambio a lo largo del tiempo. El valor predeterminado es `EasingFunction.EF_LINEAR`. Otros valores hacen que el cambio acelere o desacelere a distintas velocidades.

```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)
```

El ejemplo anterior ejecuta un tween que dura 1 segundo y mueve la textura una sola vez. Para conseguir un movimiento continuo, por ejemplo, para simular la caída de una cascada, debes 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)
```

En el ejemplo anterior se usa `setTextureMoveContinuous`, con una dirección de `(0, 1)`y una velocidad de 1 unidad por segundo.

El tween continuo de textura requiere la siguiente información:

* `entity`: La Entity cuya textura se moverá
* `direction`: Un Vector2 para el movimiento
* `speed`: Cuántas unidades por segundo se moverá la entidad

También están disponibles estos otros parámetros opcionales:

* `movementType`: Define si el movimiento se realizará en el campo de desplazamiento o en el de repetición de textura. De forma predeterminada, se usa el desplazamiento.
* `duration`: Cuántos milisegundos se mantendrá el movimiento. Transcurrido ese tiempo, el movimiento se detendrá.

**Secuencias de tween complejas**

También puedes hacer que los movimientos de la textura sigan una secuencia compleja con tantos pasos como quieras. Usa el campo `sequence` para enumerar todos los tweens que quieras; se ejecutarán secuencialmente después del primer tween descrito en el 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,
})
```

Ten en cuenta que, al definir un tween dentro de un TweenSequence, debes usar el formato más detallado de `Tween.Mode.TextureMove` para definir el tween.

### Texturas multicapa

Puedes usar varios archivos de imagen como capas para componer texturas más realistas, por ejemplo, incluir una `bumpTexture` y una `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',
	}),
})
```

La `bumpTexture` puede simular bultos y arrugas en una superficie modificando el comportamiento de sus normales en cada píxel.

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

La `emissiveTexture` puede acentuar el brillo de ciertas partes de un Material para lograr efectos muy interesantes.

**Configurar las UV**

Otra alternativa para cambiar la escala o la alineación de una textura es configurar las propiedades *uv* en el componente [MeshRenderer](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/shape-components.md).

Se configuran las coordenadas *u* y *v* en la imagen 2D de la textura para que correspondan con los vértices de la forma. Cuantos más vértices tenga la entidad, más coordenadas *uv* habrá que definir en la textura. Por ejemplo, un plano necesita 8 *uv* puntos definidos, 4 para cada una de sus dos caras.

```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,
	}),
})
```

El siguiente ejemplo incluye una función que simplifica la configuración de las UV. La función `setUVs` definida aquí recibe como parámetros un número de filas y columnas, y configura las UV para que la imagen de textura se repita una cantidad específica de veces.

```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 [
		// Cara norte del plano sin rotar
		0, //esquina inferior izquierda
		0,

		cols, //esquina inferior derecha
		0,

		cols, //esquina superior derecha
		rows,

		0, //esquina superior izquierda
		rows,

		// Cara sur del plano sin rotar
		cols, // esquina inferior derecha
		0,

		0, // esquina inferior izquierda
		0,

		0, // esquina superior izquierda
		rows,

		cols, // esquina superior derecha
		rows,
	]
}
```

Para configurar las UV de un `box` forma mesh, se aplica la misma estructura. Cada una de las 6 caras del cubo usa 4 pares de coordenadas, uno por cada vértice. Los 48 valores se enumeran en un único array.

{% hint style="warning" %}
**📔 Nota**: Las propiedades Uv actualmente solo están disponibles en `plane` y en las formas `box` . Además, los valores de *uv* afectan a todas las capas de textura por igual, ya que se establecen en la *forma*.
{% endhint %}

### Escalado de texturas

Cuando las texturas se estiran o se encogen a un tamaño diferente al de la imagen de textura original, a veces pueden aparecer artefactos. En un entorno 3D, los efectos de la perspectiva producen esto de forma natural. Existen varios algoritmos de [filtrado de texturas](https://en.wikipedia.org/wiki/Texture_filtering) para compensarlo de distintas maneras.

El objeto `Material` usa el algoritmo *bilineal* de forma predeterminada, pero permite configurarlo para que use los algoritmos de *vecino más cercano* o *trilineal* en su lugar, estableciendo la propiedad `filterMode` de la textura. Esta propiedad acepta un valor del enum `TextureFilterMode` :

* `TextureFilterMode.TFM_POINT`: Usa un algoritmo de «vecino más cercano». Esta opción es ideal para gráficos de estilo pixel art, ya que los contornos se mantienen bien definidos cuando la textura se muestra ampliada en pantalla, en lugar de verse borrosos.
* `TextureFilterMode.TFM_BILINEAR`: Usa un algoritmo bilineal para calcular el color de cada píxel.
* `TextureFilterMode.TFM_TRILINEAR`: Usa un algoritmo trilineal para calcular el color de cada píxel.

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

## Materiales sin iluminación

La mayoría de las veces querrás que los materiales de tu escena se vean afectados por las condiciones de iluminación, incluidas las sombras y los cambios de tono según la hora del día. Sin embargo, en otros casos quizá quieras mostrar los colores en su estado puro. Esto resulta útil al reproducir videos, o para marcadores abstractos que deban destacar y que sirvan para mostrar indicaciones al jugador.

Para crear un material sin iluminación, usa `Material.setBasicMaterial`. Los materiales básicos no tienen todas las propiedades de los materiales PBR; solo tienen las esenciales:

* `diffuseColor`: Color4 para el color
* `texture`: Textura
* `alphaTexture`: Textura independiente para la capa de transparencia
* `alphaTest`: Umbral para lograr la transparencia según el color de la textura
* `castShadows`: Si es false, no se proyectan sombras sobre otras entidades de la escena.

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

## Retratos de Avatares

Para mostrar una imagen en miniatura de cualquier jugador, usa `Material.Texture.Avatar` al establecer la textura de tu material, pasando la dirección de un jugador existente. Esto crea una textura a partir de una imagen de 256x256 del jugador, que muestra la cabeza y los hombros. El jugador aparece con el conjunto de Wearables que el servidor actual registró por última vez.

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

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

Puedes obtener el retrato de cualquier jugador de Decentraland, aunque no esté conectado en ese momento e incluso si no tiene un nombre de Decentraland reclamado.

Se admiten las siguientes propiedades dentro del objeto que pasas como argumento:

* `userId`: ID del usuario cuyo perfil quieres mostrar
* `filterMode`: Determina cómo se estiran o comprimen los píxeles de la textura al renderizarla. Este parámetro acepta un valor del enum `TextureFilterMode` . Consulta [Escalado de texturas](#texture-scaling).
* `wrapMode`: Determina cómo se repite una textura sobre un objeto. Este parámetro acepta un valor del enum `TextureWrapMode` enumeración. Consulta [Repetición de texturas](#texture-wrapping).

## Materiales transparentes

Para hacer transparente un material de color uniforme, simplemente define el color como un `Color4`, y establece el cuarto valor entre *0* y *1*. Cuanto más cerca esté de *1*, más opaco será.

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

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

Si un material usa una textura .png que incluye transparencia, será opaco de forma predeterminada, pero puedes activar su transparencia estableciendo `transparencyMode` en `MaterialTransparencyMode.MTM_ALPHA_BLEND`.

![](https://1216664193-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,
})
```

El `transparencyMode` puede tener los siguientes valores:

* `MaterialTransparencyMode.MTM_OPAQUE`: Sin transparencia
* `MaterialTransparencyMode.MTM_ALPHA_TEST`: Cada píxel es completamente opaco o completamente transparente, según un umbral.
* `MaterialTransparencyMode.MTM_ALPHA_BLEND`: Se permiten valores intermedios según el valor de cada píxel.
* `MaterialTransparencyMode.MTM_ALPHA_TEST_AND_ALPHA_BLEND`: Usa una combinación de ambos métodos.
* `MaterialTransparencyMode.MTM_AUTO`: Determina el método según la textura proporcionada.

{% hint style="warning" %}
**📔 Nota**: Establece siempre `transparencyMode` manualmente cuando quieras que se muestre el canal alfa de la propia textura. En el cliente de escritorio, el modo predeterminado `MTM_AUTO` ignora el canal alfa de la textura y solo mezcla cuando el alfa de `albedoColor` es inferior a 1, por lo que un `.png` transparente se muestra completamente opaco. Con `MTM_ALPHA_BLEND` o `MTM_ALPHA_TEST`, la transparencia es el alfa de la textura multiplicado por el `albedoColor` alfa.
{% endhint %}

Si configuras `transparencyMode` en `MaterialTransparencyMode.MTM_ALPHA_TEST`, puedes ajustar con precisión el umbral que se usa para determinar si cada píxel es transparente o no. Configura la propiedad `alphaTest` entre *0* y *1*. De forma predeterminada, su valor es *0.5*.

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

Al usar un [material unlit](#unlit-materials), puedes añadir un `alphaTexture` para hacer que solo ciertas zonas del material sean transparentes, según una textura.

{% hint style="warning" %}
**📔 Nota**: Pinta la máscara de blanco en las zonas donde debe verse el material y de negro donde debe desaparecer. El cliente lee el brillo de los canales de color de la máscara, no su canal alfa, así que cualquier canal con valor máximo cuenta como opaco: una máscara de color rojo puro también es opaca. No reutilices la textura de color como su propia máscara, porque cada píxel oscuro de la textura se volverá transparente y eliminará los contornos y el sombreado.
{% endhint %}

![](https://1216664193-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
// Recortar una pantalla en forma de círculo con una imagen de máscara
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,
	}),
})
```

Hay dos cosas más que debes saber sobre `alphaTexture` en el cliente de escritorio:

* **Solo funciona con materiales unlit.** `Material.setPbrMaterial` acepta un `alphaTexture` pero nunca lo usa. En un material PBR, coloca la transparencia en el propio canal alfa de la textura de color y configura `transparencyMode` en su lugar.
* **Un material unlit sin `alphaTexture` es completamente opaco**, y `alphaTest` no tiene ningún efecto. Una `texture` más `alphaTest` por sí sola dibuja el color de los píxeles transparentes, que suele ser negro.

Esto puede combinarse de formas muy interesantes con videos. Consulta [reproducción de video](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/media/video-playing.md).

## Reproducción de video

Para transmitir video desde una URL a un material o reproducir un video desde un archivo almacenado en la escena, consulta [reproducción de video](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/media/video-playing.md).

El video se usa como textura en un material. Puedes configurar cualquiera de las demás propiedades de los materiales para modificar el aspecto de la pantalla del video.

## Sintaxis avanzada

La sintaxis completa para crear un `Materials` componente, sin funciones auxiliares que la simplifiquen, es la siguiente:

```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....',
					},
				},
			},
		},
	},
})
```

Así es como el protocolo base interpreta los componentes Materials. Las funciones auxiliares abstraen estos detalles y ofrecen una sintaxis más sencilla, pero internamente generan esta sintaxis.

Los `$case` campos permiten especificar uno de los tipos admitidos. Cada tipo admite un conjunto distinto de parámetros. Aquí hay dos niveles de `$case`  :

* El `material` campo admite los valores `pbr` y `unlit`, para definir el tipo de material.
* El `tex` campo dentro de una textura admite los siguientes valores para definir el tipo de textura:
  * `texture`
  * `avatarTexture`
  * `videoTexture`

Según el valor de `$case`, es válido definir el objeto correspondiente a ese tipo e incluir las propiedades pertinentes.

Para añadir un componente `Material` a una entidad que posiblemente ya tenga una instancia de este componente, usa `Material.createOrReplace()`. Las funciones auxiliares, como `Material.setPbrMaterial()` se encargan de sobrescribir las instancias existentes del componente, pero ejecutar `Material.create()` en una entidad que ya tenga este componente devuelve un error.

## Modificar materiales de glTF

Usa el componente `GltfNodeModifiers` para modificar los materiales de un *glTF* modelo. Este componente te permite sobrescribir los materiales de un *glTF* modelo con tus propios materiales. Puedes usar cualquiera de las propiedades del `Material` componente, incluidas texturas, texturas de video, materiales sin iluminación, etc.

Hay dos formas de usar el componente `GltfNodeModifiers` :

* Modificar el material de todo el modelo dejando la propiedad `path` como una cadena vacía.
* Modificar el material de un nodo específico del modelo (o de varios nodos) estableciendo la propiedad `path` con la ruta al nodo.

### Modificar el material de todo el modelo

El siguiente ejemplo muestra cómo modificar el material de un modelo *glTF* En este caso, se modifica el material de todo el modelo para que sea rojo.

```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(),
					},
				},
			},
		},
	],
})
```

El componente `GltfNodeModifiers` tiene las siguientes propiedades:

* `modifiers`: Una matriz de modificadores. Cada modificador tiene las siguientes propiedades:
  * `path`: La ruta al nodo del modelo que se modificará.
  * `material`: El material que se usará.

La propiedad `path` es una cadena que representa la ruta al nodo del modelo *glTF* que se modificará. Si quieres modificar el material de todo el modelo, puedes usar una cadena vacía. Si quieres modificar el material de un nodo específico, puedes usar la ruta al nodo. La ruta debe apuntar a un nodo de malla, no a un nodo de vértice.

{% hint style="info" %}
**💡 Consejo**: Puedes usar la aplicación [Babylon Sandbox](https://sandbox.babylonjs.com/) para inspeccionar el modelo *glTF* y encontrar la ruta al nodo que quieres modificar.

Sin embargo, en algunos modelos, Babylon Sandbox puede mostrar rutas que pertenecen a vértices en lugar de mallas, y estas no funcionarán. Si intentas usar una ruta no válida, la consola de la escena mostrará un mensaje de error que incluirá la lista completa de rutas válidas para ese modelo.
{% endhint %}

La propiedad `material` es un objeto que representa el material que se usará. Debe escribirse con la [sintaxis avanzada](#advanced-syntax) para materiales, como se muestra en el ejemplo anterior. Las funciones auxiliares como `Material.setPbrMaterial()` no se puede usar aquí.

### Modificar el material de un nodo específico del modelo

El siguiente ejemplo muestra cómo modificar el material de un nodo específico del modelo *glTF* . En este caso, se modifica el material de la cabeza para usar una 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',
						}),
					},
				},
			},
		},
	],
})
```

A `GltfNodeModifiers` puede contener varios modificadores, cada uno de los cuales modifica un nodo diferente del modelo. El siguiente ejemplo muestra cómo modificar el material de la cabeza y el cuerpo de un 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 un material existente

El componente Material proporciona una interfaz simplificada para acceder a las propiedades del componente Material y modificarlas. Evita tener que navegar por estructuras de unión profundamente anidadas (`PBR` frente a `Unlit`, `texture` frente a `avatarTexture` frente a `videoTexture`), lo que hace que manipular materiales sea más intuitivo y menos propenso a errores.

Los siguientes métodos permiten manipular fácilmente el componente `Material` :

* `Material.getFlat(entity: Entity): ReadonlyFlatMaterial`: Devuelve un objeto accesor de **solo lectura** `FlatMaterial` que proporciona acceso de lectura directo a las propiedades del material. Devuelve un error si la entidad no tiene un componente `Material` . Para evitarlo, se pueden usar como alternativa los siguientes métodos.

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

* `Material.getFlatOrNull(entity: Entity): ReadonlyFlatMaterial | null`: Devuelve un objeto de **solo lectura o null**, según si la entidad tiene o no un componente `Material` .

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

* `Material.getFlatMutable(entity: Entity): FlatMaterial`: Devuelve un objeto **de lectura y escritura** `FlatMaterial`que permite modificar sus propiedades. Genera un error si la entidad en la que se invoca no tiene el componente `Material` .

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

* `Material.getFlatMutableOrNull(entity: Entity): FlatMaterial | null`: Devuelve un objeto **de lectura y escritura o null** `FlatMaterial` que permite modificar sus propiedades. Si la Entity no tiene un `Material component`, devolverá `null`.

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

### Quitar las sombras de un modelo glTF

Para quitar las sombras de un modelo *glTF* , puedes establecer la propiedad `castShadows` en `false` en el objeto `GltfNodeModifiers` . Esto conserva el Material original del modelo, pero evita que proyecte sombras. Es útil para modelos que no deben proyectar sombras, como los haces de luz.

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

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

{% hint style="info" %}
**💡 Consejo**: Las texturas que se usan en los materiales también se pueden aplicar a los efectos de partículas. Consulta [Sistema de partículas](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/particle-system.md) para obtener más información sobre el uso de texturas personalizadas y hojas de sprites con partículas.
{% endhint %}

{% hint style="info" %}
**💡 Consejo**: Para ver ejemplos prácticos de materiales, consulta la [`52,-52-testing-gallery`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/52,-52-testing-gallery) , una escena de prueba que muestra lado a lado distintas combinaciones PBR de metalicidad, rugosidad, emisión y mapas de normales; [`74,-8-gltfnodemodifier`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/74,-8-gltfnodemodifier), que sobrescribe los materiales PBR y sin iluminación en nodos GLTF individuales; y [`0,3-texture-movement`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0,3-texture-movement), que anima el desplazamiento y el mosaico de la 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-es/scenes-sdk7/fundamentos-del-contenido-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.
