QtCraft

J.Hilk

Hi everyone,

it's been a while since my last showcase, so here is something a bit bigger: QtCraft, a voxel sandbox game (yes, the Minecraft kind) written in C++23 with Qt 6.12.

Sunset over a forest, realistic render mode

I've always wanted to make a more elaborate game with Qt. Privately there never was the time, and at work 3D never really came up as the solution to anything.

Then I found myself with some free leftover tokens from work, and the first thing I did with them was to finally start on that old idea: a Qt-based Minecraft clone. After the weekend those tokens were used up, and like a proper junkie I upgraded my private subscription to the 200 € tier and let it keep going. Roughly 7,000 $ later (had the tokens been paid via the API), this is the result.

Part of the motivation was that I actually wanted to learn this stuff: game dev, 3D rendering and so on.

Well. I now have a 3D Qt/QML game, but I learned sadly little about how it's actually done. To change that, I'd have to sit down and work through the code myself, which puts me right back where I started x)

So, the premise, what is QtCraft exactly?

At its core, QtCraft is an experiment in how far an AI agent (Claude Code) can build a non-trivial C++/Qt project more or less autonomously. I set the direction, decided the open questions, play-tested and reviewed, but the vast majority of the code was written by the AI.

What I did put in place is a lot of guard rails, because "the AI writes code" without checks degrades quickly:

Static analysis on every change: clang-tidy, clazy, qmllint, plus project-specific checks (function/file length, no output parameters, duplicate code, QML rules)
Modern C++ guidelines (C++ Core Guidelines, e.g. only named casts), warnings as errors, no exceptions (std::expected/std::optional instead)
Sanitizers: AddressSanitizer + UBSan and ThreadSanitizer runs on the full test suite (~470 tests)
Screenshot hooks and offscreen rendering, so UI and world can be tested and compared without a visible window
Headless and GUI benchmarks with A/B comparisons between builds (e.g. Qt 6.8 vs 6.12)
Remote bot controls, so the AI can run/test actual gameplay scenarios
clangd as an LSP tool for the agent, plus a generated code map, so it navigates the code instead of reading half the repo into its context
A decision log (every larger design decision gets a numbered entry), independent review agents before every merge, and CI for macOS, Windows and Linux

QtCraft contains:

Client/server architecture, also in single player (local server in the same process), multiplayer over TLS
Generated worlds with biomes, villages and structures, survival, creative, spectator and adventure mode
Redstone-like "Signal Dust", minecarts, farming, enchanting, trading …
Data-only mods (JSON), an in-game handbook (also on the web) and QDoc API docs
Rendering via QRhi, UI in Qt Quick, gamepad support

Valley with fog and mountains, realistic render mode

There are two render modes. Village, classic
Boardwalk village, classic render mode

The menus are plain Qt Quick:

Versions currently on GitHub:

0.1.0 is more or less the unedited state of what the AI produced.
1.0.0 (currently as release candidate) contains a number of reworks on top of that.

Not everything turned out the way I would have built it myself, and some parts were reworked several times. The entities are the best example: the AI did not build in enough robustness for future requirements, so every new feature that touched them meant another round of restructuring. That's probably the most interesting lesson of the whole project for me.

So please, if you're interested, try it!

Both versions are on GitHub, with packages for macOS (universal), Windows x64 and Linux (AppImage):

Repository: https://github.com/DeiVadder/QtCraft
Releases: https://github.com/DeiVadder/QtCraft/releases
Handbook & API docs: https://deivadder.github.io/QtCraft/

Feel free to look around, play it, or dig through the code (and the decision log). I'm grateful for any feedback — on the game, the code, or the approach itself.

J.Hilk

Update: 1.0.0 is final, and 1.1.0 "The Nether" is out

Short status update for anyone who tried it or is curious.

1.0.0 left the release-candidate stage shortly after my first post, and 1.1.0 is now on GitHub too, again with packages for macOS (universal), Windows x64 and Linux (AppImage):

Release: https://github.com/DeiVadder/QtCraft/releases/tag/v1.1.0

What's in 1.1.0

The big one: a world can now have more than one dimension. Build an obsidian frame, light it, stand in it for a few seconds, and you're in the Nether. Creatures, items and minecarts come along, one block there is eight in the Overworld, and the portal on the other side is found or built for you.

Crimson forest in the Nether

Soul sand valley in the Nether

The Nether with five biomes, each with its own fog, particles, ambience and music
Nether fortresses, bastion ruins and ruined portals
New creatures, including a fireball-spitting one you can hit back and a rideable lava walker
Brewing (longer, stronger and splash potions), 17 status effects, tipped arrows
Netherite and the smithing table, a new armour formula
A three-headed boss whose drop crafts the beacon
Hunger with saturation, eight volume sliders by kind of sound, an option to start a new world in the Nether
14 music tracks by Scott Buckley (CC-BY 4.0). The generated music is still there as an option; textures and all other sounds are still generated by the game itself.

Bridge of a Nether fortress over the lava sea

Old worlds keep working. World generators are versioned and frozen per release, so a 1.0.0 world opens unchanged and simply gets a Nether the first time someone goes there. On opening, the game asks once whether you want to switch the world to the new generator. If you do, it keeps everything already explored, and "Switch with transition" blends a ring of chunks from the old terrain into the new one.

From the experiment side

Two things I found interesting this round:

The Nether is the first feature that touched almost everything at once: chunk storage, the server tick, the protocol, the renderer, the save format, the handbook. After the entity rework story from my first post I expected pain, but it went surprisingly smoothly this time. I think that's mostly the guard rails and the decision log paying off: the agent had to plan the dimension model as numbered decisions first and only then build it.
The release still nearly failed at the last step. The Windows package broke in the release workflow on an MSVC warning about a shadowed name, which neither Clang nor GCC reported in the regular builds. The fix was trivial; the lesson was to also build with /WX on Windows before a release. Guard rails only help where you actually put them x)

The test suite is now at about 540 tests.

Next: 1.2.0, "The End": strongholds, the End portal and the End dimension are already in the development branch.

As before: feedback on the game, the code or the approach is very welcome, here or as issues on GitHub.