HackMatrix: a 3D Linux desktop environment with a game engine

Windows that live where you are looking

HackMatrix is a 3D Linux desktop environment, and the README adds the parenthesis that it can also be a game engine. The project page is on itch.io, there is a video of it running, and there is a Discord server.

The idea is that the desktop is a space rather than a stack. You look around with the mouse, you move with the keyboard, and a window opens in the position you were looking at when you launched it. That is the whole difference from a conventional desktop, and everything else in the project follows from it.

The mechanics of launching are best spelled out because they are unusual. The application launcher is wofi, the same wofi that appears in the dependency list, and because the d key is mapped to movement the launcher is bound to v without a modifier. You type the program name, press enter, and the window appears where you were looking.

The project is MIT licensed, its primary language is C++, and the release history has a single entry, v1 stable, from 2024-11-24. The last push to the repository was on 2026-08-28, and the repository is not marked archived on the hosting platform, but the title of the readme itself begins with the word archived. So the honest description is a project the author has declared finished while still taking the occasional merge, and the last change was a Wayland port that the readme says will be buggy.

That combination tells you what kind of read this repository deserves, and it is a fascinating one rather than a practical one.

The key bindings are a game controller

The controls section of the readme reads like a manual for a game, and that is the point.

Movement is the wasd keys, and looking around is the mouse. Focusing a window is done by looking at it and pressing r, which is the spatial equivalent of clicking a title bar. The readme warns that this sometimes does not work temporarily because of a bug, and gives the workaround: use Super+1 to focus a window, after which manual focus works again.

Windows are given hotkeys automatically, in the order they are created, and you move between them with Super plus a number. So the first window is Super+1, the second is Super+2, and a window that is opened later is not given the number you would expect, which is a consequence of the ordering rule rather than a bug.

The rest of the bindings are short. Super+e exits a focused window, Super+q closes a focused window, and Escape exits HackMatrix when no window has focus, with the reminder to press Super+e first if one is focused. Pressing p takes a screenshot into a screenshots folder inside the project directory.

There is one more mode, and it is the bridge to the game engine part. When no application is focused, pressing f enters mouse mode, which gives you access to the small menu at the top of the interface. From there you can open the entity editor, and the wiki page for the game engine explains what it is for. In other words, the same keys that drive the desktop switch you into the tools that edit the world the desktop is made of.

The build is a fresh Wayland port and the readme says so

The build instructions come with a warning that is unusual to see in a project readme, and it is best quoted.

It says this is a new Wayland build, that it will be buggy, and that the author merged it to the main branch regardless. That single sentence sets the expectations for everything else in the repository.

The build itself is the standard CMake sequence:

mkdir -p build
cd build
cmake ..
make -j$(nproc)

Running it has one instruction that is easy to miss and would otherwise cost you an evening. It is recommended to launch from a tty, and in the root directory of the project you run the launch script. If you installed HackMatrix from the AUR package, the command is simply hackmatrix.

The reason for the tty advice is not stated, but the structure of the repository suggests it. There is a wlroots directory, so the compositor is part of the tree, and the client libraries, the protocol definitions and the tools all talk to it. A desktop environment that owns the session does not fit neatly into a graphical login session, which is why starting it from a terminal is the documented path.

The repository also has a launch file at the root, a config.yaml for configuration, an imgui.ini for the immediate mode interface library that the editor uses, and a compile_commands.json, which means the project is set up for clang tooling and for editors that read that file.

A dependency list that includes a game engine

The dependency list tells you more about the project than the readme's own summary does, and it is unusual for a desktop environment.

Beyond the Wayland pieces, so wayland-protocols, Xwayland, the XCB libraries for the wlroots X11 backend and for Xwayland, and wofi as the launcher, the list contains ZeroMQ and Protocol Buffers, which is a networking and serialisation stack for messages between processes, and spdlog and fmt for logging and formatting. Then the graphics side, with EGL and OpenGL ES 2, and Assimp, the asset import library, and SQLite3 for the database, and pthread.

