Waylandcraft: a Wayland compositor running inside Minecraft

What problem Waylandcraft solves, and for whom

Waylandcraft is a Wayland compositor implemented as a Minecraft mod. Instead of running a compositor on your desktop, you run one inside the game: application windows appear as in-world surfaces, and the game becomes the display server. The README opens with the one-line description "Wayland Compositor in Minecraft" and ships a demo video and a Modrinth listing.

The intended user is a Linux Minecraft player who already understands what a compositor and a window manager are, and who finds the idea of running real applications inside a blocky world interesting enough to tolerate setup friction. The README's system dependency list is Linux-only, so Windows and macOS users are out of scope from the start. It is also a client-side mod: the README says servers can opt to install it so players can use window items for themselves, but other players will not see your windows or interact with them. That rules out any use case built around shared screens.

How the compositor, input capture and Xwayland fit together

The architecture is split between a Java mod and a native component. The repository has both a src/ tree and a native/ directory, and the build script passes its arguments to cargo, so the native side is Rust. The README requires a Rust development environment and a Java 25 SDK to build, which confirms two toolchains rather than one.

On the input side, the mod relies on xkbcommon 1.11.0 and the xkbcommon tools, specifically xkbcli. Keyboard capture is a mode you toggle rather than a permanent state. By default V opens the app launcher, G enables keyboard capture so you can type into windows, and B opens the window manager screen. There is a second, harder capture mode bound to ALT+Q, and the README notes the only way to turn it off is to press ALT+Q again. That is the mode you want when Escape must reach the application instead of the game, and it is also the mode the README recommends for relative mouse movement in 3D games: move the mouse over the window, activate hard capture, and exiting it releases the mouse.

X11 support is delegated rather than implemented. Since v2.0.0 the mod integrates xwayland-satellite, and the README states that if the binary is installed on your system it should be started automatically. Nothing in the README describes a manual start command or a configuration key for that path, so the integration is effectively all-or-nothing on whether the binary is found.

Installing Waylandcraft and opening your first window

The README's own instructions are short: download the mod from the releases section, install Minecraft Fabric for 26.1.2, and drag the jar file into your mods folder. Before that, check the host side, because the mod will not work without it. You need Linux, the Fabric mod loader, xkbcommon library 1.11.0, xkbcommon tools (xkbcli), and xwayland-satellite if you want X11 applications. Prism Launcher and Sodium are listed as recommended rather than required.

Two installation constraints come with warnings attached. Do not use a Minecraft launcher packaged as a flatpak, because the README says you will not be able to use your apps. And on NVIDIA hardware, the README says to set the __GL_THREADED_OPTIMIZATIONS environment variable to 0 in your launcher. The README also warns that the Zink OpenGL driver has been known to cause issues and that native OpenGL should be used instead.

Once in game, the default keybinds are the whole first-run tutorial. Press V for the app launcher, and a window should appear in the world. Press G to capture the keyboard so typing goes into that window rather than the game. Press B for the window manager screen, which is where window placement and the Grab control live.

If you want to build from source instead of downloading a release, the README gives one command and notes that all arguments are passed to cargo:

./build.sh

The resulting jar lands in build/libs. For a development environment the README gives ./gradlew runClient. Building requires the Rust toolchain and a Java 25 SDK, so a plain JDK 17 or 21 install will not be enough.

Where Waylandcraft breaks, and who should not use it

The README is unusually direct: "This compositor still has lots of issues and bugs. Use it at your own risk or whatever." Treat that as the summary of the limitation section rather than a disclaimer to skim past. A compositor sits between every application and the display, so bugs there are not cosmetic.

The shader path shows the trade-off concretely. Iris shaders are supported since v2.0.2, but the README lists downsides: windows may have large borders, and text is harder to read from a distance because window anti-aliasing does not work. The explanation given is that windows are rendered with the same pipeline as entities, otherwise shaders would ignore them. Some shaders may also require disabling features such as temporal anti-aliasing. So shader users get compatibility at the cost of text legibility, which matters if you plan to read a terminal or an editor inside a window.

Multiplayer is a hard boundary rather than a rough edge. The README says multiplayer support would require video streaming, a lot of networking code and a rewrite of input handling, and that it is not really planned right now. If your goal is to show your desktop to someone else in the same world, this project is the wrong tool today. VR is a softer version of the same problem: depending on the VR mod, windows may display fine but controller interaction probably will not work, which the README summarizes as "kinda". Finally, the flatpak launcher restriction and the NVIDIA and Zink caveats mean a working desktop setup elsewhere does not guarantee this one works.

Waylandcraft against a normal nested compositor session

The obvious alternative is running a nested Wayland compositor as a regular desktop window, for example through a nested session of your existing compositor or a small standalone compositor in a window. The difference is not features, it is what hosts the session. A nested compositor runs inside your real display server, so your GPU drivers, shader stacks, launchers and input methods are the ones already working on your machine. Waylandcraft runs inside Minecraft, which means Minecraft's renderer, its mod loader, its launcher packaging and its input grab all sit between your applications and the screen.

That extra layer is exactly what buys the project its reason to exist, and it is also where every documented failure comes from: flatpak launcher packaging, Zink driver conflicts, NVIDIA threaded optimizations, shaders breaking anti-aliasing, and the ALT+Q capture mode that must be toggled off with the same key. A nested compositor has none of those specific problems because it does not route through the game. If you want a compositor for actual daily work, the nested session is the lower-risk choice. If you want applications rendered as objects in a Minecraft world, the nested session cannot do that at all, and Waylandcraft is the only thing in this comparison that tries.

Maintenance, licensing and what a fork inherits

The repository is not archived, and the last push was on 2026-09-23, five days before this writing, so the project is being touched. The release cadence is visible in the tagged versions: v2.0.1 on 2026-06-19, v2.0.2 on 2026-06-24, and v2.0.3 on 2026-06-30. Those three releases landed within twelve days of each other and then the release channel went quiet for roughly three months while commits continued, so a user pinning a version should expect to track the main branch for fixes rather than wait for tags.

Upgrade cost is higher than a typical Minecraft mod because of the native component. The build requires a Rust toolchain and a Java 25 SDK, and the runtime requires a specific xkbcommon version, 1.11.0, plus xkbcli. A distribution that ships a different xkbcommon version is a compatibility question the README does not answer. The project is GPL-3.0, and the README states that all contributions have to be made in accordance with that licence. It also sets a contribution policy around generative AI: mergeable pull requests must be made without major usage of LLMs, and work that did use them should be disclosed and filed as a draft pull request, where it may need to be examined or entirely rewritten by a human. Anyone planning to fork or vendor this code inherits both the GPL obligations and that review expectation. This is a description of the stated policy, not legal advice.

Editorial conclusion

Waylandcraft is for Linux players on Minecraft 26.1.2 with Fabric, xkbcommon 1.11.0, xkbcli and xwayland-satellite already installed, who want to see and type into real Wayland apps inside the game and accept the README's own warning that the compositor still has lots of issues and bugs. It is not for Windows or macOS users, not for flatpak launchers, not for anyone who needs multiplayer window sharing, and not for NVIDIA setups without setting __GL_THREADED_OPTIMIZATIONS to 0 and avoiding the Zink driver. Before adopting it, verify that xkbcommon 1.11.0 and xkbcli are present, confirm your launcher is not flatpak-packaged, and check that xwayland-satellite is on PATH if you need X11 apps, since the mod starts it automatically only when the binary is installed.

Frequently asked questions

Official sources

1. EVV1E/waylandcraft on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases