Darkest Dungeon®

Darkest Dungeon®

1,234 ratings
Darkest Dungeon - Modding Guide [Official]
By RedHookTyler and 2 collaborators
[WORK IN PROGRESS] Official modding guide by Red Hook Studios. Learn the basics of how to mod Darkest Dungeon! We encourage community members to make more detailed and specific guides, but this guide is intended to answer many common questions and share internal information to empower modders.
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!

Enabling Mods within 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.
Getting More Help
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!
Recommended Software
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/

Important Information for Artists
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]
Things that Can be Modded
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.
The Basics of a DD Mod
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:
/SteamApps/common/Darkest Dungeon/

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
/SteamApps/common/Darkest Dungeon/mods/
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.)
Uploading to Steam Workshop
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:

  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:
    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
  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
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!
Core Rules and Progression
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!

This is the chance that your party will successfully retreat when you attempt to do so during battle.
This is the base % chance (as a float value) that an affliction will happen. By default it is set to 75%, with a 25% chance to obtain a virtue.
This is the chance for the quirk 'Fated' to convert a miss into a hit.
This larger table lists the chances for backtracking events to occur, such as battles, traps, and hunger tiles.
This larger table determines the buffs the player/enemy team gets during different light levels.
This is the amount of HP healed when a hero consumes food.
This table determines the camping costs and rewards when choosing how much food to eat.
This is the base scouting chance for the entire team; individual heroes do not control scouting chance whatsoever.
This is the amount of food a hero can eat before he/she comes full and will not eat any more until camping.
This is the chance for an ambush to occur after camping.
This is the amount of accuracy to buff a hero with secretly if he/she has consecutively missed.
This is the week limit set for Stygian/Bloodmoon before the game will automatically fail the player.
This is the death limit set for Stygian/Bloodmoon before the game will automatically fail the player.
Strings and Localization
Steam Workshop
  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.

Third Party Mod Uploads
  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.

Third Party Mod Uploads (Alternative)
  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.
Effects - Format & Layout
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.

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

Example Effect Format
This is required for all effects to be parsed by the engine.
This specifies the name of the effect so that when a hero, enemy, or curio calls it the engine knows which line of data it needs to read.
This specifies the targeting parameters of the effect. For this example effect, the Jester's 'Inspiring Tune' targets any hero. This effect then is applied to that target.
Should an effect be used by a curio, this line followed by either "positive" or "negative" will determine which visual effect the player will see.
This is the chance for the effect to be applied.
This, followed by a number, tells the effect to heal stress by a specific number. The number, ten in this example, is before any buff or debuff is taken into account.
.on_hit & .on_miss
These are boolean (true or false) values that determine whether the effect will apply if a skill hits or misses the intended target(s).
This optional parameter, also a boolean, can tell the effect to count after the others in the skill, if there's more than one of them.

Effect Targeting Format
This effect will target the hero/enemy it is assigned to.
This effect will target the hero/enemy in line with the skill's targeting parameters.
This effect will target the entire hero/enemy party it is assigned to.
This effect will target the entire hero/enemy party in line with the skill's targeting parameters.
This effect will target the entire hero/enemy party it is assigned to apart from the performer.
This effect will target the entire hero/enemy party in line with the skill's targeting parameters apart from the target.
This is reserved for light modifier effects.

Important Notes
  • 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.
Buffs - Stat Types and Subtypes
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...

