Luanti: a C++ voxel engine where games are Lua mods

What Luanti is, and who the engine-plus-Lua split is for

Luanti is a voxel game-creation platform. The README describes it as "a free open-source voxel game engine with easy modding and game creation", and the repository topics list c-plus-plus, cpp17, game-engine, lua and voxel-engine. That combination is the whole point: the heavy work of chunk storage, meshing, networking and rendering lives in C++, while the rules of any particular game live in Lua on top of it.

The audience is therefore not someone looking for one finished game. It is someone who wants to build a voxel game, or extend one, without touching the engine's C++ core. The practical consequence is that a Luanti install with no game selected is close to an empty shell. You choose a game, and the game decides what the world contains, which items exist and which controls matter. Mods then layer on top of that game.

This is a different bargain from a game that ships complete. You get a platform and a scripting surface; you give up the assumption that everything in the box was designed together.

How the engine, games and mods fit together

The repository layout shows the split directly. src/ holds the C++ engine, builtin/ holds Lua that the engine itself provides, games/ and mods/ are the directories where content is expected, and client/, clientmods/, irr/ and lib/ cover the client, client-side mods, the Irrlicht-derived rendering code and bundled libraries. The data flow at runtime is: the engine loads a game, the game declares its mods, and each mod's Lua runs against the engine's exposed API.

Worlds are stored as separate folders under user/worlds/, which is what makes a world portable between machines: copy the folder, keep the game and mods available, and the world loads. The engine also defines three path categories, bin for compiled binaries, share for distributed read-only data, and user for user-created modifiable data. On Linux installed builds those are /usr/bin, /usr/share/minetest and ~/.minetest respectively, and the user path can be overridden with the MINETEST_USER_PATH environment variable. Note that the paths still carry the old Minetest name even though the project was renamed.

Configuration follows the same pattern. The default file is user/minetest.conf, it is created by closing Luanti for the first time, and a different file can be selected with --config <path-to-file>. A run-in-place build looks for minetest.conf relative to the executable instead. The naming inconsistency between the product name and its files is a real source of confusion when you search for documentation.

Installing Luanti on Linux and running a first world

The README points to per-platform compile guides rather than a single install command, so the honest answer is that installation depends on your distribution and on whether you want a packaged build or a source build. Compiling is documented in doc/compiling/README.md with separate files for linux.md, windows.md and macos.md. If you build from source, the common path is CMake with a build directory, as the repository's own Dockerfile does.

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

The Dockerfile uses -DCMAKE_BUILD_TYPE=Release and installs to /usr/local with -DCMAKE_INSTALL_PREFIX=/usr/local. A server-only build is possible with -DBUILD_SERVER=TRUE, and Prometheus metrics can be enabled with -DENABLE_PROMETHEUS=TRUE, which the Dockerfile also sets. Those flags are the ones the repository actually uses, so they are a safe starting point for a headless build.

Once the binary runs, the first real task is choosing a game, since the engine alone gives you nothing to play. Games and mods are distributed through ContentDB, and the client's content browser is the normal way to install them. After a game is installed you create a world, and the world folder appears under user/worlds/. Closing the client for the first time writes user/minetest.conf, which is where you would later add or change settings.

For a first mod, the shape is a directory containing an init.lua, placed where the game can find it, with the game's API used from that file. The repository ships .luacheckrc at the top level, which tells you the project expects Lua sources to pass luacheck, and that is a reasonable check to run on your own mod before sharing it.

Where Luanti is the wrong tool

The engine does not ship a default game, and that is a limitation rather than a detail. A new user who installs Luanti and expects a playable world has to make a content decision first. If you want a single, coherent, finished game with consistent art and balance, the platform model works against you: content comes from many authors, and mixing mods can produce visual and mechanical mismatches that no one designed around.

Performance is the second boundary. The engine is C++, but everything a game defines runs as Lua, and large worlds with many mods push work into that layer. The README documents a zoom privilege and other privileges, which indicates that capabilities are gated by the game rather than granted freely, so a mod that assumes a privilege will fail quietly when the game does not grant it. Debug behaviour differs between builds too: the README notes that F4 camera update disabling is not available in release builds, so a bug you can reproduce in a debug build may behave differently in the binary you ship.

The licence situation needs attention rather than assumption. The repository metadata reports the licence as NOASSERTION, while the README's badge and the COPYING.LESSER and LICENSE.txt files point to LGPLv2.1+. That is not a contradiction you should resolve by guessing, and it matters if you plan to redistribute a modified engine.

Luanti compared with Minecraft and with engine-only alternatives

The comparison people reach for is Minecraft, and the difference is structural rather than cosmetic. Minecraft is a game with a modding layer bolted onto it; Luanti is an engine whose games are content. In Luanti the game itself is replaceable, which is why the same client can run entirely different voxel games. In Minecraft you extend one game. That distinction decides most adoption questions: if you want to build a game, Luanti's model is the more direct route; if you want to play a specific game, the platform framing adds a step.

Against a general-purpose 3D engine, the difference runs the other way. Luanti already implements voxel-specific concerns such as chunked worlds, a block-oriented world format and a Lua API aimed at game rules. Using a general engine means writing that layer yourself. The cost is that you inherit Luanti's opinions about how worlds, games and mods are organised, and stepping outside them means working in src/ in C++.

The repository also carries Docker support for servers, with doc/docker_server.md for running a server and doc/developing/docker.md for developing minetestserver with Docker. That is a meaningful option for headless hosting, and it is separate from the desktop client path.

Maintenance, releases and what upgrading costs you

The last push to the repository was on 2026-09-18, and the repository is not archived. Recent releases are 5.17.0 on 2026-08-20, 5.17.0-rc1 on 2026-08-13 and 5.16.1 on 2026-05-10. The version scheme is documented as major.minor.patch since 5.0.0-dev, with an earlier 0.major.minor scheme before that, so the current line is 5.x.

The upgrade cost sits mostly in content, not in the engine. A new engine release can change what the Lua API offers, and a mod that has not been updated may not follow. Because worlds live in user/worlds/ as separate folders, the world data itself is easy to keep across upgrades; the risk is the game and mod set around it. Testing a version bump against your specific game before rolling it onto a server is the practical precaution.

On licensing, the README carries an LGPLv2.1+ badge and the repository includes COPYING.LESSER and LICENSE.txt, while the metadata field says NOASSERTION. LGPL has implications for how a modified engine can be combined and redistributed, and those implications depend on your situation. This is not legal advice; read COPYING.LESSER and LICENSE.txt directly before shipping a modified build.

Editorial conclusion

Luanti fits people who want to write a voxel game rather than only play one: the engine is C++ but games and mods are Lua, so a first mod is a directory with init.lua and no recompile. It is a poor fit if you need a single finished game with a coherent art direction, since the engine ships no default game and you pick one from ContentDB. Before building anything, verify which game you will target, because every mod you write depends on that game's API surface, and check that the version in your distro packages is current enough for the mods you want.

Frequently asked questions

Official sources

1. Issues
2. luanti-org/luanti on GitHub
3. Project website
4. README
5. Releases