Yeoman webvr-decorator generator - Adds WebVR capability to an existing (angular) application.
Note: currently only applications generated with the angular generator are supported. But this generator has been designed to accommodate multiple application formats. Additional application formats such as Webapp and Angular 2 are planned for the future.
WebVR and three.js are powerful platforms. When running together, these libraries allow you create full VR-enabled web applications that run directly on any WebVR enabled browser. When you click on the "WebVR" full-screen icon of a running application, you will generate a split-screen view suitable for viewing on a VR head-mounted display such as Oculus Rift, or Google Cardboard.
Unfortunately, both WebVR and three.js involve large amounts of tedious boilerplate. If you've never created a WebVR app before, it may take you several days to figure what needs to be done as documentation is sparse. Even experienced WebVR application developers may find it takes several hours to set up a basic application, particularly when you have to integrate it into a non-trivial platform such as Angular.
webvr-decorator allows you to inject the necessary code into an existing application, in the form of an independent MVC subapp, that allows you to display a basic VR enabled scene of a rotating cube. And by using a generator, you get a simple but useful skeleton architecture utilizing standard WebVR and THREE.js best practices, providing a solid foundation on which you can build your own VR capability, and integrate into your existing application.
npm install -g generator-webvr-decorator
Install your basic target application. For example, angular (see here for how to generate an angular application)
Make sure you are in the directory that has the application you wish to "decorate" with WebVR:
Run the generator
This generates the following:
_-----_| | .--------------------------.|----| | Welcome to the |`---------´ | webvr-decorator |
If you are decorating a vanilla angular app, and you basically want a stand-alone VR app, then it's probably easiest to just accept the defaults.
However, for the rest of this demonstration we will assume you want to add the WebVR capability as a separate "MVC subsystem" on top of an angular app that already has other functionality (in the 'main' controller and service, for example). So in this case we want to rename the following:
- main controller --> 'myVRSubApp'
- main service --> 'myVRSubApp'
- base service --> 'myVRSubAppBase'
- utils services --> 'myVRSubAppUtils'
We will use the default name for the keyboard handling directive (canvasKeys.js)
Note: Enter names as camelCase. Angular has very picky requirements regarding names, as it uses extensive "name-mangling" conventions to identify resources.
So select the artifacts by using the arrow-keys to go down the list and press the space bar on the items you wish to select:
? please specify any artifact name you wish to override, or just press ENTER to accept the defaults:◯ --- controllers ---◉ main◯ --- services ---◉ main◉ base❯◉ utils◯ --- directives ---◯ canvaskeys
You will then be prompted for the new names:
? please specify any artifact name you wish to override, or just press ENTER to accept the defaults: main, main, base, utils? new name
The generator will confirm if you wish to continue:
? We will now add webVR capability to this application. Do you wish to continue?
The generator will update several files. It will ask for permission first. Reply with 'y' to update a single file, or specify 'a' to update all files:
? We will now add webVR capability to this application. Do you wish to continue?switch: found unknown key:continuecreate app/scripts/services/myvrsubapp.jscreate app/scripts/services/myvrsubappbase.jscreate app/scripts/services/myvrsubapputils.jsidentical test/spec/services/myvrsubapp.jsidentical test/spec/services/myvrsubappbase.jsidentical test/spec/services/myvrsubapputils.jscreate app/scripts/controllers/myvrsubapp.jsidentical test/spec/controllers/myvrsubapp.jscreate app/scripts/directives/canvaskeys.jsidentical test/spec/directives/canvaskeys.jsundefinedconflict app/scripts/services/myvrsubapp.js? Overwrite app/scripts/services/myvrsubapp.js? overwrite this and all othersforce app/scripts/services/myvrsubapp.jsforce app/scripts/services/myvrsubappbase.jsforce app/scripts/services/myvrsubapputils.jsforce app/scripts/controllers/myvrsubapp.jsforce app/scripts/directives/canvaskeys.jsforce app/index.htmlforce app/scripts/app.jsforce app/lib/README.mdforce app/views/myvrsubapp.htmlapp.install: now installing threejsapp.install: now installing threejsapp.install: now installing webvr-boilerplate
Note: the libraries, particularly the three.js libraries can take on the order of several minutes to install:
bower threejs#* not-cached git://github.com/mrdoob/three.js.git#*bower threejs#* resolve git://github.com/mrdoob/three.js.git#*bower threejs#* checkout masterbower threejs#* progress Receiving objects: 40% , 14.13 MiB | 2.10 MiB/sbower threejs#* progress Receiving objects: 41% , 14.13 MiB | 2.10 MiB/sbower threejs#* progress Receiving objects: 41% , 18.59 MiB | 2.22 MiB/sbower threejs#* progress Receiving objects: 41% , 20.61 MiB | 2.16 MiB/sbower threejs#* progress Receiving objects: 42% , 20.61 MiB | 2.16 MiB/sbower threejs#* progress Receiving objects: 42% , 22.73 MiB | 2.16 MiB/sbower threejs#* progress Receiving objects: 42% , 24.88 MiB | 2.14 MiB/sbower threejs#* progress Receiving objects: 42% , 27.05 MiB | 2.12 MiB/sbower threejs#* progress Receiving objects: 42% , 29.28 MiB | 2.14 MiB/sbower threejs#* progress Receiving objects: 43% , 32.31 MiB | 2.00 MiB/sbower threejs#* progress Receiving objects: 44% , 34.01 MiB | 2.14 MiB/s
The installer is done once you see these messages:
webvr-decorator: all donesub-angular: all done
For some reason, the installer doesn't always exit at the end. You can hit Ctrl-C after seeing these messages if it appears your terminal is "hung". After the required libraries are installed, start your angular app like always:
The webVR enabled rotating cube scene will be at the following URL:
The application supports WASD keys to move around:
w: move camera forwards: move camera backwardd: move camera righta: move camera lefte: rotate cube clockwiseq: rotate cube counter-clockwise
It is recommended you backup the app directory structure of your application, or simply use a vanilla angular install (base yeoman angular template app with no modifications) before decorating it, particularly if you are using the default names. While this is less important if you're doing a "separate MVC" install (using different names), there are still some files common files, such as index.html, that of necessity need to be updated. While I have tested the changes on several of my own apps, and yeoman is fairly good about preventing an installer from trashing your app, it's just common sense to do until this installer gets more "real-world" usage, or at least until you gain more personal experience with it.
I primarily tested on a laptop. It runs on mobile, but there is a problem where the VR icon rapidly shrinking that makes it hard to enter VR Mode.
The arrow keys do not work when selecting options on Microsoft Windows (either the git bash shell, or command prompt). This appears to be a known problem with the Windows version Yeoman.
The following were run on Mozilla nightly build
pre VR expansion:
with VR expansion:
Running app available here
Skip installing the libraries (useful if running multiple times):
yo webvr-decorator --skipInstall
v0.2.x First released 2015-01-27:
- added ability to override names.
- improved documentation.
- fixed various minor bugs found during testing.
v0.1.5: Released 2014-12-07:
- Basic working form.