# Hyprland setup (/docs/guides/hyprland)

Choose native Wayland or XWayland and apply rules for your Hyprland version.

## Choose the backend [#choose-the-backend]

Native Wayland uses a layer-shell surface. Window rules matching `chudcs2.overlay` apply to the X11/XWayland overlay window. They do not configure the native layer surface.

For XWayland, enable **Hyprland Compatibility Mode** in **Debug**, save your profile and restart with:

```bash
sudo ./build/chudcs2 --x11
```

This mode lets the compositor manage the overlay window. Configure it to float, remain pinned, cover the monitor and avoid taking focus.

Check your compositor version before choosing syntax:

```bash
hyprctl version
```

## Hyprland 0.55 and newer [#hyprland-055-and-newer]

Hyprland 0.55 introduces Lua configuration. Add this rule to your `hyprland.lua`. The property names and coordinate expressions follow the [Hyprland window rules reference](https://wiki.hypr.land/Configuring/Basics/Window-Rules/).

```lua
hl.window_rule({
  match = { class = "^(chudcs2[.]overlay)$" },
  float = true,
  pin = true,
  size = { "monitor_w", "monitor_h" },
  move = { 0, 0 },
  no_focus = true,
  no_blur = true,
  no_shadow = true,
  no_anim = true,
  border_size = 0,
  suppress_event = "maximize",
})
```

## Hyprland 0.54 [#hyprland-054]

Use the structured `windowrule` syntax in `hyprland.conf`. See the [version 0.54 window rules reference](https://wiki.hypr.land/0.54.0/Configuring/Window-Rules/).

```ini
windowrule {
  name = chudcs2overlay
  match:class = ^(chudcs2[.]overlay)$
  float = on
  pin = on
  size = 100% 100%
  move = 0 0
  no_focus = on
  no_blur = on
  no_shadow = on
  no_anim = on
  border_size = 0
  suppress_event = maximize
}
```

For older versions, use that version's wiki instead of mixing `windowrulev2`, structured rules and Lua syntax. Reload the compositor configuration and restart the overlay after changing placement rules.

## Alignment and focus [#alignment-and-focus]

Match only the overlay class. Applying `no_focus` to the settings window would prevent normal menu interaction. If geometry remains wrong, check the selected monitor and [Display scaling](/docs/guides/display-scaling).