XRReferenceSpace: reset — Ereignis · JavaScript-Referenz

Signatur

referenceSpace.addEventListener("reset", handler)

Beschreibung

Das Ereignis reset wird ausgelöst, wenn das XR-System eine Diskontinuität im Ursprung eines Referenzraums feststellt. Die Position oder Ausrichtung des Koordinatensystems springt dann gegenüber der physischen Welt. Das kommt vor, wenn die Nutzerin das Headset neu zentriert (z. B. über die Systemtaste), wenn das Tracking verloren geht und wieder einsetzt oder wenn das System seine Raumkarte neu ausrichtet.

Der Handler bekommt ein XRReferenceSpaceEvent. Es hat die Eigenschaften referenceSpace (der betroffene Raum) und transform. transform ist ein XRRigidTransform, der die alte Lage des Ursprungs im neuen Koordinatensystem beschreibt. Kennt das System den Sprung nicht, ist der Wert null. Das Ereignis lässt sich per addEventListener("reset", …) abonnieren oder über die Eigenschaft onreset setzen.

Typische Aufgaben im Handler:

virtuelle Objekte, die an Weltkoordinaten verankert sind, mit transform umrechnen,
zwischengespeicherte Posen, Bewegungsverläufe und Interpolationen verwerfen,
bei bounded-floor-Räumen die geänderten boundsGeometry neu einlesen und die Begrenzung neu zeichnen.

Das Ereignis wird auch an Referenzräume weitergegeben, die mit getOffsetReferenceSpace() vom betroffenen Raum abgeleitet wurden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, immer `"reset"`.
$handler Pflicht	(event: XRReferenceSpaceEvent) => void		Callback, der ein `XRReferenceSpaceEvent` mit `referenceSpace` und `transform` (`XRRigidTransform \| null`) erhält.
$options	boolean \| AddEventListenerOptions	false	Übliche Listener-Optionen, z. B. `{ once: true }` oder `{ signal }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Die Informationen stehen im übergebenen XRReferenceSpaceEvent.

Beispiele

Reset per addEventListener erkennen und Anker korrigieren

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

// Anker der Szene (vereinfacht als DOMPointReadOnly-Liste)
let anchors = [new DOMPointReadOnly(0, 1.5, -2)];

refSpace.addEventListener('reset', (event) => {
  const { transform } = event;
  if (transform) {
    // alte Positionen ins neue Koordinatensystem umrechnen
    const m = new DOMMatrix(Array.from(transform.matrix));
    anchors = anchors.map((p) => m.transformPoint(p));
    console.log('Ursprung verschoben um', transform.position);
  } else {
    console.log('Reset ohne Transformation – Szene neu ausrichten');
  }
});

Ursprung verschoben um DOMPointReadOnly {x: 0.12, y: 0, z: -0.3, w: 1}

onreset-Eigenschaft und Aufräumen per removeEventListener

const session = await navigator.xr.requestSession('immersive-vr');
const viewerSpace = await session.requestReferenceSpace('local');

const poseHistory = [];

// Variante 1: on-Property
viewerSpace.onreset = () => {
  poseHistory.length = 0; // gespeicherte Posen sind ungültig
  console.log('Posenverlauf verworfen');
};

// Variante 2: benannter Listener, später entfernbar
const onReset = (e) => console.log('Reset in', e.referenceSpace);
viewerSpace.addEventListener('reset', onReset);

session.addEventListener('end', () => {
  viewerSpace.removeEventListener('reset', onReset);
  viewerSpace.onreset = null;
});

Posenverlauf verworfen Reset in XRReferenceSpace {...}

Begrenzung eines bounded-floor-Raums neu zeichnen

const session = await navigator.xr.requestSession('immersive-vr', {
  requiredFeatures: ['bounded-floor']
});
const bounded = await session.requestReferenceSpace('bounded-floor');

const drawBoundary = (space) => {
  const pts = space.boundsGeometry.map((p) => `(${p.x.toFixed(2)}, ${p.z.toFixed(2)})`);
  console.log('Begrenzung:', pts.join(' '));
};

drawBoundary(bounded);
bounded.addEventListener('reset', () => drawBoundary(bounded));

Begrenzung: (-1.50, -1.00) (1.50, -1.00) (1.50, 1.00) (-1.50, 1.00)

// Wichtig · Fallstricke

Kompatibilität: WebXR steht nur in Chromium-Browsern, im Meta Quest Browser und in einigen anderen XR-Browsern bereit. Firefox und Safari auf dem Desktop unterstützen es nicht. Außerdem ist ein sicherer Kontext (HTTPS) nötig. Prüfe vorab mit navigator.xr?.isSessionSupported().
event.transform kann null sein, etwa bei bounded-floor-Räumen oder wenn das System den Sprung nicht beziffern kann. Diesen Fall immer abfangen.
Im Referenzraum viewer wird kein reset ausgelöst, weil sein Ursprung immer am Kopf der Nutzerin liegt.
Wann genau das Ereignis kommt, legt das Gerät fest. Manche Systeme setzen den Ursprung neu, ohne reset auszulösen. Verlasse dich deshalb nicht darauf, dass es immer eintrifft.
Das Ereignis kommt außerhalb des requestAnimationFrame-Callbacks. Speichere im Handler nur eine Markierung oder die Transformation und wende die Korrektur im nächsten Frame an. So vermeidest du ein inkonsistentes Rendering.
Listener beim Sitzungsende (end) entfernen, damit keine Speicherlecks entstehen.

Siehe auch

XRReferenceSpace XRReferenceSpaceEvent XRRigidTransform XRReferenceSpace.getOffsetReferenceSpace() XRBoundedReferenceSpace XRSession.requestReferenceSpace() HTMLFormElement: reset