Getting Started

VotanicXR is a Software Development Toolkit of Extended Reality as a plug-in of Unity Engine. This chapter is a quick start guide to build a XR application from a new empty project, and run the build in PC and HMD platform.

VotanicXR supports Unity 2018.4 to 2021.3. In this section, Unity 2018 v.4 is used for the demonstration.

Set Up Tutorial Project

Create New Unity Project

For Standard 3D Project

For your chosen Unity version, select the 3D Core template when you create new project.

For HDRP Projects

Create a new 2020.3 Unity project

Under Project Template, select 3D Sample Scene (HDRP)

Configure Unity Project Settings

Configure the following settings before import the VotanicXR SDK:

Configure API Compatibility Level. In Edit > Project Settings > Player, set the Api Compatibility Level to .Net 4.x Equivalent in Configuration section.
Configure Editor Setting. In Edit > Project Settings > Editor, set the Version Control to Visible Meta Files and Asset Serialization to Mixed.
Configure Build Architecture. In File > Build Settings, set the Architecture to x86_64.

Import VotanicXR and tutorial content

Import VotanicXR Package

The VotanicXR for Unity SDK Package can be accessed from the VotanicXR Suite.

Select Unity SDK will open the VotanicXR Unity SDK folder shown below:

The VotanicXR 2020 for Unity SDK is available in three variations: VotanicXR 2020 for 2018.4 - targeted for Unity 2018.4 version, VotanicXR 2020 for 2019.2+ - targeted for Unity 2019.2 to 2019.4, VotannicXR 2020 for 2020.3 - targeted for Unity 2020.3 - 2021.3, and VotanicXR 2020 for 2020.3 HDRP - targeted for Unity 2020.3 - 2021.3. The below table highlight the corresponding unity version and VotanicXR SDK version. VotanicXR 2020 may work with newer Unity releases than these listed in the table, but full compatibility is not guaranteed. Due to limitation of the Unity engine, it is highly recommended that you use the LTS (Long-Term Support) version of Unity for development, and do not switch major release version of the Unity engine for your project once it is set up with the corresponding VotanicXR Unity SDK.

Unity Version	VotanicXR SDK
< 2018.4	-not supported-
2018.4	VotanicXR_2020.x for 2018.4.unitypackage
2019.1	-not supported-
2019.2 – 2019.4	VotanicXR_2020.x for 2019.2+ [NET].unitypackage
2020.3 – 2021.3	VotanicXR_2020.x for 2020.3.unitypackage
2020.3 – 2021.3 HDRP Project	VotanicXR_2020.8.6f8 for 2020.3 HDRP.unitypackage

The VotanicXR 2020 for Unity SDK importing process is a bit different for various Unity versions due to several changes in Unity's components and APIs in recent versions. Please follow the importing procedure for the corresponding version below:

For Unity 2018

Right-click in Project windows. Click Import Package > Custom Package, and select the VotanicXR SDK package.
Select all files in the Importing Package dialog, and click Import button.

For Unity 2019

Go to Unity Package Manager and install Multiplayer HLAPI for this series of tutorial.
Right-click in Project windows. Click Import Package > Custom Package, and select the VotanicXR SDK package.
Select all files in the Importing Package dialog, and click Import button.

For Unity 2020 & 2021

Select Window > Package Manager.
Install NewtonSoft Json.

In the Package Manager, select the + button and choose Add package from git URL.

Type com.unity.nuget.newtonsoft-json in the text box then click Add. Unity will automatically fetch and install NewtonSoft Json for the project
Install Multiplayer HLAPI.
1. For Unity 2020: In the Package Manager, locate and install the Multiplayer HLAPI.
1. For Unity 2021: Go to project folder and open Packages > manifest.json, add ["com.unity.multiplayer-hlapi": "1.1.1",] under dependencies and save.
Install XR Plugin Management & OpenXR Plugin.

After installing the OpenXR Plugin, confirm using the new input system and restart Unity Editor.
After restarting the Editor and re-opening the project, open the Build Settings window by selecting File > Build Settings then click the Player Settings button as shown below:

In Project Settings, select XR Plug-in Management and choose as the Plug-in Provider, then click on the warning sign next to the OpenXR option.

