Dwarf Fortress Modding Guide (version 50.01+)

Dwarf Fortress supports mods in the form of new objects and tiles. Each mod is a zip file or unzipped folder with the required format (see below.)

Using Mods

Mods are installed when you create a new world. If you subscribe to a mod on Steam Workshop, it should be available when creating a new world automatically. If you aren't using Steam, you can install mods manually by putting the mod zip or the unzipped mod folder inside the "mods" folder (if this folder doesn't exist, you can create it.)

When creating a world and choosing its initial parameters, if you have a mod available, there should be a Mods button at the bottom of the screen. Pressing this will let you select which mods you'd like to install and what the load order should be. You should put mods at the end of the mod list after the vanilla objects if you don't have any further information, so that they can reference vanilla objects after those are loaded.

Unlike the previous versions of Dwarf Fortress, mods no longer live inside save files and must be installed on every computer where saves using those mods are going to be loaded.

Mod Format and Updating Mods from Old Versions

Mods contain an info.txt file and either an "objects" folder or a "graphics" folder (or both.) All of the vanilla objects in the game now use this format.

Here is an example: Vanilla Items

You can see that the info.txt just has a few fields defining basic information about the mod, and the objects folder contains objects exactly the same as objects from previous versions of Dwarf Fortress. It's beyond the scope of this short guide to go into what specific tags do, but the vanilla objects and previous mods by members of the community will give you plenty of examples to work with.

Uploading Mods to Steam Workshop

To upload a mod to Steam Workshop, you need to make some additions to the info.txt file (see next paragraph.) Afterward, you put the unzipped mod folder in the "mods/mod_upload" folder. Then select Mods from the title menu, and upload your mods using the button you'll see there. Other Steam users will be able to subscribe to your mod immediately once it is uploaded.

Example info.txt additions for Steam Workshop:

[STEAM_TITLE:Test Descriptors]
[STEAM_DESCRIPTION:Some test object definitions for shapes and colors.]
[STEAM_TAG:mod] <-- as many as you want, use a separate STEAM_TAG for each one
[STEAM_KEY_VALUE_TAG:test:stuff] <-- as many as you want, similarly
[STEAM_METADATA:metadata test]
[STEAM_CHANGELOG:made some changes]

Once the upload process is completed successfully, you'll find a [STEAM_FILE_ID:#########] appended to your info.txt. Make sure this entry is included for future uploads if you want to make changes to your mod and have it overwrite the existing entry on the workshop. Otherwise you'll create a new entry every time you upload.