Class WebXRSystem

WebXRSystem class manages WebXR session and rendering for virtual reality experiences. This singleton class handles WebXR session lifecycle, camera setup for stereo rendering, input source management, and coordinate space transformations for VR applications.

Example

const webXRSystem = WebXRSystem.getInstance();
await webXRSystem.readyForWebXR(requestButton, '/assets/');
const controllers = await webXRSystem.enterWebXR({
  initialUserPosition: Vector3.fromCopyArray([0, 1.6, 0]),
  callbackOnXrSessionStart: () => console.log('VR started'),
  callbackOnXrSessionEnd: () => console.log('VR ended'),
  profilePriorities: ['oculus-touch', 'generic-trigger']
});

Accessors

framebuffer isReadyForWebXR isWebXRMode leftProjectionMatrix leftViewMatrix requestedToEnterWebVR requestedToEnterWebXR rightProjectionMatrix rightViewMatrix xrSession

Methods

_getCameraComponentAt _getCameraComponentSIDAt _getCameraWorldPositionAt _getLeftViewport _getProjectMatrixAt _getRightViewport _getViewMatrixAt _getViewportAt _postRender _preRender _setValuesToGlobalDataRepository enterWebXR exitWebXR getCanvasHeightForVr getCanvasWidthForVr getControllerEntities isMultiView readyForWebXR resetViewerTransform getInstance

Accessors

framebuffer

  • get framebuffer(): undefined | WebGLFramebuffer

  • Gets the WebXR framebuffer for rendering.

    Returns undefined | WebGLFramebuffer

    The WebGL framebuffer provided by the XR system, or undefined if not available.

isReadyForWebXR

  • get isReadyForWebXR(): boolean

  • Checks if the system is ready to enter WebXR.

    Returns boolean

    True if WebXR initialization is complete and ready for session start.

isWebXRMode

  • get isWebXRMode(): boolean

  • Checks if currently in WebXR rendering mode.

    Returns boolean

    True if WebXR mode is active.

leftProjectionMatrix

leftViewMatrix

requestedToEnterWebVR

  • get requestedToEnterWebVR(): boolean

  • Legacy property for backward compatibility.

    Returns boolean

    True if WebXR session entry has been requested.

    Deprecated

    Use requestedToEnterWebXR instead.

requestedToEnterWebXR

  • get requestedToEnterWebXR(): boolean

  • Checks if a WebXR session has been requested.

    Returns boolean

    True if WebXR session entry has been requested.

rightProjectionMatrix

rightViewMatrix

xrSession

  • get xrSession(): undefined | XRSession

  • Gets the current XR session object.

    Returns undefined | XRSession

    The active XRSession, or undefined if no session is active.

Methods

_getCameraComponentAt

_getCameraComponentSIDAt

  • _getCameraComponentSIDAt(index): number
  • Internal

    Gets the component SID (System ID) for the specified camera.

    Parameters

    • index: number

      Eye index (0: left, 1: right).

    Returns number

    The SID of the CameraComponent for the specified eye.

_getCameraWorldPositionAt

  • _getCameraWorldPositionAt(displayIdx): Vector3
  • Internal

    Gets the world position of the specified VR camera. Combines XR pose data with user position offset and viewer transformations.

    Parameters

    • displayIdx: number

      Eye index (0: left, 1: right).

    Returns Vector3

    The world position of the VR camera.

_getLeftViewport

  • _getLeftViewport(): Vector4
  • Internal

    Gets the viewport configuration for the left eye.

    Returns Vector4

    The viewport vector (x, y, width, height) for the left eye.

_getProjectMatrixAt

  • _getProjectMatrixAt(index): MutableMatrix44
  • Internal

    Gets the projection matrix for the specified eye.

    Parameters

    • index: number

      Eye index (0: left, 1: right).

    Returns MutableMatrix44

    The projection matrix for the specified eye.

_getRightViewport

  • _getRightViewport(): Vector4
  • Internal

    Gets the viewport configuration for the right eye. Accounts for multiview rendering mode differences.

    Returns Vector4

    The viewport vector (x, y, width, height) for the right eye.

_getViewMatrixAt

  • _getViewMatrixAt(index): Matrix44
  • Internal

    Gets the view matrix for the specified eye.

    Parameters

    • index: number

      Eye index (0: left, 1: right).

    Returns Matrix44

    The view matrix for the specified eye.

