Registrar Callback

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

A maneira mais fácil de lidar com eventos de botão é registrar uma função de callback para uma determinada entidade. Toda vez que essa entidade for interagida usando um botão específico, a função de callback é chamada.

Se você precisar adicionar o mesmo comportamento a várias entidades semelhantes, considere usar o abordagem baseada em System em vez de adicionar callbacks a cada entidade. A abordagem baseada em sistema pode resultar em mais eficiência ao iterar sobre uma lista de entidades semelhantes.

A abordagem Register callback é especialmente útil se você quiser descrever um comportamento que afeta uma única entidade, pois é mais direta.

📔 Nota: Para que uma entidade seja interativa, ela deve ter um collider. Veja obstacles para mais detalhes.

Pointer down

Use pointerEventsSystem.onPointerDown() para detectar pressionamentos de um botão específico.

Essa declaração requer dois parâmetros:

• data: Um objeto que contém o seguinte:

  • entity: A entidade a ser manipulada

  • opts: Um objeto com dados adicionais opcionais:

    • button: Qual botão escutar. Veja Pointer buttons para opções suportadas. Se nenhum botão for especificado, então todos os botões são escutados, incluindo botões de movimento como forward e jump.

    • maxDistance: A distância máxima entre a entidade e a camerado jogador, em metros.

    • maxPlayerDistance: A distância máxima entre a entidade e a avatardo jogador, em metros.

    • hoverText: Qual string exibir na dica de feedback de hover. "Interact" por padrão.

    • hideFeedback: Se true, esconde tanto a dica de hover quanto o destaque de borda para esta entidade. false por padrão.

    • showHighlight: Se true, os jogadores verão o destaque de borda ao posicionar o cursor sobre a entidade. true por padrão. Esse valor só é considerado se hideFeedback for false.

• cb: Uma função de callback para executar toda vez que um evento de botão down ocorrer enquanto se aponta para a entidade

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

O comando acima deixa a função de callback registrada e será chamada como uma funções assíncronas toda vez que o evento de botão relacionado ocorrer.

📔 Nota: Apenas um pointerEventsSystem.onPointerDown pode ser registrado por entidade. Uma vez adicionado, ele continuará escutando eventos até que o listener seja removido. Não execute isso repetidamente dentro de um system, pois isso continuaria reescrevendo o comportamento do evento pointer.

Hover Feedback

É muito importante dar aos jogadores algum tipo de indicação de que uma entidade pode ser interagida.

Ao registrar uma ação de input com o EventsSystem, por padrão os jogadores verão:

• Um destaque de borda na entidade

• Uma dica de hover próxima ao cursor com um ícone para o botão que precisam pressionar e uma string que diz "Interact".

Esses elementos podem ser alternados e personalizados.

O feedback de hover na UI exibe um ícone diferente dependendo do input que você selecionar no button campo. No PC, exibe um ícone com um E para InputAction.IA_PRIMARY, um F para InputAction.IA_SECONDARY, e um mouse para InputAction.IA_POINTER.

Altere a string mudando o hoverText valor. Mantenha essa string curta, para que seja rápida de ler e não seja muito intrusiva na tela.

pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_PRIMARY, hoverText: 'Open door' },
	},
	function () {
		// open door
	}
)

Para esconder a dica de hover, mas deixar o destaque de borda, defina o valor do hoverText para "".

pointerEventsSystem.onPointerDown(
  {entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: ''}},,
  function () {
    console.log("clicked on surprise interactive item")
  }
)

Para esconder o destaque de borda mas deixar a dica de hover, defina showHighlight para false.

pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: {
			button: InputAction.IA_PRIMARY,
			hoverText: 'Open door',
			showHighlight: false,
		},
	},
	function () {
		console.log('opened secret door')
	}
)

Para esconder tanto a dica de hover quanto o destaque de borda, defina o hideFeedback para true. Ao fazer isso, o cursor não mostra nenhum ícone, texto ou qualquer destaque de borda.

pointerEventsSystem.onPointerDown(
  {entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hideFeedback: true}},,
  function () {
    console.log("opened secret door")
  }
)

Alterar feedback existente

Ao registrar uma ação de input com o EventsSystem, isso está criando um PointerEvents componente e adicionando-o à entidade interativa nos bastidores. Esse componente lida com o comportamento da dica de hover na UI. Para alterar o comportamento do feedback de hover, modifique esse componente. Veja Show feedback para mais sobre como lidar com esse componente.

const hoverFeedback = PointerEvents.getMutable(myEntity)

hoverFeedback.pointerEvents[0].eventInfo.hoverText = 'Close door'

Limites de distância