The Assimp and OpenGL entries are what make this a game engine rather than a window manager with a 3D camera. The repository layout backs that up. There is a shaders directory, a protos directory for the protocol definitions, and directories named mmo, stream, vox, tracy and webInclude, plus a db directory, a tests directory and a tools directory. Tracy is a profiling library, and the fact that it is vendored in the tree tells you the author profiled the thing.

There is also a client_libs directory with a Python client, and a scripts directory with an install script for it. The documented flow is to run scripts/install-python-clientlib.sh from the project root, and what it does is set up a virtual environment, install the Python package from the client_libs directory and then run a script called player-move.py to test it:

python -m venv hackmatrix_python
cd hackmatrix_python
source bin/activate
cd client_libs/python
pip install .
cd ../..

So the world can be driven from Python, which is the part that makes the game engine framing more than a metaphor.

Crow is either found or fetched at a pinned revision

One dependency gets its own section in the readme, and it is the one that most often decides whether a build succeeds on a given machine.

HackMatrix now tries find_package for Crow first, and if that fails it automatically builds Crow from source at the pinned revision c61a26e.

If you want to force the source build path, or you already have a Crow tree checked out locally, the CMake configuration takes two options, MATRIX_FORCE_FETCH_CROW to turn the source build on and MATRIX_CROW_SOURCE_DIR to point at a local checkout:

cmake -S . -B build -DMATRIX_FORCE_FETCH_CROW=ON -DMATRIX_CROW_SOURCE_DIR=/path/to/Crow

The readme notes that the local source override is mainly useful for offline builds, or for testing the fallback path on a machine that already has Crow installed globally. That is a precise framing, because the fallback path is exactly the kind of thing that breaks silently when the system package and the pinned revision disagree, and the two options let you test both routes without uninstalling anything.

The pinned revision is the other half of the story. Building from source at a fixed commit means the result is the same on every machine, which is the opposite of what find_package gives you, and the project is explicit that the automatic path prefers what the system provides so that a distribution package keeps working.

Per distribution instructions, and an honest note about Arch

The installation section gives the package commands for four distributions, and the differences between them are a good illustration of how much work a Linux desktop can be to build.

For Ubuntu and Debian the list is long, covering cmake, wofi, xwayland, wayland-protocols, the protobuf compiler, build-essential, the development packages for ZeroMQ, Protocol Buffers, spdlog, fmt, EGL, OpenGL ES, Assimp and SQLite3, pkgconf, the Wayland development files and a set of individual libxcb packages for composite, dri3, ewmh, errors, icccm4, present, render, renderutil, res, shm0, xfixes0 and xinput.

Fedora has the equivalent list in dnf form, and Arch has one in pacman form. The Arch entry is the interesting one, because the author adds a note above it: he is working on an issue with protobuf compilation errors for Arch, and he links two pull requests, one showing how to resolve the issue and one asking for help testing it before it can be merged. He asks contributors to try it and report in the pull request comments.

For Arch there is also an AUR package, installed with yay, and the readme says you can use the PKGBUILD in the distributions directory instead, with a note to replace yay with whatever package manager you use. Gentoo gets an emerge command, with a warning that you may hit use flag and masked package problems and will have to work those out on your own system.

That Arch passage is the most useful paragraph in the whole readme, because it tells you what the state of the project really is: one person maintaining a large dependency tree across four distributions, and asking for help on the distribution that is hardest.

Editorial conclusion

HackMatrix fits a developer who wants to understand what a 3D desktop environment looks like from the inside, because the window management, the scene graph and the entity editor are all in the same tree, with the shaders, the protocol definitions and the tools directories next to the source. It is the wrong choice for daily use, since the README states the new Wayland build will be buggy, the manual focus command is documented as failing intermittently, and the scrolling behaviour is listed as an open bug. It is also the wrong choice if you want a maintained project, because the README marks HackMatrix as archived, even though the repository itself is not marked archived on GitHub and a Wayland port was merged to the main branch. Before you build it, install the dependency list for your distribution, fetch Crow the way the build expects, and expect to launch from a terminal rather than from a session.

Frequently asked questions

Official sources

1. collinalexbell/HackMatrix on GitHub
2. Issues
3. License: MIT
4. README
5. Releases