Skip to content

Building KeeperFX

Jump to bottom Edit New page
rainlizard edited this page Sep 8, 2026 · 32 revisions

Building KeeperFX

If you find any step in this guide unclear, seek out help on the discord.

Choose your platform:

Optional guides:

Prerequisites

Update your game installation to the latest alpha patch. Without the latest files, the game will encounter issues when launching the compiled executable.

Build on Linux

1. Install Required Packages

Open your terminal and run:

sudo apt update
sudo apt install -y build-essential mingw-w64 libpng-dev

Package Notes:

  • mingw-w64 - Pulls in all necessary MinGW tools and compilers
  • libpng-dev - Development headers and libraries (automatically pulls the correct runtime library)
  • Recent Ubuntu versions include MinGW GCC 13+ which is required for KeeperFX

Troubleshooting Compiler Version Issues:

If you encounter compilation errors, check your mingw compiler version:

i686-w64-mingw32-gcc --version

MingW32 provides two separate threading implementations. One implementation uses POSIX threading whereas the other uses native Win32 threading. In order have threading support on Ubuntu versions with GCC 10.x or earlier, MingW32 requires you to manually select one of the two implementations. On such systems the POSIX implementation can be selected as the preferred compiler using the following commands:

sudo update-alternatives --set i686-w64-mingw32-gcc /usr/bin/i686-w64-mingw32-gcc-posix
sudo update-alternatives --set i686-w64-mingw32-g++ /usr/bin/i686-w64-mingw32-g++-posix

2. Clone the Source Code

Navigate to your desired directory and clone the KeeperFX source code:

cd ~
git clone --recursive https://github.com/dkfans/keeperfx.git
cd keeperfx

3. Compile

make all

If you encounter issues:

make clean
make all

The compiled files will be in the /bin/ sub-directory. Copy these files to your KeeperFX game directory.

4. Linux Troubleshooting

  • Common compilation errors:

    • pkg_lang.mk:117: *** target pattern contains no '%'. Stop.

      Various platforms such as Ubuntu will have the environment variable LANGUAGE predefined. As a workaround, prepend LANGUAGE=eng to the make command (eg. LANGUAGE=eng make standard).

  • Missing dependencies: Re-run the package installation commands from step 1
  • Compiler too old: Ensure you're using a recent Ubuntu version with GCC 13+

Build on Windows (WSL Method)

1. Set Up WSL Environment

For New Installations: Open a command prompt as administrator and install WSL:

wsl --install

For Existing WSL Users with Older Environments: If you have an older WSL installation that may not include MinGW 13, it's recommended to create a fresh environment:

  1. Backup any important data from your current WSL environment
  2. Remove the existing distribution: 
    wsl --list
wsl --unregister Ubuntu
  3. Install fresh Ubuntu: 
    wsl --install

2. Install Required Packages

Open your WSL terminal and run:

sudo apt update
sudo apt install -y build-essential mingw-w64 libpng-dev

3. Clone the Source Code

IMPORTANT: Do not use spaces in directory names! This will cause build failures.

Option A: Using Git on Windows Open a Windows command prompt or PowerShell:

cd C:\
mkdir Github
cd Github
git clone --recursive https://github.com/dkfans/keeperfx.git

Option B: Using GitHub Desktop

  • Download and install GitHub Desktop
  • Sign in with your GitHub account
  • Click File -> Clone repository
  • Use URL: https://github.com/dkfans/keeperfx.git
  • Choose a Windows directory like C:\Github\keeperfx (NO SPACES in the path!)

4. Compile

Navigate to your cloned repository:

cd C:\Github\keeperfx

Then compile:

wsl make all

If you encounter issues:

wsl make clean
wsl make all

5. Transfer Files and Run

Copy the compiled files from /bin/ to your KeeperFX game directory and run keeperfx.exe.

6. Windows Troubleshooting

File Permission Errors: The "Cannot utime" and "Cannot change mode" errors are common with WSL and Windows filesystems. These are usually harmless warnings, but if they cause build failures:

  1. Avoid spaces in directory names - Use C:\Github\keeperfx instead of C:\Github\keeperfx code

WSL Performance Notes:

Your compile speed depends on the directory you installed the source code to and your WSL version. To check your current WSL version, enter wsl --list --verbose into a command prompt. You can set your WSL version with: wsl --set-version <NameOfDistribution> <Version>

WSL1 WSL2
Windows directory
C:\Github\keeperfx\ 		Fast Slow
\\wsl$ directory
/home/username/keeperfx/ 		Slow Fast

Recommended setup: WSL1 with source code in a Windows directory. If VSCode prompts you about upgrading to WSL2, you can ignore it and click Don't show again - WSL2 can massively slow things down if used incorrectly.

Common Issues:

  • SPACES IN PATHS: Never use spaces in directory names - this will cause build failures
  • Permission errors: Don't install your game in Program Files directories
  • Compilation errors: Try the WSL reset method described in step 1
  • Path issues: Ensure you're using the correct path format for your WSL version

