# FreeKill: a board game engine where the rules are written in Lua

> FreeKill is an open source board game engine written in Qt and Lua, with a Qt Quick client and a single-threaded asynchronous Lua server, and it ships the machinery that online card games need: a lobby, reconnection after a dropped connection, and recording and replay. The rules themselves live in separate repositories, which is the part that surprises contributors.

**Qsgs-Fans/FreeKill** — An open source board game engine, written in Qt and Lua.

- Repository: https://github.com/Qsgs-Fans/FreeKill
- Website: https://fkbook-all-in-one.readthedocs.io/
- Stars: 1,040 · Forks: 110
- Language: C
- License: GPL-3.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/qsgs-fans-freekill

## The engine is a framework, not a game

FreeKill is described as an open source board game engine, and the repository metadata says the same in English: an open source board game engine, written in Qt and Lua.

The framing is that of a framework rather than a game. Through FreeKill you can create the board game you want, or extend a board game that has already been completed. The documentation site is fkbook-all-in-one.readthedocs.io, and the games that ship with it are the proof of the concept.

The implemented games listed in the README are the well known Chinese card game, which can be extended and which is temporarily coupled inside the project and is expected to become an independent repository in the future, Chinese chess and international chess, and Hearts and bridge among others.

The audience is therefore two groups who are really one group. There are the people who want to play these games online, with the network features the framework provides, and there are the people who want to write a new game on top of the engine. The second group is the one the project is designed for, and the rules are Lua files, which is what makes the extension model work at all.

One historical note is visible in the README's contributing section, which invites contributions to a project under a different name, the New Moon Kill, the name the Chinese card game was known by. The engine outlived that name, and the repository still carries traces of it.

## A Qt Quick client on top of a Lua async server

The technical description in the README is short and specific. FreeKill uses the Lua language to implement a high-performance single-threaded asynchronous server, and it uses Qt Quick to implement the GUI, making full use of graphics hardware performance.

That pairing is the interesting engineering decision. Lua is a scripting language with a runtime that is easy to embed, and running the server logic in a single thread with an event loop means the whole server shares one execution context. A game server that has to coordinate many rooms and many asynchronous calls has no use for threads it cannot safely share, and a single-threaded asynchronous design removes an entire class of concurrency bug from a codebase that is, by definition, full of concurrent clients.

The cost is that everything inside the server is serialised. A long synchronous operation in a Lua call blocks every room in the process, and the framework's own API has to be written so that the expensive parts are cooperative. That is a discipline the rule implementer has to follow, and the fact that the engine is written this way tells you the authors had to write a lot of game rules under that constraint.

On the client side, Qt Quick means the interface is built from QML with a scene graph, which is why the README emphasises making full use of graphics hardware performance. Card games are interface-heavy, with drag, stacking, highlighting and animation, and a retained-mode scene graph is a good fit for that.

The repository layout follows the split, with client, server, src, lib, ltk, LunarLtk, Fk, lua, lang, packages, include, thirdparty, android, audio, distro, docker, fonts and image directories at the top level, along with a .clangd file for the C++ side and a .luarc.json for the Lua side, which is the editor configuration for the two languages in play.

## The scripts live in a different repository, on purpose

The repository split is the part of the README that most affects anybody who wants to contribute, and it is stated plainly.

This repo mainly provides the client-side Qt C++ support, plus a small amount of server support, and the server here is only for single-player games. The scripts contained in this repo are therefore only for use when packaging a release. For the full functionality, the README points at other repositories: an STL-based server in freekill-asio, the repository that maintains all the script files in freekill-core, and the documentation in fkbook-all-in-one, which the README marks as needing maintenance.

There is a plan to change this. It is possible that all the scripts will be removed from this repo in the future, and users will instead be required to install the freekill-core package at runtime.

That direction is worth understanding because it changes what a fork means. Today a person who clones this repository has a working single-player build, because the release scripts are present for packaging. After the change, a build needs the core package installed as well, and the scripts are a runtime dependency rather than part of the tree.

The contributing section states the rule directly: all the Lua files in the project, except those under test, are managed by the special repository freekill-core, so do not modify the Lua files in this repository directly, and the freekill-core README has more information. It also notes that only this repository is hosted and actively maintained on GitHub, while the implementations of the official characters are scattered across many small repositories maintained on Gitee, under the organisation account at gitee.com/qsgs-fans. The requirements for the project and for several extension packages are written in issues, and the README asks people to make use of them.

So a contribution to the rules of a character goes to a small repository on a different forge, and a contribution to the engine goes here. That is a deliberate split, and it is also a lot of navigation for a newcomer.

## Windows and Android ship as binaries, everyone else compiles

The installation section splits the platforms in two, and the split is worth knowing before you plan a deployment.

The release page provides packaged builds for Windows and Android, and the README says to download and use them directly. For updates, you overwrite the previous installation with the new one, and there is no need to uninstall the old version first.

