StardustXR/website
1
0
Fork 0
Code Issues 3 Pull Requests 4 Actions Packages Projects Releases Wiki Activity

Website updated with better documentation and guides

Browse Source
This commit is contained in:
Cyberneticmelon
2025-03-06 13:08:10 -05:00
parent b5d1c679f4
commit 596a580029
8 changed files with 318 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/01-get-started/01-What-is-Stardust.md Normal file
View File

@@ -0,0 +1,14 @@
---
sidebar_position: 1
---
# What is Stardust XR?
[![Stardust XR Demo Reel](/img/docs/sizzlethumb.png)](https://www.youtube.com/watch?v=v2WblwbaLaA)
Stardust XR is an XR [display server](https://itsfoss.com/display-server/) for Linux-based systems. It is functionally however, much more like a 3D environment, with applications ranging from simple 2D floating windows of your normal Linux programs, up to 3D applications that wouldn't otherwise be feasable outside of an XR environment. The design philosophy behind Stardust is what truly sets it apart, with user interface functions that not only work exclusively in an XR environment, but ones that push the user to understand the underlying connections in a way that can't be replicated with a keyboard and mouse.
Though Stardust XR isn't an operating system, because the different clients are all treated as independent objects, it is a truly unique experience to be able to place applications, both 2D and 3D, wherever you want in the area you are working in, whether that's at your desktop or an entire room
If you'd like to quickly try out Stardust XR on your desktop without the need to setup a headset, head to the [Quick Start](Quickstart) guide. If you need to set up your VR headset within Linux, let's [Setup OpenXR Runtime](setup-openxr). If you already have your heatset setup, head to the [Full Stardust Installation](manual) page. If you've never used Linux before (or even if you have), and you have a Meta Quest device, we've created a [full walkthrough to get you started playing with Stardust](quest-3-setup)!
Stardust XR is acitvely looking for help with development to expand the project. You can also [become a sponsor.](https://github.com/sponsors/technobaboo).

37
docs/01-get-started/01-setup-openxr.md
View File

@@ -1,37 +0,0 @@
---
sidebar_position: 1
---
# Setup OpenXR Runtime
:::info
if you want to test stardust in flatscreen mode (in a window) without a headset or other OpenXR device, you can skip this step and start with [trying out telescope](bundled).
:::
Check the [hardware table](https://lvra.gitlab.io/docs/hardware/) to ensure your hardware and headset are compatible:
## SteamVR
You will likely want to use [Monado](#monado) instead, but if you need to the instructions are available.
:::warning
If you are on NixOS please consult https://lvra.gitlab.io/docs/distros/nixos/ before installing SteamVR.
:::
https://lvra.gitlab.io/docs/steamvr/ is a good starting point, but be aware that the stardust server cannot run as an overlay on top of other games due to SteamVR not implementing the OpenXR Overlay extension.
## Monado
If you've got a wired headset, this is generally the way to go.
### NixOS
It's generally easiest to follow the instructions at https://lvra.gitlab.io/docs/distros/nixos/ to install properly to the system.
### Other distros
[Envision](https://lvra.gitlab.io/docs/fossvr/envision/) is the XR launcher (like a minecraft launcher) of choice for open source XR and is overall better in practice than SteamVR. If you are a Fedora user, Envision is packaged, but it's reccomended to get it from the [Terra repository](https://terra.fyralabs.com/). Other distros will need to build from source.
# Test OpenXR Runtime
Try running [XRGears](https://gitlab.freedesktop.org/monado/demos/xrgears) and see if it works, you can get it from the system's package manager often.

62
docs/01-get-started/02-Quickstart.md Normal file
View File

@@ -0,0 +1,62 @@
---
sidebar_position: 2
---
# QuickStart Guide
The quickest way to test Stardust XR, even if you don't have a VR setup, is to try out <span style={{ color: 'yellow' }}>Telescope</span>, a bundled Stardust setup that runs the **Stardust XR server**, an app launcher called **Hexagon Launcher** with some pre-installed apps to try, **Flatland** that renders 2D Linux windows in XR, and **Black Hole**, a little bag of holding that can suck up all the objects & windows in it's radius (essentially a 3D version of minimizing all windows to peek at the desktop!)
<h1>
<img
src="/img/docs/Fedora_logo.svg"
alt="Fedora Logo"
style={{ verticalAlign: 'middle', height: '1em', marginRight: '0.5em' }}
/>
<img
src="/img/docs/ultramarine-logo.svg"
alt="Ultramarine Logo"
style={{ verticalAlign: 'middle', height: '1em', marginRight: '0.5em' }}
/>
Fedora/Ultramarine Linux
</h1>
:::info
You will need the [Terra repository](https://terra.fyralabs.com/), unless you have [Ultramarine Linux](https://ultramarine-linux.org/download/) which comes pre-installed:
```
sudo dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
```
:::
In your terminal, run:
```
sudo dnf install telescope
```
<h1>
<img src="/img/docs/arch.png" alt="Logo" style={{ verticalAlign: 'middle', height: '1em', marginRight: '0.5em' }} />
Arch Linux
</h1>
For Arch Linux, Stardust XR is available via the Arch Linux User Repository [AUR](https://aur.archlinux.org/packages/stardust-xr-telescope)
```
paru -S stardust-xr-telescope
```
<h1>
<img src="/img/docs/nixos.svg" alt="Logo" style={{ verticalAlign: 'middle', height: '1em', marginRight: '0.5em' }} />
NixOS
</h1>
For NixOS use the [nix package manager](https://nixos.org/download/#nix-install-linux), make sure [flakes are enabled](https://nixos.wiki/wiki/flakes).
```
nix run github:StardustXR/telescope
```
# After installation:
From here, just run `telescope -f` for flatscreen mode in your terminal of choice!
You will see a floating hexagon with the Stardust XR logo within it, which is the Hexagon Launcher.
To look around, hold down ***Shift*** and hold down ***Right Click***
To move around, hold down ***Shift*** and ***W A S D***, with ***Q*** for moving down and ***E*** for moving up
If you click on the hexagon, the launcher will open up. Try dragging out one of the apps with the ***Mouse 5*** (Back) button. The small minus sign is Black Hole, if you click on it, it will grab any open window and store it away. Click it again and they will return to their original location.
If you are already using OpenXR within Linux, launching `telescope` while it's running should launch it within your headset. If not, check further instructions for setting up OpenXR, or the other installation guides.

54
docs/01-get-started/02-bundled.md
View File

@@ -1,54 +0,0 @@
---
sidebar_position: 2
---
# Bundled setup
Telescope is a bundled Stardust setup that lets you 1-click run all the essentials for testing a setup out on an existing 2D computer.
## Nix
### Install Nix
For easy development and distribution this project uses the [nix package manager](https://nix.dev/).<br/>
This allows to ensure all dependency requirements are met.
If you do not have nix installed follow the instructions at https://nixos.org/download/#nix-install-linux.
:::warning
Make sure to have [flakes enabled](https://nixos.wiki/wiki/flakes).
:::
### Run Telescope
Because telescope itself is a nix flake, you simply have to run
Intel/AMD/NVK graphics:
```sh
nix run github:StardustXR/telescope
```
~~Proprietary NVIDIA graphics:~~ is broken :/
```sh
NIXPKGS_ALLOW_UNFREE=1 nix run --impure github:StardustXR/telescope#telescopeNvidia
```
## Fedora/Ultramarine
You can install Telescope, and all other core Stardust tools, through the [Terra repository](https://terra.fyralabs.com/). This repository is pre-installed on Ultramarine, manual instructions can be found on their website.
To just install Telescope:
```
dnf install telescope
```
To install all Stardust XR packages (Ultramarine 40 and later, Fedora 41 and later):
```
dnf group install stardust-xr
```
From here, just run `telescope` in your terminal of choice.
## Other
An AppImage generated from the nix flake is currently WIP. Please check back later or do a [manual build.](manual)

26
docs/01-get-started/03-manual.md
View File

@@ -1,26 +0,0 @@
---
sidebar_position: 3
---
# Manual build/installation
Make sure all repos are cloned on the same branch (e.g. all main or all dev branch) to ensure stardust protocol compatibility.
## Server
Run and maybe install the server from https://github.com/StardustXR/server.
Follow the README.
## Clients
After the server is running, you'll need to run some clients. Here's a demo showing some off:
![A showcase of some different clients](/img/docs/clients/demo_01.mp4)
Non-exhaustive list of clients:
- [**flatland**](https://github.com/StardustXR/flatland): 3D panel UI (like window manager) for intercting with all your 2D apps
![A flat panel containing the prism launcher](/img/docs/clients/flatland.png)
- [**protostar**](https://github.com/StardustXR/protostar): App launcher library and examples including futuristic hexagon launcher
- [**black hole**](https://github.com/StardustXR/black-hole): Universal minimization of Stardust objects
- [**gravity**](https://github.com/StardustXR/gravity): Launch programs with a certain offset in 3D space
- [**magnetar**](https://github.com/StardustXR/magnetar): Example workspaces client
- [**atmosphere**](https://github.com/StardustXR/atmosphere): 3D environment with natural momentum-based movement
- [**comet**](https://github.com/StardustXR/comet): Annotate in 3D wherever you want amongst your other apps!

88
docs/01-get-started/03-setup-openxr.md Normal file
View File

@@ -0,0 +1,88 @@
---
sidebar_position: 3
---
# Setup OpenXR Runtime
If you have a XR Headset and you'd like to use it with Stardust XR on Linux, the following are instructions on getting it up and running within a linux environment. Although XR support in Linux is still under active development, there are a number of good options available. If you already have XR set up on your Linux distribution, head to the [Full Installation](manual) page to get Stardust XR installed.
:::info
If you want to test stardust in flatscreen mode in a window on your desktop without a headset or other OpenXR device, you can skip this step and start with [trying out telescope](Quickstart).
:::
# Envision
:::note
![Envision](/img/docs/Envision_Monado.png)
We highly recommend using [Envision](https://lvra.gitlab.io/docs/fossvr/envision/), as it is an easy to use GUI for utilizing [Monado](https://monado.dev/) (an Open-Source implementation of OpenXR for Linux) which is what you will most likely be using if you have a wired headset, and Envision also comes with [WiVRn](https://github.com/WiVRn/WiVRn) for connecting to headsets like the Meta Quest wirelessly.
:::
Check the [hardware table](https://lvra.gitlab.io/docs/hardware/) (for Monado/WiVRn support) to ensure your hardware and headset are compatible. It is very likely you will need [Nvidia drivers](https://rpmfusion.org/Howto/NVIDIA) if that's what you are using. Check the link for the which model graphics card may require different drivers, but the most likely command you will need to run if you have a modern card is:
```
sudo dnf install akmod-nvidia
```
AMD graphic cards currently do not require drivers.
<h3>
<img
src="/img/docs/Fedora_logo.svg"
alt="Fedora Logo"
style={{ verticalAlign: 'middle', height: '1em', marginRight: '0.5em' }}
/>
<img
src="/img/docs/ultramarine-logo.svg"
alt="Ultramarine Logo"
style={{ verticalAlign: 'middle', height: '1em', marginRight: '0.5em' }}
/>
Fedora/Ultramarine Linux
</h3>
:::info
You will need the [Terra repository](https://terra.fyralabs.com/), unless you have [Ultramarine Linux](https://ultramarine-linux.org/download/) which comes pre-installed:
```
sudo dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
```
:::
In your terminal, run:
```
sudo dnf install envision
```
<h3>
<img src="/img/docs/arch.png" alt="Logo" style={{ verticalAlign: 'middle', height: '1em', marginRight: '0.5em' }} />
Arch Linux
</h3>
For Arch Linux, Envision is available via the [AUR](https://aur.archlinux.org/packages/envision-xr-git)
```
paru -S envision-xr-git
```
<h3>
<img src="/img/docs/nixos.svg" alt="Logo" style={{ verticalAlign: 'middle', height: '1em', marginRight: '0.5em' }} />
NixOS
</h3>
It's generally easiest to follow the instructions at https://lvra.gitlab.io/docs/distros/nixos/ as Envision is currently unstable on NixOS and troubleshooting SteamVR can be tricky.
### Other options for installation
You can also download the [Envision AppImage](https://gitlab.com/gabmus/envision/-/pipelines?ref=main&status=success) directly. Once downloaded, unzip the archive and you should find a file named Envision-x86_64.AppImage. Make it executable either from your file manager with right click > properties > "executable as program", or under permissions enable "is executable" (this depends on your file manager) OR, from the terminal: `chmod +x Envision-x86_64.AppImage`
Double click the AppImage file to run it.
![Envision App Image](/img/docs/envisionappimage.png)
When you launch Envision, you will have to build a profile depending on what headset and setup you are using, check the [Envision website](https://lvra.gitlab.io/docs/fossvr/envision/) for instructions specific to what you have. You can take a look at [this section] of our Meta Quest setup video for an example using WiVRn.
![Envision Build Profile](/img/docs/envisionbuildprofile.png)
Once you have one of these options installed, a quick way to test it within the headset is by running the command `xrgears` and see if it works. [xrgears](https://gitlab.freedesktop.org/monado/demos/xrgears) is a demo that comes with Monado.
:::tip
If you run into any problems during installation, the [Meta Quest Walkthrough](quest-3-setup) may contain information helpful in regards to dependencies, firewalls and drivers.
:::
# ALVR
Another option is ALVR, you can check the github repository for more information [https://github.com/alvr-org/ALVR](https://github.com/alvr-org/ALVR)
# SteamVR
If you'd like to use SteamVR, head on over to [https://lvra.gitlab.io/docs/steamvr/](https://lvra.gitlab.io/docs/steamvr/), although it is not the recommended way to use VR within Linux due to current poor support.

83
docs/01-get-started/04-manual.md Normal file
View File

@@ -0,0 +1,83 @@
---
sidebar_position: 4
---
# Full Installation
Unlike bundled [Telescope](Quickstart) that launches the Stardust XR server and a small selection of clients, the typical way to interact with Stardust XR currently is to first run the server, which will only give you a black void, as there are no applications or clients running within it. You can then launch any combination of the clients listed below, as they are all considered separate items but can run concurrently within the Stardust XR server.
<h3>
<img
src="/img/docs/Fedora_logo.svg"
alt="Fedora Logo"
style={{ verticalAlign: 'middle', height: '1em', marginRight: '0.5em' }}
/>
<img
src="/img/docs/ultramarine-logo.svg"
alt="Ultramarine Logo"
style={{ verticalAlign: 'middle', height: '1em', marginRight: '0.5em' }}
/>
Fedora/Ultramarine Linux
</h3>
:::info
You will need the [Terra repository](https://terra.fyralabs.com/), unless you have [Ultramarine Linux](https://ultramarine-linux.org/download/) which comes pre-installed:
```
sudo dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
```
:::
To do a full installation of Stardust XR on Fedora/Ultramarine run the following command:
```
dnf group install stardust-xr
```
<h3>
<img src="/img/docs/arch.png" alt="Logo" style={{ verticalAlign: 'middle', height: '1em', marginRight: '0.5em' }} />
Arch Linux
</h3>
```
paru -s stardust-xr-telescope
paru -s stardust-xr-armillary
paru -s stardust-xr-atmosphere
paru -s stardust-xr-black-hole
paru -s stardust-xr-comet
paru -s stardust-xr-flatland
paru -s stardust-xr-gravity
paru -s stardust-xr-magnetar
paru -s stardust-xr-non-spatial-input
paru -s stardust-xr-protostar
paru -s stardust-xr-server
```
From there, you can launch the server with `stardust-xr-server`, and then in some other terminal windows, launch some clients. Recommended clients to start would be `flatland` & `hexagon-launcher`
# Manual Build
:::caution
Make sure all of the repositories that are cloned are on the same branch (e.g. all main or all dev branch) to ensure stardust protocol compatibility
:::
### Server
Clone the [Stardust XR server](https://github.com/StardustXR/server) `https://github.com/StardustXR/server`
Make sure to check the list of prerequisites. `Cargo build` and `Cargo run` within the cloned repo to start the server. As stated above, the Stardust XR server itself will simply load in with a black void until clients are loaded in. This behaviour can currently be modified by creating a `startup` file within the folder `~/.config/stardust/` to automate the loading in of clients, an example of which is shown [here](https://youtu.be/c6RyEYDz2iw?si=pL1zffNVsWocZHrc&t=788), and an example of is linked [here](https://github.com/cyberneticmelon/usefulscripts/blob/main/startup)
### Clients
After the server is running, you'll need to run some clients. Clone any of these, `cargo build` & then `cargo run` after the server is already running, and they will load into the Stardust XR server!
Non-exhaustive list of clients:
- [**flatland**](https://github.com/StardustXR/flatland): `https://github.com/StardustXR/flatland`
3D panel UI (like window manager) for intercting with all your 2D apps
- [**protostar**](https://github.com/StardustXR/protostar): `https://github.com/StardustXR/protostar`
App launcher library and examples including futuristic Hexagon Launcher
- [**black hole**](https://github.com/StardustXR/black-hole): `https://github.com/StardustXR/black-hole`
Universal minimization of Stardust objects
- [**gravity**](https://github.com/StardustXR/gravity): `https://github.com/StardustXR/gravity`
Launch programs with a certain offset in 3D space
- [**magnetar**](https://github.com/StardustXR/magnetar): `https://github.com/StardustXR/magnetar`
Example workspaces client
- [**atmosphere**](https://github.com/StardustXR/atmosphere): `https://github.com/StardustXR/atmosphere`
3D environment with natural momentum-based movement
- [**comet**](https://github.com/StardustXR/comet): `https://github.com/StardustXR/cometAnnotate`
Write in 3D wherever you want amongst your other apps!
### Installation Script
If you have all the correct dependencies, we've created a [script](https://github.com/cyberneticmelon/usefulscripts/blob/main/stardustxr_setup.sh) that will automatically `git clone` all of the necessary repositories, `cargo build` all of them, and give them a symlinks for running the server and clients from the command line. It also creates a [config](https://github.com/cyberneticmelon/usefulscripts/blob/main/startup) file that will by default install the default `atmosphere` background. Run the script with flag `-nobg` if you don't want that.

71
docs/01-get-started/05-quest-3-setup.md Normal file
View File

@@ -0,0 +1,71 @@
---
sidebar_position: 5
---
# Meta Quest Walkthrough
Do you have a Meta Quest and would like to try Stardust XR for yourself? Even if you don't have any experience with Linux, this full guide will get you started with Stardust! It is recommended that you install a version of Linux called [Ultramarine](https://ultramarine-linux.org/download/), any version will do, but the KDE version is very popular for its user interface and ease of use. Once you have it installed, you will mainly be using the terminal command line interface to install what you need. Linked below is a Youtube walkthrough:
[![Youtube Tutorial](/img/docs/youtubethumb.png)](https://www.youtube.com/watch?v=Rgj9-9UwA2g)
:::info
Applies to Quest, Quest 2, Quest 3, and Quest Pro. These instructions should work on all Fedora distributions, but you will need to download the [Terra repository](https://terra.fyralabs.com/):
```
sudo dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
```
The setup video is done with a Meta Quest 3, and with [Ultramarine Linux](https://ultramarine-linux.org/download/), a Fedora based distribution. Ultramarine comes with the Terra repository pre-installed. You can follow [these instructions](https://wiki.ultramarine-linux.org/en/setup/getting/) to install a version of Ultramarine.
:::
# Nvidia & AMD
AMD Graphics cards currently do not require drivers, but Nvidia graphics cards will need to install drivers [provided by RPM Fusion](https://rpmfusion.org/Howto/NVIDIA), which can be installed via:
```
sudo dnf in akmod-nvidia
```
# Envision
The next step is to install [Envision](https://lvra.gitlab.io/docs/fossvr/envision/). Envision is a GUI that makes it easier to connect and run the Quest 3 (among other headsets) with [Monado](https://monado.dev/), an open source OpenXR implementation, and [WiVRn](https://github.com/WiVRn/WiVRn), a wireless streaming implementation that also works with the Quest 3. Envision comes pre-packaged with WiVRn. Envision can be installed via:
```
sudo dnf in akmod-nvidia
```
# Vulkan Layers
If you have an Nvidia graphics card, it is possible that you will need to install [Vulkan Layers](https://gitlab.freedesktop.org/monado/utilities/vulkan-layers) for Monado, although this may not be necessary depending on the driver version:
```
sudo dnf install -y monado-vulkan-layers
```
Next, Launch Envision, and in the drop down menu on the bottom, select the **WiVRn profile** and click **Build Profile**. It'll give you a list of dependencies to install, so copy the command and run it. After they are installed, there's one extra dependency to add manually.
```
sudo dnf install libnotify-devel
```
:::note
Note that [Developer Mode](https://developers.meta.com/horizon/documentation/native/android/mobile-device-setup/) must be enabled on your Quest 3. The most streamlined way to do this is through the Meta Horizons app on [Android](https://play.google.com/store/apps/details?id=com.oculus.twilight&hl=en_US) or [iPhone](https://apps.apple.com/us/app/meta-horizon/id1366478176)
:::
# Installing WiVRn
Once that is complete, you're ready to click Build Profile within Envision. Once it's done building, you're ready to install WiVRn on the headset. Connect your headset to your computer via the Quest 3 Link cable or another compatable USB-C cable. Now that Developer Mode is enabled, you should see "Allow USB debugging", click *allow* within the headset.
With debugging enabled and the headset connected, click **Install WiVRn** within Envision to install the android apk onto the headset.
# Firewalls
Once it's installed, you'll need avahi-daemon running:
```
systemctl enable --now avahi-daemon
```
And it's possible that your firewall could prevent connection, so use the following commands to open up the ports required and reload the firewall:
```
sudo firewall-cmd --zone=public --add-port=5353/udp --permanent
sudo firewall-cmd --zone=public --add-port=9757/udp --permanent
sudo firewall-cmd --zone=public --add-port=9757/tcp --permanent
sudo firewall-cmd --reload
```
# Stardust XR
Now that we've set up the Quest 3 to be able to connect to your linux distribution via Envision/WiVRn, we can install Stardust XR!
```
sudo dnf group install stardust-xr
```
Once installed, you'll have to launch WiVRN within the headset. On the bottom right of the Quest 3 menu, go to Library > Unknown Sources, and you'll see the WiVRn app. Once you're loaded up, click the Start button at the top of Envision on your computer, and you'll be greeted with a PIN for firs time setup. Back in the Quest 3, tap Connect, and enter the PIN, and you should see "Connection ready, Start a VR application on Ultramarine"
For the quickest way to test Stardust XR, run the command
```
telescope
```
Which will launch Stardust XR along with the Hexagon App Launcher and some pre-loaded applications!