This 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!

Highlights

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 come back to open-legends afterwards. Then you can hop right into legends mode and dig into your world's history as it exists right now!
It's important to save your game because entering legends mode 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 saved game 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. Many thanks to Rumrusher, who provided the key insight that allowed this feature to work again! Here's how it looks from end to end:

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 monitor as tiles become unhidden and re-designate your digging for every. single. tile. 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 red/blue 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 seamlessly 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 go, otherwise the water might build up behind your miners and trap them.
You'll also notice that light and heavy aquifers have new icons (or, in ASCII, blink patterns) 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. This is done with permission from Bay 12. Thank you Tarn! There are also some new tools and new functionality in existing tools that go along with warm and damp dig:

• gui/aquifer allows you to see, add, remove, and modify aquifers
• gui/reveal now highlights aquifer tiles, even when not in mining mode. It also gained an alternate reveal mode where only aquifers are shown and no tiles are actually unhidden. This allows you to designate your digging with knowledge of where aquifers are, but will not spoil the caverns or other underground surprises.
• gui/blueprint captures warm and damp dig markers as part of the generated blueprints
• 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
• the aquifer_tap

Unlink buildings from 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.

Announcements

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.

Changelog

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 setting warm/damp dig markers when applying blueprints
• gui/reveal: new "aquifer only" mode to only see hidden aquifers but not reveal any tiles
• quickfort: add options for setting warm/damp dig markers when applying blueprints

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
• agitation-rebalance: fix calculated percent chance of cavern invasion
• armoks-blessing: fix error when making "Normal" attributes legendary
• emigration: remove units from burrows when they emigrate
• fix/loyaltycascade: fix edge case where loyalties of renegade units were not being fixed
• gui/launcher: don't pop up a result dialog if a command run from minimal mode has no output
• 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
• stonesense: fix a crash with buildings made of unusual materials (such as campsite tents made out of organic "walls")
• suspendmanager: prevent cancellation spam when an item is preventing a building from being completed

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
• agitation-rebalance: when more than the maximum allowed cavern invaders are trying to enter the map, prefer keeping the animal people invaders instead of their war animals
• 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