_getViewportAt

  • _getViewportAt(index): Vector4
  • Internal

    Gets the viewport configuration for the specified eye.

    Parameters

    • index: number

      Eye index (0: left, 1: right).

    Returns Vector4

    The viewport vector (x, y, width, height) for the specified eye.

_postRender

  • _postRender(): void
  • Internal

    Performs post-rendering cleanup for WebXR. Currently handles multiview framebuffer operations when enabled. Called once per frame after rendering is complete.

    Returns void

_preRender

  • _preRender(time, xrFrame): void
  • Internal

    Performs pre-rendering updates for WebXR. Updates view matrices, input sources, and gamepad states. Called once per frame before rendering begins.

    Parameters

    • time: number

      Current time in milliseconds.

    • xrFrame: XRFrame

      The XRFrame object for this rendering frame.

    Returns void

_setValuesToGlobalDataRepository

  • _setValuesToGlobalDataRepository(): void
  • Internal

    Updates camera projection matrices and pushes values to the global data repository. Called during the rendering pipeline to ensure cameras have current XR projection data.

    Returns void

enterWebXR

  • enterWebXR(options): Promise<undefined | IEntity[]>

  • Initiates a WebXR VR session with specified configuration. Requests an immersive VR session, sets up reference space, WebGL layer, and input handling.

    Parameters

    • options: {
          callbackOnXrSessionEnd: (() => void);
          callbackOnXrSessionStart: (() => void);
          initialUserPosition?: Vector3;
          profilePriorities: string[];
      }

      Configuration object for WebXR session.

      • callbackOnXrSessionEnd: (() => void)

        Callback function executed when the XR session ends.

          • (): void

          • Returns void

      • callbackOnXrSessionStart: (() => void)

        Callback function executed when the XR session starts.

          • (): void

          • Returns void

      • OptionalinitialUserPosition?: Vector3

        Initial position of the user in world space. Defaults to [0, 1.1, 0].

      • profilePriorities: string[]

        Array of controller profile names in priority order for input mapping.

    Returns Promise<undefined | IEntity[]>

    Promise that resolves to an array of controller entities, or undefined on failure.

    Example

    const controllers = await webXRSystem.enterWebXR({
      initialUserPosition: Vector3.fromCopyArray([0, 1.6, 2]),
      callbackOnXrSessionStart: () => {
        console.log('VR session started');
        // Initialize VR-specific UI or game logic
      },
      callbackOnXrSessionEnd: () => {
        console.log('VR session ended');
        // Clean up VR-specific resources
      },
      profilePriorities: ['oculus-touch-v2', 'oculus-touch', 'generic-trigger']
    });

exitWebXR

  • exitWebXR(): Promise<void>

  • Exits the current WebXR session and returns to normal rendering mode. Gracefully terminates the XR session, triggering cleanup callbacks.

    Returns Promise<void>

    Example

    // Exit VR mode when user clicks a button
    exitButton.addEventListener('click', async () => {
      await webXRSystem.exitWebXR();
    });

getCanvasHeightForVr

  • getCanvasHeightForVr(): number

  • Gets the canvas height configured for VR rendering.

    Returns number

    The height of the VR canvas in pixels.

getCanvasWidthForVr

  • getCanvasWidthForVr(): number

  • Gets the canvas width configured for VR rendering.

    Returns number

    The width of the VR canvas in pixels.

getControllerEntities

isMultiView

  • isMultiView(): boolean

  • Checks if multiview rendering is supported and enabled.

    Returns boolean

    True if multiview VR rendering is supported.

readyForWebXR

  • readyForWebXR(requestButtonDom, basePath): Promise<never[]>

  • Prepares the WebXR system for VR session initialization. Checks for WebXR support, loads required modules, and sets up the entry point.

    Parameters

    • requestButtonDom: HTMLElement

      HTML element to serve as the VR entry button. If null, creates a default button.

    • basePath: string

      Base path for loading controller models and assets.

    Returns Promise<never[]>

    Promise that resolves to an empty array on success.

    Throws

    When not running in a browser environment or WebXR is not supported.

    Example

    const enterButton = document.getElementById('enter-vr-button');
    await webXRSystem.readyForWebXR(enterButton, '/assets/controllers/');

resetViewerTransform

  • resetViewerTransform(): void

  • Resets all viewer transformation parameters to their default values. Useful for resetting user position and orientation to origin.

    Returns void

StaticgetInstance

Settings

Member Visibility

On This Page

Accessors
Methods