Hero Porting Tutorial

If you've ever had to choose between advanced skins for classes that conflict with one another, or been annoyed at that one hero that just does not have skins that you like, there is a solution.

I'm mostly making this to link to people so I don't have to re-state the instructions every time someone asks.

Overview

In this guide, I will be laying out the steps to completely replacing the assets of one hero to another.

Some reasons to do so, for example, is to port vanilla-skeletoned hero skins from their host hero onto a similar modded class, allowing you to keep them while using a skin with a unique skeleton. For example, using the Highwayman as the Baron or the Plague Doctor as the Apothecary.

This method can also be used to port Hero skins into Monsters, useful for additional customization and, again, making use of interesting but prohibitive skins without needing to play them. For example, using a Musketeer skin as the Brigand Fusilier.

Primarily, however, this is meant to allow the porting of NSFW skins among heroes and onto monsters that don't have them. For example, I run Jefuty's Crusader and other vanilla skins, while running Xelsword's on the Man-At-Arms.

This works for every class except Transformation classes, Abomination or Modded, which may require additional attention. I will describe such as well, have no fear.

Requirements

Do not be alarmed. For basic porting of heroes onto one another or onto monsters, you merely require simple text editing. ...I guess I can recommend Notepad++ [notepad-plus-plus.org], as it makes the whole process much easier.

For Transformation Classes, however, you will require Spine if you have money to burn, or Dragonbones. I do not, so this guide will instruct on using Dragonbones to port Transformation classes.

Additionally, if you wish to port audio as well as visual assets, you will need a list of vanilla audio references[www.nexusmods.com] which comes neatly packaged inside a guide for such, but I will touch on the basics here as well.

Step 1: BACK UP EVERYTHING.

Copy both the host and donor's folders, all of it, and store them separately just in case.
It's never totally safe to delete your backups, but you should at least hold onto them until you've seen your efforts working in-game like you want them.

In the event you do lose something, and you have installed mods directly into the game files making verifying the game cache difficult, you can copy the affected areas somewhere else, verify the cache, secure the vanilla files you wish to recover, then paste your modded install back onto the fresh install.
Be warned that doing so will also verify your workshop mod folder, so if you've made manual changes there, you should back them up too.

Step 1.5: Transformation Classes

Obviously skip this if you're not trying to port one.
So, transformation classes are annoying. They will have two sets of animations for anything they can do in both forms, so Combat, Defend, Heroic/Afflicted, and (if applicable) Riposte.
Non-transforming classes will get confused, as they look for specific animation names that do not exist in a transformation class... usually, some mod classes do indeed have their 'human' form use the default animation names and it just WORKS.

The Dragonbones guide has more detailed instructions, but there is a better method. Simply run the animation through the converter, open the resulting .Json file with a text editor, then rename an animation to the default.
Attack, Combat, Defend, Death... the generic version. Then, convert the .Json back into a .Skel file, and then only replace the altered skeleton file, and you'll skip all of Dragonbone's weirdness regarding static image scaling and just have the edits you want.

Now, as for porting other heroes onto transformation classes... It's still not fully clear how the game decides what animation to call for when transforming. Currently, your options are binary: You can port normally, which will break the Transformation animations, but the class will otherwise function, or you can put the following line at the beginning of the .art file;
display_modifier: .anim_override (Formname)
You can theoretically use this to port transformation classes even easier, though I have not tested this. The downside is that the class will be unable to visually transform. They will play their animation, their moves will change, but they will remain in the specified form visually, and will repeat their initial animation when transforming back.
It's a choice between which error you want, but the demand for porting transformation classes onto other transformation classes is pretty low, so it's not usually a problem. ...Usually.

Step 2: Renaming the files

When porting, you want to replace the donor's classname with the host's in the names of the files
The files you wish to rename are all of the donor's .atlas and .skel files in both the /anim and /fx folders. Additionally, rename the (classname)_# folders, the roster portraits inside them, and the guild background.