As maxDistance e maxPlayerDistance opções definem a distância máxima entre a entidade e a câmera e o avatar do jogador, respectivamente. Se o jogador estiver muito longe, o efeito de destaque da entidade ficará vermelho em vez de verde, e os eventos de pointer não funcionarão.

pointerEventsSystem.onPointerDown(
	{ entity: myEntity, opts: { maxDistance: 10, maxPlayerDistance: 5 } },
	function () {
		console.log('clicked entity')
	}
)

Se a cena estiver usando uma Virtual Camera, o maxDistance é medido a partir da câmera virtual que estiver atualmente ativa.

• Se ambos maxDistance e maxPlayerDistance forem fornecidos, a interação é permitida se QUALQUER uma das verificações passar (lógica OR). Por exemplo, se maxDistance for 10 metros e maxPlayerDistance for 5 metros, a interação é permitida se o jogador estiver dentro de 10 metros da câmera OU dentro de 5 metros do avatar.

• Se apenas um dos dois valores for fornecido, a interação é permitida se o jogador estiver dentro da distância fornecida, sem considerar o valor padrão da outra distância.

• Se nenhum dos dois valores for fornecido, o padrão se comporta como se a maxDistance (camera) fosse 10 metros.

Pointer up

Use pointerEventsSystem.onPointerUp para registrar uma função de callback que é chamada quando o jogador indicado solta o botão enquanto aponta para a entidade.

pointerEventsSystem.onPointerUp(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_PRIMARY, hoverText: 'Button up' },
	},
	function () {
		console.log('button up')
	}
)

Essa declaração requer três parâmetros:

• data: Um objeto que contém o seguinte:

  • entity: A entidade a ser manipulada

  • opts: Um objeto com dados adicionais opcionais:

    • button: Qual botão escutar. Veja Pointer buttons para opções suportadas. Se nenhum botão for especificado, então todos os botões são escutados, incluindo botões de movimento como forward e jump.

    • hoverText: Qual string exibir na dica de feedback de hover. "Interact" por padrão.

    • hideFeedback: Se true, esconde a dica de hover para esta entidade.

    • maxDistance: A que distância o jogador pode estar da entidade para poder interagir com ela, em metros. Se o jogador estiver muito longe, não haverá feedback de hover e os eventos de pointer não funcionarão.

• cb: Uma função de callback para executar toda vez que um evento de botão up ocorrer enquanto se aponta para a entidade.

Uma mesma entidade pode ter dois callbacks diferentes registrados, um para pointerEventsSystem.onPointerDown e outro para pointerEventsSystem.onPointerUp. A entidade só pode registrar um callback de cada um, Lidar com múltiplos botões para detectar botões diferentes em um mesmo callback.

📔 Nota: O feedback de hover para um evento de botão up só é exibido quando o botão está atualmente pressionado. Se o jogador apontar para a entidade sem segurar o botão, ele não verá feedback, ou verá o feedback para o evento de botão down, se houver.

Remover callbacks

Para remover uma função de callback, use pointerEventsSystem.removeOnPointerDown ou pointerEventsSystem.removeOnPointerUp.

pointerEventsSystem.removeOnPointerDown(myEntity)

pointerEventsSystem.removeOnPointerUp(myEntity)

Uma vez removido, o feedback de hover na entidade não deve mais ser exibido, e a entidade não deve mais ser interativa.

Dados da ação de input

Busque dados de uma ação de input, como o botão que foi pressionado, a entidade que foi atingida, a direção e o comprimento do raio, etc. Veja (Veja a documentação) para uma descrição de todos os dados disponíveis.

Para buscar esses dados, passe um parâmetro para a função de callback. Esse parâmetro contém a estrutura de dados completa com informações sobre o evento de input.

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

Lidar com múltiplos botões

Você não pode registrar mais de um onPointerDown em uma única entidade. Idealmente você deve usar a abordagem baseada em System abordagem, pois isso permite lidar com quantos inputs diferentes você desejar, e exibir uma dica de hover na UI para cada botão.

Como alternativa, você pode usar a abordagem Register callback e definir o button campo como InputAction.IA_ANY.

pointerEventsSystem.onPointerDown(
  {entity: myEntity, opts: { button: InputAction.IA_ANY}},,
  function (cmd) {
      if(cmd.button === InputAction.IA_POINTER){
        // do X
      } else if (cmd.button === InputAction.IA_PRIMARY){
        // do Y
      }
  }
)

Essa abordagem não é ideal, pois a dica de hover mostra uma única string e não especifica qual ação ativar. Note que isso fará a função de callback rodar para toda ação de input incluindo teclas de movimento, então você deve filtrar apenas as ações que lhe interessam.