Click Fix All to fix all issues identified during OpenXR project validation.
Under XR Plug-in Management, select OpenXR and change the Render Mode to Multi Pass.
Import VotanicXR for Unity 2020.3 packages:
1. For standard 3D Core projects: Double click the VotanicXR for Unity 2020.3 package to import the VotanicXR SDK to Unity
2. For HDRP projects: Double click the VotanicXR for Unity 2020.3 HDRP package to import the VotanicXR SDK to Unity
Open the OpenXR setting window again, under Interaction Profiles, select the + button and add the profiles to the lis

The setting page should look like below after adding the profiles:
(Optional) When OpenXR is enabled, VotanicXR uses the available OpenXR runtime when running the VotanicXR Application. For systems connected to multiple head-mounted display (HMD) VR systems, it is necessary to configure the OpenXR runtime before running the application.
1. For SteamVR Headsets
  1. Install SteamVR Software
  2. Open Settings
  3. Turn on Developer Settings and set SteamVR as Current OpenXR Runtime
2. For Oculus / Meta Quest
  1. Install Oculus Software
  2. Open Settings > General, allow content from Unknown Sources, and set Oculus as Current OpenXR Runtime.
3. For Windows Mixed Reality Headset
  1. Install SteamVR Software, and set SteamVR as Current OpenXR Runtime. (Refer to 9.1)
  2. After connecting the headset, open SteamVR and install Windows Mixed Reality driver following the pop-up prompt.
You are now ready to use VotanicXR in Unity.

Note: If you encounter the below error regarding multiple copies of NewtonSoft dll:

Multiple precompiled assemblies with the same name Newtonsoft.Json.dll included on the current platform. Only one assembly with the same name is allowed per platform. (Assets/Votanic/VotanicXR/Plugins/Core/Newtonsoft.Json.dll)

Please refer to this FAQ entry to resolve the issue.

Import Tutorial Package (for Non-HDRP projects only)

Download Tutorial Package

Click here to download the tutorial package.

Import the Tutorial Package of VotanicXR:

Right-click in Project windows. Click Import Package > Custom Package, and select the tutorial package to download.
Select all files in the Importing Package dialog, and click Import button.

Note: Tutorial package must be imported after the VotanicXR package, as some tutorial prefabs and scripts require VotanicXR base classes and materials.

Add VotanicXR Manager to Scene (for Non-HDRP projects)

Open Sample Scene

In Project windows, select Assets > Votanic > VotanicXR_Tutorial > Tutorial01_GettingStarted, open the Demo scene.

Demo Scene

Add vGear SDK Manager

Right-click in the Hierarchy window.
Click VGear > SDK Manager . This will add the vGear and the GameObject StartPoint to the scene’s hierarchy.
Agree to VotanicXR Licensing Agreement (first-run only)

If it is the first time you are adding vGear SDK Manager to your scene, you must read and agree to the VotanicXR Licensing Agreement first. The vGear GameObject will be disabled until this step is completed.
Configure XR Support

Every time when vGear SDK Manager is added to the scene, you will be prompted about configuring XR Support for your scene.

For best cross-platform compatibility, we recommend that you enable XR Support by selecting the Confirm button. This will add Unity XR libraries to your scene. Please wait awhile for Unity to finish importing these libraries. If you prefer to add the XR Support later, you can select Cancel here.

Note that you must set XR Support to Role System before building the scene if you would like your application to be cross-platform and playable in HMD systems.
VotanicXR is ready to use!

vGear SDK Manager is a group of components for creating VR environment. It includes VotanicXR core classes, cameras, and Input system. This GameObject must be present for other VotanicXR components to function, such as Media, and Behaviour system.

StartPoint represents where the player will be standing when the application starts. You can change the transform of the StartPoint to adjust the starting position of the player. In Game and Scene windows, it is indicated by a giant red cross symbol whereas the robot is a virtual representation of the user in the game for size reference, both of which will be hidden in Play mode automatically.

For HDRP projects in Unity Sample Scene

Add vGear SDK Manager

Right-click in the Hierarchy window, select vGear > SDK Manager . This will add the vGear and the StartPoint GameObject to the scene's hierarchy.
Agree to VotanicXR Licensing Agreement (first-run only) and XR support in the same way as non-HDRP projects.

Scene Object Settings

