Colliders

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

Las entidades que tienen colliders ocupan espacio y bloquean el camino de un jugador; las entidades sin colliders pueden ser atravesadas por el avatar de un jugador.

También se necesitan colliders para que una entidad sea clicable. Los eventos de botón se basan en la forma del collider de una entidad, no en su forma visible.

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

📔 Nota: Los colliders no afectan cómo otras entidades interactúan entre sí; las entidades siempre pueden superponerse. Los ajustes de colisión solo afectan cómo interactúa la entidad con el avatar del jugador y los eventos de botón. Decentraland no tiene un motor de física nativo, así que si quieres que las entidades 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 fácil de gestionar los colliders de una entidad es usar el Scene Editor.

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

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

Colliders en formas primitivas

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

Las entidades que tienen un MeshRenderer componente para darles una forma primitiva no tienen colliders por defecto. También debes darle a la entidad 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 entidad.

• plano:

  Usa MeshCollider.setPlane(), pasando la entidad.

• esfera:

  Usa MeshCollider.setSphere(), pasando la entidad.

• cilindro:

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

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

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

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

// forma visible
MeshRenderer.setBox(myCollider)

// collider
MeshCollider.setBox(myCollider)

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

📔 Nota: El MeshCollider componente y ColliderLayer deben importarse mediante

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

Consulta Imports para saber cómo manejarlos 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 de 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 termina en _collider se trata como parte de la invisibleMeshesCollisionMask layer, y se interpreta como un collider por defecto.

Definir la geometría del collider como una capa invisible separada permite mucho más control 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 ninguna geometría de collider, y quieres hacer que afecte a los sistemas de physics o pointer events, puedes hacer una de estas cosas:

• Asignar capas de colisión directamente a la geometría visible, mediante la 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 entidad un MeshCollider componente, para darle un collider de forma primitiva.

• Superpone una entidad invisible que tenga un MeshCollider componente.

• Edita el modelo en una herramienta externa como Blender para incluir un mesh de 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 pistas al pasar el cursor y los pointer events respondan con más precisión al contorno de la entidad. Ten en cuenta que esto exige más rendimiento.

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

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

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

Consulta 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"

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

Modelos animados

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

Al reproducir animaciones que implican mover meshes completas sin cambiar su forma, estos 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 solo responda a un tipo de interacción, o a varios, o a ninguno. Para hacerlo, en el MeshCollider establece la collisionMask propiedad, y en GltfContainer establece la visibleMeshesCollisionMask o invisibleMeshesCollisionMask propiedades a uno o varios de los siguientes valores:

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

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

• 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 jugador lo atraviesa directamente (sin bloqueo físico). En meshes de escena, esto es útil para marcar una mesh como "un objetivo tipo avatar" solo para detección.

• ColliderLayer.CL_MAIN_PLAYER: Similar a CL_PLAYER, pero dirigido solo al jugador 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: Puede usarse 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 layers — la cápsula del jugador los atraviesa. Si quieres que la mesh sea detectada COMO avatar Y además bloquee físicamente al jugador, combina la capa de avatar con CL_PHYSICS (p. ej. CL_PHYSICS | CL_MAIN_PLAYER).

📔 Nota: Para 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 entidad
const myEntity = engine.addEntity()
// forma visible
MeshRenderer.setBox(myEntity)

// crear un componente MeshCollider que solo responde a la física del jugador
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 opara 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 diferentes 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 diferentes para sistemas diferentes te permite usar menos recursos, ya que en cada caso solo comprobarás colisiones con las entidades relevantes.

Consulta 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 jugador se mueve en modo en tercera persona, la cámara puede quedar bloqueada por colliders o no, dependiendo de las capas de colisión asignadas a las entidades. Ten esto en cuenta al diseñar tu escena; quizá quieras evitar que la cámara atraviese paredes u otras entidades.

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

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

Tanto la ColliderLayer.CL_PHYSICS y la ColliderLayer.CL_POINTER capas se asignan a la misma capa invisible de la geometría de la entidad. Si ambas se asignaran a la capa visible, el resultado sería el mismo. Este es el comportamiento predeterminado, tanto al añadir una entidad mediante el 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 entidad, y la ColliderLayer.CL_POINTER capa se asigna a la capa visible de la entidad, aunque ambas geometrías tengan la misma forma general.

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

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

// NO, LA CÁMARA ATRAVIESA 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 entidad también necesita tener un collider para bloquear que los pointer events la atraviesen y evitar golpear entidades que estén detrás. Así que, por ejemplo, un jugador no puede recoger algo que está encerrado dentro de un cofre si el cofre tiene colliders a su alrededor. Los pointer events del jugador solo se ven afectados por las meshes que están activas en la ColliderLayer.CL_POINTER layer.

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

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

// solo responde a la física del jugador
// 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 jugador
// por ejemplo, para un objeto 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 afectar solo a una, o a ninguna, y afectar en su lugar a capas personalizadas. 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 jugador usa la geometría invisible más sencilla
// 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 jugador como los pointer events usan el contorno completo y detallado de la geometría visible
// la geometría invisible más sencilla 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 responde 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 para simplificarlo, es así:

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 detrás de escena generan esta sintaxis.

El $case 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

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