Skip to content

Commit 7f2ff64

Browse files
authored
Add documentation for enabling Native Wayland support and troubleshooting XWayland issues (#103)
* Add instructions for enabling SDL3/Wayland support * Add troubleshooting for XWayland
1 parent 76e4f73 commit 7f2ff64

File tree

2 files changed

+31
-0
lines changed

2 files changed

+31
-0
lines changed

src/source_build/launcher.md

+5
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,11 @@ if you didn't install the MSA daemon (e.g. if you ran the previous
3434
command in `/home/paul/`, you'd have to use
3535
`/home/paul/msa/build/msa-daemon` as the path).
3636

37+
### Adding Wayland support
38+
39+
By default, compiling the game launcher will not come with native Wayland support, as SDL3 is not enabled. The game will run under Xwayland, but if you are running into issues (e.g. flickering, mouse not locked), it's best to run the game natively through Wayland. To compile the launcher using SDL3, add the following cmake flag:
40+
`-DGAMEWINDOW_SYSTEM=SDL3`
41+
3742
## Installation
3843

3944
You can now optionally install the launcher system-wise. If you don't,

src/troubleshooting/index.md

+26
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,8 @@ your hardware.
9898
You may need to reinstall the proprietary drivers if you had installed
9999
them manually before.
100100

101+
Performance can also degrade by [running under Xwayland](#i-am-running-into-glitches-with-xwayland).
102+
101103
### Black screen with Mesa 23.1+
102104

103105
Try adding `MESA_EXTENSION_OVERRIDE=-GL_EXT_instanced_arrays` to
@@ -189,6 +191,30 @@ Mac OS X:
189191
- `./mcpelauncher-client -dg ~/Library/Application\ Support/mcpelauncher/versions/1.2.3.4` -
190192
Replace 1.2.3.4 with the version of Minecraft you want to run.
191193

194+
### I am running into glitches with Xwayland
195+
196+
Xwayland does a fairly good job of running X applications on Wayland, but it
197+
is not perfect. Depending on your graphics drivers and your desktop environment/
198+
window manager, you will run into issues that will affect your experience.
199+
These issues are beyond the scope of this project and should be reported
200+
upstream. There are two solutions: Fallback to an X11 session, or run the game
201+
natively under Wayland.
202+
203+
#### Run natively under Wayland
204+
205+
By default, the binary does not come with native Wayland support.
206+
You will need to [build the game launcher from source](../source_build/index.md)
207+
with SDL3 to enable native wayland support.
208+
209+
Once you have the game launcher built with Wayland support, you will need to
210+
force the client to run under Wayland, as it will still default to running
211+
under Xwayland. This is done by unsetting the `DISPLAY` environment variable.
212+
213+
Through the Qt Launcher, edit your profile and open up the
214+
advanced options. Under "Environment Variables", add a variable called
215+
`DISPLAY` (case-matching), and leave the value blank. Doing so will have the
216+
client running under native Wayland.
217+
192218
## Qt launcher UI
193219

194220
### Running the troubleshooter

0 commit comments

Comments
 (0)