react-xr

VR/AR for react-three-fiber

Virtual RealityReact
pmndrs/xrdocs.pmnd.rs/xr/react-xr

README

@react-three/xr


React components and hooks for creating VR/AR applications with @react-three/fiber

  1. ```bash
  2. npm install @react-three/xr
  3. ```

Examples


These demos are real, you can click them! They contain the full code, too.

Getting started


The following adds a button to start your session and controllers inside an XR manager to prepare your scene for WebXR rendering and interaction.

  1. ```jsx
  2. import { VRButton, ARButton, XR, Controllers, Hands } from '@react-three/xr'
  3. import { Canvas } from '@react-three/fiber'

  5. function App() {
  6.   return (
  7.     <>
  8.       <VRButton />
  9.       <Canvas>
  10.         <XR>
  11.           <Controllers />
  12.           <Hands />
  13.           <mesh>
  14.             <boxGeometry />
  15.             <meshBasicMaterial color="blue" />
  16.           </mesh>
  17.         </XR>
  18.       </Canvas>
  19.     </>
  20.   )
  21. }
  22. ```

XRButton


XRButton is an HTML button that can be used to init and display info about your WebXR session. This is aliased by ARButton and VRButton with sensible session defaults.

  1. ```jsx
  2. <XRButton
  3.   /* The type of `XRSession` to create */
  4.   mode={'AR' | 'VR' | 'inline'}
  5.   /**
  6.    * `XRSession` configuration options
  7.    * @see https://immersive-web.github.io/webxr/#feature-dependencies
  8.    */
  9.   sessionInit={{ optionalFeatures: ['local-floor', 'bounded-floor', 'hand-tracking', 'layers'] }}
  10.   /** Whether this button should only enter an `XRSession`. Default is `false` */
  11.   enterOnly={false}
  12.   /** Whether this button should only exit an `XRSession`. Default is `false` */
  13.   exitOnly={false}
  14.   /** This callback gets fired if XR initialization fails. */
  15.   onError={(error) => ...}
  16. >
  17.   {/* Can accept regular DOM children and has an optional callback with the XR button status (unsupported, exited, entered) */}
  18.   {(status) => `WebXR ${status}`}
  19. </XRButton>
  20. ```

XR


XR is a WebXR manager that configures your scene for XR rendering and interaction. This lives within a R3F Canvas.

  1. ```jsx
  2. <Canvas>
  3.   <XR
  4.     /**
  5.      * Enables foveated rendering. Default is `0`
  6.      * 0 = no foveation, full resolution
  7.      * 1 = maximum foveation, the edges render at lower resolution
  8.      */
  9.     foveation={0}
  10.     /**
  11.      * The target framerate for the XRSystem. Smaller rates give more CPU headroom at the cost of responsiveness.
  12.      * Recommended range is `72`-`120`. Default is unset and left to the device.
  13.      * @note If your experience cannot effectively reach the target framerate, it will be subject to frame reprojection
  14.      * which will halve the effective framerate. Choose a conservative estimate that balances responsiveness and
  15.      * headroom based on your experience.
  16.      * @see https://developer.mozilla.org/en-US/docs/Web/API/WebXR_Device_API/Rendering#refresh_rate_and_frame_rate
  17.     */
  18.     frameRate={72 | 90 | 120}
  19.     /** Type of WebXR reference space to use. Default is `local-floor` */
  20.     referenceSpace="local-floor"
  21.     /** Called as an XRSession is requested */
  22.     onSessionStart={(event: XREvent<XRManagerEvent>) => ...}
  23.     /** Called after an XRSession is terminated */
  24.     onSessionEnd={(event: XREvent<XRManagerEvent>) => ...}
  25.     /** Called when an XRSession is hidden or unfocused. */
  26.     onVisibilityChange={(event: XREvent<XRSessionEvent>) => ...}
  27.     /** Called when available inputsources change */
  28.     onInputSourcesChange={(event: XREvent<XRSessionEvent>) => ...}
  29.   >
  30.     {/* All your regular react-three-fiber elements go here */}
  31.   </XR>
  32. </Canvas>
  33. ```