Skip to content

Getting started

Jump to bottom
Kane Rogers edited this page Jul 21, 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

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 (22.1.7171670) 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 Android command-line tools directly from this link, scrolling down to "Command Line Tools", or install it with your system's package manager on Windows, macOS or Linux.

Once you have the tools installed, make sure you use sdkmanager to install Android SDK 28 and the build-tools package. 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.

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

Ninja and cmake

You'll need to make sure you have both ninja and cmake available on your PATH somehow. On Windows, this can be a bit annoying, but you can find some packages to make this easier by installing the Chocolatey packages for ninja and cmake respectively.

shaderc

Note: shaderc does ship with the Vulkan SDK, so if you've got this installed, you can skip this step.

We use shaderc to compile our shaders at build time, so you'll need to make sure it's installed and available on your PATH.

Optional - Vulkan SDK

The Vulkan SDK comes with a bunch of useful tools for Vulkan development. We recommend installing it if you haven't already.

Setting up your development environment

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:

.\examples\crab-saber\scripts\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:

./examples/crab-saber/scripts/run_on_device.sh

Using the simulator

After setting up the simulator, running examples should be as simple as:

cargo run --bin hotham_crab_saber --release

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