Signatur
Beschreibung
Die Schnittstelle GamepadButton steht für eine einzelne Taste eines Gamepads oder eines anderen Controllers. Du bekommst die Instanzen über das Array Gamepad.buttons, das ein Gamepad-Objekt aus navigator.getGamepads() oder dem Event gamepadconnected liefert. Selbst erzeugen kannst du sie nicht, es gibt keinen öffentlichen Konstruktor.
Ein GamepadButton hat drei schreibgeschützte Eigenschaften:
pressed(boolean):true, wenn die Taste gerade gedrückt ist.touched(boolean):true, wenn die Taste berührt wird. Das funktioniert nur, wenn die Hardware Berührungen erkennt. Sonst entspricht der Wertpressed.value(number): Analoger Wert zwischen0.0(nicht gedrückt) und1.0(voll durchgedrückt). Er ist vor allem bei Schultertasten und Triggern nützlich. Einfache Tasten liefern nur0oder1.
Die Gamepad-API arbeitet mit Abfragen (Polling), nicht mit Ereignissen: Für Tastendrücke gibt es kein Event. Deshalb fragst du den Zustand typischerweise in jedem Frame innerhalb einer requestAnimationFrame-Schleife ab. Wenn der Controller das „Standard“-Layout meldet (gamepad.mapping === "standard"), ist die Belegung der Indizes festgelegt, zum Beispiel 0 = untere Aktionstaste (A/Kreuz), 6/7 = linker/rechter Trigger, 12–15 = Steuerkreuz.
Rückgabewert
Gamepad.buttons bereitgestellt. Enthält pressed, touched und value.Beispiele
Tastenzustand bei Verbindung auslesen
window.addEventListener('gamepadconnected', (event) => {
const { gamepad } = event;
console.log(`Verbunden: ${gamepad.id} (${gamepad.buttons.length} Tasten)`);
gamepad.buttons.forEach((button, index) => {
console.log(index, button.pressed, button.touched, button.value);
});
});Game-Loop: Sprung-Taste per Flankenerkennung
let previouslyPressed = false;
const loop = () => {
const [gamepad] = navigator.getGamepads();
if (gamepad) {
const jumpButton = gamepad.buttons[0]; // A / Kreuz im Standard-Layout
// Nur beim Übergang von „losgelassen“ zu „gedrückt“ reagieren
if (jumpButton.pressed && !previouslyPressed) {
console.log('Sprung!');
}
previouslyPressed = jumpButton.pressed;
}
requestAnimationFrame(loop);
};
requestAnimationFrame(loop);Analogen Trigger als Gaspedal nutzen
const DEADZONE = 0.05;
const readThrottle = () => {
const gamepad = navigator.getGamepads().find((gp) => gp && gp.mapping === 'standard');
if (!gamepad) return 0;
const rightTrigger = gamepad.buttons[7];
// Kleine Werte ignorieren (Sensorrauschen)
return rightTrigger.value < DEADZONE ? 0 : rightTrigger.value;
};
const update = () => {
const throttle = readThrottle();
document.title = `Gas: ${Math.round(throttle * 100)} %`;
requestAnimationFrame(update);
};
requestAnimationFrame(update);// Wichtig · Fallstricke
- Keine Ereignisse für Tasten: Einen
buttondown-Event gibt es nicht. Den Zustand musst du regelmäßig abfragen, etwa mitrequestAnimationFrame. Wenn du einzelne Tastendrücke erkennen willst, vergleiche den aktuellen mit dem vorherigen Zustand. - Momentaufnahmen: In Chromium-Browsern sind die
Gamepad- undGamepadButton-Objekte statische Momentaufnahmen. Rufe deshalb in jedem Frame erneutnavigator.getGamepads()auf, statt dir Referenzen zu merken. - Belegung: Die Indizes sind nur bei
mapping === "standard"garantiert. Bei anderen Controllern hängen sie vom Gerät und vom Browser ab. touchedwird nur von wenigen Geräten wirklich unterstützt. Bei den meisten entspricht espressed.- Sicherheit/Kompatibilität: Die Gamepad-API ist nur in sicheren Kontexten (HTTPS) verfügbar und kann per Permissions Policy (
gamepad) eingeschränkt werden. Gamepads werden erst sichtbar, nachdem der Nutzer eine Taste gedrückt hat. Das schützt vor Fingerprinting. Alle modernen Browser unterstützen die API. - Analoge Werte schwanken leicht. Plane eine Totzone (Deadzone) ein.