VRStageParameters.sizeX — Eigenschaft · JavaScript-Referenz

Signatur

VRStageParameters.sizeX

Beschreibung

Die Eigenschaft sizeX des Interfaces VRStageParameters gibt die Breite des begehbaren Spielfelds entlang der X-Achse in Metern an. Das Spielfeld ist ein Rechteck. Sein Mittelpunkt liegt im Ursprung des Stage-Koordinatensystems, das über sittingToStandingTransform definiert ist. Zusammen mit sizeZ (Tiefe) beschreibt sizeX damit den Bereich, in dem sich Nutzende eines Room-Scale-Systems (z. B. HTC Vive) sicher bewegen können.

Sinnvoll ist der Wert, um die virtuelle Szene an den echten Raum anzupassen: Man kann Bodenmarkierungen oder Begrenzungsgitter zeichnen, Objekte innerhalb der erreichbaren Fläche platzieren oder warnen, wenn der Raum für eine Anwendung zu klein ist. Die Grenzen reichen von -sizeX / 2 bis +sizeX / 2.

Man erreicht die Eigenschaft über VRDisplay.stageParameters. Diese liefert null, wenn das Gerät kein Room-Scale-Tracking unterstützt. Ist keine Spielfeldgröße konfiguriert, kann sizeX den Wert 0 haben.

Wichtig: Die gesamte WebVR-API ist veraltet und wurde durch die WebXR Device API ersetzt. Dort übernimmt XRBoundedReferenceSpace.boundsGeometry diese Aufgabe.

Rückgabewert

Typ

number

Beschreibung

Breite der Spielfeldgrenzen in Metern (Gleitkommazahl). Kann 0 sein, wenn keine Grenzen konfiguriert sind.

Beispiele

Spielfeldgröße auslesen

const showStageSize = async () => {
  if (!navigator.getVRDisplays) {
    console.log('WebVR wird nicht unterstützt.');
    return;
  }
  const [display] = await navigator.getVRDisplays();
  const stage = display?.stageParameters;
  if (!stage) {
    console.log('Kein Room-Scale-Tracking verfügbar.');
    return;
  }
  console.log(`Spielfeld: ${stage.sizeX.toFixed(2)} m × ${stage.sizeZ.toFixed(2)} m`);
};

showStageSize();

Spielfeld: 3.00 m × 2.50 m

Mindestgröße für eine Anwendung prüfen

const MIN_WIDTH = 2.0; // Meter

const checkRoom = (display) => {
  const stage = display.stageParameters;
  if (!stage || stage.sizeX === 0) {
    return 'Keine Spielfeldgrenzen konfiguriert – stehender Modus.';
  }
  return stage.sizeX >= MIN_WIDTH
    ? 'Raum ist groß genug.'
    : `Raum zu schmal: ${stage.sizeX} m (mindestens ${MIN_WIDTH} m nötig).`;
};

navigator.getVRDisplays().then(([display]) => {
  if (display) console.log(checkRoom(display));
});

Raum zu schmal: 1.6 m (mindestens 2 m nötig).

Eckpunkte der Begrenzung berechnen

// Liefert die vier Bodenecken (x, y, z) im Stage-Koordinatensystem
const getStageCorners = ({ sizeX, sizeZ }) => {
  const hx = sizeX / 2;
  const hz = sizeZ / 2;
  return [
    [-hx, 0, -hz],
    [ hx, 0, -hz],
    [ hx, 0,  hz],
    [-hx, 0,  hz]
  ];
};

// Beispiel mit Beispielwerten statt echtem Gerät
console.log(getStageCorners({ sizeX: 3, sizeZ: 2 }));

[[-1.5, 0, -1], [1.5, 0, -1], [1.5, 0, 1], [-1.5, 0, 1]]

// Wichtig · Fallstricke

Veraltet: WebVR wurde nie standardisiert und ist aus Chrome und Firefox entfernt. Für neue Projekte ist die WebXR Device API zu verwenden, z. B. session.requestReferenceSpace('bounded-floor') und dann boundsGeometry.
VRDisplay.stageParameters kann null sein. Prüfe das immer vor dem Zugriff auf sizeX, sonst entsteht ein TypeError.
Ein Wert von 0 bedeutet nicht, dass der Raum null Meter breit ist. Er heißt nur, dass keine Grenzen eingerichtet wurden.
Das Spielfeld wird als Rechteck angenähert. Tatsächliche Raumgrenzen können unregelmäßig geformt sein.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird still ignoriert bzw. löst im Strict Mode einen Fehler aus.

Siehe auch

VRStageParameters VRStageParameters.sittingToStandingTransform VRDisplay.stageParameters XRBoundedReferenceSpace.boundsGeometry CSSStyleProperties.cssFloat RTCStatsReport.size