Shape Components

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

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

La forma renderizada de una entity está determinada por el component que usa.

Usa el Scene Editor en Creator Hub

La forma más fácil de darle una forma a una entity 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 Add Components.

Formas primitivas

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

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 opcional adicional, 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 opcional adicional, 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 cualquiera de los dos radiusTop o radiusBottom en 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, 0, 1)

Las formas primitivas no incluyen materials. Para darle un color o una texture, debes asignar un material component a la misma entity.

Para hacer que una primitive sea clickable, o para impedir que los players la atraviesen, debes darle a la entity un collider mediante un MeshCollider componente.

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

const myCube = engine.addEntity()

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

MeshRenderer.setBox(myCube)

// sobrescribir la forma
MeshRenderer.setSphere(myCube)

📔 Nota: El MeshRenderer component debe importarse mediante

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

Consulta Imports para ver cómo manejar esto fácilmente.

modelos 3D

Para formas más complejas, puedes construir un modelo 3D en una herramienta externa como Blender y luego importarlo 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 assets 3D que es a la vez eficiente y altamente interoperable con las tecnologías web modernas.

Para añadir un modelo externo a una scene, añade un GltfContainer component a una entity y establece su src a la ruta del archivo glTF que contiene el modelo.

const houseEntity = engine.addEntity()

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

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

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

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

Para evitar que los players atraviesen un modelo 3D, o para hacer que un modelo sea clickable, debes tener un collider, que puede estar integrado en el modelo o proporcionado mediante un MeshCollider componente.

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

📔 Nota: El GltfContainer component debe importarse mediante

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

Consulta Imports para ver cómo manejar esto fácilmente.

Precarga de un modelo 3D

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

Para evitar esto, usa el AssetLoad.create método para asegurar que el asset 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 documentación de Pre Load Resources .

Bibliotecas gratuitas de modelos 3D

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

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

• IWB Catalog

• Asset Ovi

• Assets de Builder

• SketchFab

• Clara.io

• Archive3D

• SketchUp 3D Warehouse

• Thingiverse (modelos 3D creados 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 descargas.

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

Optimizar modelos 3D

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

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

• Si tienes varios models que comparten las mismas textures, exporta tus models con las textures en un archivo separado. De ese modo, varios models pueden referenciar un único archivo de texture que solo necesita cargarse una vez.

• Si tu scene tiene entities que aparecen y desaparecen, puede ser una buena idea agrupar esas entities y mantenerlas bajo tierra, o con 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 and components

Estirar una forma

Las formas primitivas y los modelos 3D tienen dimensiones predeterminadas que puedes modificar 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 entity sea invisible dándole a una entity un VisibilityComponent, con su propiedad visible 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 entities con formas primitivas y con componentes GLTFContainer .

Si una entity es invisible, su collider puede bloquear el camino de un player y/o impedir hacer click en entities que estén detrás de ella, dependiendo de las collision layers asignadas al collider.

Propagar la visibilidad

Puedes usar el componente propagateToChildren campo en el VisibilityComponent para aplicar una configuración a cada child en el árbol de children de la entity. Si propagateToChildren se establece en true, estos ajustes afectan a todos los children en todos los niveles hacia abajo. Esto puede ahorrarte mucho trabajo tedioso al marcar cada child entity como invisible o visible también.

// Entity 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 })

// Entity child (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 entity tiene su propio VisibilityComponent, esto sobrescribe cualquier configuración de los padres.

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

Estado de carga

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

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

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

El siguiente ejemplo usa un system para comprobar periódicamente el estado de carga del modelo 3D de una entity. Si el estado es LoadingState.FINISHED, puede que quieras realizar 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 is LOADING')
				break
			case LoadingState.FINISHED:
				console.log('mesh is FINISHED')
				// Realizar 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 componente, sin usar ayudas para simplificarlo, 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 components de MeshRenderer. Las funciones de ayuda abstraen esto y exponen una sintaxis más amigable, pero detrás de escena generan esta 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 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 cualquier propiedad relevante.

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