Componentes de forma

Aprende sobre los diferentes components que le dan a las entities su forma 3D y colisión.

Las escenas tridimensionales en Decentraland se basan en el Entity-Component modelo, donde todo en una escena es una entity, y cada entidad puede incluir components que moldean sus características y funcionalidad.

La forma renderizada de una entidad está determinada por qué componente utiliza.

Usa el Scene Editor en Creator Hub

La forma más fácil de darle forma a una entidad es usar el Scene Editor. Puedes agregar un Mesh Renderer component para proporcionar una forma primitiva, o un GLTF component para referenciar un modelo 3D desde un archivo. Ver Add Components.

Formas primitivas

Varias formas básicas, a menudo llamadas primitives, pueden añadirse a una entidad dándole a la entidad un MeshRenderer component.

Las siguientes formas están disponibles. Varias formas incluyen campos adicionales opcionales, específicos para esa forma.

• caja:

  Usa MeshRenderer.setBox(), pasando la entidad. Pasa uvs como un campo adicional opcional, para mapear la alineación de la textura. Ver materials para más detalles.

• plano:

  Usa MeshRenderer.setPlane(), pasando la entidad. Pasa uvs como un campo adicional opcional, para mapear la alineación de la textura. Ver materials para más detalles.

• esfera:

  Usa MeshRenderer.setSphere(), pasando la entidad.

• cilindro:

  Usa MeshRenderer.setCylinder(), pasando la entidad. Pasa radiusTop y radiusBottom como campos opcionales adicionales, para modificar el cilindro.

  CONSEJO: Establece ya sea radiusTop o radiusBottom a 0 para crear un cono.

El siguiente ejemplo crea un cubo:

const myCube = engine.addEntity()

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

MeshRenderer.setBox(myCube)

El siguiente ejemplo crea un cilindro con un radiusTop de 0, lo que produce un cono:

const myCone = engine.addEntity()

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

MeshRenderer.setCylinder(myCone, 0, 1)

Las formas primitivas no incluyen materiales. Para darle un color o una textura, debes asignar un material component a la misma entidad.

Para hacer que una primitiva sea clicable, o para evitar que los jugadores la atraviesen, debes darle a la entidad un collider vía un MeshCollider component.

Para cambiar la forma de una entidad que ya tiene un MeshRenderer component, ejecuta MeshRenderer.setBox() o cualquiera de las otras funciones auxiliares y esto sobrescribirá la forma original. No es necesario eliminar el MeshRenderer original ni usar la sintaxis avanzada.

const myCube = engine.addEntity()

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

MeshRenderer.setBox(myCube)

// sobrescribir forma
MeshRenderer.setSphere(myCube)

📔 Nota: El MeshRenderer component debe importarse vía

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

Ver Imports para cómo manejarlos fácilmente.

Modelos 3D

Para formas más complejas, puedes construir un modelo 3D en una herramienta externa como Blender y luego importarlos en .glTF o .glb (binario .glTF). glTF (GL Transmission Format) es un proyecto abierto de Khronos que proporciona un formato común y extensible para activos 3D que es tanto eficiente como altamente interoperable con las tecnologías web modernas.

Para añadir un modelo externo a una escena, añade un GltfContainer component a una entidad y configura su src al camino del archivo glTF que contiene el modelo.

const houseEntity = engine.addEntity()

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

El src campo es obligatorio, debes darle un valor al construir el componente. En el ejemplo anterior, el modelo está ubicado en una models carpeta en el nivel raíz de la carpeta del proyecto de la escena.

💡 Consejo: Recomendamos mantener tus modelos separados en la assets/scene/models carpeta dentro de tu escena.

Los modelos glTF pueden incluir sus propias texturas, materiales, colisionadores y animaciones incrustadas. Ver Modelos 3D para más información sobre esto. Para sobrescribir los materiales de un modelo, usa el GltfNodeModifiers component. Ver Modify glTF materials para más detalles.

Para evitar que los jugadores atraviesen un modelo 3D, o para hacer que un modelo sea clicable, debes tener un collider, que puede estar incrustado en el modelo o proporcionado vía un MeshCollider component.

Ten en cuenta que todos los modelos, sus shaders y sus texturas deben estar dentro de los parámetros de las scene limitations.

📔 Nota: El GltfContainer component debe importarse vía

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

Ver Imports para cómo manejarlos fácilmente.

Pre carga de un modelo 3D

En algunos casos, un modelo 3D personalizado se añade a la escena pero no se usa inmediatamente. Por ejemplo, un modelo de silla personalizado puede cargarse solo cuando el jugador interactúa con otro objeto. En este escenario, la primera interacción podría tomar algo de tiempo hasta que termine de descargarse y cargarse el modelo.

Para evitar esto, usa el AssetLoad.create método para asegurar que el activo se descargue antes de que sea necesario.

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

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

Para más información, consulta la documentación de Pre Load Resources .

Bibliotecas gratuitas de modelos 3D

En lugar de construir tus propios modelos 3D, también puedes descargarlos de varias bibliotecas gratuitas o de pago.

Para ayudarte a empezar, a continuación hay una lista de bibliotecas que tienen contenido gratuito o relativamente económico:

• IWB Catalog

• Asset Ovi

• Assets from the Builder

• SketchFab

• Clara.io

• Archive3D

• SketchUp 3D Warehouse

