(Modding) External Conscription for Your Roster

All the information you will need in order to make NPCs playable heroes, or the closest thing possible. There will be shortcomings unless you're a magician. You have been warned.

Premises

Welcome to this wordy guide which will guide you on both creating a new hero and, if you are so inclined, conscripting an NPC or even a monster into serving you.

Before beginning, you'll have to understand how mobs are implemented versus how heroes are. You're not going to just grab a monster, turn it around, and call that a hero. That's not how it works at all.

First, see the file structure. Go to wherever you installed Steam, and within it go to steamapps/common/Darkest Dungeon. There, you will see everything that Darkest Dungeon contains. In order to properly make a hero, you'll only need to edit a few files minimum, and the rest will come later. For this section 1, you will first need to understand the file structure, of both heroes and monsters. Heroes are located in the heroes folder, obviously, and the assets that make up the heroes are located within, each in the appropriately named folder. Same with monsters under monsters.

Inside the folders, however, you'll find more folders and files. To edit any of these, you will require a text editor. Notepad will probably work, but Notepad++ will make it easier. The .darkest files are nothing more than text, and can be edited easily. Take the Crusader for example. In his folder, you'll find these files. The file "crusader.info.darkest" contains definitions for his moves, their stats, and his own stats. The "crusader.art.darkest" file is directly related: it tells the game what effects and art to use for the hero and his abilities. We'll get to the editing in the next section. For now, just know what everything does.
It is worth mentioning that each of the id tags in these files are only the internal names; they are not what you will see in the game. Those are defined in the localization files, but more on that later.

Besides the INFO and ART files, there are also the ANIM and FX folders. This is where it gets a little tricky. Each entity's (heroes and monsters) animations are defined by a PNG file that gives the game something to work with, an ATLAS file that points it to the file and defines its dimensions, and a SKEL file that rigs it to a figurative skeleton, which makes that 2D animation you know and love. I don't recommend tampering with these unless you know what you're doing, but if you were, you probably wouldn't be reading this. Anyway, the ATLAS files can be edited with Notepad++ also, and you'll have to in order to use your animations properly. The SKEL files cannot be edited without specialised programs, so from there on you're on your own.

The FX folder contains files that are for the effects that surround the animations, like the bright sheen of the Crusader's Holy Lance or the lightning on the Vestal's Judgement. These are equally as important, and their animations are structured the same way: ATLAS, PNG, and SKEL.

In short, what makes the hero is not some magic or tosh, but the animations plus the numbers, and of course the dialogue. More on that in the next section. All you need to know is, in essence:
Assets, all you'll need to work with, are located in folders named after their source.
INFO file contains the actual numbers and stats affiliated to abilities and characters.
ART file tells the game which files to use for what.
ANIM folder contains the ATLAS, PNG, and SKEL files needed for what you see on the screen.
FX folder supports the above, containing similar files to make everything shiny. Yey.

Planning

The first thing you want to do is plan your hero. Make notes to yourself on what your hero does, what each of his moves are called and what their purpose is. As a side-note, for this, I used Sticky Notes. This was one of my notes:

I also organised my thoughts thus:

Fanatic:
Strike the Heretic: melee mark killer, weak stun
Brand the Tainted: melee mark target with reduced dmg
Holy Stake: melee bloodsucker killer, bleed
Righteous Condemnation: ranged party dmg, debuff, self mark
Sentence Rendered: strong stun, spd debuff
Fury of the Righteous: ranged mark killer
Righteous Hatred: party stress, spd/dmg buff, clear mark

Definitions:
beat_down: Strike the Heretic
brand_tainted: Brand the Tainted
holy_stake: Holy Stake
righteous_condemnation: Righteous Condemnation
sentence_rendered: Sentence Rendered
crush_tainted: Fury of the Righteous
zeal_buff: Righteous Hatred

Images: (png plus atlas and skel)

