Documentation: In progressOffline copy from ModDocs. Source links remain clickable.
Dwarf Fortress modding
Dwarf Fortress exposes much of its content as raw text definitions. A mod can add creatures, items, plants, materials, reactions and graphics without editing the original files. This page targets the current v50+ mod format rather than the old practice of changing vanilla raws directly. The Dwarf Fortress Wiki modding guide documents the layout and tokens.
Quick start: make a minimal mod folder with
info.txtand one small raw-file change, enable it for a new world, and inspecterrorlog.txt. Keep the first test separate from a valued fortress because world generation incorporates selected mods into the save.
Understand the two copies of a mod
The source mod belongs in the game's /mods/ directory, in either the AppData or portable layout appropriate to your installation. Dwarf Fortress copies it into /data/installed_mods/ when it is installed. Editing /mods/ may not update the installed copy until you remove the old copy or advance the compatible version metadata. That explains many apparent "the game ignored my edit" failures. See the wiki's mod-format overview and modding pitfalls.
The small structure below follows the info.txt reference:
MyFirstMod/
info.txt
objects/
item_my_first_mod.txt
graphics/ and other folders are added only when the mod needs them. Begin with the text route so art does not obscure loading problems.
Write metadata first
The wiki lists unique ID and version tokens for info.txt. For a first private experiment, use a unique ID and integer compatibility version. A minimal pattern is:
[ID:myname_first_mod]
[NUMERIC_VERSION:1]
[DISPLAYED_VERSION:1.0.0]
[EARLIEST_COMPATIBLE_NUMERIC_VERSION:1]
[EARLIEST_COMPATIBLE_DISPLAYED_VERSION:1.0.0]
[AUTHOR:Your Name]
[NAME:My First Mod]
[DESCRIPTION:A small raw-definition experiment.]
The token reference explains how the numeric values control compatible updates. They are not decimals. Do not reuse an ID from another mod or a vanilla_ prefix. Confirm that the mod appears in the game's mod selection before adding a large object file.
Add or alter a raw definition
Read a related vanilla example from /data/vanilla/, then create your own file under objects/. The raw-file reference explains the initial file identifier, [OBJECT:...] category and subsequent token entries. Give every new object a namespaced identifier so it cannot collide with another mod. Start with an item or reaction whose required tokens you can check in the modding guide; a new item definition alone may not make it craftable until an entity or reaction permits it.
For changes to existing content, the current wiki recommends [SELECT_...] where possible. It patches an existing object without replacing its entire definition. [CUT_...] removes an object for later definitions but is more disruptive. These operations apply only to supported base object categories, so check the SELECT/CUT section rather than assuming every sub-token can be deleted. Avoid editing the original vanilla raw; game updates and other mods can overwrite or conflict with that change.
Test in a new world and diagnose
Enable the mod for a new world, generate it, then test the object in game. The wiki notes that selected mods become part of the generated world's save, so enabling a new raw mod for an existing world is not equivalent to a new-world test. Keep a disposable test world and a record of the mod's numeric version. On every load, inspect errorlog.txt in the game folder. If an object is missing, check that the installed copy contains the latest file, the initial raw-file identifier matches the file, all referenced IDs exist, and a civilization or reaction actually exposes the item.
Publish only your own mod files and describe the supported game version, dependencies, load-order assumptions and whether a new world is required. For graphics, consult the graphics reference and verify the sprite mapping on several objects, not just the title screen.
This guide is unfinished: it covers the format and a first-test workflow, but it does not yet include a locally tested full item/reaction pair, creature graphics pipeline or Workshop upload walkthrough.
Sources / References
External project and documentation links cited in this guide. Check the upstream release and version before following version-sensitive steps.