Eventos de Clique

Aprenda como lidar com cliques de usuário na sua cena.

Uma cena da Decentraland pode detectar ações de entrada de todos os botões usados para controlar o avatar do jogador. Isso inclui cliques do pointer, vários botões de ação e as teclas usadas para mover o avatar. Eventos de botão podem vir de um mouse, uma tela sensível ao toque, um controle VR ou outro dispositivo; todos são interpretados da mesma forma pelo SDK.

Você pode detectar ações de entrada direcionadas a uma entidade. Isso envolve pressionar um botão enquanto o cursor do jogador aponta para o collider dessa entidade. Você também pode detectar global evento de entrada, que envolve ativar a entrada a qualquer momento, sem considerar para onde o pointer está apontando.

📔 Nota: Entidades devem ter um collider para responder a ações de entrada. MeshRenderer modelos também devem receber um MeshCollider componente. Modelos de um GLTFContainer podem ter sua própria geometria de colisão embutida, ou podem ser configurados para usar sua geometria visível; eles também podem receber um MeshCollider componente.

Existem várias maneiras diferentes de lidar com ações de entrada, dependendo do caso de uso.

• Registrar um callback: A maneira mais fácil de adicionar interação a uma única entidade. Escreva uma única instrução para configurar uma função callback e o feedback de hover.

• Baseado em system: Ideal para lidar com múltiplas entidades com comportamento similar. Use um system para iterar sobre entidades semelhantes e consultar ações de entrada em cada uma, tratando todas com a mesma lógica. O feedback de hover precisa ser configurado separadamente. Essa abordagem também é necessária para lidar com ações de entrada globais.

• Avançado: Leia os dados brutos de resposta em cada entidade, incluindo timestamps e um histórico de eventos de entrada. Isso pode ser útil para definir padrões de interação personalizados.

Use o Scene Editor no Creator Hub

A maneira mais fácil de lidar com eventos de clique em uma entidade é usar o Scene Editor. Use os triggers no-code On Click ou On Input Action nos itens para chamar ações ao clicar neles. Ou use On Global Click, On Global Primary ou On Global Secondary Triggers para reagir a eventos de botão globais. Veja Make any item smart.

Exemplo simples

Para detectar cliques em uma entidade, use pointerEventsSystem.onPointerDown.

pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_PRIMARY, hoverText: 'Click' },
	},
	function () {
		console.log('clicked entity')
	}
)

Veja Registrar um callback para mais informações.

Feedback de hover

É importante deixar claro para os jogadores que uma entidade é interativa. Caso contrário, eles podem perder completamente a experiência que você criou. Não é uma boa experiência ficar clicando em todo objeto na esperança de que algum responda.

Quando você usa o Registrar um callback método, dois tipos de feedback são exibidos sempre que o jogador passa o cursor sobre o objeto:

• A borda da entidade é destacada (apenas no cliente Decentraland 2.0 Desktop). O destaque é verde se a entidade estiver perto o suficiente para clicar, vermelho se a entidade estiver muito longe.

• Uma dica de hover aparece próxima ao cursor com texto de UI, sinalizando o que acontecerá se o jogador clicar.

Ao usar o Baseado em system método, você pode alcançar os mesmos resultados adicionando um PointerEvents componente às entidades clicáveis.

Tanto o destaque da entidade quanto a dica de hover podem ser desativados por meio de propriedades nesses métodos e componentes.

Você também pode implementar dicas personalizadas avançadas, por exemplo, tocar um som, fazer a entidade mudar de cor, girar ou aumentar enquanto está sendo apontada, etc. Seja o que for, certifique-se de que seja um sinalizador claro.

Obstáculos

Eventos de botão lançam rays que interagem apenas com a primeira entidade em seu caminho que esteja inscrita na camada de colisão de pointer events. Isso é verdadeiro enquanto a entidade estiver mais próxima do que seus limites de distância tanto do avatar quanto da câmera.

Para que uma entidade seja interceptada pelo ray de um evento de pointer, ou:

• O modelo deve conter mesh de collider.

• O GLTFContainer deve ser configurado para usar a geometria visível com máscaras de colisão.

• A entidade deve ter um componente MeshCollider.

