Signatur
Beschreibung
Die Eigenschaft hapticActuators des Gamepad-Interfaces gibt ein Array von GamepadHapticActuator-Objekten zurück. Jedes Objekt steht für eine Hardware-Einheit, die haptisches Feedback erzeugt, typischerweise einen Vibrationsmotor. Damit kann eine Web-Anwendung, etwa ein Browserspiel, bei Treffern, Explosionen oder Kollisionen Force-Feedback auslösen.
Die Eigenschaft stammt aus der Spezifikation Gamepad Extensions und ist Teil des Interfaces, das der Browser über navigator.getGamepads() oder das Ereignis gamepadconnected bereitstellt. Jeder Aktor bietet die Methode pulse(value, duration). Sie lässt ihn mit einer Intensität zwischen 0.0 und 1.0 für eine Dauer in Millisekunden vibrieren und liefert ein Promise<boolean>.
In der Praxis ist die Eigenschaft kaum verbreitet. Chromium-Browser und Safari setzen stattdessen auf Gamepad.vibrationActuator mit der Methode playEffect("dual-rumble", …). Robuster Code prüft deshalb beide Varianten und fällt sauber zurück, wenn keine vorhanden ist.
Rückgabewert
GamepadHapticActuator-Objekten. Es ist leer, wenn das Gamepad keine haptischen Aktoren meldet. In Browsern ohne Unterstützung ist die Eigenschaft undefined.Beispiele
Aktoren eines verbundenen Gamepads auflisten
window.addEventListener('gamepadconnected', (event) => {
const { gamepad } = event;
const actuators = gamepad.hapticActuators ?? [];
console.log(`${gamepad.id}: ${actuators.length} haptische(r) Aktor(en)`);
actuators.forEach((a, i) => console.log(`Aktor ${i}: Typ = ${a.type}`));
});Kurzer Vibrationsimpuls bei einem Treffer
const vibrateOnHit = async (gamepadIndex) => {
const gamepad = navigator.getGamepads()[gamepadIndex];
const actuator = gamepad?.hapticActuators?.[0];
if (!actuator?.pulse) {
console.log('Keine Vibration verfügbar');
return;
}
// Intensität 0.8 für 200 ms
const ok = await actuator.pulse(0.8, 200);
console.log('Impuls ausgeführt:', ok);
};
vibrateOnHit(0);Browserübergreifend mit Rückfall auf vibrationActuator
const rumble = async (gamepad, intensity = 1, duration = 300) => {
// Chromium/Safari: vibrationActuator mit playEffect
if (gamepad.vibrationActuator?.playEffect) {
return gamepad.vibrationActuator.playEffect('dual-rumble', {
startDelay: 0,
duration,
strongMagnitude: intensity,
weakMagnitude: intensity / 2
});
}
// Firefox: hapticActuators mit pulse
const actuator = gamepad.hapticActuators?.[0];
if (actuator?.pulse) {
return actuator.pulse(intensity, duration);
}
return 'nicht unterstützt';
};
window.addEventListener('gamepadconnected', async ({ gamepad }) => {
console.log(await rumble(gamepad, 0.6, 250));
});// Wichtig · Fallstricke
- Kompatibilität:
hapticActuatorsist experimentell und steht praktisch nur in Firefox zur Verfügung, teils nur mit aktivierter Einstellungdom.gamepad.extensions.enabled. Chrome, Edge und Safari bieten stattdessenGamepad.vibrationActuatoran. Deshalb immer per Feature-Erkennung (?.) prüfen. - Momentaufnahme: In Chromium-Browsern sind
Gamepad-Objekte ausnavigator.getGamepads()Momentaufnahmen. Hole das Objekt daher vor jeder Nutzung neu, statt eine alte Referenz aufzubewahren. - Leeres Array: Auch wenn die Eigenschaft unterstützt wird, kann das Array leer sein, etwa bei Controllern ohne Motor oder wenn der Treiber die Aktoren nicht meldet.
- Nutzerinteraktion und sicherer Kontext: Die Gamepad-API liefert erst Daten, nachdem der Nutzer eine Taste gedrückt hat. Neuere Browser verlangen außerdem HTTPS (sicherer Kontext).
- Werte begrenzen:
pulse()erwartet eine Intensität von0.0bis1.0. Zu lange oder zu häufige Impulse wirken störend und belasten den Akku des Controllers.