reorder: everythinggg

2024-08-22 05:26:51 -04:00
parent f04a3eabbc
commit d67dc8fc4d
14 changed files with 238 additions and 195 deletions
--- a/docs/01-get-started/01-setup-openxr.md
+++ b/docs/01-get-started/01-setup-openxr.md
@@ -0,0 +1,37 @@
+---
+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.
+
+# 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.
--- a/docs/01-get-started/02-bundled.md
+++ b/docs/01-get-started/02-bundled.md
@@ -0,0 +1,30 @@
+---
+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
+```sh
+nix run github:StardustXR/telescope
+```
+
+## Non-nix
+
+An AppImage generated from the nix flake is currently WIP. Please check back later or do a [manual build.](manual)
--- a/docs/01-get-started/03-manual.md
+++ b/docs/01-get-started/03-manual.md
@@ -0,0 +1,26 @@
+---
+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!
--- a/docs/01-get-started/_category_.json
+++ b/docs/01-get-started/_category_.json
@@ -0,0 +1,4 @@
+{
+	"label": "Get Started",
+	"position": 1
+}
--- a/docs/02-dive-deeper/01-brief-overview.md
+++ b/docs/02-dive-deeper/01-brief-overview.md
@@ -2,9 +2,9 @@
 sidebar_position: 1
 ---

-# Overview
+# Brief Overview

