Supera los obstáculos con la API de Gamepad

Introducción

Deja que los novatos usen sus teclados para los juegos de aventuras, sus preciosas yemas de los dedos multitáctiles para cortar fruta y sus elegantes sensores de movimiento modernos para fingir que pueden bailar como Michael Jackson. (Alerta: No pueden hacerlo). Pero tú eres diferente. Eres mejor. Eres un profesional. Para ti, los juegos comienzan y terminan con un control en tus manos.

Pero espera. ¿No tienes mala suerte si quieres admitir un control de juegos en tu app web? Ya no. La nueva API de Gamepad viene al rescate, ya que te permite usar JavaScript para leer el estado de cualquier control de juegos conectado a tu computadora. Es tan reciente que se lanzó en Chrome 21 la semana pasada y también está a punto de ser compatible con Firefox (actualmente disponible en una compilación especial).

Eso resultó ser un momento bastante bueno, porque tuvimos la oportunidad de usarlo recientemente en el Doodle de Google de Hurdles 2012. En este artículo, se explicará brevemente cómo agregamos la API de Gamepad al doodle y qué aprendimos durante el proceso.

Doodle de Google de la carrera de vallas de 2012
Doodle de Google de Carrera de vallas de 2012

Verificador de controles de juegos

A pesar de ser efímeros, los doodles interactivos suelen ser bastante complejos en su interior. Para que sea más fácil demostrar de qué estamos hablando, tomamos el código del control de juegos del doodle y creamos un verificador de controles de juegos simple. Puedes usarla para ver si tu control de juegos USB funciona correctamente y también para examinar cómo se hace.

¿Qué navegadores lo admiten actualmente?

Browser Support

  • Chrome: 21.
  • Edge: 12.
  • Firefox: 29.
  • Safari: 10.1.

Source

¿Qué controles de juegos se pueden usar?

En general, cualquier control de juegos moderno que sea compatible con tu sistema de forma nativa debería funcionar. Probamos varios controles de juegos, desde controles USB de marcas genéricas en una PC, pasando por controles de PlayStation 2 conectados a través de un adaptador a una Mac, hasta controles Bluetooth vinculados con una Chromebook.

Controles de juegos
Controles de juegos

Esta es una foto de algunos controles que usamos para probar nuestro doodle: "Sí, mamá, eso es lo que hago en el trabajo". Si el control no funciona o si los controles se asignan de forma incorrecta, presenta un error en Chrome o Firefox . (Realiza la prueba en la versión más reciente de cada navegador para asegurarte de que no se haya corregido).

Detección de funciones de la API de Gamepad<

En Chrome:

var gamepadSupportAvailable = !!navigator.webkitGetGamepads || !!navigator.webkitGamepads;

Por el momento, no parece posible detectar esto en Firefox: todo se basa en eventos, y todos los controladores de eventos deben adjuntarse a window, lo que impide que funcione una técnica típica de detección de controladores de eventos.

Pero estamos seguros de que es temporal. La increíble herramienta Modernizr ya te informa sobre la API de Gamepad, por lo que te recomendamos que la uses para todas tus necesidades de detección actuales y futuras:

var gamepadSupportAvailable = Modernizr.gamepads;

Cómo averiguar qué controles de juegos están conectados

Incluso si conectas el control de juegos, no se manifestará de ninguna manera, a menos que el usuario presione primero alguno de sus botones. Esto es para evitar la toma de huellas digitales, aunque resulta un poco difícil para la experiencia del usuario: no puedes pedirle que presione el botón ni que proporcione instrucciones específicas del control de juegos porque no sabes si conectó su control.

Sin embargo, una vez que superes ese obstáculo, te esperan más.

Encuestas

La implementación de la API en Chrome expone una función, navigator.webkitGetGamepads(), que puedes usar para obtener una lista de todos los controles de juegos conectados actualmente al sistema, junto con su estado actual (botones y palancas). El primer control de juegos conectado se devolverá como la primera entrada del array, y así sucesivamente.

