Colliders

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

Entities que têm colliders ocupam espaço e bloqueiam o caminho de um jogador; Entities sem colliders podem ser atravessadas pelo avatar de um jogador.

Os colliders também são necessários para tornar uma Entity clicável. Os eventos de Button baseiam-se na forma do collider de uma Entity, e não na sua forma visível.

Existem separate collision layers para interagir com a física do player 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 custom layers, que podem ser usadas com raycasts para lidar com o que fizer sentido para a scene.

📔 Nota: Os colliders não afetam a forma como outras Entities interagem entre si; as Entities podem sempre sobrepor-se. As definições de colisão apenas afetam a forma como a Entity interage com o avatar do player e com os eventos de Button. Decentraland não tem um motor de física nativo, por isso, se quiseres que as Entities caiam, choquem ou ressaltem, tens de programar esse comportamento na scene ou importar uma library para lidar com isso.

Usa o Scene Editor

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

Podes adicionar um Mesh Collider component à tua Entity para atribuir uma forma primitiva (cubo, plano, esfera, cilindro ou cone) à tua Entity. Depois, podes escolher collision layers num dropdown.

Também podes configurar as collision layers num GLTF component para alterar o default collision layers usado na geometria do collider ou na geometria visível do modelo. Vê Add Components.

Colliders em formas primitivas

O MeshCollider component dá a uma Entity um collider simples com base numa 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 default. Tens também de dar à Entity um MeshCollider component.

As seguintes collider shapes estão disponíveis em MeshCollider. Várias shapes incluem campos adicionais opcionais, específicos dessa shape.

• box:

  Usa MeshCollider.setBox(), passando a Entity.

• plane:

  Usa MeshCollider.setPlane(), passando a Entity.

• sphere:

  Usa MeshCollider.setSphere(), passando a Entity.

• cylinder:

  Usa MeshCollider.setCylinder(), passando a Entity. Passa radiusTop e radiusBottom como campos opcionais adicionais, para modificar o cylinder.

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

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

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

// visible shape
MeshRenderer.setBox(myCollider)

// collider
MeshCollider.setBox(myCollider)

A shape usada pelo MeshCollider não precisa de coincidir necessariamente com a usada pelo MeshRenderer. Também podes adicionar um MeshCollider a uma Entity que tenha um modelo 3D de um GltfContainer component, ou a uma Entity que não tenha qualquer forma visível.

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

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

Vê Imports para saber como lidar facilmente com isto.

Colliders em modelos 3D

A modelos 3D podem ser atribuídos colliders em dois níveis de geometria diferentes:

• visibleMeshesCollisionMask: Refere-se à geometria visível do modelo. Por default, esta geometria não tem colliders.

• invisibleMeshesCollisionMask: refere-se às collider meshes, cujo nome termina em _collider. Por default, esta geometria é tratada como um collider tanto para physics 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 default.

Definir a geometria do collider como uma camada 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 quiseres fazê-lo afetar os systems de physics ou de pointer events, podes:

• Atribuir collision layers diretamente à geometria visível, através de visibleMeshesCollisionMask.

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

• Dar à Entity um MeshCollider component, para lhe dar um collider de forma primitiva.

• Sobrepor uma Entity invisível que tenha um MeshCollider component.

• Editar o modelo numa ferramenta externa como o Blender para incluir uma collider mesh. O collider tem de ser chamado x_collider, onde x é o nome do modelo. Portanto, para um modelo chamado house, o collider tem de ser chamado house_collider.

Talvez também queiras atribuir a collision layer de pointer events à visibleMeshesCollisionMask caso queiras que as hover hints e os pointer events respondam com mais precisão ao contorno da Entity. Nota que isto exige mais performance.

📔 Nota: Certifica-te de que não tens a mesma layer (physics, pointer events ou custom layers) atribuída a ambas as visibleMeshesCollisionMask e invisibleMeshesCollisionMask, pois isso seria uma utilização muito ineficiente dos recursos. Podes ter layers diferentes em cada uma, como physics na layer invisível e pointer events na layer 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,
})

Vê 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"

Vê Imports para saber como lidar facilmente com isto.

Modelos animados

Ao definir colliders para usar a geometria visível num modelo que inclui armature-based animations, as animations 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 não animada enquanto a animação decorre.

Quando se reproduzem animações que envolvem mover meshes inteiras sem alterar a sua forma, estas 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 também se move com a animação.

collision layers

A scene pode lidar com separate collision layers, que têm comportamentos diferentes.

Podes configurar um MeshCollider component ou o GltfContainer component para responder apenas a um tipo de interação, a vários, ou a nenhum. Para fazer isto, no MeshCollider define o collisionMask property, e em GltfContainer define o visibleMeshesCollisionMask ou invisibleMeshesCollisionMask properties para um ou vários dos seguintes valores:

