Signatur
Gamepad.mapping
Beschreibung
Die Eigenschaft mapping eines Gamepad-Objekts gibt an, ob der Browser die rohen Eingaben des Controllers auf ein bekanntes Layout umgemappt hat. Derzeit definiert die Spezifikation zwei Werte:
"standard": Der Controller entspricht dem Standard-Gamepad-Layout der W3C-Spezifikation. Dann sind die Indizes inbuttonsundaxesfest belegt, z. B.buttons[0]= untere Aktionstaste (A bzw. Kreuz),buttons[12]–buttons[15]= Steuerkreuz,axes[0]/axes[1]= linker Stick.""(leerer String): Der Browser kennt kein passendes Layout. Die Belegung der Tasten und Achsen ist geräteabhängig und muss von der Anwendung selbst ermittelt werden.
Die Eigenschaft ist besonders wichtig für Spiele und interaktive Anwendungen: Bei "standard" kannst du eine feste Tastenbelegung verwenden, andernfalls solltest du eine Belegungsoberfläche anbieten, in der Nutzer die Tasten selbst zuordnen.
Die Spezifikation sieht außerdem den Wert "xr-standard" für XR-Controller vor, der jedoch nur bei Gamepads aus der WebXR Device API (XRInputSource.gamepad) vorkommt, nicht bei navigator.getGamepads().
Rückgabewert
Typ
string
Beschreibung
"standard", wenn das Standard-Layout verwendet wird, sonst "". Bei WebXR-Controllern ggf. "xr-standard".Beispiele
Layout beim Verbinden eines Controllers prüfen
window.addEventListener('gamepadconnected', (event) => {
const { gamepad } = event;
if (gamepad.mapping === 'standard') {
console.log(`${gamepad.id}: Standard-Layout erkannt`);
} else {
console.log(`${gamepad.id}: unbekanntes Layout – bitte Tasten zuordnen`);
}
});Xbox 360 Controller (XInput STANDARD GAMEPAD): Standard-Layout erkannt
Feste oder benutzerdefinierte Belegung wählen
const STANDARD_BELEGUNG = { springen: 0, schiessen: 2, pause: 9 };
// Vom Nutzer gespeicherte Belegung für unbekannte Geräte
const eigeneBelegung = JSON.parse(localStorage.getItem('belegung') ?? 'null');
const belegungFuer = (gamepad) =>
gamepad.mapping === 'standard'
? STANDARD_BELEGUNG
: eigeneBelegung ?? STANDARD_BELEGUNG;
const spielSchleife = () => {
for (const gp of navigator.getGamepads()) {
if (!gp) continue;
const belegung = belegungFuer(gp);
if (gp.buttons[belegung.springen]?.pressed) {
console.log('Springen!');
}
}
requestAnimationFrame(spielSchleife);
};
requestAnimationFrame(spielSchleife);Springen!
Steuerkreuz nur bei Standard-Layout auswerten
const leseSteuerkreuz = (gp) => {
if (gp.mapping !== 'standard') return null;
const [hoch, runter, links, rechts] = [12, 13, 14, 15]
.map((i) => gp.buttons[i]?.pressed ?? false);
return { hoch, runter, links, rechts };
};
const [erstes] = navigator.getGamepads().filter(Boolean);
if (erstes) console.log(leseSteuerkreuz(erstes));{ hoch: false, runter: false, links: true, rechts: false }
// Wichtig · Fallstricke
- Ein leerer String bedeutet nicht, dass der Controller unbrauchbar ist – nur dass die Indizes nicht garantiert sind. Biete in diesem Fall eine manuelle Tastenzuordnung an.
- Ob ein Gerät als
"standard"erkannt wird, hängt von Browser, Betriebssystem und Treiber ab. Derselbe Controller kann in Chrome"standard"und in Firefox""melden. - Auch bei
"standard"kann ein Gerät zusätzliche Tasten oder Achsen haben, die über Index 16 bzw. 3 hinausgehen; greife deshalb immer mit optionaler Verkettung (?.) zu. - Die Gamepad API steht nur in sicheren Kontexten (HTTPS) zur Verfügung und kann per Permissions Policy (
gamepad) eingeschränkt sein. Gamepads werden erst nach einer Nutzerinteraktion (Tastendruck) sichtbar. - In Chrome sind
Gamepad-Objekte Momentaufnahmen – rufenavigator.getGamepads()in jeder Frame erneut auf.