> 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/fundamentos-de-conteudo-3d/colliders.md). # Colliders Saiba mais sobre os diferentes components que dão às entities sua forma 3D e colisão. Entidades que têm colliders ocupam espaço e bloqueiam o caminho de um avatar do jogador, enquanto entidades sem colliders podem ser atravessadas pelo avatar do jogador. Colliders também são necessários para tornar uma entidade clicável. Os eventos de botão baseiam-se na forma do collider de uma entidade, e não na sua forma visível. Existem camadas de colisão separadas para interagir com a física do jogador ou com pointer events; os colliders podem ser configurados para interagir apenas com uma ou com a outra. Também podem ser configurados para interagir com camadas personalizadas, que podem ser usadas com [raycasts](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md) para tratar do que fizer mais sentido para a Scene. {% hint style="warning" %} **📔 Nota**: Colliders não afetam a forma como outras entidades interagem entre si; as entidades podem sempre sobrepor-se. As definições de colisão só afetam a forma como a entidade interage com o avatar do jogador e com os eventos de botão. O Decentraland não tem um motor de física nativo, por isso, se quiser que as entidades caiam, colidam ou saltem, tem de codificar esse comportamento na Scene ou importar uma library para tratar disso. {% endhint %} ## Use o Scene Editor A forma mais fácil de gerir os colliders de uma entidade é usar o [Scene Editor](/creator/content-creator-pt/scene-editor/primeiros-passos/about-editor.md). Pode adicionar um **MeshCollider** component à sua entidade para atribuir uma forma primitiva (cubo, plano, esfera, cilindro ou cone) à sua entidade. Depois, pode escolher [camadas de colisão](#collision-layers) num dropdown. Também pode configurar as camadas de colisão num **GLTF** para alterar o valor predefinido [camadas de colisão](#collision-layers) usado quer na geometria do collider quer na geometria visível do modelo. Veja [Add Components](/creator/content-creator-pt/scene-editor/construir/components.md#add-components). ![](https://2402076176-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 em formas primitivas O `MeshCollider` component atribui a uma entidade um collider simples baseado numa forma primitiva (caixas, esferas, planos, cilindros ou cones). Entidades que têm um `MeshRenderer` component para lhes dar uma [forma primitiva](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/shape-components.md#primitive-shapes) não têm colliders por defeito. Também tem de atribuir à entidade um `MeshCollider` component. As seguintes formas de collider estão disponíveis em `MeshCollider`. Várias formas incluem campos adicionais opcionais, específicos dessa forma. * **box**: Use `MeshCollider.setBox()`, passando a entidade. * **plane**: Use `MeshCollider.setPlane()`, passando a entidade. * **sphere**: Use `MeshCollider.setSphere()`, passando a entidade. * **cylinder**: Use `MeshCollider.setCylinder()`, passando a entidade. Passe `radiusTop` e `radiusBottom` como campos opcionais adicionais, para modificar o cilindro. {% hint style="info" %} **💡 Dica**: Defina qualquer um deles `radiusTop` ou `radiusBottom` para 0 para criar um cone. {% endhint %} Este exemplo define uma entidade em forma de box que não pode ser atravessada. ```ts // criar entidade const myCollider = engine.addEntity() // forma visível MeshRenderer.setBox(myCollider) // collider MeshCollider.setBox(myCollider) ``` A forma usada pelo `MeshCollider` não precisa necessariamente corresponder à usada pelo `MeshRenderer`. Também pode adicionar um `MeshCollider` a uma entidade que tenha um modelo 3D de um `GltfContainer` component, ou a uma entidade que não tenha qualquer forma visível. {% hint style="warning" %} **📔 Nota**: O `MeshCollider` component e `ColliderLayer` devem ser importados via `import { MeshCollider, ColliderLayer } from "@dcl/sdk/ecs"` Veja [Importações](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar facilmente com estes. {% endhint %} ## Colliders em modelos 3D Aos modelos 3D podem ser atribuídos colliders em dois níveis de geometria diferentes: * `visibleMeshesCollisionMask`: Refere-se à geometria visível do modelo. Por defeito, esta geometria não tem colliders. * `invisibleMeshesCollisionMask`: refere-se às collider meshes, cujos nomes terminam em `_collider`. Por defeito, esta geometria é tratada como um collider tanto para física como para pointer events. Qualquer mesh incorporada como parte de um modelo 3D cujo nome termina em `_collider` é tratada como parte da `invisibleMeshesCollisionMask` layer, e interpretada como um collider por defeito. Definir a geometria do collider como uma layer invisível separada permite muito mais controlo e exige muito menos do sistema do que usar a geometria visível, uma vez que o objeto de colisão é normalmente muito mais simples (com menos vertices) do que o modelo original. Se um modelo não tiver qualquer geometria de collider e quiser fazer com que afete os systems de physics ou pointer events, pode: * Atribuir camadas de colisão diretamente à geometria visível, através do `visibleMeshesCollisionMask`. {% hint style="warning" %} **📔 Nota**: Se a geometria visível do objeto tiver muitos vertices, note que isto pode ter um custo de desempenho maior. {% endhint %} * Atribua à entidade um `MeshCollider` component, para lhe dar um collider com forma primitiva. * Sobreponha uma entidade invisível que tenha um `MeshCollider` component. * Edite o modelo numa ferramenta externa como o Blender para incluir um *collider mesh*. O collider deve ser nomeado *x\_collider*, onde *x* é o nome do modelo. Assim, para um modelo chamado *house*, o collider deve ser nomeado *house\_collider*. Também pode querer atribuir a camada de colisão de pointer events à `visibleMeshesCollisionMask` caso queira que as hover hints e os pointer events respondam com mais precisão ao contorno da entidade. Note que isto exige mais desempenho. {% hint style="warning" %} **📔 Nota**: Certifique-se de que não tem a mesma camada (physics, pointer events ou camadas personalizadas) atribuída a ambos `visibleMeshesCollisionMask` e `invisibleMeshesCollisionMask`, pois isso seria uma utilização de recursos muito ineficiente. Pode ter camadas diferentes em cada um, como physics na camada invisível e pointer events na camada visível. {% endhint %} ```ts // criar entidade 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/blob/main/creator/3d-modeling/3d-models.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 [Importações](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar facilmente com estes. {% endhint %} ### Modelos animados Ao definir colliders para usar a geometria visível num modelo que inclui [animações baseadas em armature](/creator/content-creator-pt/modelacao-3d-e-animacoes/animations.md), as animações não são seguidas pelos colliders. As collider meshes mantêm a sua forma original. Se uma animação envolver a deformação da geometria de uma mesh, as collider meshes mantêm a forma sem animação enquanto a animação é reproduzida. Ao reproduzir animações que envolvem mover meshes inteiras sem alterar a sua forma, essas alterações são refletidas com precisão pelos colliders. Por exemplo, se uma plataforma se mover como parte de uma animação, o collider da plataforma move-se com a animação. ## camadas de colisão A Scene pode lidar com camadas de colisão separadas, que têm comportamentos diferentes. Pode configurar um `MeshCollider` component ou o `GltfContainer` component para responder apenas a um tipo de interação, ou a vários, ou a nenhum. Para fazer isso, no `MeshCollider` defina o `collisionMask` na propriedade, e em `GltfContainer` defina o `visibleMeshesCollisionMask` ou `invisibleMeshesCollisionMask` as propriedades para um ou vários dos seguintes valores: * `ColliderLayer.CL_PHYSICS`: Bloqueia o movimento do jogador (paredes, pisos, plataformas da Scene). Não afeta pointer events. * `ColliderLayer.CL_POINTER`: Responde apenas a pointer events. Não bloqueia o movimento do jogador. * `ColliderLayer.CL_PLAYER`: Marca o collider como um marcador de avatar. Raycasts e trigger areas que visem `CL_PLAYER` irão detetá-lo, mas a capsule do jogador atravessa-o diretamente (sem bloqueio físico). Em scene meshes, isto é útil para marcar uma mesh como "um alvo semelhante a um avatar" apenas para deteção. * `ColliderLayer.CL_MAIN_PLAYER`: Tal como `CL_PLAYER`, mas direcionado apenas ao jogador local. Raycasts e trigger areas com `CL_MAIN_PLAYER` na sua mask detetam-no; raycasts/triggers de avatares remotos não. * `ColliderLayer.CL_CUSTOM1` até `CL_CUSTOM8`: Pode ser usado em conjunto com raycasts e trigger areas para detetar colisões apenas com camadas personalizadas específicas. * `ColliderLayer.CL_NONE`: Não responde a colisões de qualquer tipo. {% hint style="info" %} **💡 Dica**: `CL_PLAYER` e `CL_MAIN_PLAYER` num `MeshCollider` / `GltfContainer` são **apenas de deteção** layers — a capsule do jogador atravessa-as. Se quiser que a mesh seja TANTO detetável como avatar COMO também bloqueie fisicamente o jogador, combine a layer de avatar com `CL_PHYSICS` (por exemplo, `CL_PHYSICS | CL_MAIN_PLAYER`). {% endhint %} {% hint style="warning" %} **📔 Nota**: Para desativar colisões de um `MeshCollider` component, elimine o component. Não defina a camada de colisão para `ColliderLayer.CL_NONE`. Há um problema conhecido com o `MeshCollider` component. Em vez de desativar todas as colisões, faz com que este valor seja equivalente ao predefinido (`ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER`). {% endhint %} ```ts // criar entidade const myEntity = engine.addEntity() // forma visível MeshRenderer.setBox(myEntity) // criar um component MeshCollider que responde apenas à física do jogador MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS) ``` Uma única collision mask pode responder a várias camadas de colisão. Use o `|` carácter como um *ou*, para incluir tantas camadas quantas precisar. O valor predefinido de um MeshCollider é `ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER`. ```ts MeshCollider.setBox( myEntity, ColliderLayer.CL_CUSTOM1 | ColliderLayer.CL_CUSTOM3 | ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER ) ``` Pode usar as 8 camadas personalizadas diferentes para o que melhor se adequar à sua Scene; por exemplo, uma pode ser usada para cálculos de linha de visão de NPC, enquanto outra para estimar trajetórias de objetos em queda. Usar layers diferentes para systems diferentes permite usar menos recursos, já que em cada caso só estará a verificar colisões com as entidades relevantes. Veja [Raycasting](/creator/content-creator-pt/scenes-sdk7/interatividade/raycasting.md) para mais detalhes sobre como usar camadas de colisão personalizadas. ### Câmaras e colliders Quando a câmara de um jogador se move em modo de terceira pessoa, a câmara pode ou não ser bloqueada por colliders, dependendo das camadas de colisão atribuídas às entidades. Tenha isto em conta ao desenhar a sua Scene; poderá querer impedir que a câmara atravesse paredes ou outras entidades. Para evitar que a câmara atravesse paredes, tem de atribuir tanto a `ColliderLayer.CL_PHYSICS` como a `ColliderLayer.CL_POINTER` camadas às entidades que pretende que bloqueiem a câmara. É importante que ambas as layers sejam atribuídas à mesma geometria da entidade. Assim, se atribuir a `ColliderLayer.CL_PHYSICS` layer à layer visível da entidade, também tem de atribuir a `ColliderLayer.CL_POINTER` layer à mesma geometria. Por exemplo, no Creator Hub, a seguinte combinação de definições impedirá que a câmara atravesse paredes: ![](https://2402076176-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) Tanto a `ColliderLayer.CL_PHYSICS` como a `ColliderLayer.CL_POINTER` layers são atribuídas à mesma layer invisível da geometria da entidade. Se ambas fossem atribuídas à layer visível, o resultado seria o mesmo. Este é o comportamento predefinido, tanto ao adicionar uma entidade via Creator Hub como via código. ![](https://2402076176-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) Neste segundo exemplo, a câmara pode atravessar a parede, porque a `ColliderLayer.CL_PHYSICS` layer é atribuída à layer invisível da entidade, e a `ColliderLayer.CL_POINTER` layer é atribuída à layer visível da entidade, mesmo que ambas as geometrias tenham a mesma forma geral. ```ts // SEM A CÂMARA A ATRAVESSAR A PAREDE // predefinido (tanto pointer quanto physics usam a geometria invisível) GltfContainer.create(myEntity, { src: '/models/myModel.gltf', }) // SEM A CÂMARA A ATRAVESSAR A PAREDE // Ambos usam a mesma geometria invisível GltfContainer.create(myEntity2, { src: '/models/myModel.gltf', invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER, }) // SEM A CÂMARA A ATRAVESSAR A PAREDE // Ambos usam a mesma geometria visível GltfContainer.create(myEntity2, { src: '/models/myModel.gltf', visibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER, }) // SIM, A CÂMARA 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ÂMARA 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 as 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 entidade também precisa de ter um collider para bloquear os pointer events e impedir que atinjam entidades atrás dela. Por exemplo, um jogador não pode apanhar algo que esteja trancado dentro de um baú, se o baú tiver colliders à sua volta. Os pointer events do jogador só são afetados por meshes que estejam ativas na `ColliderLayer.CL_POINTER` layer. Por defeito, um MeshCollider afeta tanto as layers Physics como Pointer, mas pode alterar este valor para afetar apenas uma, ou nenhuma, e em alternativa afetar camadas personalizadas. {% hint style="warning" %} **📔 Nota**: Além de colliders, uma entidade também precisa de ter um `PointerEvents` component para responder a pointer events. Os `pointerEventsSystem` helpers também tratam deste requisito. {% endhint %} ```ts // responde apenas à física do jogador // por exemplo, para uma parede invisível que não pode ser atravessada, mas através da qual pode clicar MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS) // responde apenas ao pointer do jogador // por exemplo, para um item que pode clicar para apanhar, mas através do qual pode passar MeshCollider.setBox(myEntity2, ColliderLayer.CL_POINTER) ``` Por defeito, a geometria visível de um `GltfContainer` não é mapeada para nenhuma layer de colisão, mas a geometria invisível afeta tanto as layers Physics como Pointer. Pode alterar este valor para afetar apenas uma, ou nenhuma, e em alternativa afetar camadas personalizadas. Também pode configurar a layer da geometria visível da mesma forma. ```ts // predefinido (tanto pointer quanto physics usam a geometria invisível) GltfContainer.create(myEntity, { src: '/models/myModel.gltf', }) // a física do jogador usa a geometria invisível mais simples // os 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 física do jogador como os 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 responde a colisões de qualquer 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 de MeshCollider A sintaxe completa para criar um `MeshCollider` component, sem quaisquer helpers para a simplificar, é 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 helper functions abstraem isto e expõem uma sintaxe mais amigável, mas nos bastidores produzem esta sintaxe. O `$case` field permite especificar um dos tipos permitidos. Cada type 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 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-pt/scenes-sdk7/fundamentos-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 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.