GamepadHapticActuator.playEffect() — Methode · JavaScript-Referenz

Signatur

GamepadHapticActuator.prototype.playEffect(type, params)

Beschreibung

Die Methode playEffect() der Schnittstelle GamepadHapticActuator steuert die Vibrationsmotoren eines angeschlossenen Controllers an. Das Aktuator-Objekt erhalten Sie über gamepad.vibrationActuator eines Gamepad-Objekts, das Sie mit navigator.getGamepads() oder über das Ereignis gamepadconnected bekommen.

Der erste Parameter legt den Effekttyp fest. "dual-rumble" steuert die beiden klassischen Motoren an: einen starken, niederfrequenten und einen schwachen, hochfrequenten. "trigger-rumble" steuert zusätzlich die Motoren in den Schultertasten an, zum Beispiel beim Xbox-Controller. Welche Typen ein Gerät unterstützt, verrät die Eigenschaft effects des Aktuators, sofern der Browser sie anbietet.

Die Methode gibt ein Promise zurück. Es wird mit "complete" erfüllt, wenn der Effekt vollständig abgespielt wurde. Es wird mit "preempted" erfüllt, wenn ein neuer playEffect()-Aufruf oder reset() den Effekt unterbrochen hat. Typische Einsätze sind haptisches Feedback bei Treffern, Explosionen oder Kollisionen in Browserspielen und spürbare Bestätigungen in Anwendungen, die sich mit dem Controller bedienen lassen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	"dual-rumble" \| "trigger-rumble"		Art des Vibrationseffekts. Nicht unterstützte Typen führen dazu, dass das Promise abgelehnt wird (`NotSupportedError`).
$params	Object	{}	Objekt mit den Effekt-Parametern (siehe folgende Einträge).
$params.duration	number	0	Dauer des Effekts in Millisekunden. Browser begrenzen den Wert, z. B. Chromium auf 5000 ms.
$params.startDelay	number	0	Wartezeit in Millisekunden, bevor der Effekt startet.
$params.strongMagnitude	number	0	Stärke des niederfrequenten (starken) Motors, von `0.0` bis `1.0`.
$params.weakMagnitude	number	0	Stärke des hochfrequenten (schwachen) Motors, von `0.0` bis `1.0`.
$params.leftTrigger	number	0	Nur bei `"trigger-rumble"`: Stärke des Motors im linken Trigger, von `0.0` bis `1.0`.
$params.rightTrigger	number	0	Nur bei `"trigger-rumble"`: Stärke des Motors im rechten Trigger, von `0.0` bis `1.0`.

Rückgabewert

Typ

Promise<string>

Beschreibung

Wird mit "complete" erfüllt, wenn der Effekt zu Ende gespielt wurde, oder mit "preempted", wenn er unterbrochen wurde. Das Promise wird abgelehnt, zum Beispiel mit TypeError bei Werten außerhalb des erlaubten Bereichs, mit NotSupportedError bei nicht unterstütztem Typ oder mit InvalidStateError, wenn das Dokument nicht aktiv oder nicht sichtbar ist.

Beispiele

Einfaches Rumpeln beim Verbinden des Controllers

window.addEventListener('gamepadconnected', async (event) => {
  const actuator = event.gamepad.vibrationActuator;
  if (!actuator) {
    console.log('Keine Vibration verfügbar');
    return;
  }
  // Kurzes Begrüßungs-Rumpeln
  const result = await actuator.playEffect('dual-rumble', {
    startDelay: 0,
    duration: 300,
    strongMagnitude: 0.8,
    weakMagnitude: 0.4
  });
  console.log('Effekt:', result);
});

Effekt: complete

Treffer-Feedback im Spiel mit Stärke je nach Schaden

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

  // Schaden 0–100 auf 0.0–1.0 abbilden und begrenzen
  const intensity = Math.min(Math.max(damage / 100, 0), 1);
  try {
    await actuator.playEffect('dual-rumble', {
      duration: 150 + intensity * 350,
      strongMagnitude: intensity,
      weakMagnitude: intensity * 0.5
    });
  } catch (err) {
    console.warn('Vibration fehlgeschlagen:', err.name);
  }
};

rumbleOnHit(0, 60);

Trigger-Rumble nutzen, sonst auf dual-rumble ausweichen

const shootFeedback = async (pad) => {
  const actuator = pad.vibrationActuator;
  if (!actuator) return;

  const supportsTrigger = actuator.effects?.includes('trigger-rumble');
  if (supportsTrigger) {
    return actuator.playEffect('trigger-rumble', {
      duration: 120,
      rightTrigger: 1.0,
      leftTrigger: 0.0
    });
  }
  return actuator.playEffect('dual-rumble', {
    duration: 120,
    weakMagnitude: 1.0
  });
};

const [pad] = navigator.getGamepads().filter(Boolean);
if (pad) shootFeedback(pad).then((r) => console.log(r));

complete

Laufenden Effekt unterbrechen

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

if (actuator) {
  actuator
    .playEffect('dual-rumble', { duration: 3000, strongMagnitude: 1 })
    .then((result) => console.log('Langer Effekt:', result));

  // Nach 500 ms stoppen
  setTimeout(() => actuator.reset(), 500);
}

Langer Effekt: preempted

// Wichtig · Fallstricke

Browserunterstützung: Chromium-Browser (Chrome, Edge, Opera) unterstützen "dual-rumble" seit Langem. "trigger-rumble" funktioniert unter Windows nur mit passender Hardware. Safari unterstützt die Methode ab 16.4. Firefox bietet vibrationActuator erst seit Version 136 an. Ältere Firefox-Versionen kannten stattdessen das nicht standardisierte gamepad.hapticActuators mit pulse(). Prüfen Sie deshalb immer, ob vibrationActuator vorhanden ist, bevor Sie es verwenden.
Werte begrenzen: Liegen Stärken außerhalb von 0.0 bis 1.0 oder sind Zeiten negativ, wird das Promise mit TypeError abgelehnt. Die Dauer wird vom Browser gekürzt, in Chromium auf höchstens 5000 ms.
Unterbrechung: Jeder neue Aufruf beendet den laufenden Effekt. Dessen Promise wird dann mit "preempted" erfüllt, nicht abgelehnt. Behandeln Sie diesen Fall als normalen Ergebniswert.
Sichtbarkeit: Ist das Dokument verborgen, etwa in einem Hintergrund-Tab, lehnt der Browser den Aufruf ab oder bricht ihn ab.
Veraltete Objekte: Gamepad-Objekte sind in Chromium Momentaufnahmen. Holen Sie sich vor dem Aufruf mit navigator.getGamepads() ein aktuelles Objekt.
Kontext: Die Gamepad-API erfordert einen sicheren Kontext (HTTPS). Außerdem kann eine Permissions Policy (gamepad) sie sperren, etwa in iframes.
Barrierefreiheit: Setzen Sie Vibration sparsam ein und bieten Sie eine Einstellung an, mit der Nutzer sie abschalten können.

Siehe auch

Navigator.vibrate() GamepadHapticActuator.reset() GamepadHapticActuator.pulse() BarcodeDetector.detect() LanguageDetector.detect()