Welcome to DFHack! This guide will help get you oriented with the DFHack systemand teach you how to find and use the tools productively. If you’re reading thisin the in-game quickstart-guide reader, hit the right arrow key or click onthe hotkey hint in the lower right corner of the window to go to the next page.
What is DFHack?¶
DFHack is an add-on for Dwarf Fortress that enables mods and tools tosignificantly extend the game. The default DFHack distribution contains a widevariety of these mods and tools, including bugfixes, interface improvements,automation agents, design blueprints, modding building blocks, and more.Third-party tools (e.g. mods downloaded from Steam Workshop or the forums) canalso seamlessly integrate with the DFHack framework and extend the game farbeyond what can be done by just modding the raws.
DFHack’s mission is to provide tools and interfaces for players and modders to:
expand the bounds of what is possible in Dwarf Fortress
reduce the impact of game bugs
give the player more agency and control over the game
provide alternatives to toilsome or frustrating aspects of gameplay
make the game more fun
What can I do with DFHack tools?¶
DFHack has been around for a long time – almost as long as Dwarf Fortressitself. Many of the game’s rough edges have been smoothed with DFHack tools.Here are some common tasks people use DFHack tools to accomplish:
Automatically chop trees when log stocks are low
Mark all damaged items for trade in a single click
Copy and paste fort layouts
Import and export lists of manager orders
Clean contaminants from map squares that dwarves can’t reach
Automatically butcher excess livestock so you don’t become overrun withanimals
Promote time-sensitive job types (e.g. food hauling) so they are doneexpediently
Quickly scan the map for visible ores of specific types so you can focusyour mining efforts
Some tools are one-shot commands. For example, you can rununforbid all to claim all (reachable) items on the map after amessy siege.
Other tools must be enabled once and then they will run in thebackground. For example, once enabled, seedwatch will start monitoring yourstocks of seeds and prevent your chefs from cooking seeds that you need forplanting. Tools that are enabled in the context of a fort will save their statewith that fort, and they will remember that they are enabled the next time youload your save. You can see which tools you have enabled and toggle their statesin gui/control-panel.
A third class of tools adds information to the screen or provides new integratedfunctionality via the DFHack overlay framework. For example, the sort tooladds widgets to the squad member selection screen that allow you to sort andfilter the list of military candidates. You don’t have to run any command to getthe benefits of the tool, it appears automatically when you’re on the relevantscreen.
How can I figure out which commands to run?¶
There are several ways to scan DFHack tools and find the ones you need rightnow.
The first place to check is the DFHack logo menu. It’s in the upper left cornerof the screen by default, though you can move it anywhere you want with thegui/overlay configuration UI.
When you click on the logo (or hit the Ctrl-Shift-C keyboard shortcut), a shortlist of popular, relevant DFHack tools comes up. These are the tools that havebeen assigned hotkeys that are active in the current context. For example, whenyou’re looking at a fort map, the list will contain fortress design tools likegui/quickfort and gui/design. You can click on the tools in the list, ornote the hotkeys listed next to them and maybe use them to launch the tool nexttime without even opening the logo menu.
The second place to check is the DFHack control panel: gui/control-panel. Itwill give you an overview of which tools are currently enabled, and will allowyou to toggle tools on or off, see help text for them, or launch theirdedicated configuration UIs. You can open the control panel from anywhere withthe Ctrl-Shift-E hotkey or by selecting it from the logo menu list.
In the control panel, you can also select which tools you’d like to beautomatically enabled and popular commands you’d like to run when you start anew fort. On the “Preferences” tab, there are settings you can change, like“mortal mode” (you’ll learn more about this in the next section) or whether youwant DFHack windows to pause the game when they come up.
Finally, you can explore the full extent of the DFHack catalog ingui/launcher, which is always listed first in the DFHack logo menu list. Youcan bring up the launcher by tapping the backtick key (`) or hittingCtrl-Shift-D. In the launcher, you can quickly autocomplete any command name byselecting it in the list on the right side of the window. You can filter the listby command tag, for example, you can see only productivity tools by setting the“productivity” tag to “include” in the filter panel. Commands are ordered by howoften you run them, so your favorite commands will always be on top. You canalso pull full commandlines out of your history with Alt-S or by clicking on the“history search” button.
Once you have typed (or autocompleted, or searched for) a command, othercommands related to the one you have selected will appear in the right-handpanel. Scanning through that list is a great way to learn about new tools thatyou might find useful.
The bottom panel will show the full help text for the command you are running,allowing you to refer to the usage documentation and examples when you aretyping your command. After you run a command, the bottom panel switches tocommand output mode, but you can get back to the help text by hitting Ctrl-T orclicking on the Help tab.
What if I don’t want to be tempted by god-mode tools?¶
DFHack can give you god-like powers over the game. Sometimes, this is necessaryto recover from game-breaking bugs. Sometimes, this is desirable so players cancreate specific role playing environments and situations. Sometimes, this is justfun : )
But sometimes the knowledge that you can just “Armok” your way out of troubledetracts from the game experience. If this is the way you feel, you can hideDFHack’s god-mode tools – they all have the tag “armok” – from the game. Opengui/control-panel and go to the “Preferences” tab. Enable “Mortal mode” tohide all “armok” tools. You can still access them in gui/launcher if you typetheir names in full, but they won’t show up in autocomplete lists, in the outputof ls, or anywhere else. Any global hotkeys that run “armok” tools will bedisabled.
How do DFHack in-game windows work?¶
Many DFHack tools have graphical interfaces that appear in-game. You can tellwhich windows belong to DFHack tools because they will have the word “DFHack”printed across their bottom frame edge. DFHack provides an advanced windowingsystem that gives the player a lot of control over where the windows appear andwhether they capture keyboard and mouse input.
The DFHack windowing system allows multiple overlapping windows to be active atonce. The one with the highlighted title bar has focus and will receive anythingyou type at the keyboard. Hit Esc or right click to close the window or cancelthe current action. You can click anywhere on the screen that is not a DFHackwindow to unfocus the window and let it just sit in the background. It won’trespond to key presses or mouse clicks until you click on it again to give itfocus. If no DFHack windows are focused, you can right click directly on awindow to close it without left clicking to focus it first.
DFHack windows are draggable from the title bar or from anywhere on the windowthat doesn’t have a mouse-clickable widget on it. Many are resizable as well(if the tool window has components that can reasonably be resized).
You can generally use DFHack tools without interrupting the game. That is, ifthe game is unpaused, it can continue to run while a DFHack window is open. Ifconfigured to do so in gui/control-panel, tools will initially pause the gameto let you focus on the task at hand, but you can unpause like normal if youwant. You can also interact with the map, scrolling it with the keyboard ormouse and selecting units, buildings, and items. Some tools, likegui/blueprint, will intercept all mouse clicks to allow you to select regionsof the map. When these tools have focus, you will not be able to use the mouseto interact with map elements or pause/unpause the game. Therefore, these toolswill pause the game when they open, regardless of your settings ingui/control-panel. You can still unpause with the keyboard (spacebar bydefault), though.
Where do I go next?¶
To recap:
You can get to popular, relevant tools for the current context by clicking onthe DFHack logo or by hitting Ctrl-Shift-C.
You can enable DFHack tools and configure settings with gui/control-panel,which you can open from the DFHack logo or access directly with theCtrl-Shift-E hotkey.
You can get to the launcher and its integrated autocomplete, history search,and help text by hitting backtick (`) or Ctrl-Shift-D, or, of course, byrunning it from the logo menu list.
With those three interfaces, you have the complete DFHack tool suite at yourfingertips. So what to run first? Here are a few examples to get you started.
First, let’s import some useful manager orders to keep your fort stocked withbasic necessities. Run orders import library/basic. If you go to yourmanager orders screen, you can see all the orders that have been created foryou. Note that you could have imported the orders directly from this screen aswell, using the DFHack overlay widget at the bottom of the manager orderspanel.
Next, try setting up autochop to automatically designate trees for choppingwhen you get low on usable logs. Run gui/control-panel and enableautochop in the Automation -> Enabled tab. Click on the button tothe left of the name or hit Enter to enable it. You can then click on theconfigure button (the gear icon) to launch gui/autochop if you’d like tocustomize its settings (the defaults are usually fine). If you have the extrascreen space, you can go ahead and set the gui/autochop window to minimalmode (click on the button near the upper right corner of the window or hitAlt-M) and click on the map so the window loses keyboard focus. As you playthe game, you can glance at the live status panel to check on your stocks ofwood.
Finally, let’s do some fort design copy-pasting. Go to some bedrooms that youhave set up in your fort. Run gui/blueprint, set a name for your blueprint byclicking on the name field (or hitting the ‘n’ hotkey). Type “rooms” (orwhatever) and hit Enter to set. Then draw a box around the target area byclicking with the mouse. When you select the second corner, the blueprint willbe saved to your dfhack-config/blueprints subfolder.
Now open up gui/quickfort (the hotkey is Ctrl-Shift-Q). You can search for theblueprint you just created by typing its name, but it should be up near the topalready. If you copied a dug-out area with furniture in it, you will see twoblueprints with the labels “/dig” and “/build”. Click on the “/dig” blueprint orselect it with the keyboard arrow keys and hit Enter. You can rotate or flip theblueprint around if you need to with the transform hotkeys. You’ll see a previewof where the blueprint will be applied as you move the mouse cursor around themap. Red outlines mean that the blueprint may fail to fully apply at thatlocation, so be sure to choose a spot where all the preview tiles are shown withgreen diamonds. Click the mouse or hit Enter to apply the blueprint anddesignate the tiles for digging. Your dwarves will come and dig it out as if youhad designated the tiles yourself.
Once the area is dug out, run gui/quickfort again and select the “/build”blueprint this time. Hit o to generate manager orders for the requiredfurniture. Click to apply the blueprint in the dug-out area, and your furniturewill be designated. It’s just that easy! Note that quickfort usesbuildingplan to place buildings, so you don’t even need to have the relevantfurniture or building materials in stock yet. The planned furniture/buildingswill get built whenever you are able to produce the building materials.
There are many, many more tools to explore. Poke around or ask other player foradvice. Have fun, and dig deep!
