XRSession.end() — Methode · JavaScript-Referenz

Signatur

XRSession.prototype.end()

Beschreibung

Mit end() beendest du eine laufende WebXR-Sitzung per Programm, zum Beispiel über einen „VR verlassen“-Button, nach einem Spielende oder beim Verlassen der Seite. Die Methode gibt die XR-Hardware frei, beendet das Rendern auf dem Headset beziehungsweise die AR-Überlagerung und bringt den Nutzer in die normale 2D-Ansicht der Seite zurück.

Beim Aufruf passiert Folgendes: Die Sitzung wird als beendet markiert, alle noch ausstehenden requestAnimationFrame()-Rückrufe werden verworfen, und der Browser feuert auf der Sitzung das Ereignis end. Danach wird das zurückgegebene Promise erfüllt. Das end-Ereignis tritt übrigens auch dann auf, wenn der Nutzer oder das System die Sitzung beendet, etwa über den Systembutton des Headsets. Die Aufräumarbeiten (Zustand zurücksetzen, UI aktualisieren) gehören deshalb besser in den end-Listener als hinter das await session.end().

Eine beendete Sitzung lässt sich nicht wiederverwenden. Willst du erneut in XR einsteigen, musst du über navigator.xr.requestSession() eine neue Sitzung anfordern. Das braucht in der Regel wieder eine Nutzeraktion.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das ohne Wert erfüllt wird, sobald die Sitzung vollständig beendet ist und das Ereignis end ausgelöst wurde. Ist die Sitzung bereits beendet, wird es mit einer InvalidStateError-DOMException abgelehnt.

Beispiele

Sitzung über einen „VR verlassen“-Button beenden

let xrSession = null;
const button = document.querySelector('#xr-button');

button.addEventListener('click', async () => {
  if (xrSession) {
    // Laufende Sitzung beenden
    await xrSession.end();
    return;
  }
  xrSession = await navigator.xr.requestSession('immersive-vr');
  button.textContent = 'VR verlassen';

  // Aufräumen hier – greift auch, wenn das System die Sitzung beendet
  xrSession.addEventListener('end', () => {
    xrSession = null;
    button.textContent = 'VR starten';
    console.log('XR-Sitzung beendet');
  });
});

XR-Sitzung beendet

Sitzung automatisch nach Spielende schließen

const onXRFrame = (time, frame) => {
  const session = frame.session;
  if (game.isOver) {
    // Keinen weiteren Frame anfordern, Sitzung beenden
    session.end().then(() => showScoreScreen(game.score));
    return;
  }
  game.update(time, frame);
  session.requestAnimationFrame(onXRFrame);
};

xrSession.requestAnimationFrame(onXRFrame);

Mehrfaches Beenden abfangen

const safeEnd = async (session) => {
  try {
    await session.end();
    console.log('Sitzung geschlossen');
  } catch (err) {
    if (err.name === 'InvalidStateError') {
      console.log('Sitzung war bereits beendet');
    } else {
      throw err;
    }
  }
};

await safeEnd(xrSession);
await safeEnd(xrSession); // zweiter Aufruf

Sitzung geschlossen Sitzung war bereits beendet

// Wichtig · Fallstricke

Nicht doppelt aufrufen: Wird end() auf einer bereits beendeten Sitzung aufgerufen, wird das Promise mit InvalidStateError abgelehnt. Setze deine Sitzungsreferenz deshalb im end-Listener auf null.
Aufräumen im Ereignis, nicht nur nach await: Nutzer und System können eine Sitzung jederzeit beenden, ohne dass end() aufgerufen wird. Nur das end-Ereignis tritt in jedem dieser Fälle auf.
Ressourcen: Das XRWebGLLayer und die Referenzräume der alten Sitzung sind danach ungültig. Bei einer neuen Sitzung musst du sie neu anlegen. Den WebGL-Kontext selbst kannst du weiterverwenden.
Kompatibilität: WebXR steht nur in sicheren Kontexten (HTTPS) zur Verfügung und wird vor allem von Chromium-Browsern und den Browsern auf Headsets unterstützt. Firefox und Safari auf dem Desktop unterstützen es nicht, Safari auf der Apple Vision Pro dagegen schon. Prüfe vorher mit 'xr' in navigator, ob die API vorhanden ist.

Siehe auch

XRSession XRSystem.requestSession() XRSession.requestAnimationFrame() XRSession.visibilityState MediaKeySession.load() Permissions.revoke()