Buff Types and Subtypes
Buff Stat Type
Buff Stat Subtype
Buff Description
This adjusts the critical chance (CRIT) of the target.
This adjusts the dodge (DODGE) of the target.
This adjusts the protection (PROT) of the target.
This adjusts the speed (SPD) of the target.
This adjusts the maximum health points (HP) of the target.
This adjusts the minimum damage (DMG) of the target.
This adjusts the maximum damage (DMG) of the target.
This additively adjusts the minimum and maximum healing power of the target. A 1-1 heal with a "4.0" hp_heal_amount buff will become a 5-5 heal.
This multiplicatively adjusts the minimum and maximum healing power of the target. A 4-8 heal with a "0.5" hp_heal_percent buff will become a 6-12 heal.
This adjusts the healing received power of the target.
This adjusts the stress damage done by the target.
This adjusts the stress healing done by the target.
This adjusts the stress damage received by the target.
This adjusts the stress healing received by the target.
This adjusts the stun resistance of the target.
This adjusts the move resistance of the target.
This adjusts the blight resistance of the target.
This adjusts the bleed resistance of the target.
This adjusts the disease resistance of the target.
This adjusts the debuff resistance of the target.
This adjusts the deathblow resistance of the target.
This adjusts the trap disarm chance of the target.
This adjusts the blight skill chance of the target.
This adjusts the bleed skill chance of the target.
This adjusts the stun skill chance of the target.
This adjusts the debuff skill chance of the target.
This adjusts the move skill chance of the target.
This adjusts the virtue chance of the target. A positive amount will increase the chance for a virtue, and a negative chance will increase the chance for an affliction.
This adjusts the scouting chance of the party.
This adjusts the chance for a negative quirk to be removed from a target. Currently all chances are guaranteed (Sanitarium and curios), so this buff remains unused.
This adjusts the amount of food consumed by a party member.
This adjusts the amount of damage done to a party member when starving.
This adjusts the amount of resolve experience the target gains at the end of a quest.
This adjusts the price of weapon upgrades for the target.
This adjusts the price of armour upgrades for the target.
This adjusts the chance for the hero party to be surprised.
This adjusts the chance for the enemy party to be surprised.
This adjusts how much damage the target receives. This buff also applies to DoT damage.
Buffs - Rule Types
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.

Rule Types and Float/String Requirements
Rule Type
Rule Float?
Rule String?
Rule Description
This is the default rule that states a buff is always active.
The buff will be active when engaged with an enemy of a specific size.
The buff will be active when the torchlight is below a certain number between 0 and 100.
The buff will be active when the torchlight is above a certain number between 0 and 100.
The buff will be active when the target's HP is below a certain percentage.
The buff will be active when the target's HP is above a certain percentage.
The buff will be active when the target's stress is below a certain number between 0 and 100.
The buff will be active when the target's stress is above a certain number between 0 and 100.
The buff will be active when the target is afflicted.
The buff will be active when the target is virtued.
The buff will be active when the target is engaging or engaged in a melee attack.
The buff will be active when the target is engaging or engaged in a ranged attack.
The buff will be active during the first round only.
The buff will be active when the target is engaging or engaged with an enemy under the effects of a certain status. (poisoned, bleeding, tagged, stunned)
The buff will be active when the target is engaging or engaged with an enemy of a specific tag (UNHOLY, BEAST, HUMAN, etc...). The strings should be written in lowercase letters, even though they appear in-game as all capitals.
The buff will be active when the target is on death's door.
The buff will be active when the target is in a specific rank. The acceptable rank values are 0, 1, 2, and 3. The front rank is 0, and the back rank is 3.
The buff will be active when a camp is active.
The buff will be active when in a specific dungeon. Current dungeon strings are: cove, crypts, darkestdungeon, town, warrens, weald. Do note that there are no capital letters and no spaces in the strings.
The buff will be active when in a room tile.
The buff will be active when in a corridor tile.
The buff will be active when walking backwards.
The buff will be active when the target is in a specific town activity. Current town activities include, but are not limited to: meditation, bar, or disease_treatment.
The buff will be active when the target has a riposte active.
The buff will be active when the target is engaging with a specific skill, or engaged with an enemy using a specific skill. String should match the respective skill id.
The buff will be active when the target is in a specific mode. Currently this only applies to the Abomination who has two modes, 'beast' and 'human'
Hero info files can be split up into 3 main parts: the general hero stats, abilities, and finally the generation data. Navigate to '\heroes\crusader' 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.

General Hero Stats
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
The ability ID for string, art, and sound references.
The level of the ability that the line is describing. Level 0 is the base, or level '1' in-game, whereas level 4, or level '5' in-game, is the highest.
The type of ability for certain buff parameters to affect.
The accuracy of the ability.
The damage of the ability in relation to a hero's base damage. If set to '-50%', the Crusader's Smite with base weapon damage of 6-12 would do 3-6 damage instead. If at '50%' it would do 9-18 damage.
The crit chance of the ability to be added onto the weapon crit chance.
The ranks where the ability can be used from.
The ranks that the ability targets. If an '@' symbol precedes the numbers, this indicates that it targets friendly ranks. If an '~' symbol precedes the numbers, this indicates that it targets all of the denoted ranks. If an '?' symbol precedes the numbers, this indicates that it will randomly target one of the denoted ranks.
A boolean value that denotes whether or not an ability can crit.
The list of effects associated with an ability. Currently there can only be a maximum of 4 effects tied to a single ability level.
When a hero is spawned at the stagecoach, this parameter with a boolean value of 'true' will guarantee that the hero spawns with the specified ability. Note that only a single ability can be guaranteed per hero.