(Esta llamada a función reemplazó recientemente un array al que podías acceder directamente: navigator.webkitGamepads[]. A principios de agosto de 2012, todavía era necesario acceder a este array en Chrome 21, mientras que la llamada a función funciona en Chrome 22 y versiones posteriores. En el futuro, la llamada a función será la forma recomendada de usar la API y se extenderá de forma gradual a todos los navegadores Chrome instalados).

La parte de la especificación que se implementó hasta ahora requiere que verifiques continuamente el estado de los controles de juegos conectados (y que lo compares con el anterior si es necesario), en lugar de activar eventos cuando cambian las cosas. Nos basamos en requestAnimationFrame() para configurar el sondeo de la manera más eficiente y que menos batería consuma. En nuestro doodle, aunque ya tenemos un bucle requestAnimationFrame() para admitir animaciones, creamos un segundo bucle completamente independiente, ya que era más sencillo de programar y no debería afectar el rendimiento de ninguna manera.

Este es el código del verificador:

/**
 * Starts a polling loop to check for gamepad state.
 */
startPolling: function() {
    // Don't accidentally start a second loop, man.
    if (!gamepadSupport.ticking) {
    gamepadSupport.ticking = true;
    gamepadSupport.tick();
    }
},

/**
 * Stops a polling loop by setting a flag which will prevent the next
 * requestAnimationFrame() from being scheduled.
 */
stopPolling: function() {
    gamepadSupport.ticking = false;
},

/**
 * A function called with each requestAnimationFrame(). Polls the gamepad
 * status and schedules another poll.
 */
tick: function() {
    gamepadSupport.pollStatus();
    gamepadSupport.scheduleNextTick();
},

scheduleNextTick: function() {
    // Only schedule the next frame if we haven't decided to stop via
    // stopPolling() before.
    if (gamepadSupport.ticking) {
    if (window.requestAnimationFrame) {
        window.requestAnimationFrame(gamepadSupport.tick);
    } else if (window.mozRequestAnimationFrame) {
        window.mozRequestAnimationFrame(gamepadSupport.tick);
    } else if (window.webkitRequestAnimationFrame) {
        window.webkitRequestAnimationFrame(gamepadSupport.tick);
    }
    // Note lack of setTimeout since all the browsers that support
    // Gamepad API are already supporting requestAnimationFrame().
    }
},

/**
 * Checks for the gamepad status. Monitors the necessary data and notices
 * the differences from previous state (buttons for Chrome/Firefox,
 * new connects/disconnects for Chrome). If differences are noticed, asks
 * to update the display accordingly. Should run as close to 60 frames per
 * second as possible.
 */
pollStatus: function() {
    // (Code goes here.)
},

Si solo te interesa un control de juegos, obtener sus datos puede ser tan simple como lo siguiente:

var gamepad = navigator.webkitGetGamepads && navigator.webkitGetGamepads()[0];

Si quieres ser un poco más inteligente o admitir más de un jugador de forma simultánea, deberás agregar algunas líneas de código más para reaccionar ante situaciones más complejas (dos o más controles de juegos conectados, algunos de ellos desconectados a mitad de camino, etcétera). Puedes consultar el código fuente de nuestro verificador, la función pollGamepads(), para ver un enfoque de cómo resolver esto.

Eventos

Firefox usa una forma alternativa y mejor que se describe en la especificación de la API de Gamepad. En lugar de pedirte que realices un sondeo, expone dos eventos, MozGamepadConnected y MozGamepadDisconnected, que se activan cada vez que se conecta un control de juegos (o, más precisamente, se conecta y se "anuncia" presionando cualquiera de sus botones) o se desconecta. El objeto de control de juegos que seguirá reflejando su estado futuro se pasa como el parámetro .gamepad del objeto de evento.

En el código fuente del verificador, haz lo siguiente:

/**
 * React to the gamepad being connected. Today, this will only be executed
 * on Firefox.
 */
