Skip to content

Commit 71ac07d

Browse files
trasnake87claude
andauthored
Add note about Wayland causing software rendering issues (#123)
* 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 <noreply@anthropic.com> * 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 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 856d948 commit 71ac07d

File tree

1 file changed

+10
-4
lines changed

1 file changed

+10
-4
lines changed

src/troubleshooting/index.md

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ your hardware.
104104
You may need to reinstall the proprietary drivers if you had installed
105105
them manually before.
106106

107-
Performance can also degrade by [running under Xwayland](#i-am-running-into-glitches-with-xwayland).
107+
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.
108108

109109
### Black screen with Mesa 23.1+
110110

@@ -224,11 +224,17 @@ These issues are beyond the scope of this project and should be reported
224224
upstream. There are two solutions: Fallback to an X11 session, or run the game
225225
natively under Wayland.
226226

227+
> **Note:** If you are experiencing software rendering (llvmpipe) or other
228+
> graphics performance issues under Wayland, switching to an X11 session
229+
> is often the simplest fix. You can do this by selecting "X11" or "Xorg"
230+
> from your display manager's session menu at the login screen.
231+
227232
#### Run natively under Wayland
228233

229-
By default, the binary does not come with native Wayland support.
230-
You will need to [build the game launcher from source](../source_build/index.md)
231-
with SDL3 to enable native wayland support.
234+
By default, the binary uses EGLUT for the game window, which only supports X11
235+
(running under XWayland on Wayland sessions). To get native Wayland support, you
236+
will need to [build the game launcher from source](../source_build/index.md)
237+
with either `-DGAMEWINDOW_SYSTEM=SDL3` or `-DGAMEWINDOW_SYSTEM=GLFW`.
232238

233239
Once you have the game launcher built with Wayland support, you will need to
234240
force the client to run under Wayland, as it will still default to running

0 commit comments

Comments
 (0)