Skip to content

Getting started

Jump to bottom
David Kuhta edited this page Feb 15, 2022 · 19 revisions

Getting started with Hotham

Introduction

So you want to get started building something with Hotham? Awesome.

Here's how to do it.

Pre-requisites

Git LFS

Make sure you've got Git LFS installed and enabled for this repo. You'll have a real bad time if you don't.

Rust

If you haven't got Rust installed yet, go ahead and install it from the official website. Once you've got rustup installed, add the Android target too with

rustup target add aarch64-linux-android

Cargo APK

cargo apk is a tool that packages Rust applications into Android APKs so they can be run on mobile headsets. You can install it with: cargo install cargo-apk

Android SDK/NDK and Java JDK

With Android studio

If you're happy with Android studio, you can install them together from the official website. Note that you must use NDK r22b and Android SDK 28 as ndk-glue has some issues with newer versions.

Without Android studio

If that's not your jam, you can download the NDK directly here and either download the SDK directly, or install it with your system's package manager on Windows, macOS or Linux.

Once you have the SDK installed, make sure you use sdkmanager to install build-tools. You can read the docs if you haven't fiddled with sdkmanager before.

Important notes:

  • Make sure you're using NDK r22b
  • Make sure you're using SDK 28
  • Make sure you have build-tools installed
  • Make sure you have platforms installed

The Java JDK is required for APK signing, so you'll need to install that separately. It's recommended to use the Oracle distribution for best compatibility, but we haven't had any reports of issues using OpenJDK.

Headset setup

NOTE: Hotham currently supports the Oculus Quest 2. There is some limited support for the Quest 1, but this can't be guaranteed for the future. If you have another device you'd like to use with Hotham, let us know and we'll see what we can do!

NOTE: If you don't own a headset and just want to have a poke around, don't stress. You can skip down to the bottom section for instructions on how to use the Hotham Simulator. But if you really do want to start developing VR applications, buy a Quest 2. If you ask nicely on the Discord someone could even share a referral code. 😉

First, you'll need an Oculus Developer account. Go ahead and set one up.

Once you're done, put your device into Developer mode and connect it to your machine.

With all that done, you should now be able to see your device from ADB:

user@host:~/hotham$ adb devices
List of devices attached
1PASH9B12E0092	device

Simulator setup

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/hotham_simulator.dll"
  }
}

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

First build

Phew! You made it through all the pre-requisites. Go ahead and stand up, have a stretch and make yourself a cup of tea/coffee/your_beverage_of_choice. You earned it! Don't worry, we'll still be here when you get back.

Done? Good. Let's build this bad boy.

Building the whole gosh darn thing

Let's build the entire repo, examples and all to make sure that you followed all the steps correctly. Here's the moment of truth:

cargo build

Troubleshooting

Did it all explode in a fireball? Hopefully not. If it did, go back over the checklist above a couple times and see if you missed anything. If you're still running into issues, just jump onto the Discord and we'll be able to sort you out!

Running an example

Everything built okay? Great! Now let's up the ante. Let's run one of the examples on your headset. Arguably the most fun example is "Crab Saber", so let's run that.

Windows

We've helpfully included a couple of Powershell scripts to automate things on Windows. You'll need to follow these instructions before running them.

From the root directory, just run:

.\run_on_device.ps1

And with any luck you should be good to go.

Linux / macOS

You know what to do. From the root directory run:

./run_on_device.sh

Troubleshooting

There are so many things that can go wrong at this step. If you're still having trouble, jump onto the Discord and we'll help you out!

Next steps

Alright! So you've played a bad version of Beat Saber.. now what? Well, more than likely you're going to want to create your first application. We're still in the process of documenting that, but for now, try copying the simple_scene_example or beat_saber_example directories into a new repository, getting them built and see what you can do with them!

Clone this wiki locally