運用 Gamepad API 突破瓶頸

Marcin Wichary
Marcin Wichary

簡介

讓新手繼續用鍵盤玩冒險遊戲、用寶貴的多點觸控指尖切水果,以及用新奇的動作感應器假裝自己能像麥可傑克森一樣跳舞。(快訊:他們無法這麼做)。但你與眾不同。你比較厲害。您是專業人員。對你來說,遊戲的起點和終點,都與手中的遊戲手把息息相關。

不過,等等。如果想在網頁應用程式中支援遊戲手把,是不是就沒辦法了?答案是不需要。全新的 Gamepad API 可解決這個問題,讓您使用 JavaScript 讀取連接到電腦的任何遊戲手把控制器狀態。這項功能才剛推出,上週才在 Chrome 21 中上線,而且 Firefox 也即將支援 (目前可在特殊版本中使用)。

這項功能推出的時機恰到好處,因為我們最近在 2012 年跨欄 Google Doodle 中有機會用到。本文將簡要說明我們如何將 Gamepad API 新增至塗鴉,以及我們在過程中學到的內容。

2012 年跨欄 Google Doodle
2012 年跨欄 Google Doodle

遊戲手把測試工具

互動式塗鴉雖然只會短暫出現,但背後往往相當複雜。為了更輕鬆地示範我們討論的內容,我們從 Doodle 中擷取遊戲手把程式碼,並整合出一個簡單的遊戲手把測試工具。你可以用來查看 USB 遊戲手把是否正常運作,也可以深入瞭解運作方式。

目前有哪些瀏覽器支援這項功能?

Browser Support

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

Source

可以使用哪些遊戲手把?

一般來說,只要是系統原生支援的新式遊戲手把,應該都能使用。我們測試了各種遊戲手把,包括 PC 上的非品牌 USB 控制器、透過轉接器連接 Mac 的 PlayStation 2 遊戲手把,以及與 ChromeOS 筆電配對的藍牙控制器。

遊戲手把
遊戲手把

這張相片是我們用來測試塗鴉的控制器,我媽看到後說:「沒錯,這就是我工作時會做的事。」如果控制器無法運作,或控制項對應錯誤,請向 Chrome 或 Firefox 回報錯誤。(請在各瀏覽器的最新版本中測試,確認問題尚未修正)。

偵測 Gamepad API 功能

使用 Chrome:

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

目前似乎無法在 Firefox 中偵測到這一點,因為所有內容都是以事件為基礎,且所有事件處理常式都必須附加至視窗,這會導致偵測事件處理常式的典型技術無法運作。

但我們相信這只是暫時的。Modernizr 已經提供 Gamepad API 的相關資訊,因此建議您使用這項工具,滿足目前和未來的偵測需求:

var gamepadSupportAvailable = Modernizr.gamepads;

瞭解已連結的遊戲手把

即使連接遊戲手把,除非使用者先按下任何按鈕,否則不會以任何方式顯示。這是為了防止指紋採集,但對使用者體驗來說,這會造成一些挑戰:您無法要求使用者按下按鈕或提供遊戲手把專屬的操作說明,因為您不知道他們是否已連接控制器。

不過,克服這個障礙後 (抱歉…),還有更多挑戰等著你。

意見調查

Chrome 的 API 實作會公開 navigator.webkitGetGamepads() 函式,可用於取得目前插入系統的所有遊戲手把清單,以及其目前狀態 (按鈕 + 搖桿)。第一個連線的遊戲手把會以陣列中的第一個項目傳回,以此類推。

