Materials

Saiba como adicionar materials e textures a entities com formas primitivas.

Materiais

Materiais podem ser aplicados a entidades que usam 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 models incluem seus próprios materiais que são importados implicitamente para uma cena junto com o modelo. Para modificar ou substituir esses materiais, use o GltfNodeModifiers component. Veja Modificar materiais glTF para mais detalhes.

Ao importar um modelo 3D com seus próprios materiais, lembre-se de que nem todos os shaders são suportados pelo engine do Decentraland. Apenas materiais padrão e materiais PBR (physically based rendering) são suportados. Veja considerações sobre modelos 3D externos para mais detalhes.

Existem diferentes tipos de materiais suportados:

PBR (Physically Based Rendering): O tipo de material mais comum no Decentraland. Ele suporta cores sólidas ou texturas, e diferentes propriedades como metallic, emissive, transparência, etc. Leia mais sobre PBR.
Materiais básicos: eles não respondem à luz e às sombras, o que os torna ideais para exibir imagens de billboard.

Use o Scene Editor no Creator Hub

A maneira mais fácil de dar a uma entidade um Material é usar o Scene Editor. Você pode adicionar um Material componente à sua entidade e depois configurar todos os campos disponíveis na UI do Scene Editor. Veja Adicionar Components.

Adicionar um material

O exemplo a seguir cria um material PBR e define alguns de seus campos para dar a ele uma cor vermelha e propriedades metálicas. Esse material é adicionado a uma entidade que também tem uma forma de caixa, então ele colorirá a caixa com esse material.

//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 seus campos
Material.setPbrMaterial(meshEntity, {
	albedoColor: Color4.Red(),
	metallic: 0.8,
	roughness: 0.1,
})

Para mudar o material de uma entidade que já tenha um Material componente, execute Material.setPbrMaterial() ou qualquer uma das outras funções auxiliares e ele substituirá o material original. Não há necessidade de remover o material original Material nem de usar a sintaxe avançada.

//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 seus campos
Material.setPbrMaterial(meshEntity, {
	albedoColor: Color4.Red(),
})

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

📔 Nota: O Material component deve ser importado via

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

Ver Importações para saber como lidar facilmente com isto.

Cores do Material

Dê a um material uma cor sólida. Em um PBR Material, você define o albedoColor campo. As cores de albedo respondem à luz e podem incluir sombras nelas.

Os valores de cor são do tipo Color4, compostos por r, g e b valores (vermelho, verde e azul). Cada um deles aceita valores entre 0 e 1. Definindo valores diferentes para eles, você pode compor qualquer cor visível. Para preto, defina os três como 0. Para branco, defina todos como 1.

📔 Nota: Se você definir qualquer cor em albedoColor para um valor maior que 1, emissive, com mais intensidade quanto maior for o valor. Então, por exemplo, {r: 15, g: 0, b: 0} produz um brilho vermelho muito intenso.

Ver tipos de cor para mais detalhes sobre como definir cores.

Você também pode editar os seguintes campos em um PBR Material para ajustar como sua cor é percebida:

emissiveColor: A cor emitida pelo material.
reflectivityColor: também conhecido como Cor Especular em outra nomenclatura.

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

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

Usando texturas

Defina um arquivo de imagem como textura em um material definindo o texture parâmetro.

//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 seus campos
Material.setPbrMaterial(meshEntity, {
	texture: Material.Texture.Common({
		src: 'assets/materials/wood.png',
	}),
})

No exemplo acima, a imagem do material está localizada em uma assets/materials pasta, que está no nível raiz da pasta do projeto da cena.

💡 Dica: Recomendamos manter os arquivos de imagem da textura em algum lugar na /assets pasta dentro da sua cena.

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

filterMode: Determina como os pixels da textura são esticados ou comprimidos quando renderizados. Isso recebe um valor do TextureFilterMode enum. Veja Escala da textura.
wrapMode: Determina como uma textura é repetida em um objeto. Isso recebe um valor do TextureWrapMode enum. Veja Repetição da textura.

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 no ambiente, crie um material básico em vez de um PBR material.

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

Texturas de uma URL externa

Você pode apontar a textura do seu material para uma URL externa em vez de um caminho interno no projeto da cena.

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

A URL deve começar com https, http URLs não são suportadas.

Repetição da textura

Você pode definir como uma textura se alinha com uma superfície. Por padrão, a textura é esticada para ocupar a superfície uma vez, mas você pode escalá-la e deslocá-la.

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

