Registrar callback

Aprende cómo manejar los clics de usuario en tu escena.

La forma más fácil de manejar eventos de botones es registrar una función de callback para una entidad en particular. Cada vez que esa entidad se interactúa con un botón específico, se llama a la función de callback.

Si necesitas añadir el mismo comportamiento a múltiples entidades similares, considera usar el enfoque basado en System en lugar de añadir callbacks a cada entidad. El enfoque basado en System puede ser más eficiente al iterar sobre una lista de entidades similares.

El enfoque de Registrar callback es especialmente útil si quieres describir un comportamiento que afecta a una sola entidad, ya que es más directo.

📔 Nota: Para que una entidad sea interactiva, ésta debe tener un collider. Ver obstáculos para más detalles.

Pointer down

Usa pointerEventsSystem.onPointerDown() para detectar pulsaciones de un botón específico.

Esta instrucción requiere dos parámetros:

• data: Un objeto que contiene lo siguiente:

  • entity: La entidad a manejar

  • opts: Un objeto con datos adicionales opcionales:

    • button: Qué botón escuchar. Ver Botones de puntero para las opciones soportadas. Si no se especifica ningún botón, entonces se escuchan todos los botones, incluyendo botones de movimiento como avanzar y saltar.

    • maxDistance: La distancia máxima entre la entidad y la cámara, en metros.

    • maxPlayerDistance: La distancia máxima entre la entidad y la avatar, en metros.

    • hoverText: Qué cadena mostrar en la pista de retroalimentación hover. "Interact" por defecto.

    • hideFeedback: Si es true, oculta tanto la pista hover como el resaltado de borde para esta entidad. false por defecto.

    • showHighlight: Si es true, los jugadores verán el resaltado de borde al pasar el cursor sobre la entidad. true por defecto. Este valor solo se considera si hideFeedback es false.

• cb: Una función de callback para ejecutar cada vez que ocurre un evento de botón down mientras se apunta a la entidad

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

El comando anterior deja la función de callback registrada, y será llamada como una funciones asíncronas cada vez que ocurra el evento de botón relacionado.

📔 Nota: Solo un pointerEventsSystem.onPointerDown puede ser registrado por entidad. Una vez añadido, seguirá escuchando eventos hasta que se elimine el listener. No ejecutes esto recurrentemente dentro de un System, ya que eso estaría reescribiendo el comportamiento del evento de puntero.

Retroalimentación hover

Es muy importante dar a los jugadores algún tipo de indicación de que una entidad puede ser interactuada.

Al registrar una acción de entrada con el EventsSystem, por defecto los jugadores verán:

• Un resaltado de borde en la entidad

• Una pista hover cerca del cursor con un ícono del botón que deben presionar y una cadena que dice "Interact".

Estos elementos pueden alternarse y personalizarse.

La retroalimentación hover en la UI muestra un ícono diferente dependiendo de qué entrada selecciones en el button campo. En PC, muestra un ícono con una E para InputAction.IA_PRIMARY, una F para InputAction.IA_SECONDARY, y un ratón para InputAction.IA_POINTER.

Cambia la cadena cambiando el hoverText valor. Mantén esta cadena corta, para que sea rápida de leer y no demasiado intrusiva en la pantalla.

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

Para ocultar la pista hover, pero dejar el resaltado de borde, establece el valor de hoverText a "".

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

Para ocultar el resaltado de borde pero dejar la pista hover, establece showHighlight a false.

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

Para ocultar tanto la pista hover como el resaltado de borde, establece hideFeedback a true. Al hacerlo, el cursor no muestra ningún ícono, texto ni resaltado de borde.

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

Cambiar la retroalimentación existente

Al registrar una acción de entrada con el EventsSystem, esto está creando un PointerEvents componente y agregándolo a la entidad interactiva detrás de escena. Este componente maneja el comportamiento de la pista hover de la UI. Para cambiar el comportamiento de la retroalimentación hover, modifica este componente. Ver Mostrar retroalimentación para más información sobre cómo tratar con este componente.

const hoverFeedback = PointerEvents.getMutable(myEntity)

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

Límites de distancia