(這個函式呼叫最近才取代了可直接存取的陣列 navigator.webkitGamepads[]。截至 2012 年 8 月初,Chrome 21 仍須存取這個陣列,而函式呼叫則適用於 Chrome 22 以上版本。日後建議使用函式呼叫來使用 API,這項功能會逐步推廣到所有已安裝的 Chrome 瀏覽器。

目前實作的規格部分要求您持續檢查已連結遊戲手把的狀態 (並在必要時與先前的狀態比較),而不是在發生變更時觸發事件。我們使用 requestAnimationFrame(),以最有效率且省電的方式設定輪詢。雖然 Doodle 已有 requestAnimationFrame() 迴圈支援動畫,但我們還是建立了第二個完全獨立的迴圈,這樣編寫程式碼比較簡單,而且不會影響效能。

以下是測試人員提供的程式碼:

/**
 * 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.)
},

如果您只關心一個遊戲手把,取得其資料可能很簡單:

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

如果想更聰明地處理,或同時支援多位玩家,則需要多加幾行程式碼,以因應更複雜的情況 (例如連接兩個以上的遊戲手把、部分手把在途中中斷連線等)。您可以查看測試工具的原始碼 (函式 pollGamepads()),瞭解如何解決這個問題。

事件

Firefox 採用 Gamepad API 規格中描述的另一種更佳方式。它不會要求您輪詢,而是會公開兩個事件:MozGamepadConnected 和 MozGamepadDisconnected,每當遊戲手把插入 (或更精確地說,插入並透過按下任何按鈕「宣告」) 或拔除時,就會觸發這兩個事件。遊戲手把物件會持續反映未來狀態,並做為事件物件的 .gamepad 參數傳遞。

測試工具原始碼:

/**
 * 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);
},

摘要

最後,測試器中的初始化函式 (支援兩種方法) 如下所示:

/**
 * 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();
    }
    }
},

遊戲手把資訊

每個連接到系統的遊戲手把都會以類似下列的物件表示:

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

基本資訊

前幾個欄位是簡單的中繼資料:

  • id:遊戲手把的文字說明
  • index:整數,可用來區分連接到同一部電腦的不同遊戲手把
  • timestamp:按鈕/軸狀態上次更新的時間戳記 (目前僅 Chrome 支援)

按鈕和搖桿

現在的遊戲手把與以前大不相同,除了兩個類比搖桿外,通常至少有十六個獨立按鈕 (部分為離散按鈕,部分為類比按鈕)。Gamepad API 會顯示作業系統回報的所有按鈕和類比搖桿。

取得遊戲手把物件的目前狀態後,您就可以透過 .buttons[] 存取按鈕,並透過 .axes[] 陣列存取搖桿。以下是這些項目對應的視覺摘要:

遊戲手把圖表
遊戲手把圖表

規格要求瀏覽器將前十六個按鈕和四個軸對應至:

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
};

額外的按鈕和軸會附加到上述按鈕和軸。不過請注意,不一定會有 16 個按鈕或 4 個軸,有些可能只是未定義。

按鈕的值介於 0.0 (未按下) 到 1.0 (完全按下) 之間。軸的值介於 -1.0 (完全向左或向上) 到 1.0 (完全向右或向下) 之間,0.0 代表置中。

類比或離散?

表面上,每個按鈕都可以是類比按鈕,例如肩部按鈕。因此,最好設定門檻,而不是直接與 1.00 比較 (如果類比按鈕剛好有點髒,該怎麼辦?可能永遠不會達到 1.00)。在 Doodle 中,我們是這樣做的:

gamepad.ANALOGUE_BUTTON_THRESHOLD = .5;

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

你也可以用同樣的方式,將類比搖桿轉換成數位搖桿。當然,你也可以使用數位方向鍵 (D-pad),但你的遊戲手把可能沒有這項功能。以下是處理這項作業的程式碼:

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;
    }
};

按鈕和搖桿動作

事件

在某些情況下,例如飛行模擬模式遊戲,持續檢查並回應搖桿位置或按鈕按壓動作會更合理…但對於像 2012 年跨欄塗鴉這樣的遊戲呢?您可能會想:為什麼我需要檢查每個影格的按鈕?為什麼我無法像鍵盤或滑鼠向上/向下那樣取得事件?

好消息是,您可以這麼做。壞消息是,這在未來才會發生。這項功能已列入規格,但尚未在任何瀏覽器中實作。

意見調查

在此期間,您可以比較目前和先前的狀態,並在發現任何差異時呼叫函式。例如:

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);
}

2012 年跨欄 Doodle 的鍵盤優先做法

由於沒有遊戲手把,今天 Doodle 的首選輸入法是鍵盤,因此我們決定讓遊戲手把盡可能模擬鍵盤。這代表我們需要做出三個決定:

  1. Doodle 只需要三個按鈕,兩個用於跑步,一個用於跳躍,但遊戲手把可能會有更多按鈕。因此,我們將所有十六個已知按鈕和兩個已知搖桿對應到這三個邏輯功能,並以我們認為最合理的方式進行,這樣人們就可以透過以下方式跑步:交替 A/B 按鈕、交替肩部按鈕、按下 D-Pad 上的左/右,或左右劇烈擺動任一搖桿(當然,其中一些會比其他更有效率)。例如:

    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. 我們使用上述門檻函式,將每個類比輸入視為離散輸入。

  3. 我們甚至將遊戲手把輸入功能附加到塗鴉上,而不是直接內建,輪詢迴圈實際上會合成必要的 keydown 和 keyup 事件 (包含適當的 keyCode),並傳回 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);

這樣就大功告成了!

提示與祕訣

  • 請注意,在按下按鈕前,瀏覽器不會顯示遊戲手把。
  • 如果同時在不同瀏覽器測試遊戲手把,請注意,只有其中一個瀏覽器能感應到控制器。如果沒有收到任何事件,請務必關閉可能正在使用該事件的其他網頁。此外,根據我們的經驗,有時即使關閉分頁或退出瀏覽器,瀏覽器仍會「保留」遊戲手把。有時重新啟動系統是唯一的解決方法。
  • 一如往常,請使用 Chrome Canary 和其他瀏覽器的對等版本,確保獲得最佳支援,並在發現舊版行為不同時採取適當行動。

未來

希望這篇文章能幫助您瞭解這個新 API。雖然這個 API 仍不穩定,但已經很有趣了。

除了 API 缺少的部分 (例如事件) 和更廣泛的瀏覽器支援外,我們也希望最終能看到震動控制、存取內建陀螺儀等功能。此外,我們也希望支援更多不同類型的遊戲手把。如果您發現有遊戲手把無法正常運作或完全無法運作,請回報 Chrome 錯誤和/或回報 Firefox 錯誤。

不過,在此之前,請先試玩我們的 2012 年跨欄塗鴉,看看使用遊戲手把玩起來有多好玩。噢,你剛才說你可以跑得比 10.7 秒更快嗎?放馬過來吧!

延伸閱讀