Se o collider de outra entidade estiver bloqueando o caminho da entidade com a qual o jogador quer interagir, o jogador não conseguirá clicar na entidade que está atrás, a menos que a entidade não tenha collider, ou que esse collider esteja configurado para não responder à camada de colisão de pointer events.

// entidade clicável
const clickableEntity = engine.addEntity()
MeshRenderer.setBox(clickableEntity)
MeshCollider.setBox(clickableEntity)
Transform.create(clickableEntity, { position: Vector3.create(8, 1, 8) })

pointerEventsSystem.onPointerDown(
	{
		entity: clickableEntity,
		opts: {
			button: InputAction.IA_POINTER,
			hoverText: 'Click',
		},
	},
	function () {
		console.log('clicked entity')
		const t = Transform.getMutable(clickableEntity)
		t.scale.y += 0.2
	}
)

// não bloqueador para cliques
const nonBlocker = engine.addEntity()
MeshRenderer.setBox(nonBlocker)
MeshCollider.setBox(nonBlocker, ColliderLayer.CL_PHYSICS)
Transform.create(nonBlocker, { position: Vector3.create(10, 1, 8) })

// bloqueador para cliques
const blocker = engine.addEntity()
MeshRenderer.setBox(blocker)
MeshCollider.setBox(blocker, ColliderLayer.CL_POINTER)
Transform.create(blocker, { position: Vector3.create(8, 1, 10) })

📔 Nota: Para que uma entidade não só intercepte um evento de pointer, mas também retorne dados, a entidade também precisa ter um PointerEvents componente. Os pointerEventsSystem helpers também cuidam desse requisito.

Botões do pointer

As seguintes entradas podem ser tratadas por qualquer uma das abordagens para detectar eventos de entrada.

• InputAction.IA_POINTER: botão esquerdo do mouse em um computador.

• InputAction.IA_PRIMARY: Tecla E em um computador.

• InputAction.IA_SECONDARY: Tecla F em um computador.

• InputAction.IA_ACTION_3: 1 em um computador.

• InputAction.IA_ACTION_4: 2 em um computador.

• InputAction.IA_ACTION_5: 3 em um computador.

• InputAction.IA_ACTION_6: 4 em um computador.

• InputAction.IA_JUMP: Space em um computador.

• InputAction.IA_FORWARD: W em um computador.

• InputAction.IA_LEFT: A em um computador.

• InputAction.IA_RIGHT: D em um computador.

• InputAction.IA_BACKWARD: S em um computador.

• InputAction.IA_WALK: Control em um computador.

• InputAction.IA_MODIFIER: Shift em um computador.

Cada InputAction é abstraído da entrada literal no teclado para que possa ser mapeado para entradas diferentes dependendo do dispositivo. Por essa mesma razão, nem todos os botões do teclado podem ser rastreados para eventos de botão, apenas os botões usados para movimento e interação. Essa limitação intencional visa garantir que todo o conteúdo seja compatível no futuro com controles VR, outros tipos de controles de jogo e dispositivos móveis.

Tipos de eventos de pointer

Cada entrada pode produzir os seguintes tipos de eventos de pointer. Cada um dos seguintes é um valor no PointerEventType enum.

• DOWN: Jogador pressiona um botão específico enquanto o cursor aponta para o collider da entidade.

• UP: Jogador solta um botão específico enquanto o cursor aponta para o collider da entidade.

• HOVER_ENTER: O cursor do jogador começa a apontar para o collider da entidade.

• HOVER_LEAVE: O cursor do jogador para de apontar para o collider da entidade.

Dados de uma ação de entrada

Todas as ações de entrada incluem dados sobre o evento, incluindo coisas como o botão que foi ativado e para onde o cursor estava apontando no momento.

As seguintes informações podem ser obtidas de qualquer evento de entrada:

• analog: Flag para marcar se o evento é de uma entrada analógica ou digital. Entradas digitais têm valor 1, entradas analógicas (como um joystick) têm valor 0.

• button: Qual id do botão foi pressionado. O número corresponde ao InputAction enum, que lista todos os botões disponíveis.

• state: Tipo de evento de pointer, do enum PointerEventType. 0 refere-se a PointerEventType.PET_DOWN, 1 para PointerEventType.PET_UP, 2 para PointerEventType.PET_HOVER_ENTER, 3 para PointerEventType.PET_HOVER_LEAVE

