Wiki overview

Getting Started

Playing

Mapmaking

Developers

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

1. Install KeeperFX Alpha
  • Update your game installation to the latest alpha patch. Without the latest files, the game will encounter issues when launching the compiled executable.
2. Install Visual Studio Code
  • Download and install Visual Studio Code, available for both Windows and Linux.
  • (Windows users) Optional: To silence linter complaints and remove red squiggly lines in VSCode, install/reinstall the Windows SDK. It's not required for compilation but provides a cleaner coding environment.
3. Set Up Your WSL Environment

WSL allows you run Linux commands on Windows, essential for compiling KeeperFX on Windows.

  • (Linux users)
    • Skip this step.
  • (Windows users)
    • Install WSL: Open a command prompt and type: wsl --install
4. Install Required Packages

First, let's open a terminal that accepts Linux commands:

  • (Linux users)
    • Option 1: Open your standard Linux terminal.
    • Option 2: Open Visual Studio Code, press Ctrl + ~ to open VSCode's integrated terminal.
  • (Windows users)
    • Option 1: Search for WSL in the Start Menu or type wsl into a command prompt.
    • Option 2: Open Visual Studio Code, press Ctrl + ~ to open VSCode's integrated terminal, then type wsl and press Enter to open the WSL terminal.

Then input these commands into your terminal:

sudo apt update
sudo apt install -y build-essential g++-mingw-w64-i686 libpng16-16
5. Clone the Source Code
  • (Linux users)
    • In a terminal, navigate to your desired directory and clone the KeeperFX source code: 
      cd ~
git clone --recursive https://github.com/dkfans/keeperfx.git
  • (Windows users)
    • Download and install Github Desktop.
    • Open Github Desktop and sign in with your GitHub account.
    • Click File -> Clone repository.
    • Click the URL tab, then paste the KeeperFX repository URL: https://github.com/dkfans/keeperfx.git
    • Choose a path where you want to download the source code, then click "Clone".
6. Open the Project in VSCode

Click on File -> Open Folder and select the keeperfx directory that was created when you cloned the KeeperFX source code.

  • (Windows users)
    • When first opening the project in VSCode, you'll be prompted to select your game's keeperfx.exe executable file. Do this and a launch.json file will be created in the /.vscode/ folder.
    • In VSCode's 'Explorer' tab, navigate to /.vscode/ and open launch.json.
    • Inside the launch.json file you can modify the "args" section to set the map and campaign/mappack you wish to load immediately upon game launch. The "cwd" field is your game directory where the compiled executable will be copied to.
  • (Linux users)
    • When first opening the project in VSCode, a linuxscript.sh file will be automatically created in the /.vscode/ folder.
    • Open linuxscript.sh and update the game_directory path to your KeeperFX game installation.
    • Then modify the game_arguments section to set the map and campaign/mappack you wish to load immediately upon game launch.

Click on the 'Extensions' tab (located on the left side), search for @recommended and install all recommended extensions.

Regarding settings.json, launch.json and linuxscript.sh, if you ever need to revert these files to their defaults, you can delete them from your /.vscode/ folder, then restart VSCode and they'll be recreated from the templates. Git won't track any modifications to files inside of /.vscode/.

7. Compile
  • (Windows users)
    • In VSCode, compile the game by pressing F5
  • (Linux users)
    • In VSCode, compile the game by pressing Ctrl+Shift+B

If an error occurs, follow its instructions or seek help. Once compiled, the new executable will be automatically copied to your game directory, and the game will launch automatically.

Tips

  • Compilation time: Your initial compile might take a while, but subsequent compiles will be very fast. Note that changes to header files (.h/.hpp) can cause longer compile times.
  • Faster development: In keeperfx.cfg, set DISABLE_SPLASH_SCREENS=TRUE and SKIP_HEART_ZOOM=TRUE
  • Quick exit: Press Alt+F4 to instantly close the game.
  • Debugging:
    • (Windows) After a crash, the executable will freeze for debugging and in VSCode you'll need to press Shift+F5 or hit F5 twice in order to exit the game.
    • When a crash occurs, you might see an error like function () at src/main.cpp:3386. Here, 3386 is the line number where the crash happened. If this detail isn't provided, type: -exec bt in the debug console to help trace the cause of the crash.

Compiling Manually

To compile manually instead of using the VSCode build task, follow these steps:

1. Compile the Source Code

