This guide is intended to provide official, base level information that will be helpful for you to begin modding Darkest Dungeon. Because of the large volume of potential information involved in any large modding project, we still encourage members of the community to write their own detailed guides using their own tips and tricks.

If you'd like to contribute to this official guide, please contact one of the current guide mods! We'd love to have your help, as long as you understand we require editorial control since this is the official guide.

Good luck with your projects!

--RedHookTyler

HOW TO TURN MODS ON/OFF IN THE GAME:

1. Subscribe to any mods you wish.
   
2. Launch the game
   
3. Start a new campaign or select an existing save slot
   
4. Click on the Mods icon to the right of the save slot
   
5. This will bring up an interface allowing you to toggle which subscribed mods will be active.
   
6. Drag and drop the mods to set their order of priority.
   
7. Mods at the top of the list take priority. That is, the mods at the bottom will be applied first.
   This is important because if multiple mods affect the same file(s), the mods at the top of the list will be the changes that remain final.

While this guide is extensive, we expect others to create more elaborate guides on specific aspects of the game and how to mod them. It can be difficult to understand mechanics or concepts the first time you're shown them, and we've set up a modding group specifically to bring modders and their ideas together in a centralized area.

We welcome and encourage you to join the Darkest Dungeon - Workshop Group to discuss ideas, report issues, or seek help from people experienced in a certain subject!

Most of Darkest Dungeon's files can be edited in any text editor, though below we'll highlight some of the recommended software that can be used. Please note that, of this list, only Spine2D is absolutely necessary for skeleton editing or creation. All other programs are recommended, but not necessary.

Your best bet with any non-image file (.darkest, .json, .xml, etc...) is to simply attempt to open it in a text editor. A fantastic editor is Notepad++ due to its versatility, functionality, and availability. You'll have access to many unique and helpful features, and all for free.

Get Notepad++ here: https://notepad-plus-plus.org/

Darkest Dungeon uses Spine to create skeletons and animations for characters. Without Spine you will be unable to make new animations for characters or enemies. Because Spine is a paid program it can be a difficult entry fee into the creation of unique animations, but it's a full-featured editor whose possibilities far exceed what is required for Darkest Dungeon.

The 'Professional' version of Spine is required to attach meshes to bones
Get Spine here: http://esotericsoftware.com/

In addition, it is ABSOLUTELY NECESSARY that you use version 2.1.27 for DD.
“Make sure that you set Spine’s version to 2.1.27 before you export, otherwise our binary reader won’t read your .skel file correctly (that might be cause of the error). You can leave the Atlas export settings to default, except change the following: “Max width” and “Max height” should be set to 4096, and “Power of two” should be OFF.”

Perhaps the most featureful and powerful photo editor is one of the best ways you can jump into editing or creating art assets for Darkest Dungeon. Though not free, Photoshop can be subscribed to on a month-to-month plan for cheaper than ever before.

Get Photoshop here: http://www.adobe.com/products/photoshop.html

Gimp is a free alternative to Photoshop and, while not as featureful, it is still incredibly powerful! You will be able to manipulate or create assets just as easily, and we recommend you use whichever photo editor suits your needs!

Get Gimp here: https://www.gimp.org/

Assets in Darkest Dungeon need to be exported with transparency settings. 'Gimp' does this automatically, but for Photoshop we recommend the 'SuperPNG' plugin. Additionally, two programs can be used to trim the masks from PNG files and to remove the alpha colour layer.

To use these two programs, drag and drop your PNG file onto each of the exe files. Though no dialogue will appear, they will have done their job. Check below for the links!

Get SuperPNG here: http://www.fnordware.com/superpng/
Trim Mask Program: Download[www.dropbox.com]
Alpha Layer Remover: Download[www.dropbox.com]

This is a list of general parts/mechanics that can be modded. More specific info on areas of the game can be found in their respective guide section.

• Heroes
  
  • Heroes are very moddable currently. It is very possible to create completely new classes with their own artwork, animations, and skills.
• Buffs & Effects
  
  • Most buffs and effects are available to tinker with. Only a small handful of effects are hardcoded and inaccessible by modders.
