GamepadPose.orientation — Eigenschaft · JavaScript-Referenz

Signatur

GamepadPose.orientation

Beschreibung

GamepadPose.orientation beschreibt, wie ein Controller im Raum gedreht ist, etwa ein VR-Motion-Controller oder ein Gamepad mit Lagesensoren. Der Wert ist ein Float32Array mit vier Elementen [x, y, z, w]. Sie bilden ein Einheitsquaternion, das die Drehung gegenüber der Ruheausrichtung angibt. In der Ruheausrichtung zeigt der Controller in Richtung der negativen Z-Achse, also „nach vorn“, und die Y-Achse zeigt nach oben.

Du erreichst die Eigenschaft über gamepad.pose, wobei gamepad ein Objekt aus navigator.getGamepads() ist. Die Ausrichtung brauchst du vor allem in VR- und AR-Szenen, um ein 3D-Modell des Controllers, einen Zeigestrahl oder eine Waffe passend zur echten Handbewegung zu drehen. Quaternionen kannst du direkt an 3D-Bibliotheken wie three.js übergeben (Quaternion.fromArray()) oder bei Bedarf in Eulerwinkel umrechnen.

Kann das Gerät keine Ausrichtung melden, ist der Wert null. Das siehst du vorher an GamepadPose.hasOrientation. Lies die Pose in jedem Frame neu aus, am besten in einer requestAnimationFrame-Schleife: Die Gamepad-Objekte sind in vielen Browsern Momentaufnahmen und aktualisieren sich nicht selbst.

Rückgabewert

Typ

Float32Array | null

Beschreibung

Ein Float32Array mit vier Elementen [x, y, z, w], das die Drehung als Quaternion darstellt, oder null, wenn das Gerät keine Ausrichtung melden kann.

Beispiele

Ausrichtung in der Render-Schleife auslesen

const logOrientation = () => {
  for (const gamepad of navigator.getGamepads()) {
    // Leere Slots und Geräte ohne Pose überspringen
    if (!gamepad?.pose) continue;

    const { orientation } = gamepad.pose;
    if (orientation) {
      const [x, y, z, w] = orientation;
      console.log(`${gamepad.id}: x=${x.toFixed(3)} y=${y.toFixed(3)} z=${z.toFixed(3)} w=${w.toFixed(3)}`);
    }
  }
  requestAnimationFrame(logOrientation);
};

window.addEventListener('gamepadconnected', () => requestAnimationFrame(logOrientation));

OpenVR Controller: x=0.012 y=0.383 z=-0.004 w=0.924

Quaternion in Gierwinkel (Yaw) umrechnen

// Rechnet ein Quaternion [x, y, z, w] in Eulerwinkel (Grad) um, Y-Achse nach oben
const quatToEuler = ([x, y, z, w]) => {
  const toDeg = (rad) => rad * 180 / Math.PI;
  const yaw = Math.atan2(2 * (w * y + x * z), 1 - 2 * (y * y + x * x));
  const pitch = Math.asin(Math.max(-1, Math.min(1, 2 * (w * x - z * y))));
  const roll = Math.atan2(2 * (w * z + x * y), 1 - 2 * (x * x + z * z));
  return { yaw: toDeg(yaw), pitch: toDeg(pitch), roll: toDeg(roll) };
};

// Beispielwert: 90° Drehung um die Y-Achse
const orientation = new Float32Array([0, Math.SQRT1_2, 0, Math.SQRT1_2]);
const { yaw } = quatToEuler(orientation);
console.log(`Gierwinkel: ${Math.round(yaw)}°`);

Gierwinkel: 90°

Feature-Erkennung mit hasOrientation und Übergabe an three.js

// Voraussetzung: three.js ist geladen, controllerMesh ist ein THREE.Object3D
const updateController = (gamepad, controllerMesh) => {
  const pose = gamepad?.pose;
  if (!pose?.hasOrientation || !pose.orientation) {
    controllerMesh.visible = false; // Ohne Ausrichtung Modell ausblenden
    return;
  }
  controllerMesh.visible = true;
  controllerMesh.quaternion.fromArray(pose.orientation);
};

console.log('pose' in Gamepad.prototype ? 'GamepadPose verfügbar' : 'GamepadPose nicht unterstützt');

GamepadPose nicht unterstützt

// Wichtig · Fallstricke

Veraltet und experimentell: GamepadPose gehört zur WebVR-Erweiterung der Gamepad API. Die Schnittstelle war nur in wenigen Browsern verfügbar, etwa in älteren Firefox-Versionen und hinter Flags, und wurde inzwischen weitgehend entfernt. Nutze in neuen Projekten die WebXR Device API (XRInputSource.gripSpace zusammen mit XRFrame.getPose()).
Der Wert kann null sein. Prüfe deshalb immer vorher, zum Beispiel mit Optional Chaining oder über hasOrientation.
Die Reihenfolge ist [x, y, z, w], der Realteil w steht also am Ende. Manche Mathe-Bibliotheken erwarten w an erster Stelle.
Das zurückgegebene Array kann bei jedem Zugriff neu erzeugt werden. Wenn du den Wert später brauchst, kopiere ihn (Float32Array.from(...)), statt dich auf eine Live-Referenz zu verlassen.
Die Gamepad API funktioniert nur in sicheren Kontexten (HTTPS). Außerdem kann sie über Permissions-Policy (gamepad) eingeschränkt werden.

Siehe auch

GamepadPose GamepadPose.hasOrientation GamepadPose.position GamepadPose.angularVelocity Gamepad.pose Navigator.getGamepads() ContactAddress.organization