Intro
This guide is meant to convey different methods of "compressing" mods that change or alter base game content, by documenting actual examples of mods I found on the workshop and compressed myself.
See, the problem is a lot of mods, will make small changes to base game content, like for example changing the max age of a creature, by cutting and re-pasting the entire creature's data, just to make that one small change.
This is almost always not necessary, and will only cause potential for conflict, since any mods that affect the same creature, loaded before the mod that changes the age, will get replaced by the time the game loads. Also if a future patch makes a small change to the base creature, those changes will need to be updated in the mod to actually work in the game, which could be problematic if a mod gets abandoned or the creator doesn't have time.
It is often possible to make these changes using one or two lines of modding code, which just apply the changes we want to the creature. This means any other mod, that doesn't change that one specific attribute we want to modify, wont conflict. In addition any patch changes to the base game will pass through, will not require any updates from the mod author, and the mod will continue to work indefinitely, unless there are massive underlying changes to the way the base game reads code (unlikely) that would break every mod in existence.
Think of it like a PC upgrade, this guide will teach you how to replace that single stick of ram, without needing to demolish and rebuild your PC from scratch.
Why am I making this guide?
Most of these functions are already documented on the Dwarf Fortress wiki, but you have to dig around to find them all and most of the information is oriented towards creating new content rather than modifying existing content, including the examples they show. Also there is at least one way of modifying content that was not well known of before. (See syndromes)
Also I just want to make it clear, this is in no way meant to talk smack about the mod's or the authors of said mods that wrote them. In fact I appreciate them all and subscribed to the majority of them, and I like I said, these types of tweaks and how to make them in a compressed manner are not well documented. Using them as examples is just the best way I can teach what I've learned, while also documenting what I did to learn this stuff in case I forget later, lol.
Removing Creature Tags - Kea Thievery
In this example, there is a mod that exists in order to remove the item thievery behavior from the Kea bird creatures. If you are not familiar, in the base game, these birds will steal items lying around from your fortress, and because they can also fly away, they are really good at getting away with it. This mod changes that behavior as a QOL tweak.
In order to do this, the original mod uses the "[CUT_CREATURE:BIRD_KEA]" command to remove the entire creature's data from the base game, then recreates the Kea from scratch, just without the two tags that cause this behaviour "[CURIOUSBEAST_EATER]" and "[CURIOUSBEAST_ITEM]"
The original data from Vanilla is on the left, the mod's data is on the right:
Link to Diff Checker: https://www.diffchecker.com/XLzgIn8y/
How to Compress This Mod:
This is the compressed version of the mod: https://pastebin.com/m8fXdpbP
Line #1 is just the name of the file for human eyes, the game does not read this afaik. Technically this can be anything but the og mod author kept it the same as the vanilla file, so I left it the same too. useful to keep since it references the original vanilla file that has the Kea data, "creature_birds_new.txt"
Line #3 is how we tell the game we are about to feed it creature data. Any file modifying or adding creatures needs to start with this.
Line #5 is how we "select" the vanilla content that we want to modify, instead of cutting and replacing the whole creature. You can use this "SELECT_CREATURE" command to load any creature data loaded by the base game or another mod, by changing the name "BIRD_KEA" to the name of the creature you want to modify. All you need to make sure of is the content you want to modify is loaded before your mod in the load order.
Lines #6 & #7 use the "CV_REMOVE_TAG" function to remove the problem trait tags from the vanilla Kea. This function does exactly what it sounds like, and just cuts out the tag you name after the colon. Just make sure you spell the name exactly right.
Line #8 "APPLY_CURRENT_CREATURE_VARIATION" is the function we use to "close" the edit and tell the game to apply the changes we just made to the Kea. We don't need to always use this function for editing creatures, it is kind of situational, but you definitely need to use it when removing tags for the change to take affect. Take note of the specific tag we use, however, as there is a similar function "APPLY_CREATURE_VARIATION" that has a different purpose, and is instead used for copying already defined creature data into the current creature.
Notes on CV
Also just to clarify, a "Creature Variation" or "CV" is basically the way the game defines each distinguishing category of a creature. The Kea bird is itself a variation of the base creature template, as all other creatures are. Each gender is also a Creature Variation of the base creature, as are the Giant creatures and Animal people, with the genders of those being sub variations of those creatures respectively.
I will try to show examples of modifying one of those sub variations later in the guide, but the point I want to convey is that how it is used in this example, it applies to the "BIRD_KEA" as a whole because thats what we selected with line #5. Because the Male and Female genders of the Kea, inherit their information from the base creature, they inherit these changes equally. Because the "GIANT_KEA" and "KEA_MAN", inherit their tags from the "BIRD_KEA" creature, the changes made in both versions of this mod will also apply to those creatures.
Adding Creature Tags - War & Hunter Training
There are a number of mods out there that modify creatures by making them war and/or hunting trainable, so they can be used as guard animals or hunting animals respectively. Since there are many mods out there, and the changes needed are so simple, I will not be using a specific example, and instead just showing how to make Cats trainable as War Cats and Hunting Cats.
The entire mod: https://pastebin.com/zyEU4pRC
As you can see, adding tags to a base creature is super simple, no special functions needed. You just select the creature and add the tag below it, and the game will append that tag to the creature. As long as you aren't making any other changes, you don't need to use the apply creature variation commands to close out the edit.
You can add many any other tags that can normally be applied to a base creature this way. You can also specify War or Hunting training only, by using "TRAINABLE_HUNTING" and "TRAINABLE_WAR" tags respectively. Just putting "TRAINABLE" will add both at the same time.
More info and list of creature tokens: https://dwarffortresswiki.org/index.php/Creature_token
This may not work for every tag BTW. I can't tell you all of the ones that will or wont work this way, but I can help you in the comments and update the guide with new examples if you find exceptions to this.
BTW, "Tokens" and "Tags" are essentially the same thing, for the purposes of this guide.
Modifying A Syndrome - Cave Spider Bites
Now for this example, we have a very useful mod that exits to make it so that the syndrome caused by Cave Spider bites, actually will expire instead of lasting forever. If you are not familiar, the cave spider vermin in the undergrounds can bite your citizens and pets, which causes a permanent dizzyness affect to be applied that causes the creature to occasionally weaken and move slower. This can be a real problem for your Dwarves, as vermin aren't always visible on the game screen and they can be very sneaky as a result. Plus the poison lasting forever is a bit OP.
Also from a game data perspective, a Syndrome usually refers to a poison that can be applied through an attack (in this case the spider bite) but technically can refer to many different types of temporary effects and can be applied in many different ways. Check the DF wiki page on Syndromes for more info. https://dwarffortresswiki.org/index.php/Syndrome
Now this is a tricky modification to make, because you cant just overwrite the old syndrome with new stats, because trying to do so will only add a second syndrome while leaving the original one as a permanent effect, even if you have the same syndrome name for both. Also this is a really cool tweak I found, because in my searching I couldn't find any examples of something like this and found several sources that suggested doing this was impossible without replacing the entire creature data with the Cut command and recreating the entire creature data.
This is a pastebin of the "SPIDER_CAVE" creature from the vanilla files: https://pastebin.com/Q4Hki1vm
The section we care about starts at line #33 where the creature data begins to define the venom, however what we really need to focus on is line #42 where the Syndrome attached to that venom, which creates the actual effect we want to modify is defined.
The syndrome is created from several lines of code that define how it functions. We start with the name of the syndrome at #43, then #44 which is the class of the syndrome (defines type), line #45 that makes cave spiders immune to their own syndrome, line #46 that defines how it is applied (injected via the bite) then finally at #47 the line that defines the effect applied.
You can see that there is the effect the Syndrome causes named "CE_DIZZYNESS" with several values that define how the Dizzyness effects the target. There is SEV for Severity, along with a numerical value defining the severity, PROB with the number representing the probability it will apply when a successful poisoning bite is made, the RESISTABLE tag means that the target's Disease Resistance can hinder the effect, and finally the values defining duration.
Normally a syndrome has 3 duration tags with values, "START" "PEAK" and "END" representing the time it takes in game "ticks" for the effect to start, for the effect to reach peak strength and finally for it to fully wear off. Now as you can see in the vanilla data above, there is no "END" tag and no value for it as a result, which as the comment in the file suggests, means the syndrom will never end.
We need to add that value back in, and to do so we need to use the "CV_CONVERT_TAG" function, which is incredibly useful for modifying complex and hard to target pieces of game data like this. I have tried many other methods and this is the only way to modify the syndrome, that I have found, without replacing the entirety of the creature's data which is what the original author had to do.
The compressed version of this mod: https://pastebin.com/y1ZCigEM
We start with line #1 which is again just the human readable name of the file. In this case it is what the original mod author set it to, but the cave spider's data is actually located in the "creature_subterranean.txt" file.
Line #3 again just tells the game we are about to feed it creature data and is where the game starts caring about whats in the file. If you haven't noticed, the game only reads stuff in the brackets []
Line #5 we again tell the game to select the creature for editing, in this case it's game file name is "SPIDER_CAVE"
Line #6 we have the "CV_CONVERT_TAG" function, which is basically a "find and replace" function of the game that allows us to change specific lines of text by using a "search" string combined with a "replace" string, and it works in the same way find and replace works in notepad++ or excel or other apps that have it. Once we start this function, we need to provide the game with 3 more sub-functions to perform this task.
Line #7 "CVCT_MASTER" is a function to narrow the range of our search. This is an optional tag that sets the area we are searching within, using the next function. This is useful in case you might get multiple matches on the string you are trying to find within the same creature's data. If you leave it blank, which we did in this case, it will search the entirety of the "SPIDER_CAVE" entry for the string we are about to give it, which is ok for this purpose since it is a unique string that only shows up once. Even if you don't set a value here, you still need to add this function name and leave it blank as we did in this example, for this to function properly.
Line #8 "CVCT_TARGET" is our "find" string. This is the string of text we are telling the game to select, which will then be changed with the next function. You can give it the full line, or just a portion of a line of code. In this case, we are selecting only the last half of the line the "CE_DIZZINESS" line, where we need to append the "END" tag and value.
Line #9 "CVCT_REPLACEMENT" is our replacement text that will overwrite the text we just selected at line #8. For our replacement, we add back the line we just selected, so it continues to exist after the change, while adding "END:200" to give the syndrome an "end" time so it will actually wear off eventually.
Finally with line #10, we use the "APPLY_CURRENT_CREATURE_VARIATION" function to close out the edit we just made and make it take effect on the game data. This is another situation where you have to use this function to make the game actually accept the changes you are making.
To reiterate how this function works as a search and replace, here is a screenshot of notepad++ using the search and replace function to change the game file itself. This is what we are basically telling the game to do by using this function, so hopefully it helps make more sense of just how powerful this function is for tweaking existing creature game data.
Now in closing this section, I want to make sure that I point out this function only works for creature data. You can not use "CV_CONVERT_TAG" on other types of game data, as far as I am aware. I have not yet found out how to perform a function like this on other types of game data, so if you are reading this and have that info or any clues worth sharing, please let me know in the comments so I can work on documenting it too in this guide.
More Info Coming Soon ™
I want to go ahead and publish this guide now with what I've added to it so far, but will be making a point to add more examples and sections that expand on what I've already covered and go into more ways game data can be modded with these "surgical" edits.
My current intent is to add at least a couple more sections within the next day or two, with more beyond that as I do more discovering, modding & compression myself.
Bonus Stuff
This section is for stuff unrelated to the main purpose of this guide, but might still be super useful for people interested in modding the game.
Notepad++: https://notepad-plus-plus.org/
- A great free replacement for notepad, excellent for modding game files for Dwarf Fortress, just in case you weren't already familiar.
Notepad++ Highlighting Syntax: http://www.bay12forums.com/smf/index.php?topic=158324.0
- Use this to get Notepad++ to recognize DF code and highlight it in the same way it does for programming languages like C++ and stuff.
DF Wiki Pages - These have a lot of additional info useful relevant to what I'm covering.
Creature Variation tokens: https://dwarffortresswiki.org/index.php/Creature_variation_token
List of Creature Tokens: https://dwarffortresswiki.org/index.php/Creature_token
Creature Castes (Sub-types): https://dwarffortresswiki.org/index.php/Caste
Mods I have made: I have made a few DF mods making simple efficient changes using the methods described in this guide. Please feel free to learn from my examples and use anything you find for your own purposes!
https://steamcommunity.com/sharedfiles/filedetails/?id=3237798777
Source: https://steamcommunity.com/sharedfiles/filedetails/?id=3165135531
More Dwarf Fortress guilds
- All Guilds
- I HATE CUTEBOLDS, I WANT THEM TO DIE
- Finding Lairs [Adventure mode]
- Kosten effizienter Start [v0.1]
- Default Oldschool World Options
- World Map Key/Legend
- A humble guide - how to bury your dwarves.
- Bringing the Old Music Back to Dwarf Fortress
- Soap tutorial
- Dwarf Fortress - Orchard Guide