Components de shape

Aprenda sobre os diferentes components que dão às entities sua shape 3D e colisão.

Cenas tridimensionais em Decentraland são baseadas no Entity-Component model, em que tudo numa cena é uma entity, e cada entity pode incluir components que moldam as suas características e funcionalidade.

A forma renderizada de uma entity é determinada pelo component que ela usa.

Use o Scene Editor no Creator Hub

A maneira mais fácil de dar forma a uma entity é usar o Scene Editor. Podes adicionar um Mesh Renderer component para fornecer uma forma primitiva, ou um GLTF component para referenciar um modelo 3D a partir de um ficheiro. Vê Add Components.

Formas primitivas

Várias formas básicas, frequentemente chamadas primitives, podem ser adicionadas a uma entity dando à entity um MeshRenderer componente.

As seguintes formas estão disponíveis. Várias formas incluem campos adicionais opcionais, específicos para essa forma.

• caixa:

  Use MeshRenderer.setBox(), passando a entidade. Passe uvs como um campo adicional opcional, para mapear o alinhamento da texture. Vê materials para mais detalhes.

• plano:

  Use MeshRenderer.setPlane(), passando a entidade. Passe uvs como um campo adicional opcional, para mapear o alinhamento da texture. Vê materials para mais detalhes.

• esfera:

  Use MeshRenderer.setSphere(), passando a entidade.

• cilindro:

  Use MeshRenderer.setCylinder(), passando a entidade. Passe radiusTop e radiusBottom como campos opcionais adicionais, para modificar o cilindro.

  DICA: Define qualquer um radiusTop ou radiusBottom como 0 para criar um cone.

O seguinte exemplo cria um cubo:

const myCube = engine.addEntity()

Transform.create(myCube, {
	position: Vector3.create(8, 1, 8),
})

MeshRenderer.setBox(myCube)

O seguinte exemplo cria um cilindro com um radiusTop de 0, o que produz um cone:

const myCone = engine.addEntity()

Transform.create(myCone, {
	position: Vector3.create(8, 1, 8),
})

MeshRenderer.setCylinder(myCone, 0, 1)

As primitive shapes não incluem materials. Para lhes dar uma cor ou uma texture, tens de atribuir um material component à mesma entity.

Para tornar uma primitive clicável, ou para impedir que os jogadores andem através dela, tens de dar à entity um collider através de um MeshCollider componente.

Para alterar a forma de uma entity que já tem um MeshRenderer component, execute MeshRenderer.setBox() ou qualquer uma das outras helper functions, isso irá substituir a forma original. Não é necessário remover o original MeshRenderer nem usar a sintaxe avançada.

const myCube = engine.addEntity()

Transform.create(myCube, {
	position: Vector3.create(8, 1, 8),
})

MeshRenderer.setBox(myCube)

// substituir forma
MeshRenderer.setSphere(myCube)

📔 Nota: O MeshRenderer component deve ser importado através de

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

Veja Imports para saber como lidar facilmente com estes casos.

modelos 3D

Para formas mais complexas, podes criar um modelo 3D numa ferramenta externa como o Blender e depois importá-lo em .glTF ou .glb (binário .glTF). glTF (GL Transmission Format) é um projeto aberto da Khronos que fornece um formato comum e extensível para 3D assets, eficiente e altamente interoperável com tecnologias web modernas.

Para adicionar um modelo externo a uma cena, adiciona um GltfContainer component a uma entity e define o seu src para o caminho do ficheiro glTF que contém o modelo.

const houseEntity = engine.addEntity()

GltfContainer.create(houseEntity, {
	src: 'models/House.gltf',
})

O src é obrigatório, tens de lhe dar um valor ao construir o component. No exemplo acima, o modelo está localizado numa models pasta ao nível raiz da pasta do projeto da scene.

💡 Dica: Recomendamos manter os teus modelos separados na assets/scene/models dentro da tua scene.

Os modelos glTF podem incluir as suas próprias textures, materials, colliders e animations incorporadas. Vê modelos 3D para mais informações sobre isto. Para substituir os materials de um modelo, usa o GltfNodeModifiers component. Veja Modificar materiais glTF para mais detalhes.