Additional Notable Parameters
This parameter accepts two values, the first being the minimum healing amount and the second being the maximum. Take a look at the Vestal's healing skills for two good examples.
This parameter needs two numbers. The first number indicates movement backwards, and the second indicates movement forwards. The best simplified example of this parameter can be seen on generic movement skills.
This parameter followed by a boolean value indicates whether or not an ability can target the performing hero.
The limit on the number of times an ability can be used during a single battle.

Generation Data
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 - Data
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 'monsters\brigand_cutthroat\brigand_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.

This line will only contain a single variable, which is the amount of spaces that the monster will take up.
This line can be repeated more than once to determine what categories the enemy falls under. These categories are used in effects and buffs that require specific enemy categories in their descriptions.
This line contains the health, protection, dodge, speed, and various resistances associated with the enemy.
This indicates that the following variables are tied to an enemy skill. Usually you'll find a very similar set of information for most skills, all of which should be self-explanatory.
An antiquated and redundant variable. Keep at "-1" to avoid issues.
This line can be repeated more than once to determine what loot tables are called upon enemy death and how many times the table is called.
This line houses the variable that determines how many times an enemy can act each round.
This is the id of the AI brain that the enemy uses.
This line determines what monster class the enemy will become upon death. As you can see the cutthroat will turn into a corpse.
This line contains mostly booleans (all in this example, but other enemies have other modifiers). The booleans in the cutthroat example determine such things as the stall penalty and surprise mechanics.
Monsters - Art
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.
Monster Encounter Groups ("Mashes")
Defining Ranks
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:
room: .chance 1 .types skeleton_common_A skeleton_common_A skeleton_common_A skeleton_common_A

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.

Making & Editing Mashes
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.
Monster Brains (AI)
AI Reference - Skill Selection Desires
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!

The monster will choose a random skill to use.
The monster will use a specific skill.
The monster will use any skill with a heal attached to it when a valid target has less HP than the given threshold.
If an attack has an effect that targets a specific status (stunned, poisoned, bleeding, etc...) this will tell the monster to choose the skill based on whether or not a hero is afflicted with the defined status.
The monster will use a skill if another monster of a specified base type is still alive.
The monster will use a skill if a specified monster is not alive in the current encounter.
This skill's base chance is added to the mix on the performing initiative of the monster. To clarify, this is not the round that is being specified, but rather the performing turn of the monster. This giant in the example, if stunned in the first round before it can act first, will still have this skill selection desire during the second round.

AI Reference - Target Selection Desires
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.

The monster will choose a target at random.
The monster will choose a marked hero.
The monster will choose a marked rank. Currently this is only used by the Prophet and Vvulf.
The monster will choose a companion to target with the specified skill.
The monster will choose the companion with either the lowest or highest health, as determined by the data.
The monster will choose the hero with the highest or lowest stress, as determined by the data.
The monster will choose the hero with the highest or lowest resistance to the specified effect, as determined by the data.

  • 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.

This id will be used to identify the quirk for strings and incompatibility between other quirks.
This variable, if set to false, will not show the assigned buffs for the quirk.
This variable, if set to true, will show the custom string description in lieu of the actual buff(s) assigned.
This variable, if set to true, will show the curio interaction chances for the quirk.
This variable is the chance of the quirk to be given in relation to the other quirk chances.
This boolean, as it appears, determines whether the quirk is positive or negative.
Another boolean value that determines if the quirk is a disease or not.
Can be "physical" or "mental". Physical quirks are more likely to be given at the end of a quest to heroes that leave with lower health. Mental ones are more likely to heroes that
You can list here the quirks that will not be given to the hero if they possess the currently specified quirk.
Here you can specify curio tags that the quirk will force the hero to interact with. This requires the next value to be greater than 0.
The chance for the hero to interact with a curio tagged with the specify tag from the above value.
If set to 'true' the hero will steal the loot when they forcibly interact with curios and the resulting outcome is loot.
The list of buffs associated with the quirk.
Traits - Afflictions & Virtues
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!

ID, Curios, and Buffs

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.

Start-of-turn act-outs

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.

Reaction act-outs

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.

