GamepadHapticActuator.type — Eigenschaft · JavaScript-Referenz

Signatur

GamepadHapticActuator.type

Beschreibung

Die Eigenschaft type eines GamepadHapticActuator-Objekts gibt einen Wert des Aufzählungstyps GamepadHapticActuatorType zurück. Er beschreibt, welche Art von haptischer Hardware (Vibrationsmotoren) im Controller steckt. Mögliche Werte sind:

"vibration" – einfache Vibration mit einstellbarer Stärke und Dauer (ältere Firefox-Implementierung, pulse()).
"dual-rumble" – zwei exzentrische Motoren (stark/niederfrequent und schwach/hochfrequent), wie in Xbox- und PlayStation-Controllern üblich.
"trigger-rumble" – zusätzlich einzeln ansteuerbare Motoren in den Schultertasten (Trigger), z. B. beim Xbox-One-Controller.

Die Eigenschaft half früher dabei, vor dem Aufruf von playEffect() oder pulse() festzustellen, welche Effekte ein Controller überhaupt beherrscht. Der aktuelle Spezifikationsentwurf ersetzt type durch die Eigenschaft effects, ein Array aller unterstützten Effekttypen. Neuer Code sollte deshalb zuerst effects abfragen und type nur als Rückfallebene für ältere Browser verwenden.

Den Aktor erreicht man in Chromium-Browsern über gamepad.vibrationActuator, in Firefox (hinter einem Flag) über das Array gamepad.hapticActuators. Die Eigenschaft ist schreibgeschützt. Zuweisungen werden ignoriert.

Rückgabewert

Typ

"vibration" | "dual-rumble" | "trigger-rumble"

Beschreibung

Eine Zeichenkette aus der Aufzählung GamepadHapticActuatorType, die die Art der haptischen Hardware beschreibt.

Beispiele

Typ des Vibrationsmotors nach dem Verbinden auslesen

window.addEventListener('gamepadconnected', (event) => {
  const gamepad = event.gamepad;
  // Chromium: vibrationActuator, Firefox (Flag): hapticActuators[0]
  const actuator = gamepad.vibrationActuator ?? gamepad.hapticActuators?.[0];

  if (!actuator) {
    console.log(`${gamepad.id}: keine Vibration verfügbar`);
    return;
  }
  console.log(`${gamepad.id}: Aktor-Typ = ${actuator.type}`);
});

Xbox 360 Controller (XInput STANDARD GAMEPAD): Aktor-Typ = dual-rumble

Rumble-Effekt nur bei passendem Typ abspielen (mit effects-Fallback)

const supportsEffect = (actuator, effect) => {
  // Neuer Standard: effects-Array, alt: type-Eigenschaft
  if (Array.isArray(actuator.effects)) {
    return actuator.effects.includes(effect);
  }
  return actuator.type === effect;
};

const rumble = async (gamepadIndex) => {
  const gamepad = navigator.getGamepads()[gamepadIndex];
  const actuator = gamepad?.vibrationActuator;
  if (!actuator || !supportsEffect(actuator, 'dual-rumble')) {
    console.log('Dual-Rumble wird nicht unterstützt');
    return;
  }
  const result = await actuator.playEffect('dual-rumble', {
    startDelay: 0,
    duration: 300,
    weakMagnitude: 0.5,
    strongMagnitude: 1.0
  });
  console.log(result);
};

rumble(0);

complete

Unterschiedliche Feedback-Strategie je nach Hardware

const giveFeedback = (gamepad) => {
  const actuator = gamepad.vibrationActuator ?? gamepad.hapticActuators?.[0];
  if (!actuator) return 'kein Feedback';

  switch (actuator.type) {
    case 'trigger-rumble':
      actuator.playEffect('trigger-rumble', { duration: 200, leftTrigger: 0.8, rightTrigger: 0.8 });
      return 'Trigger-Rumble';
    case 'dual-rumble':
      actuator.playEffect('dual-rumble', { duration: 200, strongMagnitude: 0.8, weakMagnitude: 0.4 });
      return 'Dual-Rumble';
    case 'vibration':
      actuator.pulse(0.8, 200); // alte Firefox-API
      return 'Vibration';
    default:
      return 'unbekannter Typ';
  }
};

const pad = navigator.getGamepads().find(Boolean);
if (pad) console.log(giveFeedback(pad));

Dual-Rumble

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: Im aktuellen Spezifikationsentwurf wurde type durch GamepadHapticActuator.effects ersetzt. Prüfe zuerst effects und nutze type nur als Rückfallebene.
Nur ein Wert: type liefert genau einen Typ. Ein Controller mit Trigger-Motoren kann trotzdem "dual-rumble" melden, obwohl er zusätzlich "trigger-rumble" beherrscht. Ob ein Effekt wirklich funktioniert, zeigt erst das Ergebnis von playEffect().
Browser-Unterschiede: Chromium-Browser stellen den Aktor über gamepad.vibrationActuator bereit. Firefox nutzt gamepad.hapticActuators mit Typ "vibration" und pulse(), aber nur hinter dem Flag dom.gamepad.haptic_feedback.enabled. Safari unterstützt vibrationActuator erst in neueren Versionen. Frage die Eigenschaft deshalb immer mit Optional Chaining (?.) ab.
Momentaufnahmen: In Chromium sind Gamepad-Objekte Momentaufnahmen. Hole den Aktor vor jeder Nutzung neu über navigator.getGamepads().
Sichere Umgebung: Die Gamepad API steht in aktuellen Browsern nur in sicheren Kontexten (HTTPS) zur Verfügung. Außerdem kann sie per Permissions-Policy gamepad gesperrt sein.

Siehe auch

GamepadHapticActuator GamepadHapticActuator.playEffect() GamepadHapticActuator.effects GamepadHapticActuator.pulse() Gamepad.vibrationActuator Navigator.getGamepads() TrustedTypePolicyFactory.emptyScript