path: root/files/ko/web/api/gamepad_api/using_the_gamepad_api/index.html

---
title: Using the Gamepad API
slug: Web/API/Gamepad_API/Using_the_Gamepad_API
translation_of: Web/API/Gamepad_API/Using_the_Gamepad_API
---
<p><span class="seoSummary">HTML5 introduced many of the necessary components for rich, interactive game development. Technologies like <code>&lt;canvas&gt;</code>, WebGL, <code>&lt;audio&gt;</code>, and <code>&lt;video&gt;</code>, along with JavaScript implementations, have matured to the point where they can now support many tasks previously requiring native code. The Gamepad API is a way for developers and designers to access and use gamepads and other game controllers.</span></p>

<p>The <a href="/en-US/docs/Web/API/Gamepad_API">Gamepad API</a> introduces new events on the {{ domxref("Window") }} object for reading gamepad and controller (hereby referred to as <em>gamepad</em>) state. In addition to these events, the API also adds a {{ domxref("Gamepad") }} object, which you can use to query the state of a connected gamepad, and a {{ domxref("navigator.getGamepads()") }} method which you can use to get a list of gamepads known to the page.</p>

<h2 id="conntecting" name="conntecting">게임패드로 연결</h2>

<p>새로운 게임패드가 컴퓨터에 연결될 때, 포커스된 페이지는 {{ event("gamepadconnected") }} 이벤트를 받습니다. 페이지가 로드되었을 때 게임패드가 이미 연결되어 있다면, {{ event("gamepadconnected") }} 이벤트가 유저의 버튼 입력 혹은 마우스 움직일 때 포커스된 페이지에 디스패치됩니다.</p>

<div class="blockIndicator geckoVersionNote">
<p>In Firefox, gamepads are only exposed to a page when the user interacts with one with the page visible. This helps prevent gamepads being used for fingerprinting the user. Once one gamepad has been interacted with, other gamepads that are connected will automatically be visible.</p>
</div>

<p>{{event("gamepadconnected")}} 이벤트를 이렇게 이용할 수 있습니다:</p>

<pre class="brush: js;">window.addEventListener("gamepadconnected", function(e) {
  console.log("Gamepad connected at index %d: %s. %d buttons, %d axes.",
    e.gamepad.index, e.gamepad.id,
    e.gamepad.buttons.length, e.gamepad.axes.length);
});
</pre>

<p>각 게임패드는 유니크한 ID와 연관되어 있는데, 이는 {{domxref("GamepadEvent.gamepad", "gamepad")}} 이벤트의 속성에서 사용가능합니다.</p>

<h2 id="disconnecting" name="disconnecting">게임패드 연결해제</h2>

<p>When a gamepad is disconnected, and if a page has previously received data for that gamepad (e.g. {{ event("gamepadconnected") }}), a second event is dispatched to the focused window, {{ event("gamepaddisconnected") }}:</p>

<pre class="brush: js">window.addEventListener("gamepaddisconnected", function(e) {
  console.log("Gamepad disconnected from index %d: %s",
    e.gamepad.index, e.gamepad.id);
});</pre>

<p>The gamepad's {{domxref("Gamepad.index", "index")}} property will be unique per-device connected to the system, even if multiple controllers of the same type are used. The <code>index</code> property also functions as the index into the {{jsxref("Array")}} returned by {{ domxref("Navigator.getGamepads()") }}.</p>

<pre class="brush: js">var gamepads = {};

function gamepadHandler(event, connecting) {
  var gamepad = event.gamepad;
  // Note:
  // gamepad === navigator.getGamepads()[gamepad.index]

  if (connecting) {
    gamepads[gamepad.index] = gamepad;
  } else {
    delete gamepads[gamepad.index];
  }
}

window.addEventListener("gamepadconnected", function(e) { gamepadHandler(e, true); }, false);
window.addEventListener("gamepaddisconnected", function(e) { gamepadHandler(e, false); }, false);
</pre>

<p>This previous example also demonstrates how the <code>gamepad</code> property can be held after the event has completed — a technique we will use for device state querying later.</p>

<h2 id="querying" name="querying">게임패드 오브젝트에 질의</h2>

<p>As you can see, the <strong>gamepad</strong> events discussed above include a <code>gamepad</code> property on the event object, which returns a {{ domxref("Gamepad") }} object. We can use this in order to determine which gamepad (i.e., its ID) had caused the event, since multiple gamepads might be connected at once. We can do much more with the {{ domxref("Gamepad") }} object, including holding a reference to it and querying it to find out which buttons and axes are being pressed at any one time. Doing so is often desirable for games or other interactive web pages that need to know the state of a gamepad now vs. the next time an event fires.</p>