This id will be used to identify the trinket for strings.
The list of buffs associated with the trinket.
Here you can list the hero class that the trinket should be restricted to.
This is where you list the rarity of the trinket
This determines both the cost of the trinket to purchase from the Nomad Wagon, and the gold earned from selling it. Trinkets are sold for 37.5% of this value, and purchased for 100% of this value.
This limit determines how many of a specific trinket the player is allowed to have. When this limit is reached the player will not earn any more of a specific trinket. If set to 0 the player can hold an infinite amount of the trinket.
This allows you to set a specific dungeon where the trinket can only be found.

  • 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:

The id attached to the loot table.
The difficulty that the table applies to. If set to "0" the table can be called by all difficulties.
The dungeon that the table applies to. If left blank the table is universal.
The list of entries associated with the table.

List of items able to be referenced:
  • Provisions
  • Gold
  • Heirlooms
  • Gems
  • Supplies
  • Journal Pages
    • Ranges and specific pages
  • Trinkets
  • Other loot tables
Purchase/Sale Costs & Stack Limits
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.

Starting Items
In the provision.json file located at '\provision\provision.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.

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

Store Items
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 - Goals, Types, and Progression
Quests are set in the various files located at '\campaign\quest'. 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.

fail_penalty - quest.fail_penalty.json
This value determines the amount of stress damage that the party receives upon failing a quest for any reason.
goals - quest.types.json
These are the quest goals that are assigned to quests and determine what the team must accomplish before the quest can be considered completed.
town_progression_goal_ids - quest.types.json
These four variables, located directly above this section, determine what needs to occur in order to progress a week in the hamlet.
types - quest.types.json
This is where you set types with defined goals so that later in the file you can call these types to be generated for a given week.
Quests - Plot Quests
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.

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

The ID of the quest for reference.
The level of the dungeon that is required before this quest can appear. Note that this is NOT the difficulty or length of the dungeon but rather the level that appears on the skull.
This boolean value marks the quest as a quest required to move along the story and spawn subsequent quests.
The quest type, as determined from the listed types in the above section.
The area that this quest takes place in.
The difficulty of the quest (usually 1, 3, 5 or 6)
The length of the quest (usually 1, 2 or 3)
The goal of the plot 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.

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

This boolean determines whether or not the quest is needed to progress to the next plot quest in that area.
This boolean determines whether or not you can repeat the quest after initially completing it.
This boolean determines whether or not there's a statue checkbox for completing the quest.
This boolean determines whether or not additional XP is given to heroes based on a later table. You'll probably want to keep this set to false so you can manually tweak a single XP value for the quest yourself.
This boolean determines whether or not the requirements to progress a week are enabled.
This boolean determines whether or not the player is allowed to retreat from the quest.
This boolean determines whether or not you can fail attempts to retreat from battle. If set to 'false', you can fail.
This value determines how many party members are automatically killed if you retreat from the quest.
This boolean determines whether or not surprises are enabled during the quest.
This boolean determines whether or not scouting is enabled during the quest.
This boolean determines whether or not all stress is removed from all heroes in the hamlet upon successful completion of the quest.
If the quest is ignored, as it is with VVulf, this section can be expanded to describe what hamlet upgrades should be removed, if any.
If the quest is failed this section can be expanded to describe what hamlet upgrades should be removed, if any.
If the quest is failed this section can be expanded to describe what buffs to apply to the entire hamlet roster, if any.
If the above section is filled out with buffs, this value represents the minimum hero level that the buff should apply to.
Quirks to apply to the party upon successful completion of the quest.
Quirks to apply to the party upon failure of the quest.
The minimum rarity for the quest to take from your trinket inventory.
The number of trinkets the quest will take from your inventory.
Whether or not the quest will warn you about not having trinkets equipped.
Whether or not the quest will warn you about the amount of provisions you should be taking.
This section can be filled in with suggested trinkets so that a prompt is given to the player before embarking. This is seen on the second Darkest Dungeon quest, more commonly referred to as DDQ2.
This section can be filled out to determine what starting provisions or supplies the embarking team will be given.
Quests - Generation & Restriction
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.

Each line of this section is a specific week, with more quests being generated as the in-game weeks pass.
For each of the area where quests can naturally generate (not plot quests), this section can define how many quests must be completed before each area opens up and can spawn quests.
In this small table you can set what level of quests should generate for what resolve levels you have in your roster.
This much more massive table determines, for each area, what quests are available to spawn for what week. Each table in the separated square brackets denotes a week. Right away we can see that the first week in the Ruins there's only a single quest that can even be generated -- a short exterminate.
This section determines what heirlooms can be rewarded from quest rewards. Note that this applies only to quest rewards, not loot.
The amount of heirlooms to be given for quest rewards.
The amount of gold to be given for quest rewards.
The amount of XP to reward to heroes upon successful completion of a quest.
The trinket table to determine the rarities of trinkets that can be rewarded as quest rewards.

