Gamepad.vibrationActuator — Eigenschaft · JavaScript-Referenz

Signatur

Gamepad.vibrationActuator

Beschreibung

Die Eigenschaft vibrationActuator eines Gamepad-Objekts liefert ein GamepadHapticActuator, über das du Rumble-Effekte auf dem Controller auslöst. Damit gibst du Spielern körperlich spürbare Rückmeldung, etwa bei Treffern, Explosionen, Kollisionen oder zur Bestätigung in Menüs.

Der eigentliche Effekt wird mit playEffect(type, params) gestartet und mit reset() vorzeitig beendet. Unterstützt werden die Effekttypen "dual-rumble" (zwei Motoren, stark/schwach) und bei manchen Controllern "trigger-rumble" (Vibration in den Schultertasten, z. B. beim Xbox-Controller). Welche Typen ein Gerät kann, verrät die Eigenschaft effects des Aktuators (in manchen Browsern stattdessen noch das ältere type).

Hat der Controller keine Haptik-Hardware oder unterstützt der Browser die Funktion nicht, ist der Wert null bzw. undefined. Prüfe deshalb immer, ob es den Aktuator gibt, bevor du ihn benutzt. Weil navigator.getGamepads() in Chromium Momentaufnahmen liefert, solltest du das Gamepad-Objekt bei jedem Frame neu holen.

Rückgabewert

Typ

GamepadHapticActuator | null

Beschreibung

Ein GamepadHapticActuator-Objekt mit den Methoden playEffect() und reset(). Hat das Gerät keine Haptik, ist der Wert null. Wird die Eigenschaft gar nicht unterstützt, ist sie undefined.

Beispiele

Kurzer Rumble-Effekt beim Verbinden des Controllers

window.addEventListener('gamepadconnected', async (event) => {
  const actuator = event.gamepad.vibrationActuator;
  if (!actuator) {
    console.log('Keine Vibration verfügbar');
    return;
  }
  const result = await actuator.playEffect('dual-rumble', {
    startDelay: 0,
    duration: 200,       // Millisekunden
    weakMagnitude: 0.5,  // 0.0 – 1.0
    strongMagnitude: 1.0
  });
  console.log(result);
});

complete

Treffer-Feedback im Game-Loop mit Unterstützungsprüfung

const rumble = (index, strength = 1, duration = 150) => {
  const pad = navigator.getGamepads()[index];
  const actuator = pad?.vibrationActuator;
  if (!actuator) return Promise.resolve('unsupported');

  // effects ist neuer, type ist die ältere Variante
  const canDual = actuator.effects?.includes('dual-rumble')
    ?? actuator.type === 'dual-rumble';
  if (!canDual) return Promise.resolve('unsupported');

  return actuator.playEffect('dual-rumble', {
    duration,
    strongMagnitude: strength,
    weakMagnitude: strength * 0.6
  });
};

// z. B. wenn der Spieler getroffen wird
rumble(0, 0.8, 300).then((r) => console.log('Rumble:', r));

Rumble: complete

Vibration in den Triggern und vorzeitig stoppen

const pad = navigator.getGamepads().find(Boolean);
const actuator = pad?.vibrationActuator;

if (actuator?.effects?.includes('trigger-rumble')) {
  actuator.playEffect('trigger-rumble', {
    duration: 2000,
    leftTrigger: 0.7,
    rightTrigger: 0.3
  }).then((r) => console.log('Effekt:', r));

  // Nach 500 ms abbrechen, z. B. weil das Spiel pausiert wurde
  setTimeout(() => actuator.reset(), 500);
}

Effekt: preempted

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser (Chrome, Edge, Opera) und Safari unterstützen die Eigenschaft. Firefox hatte lange nur die nicht standardisierte Eigenschaft Gamepad.hapticActuators. Frag vor der Nutzung immer ab, ob die Eigenschaft da ist, z. B. mit pad?.vibrationActuator.
effects und type: Ältere Umsetzungen haben nur type ("vibration" oder "dual-rumble"), neuere nur das Array effects. Schreib deinen Code so, dass er mit beiden Varianten funktioniert.
Promise-Ergebnis: playEffect() wird mit "complete" erfüllt, wenn der Effekt normal endet. Wird er durch einen neuen Effekt oder reset() unterbrochen, ist das Ergebnis "preempted". Ungültige Parameter (z. B. Stärke außerhalb von 0–1) führen zur Ablehnung des Promise.
Einschränkungen: Die Dauer ist je nach Browser nach oben begrenzt (in Chromium auf etwa 5 Sekunden). Hat das Dokument keinen Fokus oder ist es im Hintergrund, spielt der Browser oft keinen Effekt ab.
Barrierefreiheit: Biete eine Einstellung an, mit der man die Vibration abschalten kann. Manche Menschen empfinden starke Haptik als unangenehm.
Die Gamepad-API steht nur in sicheren Kontexten (HTTPS) zur Verfügung und kann über die Permissions-Policy gamepad gesperrt werden.

Siehe auch

Gamepad GamepadHapticActuator GamepadHapticActuator.playEffect() GamepadHapticActuator.reset() Navigator.getGamepads() Navigator.vibrate()