Registrar callback

Aprende cómo gestionar 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 se interactúa con esa entidad usando 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 basado en System enfoque en lugar de añadir callbacks a cada entidad. El enfoque basado en System puede resultar más eficiente a medida que recorres una lista de entidades similares.

El enfoque de Register 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, debe debe tener un collider. Consulta obstáculos para ver más detalles.

Pulsación del puntero

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

Esta sentencia requiere dos parámetros:

• data: Un objeto que contiene lo siguiente:

  • entity: La entidad a gestionar

  • opts: Un objeto con datos adicionales opcionales:

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

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

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

    • hoverText: Qué cadena mostrar en la sugerencia de feedback al pasar el cursor. "Interact" por defecto.

    • showFeedback: Si es false, oculta tanto la sugerencia al pasar el cursor como el resaltado de borde para esta entidad. true por defecto.

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

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

pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_PRIMARY, hoverText: 'Haz clic' },
	},
	function () {
		console.log('se hizo clic en la entidad')
	}
)

El comando anterior deja la función de callback registrada, y se llamará cada vez que ocurra el evento de botón relacionado. Ten en cuenta que la callback debe ser una función síncrona; async las funciones no son compatibles aquí y dan lugar a un error.

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

Retroalimentación al pasar el cursor

Es muy importante dar a los jugadores algún tipo de indicación de que se puede interactuar con una entidad.

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

• Un resaltado de borde en la entidad

• Una sugerencia al pasar el cursor cerca del puntero con un icono del botón que deben presionar y una cadena que dice "Interact".

Estos elementos se pueden activar/desactivar y personalizar.

El feedback al pasar el cursor en la UI muestra un icono diferente según la entrada que selecciones en el button campo. En PC, muestra un icono 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 resulte demasiado intrusiva en la pantalla.

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

Para ocultar la sugerencia al pasar el cursor, pero dejar el resaltado de borde, establece el valor de la hoverText hoverText

pointerEventsSystem.onPointerDown(
  {entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: ''}},
  function () {
    console.log("se hizo clic en el objeto interactivo sorpresa")
  }
)

Para ocultar el resaltado de borde pero dejar la sugerencia al pasar el cursor, establece showHighlight en false.

pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: {
			button: InputAction.IA_PRIMARY,
			hoverText: 'Abre la puerta',
			showHighlight: false,
		},
	},
	function () {
		console.log('se abrió la puerta secreta')
	}
)

Para ocultar tanto la sugerencia al pasar el cursor como el resaltado de borde, establece showFeedback en false. Al hacerlo, el cursor no muestra ningún icono, texto ni resaltado de borde.

pointerEventsSystem.onPointerDown(
  {entity: myEntity, opts: { button: InputAction.IA_PRIMARY, showFeedback: false}},
  function () {
    console.log("se abrió la puerta secreta")
  }
)

Cambiar el feedback existente

Al registrar una acción de entrada con el EventsSystem, esto crea un PointerEvents component y lo añade a la entidad interactiva en segundo plano. Este component gestiona el comportamiento de la sugerencia al pasar el cursor de la UI. Para cambiar el comportamiento del feedback al pasar el cursor, modifica este component. Consulta Mostrar feedback para obtener más información sobre cómo trabajar con este component.

const hoverFeedback = PointerEvents.getMutable(myEntity)

if (hoverFeedback.pointerEvents[0]?.eventInfo) {
	hoverFeedback.pointerEvents[0].eventInfo.hoverText = 'Cierra la puerta'
}

Límites de distancia

El maxDistance y maxPlayerDistance las opciones 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('se hizo clic en la entidad')
	}
)

Si la Scene está usando un Virtual Camera, las maxDistance se mide desde la cámara virtual que está activa actualmente.

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

• Si solo se proporciona uno de los dos valores, la interacción se permite si el jugador está dentro de la distancia proporcionada, sin considerar el valor predeterminado de la otra distancia.

• Si no se proporciona ninguno de los dos valores, el comportamiento predeterminado es como si la maxDistance (camera) está a 10 metros.

Puntero arriba

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

pointerEventsSystem.onPointerUp(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_PRIMARY, hoverText: 'Soltar botón' },
	},
	function () {
		console.log('botón soltado')
	}
)

Esta sentencia requiere dos parámetros:

• data: Un objeto que contiene lo siguiente:

  • entity: La entidad a gestionar

  • opts: Un objeto con datos adicionales opcionales:

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

    • hoverText: Qué cadena mostrar en la sugerencia de feedback al pasar el cursor. "Interact" por defecto.

    • showFeedback: Si es false, oculta la sugerencia al pasar el cursor para esta entidad. true por defecto.

    • 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á feedback al pasar el cursor y los eventos de puntero no funcionarán.

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

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

📔 Nota: El feedback al pasar el cursor para un evento de botón liberado solo se muestra cuando el botón está actualmente pulsado. Si el jugador apunta a la entidad sin mantener el botón pulsado, no verá ningún feedback, o el feedback para el evento de pulsación de botón, si lo hay.

Entrada y salida al pasar el cursor

Usa pointerEventsSystem.onPointerHoverEnter para ejecutar un callback cuando el cursor del jugador comienza a apuntar a una entidad, y pointerEventsSystem.onPointerHoverLeave cuando el cursor deja de apuntar a ella.

pointerEventsSystem.onPointerHoverEnter(
    {
        entity: myEntity,
        opts: { button: InputAction.IA_POINTER },
    },
    function () {
        console.log('El cursor comenzó a pasar sobre la entidad')
    }
)

pointerEventsSystem.onPointerHoverLeave(
    {
        entity: myEntity,
        opts: { button: InputAction.IA_POINTER },
    },
    function () {
        console.log('El cursor dejó de pasar sobre la entidad')
    }
)

Estos callbacks son útiles para efectos personalizados al pasar el cursor, como reproducir un sonido o animar la entidad cuando el jugador la apunta.

Eliminar callbacks

Para eliminar una función de callback, usa la función de eliminación correspondiente:

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

Una vez eliminado, el feedback al pasar el cursor en la entidad ya no debería mostrarse, y la entidad ya no debería ser interactiva.

Interacciones por proximidad

Para interacciones que se activan según la proximidad del jugador en lugar de la dirección del cursor, consulta Eventos de proximidad. El pointerEventsSystem incluye helpers equivalentes — onProximityDown, onProximityUp, onProximityEnter, y onProximityLeave — que siguen el mismo patrón que las funciones descritas en esta página.

Datos de la acción de entrada

Obtén datos de una acción de entrada, como el botón que se pulsó, la entidad que fue alcanzada, la dirección y la longitud del rayo, etc. Consulta (Ver documentación) para obtener 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 basado en System enfoque, ya que esto te permite manejar tantas acciones de entrada diferentes como quieras, y mostrar una sugerencia de feedback al pasar el cursor en la UI para cada botón.

Como alternativa, puedes usar el enfoque Register 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 sugerencia al pasar el cursor 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, incluidas las teclas de movimiento, por lo que debes filtrar solo las acciones que te interesan.