Level Restriction
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 Gen
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.

This denotes the size of the dungeon; short, medium, or long.
This indicates the quest type, pulled from the quest file.
The area that this quest takes place in.
The base number of rooms the engine should generate.
The base number of corridors the engine should generate.
The size of the grid that rooms will generate in.
The amount of hallway tiles in between rooms.
The general 'connected' feeling that a dungeon will have. A higher number means that rooms are more likely to be connected with hallways. A lower number means the opposite.
The minimum final distance to the goal room; usually used for boss quests.
The minimum and maximum amount of hallway battles that you will find in the dungeon.
The minimum and maximum amount of hallway traps that you will find in the dungeon.
The minimum and maximum amount of hallway obstacles that you will find in the dungeon.
The minimum and maximum amount of hallway curios that you will find in the dungeon.
The minimum and maximum amount of hallway hunger tiles that you will find in the dungeon. Do note that backtracking has a chance to spawn additional hunger tiles not associated with this number.
The minimum and maximum amount of room battles to generate, including all of the relevant variables below.
The minimum and maximum amount of just room battles (just enemies) to generate.
The minimum and maximum amount of guarded room curios to generate.
The minimum and maximum amount of room curios (no enemies) to generate.
The minimum and maximum amount of guarded room treasure curios to generate.
The minimum and maximum amount of room treasure curios (no enemies) to generate.
The minimum and maximum amount of secret rooms to generate.
Hand-Designed Dungeons
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.
Important Notes
  • 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.

Description & Notes
In the first line we have three values which serve mainly as references and information for the curio itself. The number 2 in this line represents that it's the second curio in this file. Immediately after that we have the Curio's name. Note that this is not the name that appears in-game, rather one that helps you know what it is. The last bit here notes that there are 'mixed' effects possible. You can get loot or get a nasty DoT. Other curios may be completely good or bad in their possible effects.
There's nothing that you want to change in this line, and none of it is read by the engine. If you imported the csv to a spreadsheet program you'll see that these are all column headers mainly used in easily reading the following lines.
The first value in this line is incredibly important. This ID, following the format of having no spaces, will be used when you want to reference art and strings that will appear in-game.

Following that is the effect of 'Nothing', or interacting with the curio and having nothing happen. After 'Nothing' you'll want to put the weight of the 'effect' to happen. This weight is divided by the curio's total weight of effects.
We'll start this line at the 'Loot' part, as the 'REGION FOUND' text is not important to the overall functionality of the curio. Here you can set the chance of loot, if any, and the tables it should call. The '1' in the column after 'Loot' is the weight of that 'effect' to happen. There are only two possible effects for the Locked Strongbox, loot or a DoT. As you can see in the 6th line, 'Effect' has a weight of 1 as well. Add up the weights and then divide the current 'effect' weight by the total. Each has a 50% chance of happening, as you can see. The 50% chance following the weight is a value that is calculated in the original spreadsheet and is not read by the engine at all. The engine will only take weights into account.

After the 50% is the table that it pulls from, and the number in the next column is the number of pulls that it does from the specified loot table. You can repeat loot table calls an additional two times by putting the desired table and number of draws before the '<- # Draws' sections. When loot is awarded it will award all loot tables listed for the specified number of draws for each table.
This line lets you set a quirk reward as a curio interaction. This follows a similar format of 'weight,% chance,result' as other effects. An excellent example of the quirk effect can be seen on curio #7, the Stack of Books.
This line lets you set effects that are given when interacting with the curio. A maximum of three possible effects can be added to a curio's effect rewards. The weights in lines are different from the overall weight of individual interaction types like loot, quirk, and effect.
The immediate first value is quite important. The 'Yes' or 'No' will determine if the curio prompts the player for any item inputs or whether the curio can just be used like a sack or crate. If your curio has no item interactions, set this to 'No'.

