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)
- (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)
- (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. - Click on the 'Extensions' tab (located on the left side), search for
@recommended
and install all recommended extensions.
When first opening the project in VSCode, configuration files (settings.json
, launch.json
, or linuxscript.sh
) will be automatically created in the /.vscode/
folder. You can edit these files without git tracking the modifications. To revert them to defaults, delete those files then restart VSCode and they'll be recreated from the templates.
7. Configure the Game Directory
(Windows users)
(Linux users)
Save the file after making changes.
8. 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.
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.