fanatic.sprite.attack_book
fanatic.sprite.attack_brand
fanatic.sprite.attack_hammer
fanatic.sprite.attack_point
fanatic.sprite.combat
fanatic.sprite.defend
(along with their fx files) PLUS:
fanatic.sprite.judgement_target (didn't actually use it)

Camping skills:
fanatic_vigil: standard prevent ambush, surprise buffs
fanatic_trinket: trinket, duplicate of antiquarian one
faith_shield: stress resist on self and ally, greater if religious
wholesome_instruction: increase virtue chance

localization strings:
dialogue
heroes
miscellaneous
town_events

sound:
beat_down uses vestal crush
brand tainted uses plague_d noxious blast
holy_stake uses crusader stunning blow
righteous_condemnation uses crusader zealous accusation
sentence_rendered uses maa retribution
crush_tainted uses vestal judgement
zeal_buff uses leper revenge

fanatic vigil uses zealous vigil
fanatic trinket uses trinket scrounge
faith shield uses stand tall
wholesome instruction uses sanctuary

But this is just preference. Now for the actual modding: I highly recommend going into the heroes folder and copying the entirety of another class already in the game, and going from there. For example, you'd make a copy of the crusader folder (along with everything inside, of course) and rename it according to your class. Fanatic, piggy, skeleton, or whatever else you're planning to be reading this guide. Do not forget to rename everything inside as well, including the INFO file and the ART file. You'll be renaming everything of course, but we go one step at a time. That's why God gave us two feet.

[hero].info.darkest

There are many places you could begin, and the best is probably here. As mentioned before, the layout of the info file is relatively simple, and you can edit with Notepad++, or even just Notepad. You won't need a lot of help for this, other than the simple warning to be very careful with quotation marks and periods. Make sure that everything is where it should be, or your mod will break the game. Also be extremely careful with commas. One stray comma will break the entire game too. If you keep the spaces as they are, though, and edit what is in quotation marks, you'll be fine.

Some ropes for the info file:
The starting lines will be like so:

weapon: .name "[hero]_weapon_0" .atk 0% .dmg 5 10 .crit 5% .spd 5

For this, you'll want to replace [hero] with the internal name of your class. It is not what the player will read, of course (you'll take care of that in localization later), but it is the internal name. You probably want to choose something simple, one or two words at most to make it easy on yourself (i.e. squiddy -do not actually use this).

I'm going to skip over the rest for now. You can use the official modding guide for the structure of the info file. Just make absolutely sure that the names agree. The stuff at the bottom should be relatively straightforward, but a few things are worth mentioning.

tag: .id "heavy"
tag: .id "religious"
tag: .id "altar_of_light"

These three lines describe your character. I'm not sure what the top one affects, but "light" and "heavy" are valid. The middle one will of course affect how religious camping abilities affect the hero. "religious" and "non-religious" are valid. The bottom one defines which district building, if any, gives bonuses to the hero. Since I chose the Altar of Light for my mod, a mod with the Fanatic class enabled will have the following heroes listed for benefit from the respective district: Crusader, Fanatic, Flagellant (if using Crimson Court), Vestal.

id_index: .index 1337

Lastly, the ID index. I don't know what this affects, if anything, but Red Hook encourages using an arbitrarily high number. I did this.

Once you're done with your info file, move on to the art. Don't be afraid to keep tweaking the info file after you've left it. It rarely comes out perfect the first time.

[hero].art.darkest

This is where it gets really tricky. Remember all that stuff from the beginning of the guide? This is when it matters.

The lines of the art file will be like so:

weapon: .name "[hero]_weapon_0" .icon "eqp_weapon_0.png"

Once again, be absolutely sure that the name is exactly the same as that in the INFO file. I recommend collecting your icons at this point. You can draw them yourself if you have the ability or use some of the game's own icons. Now, the specific line above references the icons for the class weapon, and the ones below that the armour.

Making new icons might seem overwhelming, but mercifully, there is something you can do. What I did for my mod was go to the Darkest Dungeon directory, and then to the following folder: panels/icon_equip/trinket. At the very bottom, you'll find backgrounds for the various tiers. You can use those as a base for your icon. The trinkets themselves have a transparent background, so if you're desperate, you could copy/paste a trinket onto the appropriate background to make the tiers for your class weapon and armour. As for skill icons, there are plenty to recycle from the other classes. The camping skills are located in raid/camping/skill_icons.

Once you've gathered your icons, rename them appropriately, according to your class, and put them in the proper places, replacing their predecessors in your renamed folders. Now is where it gets good:

combat_skill: .id "smite" .icon "one" .anim "attack_sword" .fx "smite" .targchestfx "blood_splatter"

The above line is from the crusader's ART file. Note that the skill name (.id) exactly agrees with its name in INFO. Note also that the icons in the folder are properly named, one to seven.
You can replace the names as you see fit, just make sure to keep track of them! I highly recommend looking at how existing hero classes structure these files, so you can edit them accordingly.