Optionally, you can rename the ability icons in the same way. It is recommended, as it helps the host feel less like itself with a new skin and more like the donor. The camping icons are not stored in the Heroes\(Classname) folder, but in the raid\camping\skill_icons folder, should you wish to change them as well.

Do not rename the .pngs in the (classname)_#\anim folders. When the game attempts to render a sprite, it looks for (Hostname).skel, which then looks for (Hostname).atlas, which both then look for (Donorname).png. The Atlas is unencrypted and can be told better, but the Skeleton is not, and would need to be decompiled and recompiled to make a simple name change, so just Do not touch the .pngs and everything just WORKS.

Step 3: The .art files

All right, this is the !FUN! part. I apologize in advance for asking you to be creative.
You'll want to open up the .art files of both the host and donor, and replace the host's .anim, .fx, and .targchestfx entries with the donor's.
You do not have to replace everything. There are universal .fx like 'blood_splatter' that can be loaded anywhere, but all class-specific .anim and .fx should be replaced. Target .fx can be kept, if wished, but remember them if you do for the next step.
Do not forget the friendly fire entry and (if applicable) the riposte entry.

If you are porting onto a monster, keep in mind that they have three separate .art files in their (Monstername)_# folders, all of which say literally the same thing, so you just have to edit one and then copy/paste its contents into the other two. If you're feeling extra creative, you can in fact change the animations for monsters in different difficulty dungeons, though keep in mind you cannot change their combat, defend, and dead sprites between versions.

Step 4: Implementation

There are two ways to install your modified files: Directly, or through the mod system.

Directly is fast, easy, and dangerous, as overwriting vanilla or workshop mod files can be risky. Vanilla is obvious, clear out the host's .anim, skin folders, and other things that would be replaced, and move in the donor's files, leaving behind their .art and .info files. If you chose to keep some of the host's target FX during the previous step, just leave the host's FX folder in place, it isn't necessary to split hairs.

When porting onto monsters, move the \anim, \fx, and one of the (classname)_#\anim folders into the monster's folder, clearing out the host's files as normal. None of the other data is required, so you might have wanted to read the entire guide first before actually starting your work.
When overwriting mod assets, you can find them in steamapps\workshop\content\262060. The folders within will be ID'd and not named, so going to the mod page, right-clicking anywhere that isn't a link, selecting 'Copy Page URL,' and then pasting it into a blank notepad will give you the ID.

Why Steam no longer has the address bar at the top, only higher beings can tell.

When doing this, remember to delete the Modfiles.txt document in the main mod folder. It does nothing but prevent the game from loading unauthorized files in the mod folders, and will force the game to ignore the .pngs if left alive. Keep in mind that, if the mod updates, it'll replace the file. I honestly don't recommend doing this because of that, either move it to the manual \mods folder and unsubscribe from the mod to keep the workshop from auto-updating it, or use the mod system.

The mod system is safer, but requires a little more work. Basically, you want to create a new folder in the DarkestDungeon\mods folder, copy the default .png into it, and then copy a project.xml file from another mod into the folder.
From there, recreate the file system from the base game treating the mod folder as \DarkestDungeon, so heroes\(Classname) for heroes, monsters\(monstername) for monsters, and move over the modified files as before.
Open the .xml file and change the name to something you'll recognize. The other data doesn't need to be changed... probably. 90% sure.

Then, when starting a game, you should find the mod at the top, as the game loads mods chronologically with manual installs at the top. You can then enable it and play it like any normal mod, without having to overwrite files. ...You should still backup the files, though, just in case.

Step 4.5: Porting sound

Ok, first off, AAAAAAHHH.
Secondly, the guide in the link to the vanilla sounds I posted[www.nexusmods.com] covers this, but to be brief...
1: Create a (Classname).heroes.guid_overrides.json file.
2: Add at least one entry for every move you want to change. It should look something like this[staticdelivery.nexusmods.com].
Remember that all moves need the 'miss' entry, even friendly ones that can't miss.
3: Replace the override addresses with the entries found in the massive list you can download from the linked guide. Be very afraid.
4: Contemplate your sanity. Ask yourself if this was worth the cost. Stare into the face of god, and walk backwards.

