XRReferenceSpaceEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface XRReferenceSpaceEvent extends Event

Beschreibung

XRReferenceSpaceEvent ist der Ereignistyp, den die WebXR Device API an ein XRReferenceSpace-Objekt sendet. In der Praxis gibt es nur ein Event dieses Typs: reset. Es wird ausgelöst, wenn das XR-System den Ursprung des Referenzraums sprunghaft verschiebt, statt ihn fließend nachzuführen. Typische Auslöser: Der Nutzer zentriert die Ansicht über das Systemmenü neu, das Tracking geht verloren und wird mit neuem Ursprung wieder aufgenommen, oder der Spielbereich (bounded-floor) wird neu eingerichtet.

Zusätzlich zu den Eigenschaften von Event stellt das Interface zwei schreibgeschützte Eigenschaften bereit:

referenceSpace – der XRReferenceSpace, der das Event ausgelöst hat.
transform – ein XRRigidTransform (oder null), der den Ursprung des Raums nach dem Zurücksetzen im Koordinatensystem von vorher beschreibt. Ist er bekannt, kann die Anwendung damit gespeicherte Positionen (z. B. Objekte, Kamerapfade, Teleport-Offsets) umrechnen.

Das Event behandelt man, damit die Szene nach einem Sprung stimmig bleibt, also etwa um Physik-Zustände oder interpolierte Bewegungen zurückzusetzen oder um mit getOffsetReferenceSpace() berechnete Offsets neu aufzubauen. Den Konstruktor ruft man selbst nur selten auf, zum Beispiel in Tests oder für eigene Event-Weiterleitungen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Für XR-Referenzräume ist das in der Praxis immer `"reset"`.
$eventInitDict Pflicht	object		Initialisierungsobjekt. Erweitert `EventInit` (`bubbles`, `cancelable`, `composed`) um `referenceSpace` (`XRReferenceSpace`, Pflichtangabe) und `transform` (`XRRigidTransform` oder `null`, optional).

Rückgabewert

Typ

XRReferenceSpaceEvent

Beschreibung

Ein neues Ereignisobjekt, sofern der Konstruktor new XRReferenceSpaceEvent(type, eventInitDict) aufgerufen wird. Die Eigenschaften referenceSpace (XRReferenceSpace) und transform (XRRigidTransform | null) sind schreibgeschützt.

Beispiele

reset-Event per addEventListener behandeln

const startXR = async () => {
  const session = await navigator.xr.requestSession('immersive-vr');
  const refSpace = await session.requestReferenceSpace('local-floor');

  refSpace.addEventListener('reset', (event) => {
    // event ist ein XRReferenceSpaceEvent
    console.log('Referenzraum zurückgesetzt:', event.referenceSpace === refSpace);
    if (event.transform) {
      const { x, y, z } = event.transform.position;
      console.log(`Neuer Ursprung (im alten System): ${x.toFixed(2)}, ${y.toFixed(2)}, ${z.toFixed(2)}`);
    } else {
      console.log('Transformation unbekannt – Szene neu ausrichten.');
    }
  });
};

// Muss aus einer Nutzeraktion heraus gestartet werden
document.querySelector('#enter-vr').addEventListener('click', startXR);

Referenzraum zurückgesetzt: true Neuer Ursprung (im alten System): 0.35, 0.00, -1.20

Gespeicherte Positionen mit transform umrechnen (onreset)

// Ankerpunkte, die die App im Referenzraum verwaltet
const anchors = [
  new DOMPointReadOnly(0, 1, -2),
  new DOMPointReadOnly(1, 1, -1)
];

const updateAnchors = (event) => {
  if (!event.transform) return;
  // transform beschreibt den neuen Ursprung im alten System –
  // die Inverse rechnet alte Koordinaten in das neue System um
  const m = event.transform.inverse.matrix;
  for (let i = 0; i < anchors.length; i++) {
    const p = anchors[i];
    anchors[i] = new DOMPointReadOnly(
      m[0] * p.x + m[4] * p.y + m[8] * p.z + m[12],
      m[1] * p.x + m[5] * p.y + m[9] * p.z + m[13],
      m[2] * p.x + m[6] * p.y + m[10] * p.z + m[14]
    );
  }
  console.log('Anker aktualisiert:', anchors.length);
};

// Alternative zu addEventListener: die on-Eigenschaft
refSpace.onreset = updateAnchors;

// Später wieder abmelden
// refSpace.onreset = null;

Anker aktualisiert: 2

Event für Tests manuell erzeugen und auslösen

// Voraussetzung: aktive XRSession mit Referenzraum refSpace
const fakeReset = new XRReferenceSpaceEvent('reset', {
  referenceSpace: refSpace,
  transform: new XRRigidTransform({ x: 0, y: 0, z: -0.5 })
});

const onReset = (e) => console.log('Test-Reset, z =', e.transform.position.z);
refSpace.addEventListener('reset', onReset);
refSpace.dispatchEvent(fakeReset);
refSpace.removeEventListener('reset', onReset);

Test-Reset, z = -0.5

// Wichtig · Fallstricke

Kompatibilität: WebXR und damit XRReferenceSpaceEvent gibt es nur in Chromium-basierten Browsern (Chrome, Edge, Samsung Internet, Meta Quest Browser). In Firefox und Safari auf dem Desktop fehlt die Schnittstelle, Apple Vision Pro unterstützt WebXR nur teilweise. Vor der Nutzung mit 'xr' in navigator und navigator.xr.isSessionSupported() prüfen.
Nur in sicheren Kontexten (HTTPS) verfügbar. Sessions lassen sich nur nach einer Nutzeraktion starten, außerdem kann eine Permissions Policy (xr-spatial-tracking) den Zugriff in iframes sperren.
transform kann null sein, wenn das System den Sprung nicht beziffern kann, etwa nach komplettem Tracking-Verlust. Die Anwendung muss diesen Fall gesondert behandeln.
Referenzräume vom Typ viewer lösen in der Regel kein reset aus. Bei local, local-floor und bounded-floor ist es dagegen üblich. Bei bounded-floor können sich nach einem Reset auch die boundsGeometry ändern.
Räume, die mit getOffsetReferenceSpace() abgeleitet wurden, lösen ebenfalls ein eigenes reset aus, wenn ihr Basisraum zurückgesetzt wird. Dabei ist das transform in das Koordinatensystem des Offset-Raums umgerechnet.
Das Event kommt asynchron an. Posen aus Frames, die vor dem Event abgefragt wurden, können sich noch auf den alten Ursprung beziehen.

Siehe auch

Event XRReferenceSpace BufferedChangeEvent PreferenceManager PreferenceObject