offset: Desloca a textura para alterar seu alinhamento. O valor é um Vector2, em que ambos os eixos vão de 0 a 1, sendo 1 a largura ou altura total da textura.
tiling: Escala a textura. O valor padrão é o Vector 2 [1, 1], o que faz a imagem se repetir 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 recebe seus valores do TextureWrapMode enum, que permite os seguintes valores:
- TextureWrapMode.TWM_CLAMP: A textura é exibida apenas uma vez no tamanho especificado. O restante da superfície do mesh fica transparente. O valor de tiling é ignorado.
- TextureWrapMode.TWM_REPEAT: A textura é repetida tantas vezes quanto couber no mesh, usando o tamanho especificado.
- TextureWrapMode.TWM_MIRROR: Assim como em wrap, a textura é repetida tantas vezes quanto couber, mas a orientação dessas repetições é espelhada.

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

📔 Nota: O offset e tiling propriedades são suportadas apenas no cliente desktop DCL 2.0.

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

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

No exemplo abaixo, a textura usa um espelhado modo de wrap espelhado, e cada repetição da textura ocupa apenas 1/4 da superfície. Isso significa que veremos 4 cópias da imagem, espelhadas umas em relação às outras em ambos os eixos.

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 modo. O tween altera gradualmente o valor das offset ou o tiling propriedades de uma textura ao longo de um período de tempo, de forma suave e otimizada.

📔 Nota: Texture Tweens é um recurso suportado apenas no cliente desktop DCL 2.0.

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

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

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

entity: A entidade da qual mover a textura
início: Um Vector2 para a posição inicial
fim: Um Vector2 para a posição final
duration: Quantos milissegundos leva para mover entre as duas posições

Este outro parâmetro opcional também está disponível:

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

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 usa um tween que dura 1 segundo e move a textura apenas uma vez. Para alcançar um movimento contínuo, por exemplo para simular a queda de uma cascata, você precisa usar setTextureMoveContinuous.

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 de textura recebe as seguintes informações:

entity: A entidade da qual mover a textura
direction: Um Vector2 para o movimento
speed: Quantas unidades por segundo a entidade vai se mover

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

movementType: define se o movimento será no campo offset ou no campo tiling. Por padrão, usa offset.
duration: Quantos milissegundos manter o movimento. Após esse tempo, o movimento será interrompido.

Sequências complexas de tween

Você também pode fazer os movimentos da textura seguirem uma sequência complexa com quantos passos quiser. Use o sequence campo para listar quantos tweens você quiser; eles serão executados sequencialmente após o primeiro tween descrito em Tween component.

//(...)
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 uma TweenSequence, você precisa usar o formato mais detalhado de Tween.Mode.TextureMove para definir o tween.

Texturas em várias camadas

Você pode usar vários arquivos de imagem como camadas para compor texturas mais realistas, por exemplo incluindo uma bumpTexture e uma emissiveTexture.

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 relevos e rugas em uma superfície, modificando como os Normals da superfície se comportam em cada pixel.

A emissiveTexture pode acentuar o brilho em certas partes de um material, para obter efeitos muito interessantes.

Definir UVs

Outra alternativa para alterar a escala ou o alinhamento de uma textura é configurar uv propriedades no componente MeshRenderer.

Você define u e v coordenadas na imagem 2D da textura para corresponder aos vértices da forma. Quanto mais vértices a entidade tiver, mais uv coordenadas precisam ser definidas na textura; um plano, por exemplo, precisa ter 8 uv pontos definidos, 4 para cada uma de suas duas faces.

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 a seguir inclui uma função que simplifica a definição de UVs. A setUVs função definida aqui recebe um número de linhas e colunas como parâmetros e define os UVs para que a imagem da textura seja repetida um número específico de vezes.

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 não rotacionado
		0, // canto inferior esquerdo
		0,

		cols, // canto inferior direito
		0,

		cols, // canto superior direito
		rows,

		0, // canto superior esquerdo
		rows,

		// Lado sul do plano não rotacionado
		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 uma box forma de mesh, a mesma estrutura se aplica. Cada uma das 6 faces do cubo usa 4 pares de coordenadas, um para cada canto. Todos esses 48 valores são listados como um único array.

📔 Nota: As propriedades UV estão atualmente disponíveis apenas em plane e em box formas. Além disso, uv valores afetam todas as camadas da textura igualmente, já que são definidos na forma.

Escala da textura

Quando as texturas são esticadas ou encolhidas para um tamanho diferente da imagem de textura original, isso às vezes pode criar artefatos. Em um ambiente 3D, os efeitos de perspectiva causam isso naturalmente. Existem vários filtragem de textura algoritmos que existem para compensar isso de diferentes maneiras.

