Updated documentation for easier onboarding of developers and users #19
14
docs/01-get-started/01-What-is-Stardust.md
Normal file
14
docs/01-get-started/01-What-is-Stardust.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
|
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# What is Stardust XR?
|
||||
[](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).
|
||||
@@ -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
62
docs/01-get-started/02-Quickstart.md
Normal file
@@ -0,0 +1,62 @@
|
||||
---
|
||||
```suggestion
The quickest way to get started with Stardust XR, is to try out <span style={{ color: 'yellow' }}>Telescope</span>, this works with the device you already have, or a headset. It comes with the **Stardust XR server**, an app launcher called **Hexagon Launcher** and some helpful apps like **Flatland** to use your 2D apps inside Stardust, and **Black Hole** to quickly tuck away your objects and apps (kind of like desktop peek on Windows.)
```
```suggestion
Fedora and derivatives (except Enterprise Linux)
```
```suggestion
You will need the [Terra repository](https://terra.fyralabs.com/), unless you have [Ultramarine Linux](https://ultramarine-linux.org) or [Bazzite](https://bazzite.gg). You can install it using this command:
```
```suggestion
Then, install Telescope using:
```
```suggestion
On Arch Linux, Stardust XR is available in the Arch Linux User Repository [AUR](https://aur.archlinux.org/packages/stardust-xr-telescope). We suggest using an AUR helper, like Paru:
```
```suggestion
On NixOS use the [Nix package manager](https://nixos.org/download/#nix-install-linux), make sure [flakes are enabled](https://nixos.wiki/wiki/flakes).
```
```suggestion
# After Installation
```
```suggestion
# Quick Start Guide
```
```suggestion
From here, just run `telescope -f` for flatscreen mode in your terminal!
```
```suggestion
You will see a floating hexagon with the Stardust XR logo in the center, this is Hexagon Launcher.
```
```suggestion
To look around, hold down ***Shift*** and ***Right Click*** while moving the mouse.
```
```suggestion
To move around, hold down ***Shift*** and ***W A S D***, with ***Q*** for moving down and ***E*** for moving up.
```
```suggestion
If you click on the hexagon, the launcher will open. Try dragging one of the apps with the ***Mouse 5*** (Back) button. The small minus sign is Black Hole, if you click it, it will grab any open window and store it away. Click it again and they will return to their original location.
```
```suggestion
If you are already using OpenXR within Linux, running `telescope` while OpenXR is running should launch Stardust on your headset. If not, check further instructions for setting up OpenXR.
```
```suggestion
The quickest way to get started with Stardust XR is to try out <span style={{ color: 'yellow' }}>Telescope</span>, this works with the device you already have, or a headset. It comes with the **Stardust XR server**, an app launcher called **Hexagon Launcher**, and some helpful apps like **Flatland** to use your 2D apps inside Stardust, and **Black Hole** to quickly tuck away your objects and apps (kind of like desktop peek on Windows).
```
```suggestion
You will need the [Terra repository](https://terra.fyralabs.com/), unless you have [Ultramarine Linux](https://ultramarine-linux.org) or [Bazzite](https://bazzite.gg).
```
|
||||
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>
|
||||
|
Add how to install on immutable versions of Fedora and its derivatives. Here is what the terra docs say (make non-immutable on top though, then add back the part I removed in the previous line to encompass both ways to install): Fedora Atomic Editions On Immutable editions of Fedora, run the following command: curl -fsSL https://github.com/terrapkg/subatomic-repos/raw/main/terra.repo | pkexec tee /etc/yum.repos.d/terra.repo Other Fedora Editions Directly install terra-release: sudo dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release Add how to install on immutable versions of Fedora and its derivatives.
Here is what the terra docs say (make non-immutable on top though, then add back the part I removed in the previous line to encompass both ways to install):
Fedora Atomic Editions
On Immutable editions of Fedora, run the following command:
curl -fsSL https://github.com/terrapkg/subatomic-repos/raw/main/terra.repo | pkexec tee /etc/yum.repos.d/terra.repo
sudo rpm-ostree install terra-release
Other Fedora Editions
Directly install terra-release:
sudo dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
|
||||
<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.
|
||||
|
rm one of the empty lines rm one of the empty lines
|
||||
|
||||
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.
|
||||
@@ -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)
|
||||
@@ -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:
|
||||
|
||||
|
||||
Non-exhaustive list of clients:
|
||||
- [**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): 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
88
docs/01-get-started/03-setup-openxr.md
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
```suggestion
This guide will help you set up your VR or AR headset for use with Stardust. Although support for many headsets on Linux is still under active development, there are a number of good options available. If you already have OpenXR set up on your Linux distribution, head to the [Full Installation](manual) page to get Stardust XR installed.
```
```suggestion
If you want to try Stardust in a window on your existing device you can skip this step and checkout the [Quick Start Guide](Quickstart).
```
```suggestion
We highly recommend using [Envision](https://lvra.gitlab.io/docs/fossvr/envision/), an easy to use GUI for utilizing [Monado](https://monado.dev/) which is what you likely use if you have a wired headset. Envision also comes with [WiVRn](https://github.com/WiVRn/WiVRn) support for connecting to headsets like the Meta Quest wirelessly.
```
```suggestion
Check the [hardware table](https://lvra.gitlab.io/docs/hardware/) (for Monado/WiVRn support) to ensure your hardware and headset are compatible. If you're using a Nvidia card, you'll need to install [proprietary drivers]((https://rpmfusion.org/Howto/NVIDIA). If you're using a modern Nvidia card on Fedora (with RPMFusion) or Ultramarine, this command will install the driver:
```
```suggestion
AMD graphic cards do not require additional drivers.
```
```suggestion
Fedora and derivatives (except Enterprise Linux)
```
```suggestion
You will need the [Terra repository](https://terra.fyralabs.com/), unless you have [Ultramarine Linux](https://ultramarine-linux.org) or [Bazzite](https://bazzite.gg). You can install it using this command:
```
```suggestion
Then, install Envision using:
```
```suggestion
For Arch Linux, Envision is available via the [AUR](https://aur.archlinux.org/packages/envision-xr-git). We suggest using an AUR helper, like Paru:
```
```suggestion
On NixOS, 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.
```
```suggestion
You can also download the [Envision AppImage](https://gitlab.com/gabmus/envision/-/pipelines?ref=main&status=success). Once downloaded, unzip the archive, you should find a file named Envision-x86_64.AppImage. You can do this from the properties menu in your file manager, or run `chmod +x Envision-x86_64.AppImage` in your terminal.
```
```suggestion
Then double click the file to run it.
```
```suggestion
When you launch Envision, you will have to build a profile for your headset, 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.
```
```suggestion
Once you have one of these options installed, a quick way to test on the headset is by running `xrgears`. [xrgears](https://gitlab.freedesktop.org/monado/demos/xrgears) is a demo that comes with Monado.
```
```suggestion
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)
```
```suggestion
If you'd like to use SteamVR, head 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 poor support.
```
```suggestion
If you want to try Stardust in a window on your existing device you can skip this step and checkout the [Quick Start Guide](Quickstart).
```
```suggestion
Check the [hardware table](https://lvra.gitlab.io/docs/hardware/) (for Monado/WiVRn support) to ensure your hardware and headset are compatible. If you're using an Nvidia card, you'll need to install [proprietary drivers]((https://rpmfusion.org/Howto/NVIDIA). If you're using a modern Nvidia card on Fedora (with RPMFusion) or Ultramarine, this command will install the driver:
```
```suggestion
Check the [hardware table](https://lvra.gitlab.io/docs/hardware/) (for Monado/WiVRn support) to ensure your hardware and headset are compatible. If you're using a Nvidia card, you'll need to install [proprietary drivers]((https://rpmfusion.org/Howto/NVIDIA). If you're using a modern Nvidia card on Fedora, with the RPMFusion repository, this command will install the driver:
```
Right, in discussion with Nova about this Telescope is a little redundant with the full installation, as the startup script essentially launches the same things if you set it up that way. I believe Nova's intention with telescope is a bit of a bundled demo. I'm going to be looking into making a submodule repo and make all of these installs more organized. Right, in discussion with Nova about this Telescope is a little redundant with the full installation, as the startup script essentially launches the same things if you set it up that way. I believe Nova's intention with telescope is a bit of a bundled demo. I'm going to be looking into making a submodule repo and make all of these installs more organized.
|
||||
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.
|
||||
|
||||
|
rm one empty line rm one empty line
|
||||
|
||||
:::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
|
||||
|
||||
|
||||
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:
|
||||
```
|
||||
```suggestion
sudo dnf install akmod-nvidia
sudo akmods
# Wait for this to finish before rebooting, this may take up to 15 minutes
```
|
||||
sudo dnf install akmod-nvidia
|
||||
```
|
||||
AMD graphic cards currently do not require drivers.
|
||||
|
Add a note about secure boot, this is often a papercut Add a note about secure boot, this is often a papercut
https://wiki.ultramarine-linux.org/en/setup/post-advanced/#set-up-secure-boot
|
||||
<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`
|
||||
|
||||
|
||||
|
||||
|
rm one empty line rm one empty line
|
||||
Double click the AppImage file to run it.
|
||||
|
||||
|
||||
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.
|
||||
|
rm two empty lines rm two empty lines
|
||||
|
||||
|
||||
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
83
docs/01-get-started/04-manual.md
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
```suggestion
Unlike [Telescope](Quickstart) that launches the Stardust XR server and a small selection of clients, the typical way to interact with Stardust is to first run the server, which only provides a void by default, as there are no applications or clients within it. You can then launch any combination of the clients listed below, as they are all considered separate items but can run concurrently inside Stardust.
```
```suggestion
Fedora and derivatives (except Enterprise Linux)
```
```suggestion
You will need the [Terra repository](https://terra.fyralabs.com/), unless you have [Ultramarine Linux](https://ultramarine-linux.org) or [Bazzite](https://bazzite.gg). You can install it using this command:
```
```suggestion
Then, run this command to install the Stardust XR group:
```
```suggestion
sudo dnf group install stardust-xr
```
```suggestion
From there, you can launch the server with `stardust-xr-server`, then in another terminal window or tab, run any other clients you need. We recommend `flatland` and `hexagon-launcher`.
```
```suggestion
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
```
```suggestion
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 server!
```
```suggestion
Make sure to check the list of prerequisites. Run `cargo build` and `cargo run` in the cloned repo to start the server. As stated above, the Stardust server will simply load in with a black void until clients are loaded in. This behaviour can currently be modified by creating a `startup` file inside 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)
```
```suggestion
Clone the [Stardust XR Server](https://github.com/StardustXR/server) `https://github.com/StardustXR/server`
```
|
||||
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
71
docs/01-get-started/05-quest-3-setup.md
Normal file
@@ -0,0 +1,71 @@
|
||||
---
|
||||
```suggestion
Do you have a Meta Quest and would like to try Stardust 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/). We suggest Plasma Edition due to VRR and HDR support. Once you have it installed, you will mainly be using the terminal to install what you need. Linked below is a YouTube walkthrough:
```
```suggestion
The setup video is done with a Meta Quest 3, and with [Ultramarine](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.
```
```suggestion
AMD Graphics cards do not require additional drivers, but Nvidia graphics cards will need to install drivers [provided by RPMFusion](https://rpmfusion.org/Howto/NVIDIA), which can be installed with:
```
Sometimes the guide says in, sometimes the guide says install. Should say install everywhere to be consistent. Sometimes the guide says in, sometimes the guide says install. Should say install everywhere to be consistent.
|
||||
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:
|
||||
[](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
|
||||
```
|
||||
|
rm one empty line rm one empty line
|
||||
# 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!
|
||||
Reference in New Issue
Block a user
Remove this because we already establish these points in the previous paragraph
You should get a contributor guide kinda like what we have on UM, see: https://wiki.ultramarine-linux.org/en/contributing/contributorguide/
Not sure why
linuxwas on there?think including from implies that there's stardust exclusive 2d apps (which i don't believe there are
mayb typo
at least hyphenate
I don't believe there are at the moment but there certainly can and probably will be
rm one of these empty lines