Colisionadores

Aprende sobre los diferentes componentes que le dan a las entidades su forma 3D y colisión.

Las entidades que tienen colliders ocupan espacio y bloquean el paso del 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 botones se basan en la forma del collider de una entidad, no en su forma visible.

Existen capas de colisión separadas para interactuar con la física del jugador o con 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 otras entidades interactúan entre sí; 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 botones. Decentraland no tiene un motor de física nativo, por lo que si deseas que las entidades caigan, choquen o reboten, debes codificar ese comportamiento en la escena o importar una librería 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) a tu entidad. Luego puedes elegir Collision layers desde un desplegable.

También puedes configurar las capas de colisión en un GLTF componente para cambiar el Collision layers predeterminado 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 el 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 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 para esa forma.

• box:

  Usa MeshCollider.setBox(), pasando la entidad.

• plane:

  Usa MeshCollider.setPlane(), pasando la entidad.

• sphere:

  Usa MeshCollider.setSphere(), pasando la entidad.

• cylinder:

  Usa MeshCollider.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 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 tenga un modelo 3D desde un GLTFContainer componente, o a una entidad que no tenga 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 manejar estos 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 la física como para los eventos de puntero.

Cualquier malla incorporada como parte de un modelo 3D cuyo nombre termine en _collider se trata como parte de la capa invisibleMeshesCollisionMask 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 la física o a los sistemas de eventos de puntero, puedes:

• Asignar capas de colisión directamente a la geometría visible, a través de 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.

• Dar a la entidad un MeshCollider componente, para darle un collider con forma primitiva.

• Superponer una entidad invisible que tenga un MeshCollider componente.

• Editar el modelo en una herramienta externa como Blender para incluir una collider mesh. 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 pistas de hover y los eventos de puntero respondan con más 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 tanto a visibleMeshesCollisionMask y invisibleMeshesCollisionMask, ya que eso sería un uso muy ineficiente de los recursos. Puedes tener diferentes capas 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 3D models 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 manejar estos fácilmente.

Modelos animados

Al ajustar colliders para usar la geometría visible en un modelo que incluye armature-based animations, las animaciones no son seguidas por los colliders. Las mallas de collider mantienen su forma original. Si una animación implica deformar la geometría de una malla, las mallas de 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 responder solo a un tipo de interacción, o a varias de ellas, o a ninguna. Para hacer esto, en el MeshCollider establece la propiedad collisionMask, 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 detecte colisiones solo 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 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 diferentes capas personalizadas 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 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 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 ser 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 quieres 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 configuraciones evitará que la cámara atraviese paredes:

Ambas las ColliderLayer.CL_PHYSICS como las ColliderLayer.CL_POINTER capas 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 predeterminado, 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, aun cuando ambas geometrías tengan 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 puntero

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 capa ColliderLayer.CL_POINTER .

Por defecto, un MeshCollider afecta tanto a las capas de Physics como a las de Pointer, pero puedes cambiar este valor para afectar solo a una, a ninguna o para afectar 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 encargan 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 de Physics como a las de Pointer. Puedes cambiar este valor para afectar solo a una, a ninguna o para afectar 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, se ve 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 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:

• box

• plane

• sphere

• cylinder

Dependiendo del valor de $case, es válido definir el objeto para la forma correspondiente, pasando las propiedades relevantes.