Skip to content

Starting Development

Jump to bottom
Raphii edited this page Jul 28, 2024 · 24 revisions

In case you want to get started with developing on OyasumiVR, you're in the right place! On this page you will find instructions on how to set up the project, as well as various details regarding the project that might come in useful.

Setting up your environment

Installing Prerequisites

NodeJS

Start by installing NodeJS. This is necessary for building the web frontend for the main UI, and running most of OyasumiVR's build scripts. Sticking to the current LTS version should be good. If it's not compatible, Angular will tell you which version you need during the build process.

Install Rust & Tauri

Next, follow Tauri's prerequisites. Tauri is the Rust-based desktop framework that OyasumiVR is built with, so you need its development tools to get started.

After you've followed their prerequisites, verify you have at least the following tools installed:

  • VS C++ Build tools
  • WebView2
  • Rust Stable
  • The Tauri CLI

Install Clang & LLVM

Next, you need to install clang. This is required for generating the bindings to OpenVR. You need LLVM v17. With older or newer versions you'll run into build errors.

Following the linked guide, make sure to:

  1. Install Clang (e.g. through winget install LLVM.LLVM --version 17.0.6)
  2. Set the LIBCLANG_PATH environment variable to the bin directory of your LLVM install.

Install the .NET 8 SDK

Install the .NET 8 SDK. This is required for building the SteamVR overlay and MDNS sidecars.

Install ProtoC

Install ProtocolBuffer's ProtoC, and make sure it is available on your PATH.

Initializing the project

Now that you've got all the prerequisites installed, we can start by setting up the project:

  1. Check out Oyasumi somewhere on your machine: git clone https://github.com/Raphiiko/OyasumiVR.git
  2. Change into the new project directory: cd OyasumiVR
  3. Run the initialisation script with npm run init. This will install all required NPM packages for both the main UI and the overlay UI, and move the necessary files into places where they need to go.
  4. Now run npm run build:pre.

Now you're all set up! From here on, you can run npm run start or npm run dev to start OyasumiVR. Check out the NPM Scripts section for the difference between these two, as well as "Running in development mode" for more information.

Modules & Structure

There are various different modules to OyasumiVR, so here is a bit of an overview of them, and the folders they are in:

Main UI (/src-ui)
This is where most of OyasumiVR lives. This folder contains the Angular project that renders the main UI, and contains most of the apps' logic. OyasumiVR is mostly a web application.

Core (/src-core)
This is where OyasumiVR's Rust-based core lives. It contains all native platform functionality that Oyasumi requires, as well as certain functionalities that require the level of efficiency that cannot be achieved in the main ui. This is the entry point for the desktop application.

Overlay Sidecar (/src-overlay-sidecar)
This folder contains the .NET project that is OyasumiVR's SteamVR overlay. It is run as a sidecar to the main process, hence the name: Sidecars are auxillary processes for OyasumiVR. It uses the Chromium Embedded Framework (CEF) to render the web-based overlay UI in VR.

Overlay UI (/src-overlay-ui)
This folder contains the SvelteKit project that renders the UI for OyasumiVR's SteamVR overlay. It is used by the overlay sidecar for rendering most of the UI elements you see.

Elevated Sidecar (/src-elevated-sidecar)
This folder contains the Rust code for OyasumiVR's elevated sidecar module. The elevated sidecar is an auxiliary process that is launched with administrative permissions. It is used by OyasumiVR to be able to control some things that require this level of permissions (such as GPU power limits through NVML), without requiring elevated permissions itself. The reason it exists is because if the main process would be run with elevation, the main window would not be interactable when using it through many of the other SteamVR overlay applications.

MDNS Sidecar (/src-mdns-sidecar)
This folder contains the .NET project that is OyasumiVR's MDNS sidecar module. This is used to advertise OyasumiVR's OSCQuery server over zeroconf/mdns, for other applications (like VRChat) to find it.

Shared Library (Rust) (/src-shared-rust)
This folder contains any Rust code that is shared between both the elevated sidecar, and the core.

Shared Library (TypeScript) (/src-shared-ts)
This folder contains any TypeScript code that is shared between both the overlay UI, and the main UI.

Protobuf Schemas (/proto) This folder contains the protocol buffer schemas that are used for communication between the main application and its sidecars. From this, models and gRPC clients/servers are generated for each of OyasumiVR's modules, in their respective programming languages.

