DDNet: a DDRace platformer where the build needs SDL2, ffmpeg, Vulkan and a Rust toolchain

A DDRace server and client built on the Teeworlds codebase

DDNet is described as its own flavor of DDRace, which is a Teeworlds mod. That lineage is the key to understanding the codebase, and it is visible in the repository itself: the topics list teeworlds, and the sources are C++ with Rust components woven in.

What a reader gets is a cooperative platformer game rather than a library, and the deployment picture follows from that. Binary releases are published on the DDNet website, the game is on Steam, and the README also points at a code browser, source code documentation, a building guide, a debugging guide and a contributing guide. Development discussion happens on the #ddnet channel on Quakenet, with a Discord developer channel as the second venue.

Three badges at the top tell you how the project operates. There is a build status badge for the CI workflow, and a code coverage badge from codecov, plus a translation status badge for the Weblate localisation service. A game with community translation, coverage measurement and continuous integration is a project with a real contributor pipeline rather than a hobby fork.

The homepage is ddnet.org, the default branch is master, and the last push to the repository was on 2026-10-22 with the repository not archived. There are no GitHub releases, because the releases are distributed as game builds elsewhere.

Five clone commands, because the dependency history is enormous

The cloning section of the README is longer than any other part of it, and the reason is the bundled libraries. Five variants are given, and the sizes are stated so you can pick one before you start.

With external libraries and no history, the README says about 700 MiB:

git clone --depth 1 --recursive --shallow-submodules https://github.com/ddnet/ddnet

With the libraries already on your system and no history, about 150 MiB:

git clone --depth 1 https://github.com/ddnet/ddnet

With external libraries and full history, about 1 GiB, and the same command with --recursive. With system libraries and full history, about 450 MiB.

The fifth variant exists because the libraries were moved to a separate repository, ddnet-libs:

git clone --shallow-exclude=included-libs https://github.com/ddnet/ddnet

which is about 250 MiB, and if you cloned before that move and need the ddnet-libs history instead, you can pull it in with git submodule update --init --recursive.

For a contributor who only wants to read the code, the 150 MiB clone is the sensible default. For someone who needs to build the official bundles, the recursive clone is the one that matches what the release pipeline uses.

The dependency list is where the platform differences live

On Linux and macOS the README gives a command per distribution, and the list shows what the game actually needs. The Debian and Ubuntu line installs build-essential, cargo, cmake, git, glslang-tools, google-mock, the ffmpeg development libraries, libcurl, freetype, GLEW, libnotify, libogg, opus, opusfile, libpng, SDL2, sqlite3, OpenSSL, Vulkan, wavpack, x264, ninja-build, python3, rustc and spirv-tools.

The Rust requirement has its own escalation path. If your distribution does not ship a new enough rustc, the README points at rustup, which provides rustc 1.85.0 and above, and at a rustup-1.85 package if that is still not enough. On older distributions such as Ubuntu 18.04, the advice is different: do not install google-mock and instead set -DDOWNLOAD_GTEST=ON at build time to get a more recent gtest and gmock.

Equivalent lines follow for CentOS, RedHat and AlmaLinux, Fedora, Arch, Gentoo and Void, and macOS gets a homebrew line covering cmake, ffmpeg, freetype, glew, glslang, googletest, libpng, molten-vk, ninja, opusfile, rust, SDL2, spirv-tools, vulkan-headers, wavpack and x264.

The point of all these lines is that a DDNet build is a full multimedia stack, not a small C++ program. There is one escape hatch: passing -DPREFER_BUNDLED_LIBS=ON to cmake uses the bundled copies instead of the system ones, and the README notes that the bundled set in the ddnet-libs submodule does not contain every dependency anyway, openssl and vulkan among them, and that local development is better off using system packages.

Two CMake commands and a Ninja generator

Compiling on Linux and macOS takes two commands in the source root:

cmake -Bbuild -GNinja

cmake --build build

The generator is Ninja rather than Make, and the build directory is kept out of the source tree. A build directory named build is also what the project uses as a marker: the README says you can install the required libraries on your system, touch CMakeLists.txt, and CMake will use the system-wide libraries by default.

The feature flags follow the same pattern. The building guide referenced from the README explains how to disable features and their dependencies, with -DVULKAN=OFF as the example, which removes the Vulkan requirement entirely for a build that does not need it.

