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

Choose your platform:

• Building on Linux - Native Linux development
• Building on Windows - Using WSL (Windows Subsystem for Linux)

Optional tools and guides:

• Using Visual Studio Code - IDE setup (optional but recommended)
• Development Tips - Faster builds and shortcuts
• Debugging and Logging - Debug tools and logging
• Make Commands Reference - Complete list of build commands
• Troubleshooting - Common issues and solutions

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

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

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

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

Quick Method:

make all

Faster compilation (parallel build):

make -j8 all

If you encounter issues:

make clean
make -j8 all

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

• 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+

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

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

Open your WSL terminal and run:

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

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!)

Navigate to your cloned repository and compile:

cd C:\Github\keeperfx
wsl make all

For faster compilation:

wsl make -j8 all

If you encounter issues:

wsl make clean
wsl make -j8 all

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

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>

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

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

Download and install Visual Studio Code.

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

For Windows/WSL users:

1. Open VSCode
2. Click File -> Open Folder and select your keeperfx directory
3. When prompted, select your game's keeperfx.exe executable
4. A launch.json file will be created in /.vscode/
5. Navigate to /.vscode/ in VSCode's Explorer tab and open launch.json
6. Modify the "args" section to set the map and campaign/mappack you wish to load immediately upon game launch
7. The "cwd" field is your game directory where the compiled executable will be copied to

For Linux users:

1. Open VSCode
2. Click File -> Open Folder and select your keeperfx directory
3. A linuxscript.sh file will be created in /.vscode/
4. Open linuxscript.sh and update the game_directory path to your KeeperFX game installation
5. Modify the game_arguments section to set the map and campaign/mappack you wish to load immediately upon game launch

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

Windows (launch.json):

• Modify the "args" section to set startup map/campaign
• Set "cwd" to your game directory path

Linux (linuxscript.sh):

• Update game_directory to your KeeperFX installation path
• Modify game_arguments for startup options

Compile:

• Windows: Press F5
• Linux: Press Ctrl+Shift+B

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

The files settings.json, launch.json, and linuxscript.sh in /.vscode/ can be deleted to reset to defaults - they'll be recreated from templates when you restart VSCode. Git won't track any modifications to files inside /.vscode/.

In keeperfx.cfg, set:

DISABLE_SPLASH_SCREENS=TRUE
SKIP_HEART_ZOOM=TRUE

Press Alt+F4 to instantly close the game.

• Initial compilation takes longer
• Subsequent builds are much faster
• Header file changes (.h/.hpp) can slow compilation

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);
}

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

Linux terminal:

tail -f keeperfx.log

Windows PowerShell:

Get-Content keeperfx.log -Wait

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

• 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

• 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.