Gamepad.displayId — Eigenschaft · JavaScript-Referenz

Signatur

Gamepad.displayId

Beschreibung

Die Eigenschaft displayId gehört zur Erweiterung der Gamepad-Schnittstelle durch die inzwischen veraltete WebVR-API. Sie gibt die Kennung (VRDisplay.displayId) des VRDisplay zurück, zu dem ein Controller gehört. Dieses Display steuert die Szene, in der der Controller dargestellt und bedient wird, zum Beispiel ein VR-Headset mit den dazugehörigen Hand-Controllern.

Gebraucht wurde die Eigenschaft vor allem, wenn mehrere VR-Displays angeschlossen waren. Damit ließ sich herausfinden, welche Controller zu welchem Headset gehören, und die Eingaben ließen sich in der richtigen Szene verarbeiten. Ist ein Gamepad keinem Display zugeordnet (etwa ein normaler Xbox-Controller), ist der Wert 0.

Wichtig: WebVR wurde vollständig durch die WebXR Device API ersetzt. Dort gehören Controller über XRInputSource.gamepad direkt zu einer XRSession. Eine Zuordnung per ID ist deshalb nicht mehr nötig. Neuer Code sollte displayId nicht mehr verwenden.

Rückgabewert

Typ

number

Beschreibung

Die displayId des zugehörigen VRDisplay als ganze Zahl oder 0, wenn das Gamepad keinem VR-Display zugeordnet ist. In Browsern ohne WebVR ist die Eigenschaft undefined.

Beispiele

displayId beim Verbinden eines Controllers auslesen

window.addEventListener('gamepadconnected', (event) => {
  const { gamepad } = event;
  if (!('displayId' in gamepad)) {
    console.log('WebVR-Erweiterung wird nicht unterstützt.');
    return;
  }
  console.log(`Gamepad ${gamepad.index}: displayId = ${gamepad.displayId}`);
});

Gamepad 0: displayId = 1

Controller dem passenden VR-Headset zuordnen

const findControllersForDisplay = async () => {
  if (!navigator.getVRDisplays) {
    console.log('WebVR nicht verfügbar – bitte WebXR verwenden.');
    return;
  }
  const displays = await navigator.getVRDisplays();
  const pads = navigator.getGamepads().filter(Boolean);

  for (const display of displays) {
    const controllers = pads.filter((p) => p.displayId === display.displayId);
    console.log(`${display.displayName}: ${controllers.length} Controller`);
  }
};

findControllersForDisplay();

Oculus Rift CV1: 2 Controller

Normale Gamepads von VR-Controllern unterscheiden

const pads = navigator.getGamepads().filter(Boolean);

const vrControllers = pads.filter((p) => (p.displayId ?? 0) !== 0);
const regularPads = pads.filter((p) => (p.displayId ?? 0) === 0);

console.log('VR-Controller:', vrControllers.map((p) => p.id));
console.log('Normale Gamepads:', regularPads.map((p) => p.id));

VR-Controller: ["OpenVR Gamepad"] Normale Gamepads: ["Xbox 360 Controller (XInput STANDARD GAMEPAD)"]

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: Die Eigenschaft stammt aus der WebVR-API, die offiziell aufgegeben wurde. Unterstützt wurde sie nur in älteren Firefox-Versionen und experimentellen Chromium-Builds. Aktuelle Browser liefern meist undefined.
Vor dem Zugriff mit 'displayId' in gamepad prüfen, ob die Eigenschaft vorhanden ist, oder mit ?? 0 einen Standardwert setzen.
Der Wert 0 heißt „keinem Display zugeordnet“ und ist keine gültige Display-ID.
Die Gamepad-API ist nur in sicheren Kontexten (HTTPS) verfügbar und kann durch eine Permissions Policy (gamepad) gesperrt sein.
Als Ersatz XRSession.inputSources und XRInputSource.gamepad aus der WebXR Device API verwenden.

Siehe auch

Gamepad VRDisplay.displayId Navigator.getGamepads() Navigator.getVRDisplays() XRInputSource.gamepad PaymentAddress.city