-Stardust XR _(formerly known as Stardust)_ is an XR [display server](https://itsfoss.com/display-server) designed for Linux-based systems<!-- (possibly most unix-based too, but untested)-->.<br/>
+Stardust XR is an XR [display server](https://itsfoss.com/display-server) designed for Linux-based systems<!-- (possibly most unix-based too, but untested)-->.<br/>
 Unlike traditional display servers that focus on 2D screens, Stardust XR introduces new conventions to utilize unbounded 3D space in virtual or real environments.

 ## Priorities
@@ -24,7 +24,64 @@ Unlike traditional display servers that focus on 2D screens, Stardust XR introdu

 ## Architecture

-![simplified architecture diagram](/img/docs/simplified-architecture.png)
+```mermaid
+graph LR
+    OpenXR
+
+    OpenXR -->|Frame Data| StereoKit
+    OpenXR -->|Input Data| StereoKit
+
+    subgraph Server[Stardust Server]
+    		StereoKit[StereoKit]
+        InternalSceneGraph[Internal Scenegraph]
+        WC1[Wayland Client 1]
+        DBusConnection[D-Bus Connection]
+
+        ClientSceneGraph -->|Drawable Objects| StereoKit
+        StereoKit -->|Controller, Hand & HMD Data| InternalSceneGraph
+        InternalSceneGraph -->|Panel Items| ClientSceneGraph
+        InternalSceneGraph -->|Controller, Hand & HMD Export| DBusConnection
+        WC1 -->|Panel Item| InternalSceneGraph
+        WC1 -->|Textures| StereoKit
+        StereoKit -->|EGL Context| WC1
+        ClientSceneGraph --> C1
+
+        subgraph C1[Stardust Client 1]
+        	ClientSceneGraph[Client Scenegraph]
+        end
+    end
+
+    StardustSocket[Stardust Socket]
+    SessionBus[D-Bus Session Bus]
+    WaylandSocket[Wayland Socket]
+
+    WC1 --> WaylandSocket
+    WaylandSocket --> WC1
+    DBusConnection --> SessionBus
+    C1 --> StardustSocket
+
+    subgraph StardustClient[Stardust Client 1]
+        Fusion
+        Molecules
+        UserCode[User Code]
+
+        Fusion --> Molecules
+        Fusion --> UserCode
+        Molecules --> UserCode
+
+        subgraph Fusion
+            libstardustxr[stardust-xr library]
+        end
+    end
+
+    StardustSocket --> libstardustxr
+    SessionBus -->|HMD Spatial Reference| Fusion
+
+
+    WaylandClient[Wayland Client]
+    WaylandSocket --> WaylandClient
+    WaylandClient --> WaylandSocket
+```

 ## Projects & Components

--- a/docs/02-getting-started/02-tech-overview.md
+++ b/docs/02-getting-started/02-tech-overview.md
--- a/docs/02-getting-started/04-making-clients.md
+++ b/docs/02-getting-started/04-making-clients.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 3
 ---

 # Making Clients
--- a/docs/02-dive-deeper/09-terminology.md
+++ b/docs/02-dive-deeper/09-terminology.md
--- a/docs/02-dive-deeper/_category_.json
+++ b/docs/02-dive-deeper/_category_.json
@@ -0,0 +1,4 @@
+{
+	"label": "Dive deeper",
+	"position": 2
+}
--- a/docs/02-getting-started/01-tutorial.md
+++ b/docs/02-getting-started/01-tutorial.md
@@ -1,86 +0,0 @@
---
-sidebar_position: 1
---
-
-# Tutorial
-
-## Setup OpenXR
-
-:::note
-if you have no headset or other OpenXR device, you can skip this step and start with [installing nix](#install-nix).
-:::
-
-### SteamVR
-
-#### Archlinux
-
-TODO
-
-#### NixOS
-
-TODO
-
-#### Others
-
-TODO: collect links for setup on different distrons
-
-### [Monado](https://monado.dev/)
-
-#### Archlinux
-
-TODO
-
-#### NixOS
-
-TODO
-
-#### Others
-
-TODO: collect links for setup on different distrons
-
-## 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.
-
-:::info
-Make sure to have [flakes enabled](https://nixos.wiki/wiki/flakes).
-:::
-
-You can install nix on all common linux systems:
-
-#### Archlinux
-
-```shell
-# install git and nix
-sudo pacman -Sy git nix
-# enable flakes
-echo 'experimental-features = nix-command flakes' | sudo tee -a /etc/nix/nix.conf
-# enable nix daemon service
-sudo systemctl enable nix-daemon.service
-# add the current user to nix-users group
-sudo usermod -aG nix-users $(id -un)
-# reboot to apply user and service changes
-sudo systemctl reboot
-```
-
-#### NixOS
-
-TODO
-
-#### Others
-
-TODO: collect links for setup on different distrons
-
-## Run Demo
-
-1. clone https://github.com/StardustXR/telescope
-2. make sure your OpenXR device works (if 2D mode is not used)
-3. run `nix run .`
-
-## Run wayland client
-
-```shell
-# run demo.mp4 video in a loop within Stardust
-WAYLAND_DISPLAY=wayland-0 DISPLAY= mpv Downloads/demo.mp4 --loop
-```
--- a/docs/02-getting-started/03-setup.md
+++ b/docs/02-getting-started/03-setup.md
@@ -1,17 +0,0 @@
---
-sidebar_position: 3
---
-
-# Setup
-
-First you need to install and run the server from https://github.com/StardustXR/server. Follow the README. If you have issues getting OpenXR to work, try running https://gitlab.freedesktop.org/monado/demos/xrgears first.
-
-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): A panel item UI (XR equivalent of a window manager) so you can interact with your apps using virtual touchscreens. To show Wayland apps, run them with the proper `WAYLAND_DISPLAY` environment variable, in the server's startup script, or use a stardust launcher such as gravity or protostar. Flatland works great in 3DoF or 6DoF with direct touch and pointer interaction.
-![A flat panel containing the prism launcher](/img/docs/clients/flatland.png)
- [Gravity](https://github.com/StardustXR/gravity): Command line tool to launch programs inside of stardust at a particular offset in space. This is nestable so you can run a script using gravity, and then gravity inside that script to make a whole composed setup out of thin air! It also ensures that everything launched through it will properly connect to the stardust server, such as wayland clients.
- [Protostar](https://github.com/StardustXR/protostar): Prototype app launcher library/examples. Grab app icons and drop them in space to launch apps where they're dropped.
- [Magnetar](https://github.com/StardustXR/magnetar): Workspaces in 3D. Any object inside the rings will move with them, so you can move a bunch of stuff out of the way temporarily when you don't need it.
--- a/docs/02-getting-started/_category_.json
+++ b/docs/02-getting-started/_category_.json
@@ -1,4 +0,0 @@
-{
-	"label": "Getting Started",
-	"position": 2
-}
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -1,22 +1,22 @@
-const lightCodeTheme = require('prism-react-renderer/themes/vsLight');
-const darkCodeTheme = require('prism-react-renderer/themes/vsDark');
+const lightCodeTheme = require("prism-react-renderer/themes/vsLight");
+const darkCodeTheme = require("prism-react-renderer/themes/vsDark");

 /** @type {import('@docusaurus/types').DocusaurusConfig} */
 module.exports = {
-	title: 'Stardust XR',
-	tagline: 'We Fight for the Users!',
-	url: 'https://stardustxr.org',
-	baseUrl: '/',
+	title: "Stardust XR",
+	tagline: "We Fight for the Users!",
+	url: "https://stardustxr.org",
+	baseUrl: "/",
 	trailingSlash: false,
-	onBrokenLinks: 'throw',
-	onBrokenMarkdownLinks: 'warn',
-	favicon: 'img/favicon.ico',
-	organizationName: 'StardustXR', // Usually your GitHub org/user name.
-	projectName: 'website', // Usually your repo name.
+	onBrokenLinks: "throw",
+	onBrokenMarkdownLinks: "warn",
+	favicon: "img/favicon.ico",
+	organizationName: "StardustXR", // Usually your GitHub org/user name.
+	projectName: "website", // Usually your repo name.
 	markdown: {
 		mermaid: true,
 	},
-	themes: ['@docusaurus/theme-mermaid'],
+	themes: ["@docusaurus/theme-mermaid"],
 	themeConfig: {
 		colorMode: {
 			defaultMode: "dark",
@@ -24,105 +24,99 @@ module.exports = {
 			respectPrefersColorScheme: false,
 		},
 		navbar: {
-			title: 'Stardust XR',
+			title: "Stardust XR",
 			logo: {
-				alt: 'Stardust XR logo, a yellow astroid with smaller white astroids around it',
-				src: 'img/icon.webp',
+				alt: "Stardust XR logo, a yellow astroid with smaller white astroids around it",
+				src: "img/icon.webp",
 			},
 			items: [
 				{
-					href: '/roadmap',
-					position: 'left',
-					label: 'Roadmap',
+					href: "/roadmap",
+					position: "left",
+					label: "Roadmap",
 				},
 				{
-					type: 'doc',
-					docId: 'overview',
-					position: 'left',
-					label: 'Docs',
+					href: "https://twitter.com/stardustxr",
+					label: "Twitter",
+					position: "right",
 				},
 				{
-					href: 'https://twitter.com/stardustxr',
-					label: 'Twitter',
-					position: 'right',
+					href: "https://discord.gg/A9w7fKE",
+					label: "Discord",
+					position: "right",
 				},
 				{
-					href: 'https://discord.gg/A9w7fKE',
-					label: 'Discord',
-					position: 'right',
+					href: "https://matrix.to/#/#stardustxr:matrix.org",
+					label: "Matrix",
+					position: "right",
 				},
 				{
-					href: 'https://matrix.to/#/#stardustxr:matrix.org',
-					label: 'Matrix',
-					position: 'right',
+					href: "https://github.com/StardustXR",
+					label: "GitHub",
+					position: "right",
 				},
 				{
-					href: 'https://github.com/StardustXR',
-					label: 'GitHub',
-					position: 'right',
-				},
-				{
-					href: 'https://github.com/sponsors/technobaboo',
-					label: 'Sponsor This',
-					position: 'right',
+					href: "https://github.com/sponsors/technobaboo",
+					label: "Sponsor This",
+					position: "right",
 				},
 			],
 		},
 		footer: {
-			style: 'dark',
+			style: "dark",
 			links: [
 				{
-					title: 'Docs',
+					title: "Docs",
 					items: [
 						{
-							label: 'Roadmap',
-							href: 'roadmap',
+							label: "Roadmap",
+							href: "roadmap",
 						},
 						{
-							label: 'Getting Started',
-							to: '/docs/getting-started/tutorial',
+							label: "Getting Started",
+							to: "/docs/get-started/setup-openxr",
 						},
 					],
 				},
 				{
-					title: 'Community',
+					title: "Community",
 					items: [
 						{
-							label: 'Discord',
-							href: 'https://discord.gg/A9w7fKE',
+							label: "Discord",
+							href: "https://discord.gg/A9w7fKE",
 						},
 						{
-							label: 'Matrix',
-							href: 'https://matrix.to/#/#stardustxr:matrix.org',
+							label: "Matrix",
+							href: "https://matrix.to/#/#stardustxr:matrix.org",
 						},
 						{
-							label: 'Twitter',
-							href: 'https://twitter.com/stardustxr',
+							label: "Twitter",
+							href: "https://twitter.com/stardustxr",
 						},
 						{
-							label: 'Stardust XR (GitHub)',
-							href: 'https://github.com/StardustXR',
+							label: "Stardust XR (GitHub)",
+							href: "https://github.com/StardustXR",
 						},
 						{
-							label: 'Sponsor This',
-							href: 'https://github.com/sponsors/technobaboo',
+							label: "Sponsor This",
+							href: "https://github.com/sponsors/technobaboo",
 						},
 					],
 				},
 				{
-					title: 'Code',
+					title: "Code",
 					items: [
 						{
-							label: 'Stardust XR (Server)',
-							href: 'https://github.com/StardustXR/stardust-xr-server',
+							label: "Stardust XR (Server)",
+							href: "https://github.com/StardustXR/stardust-xr-server",
 						},
 						{
-							label: 'stardust-xr (includes Fusion)',
-							href: 'https://github.com/StardustXR/stardust-xr',
+							label: "stardust-xr (includes Fusion)",
+							href: "https://github.com/StardustXR/stardust-xr",
 						},
 						{
-							label: 'Flatland',
-							href: 'https://github.com/StardustXR/flatland',
+							label: "Flatland",
+							href: "https://github.com/StardustXR/flatland",
 						},
 					],
 				},
@@ -136,16 +130,15 @@ module.exports = {
 	},
 	presets: [
 		[
-			'@docusaurus/preset-classic',
+			"@docusaurus/preset-classic",
 			{
 				docs: {
-					sidebarPath: require.resolve('./sidebars.js'),
+					sidebarPath: require.resolve("./sidebars.js"),
 					// Please change this to your repo.
-					editUrl:
-						'https://github.com/StardustXR/website/edit/main/',
+					editUrl: "https://github.com/StardustXR/website/edit/main/",
 				},
 				theme: {
-					customCss: require.resolve('./src/css/custom.css'),
+					customCss: require.resolve("./src/css/custom.css"),
 				},
 			},
 		],
--- a/src/pages/index.js
+++ b/src/pages/index.js
@@ -1,17 +1,17 @@
-import React from 'react';
-import clsx from 'clsx';
-import Layout from '@theme/Layout';
-import Link from '@docusaurus/Link';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import styles from './index.module.css';
-import HomepageFeatures from '../components/HomepageFeatures';
-import Carousel from '../components/Carousel';
-import 'react-responsive-carousel/lib/styles/carousel.min.css';
+import React from "react";
+import clsx from "clsx";
+import Layout from "@theme/Layout";
+import Link from "@docusaurus/Link";
+import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
+import styles from "./index.module.css";
+import HomepageFeatures from "../components/HomepageFeatures";
+import Carousel from "../components/Carousel";
+import "react-responsive-carousel/lib/styles/carousel.min.css";

 function HomepageHeader() {
-	const {siteConfig} = useDocusaurusContext();
+	const { siteConfig } = useDocusaurusContext();
 	return (
-		<header className={clsx('hero hero--primary', styles.heroBanner)}>
+		<header className={clsx("hero hero--primary", styles.heroBanner)}>
 			<div className="container">
 				<link rel="me" href="https://fosstodon.org/@stardustxr"></link>
 				<h1 className="hero__title">{siteConfig.title}</h1>
@@ -19,7 +19,8 @@ function HomepageHeader() {
 				<div className={styles.buttons}>
 					<Link
 						className="button button--secondary button--lg"
-						to="/docs/getting-started/tutorial">
+						to="/docs/get-started/setup-openxr"
+					>
 						Get Started
 					</Link>
 				</div>
@@ -29,11 +30,9 @@ function HomepageHeader() {
 }

 export default function Home() {
-	const {siteConfig} = useDocusaurusContext();
+	const { siteConfig } = useDocusaurusContext();
 	return (
-		<Layout
-			image="img/icon.gif"
-			description="XR Display Server">
+		<Layout image="img/icon.gif" description="XR Display Server">
 			<HomepageHeader />
 			<main>
 				<HomepageFeatures />