Para impedir que os jogadores andem através de um modelo 3D, ou para tornar um modelo clicável, tens de ter um collider, que pode estar incorporado no modelo ou ser fornecido através de um MeshCollider componente.

Tem em atenção que todos os modelos, os seus shaders e as suas textures têm de estar dentro dos parâmetros do limitações da scene.

📔 Nota: O GltfContainer component deve ser importado através de

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

Veja Imports para saber como lidar facilmente com estes casos.

Pré-carregar um modelo 3D

Em alguns casos, um modelo 3D personalizado é adicionado à scene mas não é usado imediatamente. Por exemplo, um modelo de cadeira personalizado pode apenas ser carregado quando o player interage com outro objeto. Neste cenário, a primeira interação pode demorar algum tempo até terminar de descarregar e carregar o modelo.

Para evitar isso, usa o AssetLoad.create method para garantir que o asset é descarregado antes de ser necessário.

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

AssetLoad.create(engine.RootEntity, {
  assets: [
    "assets/scene/bundle1/explosion.glb",
  ],
})

Para mais informações, consulta a documentação de Pre Load Resources .

Bibliotecas gratuitas de modelos 3D

Em vez de criar os seus próprios modelos 3D, você também pode transferi-los de várias bibliotecas gratuitas ou pagas.

Para o ajudar a começar, abaixo está uma lista de bibliotecas que têm conteúdo gratuito ou relativamente barato:

• IWB Catalog

• Asset Ovi

• Assets do Builder

• SketchFab

• Clara.io

• Archive3D

• SketchUp 3D Warehouse

• Thingiverse (modelos 3D feitos principalmente para impressão 3D, mas adaptáveis a Virtual Worlds)

• ShareCG

• CGTrader

📔 Nota: Preste atenção às restrições de licença que o conteúdo que você descarrega tem.

Note que em vários destes sites, você pode escolher o formato em que deseja descarregar o modelo. Escolha sempre .glTF formato, se disponível. Se não estiver disponível, você deve convertê-los para glTF antes de os poderes usar numa scene. Para isso, recomendamos importá-los para o Blender e exportar como .glTF a partir daí.

Otimizar modelos 3D

Para garantir que os modelos 3D na tua scene carregam mais depressa e ocupam menos memória, segue estas melhores práticas:

• Guarda os teus modelos em .glb format, que é uma versão mais leve de .gltf.

• Se tiveres vários modelos que partilham as mesmas textures, exporta os teus modelos com textures num ficheiro separado. Dessa forma, vários modelos podem referir-se a um único ficheiro de texture que só precisa de ser carregado uma vez.

• Se a tua scene tiver entities que aparecem e desaparecem, pode ser boa ideia agrupar essas entities e mantê-las subterrâneas, ou numa escala de 0. Isto vai ajudá-las a aparecer mais depressa; a desvantagem é que vão ocupar memória quando não estiverem em uso. Vê entities e components

Esticar uma forma

As primitive shapes e os modelos 3D têm dimensões predefinidas que podes alterar mudando a escala no Transform componente.

const primitiveEntity = engine.addEntity()

MeshRenderer.setBox(primitiveEntity)

Transform.create(primitiveEntity, {
	position: { x: 8, y: 1, z: 8 },
	scale: { x: 4, y: 0.5, z: 4 },
})

Tornar invisível

Podes tornar uma entity invisível dando a uma entity um VisibilityComponent, com a sua visible propriedade definida como false.

const myEntity = engine.addEntity()
Transform.create(myEntity, {
	position: Vector3.create(4, 0, 4),
})
MeshRenderer.setBox(myEntity)

VisibilityComponent.create(myEntity, { visible: false })

O VisibilityComponent funciona da mesma forma para entities com primitive shapes e com GLTFContainer components.

Se uma entity for invisível, o seu collider pode bloquear o caminho de um player e/ou impedir o clique em entities que estejam atrás dela, dependendo das collision layers atribuídas ao collider.

Propagar visibilidade

Você pode usar o propagateToChildren campo no VisibilityComponent para aplicar uma configuração a cada child na árvore de children da entity. Se propagateToChildren estiver definido como true, estas definições afetam todos os children em todos os níveis descendentes. Isto pode poupar-te muito trabalho tedioso ao marcar cada child entity como invisível ou visível também.

