Merge branch 'main' of https://gitlab.com/lvra/lvra.gitlab.io

content/docs/fossvr/envision/_index.md

@@ -16,16 +16,14 @@ Envision is a graphical app that acts as an orchestrator to get a full [Monado](
 Envision attempts to construct a working runtime with both a native OpenXR and an OpenVR API, provided by [OpenComposite](/docs/fossvr/opencomposite/), for client aplications to utilize. Please note the OpenVR implementation is incomplete and contains only what's necessary to run most games for compatibility. If you plan to implement software, utilize the OpenXR API, specification [here](https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html).
 
 {{% hint danger %}}
-**Warning**
-
-Envision is still considered alpha-quality and highly experimental.
+We recommend **against** using Envision if your distro is NixOS. See [our NixOS page](/docs/distros/nixos/#envision) for more info.
 {{% /hint %}}
 
 You can download the latest AppImage snapshot from [GitLab Pipelines](https://gitlab.com/gabmus/envision/-/pipelines?ref=main&status=success).
 
 If you are on Arch, You can use the [AUR package](https://aur.archlinux.org/packages/envision-xr-git) `envision-xr-git`
 
-## Getting Started
+## Getting started
 
 Upon launching Envision, you will need to select a profile on the bottom of the left side bar.
 
@@ -40,7 +38,57 @@ Profiles that are available by default:
 
 Monado does not have a launcher app, and so after connecting your headset, you will likely see a solid color. This means you can now start your VR title.
 
-You may want to launch [WlxOverlay-S](/docs/fossvr/wlxoverlay-s/) first and use it to access your desktop and other VR titles. You can even start it automatically alongside the Monado session: just enter `wlx-overlay-s --openxr` into the "Autostart" field of your Envision profile.
+You may want to launch [WlxOverlay-S](/docs/fossvr/wlxoverlay-s/) first and use it to access your desktop and other VR titles. You can even start it automatically alongside the Monado/WiVRn session, by enabling it in the [Plugins](#plugin-system) menu.
+
+## Plugin system
+
+The plugin system for Envision allows you to launch anything (usually OpenXR overlays) alongside the Monado/WiVRn session.
+
+Open the Plugins window by clicking the kebab menu (three dots) at the top of the Envision window, and clicking "Plugins". Here, you can install overlays like [WlxOverlay-S](/docs/fossvr/wlxoverlay-s/) or [Stardust XR](/docs/fossvr/stardust/) (or a custom plugin — see below). After installing plugins and toggling them on, once you start a profile, the enabled plugins will start alongside it.
+
+Plugins are the replacement for the "autostart" feature from older versions.
+
+### Adding a custom plugin
+
+The plugins included in the store are just a quick front-end to the latest release AppImages. For everything else, you can create a custom plugin that runs any given executable script or binary.
+
+For example, if you installed WlxOverlay-S from AUR or built it from source, you can disable the original WlxOverlay-S plugin and create a custom plugin to run it:
+
+1. Create a new file `~/.local/bin/wlx-but-newer` (creating the `~/.local/bin` directory if it does not exist).
+2. Give it the content:
+    ```bash
+    #!/usr/bin/env bash
+    /usr/bin/wlx-overlay-s --openxr
+    ```
+3. `chmod +x ~/.local/bin/wlx-but-newer`
+4. In Envision, open the Plugins window.
+5. Add a custom plugin by clicking the ➕ plus button.
+6. For the executable file, point it to the script you just created.
+7. Name the plugin "Wlx but newer".
+8. Save, and then enable the new plugin.
+
+Now starting the profile will also start your custom or AUR version of WlxOverlay-S.
+
+### Plugin troubleshooting
+
+On some systems, a built-in plugin may not launch. This can happen for a number of reasons, but one in particular is so obtuse that it's worth a mention:
+
+Please *uninstall* AppImageLauncher. It intercepts the normal AppImage starting behavior in a dirty way that we can't predict.
+
+You can tell if you are affected if, when you run the WlxOverlay-S AppImage in terminal (whether in plugin form in `~/.local/share/envision/plugins`, or downloaded directly from GitHub), you only get the output `execv error: No such file or directory`.
+
+## Steam Flatpak
+
+To use Envision with the Flatpak version of Steam, you'll need to add the following filesystem overrides to Steam using an application like Flatseal:
+- `xdg-data/envision:ro`
+- `xdg-run/monado_comp_ipc`
+- `xdg-config/openxr:ro`
+- `xdg-config/openvr:ro`
+
+Alternatively, you can use the following command:
+```shell
+flatpak override --filesystem="xdg-data/envision:ro" --filesystem="xdg-run/monado_comp_ipc" --filesystem="xdg-config/openxr:ro" --filesystem="xdg-config/openvr:ro" com.valvesoftware.Steam
+```
 
 ## Experimental feature settings
 
@@ -48,7 +96,7 @@ The following resources can be entered into your Envision profile repo and branc
 
 ### Full body Lighthouse tracking
 
-Full body is now provided by default in Monado & OpenComposite through the XR_MNDX_xdev_space OpenXR vendor extension. This allows any tracked "xdev" in Monado to be forwarded as a raw pose without bindings to applications. OpenComposite exposes these as fake Vive FBT trackers for use.
+Full body is no longer experimental; it is enabled by default in Monado & OpenComposite through the XR_MNDX_xdev_space OpenXR vendor extension. This allows any tracked "xdev" in Monado to be forwarded as a raw pose without bindings to applications. OpenComposite exposes these as fake Vive FBT trackers for use.
 
 ### WMR & Rift S controller tracking
 
@@ -79,4 +127,10 @@ The Oculus Rift CV1 is supported on the OpenHMD profile of Envision.
 
 Start the profile with your headset placed on the floor in clear view of all bases to generate this file as your calibrated playspace origin first run and delete it to reset the configuration.
 
-A calibration of base stations will be saved to disk at `~/.config/openhmd/rift-room-config.json`.
+A calibration of base stations will be saved to disk at `~/.config/openhmd/rift-room-config.json`.
+
+### Fix View
+
+In Steam OpenVR games, the eye's are not calibrated properly, and result in double vision or cross eye effect.
+
+You can add "OXR_PARALLEL_VIEWS=1 %command%" to the launch options to fix this.

content/docs/fossvr/envision/wmr_controllers_on_arch.md

@@ -67,3 +67,12 @@ paru -S envision-xr-git
     - Leave Monado open.
     - Start the new game.
 - Always turn on the controllers **before** starting Envision.
+
+- Update controller firmware while running Windows. It's necessary for controllers to work in Linux, updating them from Linux is currently impossible.
+- Make sure that you **don't factory-reset the controllers** (performed by long-pressing the pairing button when controllers are off). This action restores the factory firmware version.
+- If monado fails to start with the following error, you likely need to update the firmware in Mixed Reality Portal:
+    ```
+    WARN [wmr_controller_send_fw_cmd] Controller fw read timed out after 250 ms
+    ERROR [wmr_bt_controller_create] WMR Controller (Bluetooth): Failed to create controller
+    ERROR [wmr_create_bt_controller] Failed to create WMR controller (Bluetooth)
+    ```