Introdução
Deixe os novatos usarem os teclados para jogos de aventura, as pontas dos dedos para cortar frutas e os sensores de movimento para fingir que dançam como o Michael Jackson. (Alerta: eles não podem.) Mas você é diferente. Você é melhor. Você é incrível. Para você, os jogos começam e terminam com um gamepad nas mãos.
Mas calma. E se você quiser oferecer suporte a um gamepad no seu app da Web? Nada disso. A nova API Gamepad vem para ajudar, permitindo que você use JavaScript para ler o estado de qualquer controle de gamepad conectado ao computador. Ele é tão recente que só foi lançado no Chrome 21 na semana passada e também está prestes a ser compatível com o Firefox (atualmente disponível em uma versão especial).
Isso acabou sendo um ótimo momento, porque tivemos a chance de usá-lo recentemente no Google Doodle de corrida com obstáculos de 2012. Neste artigo, vamos explicar brevemente como adicionamos a API Gamepad ao Doodle e o que aprendemos durante o processo.
Testador de gamepad
Apesar de serem efêmeros, os doodles interativos costumam ser bastante complexos nos bastidores. Para facilitar a demonstração do que estamos falando, pegamos o código do gamepad do doodle e criamos um testador simples. Você pode usá-lo para conferir se o gamepad USB funciona corretamente e também analisar os bastidores para entender como isso é feito.
Quais navegadores são compatíveis com ele atualmente?
Quais controles podem ser usados?
Em geral, qualquer gamepad moderno que seja compatível com seu sistema de forma nativa deve funcionar. Testamos vários gamepads, desde controles USB de marcas genéricas em um PC até controles do PlayStation 2 conectados por um dongle a um Mac, além de controles Bluetooth pareados com um notebook ChromeOS.
Esta é uma foto de alguns controles que usamos para testar nosso doodle: "Sim, mãe, é isso mesmo que eu faço no trabalho". Se o controle não funcionar ou se os controles estiverem mapeados incorretamente, registre um bug no Chrome ou no Firefox . Teste na versão mais recente de cada navegador para garantir que o problema ainda não foi corrigido.
Detecção de recursos da API Gamepad<
No Chrome:
var gamepadSupportAvailable = !!navigator.webkitGetGamepads || !!navigator.webkitGamepads;
Ainda não parece ser possível detectar isso no Firefox. Tudo é baseado em eventos, e todos os manipuladores de eventos precisam ser anexados à janela, o que impede que uma técnica típica de detecção de manipuladores de eventos funcione.
Mas temos certeza de que isso é temporário. O incrível Modernizr já informa sobre a API Gamepad, então recomendamos que você o use para todas as suas necessidades de detecção atuais e futuras:
var gamepadSupportAvailable = Modernizr.gamepads;
Como descobrir gamepads conectados
Mesmo que você conecte o gamepad, ele não vai se manifestar de forma alguma, a menos que o usuário pressione um dos botões primeiro. Isso é para evitar a identificação por impressão digital, mas é um desafio para a experiência do usuário: não é possível pedir que o usuário pressione o botão ou fornecer instruções específicas para o gamepad, porque você não sabe se ele conectou o controle.
Depois de superar esse obstáculo, você vai encontrar outros.
Enquetes
A implementação da API pelo Chrome expõe uma função, navigator.webkitGetGamepads(), que pode ser usada para receber uma lista de todos os gamepads conectados ao sistema, além do estado atual deles (botões + sticks). O primeiro gamepad conectado será retornado como a primeira entrada na matriz e assim por diante.
Essa chamada de função substituiu recentemente uma matriz que você podia acessar diretamente: navigator.webkitGamepads[]. No início de agosto de 2012, o acesso a essa matriz ainda era necessário no Chrome 21, enquanto a chamada de função funciona no Chrome 22 e em versões mais recentes. No futuro, a chamada de função será a maneira recomendada de usar a API e será disponibilizada gradualmente para todos os navegadores Chrome instalados.
A parte da especificação implementada até agora exige que você verifique continuamente o estado dos gamepads conectados (e compare com o anterior, se necessário), em vez de disparar eventos quando as coisas mudam. Usamos requestAnimationFrame() para configurar a sondagem da maneira mais eficiente e que consumisse menos bateria. Para o doodle, embora já tenhamos um loop requestAnimationFrame() para as animações, criamos um segundo loop completamente separado. Foi mais simples de programar e não deve afetar o desempenho de forma alguma.
Confira o código do testador:
/**
* 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.)
},
Se você só se importa com um gamepad, receber os dados dele pode ser tão simples quanto:
var gamepad = navigator.webkitGetGamepads && navigator.webkitGetGamepads()[0];
Se você quiser ser um pouco mais inteligente ou oferecer suporte a mais de um jogador simultaneamente, será necessário adicionar mais algumas linhas de código para reagir a cenários mais complexos (dois ou mais gamepads conectados, alguns deles sendo desconectados no meio do caminho etc.). Confira o código-fonte do nosso testador, a função pollGamepads(), para ver uma abordagem de como resolver isso.
Eventos
O Firefox usa uma maneira alternativa e melhor descrita na especificação da API Gamepad. Em vez de pedir que você faça uma sondagem, ele expõe dois eventos, MozGamepadConnected e MozGamepadDisconnected, que são acionados sempre que um gamepad é conectado (ou, mais precisamente, conectado e "anunciado" ao pressionar qualquer um dos botões) ou desconectado. O objeto do gamepad que vai continuar refletindo o estado futuro é transmitido como o parâmetro .gamepad do objeto de evento.
No código-fonte do testador:
/**
* 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);
},
Resumo
No final, nossa função de inicialização no testador, que aceita as duas abordagens, fica assim:
/**
* 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();
}
}
},
Informações do gamepad
Cada gamepad conectado ao sistema será representado por um objeto semelhante a este:
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
Informações básicas
Os primeiros campos são metadados simples:
id: uma descrição textual do gamepad.index: um número inteiro útil para diferenciar os gamepads conectados a um computador.timestamp: o carimbo de data/hora da última atualização do estado do botão/eixo (atualmente, só há suporte no Chrome)
Botões e controles
Os gamepads de hoje não são exatamente o que seu avô usava para salvar a princesa no castelo errado. Normalmente, eles têm pelo menos 16 botões separados (alguns discretos, outros analógicos), além de dois controles analógicos. A API Gamepad informa sobre todos os botões e controles analógicos relatados pelo sistema operacional.
Depois de receber o estado atual no objeto do gamepad, você pode acessar os botões pelas matrizes .buttons[] e os controles pelas matrizes .axes[]. Confira um resumo visual do que eles correspondem:
A especificação pede que o navegador mapeie os primeiros 16 botões e quatro eixos para:
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
};
Os botões e eixos extras serão adicionados aos acima. No entanto, não há garantia de que haverá 16 botões ou quatro eixos. Esteja preparado para que alguns deles simplesmente não sejam definidos.
Os botões podem assumir valores de 0,0 (não pressionado) a 1,0 (totalmente pressionado). Os eixos vão de -1,0 (totalmente para a esquerda ou para cima) a 0,0 (centro) e 1,0 (totalmente para a direita ou para baixo).
Analógico ou discreto?
Aparentemente, todos os botões podem ser analógicos. Isso é comum para botões de ombro, por exemplo. Portanto, é melhor definir um limite em vez de apenas comparar com 1,00 (e se um botão analógico estiver um pouco sujo? Talvez nunca chegue a 1,00). No nosso doodle, fazemos assim:
gamepad.ANALOGUE_BUTTON_THRESHOLD = .5;
gamepad.buttonPressed_ = function(pad, buttonId) {
return pad.buttons[buttonId] &&
(pad.buttons[buttonId] > gamepad.ANALOGUE_BUTTON_THRESHOLD);
};
Você pode fazer o mesmo para transformar controles analógicos em digitais. Claro, sempre há o botão direcional (d-pad), mas seu gamepad pode não ter um. Este é o código para lidar com isso:
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;
}
};
Pressionamentos de botões e movimentos de controle
Eventos
Em alguns casos, como em um jogo de simulador de voo, faz mais sentido verificar e reagir continuamente às posições do joystick ou aos botões pressionados… mas e para coisas como o Doodle Hurdles 2012? Você pode se perguntar: por que preciso verificar os botões em cada frame? Por que não consigo receber eventos como faço para o teclado ou o mouse para cima/baixo?
A boa notícia é que sim. A má notícia é que, no futuro, Está na especificação, mas ainda não foi implementado em nenhum navegador.
Enquetes
Enquanto isso, a saída é comparar o estado atual e o anterior e chamar funções se houver alguma diferença. Exemplo:
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);
}
A abordagem que prioriza o teclado no doodle de corrida com obstáculos de 2012
Como o método de entrada preferido do Doodle de hoje é o teclado, decidimos que o gamepad vai emular o teclado de forma bem parecida. Isso significou três decisões:
O Doodle precisa apenas de três botões (dois para correr e um para pular), mas o gamepad provavelmente terá muitos mais. Por isso, mapeamos todos os 16 botões e os dois controles analógicos conhecidos para essas três funções lógicas da maneira que achamos mais adequada. Assim, as pessoas podem correr: alternando os botões A/B, alternando os botões superiores, pressionando para a esquerda/direita no botão direcional ou movendo um dos controles analógicos rapidamente para a esquerda e para a direita (algumas dessas opções serão, é claro, mais eficientes do que as outras). Exemplo:
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),Tratamos cada entrada analógica como discreta, usando as funções de limite descritas anteriormente.
Chegamos ao ponto de conectar a entrada do gamepad ao Doodle, em vez de incorporá-la. Nosso loop de sondagem sintetiza os eventos keydown e keyup necessários (com um keyCode adequado) e os envia de volta ao 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);
E isso é tudo!
Dicas e sugestões
- Lembre-se de que o gamepad não vai ficar visível no navegador antes que um botão seja pressionado.
- Se você estiver testando o gamepad em navegadores diferentes ao mesmo tempo, apenas um deles vai detectar o controle. Se você não estiver recebendo eventos, feche as outras páginas que podem estar usando o recurso. Além disso, pela nossa experiência, às vezes um navegador pode "reter" o controle mesmo que você feche a guia ou o próprio navegador. Às vezes, reiniciar o sistema é a única maneira de corrigir problemas.
- Como sempre, use o Chrome Canary e os equivalentes para outros navegadores para garantir que você tenha o melhor suporte. Depois, aja de forma adequada se as versões mais antigas se comportarem de maneira diferente.
O futuro
Esperamos que isso ajude a esclarecer essa nova API, que ainda é um pouco instável, mas já é muito divertida.
Além das partes que faltam da API (por exemplo, eventos) e de um suporte mais amplo do navegador, também esperamos ver coisas como controle de vibração, acesso a giroscópios integrados etc. E mais suporte para diferentes tipos de gamepads. Registre um bug no Chrome e/ou no Firefox se encontrar um que funcione incorretamente ou não funcione.
Mas antes disso, jogue nosso Doodle de corrida com obstáculos de 2012 e veja como é muito mais divertido com o gamepad. Você disse que consegue fazer em menos de 10, 7 segundos? Pode vir.