Colliders

Aprende sobre los diferentes components que le 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 del jugador.

Los colliders también son necesarios 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 eventos de puntero; los colliders pueden configurarse para interactuar solo con una u otra. También pueden configurarse para interactuar con capas personalizadas, que pueden usarse con raycasts para manejar lo que tenga sentido en la escena.

📔 Nota: Los colliders no afectan cómo interactúan entre sí otras entidades; las entidades siempre pueden superponerse. Las configuraciones de colisión solo afectan cómo la entidad interactúa con el avatar del jugador y con 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 este comportamiento en la escena o importar una biblioteca para manejarlo.

Usar 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 Collision layers desde un menú desplegable.

También puedes configurar las capas de colisión en un GLTF componente para cambiar el valor predeterminado Collision layers usado ya sea en la geometría del collider o en la geometría visible del modelo. Ver Add Components.

Colliders en formas primitivas

El MeshCollider componente da a una entidad un collider simple 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 añadir a la entidad un MeshCollider componente.

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

• caja:

  Usar MeshCollider.setBox(), pasando la entidad.

• plano:

  Usar MeshCollider.setPlane(), pasando la entidad.

• esfera:

  Usar MeshCollider.setSphere(), pasando la entidad.

• cilindro:

  Usar MeshCollider.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.

Este ejemplo define una entidad en forma de caja que no puede ser atravesada.

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

// visible shape
MeshRenderer.setBox(myCollider)

// collider
MeshCollider.setBox(myCollider)

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

📔 Nota: El MeshCollider componente y ColliderLayer deben importarse vía

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

Ver Imports para ver 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, cuyo nombre termina en _collider. Por defecto, esta geometría se trata como un collider tanto para física como para eventos de puntero.

Cualquier malla integrada como parte de un modelo 3D cuyo nombre termine 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 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 que afecte a los sistemas de física o de eventos de puntero, puedes o bien:

• 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.

• Dar a la entidad un MeshCollider componente, para proporcionarle un collider de forma primitiva.

• Superponer una entidad invisible que tenga un MeshCollider componente.

• Editar 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 puede que quieras asignar la capa de colisión de eventos de puntero al visibleMeshesCollisionMask en caso de que quieras que las sugerencias de hover y los eventos de puntero respondan con mayor precisión al contorno de la entidad. Ten en cuenta que esto exige más al rendimiento.

📔 Nota: Asegúrate de no tener la misma capa (física, eventos de puntero o capas personalizadas) asignada a ambos visibleMeshesCollisionMask y invisibleMeshesCollisionMask, ya que eso sería un uso muy ineficiente de los recursos. Puedes tener capas diferentes en cada uno, por ejemplo física en la capa invisible y eventos de puntero en la capa visible.

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

// assign GLTF shape
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 vía

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

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

Modelos animados

Al configurar 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 mantienen su forma original. Si una animación implica deformar la geometría de una malla, las mallas del collider conservan la forma no animada mientras la animación se reproduce.

Al reproducir animaciones que implican mover mallas 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 se mueve con la animación.

Collision layers

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 respondan a un tipo de interacción, o a varias de ellas, o a ninguna. 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: Solo bloquea el movimiento del jugador (y no afecta a los eventos de puntero)

• ColliderLayer.CL_POINTER: Responde solo a eventos de puntero (y no bloquea el movimiento del jugador)

• ColliderLayer.CL_CUSTOM1 hasta CL_CUSTOM8: Pueden usarse junto con raycasts, de modo que un rayo solo detecte colisiones con una capa específica.

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

📔 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).

// create entity
const myEntity = engine.addEntity()
// visible shape
MeshRenderer.setBox(myEntity)

// create a MeshCollider component that only responds to player physics
MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS)

Una sola máscara de colisión puede responder a múltiples 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 diferentes para lo que mejor convenga 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 diferentes capas para distintos sistemas te permite usar menos recursos, ya que en cada caso solo comprobarás colisiones con las entidades relevantes.

Ver Raycasting para 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 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; puede que quieras evitar que la cámara atraviese paredes u otras entidades.

Para evitar que la cámara atraviese paredes, debes asignar tanto las ColliderLayer.CL_PHYSICS como las ColliderLayer.CL_POINTER capas a las entidades que quieras que bloqueen la cámara. Es importante que ambas capas estén asignadas 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 paredes:

Ambas capas ColliderLayer.CL_PHYSICS como las ColliderLayer.CL_POINTER están asignadas a la misma capa invisible de la geometría de la entidad. Si ambas estuvieran asignadas a la capa visible, el resultado sería el mismo. Este es el comportamiento por defecto, tanto al añadir una entidad vía el Creator Hub como por código.

En este segundo ejemplo, la cámara puede atravesar la pared porque la ColliderLayer.CL_PHYSICS capa está asignada a la capa invisible de la entidad, y la ColliderLayer.CL_POINTER capa está asignada a la capa visible de la entidad, incluso si ambas geometrías tienen la misma forma general.

// NO CAMERA GOING THROUGH THE WALL
// default (both pointer and physics use the invisible geometry)
GLTFContainer.create(myEntity, {
	src: '/models/myModel.gltf',
})

// NO CAMERA GOING THROUGH THE WALL
// Both use the same invisible geometry
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER,
})

// NO CAMERA GOING THROUGH THE WALL
// Both use the same visible geometry
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	visibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER,
})

// YES CAMERA GOES THROUGH THE WALL
// physics and pointer are on diferent layers
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
	visibleMeshesCollisionMask: ColliderLayer.CL_POINTER
})

// YES CAMERA GOES THROUGH THE WALL
// physics and pointer are on diferent layers
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
	visibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS
})

Bloqueo de punteros

Solo las formas que tienen colliders pueden activarse con pointer events. Una entidad también necesita tener un collider para bloquear que los eventos de puntero la atraviesen y evitar impactar entidades detrás de ella. Por ejemplo, un jugador no puede recoger algo que está dentro de un cofre si el cofre tiene colliders alrededor. Los eventos de puntero del jugador solo se ven afectados por las mallas 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 los colliders, una entidad también necesita tener un PointerEvents componente para responder a eventos de puntero. Los pointerEventsSystem helpers también se ocupan de este requisito.

// only responds to player physics
// for example for an invisible wall that you can't walk through but you can click through
MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS)

// only responds to the player's pointer
// for example for an item you can click to pick up, but can walk right through
MeshCollider.setBox(myEntity2, ColliderLayer.CL_POINTER)

Por defecto, la geometría visible de un GLTFContainer no está mapeada 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.

// default (both pointer and physics use the invisible geometry)
GLTFContainer.create(myEntity, {
	src: '/models/myModel.gltf',
})

// player physics uses the simpler invisible geometry
// pointer events use the full detailed contour of the visible geometry
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
	visibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
})

// both player physics and pointer events use the full detailed contour of the visible geometry
// the simpler invisible geometry is mapped to ColliderLayer.CL_NONE to avoid calculating both
GltfContainer.create(myEntity, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_NONE,
	visibleMeshesCollisionMask:
		ColliderLayer.CL_POINTER | ColliderLayer.CL_PHYSICS,
})

// don't respond to collisions of any kind, with either the visible or the invisible geometry:
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 bajo el capó generan esta sintaxis.

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

Los valores soportados 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.