<p>Performing such checks tends to involve using the {{ domxref("Gamepad") }} object in conjunction with an animation loop (e.g., {{ domxref("Window.requestAnimationFrame","requestAnimationFrame") }}), where developers want to make decisions for the current frame based on the state of the gamepad or gamepads.</p>

<p>The {{domxref("Navigator.getGamepads()")}} method returns an array of all devices currently visible to the webpage, as {{ domxref("Gamepad") }} objects (the first value is always <code>null</code>, so <code>null</code> will be returned if there are no gamepads connected.) This can then be used to get the same information. For example, the first code example above you be rewritten as shown below:</p>

<pre class="brush: js">window.addEventListener("gamepadconnected", function(e) {
  var gp = navigator.getGamepads()[e.gamepad.index];
  console.log("Gamepad connected at index %d: %s. %d buttons, %d axes.",
    gp.index, gp.id,
    gp.buttons.length, gp.axes.length);
});</pre>

<p>The {{ domxref("Gamepad") }} object's properties are as follows:</p>

<ul>
 <li><code>id</code>: A string containing some information about the controller. This is not strictly specified, but in Firefox it will contain three pieces of information separated by dashes (<code>-</code>): two 4-digit hexadecimal strings containing the USB vendor and product id of the controller, and the name of the controller as provided by the driver. This information is intended to allow you to find a mapping for the controls on the device as well as display useful feedback to the user.</li>
 <li><code>index</code>: An integer that is unique for each gamepad currently connected to the system. This can be used to distinguish multiple controllers. Note that disconnecting a device and then connecting a new device may reuse the previous index.</li>
 <li><code>mapping</code>: A string indicating whether the browser has remapped the controls on the device to a known layout. Currently there is only one supported known layout — the <a href="https://dvcs.w3.org/hg/gamepad/raw-file/default/gamepad.html#remapping">standard gamepad</a>. If the browser is able to map controls on the device to that layout the <code>mapping</code> property will be set to the string <code>standard</code>.</li>
 <li><code>connected</code>: A boolean indicating whether the gamepad is still connected to the system. If this is so the value is <code>True</code>; if not, it is <code>False</code>.</li>
 <li><code>buttons</code>: An array of {{ domxref("GamepadButton") }} objects representing the buttons present on the device. Each {{ domxref("GamepadButton") }} has a <code>pressed</code> and a <code>value</code> property:
  <ul>
   <li>The <code>pressed</code> property is a boolean indicating whether the button is currently pressed (<code>true</code>) or unpressed (<code>false</code>).</li>
   <li>The <code>value</code> property is a floating point value used to enable representing analog buttons, such as the triggers on many modern gamepads. The values are normalized to the range 0.0..1.0, with 0.0 representing a button that is not pressed, and 1.0 representing a button that is fully pressed.</li>
  </ul>
 </li>
 <li><code>axes</code>: An array representing the controls with axes present on the device (e.g. analog thumb sticks). Each entry in the array is a floating point value in the range -1.0 - 1.0, representing the axis position from the lowest value (-1.0) to the highest value (1.0).</li>
 <li><code>timestamp</code>: This returns a {{ domxref("DOMHighResTimeStamp") }} representing the last time the data for this gamepad was updated, allowing developers to determine if the <code>axes</code> and <code>button</code> data have been updated from the hardware. The value must be relative to the <code>navigationStart</code> attribute of the {{ domxref("PerformanceTiming") }} interface. Values are monotonically increasing, meaning that they can be compared to determine the ordering of updates, as newer values will always be greater than or equal to older values. Note that this property is not currently supported in Firefox.</li>
</ul>

<div class="blockIndicator note">
<p><strong>Note</strong>: The Gamepad object is available on the {{ event("gamepadconnected") }} event rather than the {{ domxref("Window") }} object itself, for security reasons. Once we have a reference to it, we can query its properties for information about the current state of the gamepad. Behind the scenes, this object will be updated every time the gamepad's state changes.</p>
</div>

<h3 id="버튼_정보_이용하기">버튼 정보 이용하기</h3>

<p>Let's look at a simple example that displays connection information for one gamepad (it ignores subsequent gamepad connections) and allows you to move a ball around the screen using the four gamepad buttons on the right hand side of the gamepad. You can <a href="http://chrisdavidmills.github.io/gamepad-buttons/">view the demo live</a>, and <a href="https://github.com/chrisdavidmills/gamepad-buttons/tree/master">find the source code</a> on Github.</p>

