HTML5: la API de bloqueo de puntero le permite ocultar el puntero del mouse de la vista

Los navegadores están en camino de convertirse en plataformas de juego completas. Gracias a HTML5 y JavaScript, desarrollar aplicaciones complejas sigue siendo mucho trabajo, pero posible. Sin embargo, algunos conceptos de juego no se basan en punteros de mouse visibles. Especialmente al controlar una aplicación basada en el teclado, un puntero de mouse visible puede resultar molesto. Use la nueva API de bloqueo de puntero para simplemente ocultarlo según sea necesario.

API de bloqueo de puntero: Ocultar y mostrar simple al hacer clic

El método «requestPointerLock()», adjunto a cualquier elemento aleatorio, solicita al navegador que oculte el puntero del mouse. El navegador lo hará, pero no sin ninguna acción por parte del usuario. Eso significa que no puede ocultar el puntero del mouse al cargar la página. En su lugar, utilice el evento «clic» para llamar al método.

document.getElementsByTagName("canvas")[0].addEventListener("click", function() {
  this.requestPointerLock();
}, false);

En nuestro ejemplo, el puntero del mouse se ocultará tan pronto como el usuario haga clic en el elemento „“. Similar al comportamiento del navegador al tratar con la API de pantalla completa, se mostrará una ventana emergente que informa al usuario sobre el intento de la API de bloqueo de puntero de ocultar el puntero del mouse y permite volver a mostrarlo presionando la tecla ESC.

Mientras que el puntero del mouse está desactivado, también conocido como oculto, no se mueve a ningún lado, sino que permanece donde lo dejó por última vez. Cualquier movimiento del mouse no hará que el puntero se mueva en ninguna dirección. Esto incluye la incapacidad de mover el mouse fuera de la ventana del navegador. Los clics del mouse aún se ejecutarán.

Para recuperar la visibilidad del puntero, el método „exitPointerLock()“ es nuestra herramienta preferida. Usado junto con la propiedad „pointerLockElement“, podemos ocultar y mostrar punteros haciendo clic en cualquier elemento asignado a la operación. Tan pronto como el puntero esté oculto, el valor de «pointerLockElement» será el elemento DOM al que apuntó la API. En todos los demás casos el valor será „nulo“. Por ejemplo, «pointerLockElement.nodeName» podríamos consultar el nombre del elemento; en este caso, obtendríamos «CANVAS» como valor.

document.getElementsByTagName("canvas")[0].addEventListener("click", function() {
  if (document.pointerLockElement == null) {
    this.requestPointerLock();
  } else {
    document.exitPointerLock();
  }
}, false);

En este ejemplo comprobamos si „pointerLockElement“ es „null“. De esa manera, verificamos si el puntero del mouse está oculto o se muestra. „requestPointerLock()“ o „exitPointerLock()“ se ejecutan en consecuencia. Aparte de „requestPointerLock()“, „exitPointerLock()“ no requiere ninguna acción del usuario. No tenemos que iniciar el método por cada evento de «clic».

Mientras que „requestPointerLock()“ puede asignarse a elementos aleatorios, „exitPointerLock()“ debe asignarse a „document“. Asegúrese de usar los prefijos apropiados ya que la API de Pointer Lock es bastante nueva: «webkitRequestPointerLock()» y «webkitExitPointerLock()» funcionan.

Pointer Lock API Advanced: detección del movimiento del puntero del mouse

Con la API Pointer Lock obtenemos dos nuevas propiedades para detectar el movimiento del mouse. Lo que ya podíamos hacer hasta ahora era consultar las coordenadas del mouse (dentro de la ventana del navegador) usando las propiedades de evento „clientX“ y „clientY“. Las nuevas propiedades «movimientoX» y «movimientoY» hacen más, detectan el movimiento del puntero del mouse, no solo la posición.

document.addEventListener("mousemove", function(e) {
  document.title = e.clientX + " " + e.movementX;
}

En este ejemplo, dejamos que un evento „mousemove“ inicie una función que escribe los valores recientes para „clientX“ y „movementX“ en el título del documento. Mientras que „clientX“ nos dice la posición en el momento de la consulta, „movementX“ nos dice el movimiento del mouse en el eje x en relación con la última llamada a la función. Cuanto más rápido se mueva el ratón, mayor será el valor de «movimientoX». El movimiento hacia la derecha («movimientoX») y hacia abajo («movimientoY») siempre devolverá un valor numérico positivo, mientras que el movimiento hacia la izquierda y hacia arriba siempre producirá un valor numérico negativo. Si no se detecta movimiento, el valor permanece en cero.

En este caso, los valores para „clienteX“ y „clienteY“ también permanecerían sin cambios. Mantienen los valores que tenían cuando se produjo el evento de desactivación. Las propiedades „movementX“ y „movementY“ no dependen de la API Pointer Lock y también se pueden usar con punteros completamente visibles.

Recuerde prefijar correctamente las nuevas propiedades, por ejemplo, con „webkitMovementX“ y „webkitMovementY“.

Pointer-Lock-API para fugitivos: reacción a cambios de estado y errores

La API Pointer Lock conoce dos detectores de eventos. El primero llamado «cambio de bloqueo de puntero» siempre ejecutará una función en el puntero del mouse que se oculta o se muestra.

document.addEventListener("pointerlockchange", function() {
  if (document.pointerLockElement == null) {
    alert("The mouse pointer is now visible.");
  } else {
    alert("The mouse pointer is now hidden.");
  }
}, false);

Este ejemplo lleva a que se muestre una ventana de diálogo en ambas ocasiones de mostrar y ocultar el puntero. Usando la propiedad «pointerLockElement» detectamos el estado reciente y abrimos el mensaje en consecuencia.

El segundo detector de eventos „pointerlockerror“ nos permite reaccionar a los errores que pueden ocurrir al ocultar o mostrar el puntero del mouse. Como mencioné anteriormente, el navegador solo reaccionará ocultando el puntero siempre que se llame al método „requestPointerLock()“ por evento de „clic“. Llamaríamos a „requestPointerLock()“ por „cargar“, el navegador no reaccionaría escondiéndose, sino que se iniciaría el evento „pointerlockerror“.

document.addEventListener("pointerlockerror", function() {
  alert("I could not hide the mouse pointer.");
}, false);

«pointerlockchange» y «pointerlockerror» escuchan las variantes específicas del proveedor como «webkitpointerlockchange» y «webkitpointerlockerror».

Compatibilidad con navegador

En el momento de escribir este artículo, la API Pointer Lock es compatible con las versiones de escritorio de Chrome y Firefox. Los navegadores móviles no admiten la API en absoluto, ni siquiera las versiones móviles de Chrome y Firefox. Como la API tiene sus puntos fuertes en los juegos, es probable que las personas acepten tener que instalar un navegador determinado para poder jugar ese juego que aman. Si es así, el débil soporte del navegador no sería un gran problema.

(dpe)