Registrar Callback

Saiba como lidar com cliques de usuário na sua scene.

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

Se você precisar adicionar o mesmo comportamento a várias entities semelhantes, considere usar a baseada em System em vez de adicionar callbacks a cada Entity. A abordagem baseada em System pode resultar em maior eficiência à medida que você itera por uma lista de entities semelhantes.

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

📔 Observação: Para que uma Entity seja interativa, ela devem ter um collider. Veja obstáculos para mais detalhes.

Pointer down

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

Esta instrução requer dois parâmetros:

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

  • entity: A Entity a ser tratada

  • opts: Um objeto com dados adicionais opcionais:

    • button: Qual botão escutar. Veja Botões do Pointer para opções compatíveis. Se nenhum button 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 Entity e o avatar, em metros. 10 por padrão. Veja Limites de distância.

    • maxCameraDistance: A distância máxima entre a Entity e a câmera ativa, em metros. Não definido por padrão. Veja Limites de distância.

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

    • showFeedback: Se false, oculta tanto a dica de hover quanto o realce da borda para esta Entity. true por padrão.

    • showHighlight: Se true, os players verão o realce da borda ao passar o cursor sobre a Entity. true por padrão. Esse valor só é considerado se showFeedback é true.

• cb: Uma função de callback para executar sempre que ocorrer um evento de button down enquanto aponta para a Entity

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 ela será chamada toda vez que o evento de botão relacionado ocorrer. Observe que o callback deve ser uma função síncrona; async funções não são compatíveis aqui e resultam em um erro.

📔 Observação: Apenas um pointerEventsSystem.onPointerDown pode ser registrado por Entity. 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 pointer event.

Feedback ao passar o mouse

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

Ao registrar uma input action com o EventsSystem, por padrão, os players verão:

• Um realce de borda na Entity

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

Esses elementos podem ser ativados/desativados e personalizados.

O feedback de hover na UI exibe um ícone diferente dependendo de qual input você selecionar no button campo. 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 seja 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 realce da 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 ocultar o realce da borda, mas manter a dica de hover, defina showHighlight como 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 realce da borda, defina showFeedback como false. Ao fazer isso, o cursor não mostra nenhum ícone, texto nem realce de borda.

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

Alterar feedback existente

Ao registrar uma input action com o EventsSystem, isso está criando um PointerEvents Component e adicionando-o à Entity interativa nos bastidores. Esse Component lida com o comportamento da dica de hover da UI. Para alterar o comportamento do feedback de hover, modifique este Component. Veja Mostrar feedback para saber mais sobre como lidar com este Component.

const hoverFeedback = PointerEvents.getMutable(myEntity)

if (hoverFeedback.pointerEvents[0]?.eventInfo) {
	hoverFeedback.pointerEvents[0].eventInfo.hoverText = 'Close door'
}

Limites de distância

Por padrão, um player só pode interagir com uma Entity quando o seu avatar está a até 10 metros dela. Se o player estiver longe demais, o efeito de realce da Entity fica vermelho em vez de verde, e os pointer events não são disparados.

Use maxDistance para alterar esse alcance:

// Só clicável quando o avatar do player estiver a até 5 metros
pointerEventsSystem.onPointerDown(
	{ entity: myEntity, opts: { maxDistance: 5 } },
	function () {
		console.log('clicked entity')
	}
)

Limitar pela distância da câmera

maxCameraDistance mede a partir da câmera ativa atualmente em vez do avatar. Isso é útil quando sua Scene usa uma Virtual Camera colocada longe do player, e você quer que a Entity seja clicável com base no que a câmera consegue ver.

// Só clicável quando a câmera ativa estiver a até 15 metros
pointerEventsSystem.onPointerDown(
	{ entity: myEntity, opts: { maxCameraDistance: 15 } },
	function () {
		console.log('clicked entity')
	}
)

Como os dois limites se combinam

As duas opções são verificações independentes. Quais delas são executadas depende do que você definir:

O que você define	O que o player precisa
Nenhum	Avatar a até 10 metros (o padrão)
maxDistance apenas	Avatar a até maxDistance
maxCameraDistance apenas	Câmera a até maxCameraDistance
Ambos	Qualquer um passar na verificação é suficiente

Definir ambos é uma forma de dizer "perto o bastante para chegar até ele caminhando, ou perto o bastante para vê-lo claramente":

// Clicável quando o avatar estiver a até 3 metros OU a câmera estiver a até 20 metros
pointerEventsSystem.onPointerDown(
	{ entity: myEntity, opts: { maxDistance: 3, maxCameraDistance: 20 } },
	function () {
		console.log('clicked entity')
	}
)

📔 Observação: maxCameraDistance requer @dcl/sdk versão 7.28.0 ou mais recente. O suporte para isso já está disponível no Explorer baseado em Bevy. Se sua Scene precisar se comportar de forma idêntica em cada client hoje, confie em maxDistance e trate maxCameraDistance como uma melhoria.

maxPlayerDistance está obsoleto

maxPlayerDistance é um alias obsoleto de maxDistance: ambos medem a distância a partir do avatar. Use maxDistance em novas Scenes.

Se uma Scene definir ambos, o maior dos dois é usado como limite de distância do avatar.

Pointer up

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

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

Esta instrução requer dois parâmetros:

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

  • entity: A Entity a ser tratada

  • opts: Um objeto com dados adicionais opcionais:

    • button: Qual botão escutar. Veja Botões do Pointer para opções compatíveis. Se nenhum button 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.

    • showFeedback: Se false, oculta a dica de hover para esta Entity. true por padrão.

    • maxDistance: Quão longe o avatar do player pode estar da Entity e ainda interagir com ela, em metros. 10 por padrão. Se o player estiver longe demais, não haverá feedback de hover e os pointer events não funcionarão. Veja Limites de distância.

• cb: Uma função de callback para executar sempre que ocorrer um evento de button up enquanto aponta para a Entity.

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

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

Entrada e saída do hover

Use pointerEventsSystem.onPointerHoverEnter para executar uma função de callback quando o cursor do player começar a apontar para uma Entity, e pointerEventsSystem.onPointerHoverLeave quando o cursor parar 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 personalizados de hover, como tocar um som ou animar a Entity quando o player mira nela.

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)

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

Cada função de remoção remove apenas a entrada que sua função de registro correspondente adicionou. Registrar e remover o mesmo callback repetidamente não deixa entradas obsoletas na Entity.

Interações de proximidade

Para interações que são acionadas com base na proximidade do player, e não na 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.

Uma Entity pode ter tanto um handler de cursor quanto um handler de proximidade para o mesmo tipo de evento. Ambos os callbacks são executados, cada um quando sua própria condição é atendida.

Dados da input action

Obtenha dados de uma input action, como o botão que foi pressionado, a Entity 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 obter esses dados, passe um parâmetro para a função de callback. Esse parâmetro contém a estrutura completa de dados sobre o input event.

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

Lidar com vários botões

Você não pode registrar mais de um onPointerDown em uma única Entity. Idealmente, você deve usar a baseada em System abordagem, pois isso permite lidar com quantos inputs diferentes você quiser e exibir uma dica de feedback de hover da 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. Observe que isso fará com que a função de callback seja executada para cada input action, incluindo teclas de movimento, então você deve filtrar apenas as ações com as quais se importa.