GamepadHapticActuator — Schnittstelle · JavaScript-Referenz

Signatur

interface GamepadHapticActuator

Beschreibung

Das Interface GamepadHapticActuator gehört zur Gamepad API und steht für die Hardware in einem Controller, mit der er haptisches Feedback geben kann – meist zwei Vibrationsmotoren mit unterschiedlichen Unwuchtmassen (Dual-Rumble), bei manchen Controllern zusätzlich Motoren in den Schultertasten (Trigger-Rumble). Eine Instanz erzeugt man nicht selbst. Der Browser stellt sie über die Eigenschaft Gamepad.vibrationActuator bereit, sofern der Controller Vibration unterstützt.

Die wichtigste Methode ist playEffect(type, params). Sie startet einen Effekt wie "dual-rumble" oder "trigger-rumble" und gibt ein Promise zurück. Es wird mit "complete" erfüllt, wenn der Effekt vollständig abgespielt wurde, und mit "preempted", wenn ein neuer Effekt oder reset() ihn unterbrochen hat. reset() stoppt jede laufende Vibration sofort.

Die Eigenschaft effects ist ein Array der unterstützten Effekttypen. Damit lässt sich vorab prüfen, ob etwa "trigger-rumble" verfügbar ist. Die ältere Eigenschaft type ("vibration" bzw. "dual-rumble") gilt als veraltet.

Typische Einsatzfälle sind Spiele (Treffer, Explosionen, Kollisionen), Rückmeldung in Web-Anwendungen mit Controller-Steuerung und Hinweise zur Barrierefreiheit. Setzen Sie Vibration sparsam ein und bieten Sie immer eine Option an, um sie abzuschalten.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	"dual-rumble" \| "trigger-rumble"		Parameter von `playEffect()`: Art des Effekts. Unterstützte Werte stehen in `actuator.effects`. Nicht unterstützte Typen führen zu einer Ablehnung des Promise.
$params.duration	number	0	Dauer des Effekts in Millisekunden. Browser begrenzen den Wert, meist auf etwa 5000 ms.
$params.startDelay	number	0	Verzögerung in Millisekunden, bevor der Effekt startet.
$params.strongMagnitude	number	0	Stärke des niederfrequenten (starken) Motors, Wert von `0.0` bis `1.0`.
$params.weakMagnitude	number	0	Stärke des hochfrequenten (schwachen) Motors, Wert von `0.0` bis `1.0`.
$params.leftTrigger	number	0	Nur bei `"trigger-rumble"`: Stärke am linken Trigger, Wert von `0.0` bis `1.0`.
$params.rightTrigger	number	0	Nur bei `"trigger-rumble"`: Stärke am rechten Trigger, Wert von `0.0` bis `1.0`.

Rückgabewert

Typ

Promise<"complete" | "preempted">

Beschreibung

playEffect() und reset() geben jeweils ein Promise zurück. Es wird mit "complete" erfüllt, wenn der Vorgang abgeschlossen ist, und mit "preempted", wenn ein anderer Effekt oder reset() den laufenden Effekt unterbrochen hat. Bei ungültigen Parametern oder nicht unterstützten Effekttypen wird es abgelehnt.

Beispiele

Aktuator ermitteln und einfachen Rumble-Effekt abspielen

window.addEventListener('gamepadconnected', async (event) => {
  const gamepad = event.gamepad;
  const actuator = gamepad.vibrationActuator;

  if (!actuator) {
    console.log('Dieser Controller unterstützt keine Vibration.');
    return;
  }

  console.log('Unterstützte Effekte:', actuator.effects);

  const result = await actuator.playEffect('dual-rumble', {
    startDelay: 0,
    duration: 300,
    weakMagnitude: 0.5,
    strongMagnitude: 1.0
  });
  console.log('Ergebnis:', result);
});

Unterstützte Effekte: ["dual-rumble", "trigger-rumble"] Ergebnis: complete

Treffer-Feedback im Spiel mit Einstellung zum Abschalten

const settings = { vibration: true };

const rumbleOnHit = (gamepadIndex, damage) => {
  if (!settings.vibration) return;
  const gamepad = navigator.getGamepads()[gamepadIndex];
  const actuator = gamepad?.vibrationActuator;
  if (!actuator) return;

  // Stärke aus dem Schaden ableiten (0..1)
  const strength = Math.min(damage / 100, 1);
  actuator
    .playEffect('dual-rumble', {
      duration: 150 + strength * 350,
      strongMagnitude: strength,
      weakMagnitude: strength * 0.6
    })
    .catch((err) => console.warn('Vibration fehlgeschlagen:', err));
};

// Aufruf, z. B. in der Spielschleife
rumbleOnHit(0, 40);

Trigger-Rumble mit Fallback und Abbruch per reset()

const playShot = async (gamepad) => {
  const actuator = gamepad.vibrationActuator;
  if (!actuator) return;

  const effect = actuator.effects?.includes('trigger-rumble')
    ? ['trigger-rumble', { duration: 200, rightTrigger: 0.8 }]
    : ['dual-rumble', { duration: 200, weakMagnitude: 0.8 }];

  return actuator.playEffect(...effect);
};

const gamepad = navigator.getGamepads().find(Boolean);
if (gamepad) {
  const pending = playShot(gamepad);
  // Nach 50 ms abbrechen, z. B. wenn das Spiel pausiert wird
  setTimeout(() => gamepad.vibrationActuator?.reset(), 50);
  console.log(await pending);
}

preempted

// Wichtig · Fallstricke

Browser-Unterstützung: Gamepad.vibrationActuator mit playEffect() und reset() funktioniert in Chromium-Browsern (Chrome, Edge, Opera) und in Safari ab 16.4. Firefox bietet stattdessen das nicht standardisierte Gamepad.hapticActuators mit pulse(value, duration) an, meist nur hinter einem Flag. Deshalb immer per Feature-Erkennung prüfen (if (gamepad.vibrationActuator)).
effects ist relativ neu. In älteren Browsern fehlt die Eigenschaft, dort gibt es nur das veraltete type. Mit optionaler Verkettung (actuator.effects?.includes(...)) abfragen.
Ein neuer playEffect()-Aufruf unterbricht den laufenden Effekt. Dessen Promise wird dann mit \"preempted\" erfüllt, nicht abgelehnt.
Der Wert von duration ist vom Browser begrenzt (in Chrome auf etwa 5 s). Längere Vibrationen müssen Sie wiederholt auslösen.
Die Gamepad API erfordert einen sicheren Kontext (HTTPS) und kann über die Permissions-Policy gamepad gesperrt sein. Gamepads werden erst sichtbar, nachdem der Nutzer eine Taste gedrückt hat.
Ob der Controller Vibration unterstützt, hängt auch vom Betriebssystem und vom Treiber ab (z. B. Bluetooth- oder USB-Verbindung). Das Promise kann erfüllt werden, obwohl physisch nichts vibriert.
Zur Barrierefreiheit: Vibration sollte immer abschaltbar sein und nie die einzige Rückmeldung darstellen.

Siehe auch

GamepadButton XPathEvaluator GamepadEvent GamepadPose MediaStreamTrack