Signatur
Beschreibung
Die schreibgeschützte Eigenschaft referenceSpace eines XRReferenceSpaceEvent verweist auf den XRReferenceSpace, der das Ereignis ausgelöst hat. Derzeit ist das einzige Ereignis dieses Typs reset. Es wird gefeuert, wenn der Browser bzw. das XR-Gerät den Ursprung des Referenzraums neu festlegt, etwa wenn der Nutzer die Ansicht neu zentriert oder das Tracking verloren gegangen ist und wiederhergestellt wurde.
Die Eigenschaft ist vor allem nützlich, wenn ein gemeinsamer Handler für mehrere Referenzräume registriert ist (z. B. local und bounded-floor). Über event.referenceSpace lässt sich dann feststellen, welcher Raum betroffen ist. Daraufhin kann die Anwendung zum Beispiel davon abgeleitete Räume neu berechnen (getOffsetReferenceSpace()), zwischengespeicherte Posen verwerfen oder bei XRBoundedReferenceSpace die Begrenzung (boundsGeometry) neu einlesen.
Der Wert entspricht in der Regel event.target. Er wird aber beim Erzeugen des Ereignisses fest gesetzt und lässt sich danach nicht mehr ändern.
Rückgabewert
XRBoundedReferenceSpace sein.Beispiele
Auf reset reagieren und den betroffenen Raum ermitteln
const session = await navigator.xr.requestSession('immersive-vr');
const localSpace = await session.requestReferenceSpace('local');
localSpace.addEventListener('reset', (event) => {
// event.referenceSpace ist der Raum, der zurückgesetzt wurde
console.log('Zurückgesetzt:', event.referenceSpace === localSpace);
console.log('Neue Ursprungs-Transformation:', event.transform);
});Gemeinsamer Handler für mehrere Referenzräume
const session = await navigator.xr.requestSession('immersive-vr', {
optionalFeatures: ['bounded-floor']
});
const spaces = {
local: await session.requestReferenceSpace('local'),
floor: await session.requestReferenceSpace('bounded-floor').catch(() => null)
};
const handleReset = ({ referenceSpace }) => {
if (referenceSpace instanceof XRBoundedReferenceSpace) {
// Spielfeldgrenzen können sich geändert haben
console.log('Neue Grenzpunkte:', referenceSpace.boundsGeometry.length);
} else {
console.log('Lokaler Raum neu zentriert');
}
};
Object.values(spaces)
.filter(Boolean)
.forEach((space) => space.addEventListener('reset', handleReset));Abgeleiteten Offset-Raum nach reset neu aufbauen (onreset)
const session = await navigator.xr.requestSession('immersive-vr');
const baseSpace = await session.requestReferenceSpace('local');
const offset = new XRRigidTransform({ x: 0, y: -1.6, z: 0 });
let viewerSpace = baseSpace.getOffsetReferenceSpace(offset);
baseSpace.onreset = (event) => {
// Offset-Raum auf Basis des zurückgesetzten Raums neu erzeugen
viewerSpace = event.referenceSpace.getOffsetReferenceSpace(offset);
console.log('Offset-Raum aktualisiert');
};Ereignis manuell erzeugen (z. B. für Tests)
const session = await navigator.xr.requestSession('inline');
const space = await session.requestReferenceSpace('viewer');
const evt = new XRReferenceSpaceEvent('reset', { referenceSpace: space });
console.log(evt.referenceSpace === space);// Wichtig · Fallstricke
- Schreibgeschützt: Eine Zuweisung an
event.referenceSpacewird ignoriert bzw. löst im Strict Mode einenTypeErroraus. - Nur sichere Kontexte: WebXR steht nur über HTTPS (oder
localhost) zur Verfügung. Außerdem kann eine Permissions Policy (xr-spatial-tracking) den Zugriff sperren. - Browser-Unterstützung: Chromium-basierte Browser (Chrome, Edge, Samsung Internet) und der Meta Quest Browser unterstützen WebXR. Safari und Firefox auf dem Desktop tun es nicht. Prüfe vorher mit
'xr' in navigator. - Kein Ereignis für jede Bewegung:
resetwird nur bei einem Sprung des Ursprungs ausgelöst, nicht bei normaler Kopfbewegung. Nicht jede Plattform löst das Ereignis zuverlässig aus. Beim Raumtypviewertritt es praktisch nie auf. event.transformkannnullsein, wenn der Browser die Differenz zwischen altem und neuem Ursprung nicht kennt. Die EigenschaftreferenceSpaceist dagegen immer gesetzt.