Store
What is the XR Store for?
The xr store is the central part of all @react-three/xr experiences and allows to configure those experiences using a large set of options, control the experience using various functions, and provide access to the current state of the xr experience.
Options
When creating a xr store, there are a lot of options that can be used for configuration.
For instance, we can use these options to disable the default controller on the left hand.
createXRStore({
controller: { left: false },
})
The following tables show all the available options.
| Property | Description | Default Value |
|---|---|---|
controller | Configures the <DefaultXRController/> or allows providing a custom implementation. You can set this for each handedness (e.g., left or right hand) individually. Setting this to false prevents the controllers from being used. | true |
transientPointer | Configures the <DefaultXRTransientPointer/> or allows providing a custom implementation. This can be set individually for each handedness. Setting this to false prevents transient pointers from being used. | N/A |
hand | Configures the <DefaultXRHand/> or allows providing a custom implementation. You can set this individually for each handedness. Setting this to false prevents hand tracking from being used. | N/A |
gaze | Configures the <DefaultXRGaze/> or allows providing a custom gaze implementation. Setting this to false prevents gaze-based interaction from being used. | true |
screenInput | Configures the <DefaultXRScreenInput/> or allows providing a custom screen input implementation. Setting this to false prevents screen input from being used. | true |
emulate | Emulates a specific device (e.g., "metaQuest3") using IWER if WebXR is not supported and running on "localhost" or pressing Window/Command + Alt/Option + E. It can also be set to false to disable emulation. | "metaQuest3" |
frameRate | Sets the session's framerate, with options such as "high" for smoother performance. | "high" |
foveation | Sets the WebXR foveation level between 0 (no foveation) and 1 (maximum foveation). If undefined, the device/browser's default foveation setting is used. | undefined |
frameBufferScaling | Adjusts the framebuffer scaling of the session. If undefined, the device/browser's default scaling is used (typically 1). | undefined |
enterGrantedSession | Automatically enters session modes when granted by the system without manually requesting a session. It can be an array of session modes or a boolean value to enable/disable this feature. | true |
baseAssetPath | Specifies the path to load the controller and hand models, and controller profiles from a CDN or local source. | 'https://cdn.jsdelivr.net/npm/@webxr-input-profiles/assets@1.0/dist/profiles/' |
defaultControllerProfileId | Specifies the fallback profile ID for the controller if no matching profile is found. It is useful for ensuring basic functionality when a specific controller profile isn't available. | 'generic-trigger' |
defaultXRHandProfileId | Specifies the fallback profile ID for hand tracking if no matching profile is found. It ensures basic hand-tracking functionality. | 'generic-hand' |
originReferenceSpace | Defines the reference space type for the origin, such as 'local-floor' or 'bounded-floor'. Determines how the user's position is tracked in the XR environment. | N/A |
bounded | Enables or disables the session bounds. false means unbounded (only available in AR). true means bounded (allows to reference the bounding space). undefined means bounded but no access to bounding space. | undefined |
anchors | Enables or disables anchors, which are fixed points in the XR environment that can be used to attach virtual objects. | true |
handTracking | Enables or turns off hand-tracking in the session, allowing users to interact with the XR environment using their hands. | true |
layers | Enables or turns off the use of layers in the session, which can enhance rendering performance by stacking visual content. | true |
meshDetection | Enables or turns off mesh detection, allowing the system to recognize and interact with real-world objects by detecting their mesh. | true |
planeDetection | Enables or turns off plane detection, allowing the system to recognize flat surfaces like floors and tables. | true |
depthSensing | Enables or disables depth sensing in the session, which can enhance realism by occluding virtual objects from real-world objects. | false |
customSessionInit | Overrides the session initialization object with custom settings. Use with caution, as it can significantly alter the behavior of the XR session. | undefined |
hitTest | Enables or turns off hit testing, which allows the system to detect where the user's input (e.g., a tap or gaze) intersects with objects in the XR environment. | true |
domOverlay | Enables or turns off DOM overlay in the session or provides a custom DOM element for the overlay, allowing HTML content to be rendered within the XR environment. | true |
secondaryInputSources | Enables non-primary (secondary input / tracked) sources. For example, when the device supports hands and controllers, the controllers can be used while the hands are tracked as primary input sources. This can allow to use the tracked controllers for other inputs. | false |
Functions
The xr store provides a large set of functions to modify and control the xr store. For instance, key functions are the store.enterAR and store.enterVR functions. The following table gives an overview of the complete set of functions that the xr store provides.
| Function | Description |
|---|---|
destroy() | Irreversibly destroys the XR store. |
enterXR(mode) | Initiates an XR session in the specified mode (such as immersive-ar or immersive-vr). The function returns a promise that eventually resolves with the XR session or undefined if the session fails to start. |
enterAR() | Starts an Augmented Reality (AR) session. The function returns a promise that eventually resolves with the AR session or undefined if AR is not supported. |
enterVR() | Starts a Virtual Reality (VR) session. The function returns a promise that eventually resolves with the VR session or undefined if VR is not supported. |
setHand(implementation, handedness?) | Updates the hand tracking configuration or implementation. You can target both hands or specify the handedness (left or right). This allows customization or updates to the hand implementation or configuration during runtime. |
setController(implementation, handedness?) | Updates the controller configuration or implementation. You can target both hands or specify the handedness (left or right). This enables dynamic updates to the controller setup. |
setGaze(implementation) | Updates the gaze-based interaction configuration or implementation. This function is used to modify the gaze implementation or configuration. |
setScreenInput(implementation) | Updates the screen input configuration or implementation. This function modifies how screen inputs are handled within the XR session. |
setTransientPointer(implementation, handedness?) | Updates the transient pointer configuration or implementation. You can target both hands or specify the handedness. |
setFrameRate(value) | Sets the framerate of the XR session, adjusting the session's performance and visual smoothness. Higher framerates can improve user experience but may require more processing power. |
requestFrame() | Returns a promise that resolves with the XR frame on the next render. This function is useful for synchronizing actions or processing data in the next render cycle, especially for tasks that need to be aligned with the rendering loop. |
State
Alongside a set of functions, the xr store also provides the state of the current experience. For instance, the state of the xr store contains the current XRSession inside state.session.
The following table provides a list of properties available in the state of the xr store.
| State Property | Description |
|---|---|
session | Represents the current XRSession. This object contains all the details and state information about the active XR session. |
originReferenceSpace | Refers to the XRReferenceSpace of the origin in the current session. This space is typically set at the floor level and serves as the reference point for the user's position in the XR environment. |
origin | Represents the 3D object that defines the session's origin. If this object is undefined, the origin is implicitly set at the world position (0,0,0). |
domOverlayRoot | The HTML element used for DOM overlays in handheld AR experiences. This is where any content will be overlayed over the handheld AR session. |
visibilityState | Indicates the session's visibility state, such as "visible-blurred" when the user sees an Operating System overlay. This property helps manage how the XR experience adjusts to different visibility conditions. |
frameRate | Represents the configured framerate for the XR session. Note that the actual framerate might be lower if the system cannot maintain the desired performance level. |
mode | Specifies the current XR session mode, such as immersive-vr, immersive-ar, or inline. If no session is active, this will be null. |
detectedPlanes | A read-only array of XRPlane objects representing the planes detected in the XR environment. These could include surfaces like floors, walls, and tables. |
detectedMeshes | A read-only array of XRMesh objects representing the meshes detected in the XR environment. These are typically 3D objects that have been identified and tracked during the session. |
useXR
The useXR hook allows to retrieve the state from the xr store. For instance, const session = useXR(xr => xr.session) allows us to always get the current session from any component that is placed inside the <XR> component.