Componentes de Forma

Saiba sobre os diferentes componentes que dão às entidades sua forma 3D e colisão.

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

A forma renderizada de uma entity é determinada por qual component ela usa.

Use o Scene Editor em Creator Hub

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

Formas primitivas

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

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

• box:

  Use MeshRenderer.setBox(), passando a entity. Passe uvs como um campo adicional opcional, para mapear o alinhamento da textura. Veja materials para mais detalhes.

• plane:

  Use MeshRenderer.setPlane(), passando a entity. Passe uvs como um campo adicional opcional, para mapear o alinhamento da textura. Veja materials para mais detalhes.

• sphere:

  Use MeshRenderer.setSphere(), passando a entity.

• cylinder:

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

  DICA: Defina ou radiusTop ou radiusBottom para 0 para criar um cone.

O exemplo a seguir cria um cubo:

const myCube = engine.addEntity()

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

MeshRenderer.setBox(myCube)

O exemplo a seguir 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)

Formas primitivas não incluem materials. Para dar cor ou textura, você deve atribuir um material component à mesma entity.

Para tornar uma primitiva clicável, ou para impedir que jogadores caminhem através dela, você deve dar à entity um collider via um MeshCollider component.

Para alterar a forma de uma entity que já tem um MeshRenderer component, execute MeshRenderer.setBox() ou qualquer uma das outras funções auxiliares e isso sobrescreverá a forma original. Não há necessidade de remover o original MeshRenderer ou de usar a sintaxe avançada.

const myCube = engine.addEntity()

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

MeshRenderer.setBox(myCube)

// overwrite shape
MeshRenderer.setSphere(myCube)

📔 Nota: O MeshRenderer component deve ser importado via

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

Veja Imports para como lidar com isso facilmente.

Modelos 3D

Para formas mais complexas, você pode construir um modelo 3D em uma ferramenta externa como Blender e então importá-los em .glTF ou .glb (binário .glTF). glTF (GL Transmission Format) é um projeto aberto do Khronos que fornece um formato comum e extensível para ativos 3D que é eficiente e altamente interoperável com tecnologias web modernas.

Para adicionar um modelo externo a uma cena, adicione um GltfContainer component a uma entity e defina seu src para o caminho do arquivo glTF contendo o modelo.

const houseEntity = engine.addEntity()

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

O src campo é obrigatório, você deve dar-lhe um valor ao construir o component. No exemplo acima, o modelo está localizado em uma models pasta no nível raiz da pasta do projeto da cena.

💡 Dica: Recomendamos manter seus modelos separados na assets/scene/models pasta dentro da sua cena.

Modelos glTF podem incluir suas próprias textures, materials, colliders e animations embutidos. Veja Modelos 3D para mais informações sobre isso. Para sobrescrever os materials de um modelo, use o GltfNodeModifiers component. Veja Modify glTF materials para mais detalhes.

Para impedir que jogadores atravessem um modelo 3D, ou para tornar um modelo clicável, você deve ter um collider, que pode estar embutido no modelo ou fornecido via um MeshCollider component.

Tenha em mente que todos os modelos, seus shaders e suas textures devem estar dentro dos parâmetros das scene limitations.

📔 Nota: O GltfContainer component deve ser importado via

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

Veja Imports para como lidar com isso facilmente.

Pré-carregando um modelo 3D

Em alguns casos, um modelo 3D personalizado é adicionado à cena mas não é usado imediatamente. Por exemplo, um modelo de cadeira personalizada pode ser carregado apenas quando o jogador interage com outro objeto. Nesse cenário, a primeira interação pode levar algum tempo até que o download e o carregamento do modelo terminem.

Para evitar isso, use o AssetLoad.create método para garantir que o asset seja baixado 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, consulte a documentação Pre Load Resources .

Bibliotecas gratuitas de modelos 3D

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

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

• IWB Catalog

• Asset Ovi

• Assets from the 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ê baixar possui.

Observe que em vários desses sites, você pode escolher em qual formato baixar o modelo. Sempre escolha .glTF format se disponível. Se não estiver disponível, você deve convertê-los para glTF antes de poder usá-los em uma cena. Para isso, recomendamos importá-los para o Blender e exportar como .glTF a partir daí.

Otimizar modelos 3D

Para garantir que modelos 3D em sua cena carreguem mais rápido e ocupem menos memória, siga estas melhores práticas:

• Salve seus modelos em .glb format, que é uma versão mais leve de .gltf.

• Se você tiver vários modelos que compartilham as mesmas textures, exporte seus modelos com textures em um arquivo separado. Dessa forma vários modelos podem referir-se a um único arquivo de texture que só precisa ser carregado uma vez.

• Se sua cena tem entities que aparecem e desaparecem, pode ser uma boa ideia agrupar essas entities e mantê-las no subsolo, ou com escala 0. Isso ajudará elas a aparecerem mais rápido, a troca-off é que elas ocuparão memória quando não estiverem em uso. Veja entities and components

Esticar uma forma

Formas primitivas e modelos 3D têm dimensões padrão que você pode alterar mudando a escala no Transform component.

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

Você pode tornar uma entity invisível dando a uma entity um VisibilityComponent, com 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 formas primitivas e com GLTFContainer components.

Se uma entity estiver invisível, seu collider pode bloquear o caminho do jogador e/ou prevenir cliques em entities que estão atrás dela, dependendo das camadas de colisão atribuídas ao collider.

Propagar visibilidade

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

// Parent entity (explicitamente invisible)
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 (implicitly invisible because of parent)
const child = engine.addEntity()
Transform.create(child, {
	position: Vector3.create(0, 1, 0),
	parent: parentEntity
})
MeshRenderer.setBox(child)

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

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

Estado de carregamento

Se um modelo 3D for bastante grande, pode levar algum tempo perceptível para ser renderizado, esse tempo pode variar dependendo do hardware do jogador e muitos outros fatores. Às vezes você precisa garantir que um modelo terminou de carregar antes de executar outra ação. Por exemplo, se você quiser teleportar o jogador para uma plataforma no céu, você precisa primeiro garantir que a plataforma esteja totalmente renderizada antes de mover o jogador para lá, caso contrário o jogador pode cair através da plataforma.

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

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

O exemplo a seguir usa um system para verificar periodicamente o estado de carregamento do modelo 3D de uma entity. Se o estado for LoadingState.FINISHED, você pode querer executar lógica customizada ali e encerrar 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')
				// Perform custom logic
				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 simplificá-la, é assim:

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 funções auxiliares abstraem isso e expõem uma sintaxe mais amigável, mas nos bastidores elas produzem essa sintaxe.

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

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

• box

• plane

• sphere

• cylinder

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 desse component, use MeshRenderer.createOrReplace(). As funções auxiliares como MeshRenderer.setBox() lidam com a sobrescrição de instâncias existentes do component, mas executar MeshRenderer.create() em uma entity que já tem esse component retorna um erro.