• Thingiverse (modelos 3D hechos principalmente para impresión 3D, pero adaptables a Virtual Worlds)

• ShareCG

• CGTrader

📔 Nota: Presta atención a las restricciones de licencia que tenga el contenido que descargues.

Ten en cuenta que en varios de estos sitios, puedes elegir en qué formato descargar el modelo. Siempre elige el formato .glTF si está disponible. Si no está disponible, debes convertirlos a glTF antes de poder usarlos en una escena. Para ello, recomendamos importarlos en Blender y exportarlos como .glTF desde allí.

Optimizar modelos 3D

Para asegurar que los modelos 3D en tu escena se carguen más rápido y ocupen menos memoria, sigue estas mejores prácticas:

• Guarda tus modelos en formato .glb , que es una versión más ligera de .gltf.

• Si tienes múltiples modelos que comparten las mismas texturas, exporta tus modelos con texturas en un archivo separado. De esa manera varios modelos pueden referirse a un único archivo de textura que solo necesita cargarse una vez.

• Si tu escena tiene entidades que aparecen y desaparecen, podría ser una buena idea agrupar estas entidades y mantenerlas bajo tierra, o con una escala de 0. Esto les ayudará a aparecer más rápido; la contrapartida es que ocuparán memoria cuando no estén en uso. Ver entities and components

Estirar una forma

Las formas primitivas y los modelos 3D tienen dimensiones predeterminadas que puedes alterar cambiando la escala en el 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 },
})

Hacer invisible

Puedes hacer una entidad invisible dándole a la entidad un VisibilityComponent, con su visible propiedad configurada a false.

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

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

El VisibilityComponent funciona igual para entidades con formas primitivas y con GLTFContainer components.

Si una entidad es invisible, su collider puede bloquear el camino de un jugador y/o impedir hacer clic en entidades que están detrás de ella, dependiendo de las capas de colisión asignadas al collider.

Propagar visibilidad

Puedes usar el propagateToChildren campo en el VisibilityComponent para aplicar una configuración a cada hijo en el árbol de hijos de la entidad. Si propagateToChildren está configurado a trueestas configuraciones afectan a todos los hijos en todos los niveles hacia abajo. Esto puede ahorrarte mucho trabajo tedioso marcando cada entidad hija como invisible o visible también.

// Entidad padre (explícitamente invisible)
const parentEntity = engine.addEntity()
Transform.create(parentEntity, {
	position: Vector3.create(4, 0, 4),
})
MeshRenderer.setBox(parentEntity)
VisibilityComponent.create(parentEntity, { visible: false, propagateToChildren: true })

// Entidad hija (implícitamente invisible debido al padre)
const child = engine.addEntity()
Transform.create(child, {
	position: Vector3.create(0, 1, 0),
	parent: parentEntity
})
MeshRenderer.setBox(child)

📔 Nota: Si una entidad tiene su propio VisibilityComponent , esto anula cualquier configuración de los padres.

Si una entidad no tiene su propio VisibilityComponent , entonces su visibilidad la determina su padre más cercano con un VisibilityComponent y propagateToChildren configurado a true.

Estado de carga

Si un modelo 3D es bastante grande, puede tardar un tiempo notable en renderizarse; este tiempo puede variar dependiendo del hardware del jugador y muchos otros factores. A veces necesitas asegurarte de que un modelo haya terminado de cargarse antes de realizar otra acción. Por ejemplo, si quieres teleportar al jugador a una plataforma en el cielo, primero necesitas asegurarte de que la plataforma esté completamente renderizada antes de mover al jugador allí, o de lo contrario el jugador podría caer a través de la plataforma.

Para comprobar si un modelo 3D ha terminado de renderizarse, verifica el GltfContainerLoadingState component de la entidad. Este componente está pensado para ser solo lectura, y existe en cualquier entidad que también tenga un GltfContainercomponent.

Este componente tiene una sola propiedad llamada currentState, que contiene un valor del LoadingState enum.

El siguiente ejemplo usa un sistema para comprobar periódicamente el estado de carga del modelo 3D de una entidad. Si el estado es LoadingState.FINISHED, quizá quieras ejecutar lógica personalizada allí y finalizar la ejecución del sistema.

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')
				// Ejecutar 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
		}
	})
}

Sintaxis avanzada

La sintaxis completa para crear un MeshRenderer component, sin ningún ayudante para simplificarla, se ve así:

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

Así es como el protocolo base interpreta los componentes MeshRenderer. Las funciones auxiliares abstraen esto y exponen una sintaxis más amigable, pero detrás de escena generan esta sintaxis.

El $case el campo te permite especificar uno de los tipos permitidos. Cada tipo admite un conjunto diferente de parámetros. En el ejemplo anterior, el caja type admite un uvs campo.

Los valores compatibles para $case son los siguientes:

• caja

• plano

• esfera

• cilindro

Dependiendo del valor de $case, es válido definir el objeto para la forma correspondiente, pasando las propiedades relevantes.

Para añadir un MeshRenderer component a una entidad que potencialmente ya tiene una instancia de este componente, usa MeshRenderer.createOrReplace(). Las funciones auxiliares como MeshRenderer.setBox() manejan la sobrescritura de instancias existentes del componente, pero ejecutar MeshRenderer.create() en una entidad que ya tiene este componente devuelve un error.