Gamepad.connected — Eigenschaft · JavaScript-Referenz

Signatur

Gamepad.connected

Beschreibung

Die schreibgeschützte Eigenschaft connected eines Gamepad-Objekts zeigt an, ob das zugehörige Eingabegerät noch am System hängt. Solange der Controller angeschlossen ist, liefert sie true. Wird er getrennt, etwa durch Abziehen des Kabels, einen Bluetooth-Abbruch oder einen leeren Akku, wechselt der Wert auf false.

Das ist vor allem dann nützlich, wenn eine Anwendung in ihrer Spielschleife (requestAnimationFrame) eine Referenz auf ein Gamepad-Objekt behält. Mit connected lässt sich prüfen, ob die Eingaben noch gültig sind, bevor man buttons oder axes ausliest. Beim Ereignis gamepaddisconnected hat das übergebene event.gamepad bereits connected === false.

Wichtig: In Chromium-basierten Browsern ist ein Gamepad-Objekt eine Momentaufnahme. Seine Werte werden nicht laufend aktualisiert. Den aktuellen Zustand erhält man zuverlässig nur, wenn man in jedem Frame navigator.getGamepads() neu aufruft. Getrennte Geräte erscheinen dort meist als null.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Gamepad verbunden ist, sonst false.

Beispiele

Verbindungsstatus bei den Ereignissen prüfen

window.addEventListener('gamepadconnected', (event) => {
  const pad = event.gamepad;
  console.log(`${pad.id} verbunden:`, pad.connected);
});

window.addEventListener('gamepaddisconnected', (event) => {
  const pad = event.gamepad;
  console.log(`${pad.id} verbunden:`, pad.connected);
});

Xbox Wireless Controller (STANDARD GAMEPAD) verbunden: true Xbox Wireless Controller (STANDARD GAMEPAD) verbunden: false

Spielschleife nur mit verbundenen Controllern

const update = () => {
  // In jedem Frame neu abfragen, damit die Werte aktuell sind
  const pads = navigator.getGamepads();

  for (const pad of pads) {
    if (!pad || !pad.connected) continue;

    const [x, y] = pad.axes;
    if (pad.buttons[0].pressed) {
      console.log(`Spieler ${pad.index + 1}: Sprung bei`, x.toFixed(2), y.toFixed(2));
    }
  }

  requestAnimationFrame(update);
};

requestAnimationFrame(update);

Spieler 1: Sprung bei 0.00 -0.12

Pause-Menü anzeigen, wenn der Controller getrennt wird

let activeIndex = null;

window.addEventListener('gamepadconnected', (e) => {
  activeIndex ??= e.gamepad.index;
});

const checkController = () => {
  const pad = activeIndex !== null ? navigator.getGamepads()[activeIndex] : null;
  const isConnected = Boolean(pad?.connected);

  document.body.classList.toggle('paused', activeIndex !== null && !isConnected);
  requestAnimationFrame(checkController);
};

requestAnimationFrame(checkController);

// Wichtig · Fallstricke

Momentaufnahmen: Chrome und Edge liefern bei jedem Aufruf von navigator.getGamepads() neue Objekte. Eine alte Referenz zeigt dort unter Umständen weiter connected === true, obwohl der Controller längst getrennt ist. Den Status deshalb immer über einen frischen getGamepads()-Aufruf prüfen.
Getrennte Controller erscheinen im Array von getGamepads() meist als null, nicht als Objekt mit connected: false. Beide Fälle abfangen, z. B. mit pad?.connected.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert bzw. führt im Strict Mode zu einem TypeError.
Aus Datenschutzgründen (Schutz vor Fingerprinting) machen Browser Gamepads erst sichtbar, nachdem der Nutzer einen Knopf gedrückt hat. Vorher löst auch ein angeschlossener Controller kein gamepadconnected aus.
Die Gamepad API steht nur in sicheren Kontexten (HTTPS) zur Verfügung und kann per Permissions-Policy gamepad gesperrt werden, z. B. in iframes.

Siehe auch

Gamepad Navigator.getGamepads() Gamepad.index Gamepad.timestamp GamepadEvent.gamepad