Wayland and X11: selection and diagnostics

The display server handles windows and input. The renderer builds the image; the rendering driver selects the graphics API. For example, wayland, forward_plus and vulkan describe three different choices.

Xwayland lets an X11 application run inside a Wayland session. A Wayland desktop session therefore does not establish that the game uses the native Wayland backend. See the official Xwayland documentation.

Project and editor settings

Enable Advanced Settings in Project Settings, then set display/display_server/driver.linuxbsd:

• default: this build’s standard backend order;
• x11: request X11;
• wayland: request Wayland;
• headless: no graphical window, not a Wayland/X11 test.

Current Linux source registers X11 before Wayland when both are enabled. Do not assume this order for every custom build: a backend can be excluded during compilation. Restart the application and check the actual selection.

The editor itself has Editor Settings → Run → Platforms → LinuxBSD → Prefer Wayland (run/platforms/linuxbsd/prefer_wayland), defaulting to false. It requires a restart and is considered when WAYLAND_DISPLAY is present. This neither renames the Vulkan graphics driver nor configures HDR.

Temporary CLI selection

Run on Linux from the exported game directory. First inspect this particular executable’s available options:

./MyGame.x86_64 --help
./MyGame.x86_64 --display-driver wayland
./MyGame.x86_64 --display-driver x11

The latter two commands are separate comparison runs. The correct option is --display-driver; current parsing has no --display-server option. Do not confuse it with --rendering-driver, which chooses the graphics API.

If the requested CLI backend is absent from the build, parsing reports Unknown display driver and aborts: fallback does not happen at that stage. If a registered backend fails initialization, the engine tries other registered window backends. Success is not guaranteed: another backend can also be missing or unable to connect. Automatic window-backend fallback does not select headless instead.

Inspect the actual backend

Save this class as RuntimeDisplayInfo.cs. From a C# script inside the tree, call ReckfellApi.Print(RuntimeDisplayInfo.Describe());:

using Reckfell;

public static class RuntimeDisplayInfo
{
    public static string Describe() =>
        $"display={DisplayServer.GetName()}; " +
        $"renderer={RenderingServer.GetCurrentRenderingMethod()}; " +
        $"driver={RenderingServer.GetCurrentRenderingDriverName()}";
}

Current source returns Wayland or X11 from DisplayServer.GetName() for the corresponding Linux backend; these names are capitalized unlike CLI values. Inspect actual output and fallback messages rather than only project configuration. The checked Windows headless run reports display=headless; this is not evidence of a working Linux backend.

HDR and window limitations

Current Wayland HDR output requires renderer, graphics-driver and surface-format support plus suitable window luminance headroom. The X11 backend does not provide this HDR path, including X11 applications using Xwayland. Selecting wayland alone does not establish HDR: query the particular window using the HDR guide.

Current Wayland implementation does not perform arbitrary window_set_position for ordinary top-level windows. Do not assume X11 window-placement logic works unchanged. Test placement, multiple displays, scale, input and additional windows on the target compositor; changing PCK data does not fix window-protocol restrictions.

Temporarily exclude libdecor for diagnosis

For Wayland frame/titlebar issues in a build using libdecor, try a separate run:

RECKFELL_WAYLAND_DISABLE_LIBDECOR=1 ./MyGame.x86_64 --display-driver wayland

The prefix changes the environment for this process only. It neither switches Wayland to X11 nor fixes all UI errors; client-side decorations can disappear. Enable verbose logging if you need to see whether the libdecor check was skipped. Remove the prefix for an ordinary run.

Diagnostics

CLI help and the C# example were checked using the installed Windows Runtime. Linux backend selection, fallback, HDR, libdecor and window restrictions were source-reviewed; this run does not establish a Linux session, shell execution or actual window behavior. For package contents, see Linux export.