onGamepadConnect: function(event) {
    // Add the new gamepad on the list of gamepads to look after.
    gamepadSupport.gamepads.push(event.gamepad);

    // Start the polling loop to monitor button changes.
    gamepadSupport.startPolling();

    // Ask the tester to update the screen to show more gamepads.
    tester.updateGamepads(gamepadSupport.gamepads);
},

Resumen

Al final, nuestra función de inicialización en el verificador, que admite ambos enfoques, se ve de la siguiente manera:

/**
 * Initialize support for Gamepad API.
 */
init: function() {
    // As of writing, it seems impossible to detect Gamepad API support
    // in Firefox, hence we need to hardcode it in the third clause.
    // (The preceding two clauses are for Chrome.)
    var gamepadSupportAvailable = !!navigator.webkitGetGamepads ||
        !!navigator.webkitGamepads ||
        (navigator.userAgent.indexOf('Firefox/') != -1);

    if (!gamepadSupportAvailable) {
    // It doesn't seem Gamepad API is available – show a message telling
    // the visitor about it.
    tester.showNotSupported();
    } else {
    // Firefox supports the connect/disconnect event, so we attach event
    // handlers to those.
    window.addEventListener('MozGamepadConnected',
                            gamepadSupport.onGamepadConnect, false);
    window.addEventListener('MozGamepadDisconnected',
                            gamepadSupport.onGamepadDisconnect, false);

    // Since Chrome only supports polling, we initiate polling loop straight
    // away. For Firefox, we will only do it if we get a connect event.
    if (!!navigator.webkitGamepads || !!navigator.webkitGetGamepads) {
        gamepadSupport.startPolling();
    }
    }
},

Información del control de juegos

Cada control de juegos conectado al sistema se representará con un objeto similar al siguiente:

id: "PLAYSTATION(R)3 Controller (STANDARD GAMEPAD Vendor: 054c Product: 0268)"
index: 1
timestamp: 18395424738498
buttons: Array[8]
    0: 0
    1: 0
    2: 1
    3: 0
    4: 0
    5: 0
    6: 0.03291
    7: 0
axes: Array[4]
    0: -0.01176
    1: 0.01961
    2: -0.00392
    3: -0.01176

Información básica

Los primeros campos son metadatos simples:

  • id: Es una descripción textual del control de juegos.
  • index: Es un número entero que sirve para distinguir los diferentes controles de juegos conectados a una computadora.
  • timestamp: Es la marca de tiempo de la última actualización del estado del botón o los ejes (actualmente, solo se admite en Chrome).

Botones y palancas

Los controles de juegos actuales no son exactamente lo que tu abuelo podría haber usado para salvar a la princesa en el castillo equivocado: suelen tener al menos dieciséis botones separados (algunos discretos, otros analógicos), además de dos palancas analógicas. La API de Gamepad te informará sobre todos los botones y palancas analógicas que informa el sistema operativo.

Una vez que obtengas el estado actual en el objeto del control de juegos, podrás acceder a los botones a través de los arrays .buttons[] y a los sticks a través de los arrays .axes[]. Aquí tienes un resumen visual de lo que corresponde a cada uno:

Diagrama del control de juegos
Diagrama de un control de juegos

La especificación le pide al navegador que asigne los primeros dieciséis botones y cuatro ejes a lo siguiente:

gamepad.BUTTONS = {
    FACE_1: 0, // Face (main) buttons
    FACE_2: 1,
    FACE_3: 2,
    FACE_4: 3,
    LEFT_SHOULDER: 4, // Top shoulder buttons
    RIGHT_SHOULDER: 5,
    LEFT_SHOULDER_BOTTOM: 6, // Bottom shoulder buttons
    RIGHT_SHOULDER_BOTTOM: 7,
    SELECT: 8,
    START: 9,
    LEFT_ANALOGUE_STICK: 10, // Analogue sticks (if depressible)
    RIGHT_ANALOGUE_STICK: 11,
    PAD_TOP: 12, // Directional (discrete) pad
    PAD_BOTTOM: 13,
    PAD_LEFT: 14,
    PAD_RIGHT: 15
};

