GamepadPose.hasPosition — Eigenschaft · JavaScript-Referenz

Signatur

GamepadPose.hasPosition

Beschreibung

Die Eigenschaft hasPosition des GamepadPose-Interfaces zeigt an, ob der Controller Positionsdaten liefern kann. Ist sie true, enthalten GamepadPose.position sowie ggf. linearVelocity und linearAcceleration sinnvolle Werte. Ist sie false, kann der Controller höchstens seine Ausrichtung melden (3 Freiheitsgrade, 3DoF), etwa ein einfacher VR-Zeiger-Controller.

Man fragt hasPosition typischerweise einmalig nach dem Verbinden eines Gamepads ab, um die Darstellung in einer VR-Szene anzupassen: Controller mit Positionsverfolgung werden frei im Raum gerendert, reine Orientierungs-Controller werden an eine geschätzte Position (z. B. neben der Hüfte des Nutzers) „angeheftet“.

Die Eigenschaft gehört zur experimentellen Gamepad Extensions-Spezifikation, die zusammen mit WebVR entstand. Erreichbar ist sie über Gamepad.pose. Wichtig: Auch bei hasPosition === true kann position kurzzeitig null sein, wenn die Verfolgung (z. B. durch Verdeckung) verloren geht.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Gamepad Positionsinformationen verfolgen und liefern kann, sonst false.

Beispiele

Fähigkeit beim Verbinden prüfen

window.addEventListener('gamepadconnected', (event) => {
  const { pose, id } = event.gamepad;
  if (!pose) {
    console.log(`${id}: keine Pose-Unterstützung`);
    return;
  }
  console.log(`${id}: Positionsverfolgung = ${pose.hasPosition}`);
});

OpenVR Gamepad: Positionsverfolgung = true

Position im Render-Loop sicher auslesen

const DEFAULT_OFFSET = [0.2, -0.5, -0.3]; // geschätzte Hüftposition

const getControllerPosition = (gamepad) => {
  const pose = gamepad?.pose;
  if (pose?.hasPosition && pose.position) {
    return Array.from(pose.position);
  }
  // 3DoF-Controller oder Tracking verloren: Ersatzposition
  return DEFAULT_OFFSET;
};

const loop = () => {
  for (const gp of navigator.getGamepads()) {
    if (gp) console.log(gp.index, getControllerPosition(gp));
  }
  requestAnimationFrame(loop);
};
requestAnimationFrame(loop);

0 [0.12, 1.05, -0.4]

Controller nach Freiheitsgraden klassifizieren

const classify = (pose) => {
  if (!pose) return 'kein Tracking';
  if (pose.hasPosition && pose.hasOrientation) return '6DoF';
  if (pose.hasOrientation) return '3DoF (nur Rotation)';
  return 'unbekannt';
};

const gamepads = navigator.getGamepads().filter(Boolean);
gamepads.forEach((gp) => console.log(gp.id, '→', classify(gp.pose)));

Daydream Controller → 3DoF (nur Rotation)

// Wichtig · Fallstricke

Experimentell und veraltet: GamepadPose war nur in Firefox (hinter dom.gamepad.extensions.enabled) bzw. in frühen WebVR-Builds verfügbar. Für neue Projekte die WebXR Device API verwenden (XRInputSource, XRFrame.getPose()).
gamepad.pose kann null oder undefined sein – immer mit optionaler Verkettung (?.) prüfen.
hasPosition beschreibt nur die Fähigkeit; position kann trotzdem null sein, wenn das Tracking vorübergehend ausfällt.
Die Gamepad-API liefert Daten meist nur in sicheren Kontexten (HTTPS) und nach einer Nutzerinteraktion mit dem Gerät.

Siehe auch

GamepadPose GamepadPose.hasOrientation GamepadPose.position Gamepad.pose Navigator.getGamepads() XRInputSource PageSwapEvent.viewTransition