A Material objeto usa o bilinear por padrão, mas permite que você o configure para usar o vizinho mais próximo ou trilinear em vez disso, definindo o filterMode da textura. Isso recebe um valor do TextureFilterMode enum:

TextureFilterMode.TFM_POINT: Usa um algoritmo de "vizinho mais próximo". Essa configuração é ideal para gráficos em estilo pixel art, pois os contornos permanecerão nitidamente marcados à medida que a textura é vista maior na tela, em vez de ficar borrada.
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.

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

Materiais sem iluminação

Na maioria das vezes, você vai querer que os materiais da sua cena sejam afetados pelas condições de iluminação, incluindo sombras e também tingidos pelas mudanças de tonalidade de diferentes horas do dia. Mas, em outros casos, talvez você queira mostrar as cores em seu estado puro. Isso é útil ao reproduzir vídeos, ou também para marcadores abstratos que precisam se destacar e que têm o objetivo de sinalizar dicas ao jogador.

Para criar um material sem iluminação, use Material.setBasicMaterial. Os materiais básicos não têm todas as mesmas propriedades que os PBR materials; eles têm apenas o essencial:

diffuseColor: Color4 para a cor
texture: Texture
alphaTexture: Textura separada para a camada de transparência
alphaTest: Limiar para obter transparência com base na cor da textura
castShadows: Se false, nenhuma sombra é projetada sobre outras entidades na cena.

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

Retratos de Avatar

Para exibir 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. Isso cria uma textura a partir de uma imagem 256x256 do jogador, mostrando cabeça e ombros. O jogador é exibido usando o conjunto de wearables que o servidor atual registrou por último.

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

Você pode buscar o retrato de qualquer jogador do Decentraland, mesmo que ele não esteja conectado no momento e mesmo que não tenha um Decentraland NAME reivindicado.

As seguintes propriedades são suportadas no objeto que você passa como argumento:

userId: ID do usuário cujo perfil você quer exibir
filterMode: Determina como os pixels da textura são esticados ou comprimidos quando renderizados. Isso recebe um valor do TextureFilterMode enum. Veja Escala da textura.
wrapMode: Determina como uma textura é repetida em um objeto. Isso recebe um valor do TextureWrapMode enum. Veja Repetição da textura.

Materiais transparentes

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

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, ele será opaco por padrão, mas você pode ativar sua transparência definindo o transparencyMode quando você define MaterialTransparencyMode.MTM_ALPHA_BLEND.

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

A transparencyMode pode ter os seguintes valores:

MaterialTransparencyMode.MTM_OPAQUE: Nenhuma transparência
MaterialTransparencyMode.MTM_ALPHA_TEST: Cada pixel é totalmente opaco ou totalmente transparente, com base em um limiar.
MaterialTransparencyMode.MTM_ALPHA_BLEND: Valores intermediários são possíveis com base no valor de cada pixel.
MaterialTransparencyMode.MTM_ALPHA_TEST_AND_ALPHA_BLEND: Usa uma combinação de ambos os métodos.
MaterialTransparencyMode.MTM_AUTO: Determina o método com base na texture fornecida.

Se você definir o transparencyMode quando você define MaterialTransparencyMode.MTM_ALPHA_TEST, você pode ajustar finamente o limiar usado para determinar se cada pixel é transparente ou não. Defina o alphaTest property entre 0 e 1. Por padrão, seu valor é 0.5.

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

Ao usar um material unlit, você pode adicionar um alphaTexture para tornar apenas certas regiões do material transparentes, com base em uma texture.

📔 Nota: Isto deve ser uma imagem de um único canal. Nesta imagem, use a cor vermelha ou preta para determinar quais partes da texture real devem ser transparentes.

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

Isto pode ser usado de maneiras muito interessantes junto com videos. Veja video em reprodução.

Video em reprodução

Para transmitir video de uma URL para um material, ou reproduzir um video de um file armazenado na scene, veja video em reprodução.

O video é usado como uma texture em um material; você pode definir qualquer uma das outras properties dos materials para alterar como a tela do video parece.

Sintaxe avançada

A sintaxe completa para criar um Materiais component, sem nenhum helper para simplificá-lo, é assim:

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 components Materials. As helper functions abstraem isso e expõem uma sintaxe mais amigável, mas nos bastidores elas geram esta sintaxe.

A $case fields permitem que você especifique um dos tipos permitidos. Cada tipo suporta um conjunto diferente de parâmetros. Há dois níveis de $case aqui:

A material field suporta os valores pbr e unlit, para definir o tipo de material.
A tex field dentro de uma texture suporta os seguintes valores, para definir o tipo de texture:
- texture
- avatarTexture
- videoTexture

