> 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-pt/scenes-sdk7/essenciais-de-conteudo-3d/colliders.md). # Colliders Entities que têm colliders ocupam espaço e bloqueiam o caminho de um player, Entities sem colliders podem ser atravessadas pelo avatar de um player. Colliders também são necessários para tornar uma Entity clicável. Os button events são baseados na forma do collider de uma Entity, e não na sua forma visível. Há layers de collision separadas para interagir com a física do player ou com pointer events; colliders podem ser configurados para interagir apenas com uma ou outra. Eles também podem ser configurados para interagir com layers personalizadas, que podem ser usadas com [raycasts](/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/colliders.md) para lidar com o que fizer sentido para a scene. {% hint style="warning" %} **📔 Nota**: Colliders não afetam como outras Entities interagem entre si; entities podem sempre se sobrepor. As collision settings só afetam como a Entity interage com o avatar do player e com button events. Decentraland não tem um physics engine nativo, então se você quiser que Entities caiam, batam ou quiquem, você deve codificar esse comportamento na scene ou importar uma library para lidar com isso. {% endhint %} ## Use o Scene Editor A maneira mais fácil de gerenciar os colliders de uma Entity é usar o [Scene Editor](/creator/content-creator-pt/scene-editor/comecar/about-editor.md). Você pode adicionar um **Mesh Collider** component à sua Entity para atribuir uma forma primitiva (cubo, plano, esfera, cilindro ou cone) à sua Entity. Em seguida, você pode escolher [layers de collision](#collision-layers) num dropdown. Você também pode configurar as collision layers em um **GLTF** component para alterar o padrão [layers de collision](#collision-layers) usado na geometria do collider ou na geometria visível do modelo. Veja [Adicionar Components](/creator/content-creator-pt/scene-editor/construir/components.md#add-components). ![](/files/ab25955c85c888292d8d42aabc90e2afd354c6a1) ## Colliders em formas primitivas O `MeshCollider` component fornece a uma Entity um collider simples baseado em uma forma primitiva (caixas, esferas, planos, cilindros ou cones). Entities que têm um `MeshRenderer` component para lhes dar uma [forma primitiva](/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/shape-components.md#primitive-shapes) não têm colliders por padrão. Você também deve dar à Entity um `MeshCollider` component. As seguintes formas de collider estão disponíveis em `MeshCollider`. Várias formas incluem campos adicionais opcionais, específicos para essa forma. * **box**: Use `MeshCollider.setBox()`, passando a Entity. * **plane**: Use `MeshCollider.setPlane()`, passando a Entity. * **sphere**: Use `MeshCollider.setSphere()`, passando a Entity. * **cylinder**: Use `MeshCollider.setCylinder()`, passando a Entity. Passe `radiusTop` e `radiusBottom` como campos opcionais adicionais para modificar o cylinder. {% hint style="info" %} **💡 Dica**: Defina seja `radiusTop` ou `radiusBottom` para 0 para criar um cone. {% endhint %} Este exemplo define uma Entity box que não pode ser atravessada. ```ts // criar Entity const myCollider = engine.addEntity() // forma visível MeshRenderer.setBox(myCollider) // collider MeshCollider.setBox(myCollider) ``` A forma usada por `MeshCollider` não precisa necessariamente corresponder à usada por `MeshRenderer`. Você também pode adicionar um `MeshCollider` a uma Entity que tem um modelo 3D de um `GLTFContainer` component, ou a uma Entity que não tem nenhuma forma visível. {% hint style="warning" %} **📔 Nota**: O `MeshCollider` component e `ColliderLayer` devem ser importados via `import { MeshCollider, ColliderLayer } from "@dcl/sdk/ecs"` Veja [Imports](/creator/content-creator-pt/scenes-sdk7/comecar/coding-scenes.md#imports) para ver como lidar facilmente com isso. {% endhint %} ## Colliders em modelos 3D Modelos 3D podem receber colliders em dois níveis diferentes de geometria: * `visibleMeshesCollisionMask`: Refere-se à geometria visível do modelo. Por padrão, essa geometria não tem colliders. * `invisibleMeshesCollisionMask`: refere-se às meshes de collider, cujo nome termina em `_collider`. Por padrão, essa geometria é tratada como um collider tanto para physics quanto para pointer events. Qualquer mesh embutida como parte de um modelo 3D cujo nome termina em `_collider` é tratada como parte da `invisibleMeshesCollisionMask` layer, e interpretada como um collider por padrão. Definir a geometria do collider como uma layer invisível separada permite muito mais controle e é bem menos exigente para o sistema do que usar a geometria visível, já que o objeto de collision geralmente é muito mais simples (com menos vertices) do que o modelo original. Se um modelo não tiver nenhuma geometria de collider e você quiser fazer com que ele afete os systems de physics ou pointer events, você pode: * Atribuir layers de collision diretamente à geometria visível, por meio do `visibleMeshesCollisionMask`. {% hint style="warning" %} **📔 Nota**: Se a geometria visível do objeto tiver muitos vertices, observe que isso pode ter um custo maior de performance. {% endhint %} * Dar à Entity um `MeshCollider` component, para lhe dar um collider de forma primitiva. * Sobrepor uma Entity invisível que tenha um `MeshCollider` component. * Edite o modelo em uma ferramenta externa como Blender para incluir um *mesh de collider*. O collider deve ser nomeado *x\_collider*, onde *x* é o nome do modelo. Então, para um modelo chamado *house*, o collider deve ser nomeado *house\_collider*. Você também pode querer atribuir a layer de collision de pointer events à `visibleMeshesCollisionMask` caso queira que as hover hints e pointer events respondam com mais precisão ao contorno da Entity. Observe que isso exige mais performance. {% hint style="warning" %} **📔 Nota**: Certifique-se de não ter a mesma layer (physics, pointer events ou custom layers) atribuída a ambos `visibleMeshesCollisionMask` e `invisibleMeshesCollisionMask`, pois isso seria um uso muito ineficiente de recursos. Você pode ter layers diferentes em cada um, como physics na layer invisível e pointer events na layer visível. {% endhint %} ```ts // criar Entity const myEntity = engine.addEntity() // atribuir forma GLTF GltfContainer.create(myEntity, { src: '/models/myModel.gltf', invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS, visibleMeshesCollisionMask: ColliderLayer.CL_POINTER, }) ``` Veja [modelos 3D](https://github.com/decentraland/docs-creator/blob/main/creator/3d-modeling/3d-models/README.md) para mais detalhes sobre como adicionar geometria invisível de collider a um modelo 3D. {% hint style="warning" %} **📔 Nota**: O `GltfContainer` component e `ColliderLayer` devem ser importados via > `import { GltfContainer, ColliderLayer } from "@dcl/sdk/ecs"` Veja [Imports](/creator/content-creator-pt/scenes-sdk7/comecar/coding-scenes.md#imports) para ver como lidar facilmente com isso. {% endhint %} ### Modelos animados Ao configurar colliders para usar a geometria visível em um modelo que inclui [animações baseadas em Armature](/creator/content-creator-pt/modelacao-e-animacoes-3d/animations.md), as animações não são seguidas pelos colliders. As collider meshes mantêm sua forma original. Se uma animação envolver deformar a geometria de uma mesh, as collider meshes retêm a forma não animada enquanto a animação é reproduzida. Ao reproduzir animações que envolvem mover meshes inteiras sem alterar sua forma, essas mudanças são refletidas com precisão pelos colliders. Por exemplo, se uma plataforma se move como parte de uma animação, o collider da plataforma também se move com a animação. ## layers de collision A scene pode lidar com layers de collision separadas, que têm comportamentos diferentes. Você pode configurar um `MeshCollider` component ou o `GltfContainer` component para responder apenas a um tipo de interaction, ou a vários deles, ou a nenhum. Para isso, no `MeshCollider` defina o `collisionMask` property, e em `GltfContainer` defina o `visibleMeshesCollisionMask` ou `invisibleMeshesCollisionMask` properties, para um ou vários dos seguintes valores: * `ColliderLayer.CL_PHYSICS`: Bloqueia o movimento do player (paredes, pisos, plataformas da scene). Não afeta pointer events. * `ColliderLayer.CL_POINTER`: Responde apenas a pointer events. Não bloqueia o movimento do player. * `ColliderLayer.CL_PLAYER`: Marca o collider como um marcador de avatar. Raycasts e Trigger Areas que apontam para `CL_PLAYER` o detectarão, mas a capsule do player passa direto por ele (sem bloqueio físico). Em scene meshes, isso é útil para marcar uma mesh como "um alvo semelhante a avatar" apenas para detecção. * `ColliderLayer.CL_MAIN_PLAYER`: Assim como `CL_PLAYER`, mas direcionado apenas ao player local. Raycasts e trigger areas com `CL_MAIN_PLAYER` em sua mask o detectam; raycasts/triggers de avatars remotos não. * `ColliderLayer.CL_CUSTOM1` até `CL_CUSTOM8`: Pode ser usado junto com raycasts e trigger areas para detectar collisions apenas com layers personalizadas específicas. * `ColliderLayer.CL_NONE`: Não responde a collisions de nenhum tipo. {% hint style="info" %} **💡 Dica**: `CL_PLAYER` e `CL_MAIN_PLAYER` em um `MeshCollider` / `GltfContainer` são **apenas de detecção** layers — a capsule do player passa por elas. Se você quiser que a mesh seja TANTO detectável como um avatar QUANTO bloqueie fisicamente o player, combine a layer de avatar com `CL_PHYSICS` (por exemplo `CL_PHYSICS | CL_MAIN_PLAYER`). {% endhint %} {% hint style="warning" %} **📔 Nota**: Para desativar collisions de um `MeshCollider` component, remova o component. Não defina a collision layer como `ColliderLayer.CL_NONE`. Há um problema conhecido com o `MeshCollider` component. Em vez de desativar todas as collisions, ele torna esse valor equivalente ao padrão (`ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER`). {% endhint %} ```ts // criar Entity const myEntity = engine.addEntity() // forma visível MeshRenderer.setBox(myEntity) // criar um component MeshCollider que responde apenas à physics do player MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS) ``` Uma única collision mask pode responder a várias collision layers. Use o `|` character como um *ou*, para incluir quantas layers você precisar. O valor padrão em um MeshCollider é `ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER`. ```ts MeshCollider.setBox( myEntity, ColliderLayer.CL_CUSTOM1 | ColliderLayer.CL_CUSTOM3 | ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER ) ``` Você pode usar as 8 layers personalizadas diferentes para o que melhor se adequar à sua scene; por exemplo, uma pode ser usada para cálculos de line-of-sight de NPC, enquanto outra para estimar trajetórias de falling objects. Usar layers diferentes para sistemas diferentes permite usar menos recursos, pois em cada caso você só estará verificando collisions com as Entities relevantes. Veja [Raycasting](/creator/content-creator-pt/scenes-sdk7/interatividade/raycasting.md) para mais detalhes sobre como usar layers de collision personalizadas. ### Câmeras e colliders Quando a câmera de um player se move no modo de terceira pessoa, a câmera pode ou não ser bloqueada por colliders, dependendo das collision layers atribuídas às Entities. Tenha isso em mente ao projetar sua scene; talvez você queira impedir que a câmera atravesse walls ou outras Entities. Para evitar que a câmera atravesse walls, você deve atribuir tanto o `ColliderLayer.CL_PHYSICS` e o `ColliderLayer.CL_POINTER` layers às Entities que você quer que bloqueiem a câmera. É importante que ambas as layers sejam atribuídas à mesma geometria na Entity. Então, se você atribuir a `ColliderLayer.CL_PHYSICS` layer à layer visível da Entity, você também deve atribuir a `ColliderLayer.CL_POINTER` layer à mesma geometria. Por exemplo, no Creator Hub, a seguinte combinação de settings impedirá que a câmera atravesse walls: ![](/files/84402d7a6e5fababb082f27e946c9b01bed14fdd) Tanto as `ColliderLayer.CL_PHYSICS` e o `ColliderLayer.CL_POINTER` layers são atribuídas à mesma layer invisível da geometria da Entity. Se ambas fossem atribuídas à layer visível, o resultado seria o mesmo. Esse é o comportamento padrão, tanto ao adicionar uma Entity via Creator Hub quanto via code. ![](/files/f6463a691082c11a4dea718e140b8e3dce45d6fd) Neste segundo exemplo, a câmera pode atravessar a wall, porque a `ColliderLayer.CL_PHYSICS` layer é atribuída à layer invisível da Entity, e a `ColliderLayer.CL_POINTER` layer é atribuída à layer visível da Entity, mesmo que ambas as geometrias tenham a mesma forma geral. ```ts // NENHUMA CÂMERA ATRAVESSA A PAREDE // padrão (tanto pointer quanto physics usam a geometria invisível) GLTFContainer.create(myEntity, { src: '/models/myModel.gltf', }) // NENHUMA CÂMERA ATRAVESSA A PAREDE // Ambas usam a mesma geometria invisível GltfContainer.create(myEntity2, { src: '/models/myModel.gltf', invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER, }) // NENHUMA CÂMERA ATRAVESSA A PAREDE // Ambas usam a mesma geometria visível GltfContainer.create(myEntity2, { src: '/models/myModel.gltf', visibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER, }) // SIM, A CÂMERA ATRAVESSA A PAREDE // physics e pointer estão em layers diferentes GltfContainer.create(myEntity2, { src: '/models/myModel.gltf', invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS, visibleMeshesCollisionMask: ColliderLayer.CL_POINTER, }) // SIM, A CÂMERA ATRAVESSA A PAREDE // physics e pointer estão em layers diferentes GltfContainer.create(myEntity2, { src: '/models/myModel.gltf', invisibleMeshesCollisionMask: ColliderLayer.CL_POINTER, visibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS, }) ``` ### Bloqueio de pointer Apenas formas que têm colliders podem ser ativadas com [pointer events](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md). Uma Entity também precisa ter um collider para bloquear pointer events de atravessá-la e impedir atingir Entities atrás dela. Então, por exemplo, um player não pode pegar algo que está trancado dentro de um baú, se o baú tiver colliders ao redor. Os pointer events do player são afetados apenas por meshes que estão ativas na `ColliderLayer.CL_POINTER` layer. Por padrão, um MeshCollider afeta tanto as layers Physics quanto Pointer, mas você pode alterar esse valor para afetar apenas uma, ou nenhuma, e afetar layers personalizadas em vez disso. {% hint style="warning" %} **📔 Nota**: Além de colliders, uma Entity também precisa ter um `PointerEvents` component para responder a pointer events. Os `pointerEventsSystem` helpers também cuidam desse requisito. {% endhint %} ```ts // responde apenas à physics do player // por exemplo, para uma parede invisível pela qual você não pode andar, mas pode clicar através MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS) // responde apenas ao pointer do player // por exemplo, para um item que você pode clicar para pegar, mas pode atravessar sem dificuldade MeshCollider.setBox(myEntity2, ColliderLayer.CL_POINTER) ``` Por padrão, a geometria visível de um `GLTFContainer` não é mapeada para nenhuma collision layer, mas a geometria invisível afeta tanto as layers Physics quanto Pointer. Você pode alterar esse valor para afetar apenas uma, ou nenhuma, e afetar layers personalizadas em vez disso. Você também pode configurar a layer da geometria visível da mesma maneira. ```ts // padrão (tanto pointer quanto physics usam a geometria invisível) GLTFContainer.create(myEntity, { src: '/models/myModel.gltf', }) // physics do player usa a geometria invisível mais simples // pointer events usam o contorno completo e detalhado da geometria visível GltfContainer.create(myEntity2, { src: '/models/myModel.gltf', invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS, visibleMeshesCollisionMask: ColliderLayer.CL_POINTER, }) // tanto a physics do player quanto pointer events usam o contorno completo e detalhado da geometria visível // a geometria invisível mais simples é mapeada para ColliderLayer.CL_NONE para evitar calcular ambos GltfContainer.create(myEntity, { src: '/models/myModel.gltf', invisibleMeshesCollisionMask: ColliderLayer.CL_NONE, visibleMeshesCollisionMask: ColliderLayer.CL_POINTER | ColliderLayer.CL_PHYSICS, }) // não responda a collisions de nenhum tipo, nem com a geometria visível nem com a invisível: GltfContainer.create(myEntity, { src: '/models/myModel.gltf', invisibleMeshesCollisionMask: ColliderLayer.CL_NONE, }) ``` ## Sintaxe avançada do MeshCollider A sintaxe completa para criar um `MeshCollider` component, sem nenhum helper para simplificá-la, é assim: ```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: {}, }, }) ``` É assim que o protocolo base interpreta os components MeshCollider. As funções helper abstraem isso e expõem uma sintaxe mais amigável, mas nos bastidores elas geram essa sintaxe. O `$case` campo permite especificar um dos tipos permitidos. Cada tipo suporta um conjunto diferente de parâmetros. Os valores suportados para `$case` são os seguintes: * `box` * `plane` * `sphere` * `cylinder` Dependendo do valor de `$case`, é válido definir o objeto para a forma correspondente, passando quaisquer propriedades relevantes. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/colliders.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.