> 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 entidades que tienen colliders ocupan espacio y bloquean el camino del jugador; las entidades sin colliders pueden ser atravesadas por el avatar del jugador. Los colliders también son necesarios para hacer que una entidad sea clicable. Los eventos del botón 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 los eventos del 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](/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/colliders.md) para manejar lo que tenga sentido para la escena. {% hint style="warning" %} **📔 Nota**: Los colliders no afectan cómo interactúan entre sí otras entidades; las entidades siempre pueden superponerse. La configuración de colisión solo afecta cómo interactúa la entidad con el avatar del jugador y los eventos del 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 encargarse de ello. {% endhint %} ## Usa el Scene Editor La forma más sencilla de gestionar los colliders de una entidad es usar el [Scene Editor](/creator/content-creator-es/scene-editor/primeros-pasos/about-editor.md). Puedes añadir un **MeshCollider** componente a tu entidad para asignarle una forma primitiva (cubo, plano, esfera, cilindro o cono). Luego puedes elegir [capas de colisión](#collision-layers) de un menú desplegable. También puedes configurar las capas de colisión en un **GLTF** componente para cambiar el [capas de colisión](#collision-layers) predeterminado que se usa tanto en la geometría del collider como en la geometría visible del modelo. Consulta [Añadir componentes](/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-a1566c33728b1ef858f518365390d2ce5c97fe82%2Fgltf-component.png?alt=media\&token=43fa7d3f-2ed6-48b5-9fcd-842c8a75c4dc) ## Colliders en formas primitivas El `MeshCollider` componente proporciona a una entidad un collider simple basado en una forma primitiva (cajas, esferas, planos, cilindros o conos). Las entidades que tienen un `MeshRenderer` component para darles una [forma primitiva](/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/shape-components.md#primitive-shapes) no tienen colliders por defecto. También debes dar 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. {% hint style="info" %} **💡 Consejo**: Establece `radiusTop` o `radiusBottom` en 0 para crear un cono. {% endhint %} Este ejemplo define una entidad en forma de caja que no se puede atravesar. ```ts // crear entidad const myCollider = engine.addEntity() // forma visible MeshRenderer.setBox(myCollider) // collider MeshCollider.setBox(myCollider) ``` La forma usada por el `MeshCollider` no necesariamente tiene que coincidir 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. {% hint style="warning" %} **📔 Nota**: El `MeshCollider` componente y `ColliderLayer` deben importarse mediante `import { MeshCollider, ColliderLayer } from "@dcl/sdk/ecs"` Consulta [Imports](/creator/content-creator-es/scenes-sdk7/primeros-pasos/coding-scenes.md#imports) para ver cómo manejar esto fácilmente. {% endhint %} ## 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, cuyo nombre termina en `_collider`. Por defecto, esta geometría se trata como un collider tanto para la física como para los eventos del puntero. Cualquier malla incrustada como parte de un modelo 3D cuyo nombre termina en `_collider` se trata como parte de la `invisibleMeshesCollisionMask` layer y se interpreta como 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 ninguna geometría collider y quieres hacer que afecte a los sistemas de física o de eventos del puntero, puedes hacer una de estas dos cosas: `visibleMeshesCollisionMask`. {% hint style="warning" %} **📔 Nota**: Si la geometría visible del objeto tiene muchos vértices, ten en cuenta que esto puede tener un mayor coste de rendimiento. {% endhint %} * Dale 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 *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*. Puede que también quieras asignar la capa de colisión de eventos del puntero a la `visibleMeshesCollisionMask` en caso de que quieras que las pistas al pasar el cursor y los eventos del puntero respondan con mayor precisión al contorno de la entidad. Ten en cuenta que esto exige más rendimiento. {% hint style="warning" %} **📔 Nota**: Asegúrate de no tener la misma capa (física, eventos del 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, como física en la capa invisible y eventos del puntero en la capa visible. {% endhint %} ```ts // 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](https://github.com/decentraland/docs/blob/main/creator/3d-modeling/3d-models.md) para más detalles sobre cómo añadir geometría invisible de collider a un modelo 3D. {% hint style="warning" %} **📔 Nota**: El `GltfContainer` componente y `ColliderLayer` deben importarse mediante > `import { GltfContainer, ColliderLayer } from "@dcl/sdk/ecs"` Consulta [Imports](/creator/content-creator-es/scenes-sdk7/primeros-pasos/coding-scenes.md#imports) para ver cómo manejar esto fácilmente. {% endhint %} ### Modelos animados Al configurar colliders para usar la geometría visible de un modelo que incluye [animaciones basadas en armature](/creator/content-creator-es/modelado-y-animaciones-3d/animations.md), las animaciones no son seguidas por los colliders. Las mallas collider mantienen su forma original. Si una animación implica deformar la geometría de una malla, las mallas collider conservan la forma no animada mientras se reproduce la animación. Cuando se reproducen 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 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, a varios de ellos o a ninguno. Para hacerlo, en el `MeshCollider` establece la `collisionMask` propiedad, y en `GltfContainer` establece la `visibleMeshesCollisionMask` o `invisibleMeshesCollisionMask` propiedades con uno o varios de los siguientes valores: * `ColliderLayer.CL_PHYSICS`: Bloquea el movimiento del jugador (paredes, pisos, plataformas de la escena). No afecta a los eventos del puntero. * `ColliderLayer.CL_POINTER`: Responde solo a los eventos del puntero. No bloquea el movimiento del jugador. * `ColliderLayer.CL_PLAYER`: Etiqueta el collider como un marcador de avatar. Los raycasts y las áreas de trigger que apunten a `CL_PLAYER` lo detectarán, pero la cápsula del jugador lo atraviesa directamente (sin bloqueo físico). En las mallas de la escena, esto es útil para marcar una malla como "un objetivo similar a un avatar" solo para detección. * `ColliderLayer.CL_MAIN_PLAYER`: Igual que `CL_PLAYER`, pero dirigido solo al jugador local. Los raycasts y las áreas de trigger con `CL_MAIN_PLAYER` en su máscara lo detectan; los raycasts/triggers de avatares remotos no. * `ColliderLayer.CL_CUSTOM1` hasta `CL_CUSTOM8`: Puede usarse junto con raycasts y áreas de trigger para detectar colisiones solo con capas personalizadas específicas. * `ColliderLayer.CL_NONE`: No responde a colisiones de ningún tipo. {% hint style="info" %} **💡 Consejo**: `CL_PLAYER` y `CL_MAIN_PLAYER` en un `MeshCollider` / `GltfContainer` son **solo de detección** las capas — la cápsula del jugador las atraviesa. Si quieres que la malla sea TANTO detectable como un avatar Y bloquee físicamente al jugador, combina la capa del avatar con `CL_PHYSICS` (p. ej. `CL_PHYSICS | CL_MAIN_PLAYER`). {% endhint %} {% hint style="warning" %} **📔 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`). {% endhint %} ```ts // 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 *o*, para incluir tantas capas como necesites. El valor predeterminado en 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 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 estarás comprobando colisiones con las entidades relevantes. Consulta [Raycasting](/creator/content-creator-es/scenes-sdk7/interactividad/raycasting.md) para saber 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 de 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; 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 quieres 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 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-426b56fda6516e2c2e63296a534d02aa089a566e%2Fcolliders-camera.png?alt=media\&token=7e7dbaa9-0e4f-47b7-8efe-13456cb1761b) Ambas `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 Creator Hub como mediante código. ![](https://1216664193-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-6c77ca6fce6934f939ce70f2146d972718a25556%2Fcolliders-no-camera.png?alt=media\&token=63d0c60e-c267-45df-a44a-f2c5c58f37b7) 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. ```ts // 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 del puntero Solo las formas que tienen colliders pueden activarse con [eventos del puntero](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-button/click-events.md). Una entidad también necesita tener un collider para bloquear que los eventos del puntero la atraviesen y evitar golpear a las 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 alrededor. Los eventos del puntero del jugador solo se ven afectados por las mallas 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 que solo afecte a una, o a ninguna, y para que afecte a capas personalizadas en su lugar. {% hint style="warning" %} **📔 Nota**: Además de colliders, una entidad también necesita tener un `PointerEvents` componente para responder a los eventos del puntero. Los `pointerEventsSystem` helpers 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í atravesar con clics MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS) // solo responde al puntero del jugador // por ejemplo, para un objeto que puedes hacer clic para recoger, pero que puedes atravesar 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 geometría visible de la misma manera. ```ts // 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 simple // los eventos del 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 del puntero usan el contorno detallado completo 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 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 que la simplifique, se ve así: ```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 helper abstraen esto y exponen una sintaxis más amigable, pero detrás de escena 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. --- # 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=&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.