Using Visual Studio Code (Optional)

Visual Studio Code provides an excellent development environment for KeeperFX, but it's not required for building the project.

1. Install Visual Studio Code

Download and install Visual Studio Code.

Windows users: Optionally install the Windows SDK to reduce linter warnings (not required for compilation).

2. Set Up the Project

For Windows/WSL users:

  1. Open VSCode
  2. Click File -> Open Folder and select your keeperfx directory
  3. Press F5 and select your Dungeon Keeper game directory when prompted
  4. VSCode creates a junction at .vscode/game and uses it as the launch and copy destination

For Linux users:

  1. Open VSCode
  2. Click File -> Open Folder and select your keeperfx directory
  3. Press F5 and enter your Dungeon Keeper game directory in the terminal when prompted
  4. VSCode creates a symbolic link at .vscode/game and uses it as the launch and copy destination

The first build also creates .vscode/compile_settings.cfg with a debug build and automatic parallel compilation enabled.

3. Install Recommended Extensions

In VSCode, click the Extensions tab (located on the left side), search for @recommended, and install all recommended extensions.

4. Configure Launch Settings

The launch configuration is stored under "launch" in .vscode/settings.json. Modify its "args" array to set the startup map, campaign or other command-line options. The "program" and "cwd" fields already use the .vscode/game link and normally should not be changed.

Press Ctrl+Shift+B to run the Configure build task and select a debug mode. This updates .vscode/compile_settings.cfg; it does not compile the game. You can also edit that file to set MAKE_JOBS to a specific number of jobs or set HEAVYLOG=1.

5. Compile and Debug

Compile:

  • Press F5 on Windows or Linux to compile, copy the files to .vscode/game and launch the game under the debugger
  • To compile and copy without launching, run the Compile, Copy Files task from Terminal -> Run Task

Debugging:

  • Windows: After a crash, the executable will freeze for debugging and you'll need to press Shift+F5 or hit F5 twice to exit the game
  • When a crash occurs, you might see an error like function () at src/main.cpp:3386 where 3386 is the line number where the crash happened
  • If line details aren't provided, type -exec bt in the debug console to help trace the cause of the crash

6. VSCode File Management

.vscode/settings.json, the build tasks and their scripts are tracked project files. The generated .vscode/game link and .vscode/compile_settings.cfg are ignored by Git. Delete the game link to select a different game directory on the next build, or delete the compile settings file to restore its defaults on the next build.

Development Tips

Faster Development

Use the -skipheartzoom launch argument to skip the introductory zoom to the player's Dungeon Heart when a level starts.

Quick Exit

Press Alt+F4 to instantly close the game.

Compilation Speed

  • Initial compilation takes longer
  • Subsequent builds reuse dependency information, cached objects and precompiled headers
  • Standard and heavy-log builds have separate object files, so switching between them does not require a clean build

Debugging and Logging

Using Log Functions

Use JUSTLOG() to write values to keeperfx.log. See globals.h for other logging functions.

Examples:

// Print integer
JUSTLOG("%d", name_of_variable);

// Print float  
JUSTLOG("%f", name_of_variable);

// Print string
JUSTLOG("%s", name_of_variable);

// Print after 2 seconds (20 turns per second)
if (get_gameturn() == 40) {
    JUSTLOG("%d", name_of_variable);
}

Monitoring Logs

In-game: Press ~ to view keeperfx.log in real-time

Linux terminal:

tail -f keeperfx.log

Windows PowerShell:

Get-Content keeperfx.log -Wait

Make Commands Reference

Command Description
make all Build the standard executable and report the elapsed build time
make standard Build bin/keeperfx.exe
make heavylog Build bin/keeperfx_hvlog.exe with extensive logging
make clean-build Remove game build outputs while keeping tools, dependencies and packages
make clean Remove game outputs, tools, external libraries and package outputs
make package Compress binaries into 7z archive
make pkg-languages Generate text strings from translations
make pkg-gfx Generate all graphics files from PNGs
make pkg-landviews Generate landview graphics only
make pkg-menugfx Generate menu graphics only
make pkg-enginegfx Generate engine graphics only
make pkg-sfx* Generate sound files from waves

*pkg-sfx currently doesn't work with WSL - requires MinGW with MSYS.

Known Issues and Solutions

MinGW Version Compatibility

  • GCC 10.x errors: Use GCC 13+ (included in recent Ubuntu versions)
  • Missing _Static_assert: Compiler too old, upgrade environment
  • Header file issues: Usually indicates version mismatch

Common Errors

  • target pattern contains no '%': Comment out problematic line in pkg_lang.mk
  • stdlib.h: No such file: Broken MinGW installation, reinstall packages
  • Permission errors: Move game out of Program Files directories

For any other issues, ask on the discord.

Add a custom footer

Wiki overview

Getting Started

Playing

Mapmaking

Developers

Clone this wiki locally