Open a terminal (refer to step 4) and navigate to the source code directory, if you're using VSCode's terminal then it'll be there by default. Then:

  • (Linux Users)
    • Type make all to compile. For a faster compile, use make -j8 all
    • If you have any problems then try running make clean first.
  • (Windows Users)
    • Type wsl make all to compile. For a faster compile, use wsl make -j8 all
    • If you have any problems then try running wsl make clean first.

Once the compilation is complete, the compiled files will be in the /bin/ sub-directory.

2. Transfer Compiled Files to Your Game Directory

  • In the 'Explorer' tab of VSCode, locate the /bin/ sub-directory. Right-click on it and select "Reveal in Explorer" to view the compiled files.

  • Copy the files from /bin/ and paste them into your game directory, replacing existing files. Or use the terminal to copy them.

3. Start the Game
  • Go to your game directory and double-click keeperfx.exe. Alternatively, set up a game shortcut with launch arguments, or use the terminal.

Printing variables

1. Log Function

  • Use the JUSTLOG() function to write values to the keeperfx.log file. You can find a list of other logging functions inside globals.h

    • To print an integer variable:
    JUSTLOG("%d", name_of_variable);
    • To print a float variable:
    JUSTLOG("%f", name_of_variable);
    • To print a string variable:
    JUSTLOG("%s", name_of_variable);
    • To print a value after 2 seconds (given that DK operates at 20 turns per second):
    if (get_gameturn() == 40) {
    JUSTLOG("%d", name_of_variable);
}
2. Monitoring the Log File

  • Your three options are:

    • Press ~ to view keeperfx.log in-game and display new entries in real-time
    • Open keeperfx.log in a text editor, this will be a static view
    • Or monitor the log file in a separate console window, as detailed below:

  • (Linux Users) Open a terminal, navigate to your DK directory, and use:

tail -f keeperfx.log
  • (Windows Users) Open PowerShell, navigate to your DK directory, and use:
Get-Content keeperfx.log -Wait
List of 'make' Commands
Command Description
standard Build binaries for 'standard release' of KeeperFX
heavylog Build binaries for 'heavylog release' of KeeperFX
clean Removes files created during previous builds
all Cleans if necessary, then runs standard
package Compress binaries and other files into 7z archive
pkg-languages Generate text strings DAT files from PO/POT translation sources
pkg-gfx Generate all graphics DAT/TAB/RAW/PAL files from PNG bitmaps
pkg-landviews Generate only landview graphics
pkg-menugfx Generate only menu graphics
pkg-enginegfx Generate only engine graphics
pkg-sfx* Generate sound DAT files from wave files.

*This command currently does not work with WSL. You need MinGW with MSYS for it.

WSL1 vs WSL2

On Windows, 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, which will also list the name of your distribution. You can set your WSL version with: wsl --set-version <NameOfDistribution> <Version>

Whether you should use WSL1 or WSL2 depends on the location you've installed your source code:

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

So with that in mind, your two options are:

  • Be on WSL1 with source code installed in a Windows directory
  • Be on WSL2 with source code installed in the \\wsl$ directory

But because the second option is much more complex to set up and slows down Github Desktop, we recommend staying on WSL1 with the source code in a Windows directory. If VSCode ever 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.

If you still want to try WSL2, you will have to:

  • Use the git clone command (see step 5) while in a WSL terminal (not a normal command prompt).
  • Install the VSCode WSL extension. Click the blue icon in the bottom left corner to "Open a Remote Window" to enter WSL Mode.
  • Click File -> Open Folder and navigate through the WSL filesystem until you find keeperfx and open the project.
  • Edit the game directory path to use Linux formatting like so: /mnt/d/Games/DungeonKeeper/

Linux troubleshooting

  • Compilation errors: If you encounter the error: pkg_lang.mk:117: *** target pattern contains no '%'. Stop. during compilation on Ubuntu, edit the pkg_lang.mk file and comment out line 117 or whatever the specific line is. Note: This might be a rare problem.

Windows troubleshooting

  • Permission issues: If your game directory is in C:\Program Files\ or C:\Program Files (x86)\, you might get permission errors during compilation. To solve this, move your DK game folder elsewhere. Note: you'll then need to update launch.json with your new directories.

  • WSL issues: Resetting WSL can potentially help with some difficult compilation errors:

    • Open a command prompt and list distributions: wsl --list
    • Uninstall the distribution: wsl --unregister distroName (replace 'distroName' with your listed distribution's name)
    • Install Ubuntu: wsl --install -d Ubuntu
    • Install Required Packages again with step 4

For any other issues, ask on the discord.