Signatur
Beschreibung
Die schreibgeschützte Eigenschaft gamepad der Schnittstelle GamepadEvent verweist auf das Gamepad-Objekt, zu dem das Ereignis gehört. Sie ist der zentrale Einstieg, wenn ein Controller verbunden oder getrennt wird: Über das Objekt kommst du an index, id, mapping, buttons, axes und (falls vorhanden) vibrationActuator.
Typischerweise nutzt du die Eigenschaft in Handlern für die Ereignisse gamepadconnected und gamepaddisconnected am window-Objekt. Dort merkst du dir beim Verbinden den index des Controllers, startest die Spielschleife und räumst beim Trennen wieder auf.
Wichtig: Das Objekt im Ereignis ist in Chromium-basierten Browsern ein Schnappschuss. Es aktualisiert sich nicht automatisch. Den aktuellen Zustand von Tasten und Achsen liest du deshalb in jedem Frame über navigator.getGamepads()[index] aus, am besten innerhalb von requestAnimationFrame.
Rückgabewert
Gamepad-Objekt des Controllers, der verbunden bzw. getrennt wurde. Es ist schreibgeschützt und immer gesetzt.Beispiele
Verbundenen Controller erkennen
window.addEventListener('gamepadconnected', (event) => {
const { index, id, buttons, axes, mapping } = event.gamepad;
console.log(`Gamepad ${index} verbunden: ${id}`);
console.log(`${buttons.length} Tasten, ${axes.length} Achsen, Mapping: "${mapping}"`);
});Spielschleife starten und beim Trennen beenden
let activeIndex = null;
let rafId = null;
const loop = () => {
// Aktuellen Zustand immer frisch abfragen, nicht event.gamepad verwenden
const pad = navigator.getGamepads()[activeIndex];
if (pad) {
const [x, y] = pad.axes;
if (pad.buttons[0].pressed) console.log('Sprung!');
if (Math.abs(x) > 0.2 || Math.abs(y) > 0.2) {
console.log(`Stick: x=${x.toFixed(2)}, y=${y.toFixed(2)}`);
}
}
rafId = requestAnimationFrame(loop);
};
window.addEventListener('gamepadconnected', (e) => {
activeIndex = e.gamepad.index;
rafId = requestAnimationFrame(loop);
});
window.addEventListener('gamepaddisconnected', (e) => {
if (e.gamepad.index === activeIndex) {
cancelAnimationFrame(rafId);
activeIndex = null;
console.log(`Gamepad ${e.gamepad.index} getrennt: ${e.gamepad.id}`);
}
});Mehrere Controller verwalten und per on-Property reagieren
const players = new Map();
window.ongamepadconnected = (e) => {
players.set(e.gamepad.index, { id: e.gamepad.id, score: 0 });
console.log(`Spieler ${players.size} beigetreten`);
// Kurzes Vibrationsfeedback, falls unterstützt
e.gamepad.vibrationActuator?.playEffect('dual-rumble', {
duration: 200,
strongMagnitude: 0.8,
weakMagnitude: 0.4
});
};
window.ongamepaddisconnected = (e) => {
players.delete(e.gamepad.index);
console.log(`Controller ${e.gamepad.index} entfernt, verbleibend: ${players.size}`);
};// Wichtig · Fallstricke
- Schnappschuss statt Live-Objekt: In Chrome und Edge ändert sich
event.gamepadnicht. Nutze für Eingaben immernavigator.getGamepads(). In Firefox ist das Objekt live, darauf solltest du dich aber nicht verlassen. - Nutzeraktion nötig:
gamepadconnectedwird oft erst ausgelöst, wenn eine Taste gedrückt wird, während die Seite den Fokus hat. Das schützt vor Fingerprinting. Ein bereits angeschlossener Controller erscheint deshalb nicht sofort. - Sicherer Kontext: Neuere Browser stellen die Gamepad API nur über HTTPS bereit. Per
Permissions-Policy: gamepadkann sie außerdem in iframes gesperrt sein. idundmappingunterscheiden sich je nach Browser und Betriebssystem. Nur beimapping === "standard"ist die Belegung der Tasten verlässlich.vibrationActuatorwird nicht überall unterstützt (z. B. fehlt es teilweise in Firefox und Safari). Prüfe es deshalb immer mit optionaler Verkettung (?.).