Skip to content
This repository has been archived by the owner on Jul 22, 2024. It is now read-only.

Commit

Permalink
Updated Docs
Browse files Browse the repository at this point in the history
  • Loading branch information
steakpinball committed Mar 4, 2020
1 parent 98db049 commit 487b0be
Show file tree
Hide file tree
Showing 18 changed files with 94 additions and 76 deletions.
38 changes: 23 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
# Unity WebVR Assets

Assets for creating [WebVR](https://webvr.rocks/)-enabled [Unity3D](https://unity3d.com/) projects.
Assets for creating [WebXR](https://developer.mozilla.com/topics/mixed-reality/)-enabled [Unity3D](https://unity.com/) projects.

**[Check out the demo now!](https://mozilla.github.io/unity-webvr-export/)**<br>
[Read our blog post (February 2018).](https://hacks.mozilla.org/2018/02/create-vr-on-the-web-using-unity3d/)

[![Preview of Unity WebVR-exported project in the browser](https://raw.githubusercontent.com/mozilla/unity-webvr-export/master/img/preview.gif)](https://mozilla.github.io/unity-webvr-export/)
[![Preview of Unity WebXR-exported project in the browser](https://raw.githubusercontent.com/mozilla/unity-webvr-export/master/img/preview.gif)](https://mozilla.github.io/unity-webvr-export/)

**[Free to download](https://assetstore.unity.com/packages/templates/systems/webvr-assets-109152)** and available now on the [Unity Asset Store](https://assetstore.unity.com/packages/templates/systems/webvr-assets-109152).

<a href="https://assetstore.unity.com/packages/templates/systems/webvr-assets-109152" title="Download the WebVR Assets package for free on the Unity Asset Store">
<a href="https://assetstore.unity.com/packages/templates/systems/webvr-assets-109152" title="Download the WebXR Assets package for free on the Unity Asset Store">
<img src="https://raw.githubusercontent.com/mozilla/unity-webvr-export/master/img/asset-store.png" width="640" alt="Download the WebVR Assets package for free on the Unity Asset Store">
</a>

<hr>

## Getting started

* [Setting up a Unity project for WebVR](./docs/project-setup.md)
* [Setting up a Unity project for WebXR](./docs/project-setup.md)
* [Controllers and input system](./docs/controllers.md)
* [In-editor VR playback for rapid testing](./docs/xr-testing.md)
* [Publishing](./docs/publishing.md)
Expand All @@ -26,29 +26,37 @@ Assets for creating [WebVR](https://webvr.rocks/)-enabled [Unity3D](https://unit

## Need help?

* [Join the WebVR Slack](https://webvr.rocks/slack) (join the [#unity channel](https://webvr.slack.com/messages/unity))
* [Join the WebVR Slack](https://webvr-slack.herokuapp.com/) (join the [#unity channel](https://webvr.slack.com/messages/unity))

## Compatibility

### Unity editor version

* `2018.2` and above.
* `2018.4` and newer.

### Browser Compatibility

| Platform | Browser | Compatible headsets | |
WebXR has limited support at time of writing. See compatibility at [caniuse](https://caniuse.com/#feat=webxr) or on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/WebXR_Device_API)

A special build of Firefox, [Fiefox Reality](https://mixedreality.mozilla.org/firefox-reality/), has built-in support for WebXR.

The polyfill will fall back to the old WebVR API if it is available.

| Platform | Browser | Compatible headsets | Notes |
| --- | --- | --- | --- |
| Desktop | Firefox | HTC VIVE, Oculus Rift, Windows Mixed Reality headsets (using Steam VR) | [Setup instructions](https://webvr.rocks/firefox) |
| Desktop | Microsoft Edge | Windows Mixed Reality headsets | [Setup instructions](https://webvr.rocks/microsoft_edge) |
| Desktop | Chrome Canary | HTC VIVE, Oculus Rift, Windows Mixed Reality headsets | Browser flags required. [Setup instructions](https://webvr.rocks/chrome) |
| Mobile | Oculus Browser | Oculus Quest |
| Mobile | Firefox Reality | Oculus Quest |

### Polyfilled WebVR
### Polyfilled WebXR

If the user does not have supported headset, browser or device, the content will still work through the use of the [WebVR Polyfill](https://github.com/immersive-web/webvr-polyfill).
If the user does not have supported headset, browser or device, the content will still work through the use of the [WebXR Polyfill](https://github.com/immersive-web/webxr-polyfill).

### Mobile support

This asset works by utilizing Unity's WebGL platform support and therefore shares the same limitations. Because of this, mobile support is limited and may not work. See [Unity's WebGL browser compatibility](https://docs.unity3d.com/2018.1/Documentation/Manual/webgl-browsercompatibility.html).
This asset works by utilizing Unity's WebGL platform support and therefore shares the same limitations. Because of this, mobile support is limited and may not work. See [Unity's WebGL browser compatibility](https://docs.unity3d.com/Manual/webgl-browsercompatibility.html).

### Version History and Notes

Expand All @@ -66,17 +74,17 @@ Take a look at the contributor guides too.

## We want to hear from you!

We’d love to hear about what you come up with using the _WebVR Assets_. **Share your work with us** and use the [#unitywebvr](https://twitter.com/search?f=tweets&q=%23unitywebvr) Twitter hashtag.
We’d love to hear about what you come up with using the _WebXR Assets_. **Share your work with us** and use the [#unitywebvr](https://twitter.com/search?f=tweets&q=%23unitywebvr) Twitter hashtag.

The Unity WebVR Assets is an open-source project (licensed under Apache 2) [available on GitHub](https://github.com/mozilla/unity-webvr-export).
The Unity WebXR Assets is an open-source project (licensed under Apache 2) [available on GitHub](https://github.com/mozilla/unity-webvr-export).

* [View known issues](https://github.com/mozilla/unity-webvr-export/issues)
* [File an issue or feature request](https://github.com/mozilla/unity-webvr-export/issues/new)
* [Contribute code or documentation to the project](https://github.com/mozilla/unity-webvr-export#contributing)

Reach out to us with any questions you may have or help you may need, and participate in the discussions on the [WebVR Slack](https://webvr.rocks/slack) in the [#unity channel](https://webvr.slack.com/messages/unity).
Reach out to us with any questions you may have or help you may need, and participate in the discussions on the [WebVR Slack](https://webvr-slack.herokuapp.com/) in the [#unity channel](https://webvr.slack.com/messages/unity).

* [Join the WebVR Slack](https://webvr.rocks/slack) (join the [#unity channel](https://webvr.slack.com/messages/unity))
* [Join the WebVR Slack](https://webvr-slack.herokuapp.com/) (join the [#unity channel](https://webvr.slack.com/messages/unity))


## Developer Privacy Notice for Data Collection
Expand All @@ -96,7 +104,7 @@ Also, thanks to [Arturo Paracuellos (@arturitu)](https://github.com/arturitu) fo

## License

Copyright 2017 - 2018 Mozilla Corporation
Copyright 2017 - 2020 Mozilla Corporation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Expand Down
16 changes: 8 additions & 8 deletions docs/build.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,22 @@

If you are a maintainer of this project, and you modified the demo scene distributed with the package, you will want to update the [`Build/` directory](https://github.com/mozilla/unity-webvr-export/tree/master/Build/) (hosted [online here](https://mozilla.github.io/unity-webvr-export/Build/)).

1. Launch `Edit > Build Settings > Project Settings`. From `Player Settings…` (`Edit > Project Settings > Player`), select the **`WebGL settings`** tab (HTML5 icon), toggle the **`Resolution and Presentation`** view, and select **`WebVR`** for the `WebGL Template`.
1. Launch `Edit > Build Settings > Project Settings`. From `Player Settings…` (`Edit > Project Settings > Player`), select the **`WebGL settings`** tab (HTML5 icon), toggle the **`Resolution and Presentation`** view, and select **`WebXR`** for the `WebGL Template`.

<img alt="WebGL template selector" src="./images/webvr-template.png" width="250">
![WebGL template selector](./images/webxr-template.png)

2. Launch `Edit > Build Settings > Project Settings`. Then, press the **`Build and Run`** button, and **`Save`** to the directory named **`Build`**.

<img alt="Selecting the Build folder" src="../img/build-webgl.png" width="250">
![Selecting the Build folder](../img/build-webgl.png)

If you are contributing to the Assets, you can build and export a new version of the [`WebVR-Assets.unitypackage` file](../WebVR-Assets.unitypackage).
If you are contributing to the Assets, you can build and export a new version of the [`WebXR-Assets.unitypackage` file](../WebXR-Assets.unitypackage).

Notice that the package does not include all the assets in the repository but **only those under `WebVR` and `WebGLTemplates`**:
Notice that the package does not include all the assets in the repository but **only those under `WebVR`, `WebXR`, and `WebGLTemplates`**:

1. Open **`Assets > Export Package…`**. A window titled `Exporting package` will appear. Press the **`Export…`** button to proceed.

<img alt="Exporting package" src="../img/exporting-asset-package.png" width="250">
![Exporting package](../img/exporting-asset-package.png)

2. When prompted for the file location, set **`WebVR-Assets`** as the filename of the destination Unity Asset Package, and press the **`Save`** button.
2. When prompted for the file location, set **`WebXR-Assets`** as the filename of the destination Unity Asset Package, and press the **`Save`** button.

<img alt="Export package …" src="../img/export-asset-package.png" width="250">
![Export package …](../img/export-asset-package.png)
52 changes: 27 additions & 25 deletions docs/controllers.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
# Controllers and input system

Tracked controllers are by default included in `WebVRCameraSet` prefab when installed into your project scene. See [Project Setup](./project-setup.md#4-add-the-webvr-prefab-to-your-scene) on how to do this.
Tracked controllers are by default included in `WebXRCameraSet` prefab when installed into your project scene. See [Project Setup](./project-setup.md#5-add-the-webxr-prefab-to-your-scene) on how to do this.

Out of the box, the prefab includes:

* Hand models
* Animations for hands when using grip and trigger buttons.
* Controller position and orientation tracking.
* Works with _PC, Mac and Linux Standalone_ and _WebVR_ platforms.
* Works with _PC, Mac and Linux Standalone_ and _WebXR_ platforms.
* Works with in-editor playback.

![In-editor play](images/editor-play.gif)

# WebVRController Script
# WebXRController Script

Provides configuration for setting up GameObjects as controllers. The script also applies position and orientation tracking from VR controllers.

Expand All @@ -21,17 +21,17 @@ Provides configuration for setting up GameObjects as controllers. The script als
| Option | Description |
| --- | --- |
| Hand | GameObject tracked as Left or Right hand |
| Input Map | WebVRControllerInputMap asset used to configure Inputs from controllers |
| Input Map | WebXRControllerInputMap asset used to configure Inputs from controllers |

# Cross platform support using WebVRControllerInputMap
# Cross platform support using WebXRControllerInputMap

Because we are working between two platforms, Unity (Editor and Standalone PC, Mac, Linux) and Web Browsers, we need a way to mediate between the two input systems, the [Unity Input Manager](https://docs.unity3d.com/Manual/xr_input.html) and [Browser Gamepad API](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API) respectively. To do this, we create `WebVRControllerInputMap` assets to configure _Actions_ that map to the respective inputs for each platform.
Because we are working between two platforms, Unity (Editor and Standalone PC, Mac, Linux) and Web Browsers, we need a way to mediate between the two input systems, the [Unity Input Manager](https://docs.unity3d.com/Manual/xr_input.html) and [Browser Gamepad API](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API) respectively. To do this, we create `WebXRControllerInputMap` assets to configure _Actions_ that map to the respective inputs for each platform.

In the asset package, we include two pre-made assets, one for each hand: `LeftControllerMap.asset` and `RightControllerMap.asset`. To use, _drag and drop_ the assets into `WebVRController` script `Input Map` option for the corresponding left or right hand.
In the asset package, we include two pre-made assets, one for each hand: `XRLeftControllerMap.asset` and `XRRightControllerMap.asset`. To use, _drag and drop_ the assets into `WebXRController` script `Input Map` option for the corresponding left or right hand.

![Assign Input Map](images/assign-inputmap.gif)

# Configuring a WebVRControllerInputMap asset
# Configuring a WebXRControllerInputMap asset

![Input Map configuration](images/inputmap.png)

Expand All @@ -43,61 +43,63 @@ In the asset package, we include two pre-made assets, one for each hand: `LeftCo
| Unity Input Name | Input name defined in Unity Input Manager |
| Unity Input Is Button | Whether gesture derives its value from Unity using `Input.GetButton` function |

As a note, we have two `WebVRControllerInputMap` assets, one for each hand since there is overlap between input ID's for browser Gamepad button and axis for each hand.
As a note, we have two `WebXRControllerInputMap` assets, one for each hand since there is overlap between input ID's for browser Gamepad button and axis for each hand.

## Creating a new InputMap Asset

To create a new `WebVRControllerInputMap`, use `Asset > Create > WebVRControllerInputMap`
To create a new `WebXRControllerInputMap`, use `Asset > Create > Web XR Controller Input Map`

# Configure Unity Input Manager

To get up and running using pre-configured Input Manager settings, follow [Step #5, Add Input Manager Settings to your Project](project-setup.md#5-add-input-manager-settings-to-your-project) in the [Setting up a Unity project for WebVR](./project-setup.md) guide.

You can also choose to manually configure the Input Manager by using `Edit > Project Settings > Input`

Below is an example of Unity Input Manager _input axes_ that correspond to the _Unity Input Name_ in the `WebVRControllerInputMap` as [shown above](#configuring-a-webvrcontrollerinputmap-asset).
Below is an example of Unity Input Manager _input axes_ that correspond to the _Unity Input Name_ in the `WebXRControllerInputMap` as [shown above](#configuring-a-webvrcontrollerinputmap-asset).

![Unity Input Manager configuration](images/unity-input-manager.png)

## Unity VR Input

See Unity VR Input specification for controller axis and button definitions for each VR system.

* [Input for Oculus](https://docs.unity3d.com/Manual/OculusControllers.html)
* [Input for Open VR](https://docs.unity3d.com/Manual/OpenVRControllers.html)
* [Input for Windows Mixed Reality](https://docs.unity3d.com/Manual/Windows-Mixed-Reality-Input.html)
* [Input for Editor and Standalone](https://docs.unity3d.com/Manual/XRPluginArchitecture.html)

## Gamepad API Input

Identify controller axis and button usage using the [HTML5 Gamepad Tester](http://html5gamepad.com/).

You will need to have WebVR active and rendering into the headset before controllers are visible. To do this, open [WebVR content](https://webvr.info/samples/XX-vr-controllers.html) and _Enter VR_, open another tab and navigate to the [HTML5 Gamepad Tester](http://html5gamepad.com/).
You will need to have WebXR active and rendering into the headset before controllers are visible. To test this, open [WebXR content](https://mixedreality.mozilla.org/hello-webxr/), or [HTML5 Gamepad Tester](http://html5gamepad.com/).

![html5gamepad.com](images/html5gamepad.png)

## How the WebVRController decides which Input platform to use.
## How the WebXRController decides which Input platform to use.

Unity Input Manager (for button and axis) and XR Inputs (for position and orientation) is used when using in-editor playback or when building to PC, Mac & Linux compatible standalone.
* [In-editor VR playback for rapid testing](./xr-testing.md).

When your project is built to WebVR, the browser Gamepad API is used for input from VR controllers.
* [Building your project to WebVR](./project-setup#6-build-your-project-to-webvr).
When your project is built to WebXR, the browser Gamepad API is used for input from VR controllers.
* [Building your project to WebXR](./project-setup#6-build-your-project-to-webxr).

## Using controller Inputs

The `WebVRController` Inputs are similar in use to the standard Unity Input system.
The `WebXRController` Inputs are similar in use to the standard Unity Input system.

```c#
using UnityEngine;
using System.Collections;

public class ExampleClass : MonoBehaviour {
void Update() {
// Retrieve the WebVRController commponent.
WebVRController controller = gameObject.GetComponent<WebVRController>();
public class ExampleClass : MonoBehaviour
{
private WebXRController _controller;

void Awake() {
// Retrieve the WebXRController component.
_controller = GetComponent<WebXRController>();
}

void Update() {
// Controller hand being used.
WebVRControllerHand hand = controller.hand;
WebXRControllerHand hand = controller.hand;

// GetButtonDown and GetButtonUp:
if (controller.GetButtonDown("Trigger"))
Expand Down
2 changes: 1 addition & 1 deletion docs/customization/adding-ga.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Google Analytics is a popular web analytics service that tracks and reports website traffic. It offers insight about your user behaviour and allows you to make informed decisions regarding the evolution of your site.

The [VR template](../../Assets/WebGLTemplates/WebVR/index.html) that comes with the [Unity package](https://u3d.as/1476) already includes Analytics as a part of the telemetry library used for [collecting usage data](../data-collection.md) but you'll need to set up a Google Analytics account and get a [Tracking ID](https://support.google.com/analytics/answer/7372977) first, before using it.
The [XR template](../../Assets/WebGLTemplates/WebXR/index.html) that comes with the [Unity package](https://u3d.as/1476) already includes Analytics as a part of the telemetry library used for [collecting usage data](../data-collection.md) but you'll need to set up a Google Analytics account and get a [Tracking ID](https://support.google.com/analytics/answer/7372977) first, before using it.

## Quick set up

Expand Down
Binary file modified docs/images/asset-store.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/assign-inputmap.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/camera-prefab.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/controller-script.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/import-package.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/inputmap.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/webgl-hub.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/images/webvr-template.png
Binary file not shown.
Binary file added docs/images/webxr-template.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit 487b0be

Please sign in to comment.