<p>To start with, we declare some variables: The <code>gamepadInfo</code> paragraph that the connection info is written into, the <code>ball</code> that we want to move, the <code>start</code> variable that acts as the ID for <code>requestAnimation Frame</code>, the <code>a</code> and <code>b</code> variables that act as position modifiers for moving the ball, and the shorthand variables that will be used for the {{ domxref("Window.requestAnimationFrame", "requestAnimationFrame()") }} and {{ domxref("Window.cancelAnimationFrame", "cancelAnimationFrame()") }} cross browser forks.</p>

<pre class="brush: js">var gamepadInfo = document.getElementById("gamepad-info");
var ball = document.getElementById("ball");
var start;
var a = 0;
var b = 0;
</pre>

<p>Next we use the {{event("gamepadconnected")}} event to check for a gamepad being connected. When one is connected, we grab the gamepad using {{ domxref("Navigator.getGamepads()") }}<code>[0]</code>, print information about the gamepad into our gamepad info <code>div</code>, and fire the <code>gameLoop()</code> function that starts the whole ball movement process up.</p>

<pre class="brush: js">window.addEventListener("gamepadconnected", function(e) {
  var gp = navigator.getGamepads()[e.gamepad.index];
  gamepadInfo.innerHTML = "Gamepad connected at index " + gp.index + ": " + gp.id + ". It has " + gp.buttons.length + " buttons and " + gp.axes.length + " axes.";

  gameLoop();
});</pre>

<p>Now we use the {{Event("gamepaddisconnected")}} event to check if the gamepad is disconnected again. If so, we stop the {{DOMxRef("Window.requestAnimationFrame", "requestAnimationFrame()")}} loop (see below) and revert the gamepad information back to what it was originally.</p>

<pre class="brush: js">window.addEventListener("gamepaddisconnected", function(e) {
  gamepadInfo.innerHTML = "Waiting for gamepad.";

  cancelRequestAnimationFrame(start);
});</pre>

<p>Chrome does things differently here. Instead of constantly storing the gamepad's latest state in a variable it only stores a snapshot, so to do the same thing in Chrome you have to keep polling it and then only use the {{ domxref("Gamepad") }} object in code when it is available. We have done this below using {{ domxref("Window.setInterval()") }}; once the object is available the gamepad info is outputted, the game loop is started, and the interval is cleared using {{ domxref("Window.clearInterval()") }}. Note that in older versions of Chrome {{ domxref("Navigator.getGamepads()") }} is implemented with a <code>webkit</code> prefix. We attempt to detect and handle both the prefixed version and the standard version of the function for backwards compatibility.</p>

<pre class="brush: js">var interval;

if (!('ongamepadconnected' in window)) {
  // No gamepad events available, poll instead.
  interval = setInterval(pollGamepads, 500);
}

function pollGamepads() {
  var gamepads = navigator.getGamepads ? navigator.getGamepads() : (navigator.webkitGetGamepads ? navigator.webkitGetGamepads : []);
  for (var i = 0; i &lt; gamepads.length; i++) {
    var gp = gamepads[i];
    if (gp) {
      gamepadInfo.innerHTML = "Gamepad connected at index " + gp.index + ": " + gp.id +
        ". It has " + gp.buttons.length + " buttons and " + gp.axes.length + " axes.";
      gameLoop();
      clearInterval(interval);
    }
  }
}</pre>

<p>Now on to the main game loop. In each execution of the loop we check if one of four buttons is being pressed; if so, we update the values of the <code>a</code> and <code>b</code> movement variables appropriately, then update the {{ cssxref("left") }} and {{ cssxref("top") }} properties, changing their values to the current values of <code>a</code> and <code>b</code> respectively. This has the effect of moving the ball around the screen.  In current versions of Chrome (version 34 as of this writing) the button values are stored as an array of double values, instead of {{ domxref("GamepadButton") }} objects. This is fixed in development versions.</p>

<p>After all this is done, we use our <font face="Consolas, Monaco, Andale Mono, monospace">requestAnimationFrame()</font> to request the next animation frame, running <code>gameLoop()</code> again.</p>

<pre class="brush: js">function buttonPressed(b) {
<span class="k">  if</span> <span class="p">(</span><span class="k">typeof</span><span class="p">(</span><span class="nx">b</span><span class="p">)</span> <span class="o">==</span> <span class="s2">"object"</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">    return</span> <span class="nx">b</span><span class="p">.</span><span class="nx">pressed</span><span class="p">;</span>
<span class="nx">  </span><span class="p">}</span>
<span class="p">  return</span> <span class="nx">b</span> <span class="o">==</span> <span class="mf">1.0</span><span class="p">;</span>
}

