Shape Components

Aprende sobre los diferentes Components que 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 un entity, y cada entidad puede incluir components que dan forma a sus características y funcionalidad.

La forma renderizada de una entidad está determinada por el componente que utiliza.

Usa Scene Editor en Creator Hub

La forma más sencilla de darle forma a una entidad es usar el Scene Editor. Puedes añadir un Mesh Renderer component para proporcionar una forma primitiva, o un GLTF component para referenciar un modelo 3D desde un archivo. Ver Añadir componentes.

Formas primitivas

Varias formas básicas, a menudo llamadas primitivas, se pueden añadir a una entidad dándole a la entidad un MeshRenderer componente.

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

• caja:

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

• plano:

  Usa MeshRenderer.setPlane(), pasando la entidad. Pasa uvs como un campo opcional adicional, para mapear la alineación de la textura. Ver materials para ver 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 cualquiera de los dos radiusTop o radiusBottom a 0 para hacer 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, 1, 0)

Las formas primitivas no incluyen materials. Para darles color o una textura, debes asignar un componente Material a la misma entidad.

Para hacer que una primitiva sea clicable, o para impedir que los jugadores caminen a través de ella, debes darle a la entidad un collider mediante un MeshCollider componente.

Para cambiar la forma de una entidad que ya tiene un MeshRenderer component, ejecuta MeshRenderer.setBox() o cualquiera de las otras funciones auxiliares y sobrescribirá la forma original. No hay necesidad de eliminar la original MeshRenderer 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: La MeshRenderer component debe importarse mediante

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

Consulta Imports para saber 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 a la vez eficiente y 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 establece su src en la ruta 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 se encuentra en una models carpeta en la raíz del directorio del proyecto de la escena.

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

Los modelos glTF pueden incluir sus propias textures, materials, colliders y animations incrustadas. Ver modelos 3D para más información sobre esto. Para sobrescribir los materials de un modelo, usa el GltfNodeModifiers component. Consulta Modificar materiales glTF para ver más detalles.

Para evitar que los jugadores atraviesen un modelo 3D, o para hacer clicable un modelo, debes tener un collider, que puede estar incrustado en el modelo o proporcionado mediante un MeshCollider componente.

Ten en cuenta que todos los modelos, sus shaders y sus textures deben estar dentro de los parámetros del las limitaciones de la escena.

📔 Nota: La GltfContainer component debe importarse mediante

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

Consulta Imports para saber cómo manejarlos fácilmente.

Precarga de un modelo 3D

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

Para evitar esto, usa el AssetLoad.create método para asegurarte de que el recurso se descargue antes de que se necesite.

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

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

Para más información, consulta la Precarga de recursos documentación.

Bibliotecas gratuitas para modelos 3D

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

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

• IWB Catalog

• Asset Ovi

• Assets de Builder

• SketchFab

• Clara.io

• Archive3D

• SketchUp 3D Warehouse

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

• ShareCG

• CGTrader

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

Ten en cuenta que en varios de estos sitios puedes elegir en qué formato descargar el modelo. Elige siempre .glTF el formato 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í.

Optimiza los modelos 3D

Para asegurarte de que los modelos 3D de tu escena carguen más rápido y ocupen menos memoria, sigue estas buenas prácticas:

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

• Si tienes varios modelos que comparten las mismas textures, exporta tus modelos con las textures en un archivo separado. De ese modo, 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 buena idea agrupar estas entidades y mantenerlas bajo tierra, o a una escala de 0. Esto ayudará a que aparezcan más rápido; la desventaja es que ocuparán memoria cuando no estén en uso. Ver entities y components

Estirar una forma

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

Hacer invisible

Puedes hacer que una entidad sea invisible dándole a una entidad un VisibilityComponent, con su visible propiedad establecida en 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 componentes.

Si una entidad es invisible, su collider puede bloquear el paso 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 la visibilidad

Puedes usar la 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 en true, estas configuraciones afectan a todos los hijos en todos los niveles descendentes. Esto puede ahorrarte mucho trabajo tedioso al marcar también cada entidad hija como invisible o visible.

// 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 sobrescribe cualquier configuración de los padres.

Si una entidad no tiene su propio VisibilityComponent, entonces su visibilidad está determinada por el padre más cercano que tenga un VisibilityComponent y propagateToChildren establecido en true.

Estado de carga

Si un modelo 3D es bastante grande, podría tardar un tiempo apreciable en renderizarse; este tiempo puede variar según el 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 teletransportar al jugador a una plataforma en el cielo, primero debes asegurarte de que la plataforma esté completamente renderizada antes de mover al jugador allí; de lo contrario, el jugador podría caer directamente a través de la plataforma.

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

Este componente tiene una única propiedad llamada currentState, que contiene un valor de LoadingState .

El siguiente ejemplo utiliza un System 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 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 está LOADING')
				break
			case LoadingState.FINISHED:
				console.log('mesh está FINISHED')
				// Realizar lógica personalizada
				break
			case LoadingState.FINISHED_WITH_ERROR:
				console.log('mesh está FINISHED PERO PUEDE TENER PROBLEMAS')
				break
			case LoadingState.UNKNOWN:
				console.log('mesh está en un ESTADO DESCONOCIDO')
				break
		}
	})
}

Sintaxis avanzada

La sintaxis completa para crear un MeshRenderer componente, sin ningún helper para simplificarlo, es así:

MeshRenderer.create(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 por detrás generan esta misma sintaxis.

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

Los valores admitidos 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 cualquier propiedad relevante.

Para añadir un MeshRenderer component a una entity que potencialmente ya tiene una instancia de este component, usa MeshRenderer.createOrReplace(). Las funciones auxiliares como MeshRenderer.setBox() se encargan de sobrescribir las instancias existentes del component, pero ejecutar MeshRenderer.create() en una entity que ya tiene este component devuelve un error.