Colliders

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

Las entities que tienen colliders ocupan espacio y bloquean el paso de un player; las entities sin colliders pueden ser atravesadas por el avatar del player.

Los colliders también son necesarios para hacer que una entity sea clickable. Los eventos de botón se basan en la forma del collider de una entity, no en su forma visible.

Hay capas de colisión separadas para interactuar con la física del player o con pointer events; los colliders se pueden configurar para interactuar solo con una u otra. También se pueden configurar para interactuar con capas personalizadas, que se pueden usar con raycasts para gestionar lo que tenga sentido para la escena.

📔 Nota: Los colliders no afectan cómo las demás entities interactúan entre sí; las entities siempre pueden superponerse. La configuración de colisión solo afecta cómo la entity interactúa con el avatar del player y con los eventos de botón. Decentraland no tiene un motor de físicas nativo, así que si quieres que las entities caigan, choquen o reboten, debes programar ese comportamiento en la escena o importar una biblioteca para manejarlo.

Usa el Scene Editor

La forma más sencilla de gestionar los colliders de una entity es usar el Scene Editor.

Puedes añadir un Mesh Collider a tu entity para asignarle una forma primitiva (cubo, plano, esfera, cilindro o cono) a tu entity. Luego puedes elegir Capas de colisión desde un desplegable.

También puedes configurar las capas de colisión en un GLTF para cambiar el valor predeterminado Capas de colisión usado en la geometría del collider o en la geometría visible del modelo. Ver Añadir componentes.

Colliders en formas primitivas

El MeshCollider componente le da a una entity un collider simple basado en una forma primitiva (cajas, esferas, planos, cilindros o conos).

Las entities que tienen un MeshRenderer componente para darles una forma primitiva no tienen colliders por defecto. También debes darle a la entity un MeshCollider componente.

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

• caja:

  Usa MeshCollider.setBox(), pasando la entity.

• plano:

  Usa MeshCollider.setPlane(), pasando la entity.

• esfera:

  Usa MeshCollider.setSphere(), pasando la entity.

• cilindro:

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

💡 Consejo: Establece cualquiera de radiusTop o radiusBottom a 0 para crear un cono.

Este ejemplo define una entity de caja que no se puede atravesar.

// crear entity
const myCollider = engine.addEntity()

// forma visible
MeshRenderer.setBox(myCollider)

// collider
MeshCollider.setBox(myCollider)

La forma usada por el MeshCollider no tiene por qué coincidir necesariamente con la usada por el MeshRenderer. También puedes añadir un MeshCollider a una entity que tiene un modelo 3D de un GLTFContainer componente, o a una entity que no tiene ninguna forma visible.

📔 Nota: El MeshCollider componente y ColliderLayer deben importarse mediante

import { MeshCollider, ColliderLayer } from "@dcl/sdk/ecs"

Ver Imports para ver cómo gestionarlos fácilmente.

Colliders en modelos 3D

A los modelos 3D se les pueden asignar colliders en dos niveles de geometría diferentes:

• visibleMeshesCollisionMask: Se refiere a la geometría visible del modelo. Por defecto, esta geometría no tiene colliders.

• invisibleMeshesCollisionMask: se refiere a las mallas collider, cuyos nombres terminan en _collider. Por defecto, esta geometría se trata como un collider tanto para physics como para pointer events.

Cualquier mesh incrustada como parte de un modelo 3D cuyo nombre termine en _collider se trata como parte de la invisibleMeshesCollisionMask capa, y se interpreta como un collider por defecto.

Definir la geometría del collider como una capa invisible separada permite un control mucho mayor y exige mucho menos al sistema que usar la geometría visible, ya que el objeto de colisión suele ser mucho más simple (con menos vértices) que el modelo original.

Si un modelo no tiene geometría de collider y quieres hacer que afecte a los sistemas de physics o pointer events, puedes hacer una de estas opciones:

• Asignar capas de colisión directamente a la geometría visible, mediante el visibleMeshesCollisionMask.

📔 Nota: Si la geometría visible del objeto tiene muchos vértices, ten en cuenta que esto puede tener un mayor coste de rendimiento.

• Dale a la entity un MeshCollider componente, para darle un collider de forma primitiva.

• Superpone una entity invisible que tenga un MeshCollider componente.

• Edita el modelo en una herramienta externa como Blender para incluir una malla collider. El collider debe llamarse x_collider, donde x es el nombre del modelo. Así que para un modelo llamado house, el collider debe llamarse house_collider.

También podrías querer asignar la capa de colisión de pointer events a la visibleMeshesCollisionMask en caso de que quieras que las hover hints y los pointer events respondan con más precisión al contorno de la entity. Ten en cuenta que esto exige más rendimiento.

📔 Nota: Asegúrate de no tener asignada la misma capa (physics, pointer events o custom layers) a ambos visibleMeshesCollisionMask y invisibleMeshesCollisionMask, ya que sería un uso muy ineficiente de los recursos. Puedes tener capas distintas en cada uno, como physics en la capa invisible y pointer events en la capa visible.

