114 lines
6.1 KiB
Markdown
114 lines
6.1 KiB
Markdown
# Stardust XR Server
|
|
|
|
Stardust XR is a display server for VR and AR headsets on Linux-based systems. [Stardust provides a 3D environment](https://www.youtube.com/watch?v=v2WblwbaLaA), where anything from 2D windows (including your existing apps!), to 3D apps built from objects, can exist together in physical space.
|
|
|
|
|
|
|
|
Command line installation of core & dynamic dependencies are provided below:
|
|
<details>
|
|
<summary>Ubuntu/Debian</summary>
|
|
<pre><code class="language-bash">
|
|
sudo apt update && sudo apt install \
|
|
build-essential \
|
|
cargo \
|
|
cmake \
|
|
libxkbcommon-dev libudev1 libinput10 libcap2 libmtdev1 libevdev2 libwacom9 libgudev-1.0-0 \
|
|
libglib2.0-dev libffi8 libpcre2-dev libxkbcommon-x11-dev libxcb-dev libxcb-xkb-dev libxau-dev \
|
|
libstdc++-dev libx11-dev libxfixes-dev libegl-dev libgbm-dev libfontconfig1-dev libgl-dev \
|
|
libdrm-dev libexpat1-dev libfreetype6-dev libxml2-dev zlib1g-dev libbz2-dev libpng-dev \
|
|
libharfbuzz-dev libbrotli-dev liblzma-dev libraphite2-dev
|
|
</code></pre>
|
|
</details>
|
|
|
|
<details>
|
|
<summary>Fedora</summary>
|
|
<pre><code class="language-bash">
|
|
sudo apt update && sudo apt install \
|
|
cargo \
|
|
cmake \
|
|
libxkbcommon-devel systemd-devel libinput-devel libcap-devel mtdev-devel libevdev-devel glib2-devel \
|
|
libffi-devel pcre2-devel libxkbcommon-x11-devel libxcb-devel libXau-devel libstdc++-devel libx11-devel libxfixes-devel \
|
|
mesa-libEGL-devel mesa-libgbm-devel fontconfig-devel libdrm-devel expat-devel freetype-devel libxml2-devel zlib-devel \
|
|
bzip2-devel libpng-devel harfbuzz-devel brotli-devel xz-devel graphite2-devel
|
|
</code></pre>
|
|
</details>
|
|
|
|
|
|
<details>
|
|
<summary>Arch Linux</summary>
|
|
<pre><code class="language-bash">
|
|
sudo pacman -Syu --needed \
|
|
cargo \
|
|
cmake \
|
|
libxkbcommon systemd libinput libcap mtdev libevdev libwacom glib2 libffi pcre2 libxkbcommon-x11 \
|
|
libxcb libxau libx11 libxfixes mesa fontconfig libdrm expat freetype2 libxml2 zlib bzip2 \
|
|
libpng harfbuzz brotli xz graphite
|
|
</code></pre>
|
|
</details>
|
|
|
|
## Installation
|
|
|
|
More detailed instructions and walkthroughs are provided at https://www.stardustxr.org
|
|
|
|
The [Terra Repository](https://terra.fyralabs.com/) is required, and comes pre-installed with [Ultramarine Linux](https://ultramarine-linux.org/). Other Fedora Editions and derivatives can directly install terra-release:
|
|
|
|
```bash
|
|
sudo dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
|
|
```
|
|
|
|
For a full installation of the Stardust XR server *and* a selected group of clients, run:
|
|
|
|
```bash
|
|
sudo dnf group install stardust-xr
|
|
```
|
|
|
|
## Manual Build
|
|
We've provided a manual installation script [here](https://github.com/cyberneticmelon/usefulscripts/blob/main/stardustxr_setup.sh) that clones and builds the Stardust XR server along with a number of other clients from their respective repositories, and provides a startup script for automatically launching some clients.
|
|
|
|
After cloning the repository
|
|
```bash
|
|
cargo build --release # this is needed to skip validation layers
|
|
```
|
|
|
|
## Usage
|
|
> [!NOTE]
|
|
> For help with setting up an XR headset on linux, visit https://stardustxr.org/docs/get-started/setup-openxr
|
|
|
|
|
|
The **Stardust XR Server** is a server that runs clients, so without any running, you will see a black screen. If you only have the server installed, we recommend also cloning and building the following clients to start: [Flatland](https://github.com/StardustXR/flatland), which allows normal 2D apps to run in Stardust, [Protostar](https://github.com/StardustXR/protostar), which contains Hexagon Launcher, an app launcher menu, and [Black Hole](https://github.com/StardustXR/black-hole) to quickly tuck away your objects and apps (kind of like desktop peek on Windows).
|
|
|
|
First, try running `cargo run -- -f` in a terminal window to check out flatscreen mode, (or `stardust-xr-server -f` / `stardust-xr-server_dev -f` if you installed via dnf or the manual installation script, respectively, as they provide symlinks.)
|
|
|
|
If there aren't already any clients running, you'll need to manually launch them by either navigating to their repositories and running `cargo run`, or running them via their names if you installed via dnf or the manual installation script, such as `flatland`, `hexagon_launcher`, etc.
|
|
|
|
> [!IMPORTANT]
|
|
> [Flatland](https://github.com/StardustXR/flatland) must be running for 2D apps to launch.
|
|
|
|
### Startup Script
|
|
A startup script can be created at `~/.config/stardust/startup` that will launch specified settings and clients/applications, an example of which is shown [here](https://github.com/cyberneticmelon/usefulscripts/blob/main/startup). If you used the [installation script](https://github.com/cyberneticmelon/usefulscripts/blob/main/stardustxr_setup.sh), one will have already been made for you. This allows wide flexibility of what clients to launch upon startup (and, for example, *where*, using the [Gravity](https://github.com/StardustXR/gravity) client to specify X Y and Z co-ordinates).
|
|
|
|
### Flatscreen Navigation
|
|
A video guide showcasing flatscreen controls is available [here](https://www.youtube.com/watch?v=JCYecSlKlDI)
|
|
|
|
To move around, hold down `Shift + W A S D`, with `Q` for moving down and `E` for moving up.
|
|
|
|
|
|
To look around, hold down `Shift + Right` Click while moving the mouse.
|
|
|
|
|
|
To drag applications out of the app launcher, hold down `Shift + ~`
|
|
|
|
|
|
### XR Navigation
|
|
A video guide showcasing XR controls is available [here](https://www.youtube.com/watch?v=RbxFq6JjliA)
|
|
|
|
**Quest 3 Hand tracking**:
|
|
Pinch to drag and drop, grasp with full hand for grabbing, point and click with pointer finger to click or pinch from a distance
|
|
|
|
|
|
|
|
**Quest 3 Controller**:
|
|
Grab with the grip buttons, click by touching the tip of the cones or by using the trigger from a distance
|
|
|
|
|