Skip to content

About

macOS-style fullscreen Spaces for KDE Plasma 6: a KWin script that gives every fullscreen window (and borderless game) its own virtual desktop, then cleans it up when you leave

Topics

Resources

Stars

21 stars

Watchers

1 watching

Forks

Latest commit

 

History

17 Commits

Folders and files

Repository files navigation

🖥️ Fullscreen to New Desktop

macOS‑style fullscreen Spaces for KDE Plasma 6

Fullscreen a window — or let a borderless game fill the screen — and it glides onto its own virtual desktop, right next to the one you were on. Leave fullscreen and the desktop vanishes, dropping you back exactly where you started. Just like macOS.

KDE Plasma 6 Wayland X11 KWin Script License: MIT

Get it on the KDE Store

Fullscreen to New Desktop


✨ What it does

  • 🎬 Fullscreen → own Space. Any window that goes truly fullscreen (a video, a game, a presentation — at any resolution) is moved to a brand‑new virtual desktop created immediately after your current one.
  • 🎮 Borderless games too. A window sized exactly to the screen (borderless / "fullscreen windowed" games) gets its own Space as well. A normally‑maximized window — which stops at your panel — is left alone, unless you ask for it in the settings (handy with a scrolling tiler such as Ribbon).
  • 🧠 Game‑aware. All windows of one app (e.g. an anti‑cheat launcher + the game) share a single Space instead of each spawning their own, and the flicker games produce while changing resolution settles cleanly to one Space.
  • 🧹 Auto‑cleanup. Exit fullscreen or close the window and its temporary desktop is removed automatically. You never accumulate stray desktops.
  • 🔀 Most‑recently‑used order. Switch to a Space and it moves to the front of the row of Spaces, so the one you used last is always one step to the right of your desktop — macOS keeps your last full‑screen app one swipe away. The move waits for the switch animation to finish, so the slide stays smooth. Turn it off in the settings if you'd rather Spaces never moved.
  • 🏷️ Named after the window. The Space is titled ⛶ <window title> and keeps up with it — switch the tab or start another video and the pager follows.
  • ♻️ Survives a reload. That ⛶ prefix is also how the script recognises its own leftovers after a crash or a re‑install: on startup a still‑fullscreen window is re‑adopted (its home is the desktop the Space sits next to), an abandoned Space is emptied out and deleted.
  • 🖐️ Drag it out. Grab a window that's on a Space and the Space is released right away, even if the window is still screen‑sized — putting a hand on it is the intent signal.
  • 🎯 The Space stays pure. Open a window from another app while in a fullscreen Space and it's sent back to the previous desktop (and follows you there) — exactly the macOS behavior.
  • 🖼️ Picture‑in‑Picture friendly. Windows belonging to the app that owns the Space stay on it — a browser's PiP window, or a second window of the fullscreen app. Matching is by class or pid, because Chromium/Brave's PiP window sets no Wayland app_id at all (it reports an empty resourceClass); windows with no identity are left alone rather than moved. Previously PiP dragged you to another desktop and knocked the browser out of fullscreen, since switching the desktop under a fullscreen window makes it react to the visibility change. When you leave fullscreen the companions come back with it, so no Space is left stranded.
  • 🫥 Overlay‑proof. OSDs, notifications and tiling‑helper overlays (e.g. KZones) cover the screen too — they're filtered out and never trigger anything.
  • 📸 Screenshot‑safe. Screenshot/recording tools put up a real fullscreen window to let you pick a region — property‑for‑property identical to a fullscreen game. Spectacle, Flameshot, ksnip, portal pickers and the lock screen are excluded by name — add your own in the script's settings, no code editing needed.
  • ⌨️ One shortcut. Meta + F toggles fullscreen‑to‑a‑new‑desktop for the active window. Fully rebindable.
  • ⚙️ Settings, not source edits. Exclusions, the borderless‑game trigger and debug logging live in a proper config page in System Settings.

Works great with: YouTube & video fullscreen, exclusive‑fullscreen games, IDEs, PDF/reading, anything you want to focus on.