Dependendo do valor de $case, é válido definir o object correspondente ao tipo, passando quaisquer properties relevantes.

Para adicionar um Material component a um entity que potencialmente já tenha uma instância deste component, use Material.createOrReplace(). As helper functions como Material.setPbrMaterial() lidam com a sobrescrita de instâncias existentes do component, mas executar Material.create() em um entity que já tenha este component retorna um error.

Modificar materiais glTF

Use a GltfNodeModifiers component para modificar os materials de um glTF model. Este component permite que você substitua os materials de um glTF model pelos seus próprios materials. Você pode usar qualquer uma das properties do Material component, incluindo texture, video texture, materials unlit, etc.

Há duas maneiras de usar o GltfNodeModifiers component:

Modificar o material de todo o model deixando o path property como uma string vazia.
Modificar o material de um node específico no model (ou vários nodes) definindo o path property para o path do node.

Modificar o material de todo o model

O exemplo a seguir mostra como modificar o material de um glTF model. Neste caso, o material de todo o model é modificado para ficar vermelho.

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

A GltfNodeModifiers component possui as seguintes properties:

modifiers: Um array de modifiers. Cada modifier possui as seguintes properties:
- path: O path para o node no model a modificar.
- material: O material a usar.

A path property é uma string que representa o path para o node no glTF model a modificar. Se você quiser modificar o material de todo o model, pode usar uma string vazia. Se quiser modificar o material de um node específico, pode usar o path do node. O path deve apontar para um mesh node, não para um vertex node.

💡 Dica: Você pode usar o Babylon Sandbox app para inspecionar o glTF model e encontrar o path para o node que deseja modificar.

Em alguns models, no entanto, o Babylon sandbox pode listar paths que pertencem a vertices em vez de meshes, o que não funcionará. Se você tentar usar um path que não é válido, o console da scene exibirá uma mensagem de error que inclui a lista completa de paths válidos nesse model.

A material property é um object que representa o material a usar. Ele precisa ser escrito usando a advanced syntax para materials, como mostrado no exemplo acima. Funções auxiliares como Material.setPbrMaterial() não podem ser usadas aqui.

Modificar o material de um node específico no model

O exemplo a seguir mostra como modificar o material de um node específico no glTF model. Neste caso, o material da cabeça é modificado para usar uma texture alternativa.

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 modifiers, cada um modificando um node diferente no model. O exemplo a seguir mostra como modificar o material da cabeça e do corpo de um glTF model.

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 fields de um material existente

O component Material fornece uma interface simplificada para acessar e modificar properties do component Material. Ele 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 materials mais intuitiva e menos propensa a errors.

Os seguintes methods permitem fácil manipulação do Material component:

Material.getFlat(entity: Entity): ReadonlyFlatMaterial: Ele retorna um somente leitura FlatMaterial objeto accessor que fornece acesso direto de leitura às properties do material. Ele retornará um error se o entity não tiver um Material component. Para evitar isso, os próximos methods podem ser usados como alternativa.

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

Material.getFlatOrNull(entity: Entity): ReadonlyFlatMaterial | null: Ele retorna um somente leitura ou null, dependendo se o entity tem ou não um Material component.

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

Material.getFlatMutable(entity: Entity): FlatMaterial: Ele retorna um leitura e escrita FlatMaterialobjeto que permite modificar suas properties. Ele lançará um error se o entity chamado não tiver o Material component.

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

Material.getFlatMutableOrNull(entity: Entity): FlatMaterial | null: Ele retorna um leitura e escrita ou null FlatMaterial objeto que permite modificar suas properties. Caso o entity não tenha um Material component, ele retornará null.

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

Remover shadows de um modelo glTF

Para remover shadows de um glTF model, você pode definir o castShadows property para false em GltfNodeModifiers o

object. Isso mantém o material original do model, mas impede que ele projete shadows. Isso é útil para models que não devem projetar shadows, como feixes de light.

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

💡 Dica: Textures usadas em materials também podem ser aplicadas a efeitos de particles. Veja Particle System para detalhes sobre o uso de custom textures e sprite sheets com particles.

💡 Dica: Para exemplos práticos de materials, veja o 52,-52-testing-gallery test scene, que varre combinações de PBR metallic/roughness/emissive/normal-map lado a lado, 74,-8-gltfnodemodifier, que substitui materials PBR e unlit em GLTF nodes individuais, e 0,3-texture-movement, que anima o offset da texture e o tiling.

AnteriorLights

PróximoMover Entities

Atualizado há 1 mês