function gameLoop() {
  var gamepads = navigator.getGamepads ? navigator.getGamepads() : (navigator.webkitGetGamepads ? navigator.webkitGetGamepads : []);
  if (!gamepads) {
    return;
  }

  var gp = gamepads[0];
  if (buttonPressed(gp.buttons[0])) {
    b--;
  } else if (buttonPressed(gp.buttons[2])) {
    b++;
  }
  if (buttonPressed(gp.buttons[1])) {
    a++;
  } else if (buttonPressed(gp.buttons[3])) {
    a--;
  }

  ball.style.left = a * 2 + "px";
  ball.style.top = b * 2 + "px";

  start = requestAnimationFrame(gameLoop);
}</pre>

<h3 id="Using_axes_information">Using axes information</h3>

<p><strong>TBD (basically the same, except using axes[i] rather than button[i].value for both Firefox and Chrome.)</strong></p>

<h2 id="Complete_example_Displaying_gamepad_state">Complete example: Displaying gamepad state</h2>

<p>This example shows how to use the {{ domxref("Gamepad") }} object, as well as the {{ event("gamepadconnected") }} and {{ event("gamepaddisconnected") }} events in order to display the state of all gamepads connected to the system. You can find a <a href="http://luser.github.io/gamepadtest/">working demo</a> and look at the <a href="https://github.com/luser/gamepadtest">full source code</a> on Github.</p>

<pre class="brush: js">var haveEvents = 'ongamepadconnected' in window;
var controllers = {};<span style="font-size: 1rem;">

</span><span style="font-size: 1rem;">function connecthandler(e) {
</span><span style="font-size: 1rem;">  addgamepad(e.gamepad);
</span><span style="font-size: 1rem;">}

</span><span style="font-size: 1rem;">function addgamepad(gamepad) {
</span><span style="font-size: 1rem;">  controllers[gamepad.index] = gamepad;

  var d = document.createElement("div");
</span><span style="font-size: 1rem;">  d.setAttribute("id", "controller" + gamepad.index);

</span><span style="font-size: 1rem;">  var t = document.createElement("h1");
</span><span style="font-size: 1rem;">  t.appendChild(document.createTextNode("gamepad: " + gamepad.id));
</span><span style="font-size: 1rem;">  d.appendChild(t);

</span><span style="font-size: 1rem;">  var b = document.createElement("div");
</span><span style="font-size: 1rem;">  b.className = "buttons";
</span><span style="font-size: 1rem;">  for (var i = 0; i &lt; gamepad.buttons.length; i++) {
</span><span style="font-size: 1rem;">    var e = document.createElement("span");
</span><span style="font-size: 1rem;">    e.className = "button";
</span><span style="font-size: 1rem;">    //e.id = "b" + i;
</span><span style="font-size: 1rem;">    e.innerHTML = i;
</span><span style="font-size: 1rem;">    b.appendChild(e);
</span><span style="font-size: 1rem;">  }

</span><span style="font-size: 1rem;">  d.appendChild(b);

</span><span style="font-size: 1rem;">  var a = document.createElement("div");
</span><span style="font-size: 1rem;">  a.className = "axes";

</span><span style="font-size: 1rem;">  for (var i = 0; i &lt; gamepad.axes.length; i++) {
</span><span style="font-size: 1rem;">    var p = document.createElement("progress");
</span><span style="font-size: 1rem;">    p.className = "axis";
</span><span style="font-size: 1rem;">    //p.id = "a" + i;
</span><span style="font-size: 1rem;">    p.setAttribute("max", "2");
</span><span style="font-size: 1rem;">    p.setAttribute("value", "1");
</span><span style="font-size: 1rem;">    p.innerHTML = i;
</span><span style="font-size: 1rem;">    a.appendChild(p);
</span><span style="font-size: 1rem;">  }

</span><span style="font-size: 1rem;">  d.appendChild(a);

  // See </span>https://github.com/luser/gamepadtest/blob/master/index.html<span style="font-size: 1rem;">
  var start = </span><span style="font-size: 1rem;">document.getElementById("start");</span>
<span style="font-size: 1rem;">  if (start) {
</span><span style="font-size: 1rem;">    start.style.display = "none";
  }
</span><span style="font-size: 1rem;">
  document.body.appendChild(d);
</span><span style="font-size: 1rem;">  requestAnimationFrame(updateStatus);
</span><span style="font-size: 1rem;">}
</span><span style="font-size: 1rem;">
function disconnecthandler(e) {
</span><span style="font-size: 1rem;">  removegamepad(e.gamepad);
</span><span style="font-size: 1rem;">}

