> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/colliders.md).

# Colliders

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

Las Entities que tienen colliders ocupan espacio y bloquean el paso del jugador; las Entities sin colliders permiten que el Avatar del jugador las atraviese.

Los colliders también son necesarios para que una Entity se pueda hacer clic. 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 independientes para interactuar con la física del jugador o con los eventos de Pointer. Los colliders se pueden configurar para interactuar solo con una de ellas. También se pueden configurar para interactuar con capas personalizadas, que se pueden usar con [raycasts](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/colliders.md) para gestionar lo que tenga sentido en la Scene.

{% hint style="warning" %}
**📔 Nota**: Los colliders no afectan a la interacción entre otras Entities: siempre pueden superponerse. La configuración de colisión solo afecta a la interacción de la Entity con el Avatar del jugador y los eventos de botón. Decentraland no tiene un motor de física nativo; por lo tanto, si quieres que las Entities caigan, choquen o reboten, debes programar ese comportamiento en la Scene o importar una Library para gestionarlo.
{% endhint %}

## Usar el Scene Editor

La forma más fácil de gestionar los colliders de una Entity es usar el [Scene Editor](https://docs.decentraland.org/creator/content-creator-es/scene-editor/primeros-pasos/about-editor.md).

Puedes añadir un componente **Mesh Collider** a tu Entity para asignarle una forma primitiva (cubo, plano, esfera, cilindro o cono). Luego puedes elegir las [capas de colisión](#collision-layers) en un menú desplegable.

También puedes configurar las capas de colisión de un componente **GLTF** para cambiar las [capas de colisión](#collision-layers) predeterminadas que se usan en la geometría del collider o en la geometría visible del modelo. Consulta [Añadir Components](https://docs.decentraland.org/creator/content-creator-es/scene-editor/construir/components.md#add-components).

![](https://1216664193-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-cd083f0f07f0a22b49439dfd684be0b23e825cc5%2Fgltf-component.webp?alt=media)

## Colliders en formas primitivas

El componente `MeshCollider` proporciona a una Entity un collider sencillo basado en una forma primitiva (cajas, esferas, planos, cilindros o conos).

Las Entities que tienen un componente `MeshRenderer` para asignarles una [forma primitiva](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/shape-components.md#primitive-shapes) no tienen colliders de forma predeterminada. También debes asignar a la Entity un componente `MeshCollider` .

Las siguientes formas de collider están disponibles en `MeshCollider`. Algunas 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 entidad. Pasa `radiusTop` y `radiusBottom` como campos opcionales adicionales para modificar el cilindro.

{% hint style="info" %}
**💡 Consejo**: Establece `radiusTop` o `radiusBottom` en 0 para crear un cono.
{% endhint %}

En este ejemplo se define una entidad con forma de caja por la que no se puede caminar.

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

// forma visible
MeshRenderer.setBox(myCollider)

// collider
MeshCollider.setBox(myCollider)
```

La forma que usa el `MeshCollider` no tiene por qué coincidir necesariamente con la que usa el `MeshRenderer`. También puedes añadir un `MeshCollider` a una entidad que tenga un modelo 3D de un componente `GltfContainer` o a una entidad que no tenga ninguna forma visible.

{% hint style="warning" %}
**📔 Nota**: El componente `MeshCollider` y `ColliderLayer` deben importarse mediante

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

Consulta [Importaciones](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/primeros-pasos/coding-scenes.md#imports) para saber cómo gestionarlas fácilmente.
{% endhint %}

## Colliders en modelos 3D

Se pueden asignar colliders a los modelos 3D en dos niveles de geometría distintos:

* `visibleMeshesCollisionMask`: Hace referencia a la geometría visible del modelo. De forma predeterminada, esta geometría no tiene colliders.
* `invisibleMeshesCollisionMask`: hace referencia a las mallas de collider, cuyos nombres terminan en `_collider`. De forma predeterminada, esta geometría se trata como un collider tanto para la física como para los eventos del puntero.

Cualquier malla integrada como parte de un modelo 3D cuyo nombre termine en `_collider` se trata como parte de la capa `invisibleMeshesCollisionMask` y, de forma predeterminada, se interpreta como un collider.

Definir la geometría del collider como una capa invisible independiente permite un control mucho mayor y exige muchos menos recursos del sistema que usar la geometría visible, ya que el objeto de colisión suele ser mucho más sencillo (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 PointerEvents, puedes hacer lo siguiente:

* Asignar capas de colisión directamente a la geometría visible mediante `visibleMeshesCollisionMask`.

{% hint style="warning" %}
**📔 Nota**: Si la geometría visible del objeto tiene muchos vértices, ten en cuenta que esto puede afectar más al rendimiento.
{% endhint %}

* Asignar a la Entity un componente `MeshCollider` para darle un Collider de forma primitiva.
* Superponer una Entity invisible que tenga un componente `MeshCollider` .
* Editar 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. Por ejemplo, para un modelo llamado *house*, el Collider debe llamarse *house\_collider*.

También puedes asignar la capa de colisión de PointerEvents a `visibleMeshesCollisionMask` si quieres que las indicaciones al pasar el cursor y los PointerEvents respondan con mayor precisión al contorno de la Entity. Ten en cuenta que esto exige más rendimiento.

{% hint style="warning" %}
**📔 Nota**: Asegúrate de no asignar la misma capa (de física, PointerEvents o capas personalizadas) tanto a `visibleMeshesCollisionMask` como a `invisibleMeshesCollisionMask`, ya que sería un uso muy ineficiente de los recursos. Puedes asignar capas distintas a cada una, como física a la capa invisible y PointerEvents a la capa visible.
{% endhint %}

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

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

Consulta [3D models](https://github.com/decentraland/docs/blob/main/creator/3d-modeling/3d-models.md) para obtener más información sobre cómo añadir geometría invisible de Collider a un modelo 3D.

{% hint style="warning" %}
**📔 Nota**: El componente `GltfContainer` y `ColliderLayer` deben importarse mediante

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

Consulta [Importaciones](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/primeros-pasos/coding-scenes.md#imports) para saber cómo gestionarlas fácilmente.
{% endhint %}

### Modelos animados

Al configurar los Colliders para que usen la geometría visible de un modelo que incluye [animaciones basadas en armature](https://docs.decentraland.org/creator/content-creator-es/modelado-y-animaciones-3d/animations.md), los Colliders no siguen las animaciones. Los meshes de Collider mantienen su forma original. Si una animación deforma la geometría de un mesh, los meshes de Collider conservan la forma sin animar mientras se reproduce la animación.

Al reproducir animaciones que mueven Meshes completos sin cambiar su forma, los Colliders reflejan estos cambios con precisión. Por ejemplo, si una plataforma se mueve como parte de una animación, su Collider también se mueve con ella.

## Capas de colisión

La Scene puede gestionar capas de colisión independientes, cada una con comportamientos distintos.

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

* `ColliderLayer.CL_PHYSICS`: bloquea el movimiento del jugador (paredes, suelos y plataformas de la Scene). No afecta a los PointerEvents.
* `ColliderLayer.CL_POINTER`: responde únicamente a los PointerEvents. No bloquea el movimiento del jugador.
* `ColliderLayer.CL_PLAYER`: marca el Collider como indicador de Avatar. Los Raycasts y las áreas Trigger que tengan como objetivo `CL_PLAYER` lo detectarán, pero la cápsula del jugador lo atravesará (no bloquea físicamente el paso). En los Meshes de la Scene, esto resulta útil para marcar un Mesh como «objetivo similar a un Avatar» solo para su detección.
* `ColliderLayer.CL_MAIN_PLAYER`: igual que `CL_PLAYER`, pero solo para el jugador local. Los Raycasts y las áreas Trigger que tengan `CL_MAIN_PLAYER` en su máscara lo detectarán; los Raycasts y las áreas Trigger de Avatars remotos no.
* `ColliderLayer.CL_CUSTOM1` hasta `CL_CUSTOM8`: se pueden usar junto con Raycasts y áreas Trigger para detectar colisiones únicamente con capas personalizadas específicas.
* `ColliderLayer.CL_NONE`: no responde a ningún tipo de colisión.

{% hint style="info" %}
**💡 Consejo**: `CL_PLAYER` y `CL_MAIN_PLAYER` en un `MeshCollider` / `GltfContainer` son capas **solo de detección** : la cápsula del jugador las atraviesa. Si quieres que el Mesh sea detectable como Avatar Y bloquee físicamente al jugador, combina la capa de Avatar con `CL_PHYSICS` (por ejemplo, `CL_PHYSICS | CL_MAIN_PLAYER`).
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: Para desactivar las colisiones de un `MeshCollider` componente, elimina el componente. No configures la capa de colisión como `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`).
{% endhint %}

```ts
// crear entidad
const myEntity = engine.addEntity()
// forma visible
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 varias capas de colisión. Usa el `|` carácter como un *o*, para incluir tantas capas como necesites. El valor predeterminado de un MeshCollider es `ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER`.

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

Puedes usar las 8 capas personalizadas para lo que mejor se adapte a tu escena. Por ejemplo, una podría usarse para calcular la línea de visión de los NPC y otra para estimar las trayectorias de objetos que caen. Usar capas distintas para sistemas diferentes permite consumir menos recursos, ya que en cada caso solo comprobarás las colisiones con las Entities pertinentes.

Consulta [Raycasting](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/raycasting.md) 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, los colliders pueden bloquearla o no, según las capas de colisión asignadas a las Entities. Ten esto en cuenta al diseñar la 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 capa `ColliderLayer.CL_PHYSICS` como la capa `ColliderLayer.CL_POINTER` a las Entities que quieras que bloqueen la cámara. Es importante asignar ambas capas a la misma geometría de la Entity. Por ejemplo, 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 esa misma geometría.

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

![](https://1216664193-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-e96f22c107aa35e481cd8f5291a05a99ada94904%2Fcolliders-camera.webp?alt=media)

Tanto la capa `ColliderLayer.CL_PHYSICS` como la capa `ColliderLayer.CL_POINTER` están asignadas a la misma geometría invisible de la Entity. Si ambas estuvieran asignadas a la geometría visible, el resultado sería el mismo. Este es el comportamiento predeterminado, tanto al añadir una Entity desde Creator Hub como al hacerlo mediante código.

![](https://1216664193-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-f7a82c53ff9beda10234dbbdcfb805bb9d71e4f0%2Fcolliders-no-camera.webp?alt=media)

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

```ts
// 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
// Ambos 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
// la física y el puntero 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
// la física y el puntero están en capas diferentes
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
	visibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
})
```

### Bloqueo del Pointer

Solo se pueden activar las formas que tienen colliders con [eventos de puntero](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-button/click-events.md). Una Entity también necesita tener un collider para bloquear los eventos de puntero e impedir que lo atraviesen y alcancen las Entities que están detrás. Por ejemplo, un jugador no puede recoger algo que está encerrado en un cofre si el cofre tiene colliders a su alrededor. Los eventos de puntero del jugador solo se ven afectados por los Meshes que están activos en la capa `ColliderLayer.CL_POINTER` .

De forma predeterminada, un MeshCollider afecta tanto a las capas Physics como Pointer, pero puedes cambiar este valor para que afecte solo a una, a ninguna o a capas personalizadas.

{% hint style="warning" %}
**📔 Nota**: Además de colliders, una Entity también necesita tener un componente `PointerEvents` para responder a los eventos de puntero. Los helpers de `pointerEventsSystem` también se encargan de este requisito.
{% endhint %}

```ts
// solo responde a la física del jugador
// por ejemplo, para una pared invisible que no puedes atravesar, pero sí puedes atravesar con un clic
MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS)

// solo responde al puntero del jugador
// por ejemplo, para un objeto en el que puedes hacer clic para recogerlo, pero que puedes atravesar
MeshCollider.setBox(myEntity2, ColliderLayer.CL_POINTER)
```

De forma predeterminada, 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 afecte solo a una, a ninguna o a capas personalizadas. También puedes configurar de la misma manera la capa de la geometría visible.

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

// la física del jugador usa la geometría invisible, más sencilla
// los eventos de puntero usan el contorno detallado completo 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 eventos de puntero usan el contorno detallado completo 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 responder 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 componente `MeshCollider` sin helpers que la simplifiquen es la siguiente:

```ts
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 auxiliares abstraen esta complejidad y ofrecen una sintaxis más sencilla, pero internamente generan esta sintaxis.

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

Los valores admitidos para `$case` son los siguientes:

* `box`
* `plane`
* `sphere`
* `cylinder`

Según el valor de `$case`, es válido definir el objeto para la forma correspondiente y pasar las propiedades pertinentes.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/colliders.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