The repository also carries the tooling a project of this size needs: a .clang-format and .clang-tidy, a .clangd configuration for the editor, a ruff.toml for the Python scripts, a .typos.toml, a deny.toml for cargo-deny, a Doxyfile, valgrind and memcheck suppression files, a man/ directory, a Dockerfile, a .gitlab-ci.yml alongside .github/, and scripts/ with a generator for the Rust bridge.

A Cargo workspace living inside a CMake project

The Rust side is not a separate tool. The Cargo.toml at the root of the repository declares a workspace with four members: src/base, src/engine, src/engine/shared and src/rust-bridge/test, using resolver version 2.

The bridge is a C++ to Rust binding built on the cxx crate, pinned to an exact version with cxx = "=1.0.194". The comment above that line is a maintenance instruction rather than trivia: after updating the cxx version you need to run python scripts/generate_rust_bridge.py, which is why the generator script sits in scripts/.

The profiles are tuned for a shipped game rather than for a library. The dev profile sets panic = "abort", the release profile adds thin link time optimisation and also aborts on panic, relwithdebinfo inherits release with debug info on, and there is a minsizerel profile that inherits release with opt-level = "z" for the smallest binary. There is a Cargo.lock at the root, and the repository carries a .cargo/ directory for cargo configuration.

So the build is a hybrid: CMake drives the C++ side and the graphics toolchain, and Cargo drives the Rust side, with the generated bridge code as the seam between them. That is more moving parts than a pure C++ project, and it is also the reason a Rust toolchain of a particular version is a hard requirement rather than an optional extra.

One Docker image builds both the Linux and the Windows binaries

The Dockerfile at the root of the repository exists to build DDNet for Linux and Windows in both 32 bit and 64 bit, and it is driven by two commands that the file itself documents in comments:

docker build -t ddnet - < Dockerfile

docker run -it -v PATH_TO_DDNET:/ddnet:ro -v PATH_TO_OUTPUT_DIRECTORY:/build ddnet ./build-all.sh

The image is Debian 12 with the mingw-w64 cross compilers for x86_64 and i686 in posix variants, the usual build tools, python3, the SDL2, curl, freetype, glew, ogg, opus, png, wavpack and vulkan development packages, the ffmpeg libraries, spirv-tools and cmake. Rust is installed from the rustup script with the stable toolchain, and both the i686-pc-windows-gnu and x86_64-pc-windows-gnu targets are added, which is what makes the Windows cross builds possible from Linux.

Inside the container the script configures a Linux build with cmake and make, then a Windows build that points CMake at the mingw64 toolchain file in the repository's cmake/toolchains directory. The repository is mounted read-only and the output directory is mounted separately, so the container never writes into your checkout.

For a project whose official builds must cover several platforms, having the whole matrix reproducible from one image is the difference between a build day and a build week.

Where DDNet is the wrong tool

The first wrong fit is someone who only wants to play. The official builds are on the DDNet website and the game is on Steam, and neither route needs a compiler, a Rust toolchain or a Vulkan driver. The source is for people who want to change the game or host a server.

The second is a machine that cannot take the dependency list. The multimedia stack is wide, and the failure mode is a long afternoon of chasing packages. The escape hatches exist, -DVULKAN=OFF, -DDOWNLOAD_GTEST=ON and -DPREFER_BUNDLED_LIBS=ON, but each one removes a feature and each still leaves a substantial list.

The third is anyone who expects a small codebase. The repository's own documentation is spread across a code browser, generated source documentation, a wiki development article, four documents in docs/ and the wiki, and the clone size of 150 MiB for a shallow copy without submodules says something about how much history and how much vendored code is attached to it.

The fourth is a licensing assumption. The repository is classified with a custom licence that GitHub cannot categorise, with the terms in the license.txt file at the root, and the README also points to a storage.cfg file that configures where the game looks for its data. Read those files before redistributing anything you build, and this is not legal advice. The honest summary is that DDNet is a long-lived community project with a heavy toolchain, and it rewards people who are prepared to install the stack.

Editorial conclusion

DDNet fits a developer who wants to run or extend a cooperative platformer with its own server, and a contributor who can work through a CMake plus Rust toolchain and a substantial dependency list. It does not fit someone looking for a single binary to play, since the official builds and the Steam version already exist for that, and it does not fit a build environment without Vulkan or ffmpeg unless you disable those features. Before cloning, pick the clone variant that matches whether you want the bundled libraries and the history.

Frequently asked questions

Official sources

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