</span><span style="font-size: 1rem;">function removegamepad(gamepad) {
</span><span style="font-size: 1rem;">  var d = document.getElementById("controller" + gamepad.index);
</span><span style="font-size: 1rem;">  document.body.removeChild(d);
</span><span style="font-size: 1rem;">  delete controllers[gamepad.index];
</span><span style="font-size: 1rem;">}

</span><span style="font-size: 1rem;">function updateStatus() {
</span><span style="font-size: 1rem;">  if (!haveEvents) {
</span><span style="font-size: 1rem;">    scangamepads();
</span><span style="font-size: 1rem;">  }

  var i = 0;
  var j;

</span><span style="font-size: 1rem;">  for (j in controllers) {
</span><span style="font-size: 1rem;">    var controller = controllers[j];
</span><span style="font-size: 1rem;">    var d = document.getElementById("controller" + j);
</span><span style="font-size: 1rem;">    var buttons = d.getElementsByClassName("button");
</span><span style="font-size: 1rem;">
    for (i = 0; i &lt; controller.buttons.length; i++) {
</span><span style="font-size: 1rem;">      var b = buttons[i];
</span><span style="font-size: 1rem;">      var val = controller.buttons[i];
</span><span style="font-size: 1rem;">      var pressed = val == 1.0;
</span><span style="font-size: 1rem;">      if (typeof(val) == "object") {
</span><span style="font-size: 1rem;">        pressed = val.pressed;
</span><span style="font-size: 1rem;">        val = val.value;
</span><span style="font-size: 1rem;">      }

</span><span style="font-size: 1rem;">      var pct = Math.round(val * 100) + "%";
</span><span style="font-size: 1rem;">      b.style.backgroundSize = pct + " " + pct;

</span><span style="font-size: 1rem;">      if (pressed) {
</span><span style="font-size: 1rem;">        b.className = "button pressed";
</span><span style="font-size: 1rem;">      } else {
</span><span style="font-size: 1rem;">        b.className = "button";
</span><span style="font-size: 1rem;">      }
</span><span style="font-size: 1rem;">    }

</span><span style="font-size: 1rem;">    var axes = d.getElementsByClassName("axis");
</span><span style="font-size: 1rem;">    for (i = 0; i &lt; controller.axes.length; i++) {
</span><span style="font-size: 1rem;">      var a = axes[i];
</span><span style="font-size: 1rem;">      a.innerHTML = i + ": " + controller.axes[i].toFixed(4);
</span><span style="font-size: 1rem;">      a.setAttribute("value", controller.axes[i] + 1);
</span><span style="font-size: 1rem;">    }
</span><span style="font-size: 1rem;">  }

</span><span style="font-size: 1rem;">  requestAnimationFrame(updateStatus);
</span><span style="font-size: 1rem;">}

</span><span style="font-size: 1rem;">function scangamepads() {
</span><span style="font-size: 1rem;">  var gamepads = navigator.getGamepads ? navigator.getGamepads() : (navigator.webkitGetGamepads ? navigator.webkitGetGamepads() : []);
</span><span style="font-size: 1rem;">  for (var i = 0; i &lt; gamepads.length; i++) {
</span><span style="font-size: 1rem;">    if (gamepads[i]) {
</span><span style="font-size: 1rem;">      if (gamepads[i].index in controllers) {
</span><span style="font-size: 1rem;">        </span><span style="font-size: 1rem;">controllers[gamepads[i].index] = gamepads[i];
</span><span style="font-size: 1rem;">      } else {
</span><span style="font-size: 1rem;">        </span><span style="font-size: 1rem;">addgamepad(gamepads[i]);
</span><span style="font-size: 1rem;">      }
</span><span style="font-size: 1rem;">    }
</span><span style="font-size: 1rem;">  }
</span><span style="font-size: 1rem;">}

</span><span style="font-size: 1rem;">
window.addEventListener("gamepadconnected", connecthandler);
</span><span style="font-size: 1rem;">window.addEventListener("gamepaddisconnected", disconnecthandler);

</span><span style="font-size: 1rem;">if (!haveEvents) {
</span><span style="font-size: 1rem;">  setInterval(scangamepads, 500);
</span><span style="font-size: 1rem;">}</span></pre>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName("Gamepad", "#gamepad-interface", "Gamepad")}}</td>
   <td>{{Spec2("Gamepad")}}</td>
   <td>Initial defintion</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p>{{Compat("api.Gamepad")}}</p>