🌑 Companion script: Game Dim (source) — the two split the problem rather than overlap: this script handles the window that does cover the screen, Game Dim handles the one that doesn't, dropping the wallpaper, the panels and every other window to black around it. On a multi‑monitor setup they stack — the game gets its own Space and the other screen goes black instead of showing an empty, bright desktop.


🎥 Demo

flowchart LR
    A["🖥️ Desktop 1<br/>(your work)"] -->|"fullscreen a video"| B["🆕 New Space<br/>video only"]
    B -->|"exit fullscreen"| A2["🖥️ Desktop 1<br/>Space removed ✔"]
    style B fill:#1d99f3,stroke:#0b76c4,color:#fff
    style A fill:#2a2e32,stroke:#444,color:#eee
    style A2 fill:#2a2e32,stroke:#444,color:#eee
Loading

🤔 Why?

KDE's virtual desktops are great, but there's no built‑in way to get the thing macOS nails: a fullscreen app becoming its own Space, appearing right beside your work and disappearing the moment you're done — no manual desktop juggling.

An older script, Aetf/kwin‑maxmize‑to‑new‑desktop, did something similar for Plasma 5, but it relies on APIs that were removed in the Plasma 6 rewrite (client.desktop integers, workspace.clientFullScreenSet, …). This project is a clean, modern rewrite for Plasma 6 / KWin 6 using the current scripting API (window.desktops, VirtualDesktop objects, fullScreenChanged, createDesktop/removeDesktop).


📦 Installation

Option A — one‑liner (recommended)

git clone https://github.com/geodro/kde-fullscreen-spaces.git
cd kde-fullscreen-spaces
./install.sh

The installer copies the script into place, enables it, and hot‑reloads KWin — no logout needed.

Option B — with kpackagetool6

git clone https://github.com/geodro/kde-fullscreen-spaces.git
kpackagetool6 --type KWin/Script --install kde-fullscreen-spaces

Then enable it in System Settings → Window Management → KWin Scripts.

Uninstall

./uninstall.sh

Unloads the script, disables it and removes the installed copy. Its settings stay in ~/.config/kwinrc under [Script-fullscreen-to-new-desktop]; delete that group if you want them gone too.

Enable the shortcut

The default trigger is Meta + F. Change it in System Settings → Keyboard → Shortcuts → KWin (search for "Fullscreen active window on a new desktop").


⚙️ Configuration

System Settings → Window Management → KWin Scripts → the ⚙ next to Fullscreen to New Desktop:

Setting What it does
Also give a Space to screen‑sized windows Off = only true fullscreen windows get a Space; borderless "fullscreen windowed" games stay put.
Also give a Space to maximized windows On = maximizing a window sends it to its own Space too, title bar and all. Off by default.
Keep the Space you last used next to your desktop On = switching to a Space moves it to the front of the row of Spaces, so the one you used last is always one step away (most‑recently‑used order). Off = Spaces keep the position they were created at.
Excluded applications Comma‑separated app ids that never get a Space, on top of the built‑in list (Spectacle, Flameshot, ksnip, OBS, portal pickers, lock screen).
Log to the journal Turns on [fs2desktop] debug output — journalctl --user -f | grep fs2desktop.

Settings are read when the script loads, so reload it after changing them: untick and re‑tick it in the KWin Scripts list, re‑run ./install.sh, or run the three commands below.

Anything not exposed there lives at the top of contents/code/main.js (installed to ~/.local/share/kwin/scripts/fullscreen-to-new-desktop/). After editing, reload with:

qdbus6 org.kde.KWin /Scripting org.kde.kwin.Scripting.unloadScript fullscreen-to-new-desktop
qdbus6 org.kde.KWin /Scripting org.kde.kwin.Scripting.loadScript \
  ~/.local/share/kwin/scripts/fullscreen-to-new-desktop/contents/code/main.js fullscreen-to-new-desktop
qdbus6 org.kde.KWin /Scripting org.kde.kwin.Scripting.start

Animation. The automatic switch onto/off a Space is un‑animated (the slide effect is briefly suppressed) so it feels instant and doesn't flash the background through transparent windows. Your manual desktop switches keep animating. To keep the slide, delete the runNoSlide(...) wrapper and call fn() directly.

Debugging. Tick Log to the journal in the settings above (or set debugLogging=true under [Script-fullscreen-to-new-desktop] in ~/.config/kwinrc), reload, then watch:

journalctl --user -f -t kwin_wayland | grep fs2desktop

🧠 How it works

A window earns its own Space when KWin flags it fullscreen or when its frame exactly covers its screen (borderless games). It reacts immediately in both directions — no delay entering or leaving.

When triggered, the script snapshots the window's real home desktops (by stable id — never a temporary one), creates a new desktop right after the current one (or joins the Space an earlier window of the same app already owns), and moves the window there — assigning the window and switching desktops together, so browsers don't drop out of fullscreen from the visibility change. The switch is un‑animated (the slide effect is momentarily suppressed) so the Space appears instantly. On exit the saved ids are re‑resolved to fresh desktop objects, the window is restored, and the temporary desktop is removed once its last window leaves. All desktop ids are stored as stable strings — never VirtualDesktop wrappers, which go stale — so a game briefly flicking fullscreen still settles to a single clean Space.

New windows born on a dedicated Space are matched against the app that owns it by isCompanionOf(): same resourceClass, same pid, or no identity at all. A different, identifiable app is redirected to the home desktop and you follow it; everything else stays. The pid and no‑identity arms exist because Chromium's Picture‑in‑Picture window reports an empty resourceClass on Wayland — class alone never matched it. The same predicate decides who gets evacuated when the fullscreen window exits, so nothing we let stay can strand the Space. Excluded apps — the built‑in EXCLUDED_CLASSES list plus whatever you add in the settings — are ignored on both paths, which is what keeps Spectacle's fullscreen capture overlay from stealing a Space.

Switching to a Space re‑sorts it: it is moved to the front of its row of Spaces — the slot right after the last ordinary desktop — so the Space you used most recently is always the nearest one. KWin's workspace.moveDesktop() does the move outright, with no desktop created or destroyed and no window re‑assigned, so ids and window placement are untouched. It waits for the switch animation first: there is no "animation finished" signal, but workspace.isEffectActive("slide") answers the question, and moving a desktop out from under a running slide is what made it stutter. The wait is not conditional on you still standing on that Space — a slide reports active for about a second, and hopping onward inside that second is exactly what people do. Untick Keep the Space you last used next to your desktop to switch the whole behaviour off.

Nothing of this survives in memory across a reload, so the Space carries its own marker: it is named ⛶ <window title>, renamed whenever that title changes, and on startup recoverOrphanSpaces() walks every ⛶ desktop — re‑adopting the one that still holds a fullscreen window (its home is the nearest ordinary desktop to the left — where the Space was inserted from, and where re‑sorting keeps it) and deleting the rest after sending any stragglers home.


🩹 Troubleshooting

  • Nothing happens. Make sure the script is enabled (System Settings → KWin Scripts) and try logging out/in once. Confirm with: qdbus6 org.kde.KWin /Scripting org.kde.kwin.Scripting.isScriptLoaded fullscreen-to-new-desktop
  • A stray desktop was left behind. Reload the script (or log out and in): every Space it made is named ⛶ …, and on startup it deletes the empty ones and re‑adopts the ones still holding a fullscreen window. A desktop you renamed yourself is no longer recognised as ours — remove it in System Settings → Virtual Desktops.
  • Meta + F stopped reacting. The script instance died (a KWin crash will do it) while the shortcut stayed registered. Re‑run ./install.sh — it hot‑reloads the script and cleans up anything left over.
  • A screen‑filling window I didn't want moved. The trigger is "frame exactly covers the screen". A window you manually resized to the full screen qualifies; drag it 1 px smaller, or switch the trigger to fullscreen‑only (see Configuration).
  • I want the Space switch to animate. By default it's un‑animated (instant). Remove the runNoSlide(...) wrapper in main.js to restore the slide.

🙏 Credits

Inspired by Aetf/kwin‑maxmize‑to‑new‑desktop (Plasma 5) and, of course, by macOS Spaces.

📄 License

MIT © George Dumitrescu

About

macOS-style fullscreen Spaces for KDE Plasma 6: a KWin script that gives every fullscreen window (and borderless game) its own virtual desktop, then cleans it up when you leave

Topics

Resources

Stars

21 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages