Modding - Revision history

Quietust at 13:38, 27 January 2026

2026-01-27T13:38:24Z

Putnam3145: /* Basics of DF modding */

2026-01-27T11:05:05Z

Basics of DF modding

Putnam3145: /* Resource Overview */ it's noooot quite right to call it the "SDL2 repository", since it's the entire, like, renderer and input section of the game's code, including how it actually places tiles

2026-01-27T11:03:51Z

Resource Overview: it's noooot quite right to call it the "SDL2 repository", since it's the entire, like, renderer and input section of the game's code, including how it actually places tiles

DPhKraken: /* Basics of DF modding */ Full mod folder structure as of the Lua update

2025-10-07T18:51:28Z

Basics of DF modding: Full mod folder structure as of the Lua update

Zymlex: Wrong path

2025-09-07T14:14:16Z

Wrong path

DPhKraken: /* Resource Overview */ Add Putnam's DFRaws repository

2025-08-08T21:25:52Z

Resource Overview: Add Putnam's DFRaws repository

DPhKraken: /* Basics of DF modding */ Namespace your mods to prevent raw duplication errors

2025-08-01T22:26:27Z

Basics of DF modding: Namespace your mods to prevent raw duplication errors

DPhKraken: /* Basics of DF modding */ Link to file page to be more OS-agnostic

2025-07-22T21:26:34Z

Basics of DF modding: Link to file page to be more OS-agnostic

DPhKraken: /* Basics of DF modding */ Non-portable directories are important

2025-07-22T21:23:35Z

Basics of DF modding: Non-portable directories are important

Silverwing235: snip-snip case

2025-06-13T21:58:56Z

snip-snip case

@@ Line 33: / Line 33: @@
 ; Modding tools
 * There are several specialized [[Utilities#Modding tools|utilities]] that assist in modding efforts. There is [http://www.bay12forums.com/smf/index.php?topic=28829.0 a longer list of them] on the [[Bay 12 Forums]].
-:*[https://putnam3145.github.io/helper Material Helper] by [[User:Putnam3145]], for calculating [[Material definition token|material properties]].
+**[https://putnam3145.github.io/helper Material Helper] by [[User:Putnam3145]], for calculating [[Material definition token|material properties]].
-:*[https://jose96xd.github.io/DF_Tools/index.html DF Tools] by [[User:Jose96xd]], a collection of web tools.
+**[https://jose96xd.github.io/DF_Tools/index.html DF Tools] by [[User:Jose96xd]], a collection of web tools.
-:*[https://dffd.bay12games.com/file.php?id=1738 DFLang] (by Igfig) and [https://dffd.bay12games.com/file.php?id=7174 LangCreate] (by Talvieno) for generating [[Language token|translations]].
+**[https://dffd.bay12games.com/file.php?id=1738 DFLang] (by Igfig) and [https://dffd.bay12games.com/file.php?id=7174 LangCreate] (by Talvieno) for generating [[Language token|translations]].
-:*[http://www.bay12forums.com/smf/index.php?topic=158930.0 Dwarf Portrait] by Rose, for visualizing unit [[Body token|bodies]].
+**[http://www.bay12forums.com/smf/index.php?topic=158930.0 Dwarf Portrait] by Rose, for visualizing unit [[Body token|bodies]].
 * Text editors are used in all areas of modding. Use a good text editor to edit files and search into multiple files (like the free [https://notepad-plus-plus.org/ Notepad++] for example) or more advanced editors capable of highlighting and formatting the displayed text (like [[Utilities#DF RAW Language server|DF RAW Language server]])
 * Image editors are needed for doing custom graphics. [https://www.getpaint.net/ Paint.NET], Photoshop and GIMP are the most used, but whatever supports the .png format will work.
@@ Line 49: / Line 49: @@
 ; [[Graphics|Graphics files]]:
-The `/data/art/` subfolder of Dwarf Fortress is used to store user-customizable [[tileset]]s while mods can include their own [[Graphics#Premium Graphics|graphics files]].
+The ``/data/art/`` subfolder of Dwarf Fortress is used to store user-customizable [[tileset]]s while mods can include their own [[Graphics#Premium Graphics|graphics files]].
 ; [[Reaction]]s:
@@ Line 57: / Line 57: @@
 ; [[Audio|Sound and Music files]]:
-All sound and music files used by ''Dwarf Fortress'' are stored in the [https://en.wikipedia.org/wiki/Ogg .ogg] format within the <code>/data/sound/</code> subfolders. Mods can load new audio files. You can also change some of the definitions of when certain musical cues are played, using available [[music token]]s and [[sound token]]s in the raw files.
+All sound and music files used by ''Dwarf Fortress'' are stored in the [[wikipedia:Ogg|.ogg]] format within the <code>/data/sound/</code> subfolders. Mods can load new audio files. You can also change some of the definitions of when certain musical cues are played, using available [[music token]]s and [[sound token]]s in the raw files.
 An example mod by [[User:Putnam3145]] is available on [https://github.com/Putnam3145/dwarf-fortress-example-sound-mod Github].
@@ Line 267: / Line 267: @@
   [CULL_SYMBOL:ALL:SUBORDINATE]
   [CULL_SYMBOL:ALL:EVIL]
   [CULL_SYMBOL:ALL:FLOWERY]
   [CULL_SYMBOL:ALL:NEGATIVE]
@@ Line 505: / Line 504: @@
 It's evident that the process of creating and editing castes is comparable to the modifications we were making to tissues and materials earlier: A caste is declared, and modifications to the base creature are made. Declared castes can be selected and subsequently modified, again, just like tissues and materials.
-In this case, each caste is declared, given its own name, and a {{token|POP_RATIO}}, which determines how commonly a birth results in that caste - for every 10000 workers born, there'll be an average of 1000 soldiers, 5 drones and one queen. You've probably also noticed that the "DRONE" and "QUEEN" castes have the {{token|MALE}} and {{token|FEMALE}} tokens respectively - these tokens determine how breeding works. A creature without both a {{token|MALE}} caste and a {{token|FEMALE}} caste will be unable to breed (no asexually reproducing creatures yet, unfortunately). As they lack {{token|FEMALE}}, the workers and soldiers are unable to breed with the male drones.
+In this case, each caste is declared, given its own name, and a {{token|POP_RATIO}}, which determines how commonly a birth results in that caste - for every 11,006 workers born, there'll be an average of 1000 soldiers, 5 drones and one queen. You've probably also noticed that the "DRONE" and "QUEEN" castes have the {{token|MALE}} and {{token|FEMALE}} tokens respectively - these tokens determine how breeding works. A creature without both a {{token|MALE}} caste and a {{token|FEMALE}} caste will be unable to breed (no asexually reproducing creatures yet, unfortunately). As they lack {{token|FEMALE}}, the workers and soldiers are unable to breed with the male drones.
 After this, there are some modifications to bodyparts. In this case, the drones have wings and the {{token|FLIER}} token, which the other castes lack. It's entirely possible for creatures of different castes to have completely different body structures, even to the extent that they don't resemble each other at all. If you read the section of this guide that dealt with entities, you may remember a passing mention of multi-creature civilisations and how they don't quite work as you may think they would. The castes system is your workaround. You could create a caste that is, for all intents and purposes, a human, and another caste of the same creature that acts exactly like a giant cave spider, put the creature in a civ, and get a human-spider civ. The only flaw in this approach is that the castes will interbreed and produce offspring of either caste.
@@ Line 573: / Line 572: @@
 First, you'd need a whole new "language_NAME.txt" file, such as "language_LIZARDMAN.txt", along with "language_LIZARDMAN" at the top of the file, followed by ``[OBJECT:LANGUAGE]`` and ``[TRANSLATION:LIZARDMAN]``.  After that, it's just a matter of copy-pasting one of the existing language lists and editing the finished 'translated' word.  That's it! Then just add the translation link to your civ in entity_default.txt and it'll be added to the game on worldgen.
-All raw files use [[Character table|Code Page 437]] encoding, and you should make sure you are editing these files in that format. As many text editors default to UTF-8, some characters with diacritical marks may fail to show properly. Saving one of the default language raw files in this state will overwrite these characters with the Unicode question mark, which will corrupt the file. To fix this  replace the file with a clean one downloaded from the distributed version of DF.
+All raw files use [[Character table|Code Page 437]] encoding, and you should make sure you are editing these files in that format. As many text editors default to UTF-8, some characters with diacritical marks may fail to show properly. Saving one of the default language raw files in this state will overwrite these characters with the Unicode question mark, which will corrupt the file. To fix this, replace the file with a clean one downloaded from the distributed version of DF.
 (Note that the name of the file doesn't actually matter; but it's typical to name the file after a creature if it's exclusive to their civilization.)
@@ Line 779: / Line 778: @@
 }}
-First we define what season(s) the plant may grow in, then we define how frequently this plant is generated in a particular area, followed by how many harvested crop items may come from 1 plant. {{token|PREFSTRING|p}} is what your dwarves [[Preference|like]] about the plant, which in this case is the rounded tops. {{token|WET|p}}{{token|DRY|p}} are the conditions under which the plant can grow. Wet means it can grow close to water, dry means it can grow away from water. This does not mean you can grow the plant on dry stone however. It is just for natural spawning of the plant.<br>
+First we define what season(s) the plant may grow in, then we define how frequently this plant is generated in a particular area, followed by how many harvested crop items may come from 1 plant. {{token|PREFSTRING|p}} is what your dwarves [[Preference|like]] about the plant, which in this case is the rounded tops. {{token|WET|p}}/{{token|DRY|p}} are the conditions under which the plant can grow. Wet means it can grow close to water, dry means it can grow away from water. This does not mean you can grow the plant on dry stone however. It is just for natural spawning of the plant.<br>
-{{token|BIOME|p}} is what [[Biome token|biome]] the plant grows in. {{token|UNDERGROUND_DEPTH:Minimum:Maximum|p}} Is the highest and lowest cavern levels that the plant can appear in if its biome is subterranean. Dwarven civilizations will only export (via the embark screen or caravans) things that are available at depth 1. Defaults to ``0:0`` (surface only).<br>
+{{token|BIOME|p}} is what [[Biome token|biome]] the plant grows in. {{token|UNDERGROUND_DEPTH|p|Minimum:Maximum}} is the highest and lowest cavern levels that the plant can appear in if its biome is subterranean. Dwarven civilizations will only export (via the embark screen or caravans) things that are available at depth 1. Defaults to ``0:0`` (surface only).<br>
-Lastly, {{token|SHRUB_TILE|p}} is the character used for the naturally spawning [[shrub]] of this plant, {{token|DEAD_SHRUB|p}} is the dead shrub character. {{token|SHRUB_COLOR|p}} Is the shrub's color, and {{token|DEAD_SHRUB_COLOR|p}} is, of course, the dead shrub's color.
+Lastly, {{token|SHRUB_TILE|p}} is the character used for the naturally spawning [[shrub]] of this plant, {{token|DEAD_SHRUB|p}} is the dead shrub character, {{token|SHRUB_COLOR|p}} is the shrub's color, and {{token|DEAD_SHRUB_COLOR|p}} is, of course, the dead shrub's color.
 Plump helmet shrubs look like {{Tile|:|5:0}}.
@@ Line 1,049: / Line 1,048: @@
 }}
-{{token|DIM|b}} refers to how large the workshop will be, in this case 3 wide, 3 tall. {{token|WORK_LOCATION|b}} tells where the creature using it (usually a dwarf) will work, numbered from the top right--in this case, ``2:2``, or the middle. Multiple work locations can be defined, even outside the dim.
+{{token|DIM|b}} refers to how large the workshop will be, in this case 3 wide, 3 tall. {{token|WORK_LOCATION|b}} tells where the creature using it (usually a dwarf) will work, numbered from the top left--in this case, ``2:2``, or the middle. Multiple work locations can be defined, even outside the dim.
 {{code|

@@ Line 143: / Line 143: @@
 * When a new world is generated, the mods included are "baked in" and cannot be modified except to be updated—for this, the game checks that the mod used by the save is of a compatible {{token|NUMERIC_VERSION|modinfo}}.
 * There's nothing stopping you from just copying an existing creature/entity/whatever, changing the identifier, and modifying it. This can save you a lot of time, especially when it comes to entities.
 === Modifying the vanilla objects ===

@@ Line 22: / Line 22: @@
 * [[String dump]]
-* [https://github.com/Putnam3145/Dwarf-Fortress--libgraphics-- Official SLD2 repository]
+* [https://github.com/Putnam3145/Dwarf-Fortress--libgraphics-- Source code for Dwarf Fortress's graphics/input/sound]
 * [https://docs.dfhack.org/en/latest/docs/guides/modding-guide.html#dfhack-modding-guide DFHack modding guide]
 * [[Memory hacking]], [[Main:Offset Finding Methods|Offset Finding Methods]]

@@ Line 81: / Line 81: @@
 To make a mod, one must put a folder into the <code>/mods/</code> directory in the game's AppData [[File|folder]] or the portable directory. When a mod is first installed, it is copied to <code>/data/installed_mods/</code> and the game loads all data from the installed copy. Changes are NOT immediately propagated from <code>/mods/</code> to <code>/data/installed_mods/</code>. You can create a new installed copy by deleting the old copy or by incrementing the [[Mod info token|version info]] - see [[modding pitfalls]] for more information. The vast majority of modifications to the game can be done via this method.
-Your mod folder should contain a file named "info.txt" and two subfolders: "graphics" (where you insert [[Graphics set repository|graphics sets]]), and "objects", which contains all the data for, generally, everything in the game that is not hardcoded.
+Your mod folder must contain a file named "info.txt" and subfolders depending on what your mod includes. The majority of mods will want to have an ``objects/`` folder, which can define most kinds of [[Raw file|game content]], and a ``graphics/`` folder, to add [[graphics]].
 The [[info.txt]] is formatted like so:

@@ Line 98: / Line 98: @@
 A mod should have all of these. There are a [[mod info token|few more tokens]], but the above are the important ones.
-Most of the game's vanilla content is in the same format as mods. Many text files can be found in the subfolders of the <code>/data/vanilla</code> folder - these are the [[raw file|raw files]], and using them as a basis for modification is quite easy. For now, we will take a look at one of the existing files. For example, if you open <code>/data/vanilla/vanilla_creatures/creature_standard.txt</code>, it should look something like this:
+Most of the game's vanilla content is in the same format as mods. Many text files can be found in the subfolders of the <code>/data/vanilla</code> folder - these are the [[raw file|raw files]], and using them as a basis for modification is quite easy. For now, we will take a look at one of the existing files. For example, if you open <code>/data/vanilla/vanilla_creatures/objects/creature_standard.txt</code>, it should look something like this:
 {{code|

@@ Line 17: / Line 17: @@
 * [[Mod#Mod format|Mod format]] and [[Game folders and files]]
-* [https://github.com/DF-Wiki/DFRawFunctions Repository of raws and wiki functions]
+* [https://github.com/Putnam3145/DF-Raws/tree/master Official DFRaws repository] and [https://github.com/DF-Wiki/DFRawFunctions Wiki mirror]
 * [[Mod#Publishing on Steam Workshop|Publish on Steam Workshop]]
 * [[Character table]]

@@ Line 129: / Line 129: @@
 * Try to avoid modifying the existing raw files when possible. You should make a mod instead!
-* When adding files, token identifiers are all you need to include to ensure proper references are maintained.  The game searches through all loaded raw files by tokens.  For example, you can add a new pair of leather boots and not even have to add it to a file named ``item_shoes.txt``, but rather your own file, say ``item_shoes_new.txt`` and ensure you have the token listed, ex. ``[ITEM_SHOES:ITEM_SHOES_BOOTS_NEW]``.
+* When adding files, token identifiers are all you need to include to ensure proper references are maintained.  The game searches through all loaded raw files by tokens.
+** For example, you can add a new pair of leather boots and not even have to add it to a file named ``item_shoes.txt``, but rather your own file, say ``item_shoes_new.txt``.
-* When a new world is generated, the mods included are "baked in" and cannot be modified except to be updated--for this, the game checks that the mod used by the save is of a compatible {{token|NUMERIC_VERSION|modinfo}}.
+** All objects must have a unique token identifier. Adding a consistent prefix or suffix to your mod's objects (ie: ``[ITEM_SHOES:ITEM_SHOES_BOOTS_NEW]``) greatly reduces the chance that another mod uses the same token. If two mods define objects with the same token without cutting the other, then they will be incompatible due to [[duplicated raws]].
 * There's nothing stopping you from just copying an existing creature/entity/whatever, changing the identifier, and modifying it. This can save you a lot of time, especially when it comes to entities.

@@ Line 79: / Line 79: @@
 === Basics of DF modding ===
-To make a mod, one must put a folder into the <code>/mods/</code> directory in either ``<user>/AppData/Roaming/Bay 12 Games/Dwarf Fortress/`` or the game's portable directory. When a mod is first installed, it is copied to <code>/data/installed_mods/</code> and the game loads all data from the installed copy. Changes are NOT immediately propagated from <code>/mods/</code> to <code>/data/installed_mods/</code>. You can create a new installed copy by deleting the old copy or by incrementing the [[Mod info token|version info]] - see [[modding pitfalls]] for more information. The vast majority of modifications to the game can be done via this method.
+To make a mod, one must put a folder into the <code>/mods/</code> directory in the game's AppData [[File|folder]] or the portable directory. When a mod is first installed, it is copied to <code>/data/installed_mods/</code> and the game loads all data from the installed copy. Changes are NOT immediately propagated from <code>/mods/</code> to <code>/data/installed_mods/</code>. You can create a new installed copy by deleting the old copy or by incrementing the [[Mod info token|version info]] - see [[modding pitfalls]] for more information. The vast majority of modifications to the game can be done via this method.
 Your mod folder should contain a file named "info.txt" and two subfolders: "graphics" (where you insert [[Graphics set repository|graphics sets]]), and "objects", which contains all the data for, generally, everything in the game that is not hardcoded.