Colliders

Aprenda sobre os diferentes components que dão às entities sua shape 3D e colisão.

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 para lidar com o que fizer sentido para a scene.

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

Use o Scene Editor

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

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

Você também pode configurar as collision layers em um GLTF component para alterar o padrão layers de collision usado na geometria do collider ou na geometria visível do modelo. Veja Adicionar Components.

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

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

Este exemplo define uma Entity box que não pode ser atravessada.

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

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

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

Veja Imports para ver como lidar facilmente com isso.

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.

📔 Nota: Se a geometria visível do objeto tiver muitos vertices, observe que isso pode ter um custo maior de performance.

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

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

// 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 para mais detalhes sobre como adicionar geometria invisível de collider a um modelo 3D.

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

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

Veja Imports para ver como lidar facilmente com isso.

Modelos animados

Ao configurar colliders para usar a geometria visível em um modelo que inclui animações baseadas em Armature, 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.

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

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

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

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

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.

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.

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

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

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

// 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:

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.