Custom Configuration files

1. Introduction

KeeperFX has several configuration(config) files that determine how everything works, from which creatures exist, what abilities they have to how fast chickens spawn in your library and what Powers cost for the Keeper. This together is the 'ruleset', and they can easily be edited with a text editor to make either your own game or levels you create to share with others function.

This page explains how to go about modifying the config files.

2. How config files get stacked.

Because there are huge amounts of config files, and KeeperFX is frequently expanded, we do not require each level to be bundled with all possible configurations. Instead the config files are 'stacked'. This means that there are high and low level config files. The lower levels overwrite the settings of the highest levels. The highest level of config files is the KeeperFX defaults, which are the complete and full set of configurations.

One level lower would be config files for a Campaign or Level pack. These configurations do not need to be complete but only hold those files and settings that are different from the defaults.

A level further down is map specific config files. The settings in these will overwrite both the defaults and the campaign/pack specific config files. These are most useful however not for levels shared as 'Free levels', so as not being part of a pack or campaign.

The lowest level is the 'level script', which is part of the level itself. This overwrites all earlier settings, but quickly bloats your script. Use this for small tweaks or things that need to be modified partway through the level.

Example:

---

The default fly, creatrs/fly.cfg holds these attributes:

Armour = 10
Dexterity = 50
Defence = 45
Luck = 15
Strength = 10

You are playing a campaign with a custom fly config campgns/exampl_crtr/fly.cfg

Armour = 20
Strength = 20

The first map of the campaign map specific config campgns/exampl/map00201.fly.cfg:

Dexterity = 25
Strength = 10

A level 1 fly on this map will now have these stats:

Armour = 20
Dexterity = 25
Defence = 45
Luck = 15
Strength = 10

Then somewhere inside campgns/exampl/map00201.txt there is this piece of level script:

IF(PLAYER0,BATTLES_WON > 20)
  SET_CREATURE_CONFIGURATION(FLY,Strength,60)
  SET_CREATURE_CONFIGURATION(FLY,Luck,40)
ENDIF

This means that on this map, after the player has won 20 battles, the flies will now have these stats:

Armour = 20
Dexterity = 25
Defence = 45
Luck = 40
Strength = 60

---

Key is that config files do not contain more information than needed, so that others can easily learn what is different, the files are easy to maintain and changes to KeeperFX over time do not break your maps.

3. Partial configs

This would be a complete bug.cfg file you could include with a campaign. Here a beetle can hold more gold and likes to train. All other configuration settings of the beetle will be taken from the default /creatrs/bug.cfg.

[attributes]
Name = BUG
GoldHold = 2500

[jobs]
PrimaryJobs = TRAIN

This would be a perfectly correct map03241.magic.cfg file, for a map with number 3241 where you want more expensive imps:

[power2]
Name = POWER_IMP
Cost = 600 600 600 600 600 600 600 600 600

The 'Name' field there is not required, but makes the file more readable. There is a tool that makes such files for you found here.

4. Possible files

4.1 Unit configs

Inside the CREATURES_LOCATION folder there are .cfg files for each and every unit (creature or hero) there is. The default CREATURES_LOCATION is the /creatrs/ folder, and there are '_crtr' subfolders in the 'campgns' and 'levels' folders that hold the campaign/pack specific creatures. The file bile_demon.cfg will hold all information there is to know about the Bile Demon, but it is the file 'sorceror.cfg' that is for the Warlock. (Presumably because the name of the creature changed somewhere during development of DK1).

The /creatrs/imp.cfg file holds explanations of all the different creature attributes there are. Lines starting with ; are comments.

Not all unit configs are automatically loaded in. Only those that are listed in the creature.cfg file in the CONFIGS_LOCATION (default: /fxdata/).

[common]
; Creatures used - note that the order is important
Creatures = WIZARD BARBARIAN ARCHER MONK DWARFA KNIGHT AVATAR TUNNELLER WITCH GIANT FAIRY THIEF SAMURAI HORNY SKELETON TROLL DRAGON DEMONSPAWN FLY DARK_MISTRESS SORCEROR BILE_DEMON IMP BUG VAMPIRE SPIDER HELL_HOUND GHOST TENTACLE ORC FLOATING_SPIRIT TIME_MAGE DRUID

If you were to add a new 'Pony' unit, add 'PONY' to the end of that list of the campaign/pack specific creature.cfg file and it will cause 'pony.cfg' to be read by the game. Again, stacked, so both from the default and the campaign/pack CREATURES_LOCATION, as well as the a map#####_pony.cfg file.

Inside you will need to have this:

[attributes]
Name = PONY

That name is the name by which creatures can be added to the game in the script.

Alternatively, the NEW_CREATURE_TYPE script command can be used to ensure a unit config is loaded up by the game.

Do note that new units require custom sprites, unless you make them look identical to bundled units. This is difficult and time consuming work. However, making slight tweaks to existing units is very quick and easy.

4.2 Other config files

Inside the CONFIGS_LOCATION there may be these files:

1. The rules.cfg, it holds all kind of information on how the Dungeon Keeper world functions. What sacrifices come from the temple, that imps get no experience from digging and what the chance is a creature gets converted in the torture room. All information is documented in the file itself.
2. In creature.cfg you can modify which creatures get loaded in the game, some basic information, and most importantly all 'Instances', which is the names of the creature abilities creatures learn when they train and their properties like how often they can be used. These instance names are used in the unit configs. On [instance0] you will find the instance properties explained.
3. Edit magic.cfg to edit or add shots, spells and keeper powers. It's [spell0], [shot0] and [power0] that explain all the configurable attributes of these. Note the 'instance' from creature.cfg launches a spell or shot from this file.
4. The 'trapdoor.cfg` file specifies all the possible traps and doors. Here too it is [trap0] and [door0] which has everything documented.
5. Look in objects.cfg to find all objects that can be placed in game. If you have added a new unit, trap or power this is the place to add the linked lair, crate or spellbook. The [object0] object has the documentation.
6. The 'terrain.cfg' file holds information about all rooms, as well as the different slabs. These are documented on [room1] and [slab0]. To modify slabs and textures you will need to edit slabset.toml, textureanim.toml, columnset.toml and cubes.cfg too. These are not documented yet.
7. In effects.toml there are effect generators, effects and effect elements which can be added and edited. These are the flames, feathers, drips and sparks you will see in the game. Still hardly documented but it is easy enough to work with.

It is also possible to translate individual levels

5. Personal ruleset

If you do not want to make maps to share with others, but instead want to make changes to your own game, it is advised to not modify the default configs. This is because you would be unable to keep your modified config files when you update KeeperFX.

Instead, it is advised to use the /levels/personal_cfgs/ and /levels/personal_crtr/folders. Make them if they do not yet exist. Edit /levels/personal.cfg to activate these folders once you do. Then maps you download from the workshop can be placed into /levels/personal/to play the maps with the changes you made.

Then when you want to play other campaigns with this rule set, edit the specific campaign configs to use these folders too. To modify the original campaign edit /campgns/keeporig.cfg.