// crear entity
const myEntity = engine.addEntity()

// asigna forma GLTF
GltfContainer.create(myEntity, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
	visibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
})

Ver Modelos 3D para más detalles sobre cómo añadir geometría invisible de collider a un modelo 3D.

📔 Nota: El GltfContainer componente y ColliderLayer deben importarse mediante

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

Ver Imports para ver cómo gestionarlos fácilmente.

Modelos animados

Al configurar colliders para usar la geometría visible de un modelo que incluye animaciones basadas en armature, las animaciones no son seguidas por los colliders. Las mallas collider conservan su forma original. Si una animación implica deformar la geometría de un mesh, las mallas collider conservan la forma sin animar mientras se reproduce la animación.

Cuando se reproducen animaciones que implican mover meshes completas sin cambiar su forma, esos cambios se reflejan con precisión en los colliders. Por ejemplo, si una plataforma se mueve como parte de una animación, el collider de la plataforma también se mueve con la animación.

Capas de colisión

La escena puede manejar capas de colisión separadas, que tienen comportamientos diferentes.

Puedes configurar un MeshCollider componente o el GltfContainer componente para que responda solo a un tipo de interacción, a varios de ellos o a ninguno. Para hacerlo, en el MeshCollider establece el collisionMask propiedad, y en GltfContainer establece el visibleMeshesCollisionMask o invisibleMeshesCollisionMask propiedades a uno o varios de los siguientes valores:

• ColliderLayer.CL_PHYSICS: Bloquea el movimiento del player (paredes, suelos, plataformas de la escena). No afecta a pointer events.

• ColliderLayer.CL_POINTER: Responde solo a pointer events. No bloquea el movimiento del player.

• ColliderLayer.CL_PLAYER: Marca el collider como un marcador de avatar. Los raycasts y las trigger areas que apunten a CL_PLAYER lo detectarán, pero la cápsula del player lo atravesará directamente (sin bloqueo físico). En meshes de la escena, esto es útil para marcar un mesh como "un objetivo similar a un avatar" solo para detección.

• ColliderLayer.CL_MAIN_PLAYER: Como CL_PLAYER, pero dirigido solo al player local. Los raycasts y las trigger areas con CL_MAIN_PLAYER en su máscara lo detectan; los raycasts/trigger de avatares remotos no.

• ColliderLayer.CL_CUSTOM1 hasta CL_CUSTOM8: Se puede usar junto con raycasts y trigger areas para detectar colisiones solo con capas personalizadas específicas.

• ColliderLayer.CL_NONE: No responde a colisiones de ningún tipo.

💡 Consejo: CL_PLAYER y CL_MAIN_PLAYER en un MeshCollider / GltfContainer son solo de detección capas — la cápsula del player las atraviesa. Si quieres que el mesh pueda ser detectado TANTO como un avatar COMO bloquear físicamente al player, combina la capa de avatar con CL_PHYSICS (p. ej. CL_PHYSICS | CL_MAIN_PLAYER).

📔 NotaPara desactivar las colisiones de un MeshCollider componente, elimina el componente. No establezcas la capa de colisión en ColliderLayer.CL_NONE. Hay un problema conocido con el MeshCollider componente. En lugar de desactivar todas las colisiones, hace que este valor sea equivalente al predeterminado (ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER).

// crear entity
const myEntity = engine.addEntity()
// forma visible
MeshRenderer.setBox(myEntity)

// crea un componente MeshCollider que solo responde a la física del player
MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS)

Una sola máscara de colisión puede responder a varias capas de colisión. Usa el | carácter como un o, para incluir tantas capas como necesites. El valor predeterminado en un MeshCollider es ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER.

MeshCollider.setBox(
	myEntity,
	ColliderLayer.CL_CUSTOM1 |
		ColliderLayer.CL_CUSTOM3 |
		ColliderLayer.CL_PHYSICS |
		ColliderLayer.CL_POINTER
)

Puedes usar las 8 capas personalizadas distintas para lo que mejor se adapte a tu escena; por ejemplo, una podría usarse para cálculos de línea de visión de NPC, mientras que otra para estimar trayectorias de objetos que caen. Usar capas distintas para sistemas distintos te permite usar menos recursos, ya que en cada caso solo comprobarás colisiones con las entities relevantes.

Ver Raycasting para obtener más información sobre cómo usar capas de colisión personalizadas.

Cámaras y colliders

Cuando la cámara de un player se mueve en modo de tercera persona, la cámara puede quedar bloqueada por colliders o no, dependiendo de las capas de colisión asignadas a las entities. Ten esto en cuenta al diseñar tu escena; quizá quieras evitar que la cámara atraviese paredes u otras entities.

Para evitar que la cámara atraviese las paredes, debes asignar tanto la ColliderLayer.CL_PHYSICS y la ColliderLayer.CL_POINTER capas a las entities que quieres que bloqueen la cámara. Es importante que ambas capas se asignen a la misma geometría de la entity. Así que, si asignas la ColliderLayer.CL_PHYSICS capa a la geometría visible de la entity, también debes asignar la ColliderLayer.CL_POINTER capa a la misma geometría.

