VR - Oculus Rift
Overview
Oculus Rift support is now included in CRYENGINE 3.8.1 and beyond. This article will guide you through setting up VR and any important information you should know before you get started.
Getting Started
- Drivers: Install the most up to date drivers - Available from Oculus. We currently support version 0.8.0.0 Beta.
- Oculus Documentation: Please read the documentation regarding device set-up & configuration - Available from Oculus.
- Health & Safety: Please carefully read the H&S information - Available from Oculus.
- Video Drivers: Update your Video Card Driver and ensure that you are running the most recent revision that supports Oculus Rift.
- Recommended PC Spec: Information regarding hardware requirements - Available from Oculus.
The Sandbox Editor does not currently support the Oculus Rift device. To run CRYENGINE with the Oculus enabled, you must do so through the CRYENGINE GameSDK.exe.
Rift Display Mode: CRYENGINE uses the Direct HMD Access from Apps option in the Tools -> Settings mode.
To help preserve the lifetime of your kit keep the Rift Saver enabled.
Once you have completed the set-up above and your device is working and initializing properly with the Oculus Demo test scene, then you are ready to use the device with CRYENGINE.
Click the "Show Demo Scene" button found at the bottom of the Oculus Configuration Utility to test if the device is working correctly. This tool Should appear in your system tray.
VR Setup for CRYENGINE
The process of enabling VR in CRYENGINE has been designed to be as simple as is possible. However, as CRYENGINE is shipped to also function in non-VR mode we cannot initialize everything for users i.e. 'VR out of the box'. Some configuration files are available to users that will set the required parameters so that the relevant engine features are initialized and the VR mode will run. If you are making a purely VR-based game then you can make these values your default settings.
When using VR, your build should look something like the following screenshot:
Notice the extra file in the root of the folder. The user.cfg is a file that the engine will always look for on boot:
This file is used to initialize the engine to run in VR mode. The file can be download by clicking the link above.
We didn't include this file into the build by default because you may already have a specific user.cfg in use and it would've been replaced accidentally. Therefore, please download the user.cfg linked above. You can then add the appropriate CVars from the downloaded file into your own user.cfg.
The vr.cfg is a new file which we have created and contains the relevant CVars that will initialize once the launcher (GameSDK.exe) has been loaded & in the main menu. We had to separate the vr.cfg from the user.cfg because we are modifying certain CVars that will be reset if placed in the user.cfg, on engine load.
This is stored in the folder: <root>\engine\config\vr.cfg (inside the engine.pak)
This is because the system spec configuration files (sys_spec 1,2,3,4) are loaded after the user.cfg
Example: Setting r_motionblur = 0 in the user.cfg this will be reset back to r_motionblur = 2
Because...
Build\engine\Config\CVarGroups\sys_spec_Full.cfg sets the required CVar groups as per system spec. (Default is sys_spec 4)
A portion of this .cfg calls another file Build\engine\Config\CVarGroups\sys_spec_PostProcessing.cfg
This is where the r_motionblur is set back to 2
Due to the order in which files are loaded i.e. user.cfg first, then sys_spec_Full.cfg second is why we need to separate out some of the CVars from the vr.cfg
User.cfg
This configuration file (*.cfg) contains a list of CVars that are required to be set at engine boot/launch.
-------------------------------------------
-- HMD Related
-------------------------------------------
sys_vr_support = 1 (specifies if virtual reality devices should be enabled)
r_overrideDXGIoutput = 0 (specifies the index of display to use for output (0=primary display))
r_stereodevice = 100 (the default auto-detect mode for picking-up the various HMD units attached to the ENGINE)
r_stereomode = 1 (controls the method of stereo rendering we use 0 = off, 1 = Dual rendering, 2 = Post stereo)
r_stereooutput = 7 (controls the stereo method (Side by side, interlaced etc... 7 = Oculus Rift)
r_minimizeLatency = 1 (self explanatory)
hmd_low_persistence = 1 (enables low persistence mode)
r_stereoScaleCoefficient = 1 (multiplier which influences the perceived scale of the world in VR (1.f = no effect, 0.25 = approx. 1/4 the size)
-----------------------------------------------
-- Resolution (backbuffer and eye textures)
-----------------------------------------------
r_width = 960
r_height = 1080
r_backbufferWidth = 1920
r_backbufferHeight = 1080
As each eye is rendering independently the "overall width" (1920) is divided by 2 to get r_width = 960.
Height is unaffected so remains at 1080.
VR.cfg
This configuration file needs to be executed once the game has been launched and is sits inside the menu front end.
You should already be in the dual rendering mode, where the screen is displaying the dual eye set-up on the monitor and both eye viewports on the Oculus Rift device are active.
To execute the vr.cfg, bring down the console with the ~key and type:
exec vr
This will process the vr.cfg, and set all the CVars that are contained within the .cfg file.
-----------------------------------------------
-- Resolution (backbuffer and eye textures) (Already set via the user.cfg at boot)
-----------------------------------------------
r_width = 960
r_height = 1080
r_backbufferWidth = 1920
r_backbufferHeight = 1080
-------------------------------------------
-- Set the system Spec (Medium)
-------------------------------------------
sys_spec = 2 (sets the launcher to medium spec. Default is sys_spec = 4, set in the system.cfg)
-------------------------------------------
-- HMD related (Already set via the user.cfg at boot)
-------------------------------------------
r_overrideDXGIoutput = 0
r_stereodevice = 100
r_stereomode = 1
r_stereooutput = 7
r_minimizeLatency = 1
hmd_low_persistence = 1
r_stereoScaleCoefficient = 1
-------------------------------------------
-- Set some video optimisations
-------------------------------------------
r_vsync = 0 (disable V Sync)
r_motionblur = 0 (turns off motion blur. (When enabled the effect is not a pleasant experience in VR)
r_ssdoHalfRes = 3 (default is 2)
r_Refraction = 0 (disables refraction)
r_DeferredShadingTiled = 0 (disables deferred tiled shading)
r_CBufferUseNativeDepth = 0
-------------------------------------------
-- Hide the hud
-------------------------------------------
--Hud_hide = 1 (hides the hud. Currently commented out so the hud will be visible as per default. If this is not to your liking, then remove the "--" to activate the 'hide' command). Although this does give some reference to which direction your body is pointing, so have it enabled assists in orienting yourself in the VR world.
Resetting your HMD Device
Say your "default pose" is sitting down in a normal comfortable position looking directly at the tracking device. But;
On boot of the launcher (GameSDK.exe) the headset has been left on a table. This is not the recognized "default pose" of the Oculus device so when putting the device on it is not in the correct forward view.
To reset - put the headset on and bring down the console with key ~ and type:
hmd_center_pose
This assumes you are now positioned in the 'new' "default pose" and with your head pointing directly at the tracker and looking straight forward. This action will reset the Oculus viewport as if you were standing (in-game) with your head looking straight forward and perpendicular to your shoulders i.e. standing normally.
Resetting can be accomplished as often as you like during a game session. However, resetting is generally not necessary and is only required if the Oculus device and the tracker unit get out of sync.
Input Configuration
If so desired you can bind this directly to a key/gamepad button. This can be achieved via Flowgraph Input:Key node.
Alternatively, you could modify the <game_folder>\Libs\Config\DefaultProfile.xml file and assign a button there.
See Setting up Controls & Actionmaps for more information.
Flowgraph
We have exposed some controls / functions that are related to the HMD device. This can be accessed through Flowgraph:
- VR:GetCameraAngles
- VR:Tools
- VR:GetCameraAngles
The node outputs the YPR of the HMD device.
- VR:Tools
This allows you to hookup an input to trigger the RecenterPose command.
Quick Start Guide
- Configure your Oculus device to work with Windows.
- Get the 3.8.1 (or later) release of CRYENGINE.
- Download the user.cfg & place it in the root of the build (or copy the info above into your own user.cfg if you use one).
- Re-read Health & Safety information - Available from Oculus.
- Launch GameSDK.exe.
- Once in the Menu, bring down the console with the tilda key (~).
- Type exec vr.
- Load your map.
Possible issues you could encounter
- Running the editor with the user.cfg. This will try to enable VR in editor mode, which it will attempt, but can't do. Rename the user.cfg to something else such as "_user.cfg". This will bypass the file being read on loading of the Editor. Make sure to rename it back to user.cfg when you want to use VR again in the launcher.
- In some instances the Launcher (GameSDK.exe) boots to a black screen. The game is active in the background but nothing visually represented on screen. This can be resolved by deleting the user folder in the root of the build. Then relaunch the GameSDK.exe.
- In some extreme instances, it can boot to an orange screen detailing "Application is paused while an old SDK application is rendering". Try stopping and restarting the Oculus service through the Oculus Configuration Utility, under the Tools menu.