From cfc3054950070ba4e4249a3b3559214e50aa6cb5 Mon Sep 17 00:00:00 2001 From: Tom Date: Thu, 5 Feb 2026 19:23:22 -0800 Subject: [PATCH 1/2] Add note about Wayland causing software rendering issues Expand the troubleshooting documentation to more clearly guide users who are experiencing software rendering (llvmpipe) or graphics performance issues when running under a Wayland session. This adds a cross-reference to the native Wayland option in the graphics section and a practical note about switching to X11 in the Xwayland glitches section. Closes #82 Co-Authored-By: Claude Opus 4.6 --- src/troubleshooting/index.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/troubleshooting/index.md b/src/troubleshooting/index.md index 6e9c9fb..a0ba134 100644 --- a/src/troubleshooting/index.md +++ b/src/troubleshooting/index.md @@ -104,7 +104,7 @@ your hardware. You may need to reinstall the proprietary drivers if you had installed them manually before. -Performance can also degrade by [running under Xwayland](#i-am-running-into-glitches-with-xwayland). +Performance can also degrade by [running under Xwayland](#i-am-running-into-glitches-with-xwayland). If you are on a Wayland session and experiencing software rendering or graphical issues, try switching to an X11 session or running the game [natively under Wayland](#run-natively-under-wayland). ### Black screen with Mesa 23.1+ @@ -224,6 +224,11 @@ These issues are beyond the scope of this project and should be reported upstream. There are two solutions: Fallback to an X11 session, or run the game natively under Wayland. +> **Note:** If you are experiencing software rendering (llvmpipe) or other +> graphics performance issues under Wayland, switching to an X11 session +> is often the simplest fix. You can do this by selecting "X11" or "Xorg" +> from your display manager's session menu at the login screen. + #### Run natively under Wayland By default, the binary does not come with native Wayland support. From 1ee1dbea74722646eeca43bdb95efc1552c08b8e Mon Sep 17 00:00:00 2001 From: Tom Date: Fri, 6 Feb 2026 07:03:57 -0800 Subject: [PATCH 2/2] Address review: clarify EGLUT/X11 default, mention GLFW as Wayland option Per ChristopherHX's feedback: the default game window system (EGLUT) only supports X11/XWayland. Both SDL3 and GLFW support native Wayland, not just SDL3. Co-Authored-By: Claude --- src/troubleshooting/index.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/troubleshooting/index.md b/src/troubleshooting/index.md index a0ba134..0120c0b 100644 --- a/src/troubleshooting/index.md +++ b/src/troubleshooting/index.md @@ -104,7 +104,7 @@ your hardware. You may need to reinstall the proprietary drivers if you had installed them manually before. -Performance can also degrade by [running under Xwayland](#i-am-running-into-glitches-with-xwayland). If you are on a Wayland session and experiencing software rendering or graphical issues, try switching to an X11 session or running the game [natively under Wayland](#run-natively-under-wayland). +Performance can also degrade by [running under Xwayland](#i-am-running-into-glitches-with-xwayland). If you are on a Wayland session and experiencing software rendering or graphical issues, try switching to an X11 session or building with native Wayland support (see [below](#run-natively-under-wayland)). Note that the default game window system (EGLUT) only supports X11, so the game runs under XWayland unless built with SDL3 or GLFW. ### Black screen with Mesa 23.1+ @@ -231,9 +231,10 @@ natively under Wayland. #### Run natively under Wayland -By default, the binary does not come with native Wayland support. -You will need to [build the game launcher from source](../source_build/index.md) -with SDL3 to enable native wayland support. +By default, the binary uses EGLUT for the game window, which only supports X11 +(running under XWayland on Wayland sessions). To get native Wayland support, you +will need to [build the game launcher from source](../source_build/index.md) +with either `-DGAMEWINDOW_SYSTEM=SDL3` or `-DGAMEWINDOW_SYSTEM=GLFW`. Once you have the game launcher built with Wayland support, you will need to force the client to run under Wayland, as it will still default to running