This beta release is compatible with all distributions of Dwarf Fortress: Steam, Itch, and Classic.

• Install DFHack from Steam
• Manual install
• Quickstart guide (for players)
• Modding guide (for modders)

Please report any issues (or feature requests) on the DFHack GitHub issue tracker. When reporting issues, please upload a zip file of your savegame and a zip file of your mods directory to the cloud and add links to the GitHub issue. Make sure your files are downloadable by "everyone with the link". We need your savegame to reproduce the problem and test the fix, and we need your active mods so we can load your savegame. Issues with savegames and mods attached get fixed first!

What needs testing

Dig through warm or damp tiles without interruption

DF has a safety feature: when your miners uncover a warm or damp tile, any dig designation on that tile will be canceled. This is to protect you from blithely mining your way into a lake or an underground magma pool. However, this also means that if you want to dig through a warm or damp area, you will have to re-designate every. single. tile. as it becomes unhidden. This is very very very painful. Digging through light aquifers or above magma is an exercise in frustration. Many players completely avoid aquifers for this reason. There is now a new icon in the mining toolbar. In graphics mode, it looks like a pickaxe with a drop of water and a lava flow behind it. In ASCII mode, it looks like two tildes (~~). Click it (or hit the Ctrl-D hotkey), and you can enable warm and/or damp dig mode. Tiles that you subsequently designate for digging will have a special marker on them (or will blink blue/red in ASCII mode), and they will not be canceled if the designated tile turns out to be warm or damp (respectively). This means that you can dig without interruption under lakes or through light aquifers. If you enable both damp dig and vanilla autodig, e.g. to mine out a mineral vein, the damp dig marker will propagate along with the autodig. This allows you to automine veins that cross under lakes or through aquifers. Note that if you autodig through an aquifer, you might want to smooth the walls as you autodig, otherwise the water might build up behind your miners and trap them. You'll also notice that light and heavy aquifers have new icons that distinguish them from each other and from non-leaky "just damp" tiles. The new toolbar and aquifer icons are distributed with DFHack and are derived from vanilla assets. They are used with permission from Bay 12. There are also some new tools and new functionality in existing tools for warm and damp dig:

• gui/aquifer allows you to see and edit aquifers
• gui/reveal now highlights aquifer tiles, even when not in mining mode
• gui/blueprint captures warm and damp dig markers
• gui/quickfort reproduces warm and damp dig markers stored in blueprints, and additionally allows you to apply any blueprint with warm and/or damp dig markers

Open legends mode directly from an active fort

The long-awaited, much-requested feature is here: you can now jump into legends mode without retiring your current fortress. When you run open-legends, you'll get a dialog explaining what is about to happen and you will be prompted to save your game. The dialog gives you a clickable link that will do an autosave, or you can exit the dialog to do a named manual save and then come back to open-legends. Then you can hop right into legends mode and dig into your world's history! Legends mode, however, disrupts the state of the game. You can't safely jump back into your fort afterwards. DFHack takes steps to protect your savegame and will exit to desktop when you're done browsing legends mode. You can relaunch DF and load your savegame to continue. This isn't ideal, but it is much easier than the current process: saving to a new timeline, retiring your fort, loading up the world anew for a legends session, browsing, and then deleting (or forgetting to delete) the extra timeline.

Unlink levers

When viewing levers or the buildings they are linked to, you will now see buttons for unlinking and freeing unlinked mechanisms. This allows you to repurpose levers without deconstructing them, and allows you to retrieve unused mechanisms from unlinked buildings.

PSAs

