> 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.

As entidades que têm colliders ocupam espaço e bloqueiam o caminho do jogador; as entidades sem colliders podem ser atravessadas pelo avatar do jogador.

Os 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, não na sua forma visível.

Existem camadas de colisão distintas para interagir com a física do jogador ou com eventos de ponteiro. 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 utilizadas com [raycasts](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md) para gerir o que fizer sentido na cena.

{% hint style="warning" %}
**📔 Nota**: Os colliders não afetam a forma como as entidades interagem entre si; as entidades podem sempre sobrepor-se. As definições de colisão afetam apenas a interação da entidade com o avatar do jogador e com os eventos de botão. Decentraland não tem um motor de física nativo. Por isso, se quiser que as entidades caiam, colidam ou ressaltem, tem de programar esse comportamento na cena ou importar uma biblioteca para o gerir.
{% endhint %}

## Utilizar o Scene Editor

A forma mais fácil de gerir os colliders de uma entidade é utilizar o [Scene Editor](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/primeiros-passos/about-editor.md).

Pode adicionar um componente **Mesh Collider** à sua entidade para lhe atribuir uma forma primitiva (cubo, plano, esfera, cilindro ou cone). Depois, pode escolher as [camadas de colisão](#collision-layers) num menu pendente.

Também pode configurar as camadas de colisão num componente **GLTF** para alterar as [camadas de colisão](#collision-layers) predefinidas utilizadas na geometria do collider ou na geometria visível do modelo. Consulte [Adicionar componentes](https://docs.decentraland.org/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-cd083f0f07f0a22b49439dfd684be0b23e825cc5%2Fgltf-component.webp?alt=media)

## Colliders em formas primitivas

O componente `MeshCollider` atribui a uma entidade um collider simples baseado numa forma primitiva (caixas, esferas, planos, cilindros ou cones).

As entidades que têm um componente `MeshRenderer` para lhes atribuir uma [forma primitiva](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/shape-components.md#primitive-shapes) não têm colliders por predefinição. Também tem de adicionar à entidade um componente `MeshCollider` .

As seguintes formas de collider estão disponíveis em `MeshCollider`. Algumas formas incluem campos adicionais opcionais específicos de cada forma.

* **caixa**:

  Utilize `MeshCollider.setBox()`, passando a entidade.
* **plano**:

  Utilize `MeshCollider.setPlane()`, passando a entidade.
* **esfera**:

  Utilize `MeshCollider.setSphere()`, passando a entidade.
* **cilindro**:

  Utilize `MeshCollider.setCylinder()`, passando a entidade. Passe `radiusTop` e `radiusBottom` como campos adicionais opcionais para modificar o cilindro.

{% hint style="info" %}
**💡 Dica**: Defina `radiusTop` ou `radiusBottom` como 0 para criar um cone.
{% endhint %}

Este exemplo define uma entidade em forma de caixa pela qual não é possível passar.

```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 componente `GltfContainer` ou a uma entidade que não tenha nenhuma forma visível.

{% hint style="warning" %}
**📔 Nota**: O componente `MeshCollider` e `ColliderLayer` devem ser importados por meio de

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

Consulte [Imports](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com eles facilmente.
{% endhint %}

## Colliders em modelos 3D

É possível atribuir colliders a modelos 3D em dois níveis diferentes da geometria:

* `visibleMeshesCollisionMask`: refere-se à geometria visível do modelo. Por padrão, essa geometria não tem colliders.
* `invisibleMeshesCollisionMask`: refere-se às malhas de collider, cujos nomes terminam em `_collider`. Por padrão, essa geometria é tratada como collider tanto para a física quanto para eventos de ponteiro.

Qualquer malha incorporada como parte de um modelo 3D cujo nome termine em `_collider` é tratada como parte da camada `invisibleMeshesCollisionMask` e interpretada como collider por padrão.

Definir a geometria do collider como uma camada invisível separada proporciona muito mais controle e exige bem menos do sistema do que usar a geometria visível, pois o objeto de colisão costuma ser bem mais simples (com menos vértices) do que o modelo original.

Se um modelo não tiver qualquer geometria de collider e quiser que afete os sistemas de física ou de eventos do ponteiro, pode optar por:

* Atribuir camadas de colisão diretamente à geometria visível, através de `visibleMeshesCollisionMask`.

{% hint style="warning" %}
**📔 Nota**: se a geometria visível do objeto tiver muitos vértices, tenha em conta que isso pode ter um custo de desempenho mais elevado.
{% endhint %}

* Adicionar à entidade um componente `MeshCollider` , para lhe atribuir um collider com forma primitiva.
* Sobrepor uma entidade invisível que tenha um componente `MeshCollider` .
* Editar o modelo numa ferramenta externa, como o Blender, para incluir uma *mesh de collider*. O collider tem de se chamar *x\_collider*, sendo que *x* é o nome do modelo. Assim, para um modelo chamado *house*, o collider tem de se chamar *house\_collider*.

Também pode atribuir a camada de colisão dos eventos do ponteiro a `visibleMeshesCollisionMask` se quiser que as sugestões ao passar o cursor e os eventos do ponteiro respondam com maior precisão ao contorno da entidade. Tenha em conta que isso exige mais desempenho.

{% hint style="warning" %}
**📔 Nota**: certifique-se de que não atribui a mesma camada (física, eventos do ponteiro ou camadas personalizadas) a `visibleMeshesCollisionMask` e a `invisibleMeshesCollisionMask`, pois isso seria uma utilização muito ineficiente dos recursos. Pode atribuir camadas diferentes a cada uma, como física à camada invisível e eventos do ponteiro à camada visível.
{% endhint %}

```ts
// criar entidade
const myEntity = engine.addEntity()

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

Consulte [modelos 3D](https://github.com/decentraland/docs/blob/main/creator/3d-modeling/3d-models.md) para obter mais detalhes sobre como adicionar geometria invisível de collider a um modelo 3D.

{% hint style="warning" %}
**📔 Nota**: o componente `GltfContainer` e `ColliderLayer` têm de ser importados através de

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

Consulte [Imports](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com eles facilmente.
{% endhint %}

### Modelos animados

Ao configurar colliders para usarem a geometria visível de um modelo que inclui [animações baseadas em armature](https://docs.decentraland.org/creator/content-creator-pt/modelacao-3d-e-animacoes/animations.md), os colliders não acompanham as animações. As meshes dos colliders mantêm a forma original. Se uma animação deformar a geometria de uma mesh, as meshes dos colliders mantêm a forma não animada enquanto a animação é reproduzida.

Ao reproduzir animações que envolvem mover meshes inteiras sem alterar a sua forma, estas alterações são refletidas corretamente pelos Colliders. Por exemplo, se uma plataforma se mover como parte de uma animação, o Collider da plataforma também se move com a animação.

## Camadas de colisão

A Scene pode suportar camadas de colisão separadas, com comportamentos diferentes.

Pode configurar um `MeshCollider` componente ou o componente `GltfContainer` para responder apenas a um tipo de interação, a vários deles ou a nenhum. Para isso, no `MeshCollider` defina a propriedade `collisionMask` e, no `GltfContainer` defina a propriedade `visibleMeshesCollisionMask` ou `invisibleMeshesCollisionMask` defina as propriedades com um ou vários dos seguintes valores:

* `ColliderLayer.CL_PHYSICS`: Bloqueia o movimento do jogador (paredes, pisos e plataformas da Scene). Não afeta os eventos do Pointer.
* `ColliderLayer.CL_POINTER`: Responde apenas a eventos do Pointer. Não bloqueia o movimento do jogador.
* `ColliderLayer.CL_PLAYER`: Identifica o Collider como um marcador de Avatar. Os Raycasts e as áreas Trigger que visam `CL_PLAYER` irão detetá-lo, mas a cápsula do jogador atravessa-o (sem bloqueio físico). Nos meshes da Scene, isto é útil para assinalar um 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. Os Raycasts e as áreas Trigger com `CL_MAIN_PLAYER` na respetiva máscara detetam-no; os Raycasts e as áreas Trigger de Avatares remotos não.
* `ColliderLayer.CL_CUSTOM1` até `CL_CUSTOM8`: Podem ser usados em conjunto com Raycasts e áreas Trigger para detetar colisões apenas com camadas personalizadas específicas.
* `ColliderLayer.CL_NONE`: Não responde a colisões de nenhum tipo.

{% hint style="info" %}
**💡 Sugestão**: `CL_PLAYER` e `CL_MAIN_PLAYER` num `MeshCollider` / `GltfContainer` são camadas de **apenas deteção** — a cápsula do jogador atravessa-as. Se quiser que o mesh seja detetável COMO um Avatar e também bloqueie fisicamente o jogador, combine a camada do Avatar com `CL_PHYSICS` (por exemplo, `CL_PHYSICS | CL_MAIN_PLAYER`).
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: Para desativar as colisões de um `MeshCollider` componente, exclua o componente. Não defina a camada de colisão como `ColliderLayer.CL_NONE`. Há um problema conhecido com o `MeshCollider` componente. Em vez de desativar todas as colisões, ele faz com que esse valor seja equivalente ao padrão (`ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER`).
{% endhint %}

```ts
// criar entidade
const myEntity = engine.addEntity()
// forma visível
MeshRenderer.setBox(myEntity)

// cria um componente MeshCollider que responde apenas à física do jogador
MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS)
```

Uma única máscara de colisão pode responder a várias camadas de colisão. Use o `|` caractere como um *ou*, para incluir quantas camadas forem necessárias. O valor padrão 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
)
```

Você pode usar as 8 camadas personalizadas para o que melhor se adequar à sua cena. Por exemplo, uma pode ser usada para cálculos de linha de visão de NPCs, enquanto outra pode servir para estimar as trajetórias de objetos em queda. Usar camadas diferentes para sistemas distintos permite economizar recursos, pois, em cada caso, você só verificará as colisões com as entidades relevantes.

Consulte [Raycasting](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/raycasting.md) para saber mais sobre como usar camadas de colisão personalizadas.

### Câmeras e Colliders

Quando a câmera de um jogador se move no modo de terceira pessoa, ela pode ou não ser bloqueada por Colliders, dependendo das camadas de colisão atribuídas às entidades. Leve isso em consideração ao projetar sua cena: talvez você queira impedir que a câmera atravesse paredes ou outras entidades.

Para impedir que a câmera atravesse paredes, você deve atribuir as camadas `ColliderLayer.CL_PHYSICS` e `ColliderLayer.CL_POINTER` às entidades que você quer que bloqueiem a câmera. É importante atribuir ambas as camadas à mesma geometria da entidade. Portanto, se você atribuir a camada `ColliderLayer.CL_PHYSICS` à camada visível da entidade, também deverá atribuir a camada `ColliderLayer.CL_POINTER` à mesma geometria.

Por exemplo, no Creator Hub, a seguinte combinação de configurações impedirá que a câmera atravesse paredes:

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

As camadas `ColliderLayer.CL_PHYSICS` e `ColliderLayer.CL_POINTER` estão atribuídas à mesma camada invisível da geometria da entidade. Se ambas fossem atribuídas à camada visível, o resultado seria o mesmo. Esse é o comportamento padrão, tanto ao adicionar uma entidade pelo Creator Hub quanto por código.

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

Neste segundo exemplo, a câmera pode atravessar a parede porque a camada `ColliderLayer.CL_PHYSICS` está atribuída à camada invisível da entidade, enquanto a camada `ColliderLayer.CL_POINTER` está atribuída à camada visível da entidade, mesmo que ambas as geometrias tenham o mesmo formato geral.

```ts
// A CÂMERA NÃO ATRAVESSA A PAREDE
// padrão (pointer e physics usam a geometria invisível)
GltfContainer.create(myEntity, {
	src: '/models/myModel.gltf',
})

// A CÂMERA NÃO ATRAVESSA A PAREDE
// Ambos usam a mesma geometria invisível
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask:
		ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER,
})

// A CÂMERA NÃO ATRAVESSA 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
// a física e o ponteiro estão em camadas diferentes
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
	visibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
})

// SIM, A CÂMARA ATRAVESSA A PAREDE
// a física e o ponteiro estão em camadas diferentes
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
	visibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
})
```

### Bloqueio do ponteiro

Só é possível ativar formas que tenham colliders com [eventos de ponteiro](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md). Uma entidade também precisa de um collider para bloquear os eventos de ponteiro e impedir que atravessem essa entidade e atinjam as entidades atrás dela. Por exemplo, um jogador não consegue apanhar um objeto trancado dentro de um baú se o baú tiver colliders à sua volta. Os eventos de ponteiro do jogador só são afetados pelas meshes ativas na `ColliderLayer.CL_POINTER` camada.

Por predefinição, um MeshCollider afeta as camadas Physics e Pointer, mas pode alterar este valor para afetar apenas uma delas, nenhuma delas ou camadas personalizadas.

{% hint style="warning" %}
**📔 Nota**: Além dos colliders, uma entidade também precisa de ter um componente `PointerEvents` para responder a eventos de ponteiro. Os auxiliares `pointerEventsSystem` também tratam deste requisito.
{% endhint %}

```ts
// só responde à física do jogador
// por exemplo, para uma parede invisível pela qual não se consegue passar, mas através da qual se pode clicar
MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS)

// só responde ao ponteiro do jogador
// por exemplo, para um objeto em que se pode clicar para o apanhar, mas pelo qual se pode passar
MeshCollider.setBox(myEntity2, ColliderLayer.CL_POINTER)
```

Por predefinição, a geometria visível de um `GltfContainer` não é atribuída a nenhuma camada de colisão, mas a geometria invisível afeta as camadas Physics e Pointer. Pode alterar este valor para afetar apenas uma delas, nenhuma delas ou camadas personalizadas. Também pode configurar a camada da geometria visível da mesma forma.

```ts
// padrão (pointer e 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 eventos de ponteiro usam o contorno detalhado completo 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 eventos de ponteiro usam o contorno detalhado completo da geometria visível
// a geometria invisível mais simples é atribuída 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,
})

// não responder 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 componente `MeshCollider` sem quaisquer auxiliares para a simplificar tem este aspeto:

```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 componentes MeshCollider. As funções auxiliares abstraem esse processo e expõem uma sintaxe mais simples, mas, nos bastidores, geram esta 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`

Consoante o valor de `$case`, é válido definir o objeto para a forma correspondente, passando as 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=<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.