Step 5: Testing and cleanup

To test your modifications, start a new game with the Full Roster Start Mod to quickly get access to whatever vanilla class you chose, and the disabled core heroes mod when testing a modded class, to ensure the modded class appears in the stagecoach on the first week. It is recommended to run the latter with the former, so you can go into the tutorial dungeon with whatever team comp the modded class needs.

Now that you have ensured your mod works, you can safely dispose of your backups, should you need the space. Again, it is never safe to get rid of your backups when you do not have the original, unmodded files available, but it's also not the end of the world if you do end up regretting it.
If you're a neat freak, you can safely remove .atlas, .skel, and .pngs not referenced by the .art file.

Q&A

Q: Can monsters be ported onto heroes?
A: No. Monsters do not have idle or walking animations, and making them requires actual talent and paid software.

Q: Game Crashed.
A: Check the .art file for typos, missed entries, or other silliness.

Q: White blocks, what's happening?
A: Do not. Rename. The PNGs.

Q: This is all too complicated, do you have an easier method?
A: I'll take requests and do the work myself. Ask for sound porting at your own peril.

Q: Nice attitude, no one was requesting or demanding anything, just asking if someone would...?
A: You get what you pay for.

Q: But you aren't being paid?
A: And yet I'm offering my help anyway, what a steal! ...Stop looking in my mouth.

[S. Agent Gadriel]

The error isn't localized to LL and as far as I know, it isn't intentional in any way.

[xiangyu120596]

I already tried all of these one weeks ago. Thought it's some limitation for new member.

[S. Agent Gadriel]

...That error doesn't seem to be localized to Loverslab. Refreshing the page and/or clearing your cache is supposed to fix it.

[xiangyu120596]

Thanks, I completed it.

Did you meet the error of reply when you first register in the loverslab? Like "[[Template forums/front/topics/topic is throwing an error. This theme may be out of date. Run the support tool in the AdminCP to restore the default theme.]]"

[S. Agent Gadriel]

Correct, that is how it works for most things.
Defend sprites have to have Defend Skeletons, though, because they need both 'Defend' and 'Death' animations.

[xiangyu120596]

So if I want to use investigate anim as dead anim, I just need to rename the flagellant.sprite.investigate.skel as ghoul.sprite.dead.skel and flagellant.sprite.investigate.atlas as ghoul.sprite.dead.atlas?

[S. Agent Gadriel]

Do not. Rename. The .Pngs. At all. In any way.

If you wanted to replace the Ghoul with a Flagellant skin, I don't think there would be a place for their investigate sprite. I don't know what you're talking about with a 'hash' and it's not necessary.

Replace 'Flagellant' in the names of the .atlas and .skel files with 'Ghoul,' move them and a set of Flagellant .pngs to the .anim folder. Do the same with the /fx folder.

Then, go into the .art file and change the attack and fx names to flagellant attacks. So, 'Attack_Claw,' 'Rend,' and 'Blood_splatter' become 'Attack_Punish,' 'Punish,' and 'Punish_Target'... for example.

Repeat with the other two attacks, then copy the .art file's contents onto the other two, since they're identical, and it'll just work.

You shouldn't be editing the contents of the .atlas or .skel files. You don't need to, and it adds so much more complexity and room for error to simply change the names of the .pngs to look cleaner.

[xiangyu120596]

"When the game attempts to render a sprite, it looks for (Hostname).skel, which then looks for (Donorname) .atlas, which both then look for (Donorname) .png."
Does this also means that we should not change the name of atlas because (Hostname).skel will look for (Donorname).atlas and we can not modify skel file?

[xiangyu120596]

Because the atlas file include the name of original .png file. Do you mean I shouldn't change it?

[xiangyu120596]

I want to transfer a flagellant skin to ghoul, and use the "investigate" as dead anim, what should I change for flagellant.sprite.investigate.png? What does hash in skel file meaning for? The name of class or the name of both class and skill?