The Part You Came For (Animations)

If you're reading this guide and looking to conscript some ugly skeleton or that cute (eugh) little devil Wilbur into your team, this is the part you've been waiting for. Up until now, everything has been what your hero actually DOES in the game. But if you're reading this to learn how to turn mobs into heroes, this is what you've been waiting for, because animations are the name of the game.

If you followed the steps of the guide, you renamed everything in the anim folder according to your class, and you did the same with everything in the fx folder. If not, do so now.

Now observe: once again, you have three types of files. Everything animation you see in the game has these three parts: the PNG, the ATLAS, and the SKEL. If you were making a hero from scratch, you'd draw up the PNG, rig the parts in the ATLAS, and attach them to a skeleton in the SKEL. I can't help you with that, though, so let's continue with the assumption that you're recruiting some creepy crawly. Go to the monsters folder, find your appropriate creature, and copy all of its anim and fx files to wherever you're putting your assets. Rename them according to your class hero, and replace the ones in your hero folder with these that you grabbed from monsters/[your recruit].

Two EXTREMELY important warnings now!! FIRST, open the ATLAS file. The first thing you'll see are lines like these:

collector.sprite.attack_skull.png
size: 970,811
format: RGBA8888
filter: Linear,Linear

RENAME the first part of the top line according to your hero. Note that size indicates the exact pixel size of the PNG file. This is one way you'll know what file it's referencing. Do this for ALL of your ATLAS files if you expect your mod to work. Then, in your ART file, make sure that all of your moves reference the proper ANIM and FX files according to the way you renamed them. Congratulations! That's all there is to it. Don't worry about flipping the sprite or whatever. At first I thought I'd have to flip the image horizontally, but while making the Fanatic I found out that the game does it for you. Congratulations.
Make sure to reference only the part indicated. So for fx, don't put in something like
.fx "fanatic.sprite.attack_book"! That part is assumed. Just put it in like so:
.fx "attack_book"
And so on. If you get stuck, imitate the vanilla classes. You'll get the hang of it!

NOW comes the OTHER warning, though I'm sure you figured it out by now: not all the animations are there! Well, unless you have the skeleton editing program and you're planning on drawing Wilbur sitting at the campfire or whatever, there's nothing you can do about it. Your new recruit will work perfectly in combat, having a combat stance, one or more attack animations, and a defend animation. However, you will be missing an afflicted animation, a heroic animation, a camping one, an idle one, an investigating one, and a walking one. This is something you'll just have to make do with, unless, once again, you're planning on making those yourself. Once again, that's not something I did, so I won't be able to help.

To summarise, make SURE that you:

• Copied the PNG files
  
• Copied the ATLAS files
  
• Copied the SKEL files
  
• Changed the first line of the ATLAS files
  
• Replaced the old hero files with your new ones, for all 4 palettes if applicable
  
• Do this for both the ANIM folder files and the FX folder files
  
• Ensure that the ART file references every anim and fx file properly

Palettes and Backgrounds

As I'm sure you've found, the monster you just conscripted was never designed to be a hero, so there will be a great many things missing. In the raid/camping folder, you'll find default.camping_skills.json, which is what you'll edit to give your hero camping skills. Just be EXTREMELY CAREFUL with the commas! To minimise error, I like copy/pasting another skill already there, and carefully editing it to suit what I need. Don't be afraid to look at other camping skills in there to see how you put certain things in.

Now for palettes. These are of course a luxury. You don't have to put in palette changes if you don't want to. But if you do, you go.
If you lack artistic skill like I do, take a look at what I used to get a grey, red, and gold Fanatic: http://www194.lunapic.com/editor/?action=changecolor

On top of all this, you'll notice two other files. [hero]_guild_header.png, in your hero's folder, is what the game will use as a background for the guild screen and for your character screen.

Notice the background, courtesy of fanatic_guild_header.png. I was really lucky to have taken a fancy to the Fanatic, because he has an abundance of artwork to work with. Be sure to check if your chosen mob has an icon used for the Ancestor's Memoirs or the Activity Log, which you'll find under campaign/town/buildings/statue, or dlc\580100_crimson_court\features\crimson_court\campaign\town\buildings\statue if you are looking for something in the DLC.
It is worth the extra efforts! I mean, just look at the difference between the awful class portrait I made...

