Registar callback

Aprenda a lidar com cliques do utilizador na sua cena.

A forma mais fácil de lidar com eventos de botão é registrar uma função de callback para uma entidade específica. Sempre 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 a Baseado em System em vez de adicionar callbacks a cada entidade. A abordagem baseada em System pode resultar em mais eficiência, à medida que você percorre 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 deve ter uma collider. Veja obstacles para mais detalhes.

Pointer down

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

Esta instrução requer dois parâmetros:

dados: Um objeto que contém o seguinte:
- entity: A entidade a ser tratada
- opts: Um objeto com dados adicionais opcionais:
  - button: Qual botão ouvir. Veja Pointer buttons para opções suportadas. Se nenhum botão for especificado, então todos os botões serão ouvidos, 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 hover feedback. "Interact" por padrão.
  - hideFeedback: Se true, oculta 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 passar o cursor sobre a entidade. true por padrão. Este valor só é considerado se hideFeedback for false.
cb: Uma função de callback a ser executada cada vez que ocorrer um evento de button down 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 um funções assíncronas cada vez que o evento de botão relacionado ocorrer.

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

Feedback de Hover

É 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 eles precisam pressionar e uma string que diz "Interact".

Esses elementos podem ser alternados e personalizados.

O hover feedback na UI exibe um ícone diferente dependendo do input selecionado no button field. No PC, ele 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 alterando o hoverText valor. Mantenha essa string curta, para que seja rápida de ler e não fique muito intrusiva na tela.

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

Para ocultar a dica de hover, mas manter o destaque de borda, defina o valor de hoverText como "".

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

Para ocultar o destaque de borda, mas manter a dica de hover, defina showHighlight // desenhar UI false.

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

Para ocultar tanto a dica de hover quanto o destaque de borda, defina o hideFeedback como true. Ao fazer isso, o cursor não mostra nenhum ícone, texto ou 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, isto está criando um PointerEvents component e adicionando-o à entidade interativa nos bastidores. Este component lida com o comportamento da dica de hover da UI. Para alterar o comportamento do hover feedback, modifique este component. Veja Show feedback para saber mais sobre como lidar com este component.

const hoverFeedback = PointerEvents.getMutable(myEntity)

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

Limites de distância

O maxDistance e maxPlayerDistance as opções definem a distância máxima entre a entidade e a camera e o avatar do jogador, respectivamente. Se o jogador estiver longe demais, o efeito de hightlight da entidade será 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 scene estiver usando um Virtual Camera, os maxDistance é medido a partir da virtual camera que está 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 camera 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 o 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')
	}
)

Esta instrução requer três parâmetros:

dados: Um objeto que contém o seguinte:
- entity: A entidade a ser tratada
- opts: Um objeto com dados adicionais opcionais:
  - button: Qual botão ouvir. Veja Pointer buttons para opções suportadas. Se nenhum botão for especificado, então todos os botões serão ouvidos, incluindo botões de movimento como forward e jump.
  - hoverText: Qual string exibir na dica de hover feedback. "Interact" por padrão.
  - hideFeedback: Se true, oculta a dica de hover para esta entidade.
  - maxDistance: Quão longe o jogador pode estar da entidade para conseguir interagir com esta entidade, em metros. Se o jogador estiver muito longe, não haverá hover feedback e os eventos de pointer não funcionarão.
cb: Uma função de callback a ser executada cada vez que ocorrer um evento de button up enquanto se aponta para a entidade.

A 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, Lidar com múltiplos botões para detectar botões diferentes em um mesmo callback.

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

Hover enter e leave

Use pointerEventsSystem.onPointerHoverEnter para executar um callback quando o cursor do jogador começa a apontar para uma entidade, e pointerEventsSystem.onPointerHoverLeave quando o cursor deixa de apontar para ela.

pointerEventsSystem.onPointerHoverEnter(
    {
        entity: myEntity,
        opts: { button: InputAction.IA_POINTER },
    },
    function () {
        console.log('Cursor started hovering over entity')
    }
)

pointerEventsSystem.onPointerHoverLeave(
    {
        entity: myEntity,
        opts: { button: InputAction.IA_POINTER },
    },
    function () {
        console.log('Cursor stopped hovering over entity')
    }
)

Esses callbacks são úteis para efeitos de hover personalizados, como tocar um som ou animar a entidade quando o jogador a mira.

Remover callbacks

Para remover uma função de callback, use a função de remoção correspondente:

pointerEventsSystem.removeOnPointerDown(myEntity)
pointerEventsSystem.removeOnPointerUp(myEntity)
pointerEventsSystem.removeOnPointerHoverEnter(myEntity)
pointerEventsSystem.removeOnPointerHoverLeave(myEntity)

Depois de removido, o hover feedback na entidade não deverá mais ser exibido, e a entidade não deverá mais ser interativa.

Interações por proximidade

Para interações que são acionadas com base na proximidade do jogador, em vez da mira do cursor, veja Proximity Events. O pointerEventsSystem inclui helpers equivalentes — onProximityDown, onProximityUp, onProximityEnter, e onProximityLeave — que seguem o mesmo padrão das funções descritas nesta página.

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 ray, etc. Veja (Ver 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 completa de dados 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 Baseado em System pois isso permite lidar com quantos inputs diferentes você quiser e exibir uma dica de hover feedback de 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){
        // faça X
      } else if (cmd.button === InputAction.IA_PRIMARY){
        // faça Y
      }
  }
)

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

AnteriorEventos de clique PróximoEventos baseados em Systems

Atualizado há 2 meses