Adding the Hotham Simulator to your development environment

Introduction

NOTE: This can get annoying if you use OpenXR regularly on your device, eg. for playing games. The Steam and Oculus apps both have handy ways of "restoring" the previous OpenXR runtime when you want to go back.

Hotham comes with a lightweight OpenXR simulator to help ease development and run unit tests. To make that work on your device, you'll need to make sure your desktop is using the Hotham Simulator as your default runtime.

Windows

You'll need to add/modify the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenXR\ActiveRuntime value so that it points to where you've got <HOTHAM_LOCATION>\hotham-simulator\hotham_simulator.json

On my machine this looks like

[HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenXR\1]
"ActiveRuntime"="C:\\Users\\kanem\\Development\\hotham\\hotham-simulator\\hotham_simulator.json"

You can find more details in the OpenXR documentation.

Linux

On Linux, you'll need to do a little more work. The steps are outlined in the OpenXR documentation, but you'll essentially need to create your own active_runtime.json file in /etc/xdg/openxr/1/active_runtime.json that looks something like this:

{
  "file_format_version": "1.0.0",
  "runtime": {
    "api_version": "1.0",
    "name": "Hotham Simulator",
    "library_path": "<HOTHAM_INSTALL_LOCATION>/target/debug/libhotham_simulator.so"
  }
}

Then you'll need to install some additional packages (as per monado docs) and the Vulkan validation layers:
sudo apt install libopenxr-loader1 libopenxr-dev libopenxr1-monado
sudo apt install vulkan-validationlayers

Troubleshooting

Linux Simulator Rendering Error

On occasion, Hotham will select the wrong graphics card for rendering. If that happens you'll see an error similar to the following:

[HOTHAM_VULKAN] Initialising Vulkan..
Required Vulkan instance extensions: ["VK_KHR_surface", "VK_KHR_xlib_surface"]
MESA-INTEL: warning: Performance support disabled, consider sysctl dev.i915.perf_stream_paranoid=0

[HOTHAM_SIMULATOR] Created physical device: 0x55a35592f600
[HOTHAM_VULKAN] Creating logical device..
[HOTHAM_VULKAN] Using device extensions: ["VK_KHR_swapchain"]
WARNING: lavapipe is not a conformant vulkan implementation, testing use only.
../src/gallium/frontends/lavapipe/lvp_device.c:1216: VK_ERROR_FEATURE_NOT_PRESENT
[HOTHAM_SIMULATOR] Destroy called..
[HOTHAM_SIMULATOR] All things are now destroyed
thread 'main' panicked at '!!FATAL ERROR - Unable to initialise OpenXR!!: Requested feature is not available on this device', hotham/src/engine.rs:73:30
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

(This can also manifest with Extension specified does not exist)

Manually exporting an env variable pointing to the correct icd should remedy the error:
export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/nvidia_icd.json, substituting nvidia_icd.json with your graphics card vendor.

Troubleshooting

Hotham Simulator can be a pretty temperamental piece of software. It's still very much in its infancy and has lots of bugs that need to be ironed out. But, the trusty Hotham community is always on hand to help. Just drop into the Discord and we'll get you sorted!