Linux and BSD users have to build from source, and the README gives a Debian example with a long apt list:

```sh
$ sudo apt install git gcc g++ cmake swig
$ sudo apt install liblua5.4-dev libsqlite3-dev libreadline-dev libssl-dev libgit2-dev
# qt6-declarative-dev - qml, qt6-tools-dev - LinguistTools
$ sudo apt install qt6-base-dev qt6-declarative-dev qt6-multimedia-dev qt6-tools-dev
```

Those packages are the dependency list, and they describe the engine: Lua 5.4, SQLite, readline, OpenSSL, libgit2 for the content the engine fetches, and the Qt 6 modules for the client, the QML runtime, multimedia and the Linguist translation tools. The comment marking which package provides which feature is a good sign, because it is the kind of detail that usually goes undocumented.

The build itself is a standard out-of-source CMake build:

```sh
$ git clone https://github.com/Qsgs-Fans/FreeKill.git
$ cd FreeKill
$ mkdir build && cd build
$ cmake .. && make -j8
```

Arch Linux users can install from the AUR with yay -S freekill, and Mac users also build from source after installing cmake, libgit2, lua, qt, pkgconfig, vulkan-headers and swig with homebrew, then run the binary from the build directory as ./build/FreeKill. The Mac note in the README is that Qt needs the full Xcode, which is the kind of detail that costs an afternoon if you do not know it.

## The alternative is a general purpose rules engine

There is a real alternative to FreeKill, and the difference in approach is about where the work goes.

The alternative is a general purpose board game or card game framework, or writing your own engine, where the framework gives you a data model for cards, players, phases and rules, and the rules of your particular game are yours to write in your language of choice. The engine is generic and the game is the work.

FreeKill takes the opposite position. The framework is not generic: it is a specific engine that already knows how to model the games it ships, how to present them in a QML client, and how to run a lobby and an online session. What you write when you extend it is a game or a character expressed in the framework's own Lua dialect, with the rules of the base game already in place.

The difference in effort is stark. In the generic framework, you implement a whole game, and the online layer is your problem unless the framework has one. In FreeKill, you implement the parts that differ, and the lobby, the reconnection after a dropped connection, and the recording and replay come with the engine, which is exactly the set of features the README says the framework provides for the games built on it.

The trade is the same trade as before, expressed differently. FreeKill's model is powerful if your game resembles the ones it was built for, and awkward if it does not, because you are writing Lua against conventions that were shaped by a particular card game. A generic engine asks more of you up front and constrains you less afterwards.

## Conclusion

FreeKill fits a developer who wants to build an online card or board game and needs the lobby, the reconnect logic and the replay recordings handled for them, and who is willing to write the rules in Lua against the framework's own API. It does not fit a developer who wants a general purpose rules engine to build an original game in an original language, and it does not fit someone who expects to contribute rules to this repository. Before you start, read the repository split described in the README, because the scripts you would want to edit live in freekill-core, and the build needs a full Qt 6 and Lua toolchain on Linux, macOS or FreeBSD.

## FAQ

### What is FreeKill and what is it written in?

FreeKill is an open source board game engine written in Qt and Lua. It uses Lua for a high-performance single-threaded asynchronous server and Qt Quick for the GUI, and it lets you create your own board game or extend one that has already been completed.

### Which platforms does FreeKill support?

It is currently available on Linux, Mac, Windows, Android and FreeBSD. Windows and Android are distributed as packaged builds on the release page, while Linux, BSD and Mac users build from source.

### Where do I edit the Lua scripts for FreeKill?

Not in this repository. All the Lua files of the project, except those under test, are managed by the separate freekill-core repository, and the README asks that you do not modify the Lua files here directly. The scripts in this repo are for use when packaging a release, and the server here is only for single-player games.

### How do I build FreeKill on Linux?

Install the build dependencies, which on Debian are git, gcc, g++, cmake, swig, the Lua, SQLite, readline, OpenSSL and libgit2 development packages and the Qt 6 base, declarative, multimedia and tools packages, then clone the repository, create a build directory, run cmake .. and make -j8. A full guide is linked from the README.

### What licence is FreeKill released under?

GPLv3, with the licence text in the LICENSE file at the root of the repository. The recent releases are v0.5.23 from 2026-09-03, v0.5.24 from 2026-09-04 and v0.5.25 from 2026-09-08.

## Sources

- [License: GPL-3.0](https://github.com/Qsgs-Fans/FreeKill/blob/master/LICENSE)
- [Project website](https://fkbook-all-in-one.readthedocs.io/)
- [Qsgs-Fans/FreeKill on GitHub](https://github.com/Qsgs-Fans/FreeKill)
- [README](https://github.com/Qsgs-Fans/FreeKill/blob/master/README.md)
- [Releases](https://github.com/Qsgs-Fans/FreeKill/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/qsgs-fans-freekill