For Lighting, set Layer of “Volumes” to vLayerCore
For Props, set Layer of “Structure” to vLayerFloor
Open vGear -> Boudary, select and disable the Floor object
Play the project in Unity, the HDRP project should be running normally

Note: you can also load the template scene in the vGear folder to inspect how each default component works in HDRP:

Configure VotanicXR Settings

Basically, VotanicXR’s settings can be configured in two ways, one is inside Unity Editor, another one is an external setting.vxrs file. The setting.vxrs file path is defined in the vGear SDK manager Setting Path property.

The below table summarized what type of settings are included in the Application Setting, and the related setting location in the Unity editor.

Application Setting	vGear SDK Manager GameObject Path	Inspector Location
XR Attributes	vGear	V Gear (Script) -> Attribute
Performance	vGear	V Gear (Script) -> [Performance]
Frame & User	Frame: vGear -> Frame User: vGear -> Frame -> User	V Cast_Frame (Script) -> [Settings] V Gear_User (Script) -> [Settings]
Controllers*	vGear -> Frame -> Controller	V Gear_Controller (Script) -> [Settings]

*Controllers setting will be further discussed in the in-game tools section

By default, if the scene is played in the Unity Editor, the above settings defined in the inspector will be used rather than the setting.vxrs file. If you would like to test the configurations defined in the application setting file while running the scene in Unity Editor, it is required to uncheck the Use Editor Setting property.

The application setting in Unity Editor will be exported and saved to the application setting setting.vxrs file when building the application. If you do not want the Unity Editor executes this action, it is required to uncheck the Auto Apply Setting in vGear inspector window.

Test Run in Unity Editor

You can test run the VotanicXR application in Unity Editor. When the application is loaded, the vGear GameObject will be populated with objects according to the Config and Setting files defined in vGear. By default, the PC config is loaded for in-editor testing. If you would like to use the HMD to test in Unity Editor, change the Config Path from xxxxxx/ConfigPC.vxrc to xxxxxx/ConfigHMD.vxrc, and make sure XR Support is set to Role System before hitting the play button.

Remark: For Unity 2020 or later, the HMD device must be in active state (wearing by user) in order to get button input from VR controllers.

Build the Scene

When building the VotanicXR application, VotanicXR creates a series of batch files that can launch the application for different hardware / software systems. By default, batch files are created for PC, HMD, CAVE, and DOME system. User can select which batch file to be created in the Build Batches setting in vGear SDK Manager.

VotaincXR builds 1 standalone PC application that can adapt to settings of different PC-based VR systems. Make sure you have correctly configured the Unity project setting as introduced at the beginning of this section, then perform the following steps to build the VotanicXR application:

Go to File > Build Setting.
Click Add Open Scenes .
Click Build, (Note: It is recommended to create a new folder to save your published build files).
When the build process is completed, the build folder will be opened in the file explorer.

Running the Application

The output folder will contain some batch (.bat) files with the format {Project Name}_[{Environment}].bat.

Double click the batch file to start the application with different pre-defined environment configuration. The differences between various environment are shown in below table.

Environment	Config Location	Remark
CAVE	Loading the configCAVE.vxrc file in %VOTANIC_PATH%/Configs/	The CAVE system’s global configuration in production environment
HMD	Loading the configHMD.vxrc file in %VOTANIC_PATH%/Configs/	The HMD system’s global configuration in production environment. This configuration enabled HMD and controllers.
PC	Loading the configPC.vxrc file in %VOTANIC_PATH%/Configs/	The PC system’s global configuration in production environment. This configuration use keyboard and mouse as output.
DOME	Loading the configDOME.vxrc file in %VOTANIC_PATH%/Configs/	The DOME system’s global configuration in production environment.
Local CAVE	[output folder]\VotanicXR\Configs ConfigCAVE.vxrc	The local CAVE system’s configuration in output folder for testing purpose.
Local HMD	[output folder]\VotanicXR\Configs ConfigHMD.vxrc	The local HMD system’s configuration in output folder for testing purpose.
Local PC	[output folder]\VotanicXR\Configs ConfigPC.vxrc	The local PC system’s configuration in output folder for testing purpose.
Local DOME	[output folder]\VotanicXR\Configs ConfigDOME.vxrc	The local DOME system’s configuration in output folder for testing purpose.