...and the fantastic class portrait the devs made!

Speaking of which, you're not done yet. We have a ways to go.

Upgrades

Go to upgrades/heroes and copy one of the files, renaming it according to your class. Then, open it and carefully rename the appropriate things according to the name of your class. When you finish, it should look something like this:

It shouldn't be hard, but be careful.

Localization

TO AVOID ERRORS, BE SURE TO READ THE LAST LINE OF THIS SECTION THOROUGHLY.
This is potentially the most tedious part of the mod, but it is undoubtedly one of the most important. Upon further review, the best way to create your heroes is NOT to edit dialogue.string_table.xml, heroes.string_table.xml, and miscellaneous.string_table.xml, but to make a new file called [hero].string_table.xml, with [hero] being the name of your class. This is so that the mod doesn't break with every update (confound it, Red Hook), as its files are its own. I recommend imitating the file structure of the finest mods, or of mine now that I figured this out. Again, with the Steam download broken, use the Nexus or Drive links.

Dialogue is self-explanatory. You will have to write dialogue for your character to say, for literally every cause in the book: every affliction, every action, every moment. Be very careful, and do not mess anything up. Be careful with the brackets especially. Save often while you edit, and if the file breaks, return to a previous version. If typing directly into the file is slow because of its massive size, do as I did: type your line in Notepad, copy it, and paste it into Notepad++, replacing the original line within the brackets. Do not forget to rename for your class near the beginning of the line.

The content from the heroes file is extremely important. It dictates what the player will actually see and read in the game. Your class skill and abilities can have any internal name you want, even yadayada3, but what comes in the brackets in this file is what the player will actually read in-game. Be very careful with underscores versus periods. Keep that in mind, and your editing should go swimmingly. This file is also where you will give names to your class camping skills as well as name their actual weapons and armour. Furthermore, you will write a thorough description for the Guild and Blacksmith. It'll be fun!

Miscellaneous only contains one item relevant to hero mods, which is the line your hero uses when facing the final boss. You can put that in your own string file pretty much anywhere.

Since you are no longer using the archaic method of replacing files, you probably won't need to run localization.bat. But if this happens:

You know what to do.

Sound

Another luxury, but it sure adds another layer of enjoyment to your mod. The easiest way to do this is to download an already-made class mod with sounds and imitate their structure. Make a folder named audio in your mod directory if it doesn't have it already. It will contain two files: [hero].campaign.guid_overrides.json and [hero].campaign.load_order.json. Rename these appropriately and edit their contents.

The load_order file of the Fanatic mod looks like this:

{
"load_order":
[

"secondary_banks/hero_vestal.bank",
"secondary_banks/hero_crusader.bank",
"secondary_banks/hero_man_at_arms.bank",
"secondary_banks/hero_leper.bank",
"secondary_banks/hero_plague_doctor.bank",
"secondary_banks/hero_antiquarian.bank"
]
}

Essentially, it tells the game which of the sound banks under the secondary_banks folder to use for your mod. Technically, they could be anything there, but consult the Red Hook official modding guide for making your own sound banks. I'm staying away from that like it's the Diggle Plague. [inquisitorial shudder]

Anyway, the guid_overrides file will look like this:

{
"event_guid_overrides":
[
{"event_id": "event:/char/ally/fanatic_beat_down", "guid_override":"{e609c231-fad8-4b42-9117-3f58f98c156e}"},
{"event_id": "event:/char/ally/fanatic_beat_down_miss", "guid_override":"{4ee60a31-0148-4c82-909f-10fa62b48767}"},
{"event_id": "event:/char/ally/fanatic_brand_tainted", "guid_override":"{24d00e2b-de53-4824-97ca-d3a665d64dd2}"},
{"event_id": "event:/char/ally/fanatic_brand_tainted_miss", "guid_override":"{b2e0b295-cca2-47ec-86f1-ff57c51929d6}"},
{"event_id": "event:/char/ally/fanatic_holy_stake", "guid_override":"{48723e30-7f15-4ee5-979a-63f47df387a0}"},
{"event_id": "event:/char/ally/fanatic_holy_stake_miss", "guid_override":"{f5908cd3-dcde-4290-b561-8672a4b4481d}"},
{"event_id": "event:/char/ally/fanatic_righteous_condemnation", "guid_override":"{a195abae-ff9f-42b7-91df-6df2b7bd254a}"},
{"event_id": "event:/char/ally/fanatic_righteous_condemnation_miss", "guid_override":"{cc20caa3-5a59-40a4-9262-475e7a4fa85b}"},
{"event_id": "event:/char/ally/fanatic_sentence_rendered", "guid_override":"{2660adf0-b411-4485-b0d2-ff02bc45e63f}"},
{"event_id": "event:/char/ally/fanatic_sentence_rendered_miss", "guid_override":"{d29a51a8-a64c-4e31-ac6b-5090b4c0e4b5}"},
{"event_id": "event:/char/ally/fanatic_crush_tainted", "guid_override":"{2943f606-8cff-4adf-9135-bc156be87f73}"},
{"event_id": "event:/char/ally/fanatic_crush_tainted_miss", "guid_override":"{3b35e023-6ddd-4ca3-91ec-d467963853a7}"},
{"event_id": "event:/char/ally/fanatic_zeal_buff", "guid_override":"{3cf95339-7bc2-45c2-aadc-3b7aa18ff32c}"},
{"event_id": "event:/char/ally/fanatic_zeal_buff_miss", "guid_override":"{6898e3ec-cf20-4273-9cc1-c63536a17abb}"},
{"event_id": "event:/vo/town/recruit_fanatic", "guid_override":"{0688de26-a676-4672-99ab-b5a4323e7c95}"},
{"event_id": "event:/camp/skill/fanatic_vigil", "guid_override":"{95dc4f21-cef7-4e25-aab9-fb90273e18ab}"},
{"event_id": "event:/camp/skill/fanatic_trinket", "guid_override":"{1d0f073a-50a4-4634-8613-5a6dcf32040c}"},
{"event_id": "event:/camp/skill/faith_shield", "guid_override":"{8272770d-0b03-4bac-b85e-449c7dbdee6b}"},
{"event_id": "event:/camp/skill/wholesome_instruction", "guid_override":"{6057bb01-8644-47ba-970a-90b0470866fd}"}

]
}

The event_id part tells the game when to play the sound. Be sure to put the proper names, according to the way you called them in the INFO file and in the camping file.

Now, the guid_override part is the hard part. It tells the game what sound to play. That complicated jumble of letters and numbers is the only way the game will understand it. What you do is copy the jumble into the space between the quotes, according to the sound you want. Be careful not to mess up the quotes or the curly braces.

Fortunately, there is a master list of the sounds in the base game for your use. Access it here: https://drive.google.com/file/d/0B05DVqF3z5WNeF9rRjQwOHdiNVk/view

You're Done!

That's all there is to it. Consult the Red Hook official modding guide for all that fills in the gaps. At this point, you should be pulling off all kinds of amazing tricks like this:

If I left anything important out of the guide, let me know and I'll add it in.

[Barrelmaker]

Correction: I don't know what my amateur self was thinking. You can easily test your mod or generate strings by making a copy of it in your /mods folder (that you create in the base directory). Generate it like any other mod with your project.xml, but use the dont_submit setting. This can also be used to regenerate mod_files.txt

[Barrelmaker]

While copying the bat to your mod may work, I never tried it and I don't know what would happen. Your call

[Barrelmaker]

Run from the base directory. It's up to you how you decide to test your mod, but when I made the Fanatic I integrated its files with the base game, seemed simplest. For the final product, of course, you'll want to put it in your mods folder.

[The Blessed Word]

ty, do I run from the base directory or do I copy the .bat to where my mod localization files are? Or does it not matter?

[Barrelmaker]

Simply run localization.bat if you have already written all the names and lines and still get that blue internal text instead.

[The Blessed Word]

@Multivac 9000
Regarding the ending sentence of the localization section, what do I do if I DON'T know what to do?

[Khbikhib]

... OKAY.

[Barrelmaker]

But I absolutely said I do NOT have art skills to change appearances. Consult one of the creators of skin mods perhaps

[Khbikhib]

I have some modest drawing skills and i just want to make like outfits (without changing the character animation or skills .. only appearance) .
Should i just modify over the png picture on the folder ? ..basicly the character will remain the same only the appearance that will change
(Excuse my bad english)

[Barrelmaker]

...what? I'm talking about replacing assets here, I have no skill or experience in drawing new assets altogether. I recommend GIMP if you don't have Photoshop, but you'll need Spine to rig the skeleton. I can not help you there, nor in drawing