• ColliderLayer.CL_PHYSICS: Bloqueia o movimento do player (walls, floors, 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 apontem para CL_PLAYER vão detetá-lo, mas a cápsula do player atravessa-o sem bloqueio físico. Em meshes da scene, isto é útil para sinalizar uma mesh como "um alvo semelhante a um avatar" apenas para deteção.

• ColliderLayer.CL_MAIN_PLAYER: Como CL_PLAYER, mas direcionado apenas para o player 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 custom layers específicas.

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

💡 Dica: CL_PLAYER e CL_MAIN_PLAYER num MeshCollider / GltfContainer são apenas de deteção layers — a cápsula do player atravessa-os. Se quiseres que a mesh seja TANTO detetável como avatar QUANTO bloqueie fisicamente o player, combina a layer de avatar com CL_PHYSICS (por ex. CL_PHYSICS | CL_MAIN_PLAYER).

📔 Nota: Para desativar collisions de um MeshCollider component, apaga o component. Não definas a collision layer como ColliderLayer.CL_NONE. Há um problema conhecido com o MeshCollider component. Em vez de desativar todas as collisions, faz com que este valor seja equivalente ao default (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 collision mask pode responder a várias collision layers. Usa o | caracter como oupara incluir tantas layers quantas precisares. O valor default de um MeshCollider é ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER.

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

Podes usar as 8 custom layers diferentes para o que melhor se adequar à tua scene; por exemplo, uma pode ser usada para cálculos de linha de visão de NPCs, enquanto outra para estimar trajetórias de objetos a cair. Usar layers diferentes para systems diferentes permite usar menos recursos, porque em cada caso só vais verificar colisões com as Entities relevantes.

Vê Raycasting para saber mais sobre como usar custom collision layers.

Cameras e colliders

Quando a camera de um player se move em modo de 3.ª pessoa, a camera pode ser bloqueada por colliders ou não, dependendo das collision layers atribuídas às Entities. Tem isto em conta ao desenhares a tua scene; talvez queiras impedir que a camera passe por walls ou por outras Entities.

Para evitar que a camera passe por walls, tens de atribuir tanto a ColliderLayer.CL_PHYSICS como a ColliderLayer.CL_POINTER layers às Entities que queres que bloqueiem a camera. É importante que ambas as layers sejam atribuídas à mesma geometria na Entity. Portanto, se atribuíres a ColliderLayer.CL_PHYSICS layer à layer visível da Entity, tens também de atribuir a ColliderLayer.CL_POINTER layer à mesma geometria.

Por exemplo, no Creator Hub, a seguinte combinação de definições impedirá a camera de passar pelas walls:

Ambas as ColliderLayer.CL_PHYSICS como a 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. Este é o comportamento default, tanto ao adicionar uma Entity via Creator Hub como via código.

Neste segundo exemplo, a camera pode atravessar a wall, porque a ColliderLayer.CL_PHYSICS layer está atribuída à layer invisível da Entity, e a ColliderLayer.CL_POINTER layer está atribuída à layer visível da Entity, mesmo que ambas as geometrias tenham a mesma forma global.

// 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 different 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 different layers
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
	visibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
})

Bloqueio de pointer

Só as shapes que têm colliders podem ser ativadas com pointer events. Uma Entity também precisa de ter um collider para bloquear que pointer events a atravessem e evitar atingir Entities atrás dela. Portanto, por exemplo, um player não consegue apanhar algo que esteja trancado dentro de um baú, se o baú tiver colliders à volta. Os pointer events do player só são afetados por meshes que estejam ativas na ColliderLayer.CL_POINTER layer.

Por default, um MeshCollider afeta tanto a layer Physics como a layer Pointer, mas podes alterar este valor para afetar apenas uma, ou nenhuma, e afetar custom layers em vez disso.

📔 Nota: Além de colliders, uma Entity também precisa de ter um PointerEvents component para responder a pointer events. Os helpers do pointerEventsSystem também tratam 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 default, a geometria visível de um GltfContainer não está mapeada para quaisquer collision layers, mas a geometria invisível afeta tanto a layer Physics como a layer Pointer. Podes alterar este valor para afetar apenas uma, ou nenhuma, e afetar custom layers em vez disso. Também podes configurar a layer 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,
})

Advanced MeshCollider Syntax

A sintaxe completa para criar um MeshCollider component, sem quaisquer helpers para a simplificar, é 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 componentes MeshCollider. As helper functions abstraem isto e expõem uma sintaxe mais amigável, mas nos bastidores produzem esta sintaxe.

O $case field permite-te 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 shape correspondente, passando quaisquer propriedades relevantes.