Gamepad API について
■Gamepad API について
Gamepad API は、HTML5 世代の機能です。
http://www.w3.org/TR/gamepad/ (Working Draft)
ゲームパッドの入力情報を取得する事ができます。
ゲームパッドの入力を取得する
■ GamepadList オブジェクトを取得する
navigator.getGamepads() メソッドを使用します。
戻り値から、 GamepadList オブジェクトが得られます。
Navigator.getGamepads() :GamepadList
| 引数 | Void | なし |
| 戻り値 | GamepadList | GamepadList オブジェクトが得られる |
■取得例
ゲームパッドリストを取得する
// ゲームパッドリストを取得する
var gamepad_list = navigator.getGamepads();
// 出力テスト
console.log(gamepad_list);
■ゲームパッドを検出できない場合（セキュリティ）
ページを開いてから、ゲームパッドを一度操作する必要があります。
ユーザーによる押下操作後に、getGamepads() メソッドで取得できるようになります。
■ Google Chrome 112 時点での注意点
getGamepads() メソッドは、毎フレーム実行する必要があります。
■ GamepadList オブジェクトについて
■ Gamepad オブジェクトを取得する
GamepadList オブジェクトは、配列のように中身を取り出せます。
中には、Gamepad オブジェクトが格納されています。
■プレイヤー番号の欠番について
ブラウザによっては、undefined 値が格納されている場合があります。
これは、プレイヤー番号（index 値）の欠番を意味します。
■ Gamepad オブジェクトの総数を取得する
length プロパティを使用します。
得られた総数のゲームパッドが、必ずしも接続されているとは限りません。
欠番が存在する可能性があります。
■取得例
Gamepad オブジェクトを取得する
// getGamepads メソッドに対応している
if(navigator.getGamepads){
// ------------------------------------------------------------
// ゲームパッドリストを取得する
// ------------------------------------------------------------
var gamepad_list = navigator.getGamepads();
// ------------------------------------------------------------
// アイテム総数を取得する
// ------------------------------------------------------------
var num = gamepad_list.length;
// ------------------------------------------------------------
// ゲームパッドを順番に取得する
// ------------------------------------------------------------
var i;
for(i=0;i < num;i++){
// ゲームパッドを取得する（undefined 値の場合もある）
var gamepad = gamepad_list[i];
// 出力テスト
console.log(gamepad);
}
}
■ GamePad オブジェクトについて
■ GamePad のプロパティ一覧
| プロパティ名 | 型 | 説明 |
| id | String | ゲームパッドの識別名。（製品名、製造番号、製造業者など） |
| index | Number | ゲームパッドのインデックス値。（プレイヤー番号に該当） |
| connected | Boolean | ゲームパッドの物理的な接続状態。false に変化すると利用不可能。 |
| mapping | String | ゲームパッドのレイアウトの種類。 |
| buttons | GamepadButtonList | 「ゲームボタン」のリスト。 |
| axes | Array | 「感圧可能なスティックなどの入力強度」のリスト。 |
| timestamp | Number | タイムスタンプ情報。 |
■ゲームパッド情報の更新について
現状では、getGamepads() メソッドを、毎フレーム実行して、最新の GemePad オブジェクトを入手します。（Google Chrome 112 の時点）
■取得例
ゲームパッドの入力情報を出力する
<html>
<body>
<pre id="aaa"></pre>
<script type="text/javascript">
<!--
// 匿名関数を即時実行
(function(){
// ------------------------------------------------------------
// Gemapad API に対応しているか調べる
// ------------------------------------------------------------
if(!(window.Gamepad)) return;
if(!(navigator.getGamepads)) return;
// ------------------------------------------------------------
// "aaa" という ID 属性のエレメントを取得する
// ------------------------------------------------------------
var element = document.getElementById("aaa");
// ------------------------------------------------------------
// 一定時間隔で、繰り返し実行される関数
// ------------------------------------------------------------
setInterval(function(){
var a = new Array();
// ゲームパッドリストを取得する
var gamepad_list = navigator.getGamepads();
// ゲームパッドの総数を取得する
var gamepad_length = gamepad_list.length;
var i;
for(i=0;i < gamepad_length;i++){
// ------------------------------------------------------------
// Gamepad オブジェクトを取得する
// ------------------------------------------------------------
var gamepad = gamepad_list[i];
if(!gamepad) continue;
// ------------------------------------------------------------
// ゲームパッドのインデックス値
// ------------------------------------------------------------
a.push("index: " + gamepad.index);
// ------------------------------------------------------------
// タイムスタンプ情報
// ------------------------------------------------------------
a.push("timestamp: " + gamepad.timestamp);
// ------------------------------------------------------------
// ゲームパッドの識別名
// ------------------------------------------------------------
a.push("id: \"" + gamepad.id + "\"");
// ------------------------------------------------------------
// ゲームパッドの物理的な接続状態
// ------------------------------------------------------------
a.push("connected: " + gamepad.connected);
// ------------------------------------------------------------
// マッピングタイプ情報
// ------------------------------------------------------------
a.push("mapping: \"" + gamepad.mapping + "\"");
// ------------------------------------------------------------
// ボタンリスト
// ------------------------------------------------------------
var buttons = gamepad.buttons;
a.push("buttons: {");
var j;
var n = buttons.length;
for(j=0;j < n;j++){
// GamepadButton オブジェクトを取得
var button = buttons[j];
// ボタン押下状態
var pressed = button.pressed;
// タッチ押下状態
var touched = button.touched;
// ボタン入力強度
var value = button.value;
a.push(" \"" + j + "\": { pressed:" + pressed + " , touched:" + touched + " , value:" + value + " }");
}
a.push("}");
// ------------------------------------------------------------
// 軸リスト
// ------------------------------------------------------------
var axes = gamepad.axes;
a.push("axes: {");
var j;
var n = axes.length;
for(j=0;j < n;j++){
// 軸の入力強度
var axis = axes[j];
a.push(" \"" + j + "\": " + axis);
}
a.push("}");
a.push("\n ----- \n");
}
element.textContent = a.join("\n");
},1000/60);
})();
//-->
</script>
</body>
</html>
■マッピングタイプ情報について（mapping プロパティ）
■レイアウトの種類について
mapping プロパティから、以下の文字列が得られます。
| レイアウト名 | 説明 |
| "standard" | 標準レイアウト |
| "" (空文字) | ベンダー独自レイアウト |
■標準レイアウトである場合
「Xbox 360 コントローラー」と同じキー配置である事が保証されています。
初期配置は、意図通りに機能するでしょう。
■ベンダー独自レイアウトの場合
未知のキー配置であり、仕様は一切不明です。
スティックの個数、ボタン番号の配置などを知る方法はありません。
ゲームパッドによっては、意図しない初期配置となる状況が発生するでしょう。
キーコンフィグを実装しておくと、ユーザー側で対応できるようになります。
■ GamepadButtonList オブジェクトについて（buttons プロパティ）
■ GamepadButton オブジェクトを取得する
GamepadButtonList オブジェクトは、配列のように中身を取り出せます。
中には、GamepadButton オブジェクトが格納されています。
■標準レイアウトのマッピングについて
| 番地 | 説明 |
| 12 | 上ボタン |
| 13 | 下ボタン |
| 14 | 左ボタン |
| 15 | 右ボタン |
| 番地 | 説明 |
| 0 | A ボタン（下段のボタン列） |
| 1 | B ボタン（下段のボタン列） |
| 2 | X ボタン（上段のボタン列） |
| 3 | Y ボタン（上段のボタン列） |
| 4 | L1 ボタン（上段） |
| 5 | R1 ボタン（上段） |
| 6 | L2 ボタン（下段） |
| 7 | R2 ボタン（下段） |
| 番地 | 説明 |
| 8 | SELECT ボタン |
| 9 | START ボタン |
| 10 | 左スティック押込 |
| 11 | 右スティック押込 |
| 16 | 中央ボタン |
■ベンダー独自レイアウトの場合
大抵の場合、A～Z ボタンが、0 番地から割り当てられています。
十字キーボタンに該当する番地を知る方法は無いようです。
ゲームパッドの種類によっては、十字キーボタンの入力結果は、buttons プロパティではなく、axes プロパティの方に出力されます。
■感圧可能なスティックなどの入力強度（axes プロパティ）
■入力強度情報を取得する
アナログスティックなどの入力強度情報が、配列で得られます。
中には、数値データ (-1.0 ～ 1.0) が格納されています。
ゲームパッドの種類によっては、十字キーボタンの入力結果は、ここで得られます。
■標準レイアウトのマッピングについて
| 番地 | 説明 |
| 0 | 左スティックの水平方向（-1.0 ～ +1.0）（負数なら左方向、正数なら右方向） |
| 1 | 左スティックの垂直方向（-1.0 ～ +1.0）（負数なら上方向、正数なら下方向） |
| 2 | 右スティックの水平方向（-1.0 ～ +1.0）（負数なら左方向、正数なら右方向） |
| 3 | 右スティックの垂直方向（-1.0 ～ +1.0）（負数なら上方向、正数なら下方向） |
■ベンダー独自レイアウトの場合
大抵の場合、アナログスティックか十字キーが、以下のように割り当てられています。
| 番地 | 説明 |
| 0 | 水平方向（-1.0 ～ +1.0）（負数なら左方向、正数なら右方向） |
| 1 | 垂直方向（-1.0 ～ +1.0）（負数なら上方向、正数なら下方向） |
他にも、１～３次元的な入力デバイスが存在するかもしれません。
連番でマッピングされていないゲームパッドも存在するようです。
■ GamepadButton オブジェクトについて
■プロパティ一覧
| プロパティ名 | 型 | 説明 |
| pressed | Boolean | ボタンの押下状態。true で押されています。false で離されています。 |
| touched | Boolean | タッチの押下状態。true で押されています。false で離されています。 |
| value | Number | 感圧可能なボタンの入力強度。(0.0 ～ 1.0) |
ゲームパッドの接続状態を監視する
■ゲームパッドの接続状態を監視する
ゲームパッドの接続関連のイベントは、以下の種類があります。
イベントリスナーを使って登録します。
| イベント名 | 型 | 解説 |
| "gamepadconnected" | GamepadEvent | ゲームパッドを接続すると実行されるイベント |
| "gamepaddisconnected" | GamepadEvent | ゲームパッドの接続を解除すると実行されるイベント |
■ゲームパッドを検出できない場合（セキュリティ）
ページを開いてから、ゲームパッドを一度操作する必要があります。
ユーザーによる押下操作後に、gamepadconnected イベントが発行されます。
■ GamepadEvent オブジェクトを取得する
登録したコールバック関数の引数から、GamepadEvent オブジェクトが得られます。
■ Gamepad オブジェクトを取得する
■取得例
ゲームパッドの接続状態を監視する
// GamepadEvent に対応している
if(window.GamepadEvent){
// ------------------------------------------------------------
// ゲームパッドを接続すると実行されるイベント
// ------------------------------------------------------------
window.addEventListener("gamepadconnected",function(e){
console.log("ゲームパッドが接続された");
console.log(e.gamepad);
});
// ------------------------------------------------------------
// ゲームパッドの接続を解除すると実行されるイベント
// ------------------------------------------------------------
window.addEventListener("gamepaddisconnected",function(e){
console.log("ゲームパッドの接続が解除された");
console.log(e.gamepad);
});
}