VRStageParameters.sizeY — Eigenschaft · JavaScript-Referenz

Signatur

VRStageParameters.sizeY

Beschreibung

Die Eigenschaft sizeY der Schnittstelle VRStageParameters gibt die Tiefe der Spielbereichsgrenzen in Metern an. Zusammen mit sizeX (Breite) beschreibt sie ein Rechteck auf dem Boden, in dem sich Nutzer bei „Room-Scale“-Anwendungen gefahrlos bewegen können. Trotz des Namens „Y“ ist damit nicht die Höhe gemeint, sondern die Ausdehnung entlang der Z-Achse des Stage-Koordinatensystems.

An das Objekt kommt man über VRDisplay.stageParameters. Ist diese Eigenschaft null, unterstützt das Gerät keine Stage-Tracking-Daten (z. B. reine Sitz- oder Mobil-Headsets). Werte von 0 bedeuten meist, dass zwar Stage-Unterstützung vorhanden ist, der Spielbereich aber (noch) nicht eingerichtet wurde.

Typischer Einsatzzweck: den virtuellen Boden, Begrenzungsgitter oder die Platzierung interaktiver Objekte so zu skalieren, dass alles innerhalb des physisch verfügbaren Raums erreichbar bleibt. Der Rechteck-Mittelpunkt liegt im Ursprung des durch sittingToStandingTransform definierten Koordinatensystems.

Rückgabewert

Typ

number

Beschreibung

Tiefe des Spielbereichs in Metern als Gleitkommazahl (float). 0, wenn keine Grenzen konfiguriert sind.

Beispiele

Spielbereichsgröße auslesen

const initStage = async () => {
  if (!navigator.getVRDisplays) {
    console.warn('WebVR wird nicht unterstützt');
    return;
  }
  const [display] = await navigator.getVRDisplays();
  const stage = display?.stageParameters;

  if (stage) {
    console.log(`Breite: ${stage.sizeX} m, Tiefe: ${stage.sizeY} m`);
  } else {
    console.log('Keine Stage-Daten verfügbar (Sitz-/Mobil-Headset)');
  }
};

initStage();

Breite: 3.2 m, Tiefe: 2.5 m

Bodenfläche für eine Three.js-Szene skalieren

// Voraussetzung: three.js geladen, scene existiert
const createFloor = (display, scene) => {
  const stage = display.stageParameters;
  // Fallback 2 × 2 m, wenn keine Grenzen konfiguriert sind
  const width = stage?.sizeX || 2;
  const depth = stage?.sizeY || 2;

  const geometry = new THREE.PlaneGeometry(width, depth);
  const material = new THREE.MeshBasicMaterial({ color: 0x336699, wireframe: true });
  const floor = new THREE.Mesh(geometry, material);
  floor.rotation.x = -Math.PI / 2; // flach auf den Boden legen
  scene.add(floor);
  return floor;
};

Prüfen, ob ein Objekt im Spielbereich erreichbar ist

const isInsideStage = (stage, x, z) => {
  const halfW = stage.sizeX / 2;
  const halfD = stage.sizeY / 2; // sizeY entspricht der Z-Achse
  return Math.abs(x) <= halfW && Math.abs(z) <= halfD;
};

const stage = { sizeX: 3, sizeY: 2 };
console.log(isInsideStage(stage, 1.2, 0.8));
console.log(isInsideStage(stage, 0.5, 1.5));

true false

// Wichtig · Fallstricke

Veraltet: Die WebVR-API wurde nie Standard und ist aus aktuellen Browsern entfernt (unterstützt u. a. in älterem Firefox und Oculus-/Samsung-Internet-Browsern). Für neue Projekte WebXR verwenden: Dort liefert ein XRBoundedReferenceSpace über boundsGeometry sogar beliebige Polygone statt nur eines Rechtecks.
Achsen-Falle: sizeY ist die Tiefe (Z-Achse), nicht die Höhe. Beim Aufbau von 3D-Geometrie also auf die Z-Achse abbilden.
Der Wert kann 0 sein, wenn der Nutzer keinen Spielbereich eingerichtet hat – immer einen sinnvollen Fallback vorsehen.
stageParameters kann sich zur Laufzeit ändern (z. B. nach neuer Raumkalibrierung); Werte daher nicht dauerhaft zwischenspeichern, sondern bei Bedarf erneut lesen.
Nur in sicheren Kontexten (HTTPS) und teils hinter Browser-Flags verfügbar.

Siehe auch

VRStageParameters VRStageParameters.sizeX VRStageParameters.sittingToStandingTransform VRDisplay.stageParameters XRBoundedReferenceSpace KeyboardLayoutMap.size URLSearchParams.size