El maxDistance y maxPlayerDistance options establecen la distancia máxima entre la entidad y la cámara y el avatar del jugador, respectivamente. Si el jugador está demasiado lejos, el efecto de resaltado de la entidad será rojo en lugar de verde, y los eventos de puntero no funcionarán.

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

Si la escena está usando una Virtual Camera, el maxDistance se mide desde la cámara virtual que está activa actualmente.

• Si ambos maxDistance y maxPlayerDistance son proporcionados, la interacción está permitida si CUALQUIERA de las comprobaciones pasa (lógica OR). Por ejemplo, si maxDistance es 10 metros y maxPlayerDistance es 5 metros, la interacción está permitida si el jugador está dentro de 10 metros de la cámara O dentro de 5 metros del avatar.

• Si solo uno de los dos valores es proporcionado, la interacción está permitida si el jugador está dentro de la distancia proporcionada, sin considerar el valor por defecto de la otra distancia.

• Si ninguno de los dos valores es proporcionado, el comportamiento por defecto es como si la maxDistance (cámara) fuera de 10 metros.

Pointer up

Usa pointerEventsSystem.onPointerUp para registrar una función de callback que se llame cuando el jugador indicado suelte el botón mientras apunta a la entidad.

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

Esta instrucción requiere tres parámetros:

• data: Un objeto que contiene lo siguiente:

  • entity: La entidad a manejar

  • opts: Un objeto con datos adicionales opcionales:

    • button: Qué botón escuchar. Ver Botones de puntero para las opciones soportadas. Si no se especifica ningún botón, entonces se escuchan todos los botones, incluyendo botones de movimiento como avanzar y saltar.

    • hoverText: Qué cadena mostrar en la pista de retroalimentación hover. "Interact" por defecto.

    • hideFeedback: Si es true, oculta la pista hover para esta entidad.

    • maxDistance: A qué distancia puede estar el jugador de la entidad para poder interactuar con esta entidad, en metros. Si el jugador está demasiado lejos, no habrá retroalimentación hover y los eventos de puntero no funcionarán.

• cb: Una función de callback para ejecutar cada vez que ocurre un evento de botón up mientras se apunta a la entidad.

Una misma entidad puede tener dos callbacks diferentes registrados, uno para pointerEventsSystem.onPointerDown y otro para pointerEventsSystem.onPointerUp. La entidad solo puede registrar un callback de cada tipo, Manejar múltiples botones para detectar diferentes botones con un mismo callback.

📔 Nota: La retroalimentación hover para un evento de botón up solo se muestra cuando el botón está actualmente presionado. Si el jugador apunta a la entidad sin mantener el botón presionado, no verá retroalimentación, o verá la retroalimentación del evento de botón down, si la hay.

Eliminar callbacks

Para eliminar una función de callback, usa pointerEventsSystem.removeOnPointerDown o pointerEventsSystem.removeOnPointerUp.

pointerEventsSystem.removeOnPointerDown(myEntity)

pointerEventsSystem.removeOnPointerUp(myEntity)

Una vez eliminado, la retroalimentación hover en la entidad ya no debería mostrarse, y la entidad debería dejar de ser interactiva.

Datos de la acción de entrada

Obtén datos de una acción de entrada, como el botón que se presionó, la entidad que fue golpeada, la dirección y longitud del rayo, etc. Ver (Ver documentación) para una descripción de todos los datos disponibles.

Para obtener estos datos, pasa un parámetro a la función de callback. Este parámetro contiene la estructura de datos completa con información sobre el evento de entrada.

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

Manejar múltiples botones

No puedes registrar más de un onPointerDown en una sola entidad. Idealmente deberías usar el enfoque basado en System enfoque, ya que esto te permite manejar tantos inputs diferentes como desees, y mostrar una pista hover de UI para cada botón.

Como alternativa, puedes usar el enfoque de Registrar callback y establecer el button campo como InputAction.IA_ANY.

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

Este enfoque no es ideal, ya que la pista hover muestra una sola cadena y no especificará qué acción activar. Ten en cuenta que esto hará que la función de callback se ejecute para cada acción de entrada, incluyendo teclas de movimiento, por lo que debes filtrar solo las acciones que te interesan.