Por ejemplo, en Creator Hub, la siguiente combinación de ajustes impedirá que la cámara atraviese las paredes:

Ambas ColliderLayer.CL_PHYSICS y la ColliderLayer.CL_POINTER capas se asignan a la misma capa invisible de la geometría de la entity. Si ambas se asignaran a la capa visible, el resultado sería el mismo. Este es el comportamiento predeterminado, tanto al añadir una entity mediante Creator Hub como mediante código.

En este segundo ejemplo, la cámara puede atravesar la pared, porque la ColliderLayer.CL_PHYSICS capa se asigna a la capa invisible de la entity, y la ColliderLayer.CL_POINTER capa se asigna a la capa visible de la entity, aunque ambas geometrías tengan la misma forma general.

// NO DEJAR QUE LA CÁMARA ATRAVIESE LA PARED
// predeterminado (tanto pointer como physics usan la geometría invisible)
GLTFContainer.create(myEntity, {
	src: '/models/myModel.gltf',
})

// NO DEJAR QUE LA CÁMARA ATRAVIESE LA PARED
// Ambas usan la misma geometría invisible
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask:
		ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER,
})

// NO DEJAR QUE LA CÁMARA ATRAVIESE LA PARED
// Ambas usan la misma geometría visible
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	visibleMeshesCollisionMask:
		ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER,
})

// SÍ, LA CÁMARA ATRAVIESA LA PARED
// physics y pointer están en capas diferentes
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
	visibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
})

// SÍ, LA CÁMARA ATRAVIESA LA PARED
// physics y pointer están en capas diferentes
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
	visibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
})

Bloqueo de pointer

Solo las formas que tienen colliders pueden activarse con pointer events. Una entity también necesita tener un collider para bloquear que los pointer events la atraviesen y evitar golpear entities que estén detrás. Por ejemplo, un player no puede recoger algo que esté cerrado dentro de un cofre, si el cofre tiene colliders alrededor. Los pointer events del player solo se ven afectados por meshes que estén activas en la ColliderLayer.CL_POINTER capa.

Por defecto, un MeshCollider afecta tanto a las capas Physics como Pointer, pero puedes cambiar este valor para que solo afecte a una, o a ninguna, y para que afecte a capas personalizadas en su lugar.

📔 Nota: Además de colliders, una entity también necesita tener un PointerEvents componente para responder a pointer events. Los pointerEventsSystem helpers también se encargan de este requisito.

// solo responde a la física del player
// por ejemplo, para una pared invisible que no puedes atravesar pero sí clicar a través de ella
MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS)

// solo responde al pointer del player
// por ejemplo, para un item que puedes clicar para recoger, pero que puedes atravesar directamente
MeshCollider.setBox(myEntity2, ColliderLayer.CL_POINTER)

Por defecto, la geometría visible de un GLTFContainer no se asigna a ninguna capa de colisión, pero la geometría invisible afecta tanto a las capas Physics como Pointer. Puedes cambiar este valor para que solo afecte a una, o a ninguna, y para que afecte a capas personalizadas en su lugar. También puedes configurar la capa de la geometría visible de la misma manera.

// predeterminado (tanto pointer como physics usan la geometría invisible)
GLTFContainer.create(myEntity, {
	src: '/models/myModel.gltf',
})

// la física del player usa la geometría invisible más simple
// los pointer events usan el contorno completo y detallado de la geometría visible
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
	visibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
})

// tanto la física del player como los pointer events usan el contorno completo y detallado de la geometría visible
// la geometría invisible más simple se asigna a ColliderLayer.CL_NONE para evitar calcular ambas
GltfContainer.create(myEntity, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_NONE,
	visibleMeshesCollisionMask:
		ColliderLayer.CL_POINTER | ColliderLayer.CL_PHYSICS,
})

// no responden a colisiones de ningún tipo, ni con la geometría visible ni con la invisible:
GltfContainer.create(myEntity, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_NONE,
})

Sintaxis avanzada de MeshCollider

La sintaxis completa para crear un MeshCollider componente, sin ningún helper que la simplifique, es la siguiente:

MeshCollider.create(myBox, {
	mesh: {
		$case: 'box',
		box: {},
	},
})

MeshCollider.create(myPlane, {
	mesh: {
		$case: 'plane',
		plane: {},
	},
})

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

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

Así es como el protocolo base interpreta los componentes MeshCollider. Las funciones helper abstraen esto y exponen una sintaxis más amigable, pero por debajo generan esta sintaxis.

El $case el campo te permite especificar uno de los tipos permitidos. Cada tipo admite un conjunto diferente de parámetros.

Los valores admitidos para $case son los siguientes:

• caja

• plano

• esfera

• cilindro

Según el valor de $case, es válido definir el objeto para la forma correspondiente, pasando cualquier propiedad relevante.