JavaScript プログラミング講座

 

Gamepad API について

 


■Gamepad API について

 
Gamepad API は、HTML5 世代の機能です。
 
http://www.w3.org/TR/gamepad/ (Working Draft)
 
ゲームパッドの入力情報を取得する事ができます。
 


 

ゲームパッドの入力を取得する

 
 
 


■ GamepadList オブジェクトを取得する

 
navigator.getGamepads() メソッドを使用します。
 
戻り値から、 GamepadList オブジェクトが得られます。
 
Navigator.getGamepads() :GamepadList
引数 Voidなし
戻り値 GamepadListGamepadList オブジェクトが得られる
 
■取得例
 
ゲームパッドリストを取得する

// ゲームパッドリストを取得する
var gamepad_list = navigator.getGamepads();

// 出力テスト
console.log(gamepad_list);
 
■ゲームパッドを検出できない場合(セキュリティ)
 
ページを開いてから、ゲームパッドを一度操作する必要があります。
 
ユーザーによる押下操作後に、getGamepads() メソッドで取得できるようになります。
 
■ Google Chrome 112 時点での注意点
 
getGamepads() メソッドは、毎フレーム実行する必要があります。
 
Gamepad は、Live なオブジェクトではなくなりました。
 
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 のプロパティ一覧
 
プロパティ名説明
idStringゲームパッドの識別名。(製品名、製造番号、製造業者など)
indexNumberゲームパッドのインデックス値。(プレイヤー番号に該当)
connectedBooleanゲームパッドの物理的な接続状態。false に変化すると利用不可能。
mappingStringゲームパッドのレイアウトの種類。
buttonsGamepadButtonList「ゲームボタン」のリスト。
axesArray「感圧可能なスティックなどの入力強度」のリスト。
timestampNumberタイムスタンプ情報。
 
■ゲームパッド情報の更新について
 
現状では、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右ボタン
 
番地説明
0A ボタン(下段のボタン列)
1B ボタン(下段のボタン列)
2X ボタン(上段のボタン列)
3Y ボタン(上段のボタン列)
4L1 ボタン(上段)
5R1 ボタン(上段)
6L2 ボタン(下段)
7R2 ボタン(下段)
 
番地説明
8SELECT ボタン
9START ボタン
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)(負数なら上方向、正数なら下方向)
 
他にも、1~3次元的な入力デバイスが存在するかもしれません。
 
連番でマッピングされていないゲームパッドも存在するようです。
 

■ GamepadButton オブジェクトについて

 
■プロパティ一覧
 
プロパティ名説明
pressedBooleanボタンの押下状態。true で押されています。false で離されています。
touchedBooleanタッチの押下状態。true で押されています。false で離されています。
valueNumber感圧可能なボタンの入力強度。(0.0 ~ 1.0)
 


 

ゲームパッドの接続状態を監視する

 


■ゲームパッドの接続状態を監視する

 
ゲームパッドの接続関連のイベントは、以下の種類があります。
 
イベントリスナーを使って登録します。
 
イベント名 解説
"gamepadconnected" GamepadEvent ゲームパッドを接続すると実行されるイベント
"gamepaddisconnected" GamepadEvent ゲームパッドの接続を解除すると実行されるイベント
 
■ゲームパッドを検出できない場合(セキュリティ)
 
ページを開いてから、ゲームパッドを一度操作する必要があります。
 
ユーザーによる押下操作後に、gamepadconnected イベントが発行されます。
 
■ GamepadEvent オブジェクトを取得する
 
登録したコールバック関数の引数から、GamepadEvent オブジェクトが得られます。
 
■ Gamepad オブジェクトを取得する
 
GamepadEvent.gamepad プロパティを使用します。
 
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);
	});

}