Creating a mod

What is a mod

A finished mod is a folder, placed in the Mods/ folder, containing the following files:

• Mods/mod_name/Mod.manifest
• Mods/mod_name/Mod.cfg
• Mods/mod_name/modding_eula.txt
• Any number of .pak files

To create a new mod, use the Modding tool in Sandbox editor. Alternatively you can create the folder by hand (you can find a copy of modding_eula.txt in the modding tools pack. All mods must include the eula).

Then you can create your mod by placing new files in the Data folder, thereby replacing the original files in the game folder. For most files, you must replace the entire file, even if you only want to change a single line. When you have all the files you need in the Data folder, you can use the editor tool to pack all of them into a single PAK file, which will be placed in your mod folder. Once you do this, the game will start using your files.

The database is, in the end, exported as XML files in the Data folder, and you could use the above method for replacing files to replace one of these XML files. However, that would make your mod incompatible with any mod that changes the same file. Instead, you can use the editor tool to export only the differences between the original tables and your new tables, ensuring compatibility with any other mod. The editor tool can create these difference files and place them in a new PAK file, alongside the PAK for modified files. As before, once you create this PAK file, the game will start using your modifications to the database.

During the development of your mod, you will probably export the mod several times. The editor uses local changes, so you can partially test your mod’s functionality, but you are going to need to test it in the game as well. The game ignores your SQL database and your local files, and only uses PAKs in Data/ and Mods/mod_name/ folders. This behaviour can be overridden with sys_PakPriority cvar, but it is not recommended to do that. If your game only runs from PAKs, and you never modify the original PAKs (which you shouldn't), then by running the game you are testing the “public” version of the mod. In other words, you are testing the exact same game state that any user of your mod will have.

After you are satisfied with your mod, you can simply just pack the entire mod folder into a single archive and distribute it.

Exporting level

Warning – exporting level is not supported by modding tools, you might have to figure some stuff out by yourself. This guide is here to give you a fighting chance

Level defines all entities that are in game world, like NPCs, structures, items lying on ground, etc... The game uses a different format of the level than the editor, so for any changes to manifest in the game, you must export the level (The level is divided into many “layers”, which allow multiple people to work at the same level at the same time. To save on loading time, they are all merged into a single file on export.) Use the following command to start the export (you will need to close editor first):

Editor.exe -useHDDForILAO -useILAOFolder AOData_builder -unattended +r_BreakOnError 0 -noSourceControl -exportTexture -layerExportProfile Game -export Data\Levels\rataje\rataje.cry

Be warned, this process will take up to several hours. It will create level.pak, which will replace the level.pak provided by us (so you might want to back that one up before running the command). You can move this level.pak to your_mod_folder/Data/Levels/rataje/level.pak, and then the game will load it in place of the original level.pak. Notice that only one mod at a time can replace the level.pak, so for more mods to work, you would have to use some 3rd party merging software.

Mod.manifest

Manifest file describes the mod and informs the game about some specific requirements. It is technically optional, but it’s strongly recommended to include one. The format is following:

<?xml version="1.0" encoding="utf-8"?>
<kcd_mod>
  <info>
    <name>Name of mod -- can be different from mod folder name</name>
    <description>Some text</description>
    <author>Your name</author>
    <version>Version of the mod -- string</version>
    <created_on>some date -- string</created_on>
    <modid>name_of_mod_in_standard_format-lowercase_only</modid>
    <modifies_level>false</modifies_level>
  </info>
  <supports>
    <kcd_version>1.2</kcd_version>
    <kcd_version>1.3</kcd_version>
    ...
  </supports>
</kcd_mod>

Many of the tags are optional, however several have a meaning:

• modid defines a “standardized” name of the mod. Whenever the code uses mod name, it uses this version. If modid tag is not present, then a standardized name is created from the mod name. If the mod name is also not present, than it is generated from folder name.
  • modid is used, for example, by table diff engine. Table diffs have the modid as a suffix, and therefore won’t work, if the modid changes (for example, if you specify neither modid nor mod name, and the user changes folder name when they install the mod)
• modifies_level marks that this mod changes something in level.pak. If at least one mod modifies level, a new “newgame save” is generated when the game starts
• supports specifies versions of KCD which this mod supports. Generally it is a good idea to specify only those versions you have tested the mod with. If omitted, mod is considered to support all versions of KCD