fwm: A Wayland Compositor Where Windows Are Box2D Bodies

A Compositor That Treats Windows as Physical Objects

fwm, the Physics Window Manager, is a Wayland compositor written in C using wlroots. Its defining feature is that windows are simulated as real rigid bodies by Box2D v3, giving them mass, momentum, inertia, and velocity. You can drag a window and throw it; it slides, bounces off walls, stacks under gravity, and comes to rest. This is not a visual effect layered on top. The README states windows behave as physical objects with those properties, and the simulation handles collisions, mass ratios, resting contact, and sleeping. The target user is someone who wants a desktop that feels like a physical space, not just a collection of rectangles. It is also for tinkerers who want a compositor where the physics engine is the core interaction model, not an afterthought.

How the Physics Simulation Works

The physics is powered by Box2D, an impulse-based rigid-body engine. The README lists specific parameters: restitution is 0.3, giving dull heavy bounces, and there is contact friction. Gravity modes cycle via Super+G between zero-g, space mode, and Earth gravity at 9.8 m/s², using a 100 px/m scale. There is a global speed limit, max_throw_speed, which caps how fast any dynamic window can move. The walls are swept against using continuous collision, and the README claims they can contain a throw at 96,000 px/s, fifty times the default cap. Free rotation, toggled with Super+R, hands a window's rotation to the simulation, so the collision box turns with the picture. The documentation in docs/physics.md covers units and limits, which is where you would go to understand the boundaries of the simulation. The key design choice is that physics is not a mode you turn on globally: each desktop decides whether it is a physics desktop, a BSP tiling one, or plain floating. That means the same windows can be physical objects on one desktop and neatly tiled on another.

The Desktop Strip and Built-In Tools

Beyond physics, fwm provides a full desktop environment. Ten desktops sit on one continuous strip, and the screen acts as a camera that pans across them. Moving between desktops is a pan, not a cut, and you can scroll freely mid-way. The expo view, triggered by the expo action, shows all desktops, and pressing z switches to a 3D mode where desktops become cards on a ring you can fly around. Each desktop has its own layout mode: physics, BSP tiling, or floating. Tiling is a property of the desktop, so switching it off returns windows to physical objects. The compositor includes a launcher, desktop strip, screenshots, wallpaper picker (stills or video), sound panel, and spectrum visualiser, so you do not need rofi, grim, slurp, or cava. There is also a modes menu where you can toggle tiling, floating, gravity, sound, visualiser, and even grass and wind. The grass is a lawn along the bottom edge of the monitor, with gusts travelling across it, and it has its own separate switch from wind.

Getting It Running: Build and Configuration

The README points to docs/getting-started.md for build and install instructions, and docs/configuration.md for the config file. Configuration is in config.toml, and every section is documented key by key. The keybindings and actions are in docs/keybindings.md, covering defaults, the action vocabulary, modes, mouse, and gestures. To start a session, you follow the getting-started guide, which covers the first five minutes. The compositor uses wlroots, so it depends on that library and Box2D v3. The built-in tools mean you do not need external utilities, but you still need a Wayland session manager or a way to start the compositor. The fwmctl command reads state, changes settings live without touching the config file, and streams events for scripting. This is a significant feature: you can adjust any setting at runtime, which is useful for experimenting with physics parameters without restarting.

A Known XWayland Bug and Other Limitations

The README mentions one open bug with XWayland: an invisible window that takes clicks. This is a concrete failure mode that could affect users running X11 applications. The physics simulation also has a documented limit: a very fast drag can outrun the windows it is pushing, even with the speed cap. The README points to docs/physics.md for details on this. Another limitation is that breakable windows, a mode where a window thrown hard enough destroys another, is only switched on from the modes menu, never from the config, and every session starts with it off. This suggests the feature is experimental and not meant for daily use. The physics model might also be a problem for accessibility or for users who prefer predictable window placement. A window that slides and bounces might be fun, but it is not efficient for a productivity-focused workflow. The compositor is young, with the first release in June 2026 and the Wayland port in July 2026, so expect rough edges.

Alternatives: Traditional Compositors vs. Physics-Based Ones

The most direct alternative is a traditional Wayland compositor like sway, which uses a tree-based layout and has no physics at all. Sway is built on wlroots like fwm, but its windows are static rectangles that you move and resize with keyboard shortcuts. The difference is fundamental: sway gives you predictable, deterministic control, while fwm gives you momentum and inertia. If you want tiling without physics, sway is a mature, stable option. Another alternative is a floating compositor like river, which also uses wlroots but treats windows as simple surfaces. River has tags and layouts, but no rigid-body simulation. The physics approach is unique to fwm among mainstream compositors, but it comes at the cost of complexity and potential frustration. For users who want the physics but also need reliability, fwm's per-desktop layout modes are a compromise: you can have a physics desktop for fun and a tiling desktop for work.

Maintenance, License, and Upgrade Considerations

fwm is licensed under GPL-2.0, which means any derivative work must also be GPL-2.0 or later. This is a copyleft license, so if you embed fwm code into your own project, that project must be GPL-compatible. The project is actively developed, with the last push on July 19, 2026, and releases coming every few weeks: v0.1.0 in June, v0.2.0 in July, and v0.3.0 in July. The version numbering suggests pre-1.0 instability. The README states the X11 version on the x11 branch is no longer supported, so upgrades are only for the Wayland version. The documentation includes an architecture guide for anyone changing the code, which is a good sign for maintainability. The dependency on Box2D v3 is a specific version, so upgrading Box2D could break fwm. The live IPC through fwmctl means you can change settings without restarting, which reduces the cost of experimentation, but the compositor itself is young and may require frequent updates as wlroots evolves.

Editorial conclusion

Adopt fwm if you want a compositor that makes physics a first-class interaction model and you are comfortable with a young, actively developed codebase under GPL-2.0. Do not choose it if you need a stable, minimal window manager for daily production work, or if you rely on XWayland without known bugs. Before adopting, verify the XWayland invisible-window bug, test the physics with your typical window sizes and screen resolution, and confirm the Box2D v3 dependency builds on your distribution. fwm is a bold experiment, not a conservative choice, and its value depends on whether the physics model improves your workflow or just gets in the way.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes