GamepadHapticActuator.pulse() — Methode · JavaScript-Referenz

Signatur

GamepadHapticActuator.prototype.pulse(value, duration)

Beschreibung

Die Methode pulse() des Interfaces GamepadHapticActuator startet am Controller einen einfachen Vibrationsimpuls. Sie erwartet zwei Werte: die Stärke (value, von 0.0 bis 1.0) und die Dauer (duration) in Millisekunden. Zurück kommt ein Promise, das mit true erfüllt wird, wenn der Impuls erfolgreich ausgelöst wurde.

Einen Aktor bekommst du in Firefox über das Array Gamepad.hapticActuators. Vor allem VR-Controller (z. B. Oculus Touch, HTC Vive) stellen dort Aktoren vom Typ "vibration" bereit. Typische Einsatzfälle sind kurzes haptisches Feedback bei Treffern, Kollisionen oder beim Drücken virtueller Knöpfe.

Wichtig: pulse() gehört nicht zum aktuellen Standard der Gamepad-API. Chromium-Browser und Safari setzen stattdessen auf Gamepad.vibrationActuator mit der Methode playEffect() (Effekt "dual-rumble" oder "trigger-rumble"). Wer browserübergreifend entwickeln will, sollte deshalb vor jedem Aufruf prüfen, welche Variante vorhanden ist, und notfalls auf die andere ausweichen.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	number		Stärke des Impulses von `0.0` (aus) bis `1.0` (maximal). Werte außerhalb dieses Bereichs werden auf die Grenzen gekürzt.
$duration Pflicht	number		Dauer des Impulses in Millisekunden. Die Hardware kann eine eigene Höchstdauer haben.

Rückgabewert

Typ

Promise<boolean>

Beschreibung

Ein Promise, das mit true erfüllt wird, wenn der Impuls erfolgreich ausgelöst wurde, und sonst mit false.

Beispiele

Einfacher Impuls beim ersten verbundenen Gamepad

window.addEventListener('gamepadconnected', async (event) => {
  const gamepad = event.gamepad;
  const actuator = gamepad.hapticActuators?.[0];

  if (actuator && typeof actuator.pulse === 'function') {
    // halbe Stärke, 200 ms lang
    const ok = await actuator.pulse(0.5, 200);
    console.log('Impuls ausgelöst:', ok);
  } else {
    console.log('pulse() wird nicht unterstützt');
  }
});

Impuls ausgelöst: true

Browserübergreifendes Feedback mit Ausweichlösung über playEffect()

const vibrate = async (gamepad, intensity = 1, duration = 150) => {
  // Firefox: hapticActuators + pulse()
  const legacy = gamepad.hapticActuators?.[0];
  if (legacy?.pulse) {
    return legacy.pulse(intensity, duration);
  }
  // Chromium/Safari: vibrationActuator + playEffect()
  const modern = gamepad.vibrationActuator;
  if (modern?.playEffect) {
    const result = await modern.playEffect('dual-rumble', {
      duration,
      strongMagnitude: intensity,
      weakMagnitude: intensity / 2
    });
    return result === 'complete';
  }
  return false;
};

// Im Spiel-Loop bei einem Treffer aufrufen
const onHit = async () => {
  const [pad] = navigator.getGamepads().filter(Boolean);
  if (pad) console.log('Feedback:', await vibrate(pad, 0.8, 120));
};

Feedback: true

Rhythmische Pulsfolge (Herzschlag-Effekt)

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

const heartbeat = async (actuator, beats = 3) => {
  for (let i = 0; i < beats; i++) {
    await actuator.pulse(1.0, 80);
    await sleep(120);
    await actuator.pulse(0.6, 60);
    await sleep(500);
  }
};

const pad = navigator.getGamepads().find((g) => g?.hapticActuators?.length);
if (pad) heartbeat(pad.hapticActuators[0]);

// Wichtig · Fallstricke

Browserunterstützung: pulse() und Gamepad.hapticActuators gibt es nur in Firefox, und selbst dort teilweise nur hinter Einstellungen wie dom.gamepad.extensions.enabled. Chrome, Edge und Safari bieten stattdessen vibrationActuator.playEffect() an. Prüfe deshalb immer vorher, ob die Methode vorhanden ist.
Das Promise wird sofort erfüllt: Es wartet nicht, bis der Impuls zu Ende ist. Wenn du mehrere Impulse hintereinander abspielen willst, musst du die Pausen selbst einplanen, zum Beispiel mit setTimeout.
Neuer Aufruf ersetzt den alten: Ruft man pulse() erneut auf, während noch ein Impuls läuft, wird der laufende in der Regel ersetzt.
Nutzer-Interaktion nötig: Die Gamepad-API liefert erst Daten, wenn der Nutzer eine Taste am Controller gedrückt hat. Außerdem funktioniert sie nur in einem sicheren Kontext (HTTPS) und kann durch die Permissions-Policy gamepad gesperrt werden.
Hardware: Nicht jeder Controller besitzt einen Vibrationsmotor. Ein leeres Array hapticActuators ist deshalb ganz normal.
Barrierefreiheit: Setze Vibration sparsam ein und biete eine Einstellung an, mit der man sie abschalten kann.

Siehe auch

GamepadHapticActuator GamepadHapticActuator.playEffect() GamepadHapticActuator.reset() Gamepad.hapticActuators Gamepad.vibrationActuator Navigator.getGamepads()