Introduction and Overview

DFHack is a Dwarf Fortress memory access library, distributed with a wide variety of useful scripts and plugins.

The project is currently hosted at https://www.github.com/DFHack/dfhack, and can be downloaded from the releases page.

All new releases are announced in the bay12 forums thread, which is also a good place for discussion and questions.

For users, it provides a significant suite of bugfixes and interface enhancements by default, and more can be enabled. There are also many tools (such as workflow or autodump) which can make life easier. You can even add third-party scripts and plugins to do almost anything!

For modders, DFHack makes many things possible. Custom reactions, new interactions, magic creature abilities, and more can be set through Scripts for Modders and custom raws. Non-standard DFHack scripts and inits can be stored in the raw directory, making raws or saves fully self-contained for distribution - or for coexistence in a single DF install, even with incompatible components.

For developers, DFHack unites the various ways tools access DF memory and allows easier development of new tools. As an open-source project under various copyleft licences, contributions are welcome.

Installing DFHack

DFHack is available for the SDL version of Dwarf Fortress on Windows, any modern Linux distribution, and Mac OS X (10.6.8 and later). It is possible to use Windows DF+DFHack under Wine on Linux or OS X.

Most releases only support the version of DF mentioned in their title - for example, DFHack 0.40.24-r2 only supports DF 0.40.24 - but some releases support earlier DF versions as well. Wherever possible, use the latest version of DFHack built for the target version of DF.

Installing DFhack involves copying files from a release archive into your DF folder, so that:

  • On Windows, SDL.dll is replaced
  • On Linux or OS X, the dfhack script is placed in the same folder as the df script

Uninstalling is basically the same, in reverse:

  • On Windows, replace SDL.dll with SDLreal.dll, then remove the DFHack files.
  • On Linux or OS X, remove the DFHack files.

New players may wish to get a pack with DFHack preinstalled.

Getting started

DFHack basically extends DF with something similar to the console found in many PC games.

If DFHack is installed correctly, it will automatically pop up a console window once DF is started as usual on Windows. Linux and Mac OS X require running the dfhack script from the terminal, and will use that terminal for the console.

  • Basic interaction with dfhack involves entering commands into the console. To learn what commands are available, you can keep reading this documentation or skip ahead and use the ls and help commands.
  • Another way to interact with DFHack is to set in-game keybindings for certain commands. Many of the newer and user-friendly tools are designed to be used this way.
  • Commands can also run at startup via init files, on in batches at other times with the script command.
  • Finally, some commands are persistent once enabled, and will sit in the background managing or changing some aspect of the game if you enable them.

Troubleshooting

Don’t panic! Even if you need this section, it’ll be OK :)

If something goes wrong, check the log files in DF’s folder (stderr.log and stdout.log). Looking at these might help you - or someone else - solve the problem. Take screenshots of any weird error messages, and take notes on what you did to cause them.

If the search function in this documentation isn’t enough and the DF Wiki hasn’t helped, try asking in: