# 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](https://dwarffortresswiki.org/index.php/Modding) documents the layout and tokens.

> **Quick start:** make a minimal mod folder with `info.txt` and one small raw-file change, enable it for a **new world**, and inspect `errorlog.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](https://dwarffortresswiki.org/index.php/Modding#Basics_of_DF_modding) and [modding pitfalls](https://dwarffortresswiki.org/index.php/Modding_pitfalls).

The small structure below follows the [info.txt reference](https://dwarffortresswiki.org/index.php/Info.txt_file):

```text
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:

```text
[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](https://dwarffortresswiki.org/index.php/Info.txt_file) 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](https://dwarffortresswiki.org/index.php/Raw_file) 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](https://dwarffortresswiki.org/index.php/Modding); 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](https://dwarffortresswiki.org/index.php/Modding#Modifying_the_vanilla_objects) 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](https://dwarffortresswiki.org/index.php/Graphics) 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.
