Xonotic: a fast arena shooter whose GitHub repo is a build superproject

The GitHub copy is a mirror, and the real work happens on GitLab

The repository description says it plainly: this is a mirror of the GitLab superproject, and the superproject contains build scripts and tools to download other repositories and assets. The README repeats the point in bold and adds that the repositories on GitHub are mirrors of GitLab's unless specified otherwise. That single sentence reframes the project. When you look at the top level of the tree here, you see a `data/` directory, a `server/` directory, a `Makefile`, a `CMakeLists.txt`, a `release.cmake`, and shell scripts for the SDL client and the dedicated server, but not the full game. The superproject is the recipe: it knows where the other repositories live and how to fetch them. The README also points at xonotic-data.pk3dir as the place where most development takes place, which is a separate repository from the one holding the engine build.

The Makefile is where the two engines and the two binaries are wired together

The top-level Makefile is the part of the superproject that does the real work, and its variables explain the shape of the build:

DPSRC = source/darkplaces
D0SRC = source/d0_blind_id
CLIENTBIN ?= xonotic-sdl
SERVERBIN ?= xonotic-dedicated

# CC and MAKEFLAGS are always set so ?= has no effect, therefore
# we use CFLAGS to set default optimisations which users may override
CFLAGS ?= -march=native -mtune=native
CFLAGS += -flto=auto
# user can override this with make -j
MAKEFLAGS := -j$(shell nproc)
# DP makefile overrides CFLAGS (exporting CFLAGS does work for d0_blind_id but so does this)
export CC += $(CFLAGS)

Two source trees are involved. `DPSRC` is the DarkPlaces engine, which is the game engine itself, and `D0SRC` is the d0_blind_id component. Two binaries come out of it, `xonotic-sdl` for the player and `xonotic-dedicated` for the server, and the Makefile's help target notes that these will be preferred by the xonotic-linux-sdl.sh and xonotic-linux-dedicated.sh scripts, which are used to play with the SDL client or host a dedicated server respectively. The optimisation defaults are aggressive: `CFLAGS ?= -march=native -mtune=native` builds for the CPU you are on, and `-flto=auto` turns on link-time optimisation. Parallelism is handled by `MAKEFLAGS := -j$(shell nproc)`, with a comment noting the user can override this with `make -j`.

Cleaning the build has its own targets

The help text lists the maintenance targets, and the first two are the ones you will use most:

	@echo   "  make clean-sources         Delete build objects"
	@echo   "  make clean                 Delete engine builds and build objects"

`make clean-sources` deletes build objects, and `make clean` deletes engine builds as well as build objects, which is the difference between a fast rebuild and a full one. The distinction exists because the engine and the game code change at different rates, and most contributors are editing assets rather than the engine. The same help output also documents `make update-stable` to update to the latest stable release via rsync, and `make update-beta`, which points at the autobuild system. The help target ends with a warning that moving files outside of the directory isn't officially supported, since it is incompatible with the included updater and the working directory may be incorrect, and suggests calling the scripts from elsewhere via symlinks or .desktop files instead.

Getting the source is lighter from a release tarball than from a clone

The README offers two paths and recommends the lighter one for most people. Stable releases and related info are available from the download page at xonotic.org/download/, and beta builds are published through the autobuild system. The source code included in stable releases and autobuilds can be compiled as described on the wiki, and the README is explicit that this is much lighter than a full git clone. The reason follows from the superproject structure: a clone of the mirror repository does not contain the game data or the other repositories, so the build has to fetch them anyway, whereas a release tarball arrives with the sources already assembled. For a developer who wants to compile the latest revision from git, the README points to the Repository Access guide, and the directory structure is documented separately on the Git wiki. Two more build systems sit alongside the Makefile: `default.nix` and `derivation.nix` with `nix-build.sh` for a Nix build, and a `release.nix` for release artefacts.

The game itself is an arena shooter built on the DarkPlaces engine

Xonotic describes itself as an addictive, arena-style first person shooter with crisp movement and a wide array of weapons, combining intuitive mechanics with in-your-face action. The engine is DarkPlaces, and the lineage is visible in the repository topics, which name the Quake and Quake III family, DarkPlaces, Nexuiz and the AFPS and CPMA game modes. The engine choice is what makes the movement model what it is. The README offers a short introduction as a two-minute video, and points to Halogene's Newbie Guide for gameplay and client configuration advice, and to the Frequently Asked Questions for common tech support topics. There is also a web interface for browsing the console features, a Command Alias and Cvar Search at xonotic.org/tools/cacs/, and Doxygen-generated documentation for discovering details and dependencies in the code.

Contributing has house rules about testing and about official-looking things

The contributing section is specific about what help is wanted, and the list is more informative than a generic call for contributors. Translations are handled through Transifex, modelling and texturing has its own issue label in the assets repository, and documentation is called out with a candid description of the current state, since some of it is still scattered in Docs instead of on the wiki, some wiki pages are slightly out of date or contain links to empty pages, and fixing typos everywhere is described as mattering because attention to detail makes a good impression on potential players. The testing note contains the single most useful technical fact for anyone modifying the game: when playing online, the server's version of the gamecode is downloaded and used by all clients, so you have to play offline or run your own server for testing. The PR guidance adds a social rule, which is that you should not create anything that looks official, such as social media accounts or entries on pages like Steam, without contacting the project first. The README also asks that you read CONTRIBUTING.md before pushing commits or opening merge requests.

Where Xonotic is the wrong choice

Three limits are worth naming. The first is for players rather than developers. If you want to play, compiling a superproject that pulls several repositories and builds an engine with `-march=native` is not the shortest path, since stable releases and beta builds are published as downloads and the beta autobuild page is linked directly. The second is the mirror problem, and it is a real one for anyone planning to work on the code. The GitHub repository is a mirror of GitLab's, so opening issues and merge requests against GitHub means working against a copy whose history and issue tracker live elsewhere, and the README says as much when it points to the GitLab project page for development activity. The third is licensing ambiguity in the metadata. The README states the game is and will always be free and open source under the copyleft-style GPLv3+ licence, with the COPYING and CONTRIBUTING files for full details, and the repository carries GPL-2 and GPL-3 files, but the repository metadata classifies the licence as a custom one that GitHub cannot classify. Anyone embedding Xonotic code in a proprietary product needs to read COPYING directly rather than trust the badge.

The alternative is the packaged release or an autobuild

The practical alternative to building is downloading, and the difference in approach is between a fixed artefact and a reproducible tree. A stable release tarball gives you the assembled sources that the project published, which compile with the Makefile and the scripts already in place, and the autobuild system gives you a nightly or beta build of the same thing without a local toolchain at all. Building from the superproject yourself is the third option, and it is the one that pays off when you intend to change the game, since it gives you the git history and the ability to patch the engine or the data. The comparison with the wider ecosystem of open source shooters is also worth making, because the reason to choose Xonotic over its relatives is the DarkPlaces movement model and the arena feel the README describes, not the toolchain. If the movement is not the draw, the build complexity buys you nothing.

Editorial conclusion

Xonotic fits a developer or player who wants to compile the game, host a dedicated server, or contribute to a project where the asset pipeline lives in a separate repository. It is the wrong choice if you only want to play, since stable releases and beta builds are published as downloads, and it is the wrong choice for a codebase you intend to fork, since the GitHub copy is a mirror and GitLab is where the history and the issue tracker live. Before you build, read the Repository Access guide the README points to, and check the licensing files, since the README states the game is GPLv3+ while the repository metadata classifies the licence as custom.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. xonotic/xonotic on GitHub