gamepad.AXES = {
    LEFT_ANALOGUE_HOR: 0,
    LEFT_ANALOGUE_VERT: 1,
    RIGHT_ANALOGUE_HOR: 2,
    RIGHT_ANALOGUE_VERT: 3
};

Los botones y ejes adicionales se agregarán a los anteriores. Sin embargo, ten en cuenta que no se garantiza que haya dieciséis botones ni cuatro ejes; prepárate para que algunos de ellos simplemente no estén definidos.

Los botones pueden tomar valores de 0.0 (sin presionar) a 1.0 (presionado por completo). Los ejes van de -1.0 (completamente a la izquierda o hacia arriba) a 0.0 (centro) y a 1.0 (completamente a la derecha o hacia abajo).

¿Analógico o discreto?

En teoría, todos los botones podrían ser analógicos, lo que es bastante común para los botones superiores, por ejemplo. Por lo tanto, es mejor establecer un umbral en lugar de compararlo directamente con 1.00 (¿qué pasa si un botón analógico está un poco sucio? Es posible que nunca llegue a 1.00). En nuestro doodle, lo hacemos de esta manera:

gamepad.ANALOGUE_BUTTON_THRESHOLD = .5;

gamepad.buttonPressed_ = function(pad, buttonId) {
    return pad.buttons[buttonId] &&
            (pad.buttons[buttonId] > gamepad.ANALOGUE_BUTTON_THRESHOLD);
};

Puedes hacer lo mismo para convertir los sticks analógicos en joysticks digitales. Por supuesto, siempre está el pad digital (pad direccional), pero es posible que tu control de juegos no tenga uno. Este es nuestro código para controlar eso:

gamepad.AXIS_THRESHOLD = .75;

gamepad.stickMoved_ = function(pad, axisId, negativeDirection) {
    if (typeof pad.axes[axisId] == 'undefined') {
    return false;
    } else if (negativeDirection) {
    return pad.axes[axisId] < -gamepad.AXIS_THRESHOLD;
    } else {
    return pad.axes[axisId] > gamepad.AXIS_THRESHOLD;
    }
};

Presiones de botones y movimientos de palancas

Eventos

En algunos casos, como un juego de simulador de vuelo, tiene más sentido verificar y reaccionar continuamente a las posiciones de la palanca o a las pulsaciones de botones, pero ¿qué pasa con juegos como el doodle de Hurdles 2012? Quizás te preguntes por qué necesitas verificar los botones en cada fotograma. ¿Por qué no puedo obtener eventos como lo hago con el teclado o el mouse hacia arriba o abajo?

La buena noticia es que puedes hacerlo. La mala noticia es que, en el futuro, Está en la especificación, pero aún no se implementó en ningún navegador.

Encuestas

Mientras tanto, la solución es comparar el estado actual y el anterior, y llamar a funciones si ves alguna diferencia. Por ejemplo:

if (buttonPressed(pad, 0) != buttonPressed(oldPad, 0)) {
    buttonEvent(0, buttonPressed(pad, 0) ? 'down' : 'up');
}
for (var i in gamepadSupport.gamepads) {
    var gamepad = gamepadSupport.gamepads[i];

    // Don't do anything if the current timestamp is the same as previous
    // one, which means that the state of the gamepad hasn't changed.
    // This is only supported by Chrome right now, so the first check
    // makes sure we're not doing anything if the timestamps are empty
    // or undefined.
    if (gamepadSupport.prevTimestamps[i] &&
        (gamepad.timestamp == gamepadSupport.prevTimestamps[i])) {
    continue;
    }
    gamepadSupport.prevTimestamps[i] = gamepad.timestamp;

    gamepadSupport.updateDisplay(i);
}

El enfoque centrado en el teclado en el doodle de Hurdles 2012

Dado que, sin un control de juegos, el método de entrada preferido del doodle de hoy es el teclado, decidimos que el control de juegos lo emulara de forma bastante similar. Esto implicó tomar tres decisiones:

  1. El doodle solo necesita tres botones (dos para correr y uno para saltar), pero es probable que el control de juegos tenga muchos más. Por lo tanto, asignamos los dieciséis botones conocidos y los dos sticks conocidos a esas tres funciones lógicas de la manera que nos pareció más lógica, para que las personas pudieran correr alternando los botones A/B, alternando los botones superiores, presionando izquierda/derecha en el pad direccional o moviendo cualquiera de los sticks con fuerza hacia la izquierda y la derecha (algunas de esas opciones, por supuesto, serán más eficientes que las otras). Por ejemplo:

    newState[gamepad.STATES.LEFT] =
        gamepad.buttonPressed_(pad, gamepad.BUTTONS.PAD_LEFT) ||
        gamepad.stickMoved_(pad, gamepad.AXES.LEFT_ANALOGUE_HOR, true) ||
        gamepad.stickMoved_(pad, gamepad.AXES.RIGHT_ANALOGUE_HOR, true),
    
    newState[gamepad.STATES.PRIMARY_BUTTON] =
        gamepad.buttonPressed_(pad, gamepad.BUTTONS.FACE_1) ||
        gamepad.buttonPressed_(pad, gamepad.BUTTONS.LEFT_SHOULDER) ||
        gamepad.buttonPressed_(pad, gamepad.BUTTONS.LEFT_SHOULDER_BOTTOM) ||
        gamepad.buttonPressed_(pad, gamepad.BUTTONS.SELECT) ||
        gamepad.buttonPressed_(pad, gamepad.BUTTONS.START) ||
        gamepad.buttonPressed_(pad, gamepad.BUTTONS.LEFT_ANALOGUE_STICK),
    
  2. Tratamos cada entrada analógica como una discreta, usando las funciones de umbral descritas anteriormente.

  3. Llegamos al punto de conectar la entrada del control de juegos al doodle, en lugar de integrarla. Nuestro bucle de sondeo sintetiza los eventos keydown y keyup necesarios (con un keyCode adecuado) y los envía de vuelta al DOM:

    // Create and dispatch a corresponding key event.
    var event = document.createEvent('Event');
    var eventName = down ? 'keydown' : 'keyup';
    event.initEvent(eventName, true, true);
    event.keyCode = gamepad.stateToKeyCodeMap_[state];
    gamepad.containerElement_.dispatchEvent(event);

Eso es todo.

Sugerencias y trucos

  • Recuerda que el control de juegos no será visible en tu navegador antes de que se presione un botón.
  • Si estás probando el control de juegos en diferentes navegadores de forma simultánea, ten en cuenta que solo uno de ellos puede detectar el control. Si no recibes ningún evento, asegúrate de cerrar las otras páginas que podrían estar usándolo. Además, según nuestra experiencia, a veces un navegador puede "retener" el control de juegos incluso si cierras la pestaña o sales del navegador. A veces, reiniciar el sistema es la única forma de solucionar los problemas.
  • Como siempre, usa Chrome Canary y los equivalentes para otros navegadores para asegurarte de tener la mejor compatibilidad y, luego, actúa de forma adecuada si ves que las versiones anteriores se comportan de manera diferente.

El futuro

Esperamos que esto ayude a aclarar un poco esta nueva API, que aún es un poco precaria, pero ya es muy divertida.

Además de las partes faltantes de la API (p. ej., eventos) y una mayor compatibilidad con navegadores, también esperamos ver cosas como el control de vibración, el acceso a giroscopios integrados, etc. Además, esperamos ver más compatibilidad con diferentes tipos de controles de juegos. Informa un error en Chrome o en Firefox si encuentras uno que no funciona correctamente o que no funciona en absoluto.

Pero antes, juega con nuestro doodle de Carrera de vallas 2012 y descubre cuánto más divertido es con el control de juegos. ¿Acabas de decir que podrías hacerlo mejor que 10.7 segundos? ¡Adelante!

Lecturas adicionales