The 'Purge' effect allows you to remove a quirk, positive or negative. Curio #5, the Eldritch Altar, shows an excellent example of this.
This line allows you to set scouting events that can trigger as an effect. Curio #20, the Bookshelf, has a great example of this effect. Much like the other effects you must set weights for the different scouting examples to proc, but the data that you put into the proper column is a bit different. As you can see in the Bookshelf, there is a '0 - curios' and a '0 - all' listed. The number in each is the number of rooms this scout will go, so both will only extend to the hallways on each side. The string on the opposite side of the dash describe what the scout will reveal. This can be 'curios', 'all', 'room_battles' and more. As recommended at the top of this section, take a look at all curios for further examples.
The first two string values in this line are the curio 'tags', or two describing tags of what the curio is. These are used mainly by quirks that interact with specific curio tags, like Hyromania or Bloodthirsty. The 'teleport' effect after the tags is unused and dysfunctional, so it is not relevant to the curio's overall functionality.
After two of the commas in this line you can set a third tag, though it's not set on all curios. You can see this in the next curio in the file, the Goal Strongbox. It has the tags of 'Treasure', 'Goal', and 'All'. The last tag is used mainly by the quirk of Curious, which can interact with any curio tagged with 'All', which is all of them.

This line also lets you set a disease effect. An example of this can be seen in the 8th curio, the Iron Maiden. You can either call specific diseases and/or any of them.
Nothing in this line needs to be edited; it acts mainly as a separator and reference line for the following item interactions.
This is the first item interaction. A Skeleton Key can be used on the Locked Strongbox to get 3 pulls from the loot table 'A'. You can use any of the main 'effects' as item effects, but note that you can only have a single possible effect tied to a single item. It is not possible, for instance, to have a Skeleton Key give loot or a quirk on the same curio. Take a look at all of the curios for many, many examples of item interactions and their precise formatting.
Town Activities and Shops
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.

General Information
You can get to the location of each building info file by navigating to '\campaign\town\buildings'. 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.

Upgrade Requirements
Navigate to '\upgrades\building' to find each of the building upgrade files. These should be very simple to understand and edit to your desires.
Town Events
Town events can be both modified and added very easily. To start, open up the base.town_events.events.json located in 'campaign\town_events\'. Below we'll cover the sections one by one...

Town Event Chance Setting
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.

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

The event ID to be referenced.
The base chance for the event to appear. Percentage chance each week is this number divided by the total of all base chances of available events.
Each week that passes, if the event requirements are being met, this number is added to the base chance. The base chance will reset to the designated value when this event is rolled.
The amount of weeks that must pass before this event can be rolled again.
A set of, as it says, requirements that must be met before the event can be rolled.
The general attitude of the event. This can be set to 'good', 'bad', or 'neutral'.
The sprite that should be enabled when the event is active.
The building that the specified sprite should attach to, if any.
The collection of buffs, town modifications, or general changes that the event gives.

Quest Completion Guaranteed Events
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

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://steamcommunity.com/groups/dd-workshop
Background Art
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!
< >
tunaicen Dec 21, 2023 @ 12:32pm 
Is it possible to make a skill only target stealthed enemies?
IceWitch11 Dec 16, 2023 @ 2:25pm 
does normal notepad work in stead of ++?
kamil.kouba2001 Sep 22, 2023 @ 3:40pm 
hey, is it possible, I have too many mods?
Zee Captain (o.W.n) Sep 7, 2023 @ 6:09am 
I still don't understand how I can just skin a character.
hyη Jun 5, 2023 @ 8:14am 
Hello everyone! I'm having trouble with game mods, could use a hand please. I'm not sure if I have too many, but now when I add new ones they won't show after installed.Tried to reboot the game several times and nothing. :stress: Any ideas what to do to make them show up? Thanks in advance!
the May 11, 2023 @ 11:34am 
I have a quick question about the buffs category. Is it possible to make an effect that heals its target by a negative percent, thus removing health?
Cute Star Nov 27, 2022 @ 2:01am 
Hello,Mr.developers.I have a error. I upload my new mod today,it always appear"Unhandled error".I try to fix it almost an hour,but it didn't work.Can someone help me?
SingularAndrew Aug 29, 2022 @ 4:03pm 
@Sharaj The link has been removed. This is the new one. Found on the Darkest Dungeon Discord, in the mod resources channel. https://drive.google.com/open?id=1tWf1kihFg7fVHRR4TNCOGkMTBbnckoIC
Lewd Wig Apr 29, 2022 @ 5:23pm 
@JUST 莫妮卡 if you add your own "preview icon" for your mod, it will bug and crash your upload. Same thing happened to me when i try to add my own image for the mod.