From e7600d1060d13fb7dc4c1f2dc7f2cf251ded64f9 Mon Sep 17 00:00:00 2001
From: hut <hut@hut.pm>
Date: Thu, 25 Apr 2024 02:42:16 +0200
Subject: [PATCH] document `--gl` option, adding a Troubleshooting section

---
 README.md | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 3d782a9..92a6ed3 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@
  +   ▀████████████████████████████████████████████████████▀
 ```
 
-Chapters: [Features](#features) • [Controls](#controls) • [Running OutFly](#running-outfly) • [Building](#building) • [Changelog](#changelog) • [Credits](#credits)
+Chapters: [Features](#features) • [Controls](#controls) • [Running OutFly](#running-outfly) • [Troubleshooting](#troubleshooting) • [Building](#building) • [Changelog](#changelog) • [Credits](#credits)
 
 Links: [Code](https://codeberg.org/hut/outfly) • [itch.io](https://yunicode.itch.io/outfly) • [Mastodon](https://mastodon.social/@outfly) • [Chat](https://matrix.to/#/#outfly:pub.solar)
 
@@ -80,12 +80,6 @@ pacman -S glibc libcap gcc-libs alsa-lib systemd-libs
 ./outfly
 ```
 
-If your graphics card does not support vulkan, try setting the environment variable `WGPU_BACKEND=gl`: (will result in poor performance)
-
-```
-WGPU_BACKEND=gl ./outfly
-```
-
 Alternatively, you can also install OutFly as a package, if your distribution has one. This will place OutFly in your "start menu". As of writing, only an ArchLinux AUR package exists, which you can install with this command:
 
 ```
@@ -101,6 +95,18 @@ yay -S outfly-git
 
 No releases for these operating systems exist yet. For MacOS, you can build OutFly yourself using the instructions below. Support for Android/iOS is planned for the future.
 
+# Troubleshooting
+## My GPU doesn't support Vulkan!
+
+Try running outfly with the "--gl" option, with one of these commands:
+
+```
+./outfly --gl
+cargo run --release -- --gl
+```
+
+This will result in some visual glitches, reduced performance, as well as a lot of error messages about CubeArrays which you can safely ignore.  Internally, this option sets `WGPU_BACKEND` to `gl`.
+
 # Building
 
 If there is no package for the version or operating system that you need, or if you wish to tinker on the game, you can also build outfly yourself.