webxr-3d-spatial-design

WebXR & 3D Spatial Design Production Guidelines

This skill covers architecture, frame loop synchronization, input handling (tracked controllers, hand tracking, raycasting), spatial audio integration, and performance optimization for WebXR and Three.js applications across VR headsets and AR pass-through devices.

1. WebXR Lifecycle & Session Management

1.1 Session Initialization (Immersive VR vs Immersive AR)

import * as THREE from 'three';
import { VRButton } from 'three/addons/webxr/VRButton.js';
import { ARButton } from 'three/addons/webxr/ARButton.js';

class SpatialApp {
  constructor() {
    this.container = document.createElement('div');
    document.body.appendChild(this.container);

    // 1. Scene & Camera Setup
    this.scene = new THREE.Scene();
    this.camera = new THREE.PerspectiveCamera(
      50, 
      window.innerWidth / window.innerHeight, 
      0.1, 
      20
    );
    this.camera.position.set(0, 1.6, 0); // 1.6m height standard human eye level

    // 2. Renderer with WebXR enabled
    this.renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
    this.renderer.setPixelRatio(window.devicePixelRatio);
    this.renderer.setSize(window.innerWidth, window.innerHeight);
    this.renderer.xr.enabled = true;
    this.renderer.shadowMap.enabled = true;
    this.renderer.shadowMap.type = THREE.PCFSoftShadowMap;
    this.container.appendChild(this.renderer.domElement);

    this.initButtons();
    this.initLighting();
  }

  initButtons() {
    // Add VR entry button to DOM
    document.body.appendChild(VRButton.createButton(this.renderer));
  }

  initLighting() {
    const ambientLight = new THREE.AmbientLight(0xffffff, 0.6);
    this.scene.add(ambientLight);

    const dirLight = new THREE.DirectionalLight(0xffffff, 0.8);
    dirLight.position.set(2, 4, 2);
    dirLight.castShadow = true;
    this.scene.add(dirLight);
  }

  // 3. WebXR-compliant Render Loop (Do NOT use requestAnimationFrame directly)
  start() {
    this.renderer.setAnimationLoop((timestamp, frame) => {
      this.update(timestamp, frame);
      this.renderer.render(this.scene, this.camera);
    });
  }

  update(timestamp, frame) {
    // Frame delta handling
    if (frame) {
      const session = frame.session;
      // Process XR input sources / reference space poses
    }
  }
}