gRPC Web Client (/src-grpc-web-client) This folder contains the models and gRPC clients generated from the protocol buffer definitions in /proto. The folder contains only generated source files, and should therefore never be altered manually. The files inside can be regenerated by running npm run generate:grpc-web-client.

NPM Scripts

In this section I've documented some of the more notable NPM scripts and what they do. You run these with npm run <script name>.

Script Description
start Runs Oyasumi in 'release' mode.

This has the following effects:
  • Ports for gRPC and gRPC-Web on the core and overlay sidecar will be randomly allocated.
  • The port for the HTTP server on the core will be randomly allocated.
  • OyasumiVR will launch the most recently built overlay sidecar.
If you are working on the overlay sidecar, or the overlay ui, look into using `npm run dev` instead!
dev Runs Oyasumi in 'dev' mode.

This has the following effects:
  • Ports for gRPC and gRPC-Web on the core and overlay sidecar will be set to their development ports
  • he port for the HTTP server on the core will be set to its development port
  • OyasumiVR will not attempt to launch the overlay sidecar, or the overlay sidecar UI. You are expected to run these yourself separately.
This script is useful when you are working on the overlay sidecar, or the overlay UI. For more information, check out Running in development mode.
generate:grpc-web-client Generates new TypeScript models and web clients for gRPC communication between OyasumiVR's different modules. Run this when you have changed any of the protobuf definitions in the /proto/ folder.
clean Removes most of the build artifacts scattered throughout the project folder, allowing you to start building with a clean slate.
build or build:core Builds OyasumiVR in its entirety, including an installer bundle. Do note that this can take quite a while.
build:sidecars Builds all sidecars.
build:sidecar:elevated Builds the elevated sidecar
build:sidecar:overlay Builds the overlay sidecar
build:sidecar:mdns Builds the MDNS sidecar
build:front Builds the main UI
set-version <semver> Sets a new version number in all relevant files.
set-flavour <DEV|STANDALONE|STEAM|STEAM_CN> Sets the flavour to build and/or run, meant for making builds that require slightly different functionality.
DEV: The default. Every development build has this flavour set.
STANDALONE: For release builds distributed through GitHub, Gumroad and Booth.
STEAM: For release builds distributed through Steam.
STEAM_CN: For release builds distributed through Steam to mainland China.

Overlay UI: NPM Scripts

The overlay ui in /src-overlay-ui comes with its own set of npm scripts:

Script Description
dev Runs the Overlay UI in development mode. Run this if you want to test the overlay UI in the browser, or if you are using `npm run dev` on the main project!

Running in development mode

Running in development mode (using npm run dev) is useful when working on the sidecars. By default when you run OyasumiVR in release mode (using npm run start), the overlay sidecar is not rebuilt, and instead OyasumiVR launches the most recently built version by itself. Additionally, all ports that are bound are randomly allocated. This is not great when you're trying to work on the sidecar, or debug any of the HTTP/gRPC endpoints.

For this reason, you can run the project in development mode. Running in development mode however, requires you to run the overlay sidecar and its UI by yourself. This goes as follows:

  1. Start OyasumiVR in development mode: npm run dev.
  2. Open a secondary terminal, and start the overlay UI in development mode: npm run start:overlay-ui.
  3. Open a third terminal, and start the overlay sidecar: npm run start:overlay
    or alternatively: open src-overlay-sidecar in your favourite .NET IDE, like Rider, Visual Studio, or VS Code, and run it from there!

If in step 3 you choose to run the overlay sidecar in your IDE, instead of using the npm script, make sure to pass dev as the first argument to ensure it runs in development mode.

Note that the elevated sidecar does not currently contain a development mode, and its ports are always randomly allocated.

Development Ports

In production, most of the ports that OyasumiVR uses are randomly allocated, to prevent running into already bound ports. During development however, there are extra ports for development purposes, as well as defaults when running the project in development mode. Here you will find a reference of them.

Port Number Description Notes
4200 The port Angular serves the main UI on when running the project through `npm run start` or `npm run dev`.
5173 The port SvelteKit serves the overlay UI on when running it standalone with `npm run start:overlay-ui`.
5174 The gRPC port for the overlay sidecar Only bound when running in development mode. Otherwise randomly allocated.
5175 The gRPC-Web port for the overlay sidecar Only bound when running in development mode. Otherwise randomly allocated.
5176 The gRPC port for the core module Only bound when running in development mode. Otherwise randomly allocated.
5177 The HTTP port for the core module Only bound when running in development mode. Otherwise randomly allocated.
Clone this wiki locally