Adding or using Custom images

Introduction

It's possible for users to add custom images to KeeperFX, which could be used instead of icons, cursors and the like.

Overview

Dungeon Keeper and KeeperFX use images from .dat files for all things in game. For sprites, see here.

The custom images do not need to be merged into these .dat files, but can be bundled in .zip files, along with a json file that describe which png files are available and under what name.

Creating a Custom Image

You can make images in any image editing software, like Paint, Photoshop or GIMP. It is smart that when you replace an image with a custom one, you replace it with one of the same size.

KeeperFX has a limited color palette. The game will automatically convert colors in the custom PNG files to the nearest one in the palette, but to get a reliable result you could use the palette when creating your image. To import the DK palette into GIMP, use this file.

Keep in mind that KeeperFX can be played in high res (480p and above) mode and low res(200p) mode. In low res mode, smaller sprites are selected, so consider making images in both sizes. Some images also have an 'enabled' and 'disabled' variant, so make a greyscale version of your image in those cases too.

A smart approach would be to use the regular KeeperFX source images as a basis for your custom ones. They are included in the KeeperFX GFX Source Data.

Creating the JSON file

A JSON file called 'icons.json' needs to be created to allow the game to use the images. A json file can be made with any text editor, but using an application that can validate them is recommended, as it's easy to miss a bracket or comma and have the entire file not work.

Enter all the filenames of the images, following this format:

[// opening square bracket, for the entire file, needs closing up.
    {// opening curly bracket for each sprite you put in the zip. A comma after each one except the final one.
        "name": "FLAME_CURSOR", //The name given here will be used to assign the image. May only use capitals.
        "file": ["flame_cursor.png" ] //The exact image file name as included in the .zip file, this is the file you'll see ingame. Note the straight brackets.
    },
    {
        "name": "ARROW_ICON_MEDIUM",
        "file": ["arrow_icon_medium.png", "arrow_icon_medium_grey.png" ] //Some images use multiple variations, like an enabled and disabled one. Add them all with a comma in between.
    }
]

The json file gets zipped in with the image files, and now the image file is ready to be used.

Using Custom Images on a Map

When using custom images, first be sure they are installed properly. To use them game wide, create a mod folder such as /mods/my_custom_images/fxdata/, place the zip file there, then add my_custom_images to the [after_base] section of /mods/load_order.cfg. If the file is still named _load_order.cfg, rename or copy it to load_order.cfg first.

To use custom images campaign/mappack wide, place the zip file in the CONFIGS_LOCATION folder specified in the campaign/mappack config file. To use them on one map only, name the zip file e.g. map00440.zip and place it with the other files of map 440. It's possible to have both images and sprites in a single zip. When the image is available for KeeperFX, the next step is to configure it to be used in game.

Using the new image

To replace an image in game, either change the configuration files or change it with a level script command.

To change it in the configs, find where it is configured; If you are making a custom trap, a good chance you'll find your icon in 'trapdoor.cfg', but if you are modifying a bile demon, open 'bile_demon.cfg'. The 'creature spells' are called instances and can be found in 'creature.cfg'. Use common sense and a text editor. It is possible to use a map specific config. Changing a Bile Demon for map 440 you would name the file map00440.bile_demon.cfg. Be sure that custom configs only contain those lines that differ from the original game to ensure the map keeps working on future versions of KeeperFX.

For the level script, find the corresponding script command, usually called SET_****_CONFIGURATION, which allows you to overwrite the values from the config files on a er map basis. In either case, replace the number of the original image, with the name of your new icon as defined in the .json file.

Custom lenses and mists

Similar to custom icons, it is also possible to create custom overlays and mists for creature eye lenses.
Lens overlays are specified in a lenses.json file, mists in a mists.json. The format is identical to that of the 'icons.json' file. As for the overlay/mist image, this would be an in-palette png up to 4096*4096 pixels in size. The image will be stretched to the players viewport. To use them, specify the name in lenses.cfg.