As always, remember that, just like the vanilla DF game, DFHack tools can also have bugs. It is a good idea to save often and keep backups of the forts that you care about. Many DFHack tools that worked in previous (pre-Steam) versions of DF have not been updated yet and are marked with the "unavailable" tag in their docs. If you try to run them, they will show a warning and exit immediately. You can run the command again to override the warning (though of course the tools may not work). We make no guarantees of reliability for the tools that are marked as "unavailable". The in-game interface for running DFHack commands (gui/launcher) will not show "unavailable" tools by default. You can still run them if you know their names, or you can turn on dev mode by hitting Ctrl-D while in gui/launcher and they will be added to the autocomplete list. Some tools do not compile yet and are not available at all, even when in dev mode. If you see a tool complaining about the lack of a cursor, know that it's referring to the keyboard cursor (which used to be the only real option in Dwarf Fortress). You can enable the keyboard cursor by entering mining mode or selecting the dump/forbid tool and hitting Alt-K (the DFHack keybinding for toggle-kbd-cursor). We're working on making DFHack tools more mouse-aware and accessible so this step isn't necessary in the future.

New Tools

• aquifer: commandline tool for creating, draining, and modifying aquifers
• gui/aquifer - interactive aquifer visualization and editing
• open-legends: (reinstated) open legends mode directly from a loaded fort

New Features

• blueprint:
  • designations and active dig jobs are now captured in generated blueprints
  • warm/damp dig markers are captured in generated blueprints
• buildingplan: add overlays for unlinking and freeing mechanisms from buildings
• dig:
  • designate tiles for damp or warm dig, which allows you to dig through damp or warm tiles without designations being canceled
  • damp and warm tile icons now remain visible when included in the designation selection box (graphics mode)
  • aquifer tiles are now visually distinct from "just damp" tiles (graphics and ascii modes)
  • light aquifer tiles are now visually distinct from heavy aquifer tiles (graphics and ascii modes)
  • autodig designations that are marked for damp/warm dig propagate the damp/warm tag when expanding to newly exposed tiles
• gui/notify: optional notification for general wildlife (not on by default)
• gui/quickfort: add options for applying blueprints with warm and/or damp dig markers
• gui/reveal: new "aquifer only" mode to only see hidden aquifers but not reveal any tiles
• quickfort: add options for applying blueprints with warm and/or damp dig markers

Fixes

• fix behavior of Linux Steam launcher on systems that don't support the inotify API
• fix rendering of resize "notch" in lower right corner of resizable windows in ascii mode
• armoks-blessing: fix error when making class "Normal" attributes legendary
• fix/loyaltycascade: fix lookup of associated unit metadata when the metadata list is sparse (that is, the script was sometimes failing to fix the loyalties of renegade units because it was failing to find those units' metadata)
• quickfort:
  • stockpiles can now be placed even if there is water covering the tile, as per vanilla behavior
  • reject tiles for building that contain magma or deep water

Misc Improvements

• aquifer tap blueprint: now designates in damp dig mode for uninterrupted digging in a light aquifer
• pump stack blueprint: now designates in warm and damp dig mode for uninterrupted digging through warm and damp tiles
• gui/control-panel: add alternate "nodump" version for cleanowned that does not cause citizens to toss their old clothes in the dump. this is useful for players who would rather sell old clothes than incinerate them
• gui/reveal: show aquifers even when not in mining mode
• keybinding: you can now assign keybindings to mouse buttons (if your mouse has more than the three buttons already used by DF)
• tailor: allow turning off automatic confiscation of tattered clothing

Removed

• drain-aquifer: replaced by aquifer drain --all; an alias now exists so drain-aquifer will automatically run the new command

API

• Buildings :: checkFreeTiles: now takes a allow_flow parameter to control whether water- or magma-filled tiles are valid
• Units :: citizensRange: c++-20 std :: range filter for citizen units
• Units :: forCitizens: iterator callback function for citizen units
• Units :: paintTile, Units :: readTile: now takes an optional field specification for reading and writing to specific map compositing layers

Lua

• dfhack.gui.matchFocusString: focus string matching is now case sensitive (for performance reasons)

Structures

• name many previously-unknown map-related fields and flag bits
• job_type: new job class type: "Carving" (for smoothing and detailing)
• unit_action_data_attack (unit_move_attackst): identify flags

Documentation

• Lua API: documented existing enum:next_item(index) function