// Entity pai (explicitamente invisível)
const parentEntity = engine.addEntity()
Transform.create(parentEntity, {
	position: Vector3.create(4, 0, 4),
})
MeshRenderer.setBox(parentEntity)
VisibilityComponent.create(parentEntity, { visible: false, propagateToChildren: true })

// Child entity (implicitamente invisível por causa do pai)
const child = engine.addEntity()
Transform.create(child, {
	position: Vector3.create(0, 1, 0),
	parent: parentEntity
})
MeshRenderer.setBox(child)

📔 Nota: Se uma entity tiver o seu próprio VisibilityComponent, isso substitui qualquer configuração dos pais.

Se uma entity não tiver o seu próprio VisibilityComponent, então a sua visibilidade é determinada pelo seu pai mais próximo com um VisibilityComponent e propagateToChildren definido como true.

Estado de carregamento

Se um modelo 3D for bastante grande, pode demorar algum tempo visível a ser renderizado; esse tempo pode variar consoante o hardware do player e muitos outros fatores. Às vezes precisas de garantir que um modelo terminou de carregar antes de executares outra ação. Por exemplo, se quiseres teleportar o player para uma plataforma no céu, primeiro tens de garantir que a plataforma está totalmente renderizada antes de mover o player para lá, caso contrário o player pode cair diretamente através da plataforma.

Para verificar se um modelo 3D terminou de ser renderizado, verifica o GltfContainerLoadingState component da entity. Este component destina-se a ser apenas de leitura e existe em qualquer entity que também tenha um GltfContainercomponente.

Este component tem uma única propriedade chamada currentState, contendo um valor do LoadingState enum.

O seguinte exemplo usa um system para verificar periodicamente o estado de carregamento do modelo 3D de uma entity. Se o estado for LoadingState.FINISHED, podes querer executar lógica personalizada aí e terminar a execução do system.

export function main() {
	const meshEntity = engine.addEntity()
	GltfContainer.create(meshEntity, { src: 'models/Monster.glb' })
	engine.addSystem((deltaTime) => {
		const loadingState = GltfContainerLoadingState.getOrNull(meshEntity)
		if (!loadingState) return
		switch (loadingState.currentState) {
			case LoadingState.LOADING:
				console.log('mesh is LOADING')
				break
			case LoadingState.FINISHED:
				console.log('mesh is FINISHED')
				// Executar lógica personalizada
				break
			case LoadingState.FINISHED_WITH_ERROR:
				console.log('mesh is FINISHED BUT MAY HAVE PROBLEMS')
				break
			case LoadingState.UNKNOWN:
				console.log('mesh is in an UNKNOWN STATE')
				break
		}
	})
}

Sintaxe avançada

A sintaxe completa para criar um MeshRenderer component, sem quaisquer auxiliares para o simplificar, é a seguinte:

MeshRenderer.setBox(myBox, {
	mesh: {
		$case: 'box',
		box: { uvs: [] },
	},
})

MeshRenderer.create(myPlane, {
	mesh: {
		$case: 'plane',
		plane: { uvs: [] },
	},
})

MeshRenderer.create(myShpere, {
	mesh: {
		$case: 'sphere',
		sphere: {},
	},
})

MeshRenderer.create(myCylinder, {
	mesh: {
		$case: 'cylinder',
		cylinder: {},
	},
})

É assim que o protocolo base interpreta components MeshRenderer. As helper functions abstraem isto e expõem uma sintaxe mais amigável, mas por trás dos bastidores produzem esta sintaxe.

O $case campo permite-lhe especificar um dos tipos permitidos. Cada tipo suporta um conjunto diferente de parâmetros. No exemplo acima, o caixa tipo suporta um uvs field.

Os valores suportados para $case são os seguintes:

• caixa

• plano

• esfera

• cilindro

Dependendo do valor de $case, é válido definir o objeto para a forma correspondente, passando quaisquer propriedades relevantes.

Para adicionar um MeshRenderer component a uma entity que potencialmente já tem uma instância deste component, use MeshRenderer.createOrReplace(). As funções auxiliares como MeshRenderer.setBox() tratam de substituir instâncias existentes do component, mas executar MeshRenderer.create() numa entity que já tem este component devolve um erro.