Colliders

Saiba sobre os diferentes componentes que dão às entidades sua forma 3D e colisão.

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

Colliders também são necessários para tornar uma entidade clicável. Eventos de botão são baseados na forma do collider de uma entidade, não na sua forma visível.

Existem camadas de colisão separadas para interagir com a física do jogador ou com eventos de ponteiro; colliders podem ser configurados para interagir apenas com uma ou com a outra. Eles também podem ser configurados para interagir com camadas personalizadas, que podem ser usadas com raycasts para tratar o que fizer sentido para a cena.

📔 Nota: Colliders não afetam como outras entidades interagem entre si; entidades podem sempre se sobrepor. As configurações de colisão afetam apenas como a entidade interage com o avatar do jogador e com eventos de botão. Decentraland não possui um motor de física nativo, portanto se você quiser que entidades caiam, colidam ou ricocheteiem, você deve codificar esse comportamento na cena ou importar uma biblioteca para tratar disso.

Use o Scene Editor

A maneira mais fácil de gerenciar os colliders de uma entidade é usar o Scene Editor.

Você pode adicionar um Mesh Collider componente à sua entidade para atribuir uma forma primitiva (cubo, plano, esfera, cilindro ou cone) à sua entidade. Você pode então escolher Collision layers de um menu suspenso.

Você também pode configurar as camadas de colisão em um GLTF componente para alterar o Collision layers padrão usado tanto na geometria do collider quanto na geometria visível do modelo. Veja Add Components.

Colliders em formas primitivas

O MeshCollider componente dá a uma entidade um collider simples baseado em uma forma primitiva (caixas, esferas, planos, cilindros ou cones).

Entidades que têm um MeshRenderer componente para lhes dar uma forma primitiva não têm colliders por padrão. Você também deve dar à entidade um MeshCollider componente.

As seguintes formas de collider estão disponíveis em MeshCollider. Várias formas incluem campos adicionais opcionais, específicos daquela 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.

💡 Dica: Defina ou radiusTop ou radiusBottom para 0 para fazer um cone.

Este exemplo define uma entidade caixa pela qual não se pode atravessar.

// create entity
const myCollider = engine.addEntity()

// visible shape
MeshRenderer.setBox(myCollider)

// collider
MeshCollider.setBox(myCollider)

A forma usada pelo MeshCollider não precisa necessariamente coincidir com a usada pelo MeshRenderer. Você também pode adicionar um MeshCollider a uma entidade que tenha um modelo 3D de um GLTFContainer componente, ou a uma entidade que não tenha forma visível alguma.

📔 Nota: O MeshCollider componente e ColliderLayer devem ser importados via

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

Veja Imports para como lidar com estes facilmente.

Colliders em modelos 3D

Modelos 3D podem ter colliders atribuídos 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 malhas de collider, cujo nome termina em _collider. Por padrão, essa geometria é tratada como um collider tanto para física quanto para eventos de ponteiro.

Qualquer malha incorporada 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 camada invisível separada permite um controle muito maior e exige muito menos do sistema do que usar a geometria visível, pois o objeto de colisão costuma ser muito mais simples (com menos vértices) do que o modelo original.

Se um modelo não tiver geometria de collider e você quiser que ele afete os sistemas de física ou de eventos de ponteiro, você pode ou:

• Atribuir camadas de colisão diretamente à geometria visível, via o visibleMeshesCollisionMask.

📔 Nota: Se a geometria visível do objeto tiver muitos vértices, note que isso pode ter um custo maior de desempenho.

• Dar à entidade um MeshCollider componente, para lhe dar um collider de forma primitiva.

• Sobrepor uma entidade invisível que tenha um MeshCollider componente.

• Editar o modelo em uma ferramenta externa como Blender para incluir uma 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.

Você também pode querer atribuir a camada de colisão de eventos de ponteiro ao visibleMeshesCollisionMask caso queira que as dicas de hover e os eventos de ponteiro respondam com mais precisão ao contorno da entidade. Note que isto exige mais desempenho.

📔 Nota: Certifique-se de não ter a mesma camada (física, eventos de ponteiro ou camadas personalizadas) atribuída a ambos visibleMeshesCollisionMask e invisibleMeshesCollisionMask, pois isso seria um uso muito ineficiente de recursos. Você pode ter camadas diferentes em cada um, como física na camada invisível e eventos de ponteiro na camada visível.

// create entity
const myEntity = engine.addEntity()

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

Veja 3D models para mais detalhes sobre como adicionar geometria invisível de collider a um modelo 3D.

📔 Nota: O GltfContainer componente e ColliderLayer devem ser importados via

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

Veja Imports para como lidar com estes facilmente.

Modelos animados

Ao definir colliders para usar a geometria visível em um modelo que inclui armature-based animations, as animações não são seguidas pelos colliders. As malhas de collider mantêm sua forma original. Se uma animação envolver deformar a geometria de uma malha, as malhas de collider mantêm a forma não animada enquanto a animação é reproduzida.

Ao reproduzir animações que envolvem mover malhas 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 se move com a animação.

Collision layers

A cena pode tratar camadas de colisão separadas, que têm comportamentos diferentes.

Você pode configurar um MeshCollider componente ou o GltfContainer componente para responder apenas a um tipo de interação, ou a vários deles, ou a nenhum. Para fazer isso, no MeshCollider defina a propriedade collisionMask e nas propriedades do GltfContainer defina a propriedade visibleMeshesCollisionMask ou invisibleMeshesCollisionMask defina uma ou várias dos seguintes valores:

• ColliderLayer.CL_PHYSICS: Bloqueia apenas o movimento do jogador (e não afeta eventos de ponteiro)

• ColliderLayer.CL_POINTER: Responde apenas a eventos de ponteiro (e não bloqueia o movimento do jogador)

• ColliderLayer.CL_CUSTOM1 até CL_CUSTOM8: Pode ser usado junto com raycasts, de forma que um raio só detecte colisões com uma camada específica.

• ColliderLayer.CL_NONE: Não responde a colisões de nenhum tipo.

📔 Nota: Para desativar colisões de um MeshCollider componente, delete o componente. Não defina a camada de colisão para ColliderLayer.CL_NONE. Há um problema conhecido com o MeshCollider componente. Em vez de desativar todas as colisões, ele torna este valor equivalente ao padrão (ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER).

// create entity
const myEntity = engine.addEntity()
// visible shape
MeshRenderer.setBox(myEntity)

// create a MeshCollider component that only responds to player physics
MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS)

Uma única máscara de colisão pode responder a múltiplas camadas de colisão. Use o | caracter como um ou, para incluir quantas camadas você precisar. O valor padrão em um MeshCollider é ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER.

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

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

Veja Raycasting para mais sobre como usar camadas de colisão personalizadas.

Câmeras e colliders

Quando a câmera do jogador se move em modo 3ª pessoa, a câmera pode ser bloqueada por colliders ou não, dependendo das camadas de colisão atribuídas às entidades. Tenha isso em mente ao projetar sua cena; você pode querer impedir que a câmera atravesse paredes ou outras entidades.

Para evitar que a câmera atravesse paredes, você deve atribuir tanto a ColliderLayer.CL_PHYSICS quanto a ColliderLayer.CL_POINTER camadas às entidades que você quer que bloqueiem a câmera. É importante que ambas as camadas sejam atribuídas à mesma geometria da entidade. Portanto, se você atribuir a ColliderLayer.CL_PHYSICS camada à camada visível da entidade, você também deve atribuir a ColliderLayer.CL_POINTER camada à mesma geometria.

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

Ambas as ColliderLayer.CL_PHYSICS quanto a ColliderLayer.CL_POINTER camadas são atribuídas à mesma camada invisível da geometria da entidade. Se ambas fossem atribuídas à camada visível, o resultado seria o mesmo. Este é o comportamento padrão, tanto ao adicionar uma entidade via Creator Hub quanto via código.

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

// 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
// Both use the same visible geometry
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	visibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER,
})

// YES CAMERA GOES THROUGH THE WALL
// physics and pointer are on diferent layers
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
	visibleMeshesCollisionMask: ColliderLayer.CL_POINTER
})

// YES CAMERA GOES THROUGH THE WALL
// physics and pointer are on diferent layers
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
	visibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS
})

Bloqueio de ponteiro

Apenas formas que têm colliders podem ser ativadas com pointer events. Uma entidade também precisa ter um collider para bloquear eventos de ponteiro de atravessarem e impedir atingir entidades atrás dela. Então, por exemplo, um jogador não pode pegar algo que esteja trancado dentro de um baú, se o baú tiver colliders ao seu redor. Os eventos de ponteiro do jogador são afetados apenas por malhas que estejam ativas na ColliderLayer.CL_POINTER layer.

Por padrão, um MeshCollider afeta tanto as camadas Physics quanto Pointer, mas você pode mudar esse valor para afetar apenas uma, ou nenhuma, e para afetar camadas personalizadas em vez disso.

📔 Nota: Além dos colliders, uma entidade também precisa ter um PointerEvents componente para responder a eventos de ponteiro. Os pointerEventsSystem helpers também cuidam desse requisito.

// only responds to player physics
// for example for an invisible wall that you can't walk through but you can click through
MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS)

// only responds to the player's pointer
// for example for an item you can click to pick up, but can walk right through
MeshCollider.setBox(myEntity2, ColliderLayer.CL_POINTER)

Por padrão, a geometria visível de um GLTFContainer não está mapeada para nenhuma camada de colisão, mas a geometria invisível afeta tanto as camadas Physics quanto Pointer. Você pode mudar esse valor para afetar apenas uma, ou nenhuma, e para afetar camadas personalizadas em vez disso. Você também pode configurar a camada da geometria visível da mesma forma.

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

// player physics uses the simpler invisible geometry
// pointer events use the full detailed contour of the visible geometry
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
	visibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
})

// both player physics and pointer events use the full detailed contour of the visible geometry
// the simpler invisible geometry is mapped to ColliderLayer.CL_NONE to avoid calculating both
GltfContainer.create(myEntity, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_NONE,
	visibleMeshesCollisionMask:
		ColliderLayer.CL_POINTER | ColliderLayer.CL_PHYSICS,
})

// don't respond to collisions of any kind, with either the visible or the invisible geometry:
GltfContainer.create(myEntity, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_NONE,
})

Sintaxe avançada de MeshCollider

A sintaxe completa para criar um MeshCollider componente, sem quaisquer helpers para simplificá-la, se parece com isto:

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 componentes MeshCollider. As funções helper abstraem isso e expõem uma sintaxe mais amigável, mas por trás dos panos elas produzem 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

Dependendo do valor de $caseé válido definir o objeto para a forma correspondente, passando quaisquer propriedades relevantes.