Introducing the React VR Pre-Release

Oculus Developer Blog
Posted by Mike Armstrong and Andrew Imm
December 13, 2016

TL;DR:At Oculus Connect 3, we announced our work to bring React VR to the VR Web. Today, we’re very pleased to share the React VR pre-release! If you’re new to React and React Native, you can read more on their websites here: React and React Native. You can also experiment with React VR using the Carmel Developer Preview.

React VR Makes VR Web Applications Simple
The pursuit of the maximum frame rate for web-based VR experiences has meant an increase in complexity for developers. React VR aims to simplify the process and bring VR creation within the reach of all web developers.

We want to build frameworks that allow the creation of VR content using existing concepts and tools, while preserving the rapid iteration process of web development. We also want to separate the concerns of rendering from application logic so that you can focus on what makes your app great. To achieve this, we’ve combined the expressive, declarative power of React with lower-level WebVR and WebGL APIs. The result is a toolkit that lets web developers to build VR experiences using primitives such as <View> and <Text>, manage layout with Flexbox, and handle complex application states using the straightforward flows of React JS.

Say hello to VR inside your browser with the iteration speeds web developers are accustomed to.

import React from 'react';
import { AppRegistry, Pano, Text, View } from 'react-vr';
class WelcomeToVR extends React.Component {
render() {
// Displays "hello" text on top of a 360 panorama image.
// Text is 0.8 meters in size and is centered three
// meters in front of you.
return (
<Pano source={asset('mpk18.jpg')}/>
backgroundColor: 'blue',
fontSize: 0.8,
layoutOrigin: [0.5, 0.5],
transform: [{translate: [0, 0, -3]}],
AppRegistry.registerComponent('WelcomeToVR', () => WelcomeToVR);

The Pre-Release
Today’s initial release is available as a direct download here. This helps ensure we’re hitting key user requirements prior to moving to active development as an open source framework on GitHub. Given that it’s a pre-release, we’d love you hear your feedback. Please jump in with GitHub issue tracking here. This early preview puts the code right in the hands of developers, and we’re excited to see what you build.

The pre-release includes documentation within the package making it easy to get started. Even if you don’t have a VR headset or an experimental WebVR browser, you can begin writing your first VR web application today.

Let’s dive in by creating your first React VR project. Before building it, you’ll need to make sure you have Node.js installed. Node powers our development tools and will let you compile your code and run a local development server.

Viewing Samples and Documentation
We’ve provided a number of samples in the downloadable preview that demonstrate the power of React VR, as well as the various things you can do right out of the box.

To view the samples, install the React VR dependencies using the npm tool that comes with Node—just open up a command line from within the root of the preview folder and run npm install.

Once the dependencies are installed, run npm start and point your browser at http://localhost:8081/Samples where you’ll see a list of the samples available.

Documents for this release can be found by opening docs/index.html

Your First Application
With dependencies installed and the samples explored, it’s time to build your own project. We provide a command line tool that will help you bootstrap any new React VR application with ease. Install the react-vr tool with the following command:

npm install -g react-vr-cli

Now, we’ll use the React VR CLI to generate a new project called “WelcomeToVR.” The tool will create a folder containing the scaffolding for a React VR project and fetch all of the necessary external dependencies. Once setup is complete, run npm start to initialize your local development server and open the web page for your new project.

react-vr init WelcomeToVR
cd WelcomeToVR
npm start

When the process is finished, open your web browser and navigate to http://localhost:8081/vr. You should see something like this:

Welcome to React VR! Click and drag around the world in your browser, or open it up on your mobile device to see more. If you own a Gear VR, you can download the Carmel Developer Preview and explore your new world in VR.

Technical Details
React VR builds on the React Native framework and its tools with a new VR-focused runtime that let web developers to cut their teeth on VR.

The framework layers look like this:

At the top level is the React code. This is where an application developer will spend the majority of their time. React VR code is most similar to React Native and uses the same core components of View, Image, and Text, but further supplements them with support for common VR media with Pano, Mesh, and Lights.

The React code is designed to look web-like and familiar. Through the use of the React Native toolchain, it is turned into JavaScript, although this is something most developers don’t need to worry about.

React code runs in a WebWorker and communicates with the browser window asynchronously via message-passing; this lets the main rendering thread to run as fast as possible to get the best VR experience. Underneath React VR, there is a set of supporting layers and libraries that work together to make UIs come to life. Here is a quick summary of how they interact:

  • React Runtime—React Runtime runs in the webpage document (as opposed to the web worker) and converts React primitives into OVRUI/Three.js objects. The runtime also supports the React abstractions to networking, timers, and async storage. If you need to make a custom module that uses specific Web APIs or interacts with Three.js shaders and geometry, this is your layer. In the download package, we’ve documented how React VR can be extended to include your application view and module requirements.
  • OVRUI—OVRUI is a user interface library that provides a set of geometry types for Three.js, helping you build UIs in VR. Geometry objects describe text, buttons and other content that can be displayed within a 3D scene. For the pre-release, this is written primarily to support the requirements of React VR, but we’ll be developing this and placing it separately on GitHub so that this library can be used in its own right. More documentation on the direct use of OVRUI will follow.
  • Three.js—Three.js is a popular 3D library based on WebGL that allows rendering scenes composed of geometries and 3D objects. OVRUI creates these objects to describe UI elements and places them into the scene for rendering.
  • WebVR and Browser—Ultimately, all of the above code runs in the browser that exposes WebVR and WebGL APIs, plus the rest of the web platform. React developers should not need to interact with this level, yet it is available for achieving non-standard rendering effects or system interactions.

When you create a new React VR project, “react-vr init” script generates some boilerplate initialization code that makes use of an OVRUI component known as the Player. Player acts as a window into your 3D world, setting up the initial Three.js scene and displaying overlay widgets such as the compass and the “View in VR”button.

Player logic handles interaction with low-level WebVR APIs, automatically configuring UI to run well on the desktop or mobile browser, or within a VR headset. It is also designed to work seamlessly with our Carmel browser—users who have Carmel installed will be able to click the button, put on their headset, and enter a fully immersive experience.

Support and Full Release
In order for our React VR team to provide support for the preview release, we ask that all issues are reported via GitHub issue tracking. There, you’ll find a form with the minimal information we need to help determine the problem. It’s helpful if a reproducible example of the problem can be provided as well. Since the modules of React VR are delivered through npm, we’ll release consistent patches and follow-up releases as we respond to community feedback. You can expect information on each release through the React VR repo’s releases page as well.

For the full release, we’ll move the full repository to GitHub and actively work with the community to make the framework useful, fast, and simple for creating varied VR experiences. Happy building!