• Supplies & Provisions
  
  • Many current supply effects are hardcoded, but new ones can be added with general ease. Limiting supply items to certain classes or scenarios is currently not possible.
• Monsters
  
  • New and existing monsters can be added or modded.
• Locations
  
  • New locations cannot be added in, but existing ones can be modified.
• AI
  
  • All AI can be modded, but new AI mechanics cannot be added.
• Curios
  
  • Curios can be modded or added, but are very limited in potential.
• Trinkets
  
  • All trinkets are available to mod, and new ones can be added quite easily.
• Quirks
  
  • All quirks are available to mod or add!
• Afflictions/Virtues
  
  • New and existing afflictions/virtues can be modded.
• Loot
  
  • Loot tables can be added and modified with ease.
• Quest & Dungeon Generation
  
  • Dungeon generation is largely controlled by a few variables linked to hardcoded parameters, but quest generation is a tad more available to mod.
• Town Events
  
  • New and existing town events are easily moddable, though you will have to work with existing mechanics, as new ones cannot be added.
• Audio
  
  • Audio can be modded, but is quite time consuming and difficult for users looking to modify large amounts.

Making a mod for DD is actually pretty simple in concept. (It's the execution that always matters.)

All of the moddable files in the game are contained in this location of Darkest Dungeon's installation:
To create a mod, simply follow the relative file structure that you see in the above folder and edit whatever files you wish. For example, I could create a mod by creating a directory somewhere on my hard-drive called and then place any files in there that I wish to change relative to the main game.

So if I wanted to edit the leper's stats, I would copy over to
When I upload the mod to Steam Workshop (see elsewhere in this guide), that relative file structure and organization will be retained. When a user subscribes to your mod and turns it on, the appropriate files will be overwritten at run-time when they load that campaign.

To test your mods, of course, you'll need to keep the files in the actual directory of the game while you run it. You can also make a copy of Darkest Dungeon and overwrite files for testing, allowing your Steam/GOG version to remain untarnished. When doing this, run the executable in the 'nosteam' folder.

For more about the individual files and directories, see the relevant subsections of this guide. (e.g. If you like the idea of modifying a hero class, jump over to the HEROES section for full details.)

Your mod is a collection of changed data files, in the same relative file hierarchy as the core game. Once your mod is ready to go, follow this procedure:

UPLOADING TO STEAM WORKSHOP

1. Locate the following file:
   
   /SteamApps/common/Darkest Dungeon/_windows/steam_workshop_upload.exe
2. Double-click the exe to see HELP/DOCS. Double-clicking also creates:
   "sample_project.xml"
   in the same folder
   
3. Rename this file as desired and put it in the root folder of your mod.
   
4. Open the xml and fill it out
   
5. ENSURE THAT FILES WITHIN YOUR MOD FOLDER FOLLOW THE EXACT SAME HIERARCHY AS IN THE CORE GAME. For example, if you want to mod "skeleton_courtier", make sure the folder is
   /<yourmodfolder>/monsters/skeleton_courtier/
6. When your mod is ready, drag the .xml file onto
   /SteamApps/common/Darkest Dungeon/_windows/steam_workshop_upload.exe
   This will upload your mod to the Darkest Dungeon Steam Workshop. As part of this process, it will assign your mod a unique identifier number. This will be added directly to your .xml file.

***IMPORTANT: Continue to use the same .xml file with the same ID number for future updates of the same mod. Otherwise, uploading a new version of your mod will create a new Workshop item entirely. This would be bad, as you will lose previous subscribers.***

To edit your mod Icon, include a PNG image file with the name "preview_icon" in your mod's root directory. Your mod description can be edited via the Steam Workshop interface.

Modding DLC content may at first seem confusing since all of the DLC content is kept in a seperate folder, but it actually requires you to do nothing differently. DLC content is applied much like a mod is. That is to say that it is applied over the base game files before mods.

So to mod DLC content you simply need to keep the hierarchy the exact same as you've been doing to mod the base game!

The 'rules' file contains a bunch of variables and values that were hardcoded previous to official mod support. Things like light level buffs, affliction chances, etc... can all be found within. You can find thie file at '/shared/rules.json'. Below is a table listing some notable sections and variables!

1. Copy any or all XML files from the game's localization folder to your mod's /localization folder
   
2. Make changes you need to the XML files in your mod's /localization folder
   
3. Run the steam_workshop_upload.exe with your project's uploader XML.

The steam_workshop_upload should run the localization if necessary.

1. Copy any or all XML files from the game's localization folder to your mod's /localization folder
   
2. Make changes you need to the XML files in your mod's /localization folder
   
3. Copy your localization and, if you've modified it, colours folder to the game's directory
   
4. In the game's localization folder you should see a localization batch file. Run it to generate the .loc file containing all of the game's strings.
   
5. Copy that .loc file to your mod's localization folder

All users that download your mod will now have all new or modified strings.

1. Copy any or all XML files from the game's localization folder to your mod's /localization folder
   
2. Make changes you need to the XML files in your mod's /localization folder
   
3. Set the upload mode to 'dont_submit' in your project's uploader XML
   
4. Run the steam_workshop_upload.exe with your project's uploader XML

The localization for your mod will have been compiled and will now be included in your mod's localization directory.

This section covers the formatting of the effects and different ways to control the effects to perform the desired actions.

We recommend perusing the effects file and getting familiar with how effects are set up. There are many different effects, and explaining them individually would take far too long. It's best to have a desired effect or set of effects in mind, and knowing what hero, enemy, or curio has such an effect. That way you can determine how your effect should work!

Let's say, for instance, you want to mimic the Jester's stress healing effects of Inspiring Tune. You may either scroll down to where the Jester's skill effects are listed, or you may do a search for "Jester" and you'll find his section in the file. Take note of how the effect is laid out. There's a name that can be easily identified at first glance, the targeting information determining who the effect is applied to, the chance for the effect to apply, and whether or not it applies on a hit and/or a miss among other rules. Let's dissect the first rank of that particular effect, "InspiringTune 1", below.

For the sake of visibility, the effect has been split up into two images.



Example Effect Format

• If no duration is assigned to an effect containing buffs, duration will default to 3 rounds
  
• If buffs are called from the buff library, but no duration is outlined in the effect, duration will first look for one in the buff library before defaulting to 3 rounds
  
• Take note of what the effect is trying to accomplish compared to the effect percentage.
  
• The chance percentage on a disease effect is NOT the chance for it to apply. The chance for a disease to apply is always 100%. The chance of the effect is the chance for there to be a disease check on the target.

This section will go over all current buff/debuff types that can be applied to quirks, afflictions/virtues, skills, trinkets, supply effects, curio effects, etc...

This section will cover "rule types", commonly known as buff conditions. Many rules will require specific float (number) values or a string value. Whichever is needed by a certain rule will be denoted by an 'X' in that column. Explanations will be provided in the rule description to help.

In addition, many of these rules can be tagged as a 'false' rule, meaning the effect will be active when the conditions aren't being met.

Hero info files can be split up into 3 main parts: the general hero stats, abilities, and finally the generation data. Navigate to 'heroescrusader' for this example, and open up the 'crusader.info.darkest' file.

• NOTE on .id_index
  
  • "id_index:" is a parameter found towards the bottom of the hero file. It's very important that every hero class in the game have a unique id_index. It's a bit clumsy, but we recommend giving an arbitrary high number so your class doesn't conflict with one of the core game classes, which start at 1 and count up as integers.

Look along the leftmost margin at the beginning of each line. Right at the start of the file you'll see "resistances", "weapon", and "armour". These three areas make up the general hero stats and are extremely easy to edit.

Immediately following the general stats you should see many lines starting with 'combat_skill' and a single 'move_skill'. These are the abilities. Let's take a look at Smite more closely. Note that while the Crusader contains most ability mechanics, you may need to look at other heroes for additional information and examples.

For visual clarity the ability has been split up into two images.





Example Parameters

Additional Notable Parameters

The last set of lines control various aspects of the hero such as generation, recovery buffs, religious tags, and more. All of these parameters are rather self-explanatory, and you are encouraged to look at other heroes for slight variations.

Monsters can generally be explained in two parts - data and art. Data comprises of the stats, abilities, and other information that isn't primarily related to what the monster looks like.

For this example we'll be taking a look at the Apprentice Brigand Cutthroat, his folder of which is 'monstersbrigand_cutthroatbrigand_cutthroat_A'. Open up the 'brigand_cutthroat_A.info.darkest' file with a text editor such as Notepad++. You can set the "language" to Javascript for visual help. You should see this:

Click image if it's too small to read


At the start of each line you should see a word followed by a colon (:). These generally specify what that line contains in terms of data, so below is a table to specific the basics of each line. As with most other sections here you are encouraged to look at other examples, for some unique cases and mechanics exist solely in a single enemy file.

We'll continue to look at the Apprentice Brigand Cutthroat, but this time we're going to focus on the art of the enemy. In the parent 'brigand_cutthroat' folder you should see two additional folders named 'anim' and 'fx'.



The 'anim' folder contains the battle animation for the monster along with the static sprites of their attacks. The 'fx' folder contains all of the skill fx that appears on the enemy, weapon, or target when a skill is used.

Both the animations and skill fx are made in the application "Spine2D[esotericsoftware.com]", but light edits can be done to the physical PNGs. Just be aware that general bone movements and boundaries cannot be modified without the use of Spine2D.

Within the individual enemy sub-tier folders, which is the 'brigand_cutthroat_A' in this example, you'll find the 'brigand_cutthroat_A.art.darkest' file. This file can be opened up in any text editor, such as Notepad++, and contains the information necessary to tie sprite animations and visual fx to specific skills.

Mashes, more commonly known as encounters, are fairly simple to understand. For a start, let's define the enemy ranks 'on paper' and in-game!



As you can see, enemy ranks are from left to right and hero ranks are from right to left. For mashes, we only need to focus on the enemy ranks. In the mash files, here is what that 4 skeleton rabble composition looks like:

Remember: Read the enemy ranks from left to right; changing the last skeleton to a 'skeleton_arbalist_A' would change the rank 4 skeleton into an apprentice arbalist.

First you'll want to specify when you want a mash to appear, usually with 'hall:' or 'room:'. Others also exist such as 'stall' (an encounter than can only appear as reinforcements), 'boss' (for boss quests only), and 'named' (for curio summons or custom maps).

Secondly you'll want to define a chance for that encounter to spawn. The chance in-game is (specific chance/(sum of all chances)), so anything too large will make it much more likely to come across that specific encounter.

Lastly you must define the monster IDs that you want to appear. Optionally you may also append the boolean value of '.can_be_ambush false' to the end of an encounter to specify that you do not want that encounter to be possible during camping ambushes.

This section covers the basic skill selection desires of the enemy AI. There are more than what's listed below, but this should give you a nice jumping off point. Don't be afraid to look at a specific enemy AI if you're looking to mimic a particular effect. Below you'll find examples and descriptions!



This section covers the basic target selection desires of the enemy AI. As with the skill selection desires above, only the very basics are covered here, and it's recommended that you scour the file yourself to get a hang of how things work in different situations.

• Important Tips
  
  • Make note of specific flags and desires on different enemy AI to see how best to accomplish what you're intending.
    
  • Watch your commas; missing even one will make the entire file unreadable.

Quirks, apart from their in-game strings, are handled in two main files. You'll need to set the specifics of the quirk and then set the buffs (if the quirk has any). Below we'll use two quirks as examples!



On the left you can see the disease of Black Plague, and on the right we have the Claustrophobia quirk.

Afflictions and virtues (known as traits) can be modified easily, and others can be added with little work. For this section we'll simply identify the different parts of a trait so you can modify or add your own ones with ease!




As you can see in the image above, we're going to be using the affliction of 'selfish' as an example. "is_generated" of course tells the engine whether or not the trait should even appear in-game. Should you change the "overstress_type" to "virtue", it would register that trait as a virtue instead.

The "curio_tag" and "curio_tag_chance" allow the trait to interact with curios and, if "keep_loot" is set to true like in 'selfish', steal the loot.

The "buff_ids" are the set of buffs that are applied to the afflicted or virtued hero. These are always present while the particular virtue or affliction is active.


At the start of the turn, the hero with the trait will have a chance to do things like shout and cause stress, skip their turn, and more. You can nullify the possibility of any of these by setting the chance to 0, and you can raise the possibility by increasing that number. Based on the numbers of 'Selfish' there is a 33% chance for the hero to perform an act at the start of each turn. You can get this number by adding up all of the chances in that section and dividing a specific action by the total.


These actions, commonly known as 'barks', are done in reaction to something. These barks are accompanied by strings that the character speaks followed by stress damage or healing, depending on the trait.

The chances here, unlike the ones for the start-of-turn act-outs, are percentages translated to decimals. A value of 0.2 in this case is equal to a 20% chance.

• Do note that for most act-outs you will need to write strings of dialogue for the hero in order to avoid 'naked strings' from appearing.

Editing or creating trinkets is incredibly easy, so below we'll take a look at the Ancestor's Bottle and Selfish Pendant to cover the majority of possibilities for a trinket.

• New rarities need a defined RGB or Hex color in the colours.darkest file.
  
• Trinket images should be put in /panels/icons_equip/trinket

Loot tables are confined to a single file, and scanning the file should provide you with enough examples to accomplish anything you may be attempting. We'll provide a few examples below with information on how to manipulate and understand certain variables.

Gold Example:


Heirloom Example:


Trinket Example:



List of items able to be referenced:

• Provisions
  
• Gold
  
• Heirlooms
  
• Gems
  
• Supplies
  
• Journal Pages
  
  • Ranges and specific pages
• Trinkets
  
• Other loot tables

In the 'inventory' folder you'll find the files that determines stack limits and the costs for purchasing items and selling them off when you finish a quest.



This is a small snippet mildly condensed for purposes of space. Here you can see the inventory information for provisions (food), gold, and the portrait heirloom.

This snippet, and the rest of the files, should be relatively self-explanatory.

In the provision.json file located at 'provisionprovision.json' you'll first find the section that determines what items the player starts with in their inventory for a specific length of quest.

Lengths are denoted by square brackets "[ ]". Note that the first set is reserved for length '0' of which no quests exist for this length. The following difficulties are 1,2,3, and 4.

The next section in that same document, provisions.json, covers the starting items for specific heroes. The item lists here should be self-explanatory.

The final section of provisions.json covers the available items in the store. Do note that these sections are controlled by the length of the dungeon, not the difficulty.

Quests are set in the various files located at 'campaignquest'. Below we will describe some of the sections and what they mean in regards to quest generation and descriptions. These are very large and expansive file, so please explore the file to understand the workings of it beyond what is explained here.

Plot quests are quests that, apart from VVulf, will stay around until they're completed. These are usually boss quests or quests that take place in the Darkest Dungeon, but the tutorial Crypts quest is also considered a plot quest.

Below we'll cover one such entry, the Apprentice Necromancer boss quest.



This next small section will go over the rewards for the quest. Below is an image of this small section, all part of the same Apprentice Necromancer quest.


In this area you can define what is rewarded to the player upon successful completion of the defined quest. Follow this form to adjust resolve, gold, heirloom, and trinket rewards for these plot quests.

This final section in the plot quests holds some important variables; follow the table after the image for descriptions of each one.

In the 'quest.generation.json' file is a larger section containing the week-to-week generation data. In order to effectively communicate such an expansive amount of data, the table below will describe the general nature and purpose of the data sets.


You can find the level restrictions in 'quest.restriction.json' file. Each row represents the maximum level of hero allowed to participate on a quest. Setting all to 6 or higher effectively removes the level restrictions.

Random dungeon generation can only be controlled via a small number of variables. Below we'll use a medium Ruins explore as an example to describe how to manipulate each variable.

Custom dungeons are best made in either Google Sheets or Microsoft Excel. First thing you'll need to do is obtain the spreadsheet necessary for map-making. Explanations for how to make a map are included as comments in the cells.

• Google Sheet[docs.google.com] - Make a copy from the menu
  
• XLSX file for Microsoft Excel[www.dropbox.com]

• Maps can only be called by plot quests, so make sure to set the plot quest up correctly.
  
• CSV files will automatically be processed into DM files when running the mod exporter XML through the exporter EXE.
  
• Custom maps can be quite fragile if something is broken or missing within the map's data. Be very vigilant when creating maps!

The curio data file, 'curio_type_library.csv', is a comma-separated value file outputted from a spreadsheet. Some may find it helpful to re-import the file into something like Microsoft Excel or Google Sheets. Doing this will actually allow you to re-export it back into a csv file that the game can use, but it is an optional step that is recommended due to how difficult it can be to understand this specific file on a first look.

For this example we'll be taking a look at the Locked Strongbox curio which is the second curio in this file. It is highly recommended that you look at the setup for all curios to better understand individual mechanics and how they are set up. Missing even a single comma may result in the file being unreadable by the engine, so caution is urged. In addition, anything completely in CAPITAL LETTERS is a header appearing in the original spreadsheet and is not a value that will matter for the engine. Lastly, any sets of strings (sentences of text), located in this file are NOT read by the engine. Changing, adding, or removing the sentences will have no effect on what is seen in-game.

You may have to click this image to see it more clearly


There are 13 lines in the image above, and in the table below you'll find a general explanation for the first 12 lines (line 13 is redundant for this explanation) and what they mean. As mentioned above, use other curios as examples for what you want to tweak or add, and use this reference as a supplement if you're confused.

Town building information can be found primarily in two spots. The first area contains all of the building information aside from the upgrade costs. The second contains only the upgrade costs.

You can get to the location of each building info file by navigating to 'campaigntownbuildings'. Each folder contains the information pertaining to the designated building. Each file structure is relatively the same, but with different metadata depending on the purpose of the building. Most values are floats, so modifying buildings to your liking should be quite straightforward.

Navigate to 'upgradesbuilding' to find each of the building upgrade files. These should be very simple to understand and edit to your desires.

Town events can be both modified and added very easily. To start, open up the base.town_events.events.json located in 'campaigntown_events'. Below we'll cover the sections one by one...

Immediately you will be greeted by a set of values denoting the chances of receiving a town event when you visit the hamlet. These three settings can be chosen by the player in the options menu, and each subsequent chance is applied if a town event is not rolled.

We'll use the Nomad Wagon Discount event, known in-game as the "Nomad New Year", as an example.




Open up the 'town_events.quest_type_event_guarantees.json' file. Here you can specific events that will occur upon successful completion of a quest type in a specified area.

• Important Notes
  
  • Additional town events need a background made and placed in '\campaign\town\town_event'

Before getting started on any mod stuff, be sure you're using the correct version of FMOD Studio. We're on 1.06.07 for the release version of Darkest Dungeon.

If you were asked to "migrate project to new version" upon loading this project file, you'll need to re-download and reopen this project file with the correct version of FMOD Studio.

Download URLs below:
Darkest Dungeon Files: http://darkestdungeon.com/darkestdungeon_audio_mod_materials.zip

FMOD:
Win: http://www.fmod.org/download/fmodstudio/tool/Win/fmodstudio10607win-installer.exe
Mac: http://www.fmod.org/download/fmodstudio/tool/Mac/fmodstudio10607mac-installer.dmg

Download a source code editor such as Notepad++. https://notepad-plus-plus.org/

Once you do that, you should be ready to dive in to the FMOD Studio project file.
We've prepared a very quick tutorial for you, located inside the project file,
in the Properties Pane of all events inside the "MODDERS_READ_ME_FIRST" folder.

If you need help with anything further, feel free to join and contribute to the
Darkest Dungeon - Workshop group on Steam: http://cs2bus.com/groups/dd-workshop

Most background art can be found in the various area folders located in the 'dungeons' folder. These images are fairly easy to change with any image editor. The general dimensions themselves should be adhered to.

Backgrounds and hall tiles can be modified or added with no other work needed!