• timestamp: Um timestamp lamport para identificar cada evento de botão.

  Nota: Esse timestamp não é numerado com base no tempo atual. Pense nele como um contador que começa em 0 e é incrementado em 1 para cada evento.

• hit: Um objeto que contém os seguintes dados sobre o evento de hit:

  • entityId: Número de id da entidade que foi atingida pelo raio.

  • meshName: String com o nome interno da mesh específica no modelo 3D que foi atingida. Isso é útil quando um modelo 3D é composto por múltiplas meshes.

  • origin: Vector3 para a posição onde o raio se origina (relativa à cena)

  • position: Vector3 para a posição onde o raio intersectou a entidade atingida (relativa à cena)

  • length: Comprimento do raio desde sua origem até a posição onde o hit contra a entidade ocorreu.

  • normalHit: Quaternion para o ângulo da normal do hit no espaço mundial.

Esses dados são acessados de maneiras diferentes dependendo da abordagem que você está usando para lidar com ações de entrada.

Usando a Registrar um callback abordagem, o primeiro parâmetro passado para a função callback contém toda essa estrutura de dados.

pointerEventsSystem.onPointerDown({ entity: myEntity }, function (cmd) {
	console.log(cmd.hit.entityId)
})

Usando a Baseado em system abordagem, use inputSystem.getInputCommand() para buscar esses dados.

engine.addSystem(() => {
	const cmd = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN,
		myEntity
	)
	if (cmd) {
		console.log(cmd.hit.entityId)
	}
})

📔 Nota: Para que uma entidade não só intercepte um evento de pointer, mas também retorne dados, a entidade também precisa ter um PointerEvents componente. Os pointerEventsSystem helpers também cuidam desse requisito.

Usando a Avançado abordagem, o PointerEventsResults contém um array com um histórico recente de todos os eventos de pointer contra essa entidade.

engine.addSystem(() => {
	const pointerEvents = engine.getEntitiesWith(PointerEventsResult)
	for (const [entity] of pointerEvents) {
		const poninterEvents = PointerEventsResult.get(entity)

		if (poninterEvents.commands.length > 0) {
			console.log(poninterEvents.commands[0].hit.entityId)
		}
	}
})

Bloquear ou desbloquear o cursor

Jogadores no cliente desktop da Decentraland podem alternar entre dois modos distintos de interação com o cursor:

• Cursor bloqueado: mover o mouse desloca a câmera e eventos de clique ocorrem na mira no centro da tela movendo o mouse ou pointer diretamente

• Cursor desbloqueado: o cursor é livre para se mover independentemente da câmera, e os jogadores podem clicar em qualquer lugar da tela para interagir tanto com o espaço 3D quanto com a UI

Esses modos de interação são ideais para diferentes tipos de mecânicas de jogo, e você pode querer que os jogadores adotem um ou outro dependendo do que for mais adequado à sua cena. Você também pode querer garantir momentaneamente que o cursor do jogador esteja desbloqueado para permitir que ele interaja com uma UI; isso é especialmente útil para jogadores novos que não estão familiarizados com como isso é controlado.

Para alterar o estado do cursor do jogador, use o PointerLock componente no engine.CameraEntity entity.

import {PointerLock} from '@dcl/sdk/ecs'
    
PointerLock.create(engine.CameraEntity, {isPointerLocked: false})

Você também pode consultar o estado do cursor do jogador lendo o PointerLock estado do componente.

import {PointerLock} from '@dcl/sdk/ecs'

PointerLock.create(engine.CameraEntity)

const isPointerLocked = PointerLock.get(engine.CameraEntity).isPointerLocked

Use a .onChange função para reagir às mudanças no estado do pointer. O exemplo a seguir faz com que o cursor esteja sempre desbloqueado.

import {PointerLock} from '@dcl/sdk/ecs'

export function main() {

    PointerLock.create(engine.CameraEntity, {isPointerLocked: false});

    PointerLock.onChange(engine.CameraEntity, (pointerLock) => {
		    if (!pointerLock) return
		    if(pointerLock.isPointerLocked){
			    PointerLock.getMutable(engine.CameraEntity).isPointerLocked = false
		   }
	})
}