DFHack - Dwarf Fortress Modding Engine News

DFHack 50.13-r2

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

It currently has good support for:

Spanish
Italian
Russian
German
Portuguese (Brazil)
French
Polish

The translations are done by volunteers. Please consider contributing to the translations if you are bilingual -- these translations help make Dwarf Fortress more accessible to non-English speakers.

More details at the Dwarf Fortress localization project home page: https://github.com/dfint
[h3]Adventure mode support[/h3]

Dwarf Fortress adventure mode is currently available on DF's Steam beta branch. DFHack supports the adventure beta on its own adventure-beta branch. Please make sure you are subscribed to DFHack's adventure-beta branch if you are running the DF adventure beta!

We are going through our back catalog and steadily updating adventure mode tools. Moreover, we are modifying existing tools as necessary to be useful for adventure mode.

Here's what's been validated so far:

flashstep: teleport the adventurer to the mouse cursor
ghostly: allow the adventurer to walk through walls
gui/create-item: create arbitrary items
gui/reveal: reveal the map beyond your cone of vision
gui/sandbox: create units or trees (or items too)
gui/unit-info-viewer: get extended information on the selected unit
resurrect-adv: bring your adventurer back to life
reveal-adv-map: reveal hidden world map tiles
reveal-hidden-sites: reveal hidden world map sites
reveal-hidden-units: reveal hidden units on the local map
unretire-anyone: start an adventure as anybody in the world

In addition, all tools that aren't mode-specific, such as the mod manager and the new markdown unit/item description export, should work just fine too. If you try to use a tool in adventure mode and it doesn't behave as you'd expect, please tell us so we can improve the experience!
[h2]Expectations for the adventure mode beta[/h2]
DFHack needs to release a new compatible build whenever a new DF beta is pushed, just like we need to release a new compatible build whenever a stable DF version is released.

The good news is that DFHack now has a process in place to automatically build a compatible DFHack version when a new DF beta drops. DFHack should be compatible with new DF betas within 15 minutes. Sometimes, however, Steam gets one update but not the other. If you get a message that DFHack does not recognize the version of Dwarf Fortress, try going into the app settings in your Steam client for both DFHack and Dwarf Fortress, click on Installed Files, and click the Verify integrity of game files button. That will poke Steam to ensure that both DF and DFHack are fully updated.

In addition to compatibility bumps, the adventure-beta branch of DFHack will be updated frequently as DFHack's support for adventure mode is improved.
[h3]Export unit and item descriptions[/h3]
This release includes a unit/item description exporter that will write details about the selected unit or item to a formatted markdown text file.

Just select a unit or item and hit the Ctrl-t hotkey (or select markdown from the DFHack logo context menu)! The text will be written to a file in your Dwarf Fortress game directory, named after your current world. If you export multiple times, the text will be appended to the same file, so feel free to run markdown on all your forgotten beasts and expensive artifacts. The whole list will be ready for you when you're done.

[h3]Quick switch favorites for building planner materials[/h3]

When you want to use a specific material for construction, say because you are designing a pattern in your tavern floor, it can be annoying to have to set the material filter each time. Now, you can set your favorite material filters and quickly switch among them with the new building planner favorites panel!

Your favorites are saved with your fort, so they'll be there for you if you save and load the game.

You can also rename a favorite by shift-clicking on the name.
[h2]Announcements[/h2][h3]PSAs[/h3]
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

[h2]New Tools[/h2]

Updated for adventure mode:
- reveal
- gui/sandbox, gui/create-item, gui/reveal
adaptation: (reinstated) inspect or set unit cave adaptation levels
fix/engravings: fix corrupt engraving tiles
flashstep: (reinstated) teleport your adventurer to the mouse cursor
ghostly: (reinstated) allow your adventurer to phase through walls
markdown: (reinstated) export description of selected unit or item to a text file
resurrect-adv: (reinstated) allow your adventurer to recover from death
reveal-adv-map: (reinstated) reveal (or hide) the adventure map
unretire-anyone: (reinstated) choose anybody in the world as an adventurer

[h2]New Features[/h2]

DFHack and the Dwarf Fortress translation project can now both be run at the same time
buildingplan: quick material filter favorites on main planner panel
instruments: new subcommand instruments order for creating instrument work orders

[h2]Fixes[/h2]

blueprint: correctly define stockpile boundaries in recorded stockpile ("place") blueprints when there are adjacent non-rectangular stockpiles of identical types
caravan: don't include undiscovered divine artifacts in the goods list
combine: respect container volume limits
dig:
- refresh count of tiles that will be modified by "mark all designated tiles on this z-level for warm/damp dig" when the z-level changes
- don't affect already-revealed tiles when marking z-level for warm/damp dig
gui/quantum: fix processing when creating a quantum dump instead of a quantum stockpile
logistics: include semi-wild pets when autoretrain is enabled
modtools/create-item: now functions properly when the reaction-gloves tweak is active
prospect: don't use scientific notation for representing large numbers
quickfort:
- don't designate multiple tiles of the same tree for chopping when applying a tree chopping blueprint to a multi-tile tree
- fix detection of valid tiles for wells
suspendmanager: fully suspend unbuildable dead ends (e.g. buildling second level of a wall when the wall top is only accessible via ramp, causing the planned wall to be pathable but not buildable)
zone:
- fix display of distance from cage/pit for small pets in assignment dialog
- refresh values in distance column when switching selected pastures when the assign animals dialog is open

[h2]Misc Improvements[/h2]

Dreamfort: move wells on services level so brawling drunken tavern patrons are less likely to fall in
New commandline options for controlling the Cloud Save coprocess when launching from Steam. See the dfhack-core documentation for details.
caravan: display who is in the cages you are selecting for trade and whether they are hostile
combine: reduce combined drink sizes to 25
deathcause: automatically find and choose a corpse when a pile of mixed items is selected
dig:
- warm/damp/aquifer status will now be shown in mining mode for tiles that your dwarves can see from the level below
- warm/damp/aquifer status will now be shown when in smoothing/engraving modes
flashstep: new keybinding for teleporting adventurer to the mouse cursor: Ctrl-t (when adventure map is in the default state and mortal mode is disabled in DFHack preferences)
gui/autobutcher: add shortcuts for butchering/unbutchering all animals
gui/launcher: add button for copying output to the system clipboard
gui/quantum:
- add option for whether a minecart automatically gets ordered and/or attached
- when attaching a minecart, show which minecart was attached
- allow multiple feeder stockpiles to be linked to the minecart route
markdown: new keybinding for triggering text export: Ctrl-t (when unit or item is selected)
prioritize: add PutItemOnDisplay jobs to the default prioritization list -- when these kinds of jobs are requested by the player, they generally want them done ASAP
regrass:
- can now add grass to stairs, ramps, ashes, buildings, muddy stone, shrubs, and trees
- can now restrict area of effect to specified tile, block, cuboid, or z-levels
- can now add grass in map blocks where there hasn't been any
- can now choose specific grass type
stockpiles: support import and export "desired items" configuration for route stops
unretire-anyone: new keybinding for adding a historical figure to the adventurer selection list in the adventure mode setup screen: Ctrl-a

[h2]API[/h2]

dfhack.items.getReadableDescription(): easy API for getting a human-readable item description with useful annotations and information (like tattered markers or who is in a cage)
Items::createItem: now returns a list of item pointers rather than a single ID, moved creator parameter to beginning, added growth_print and no_floor parameters at end
World::getAdventurer: returns current adventurer unit
World::ReadPauseState: now returns true when the game is effectively paused due to a large panel obscuring the map. this aligns the return value with the visual state of the pause button when in fort mode.

[h2]Lua[/h2]

dfhack.internal.setClipboardTextCp437Multiline: for copying multiline text to the system clipboard
dfhack.items.createItem: return value and parameters have changed as per C++ API
dfhack.world.getAdventurer: returns current adventurer unit

[h2]Documentation[/h2]

Quickfort Blueprint Library: add demo videos for pump stack and light aquifer tap blueprints
Update docs for dependency requirements and compilation procedures

DFHack 50.13-r1

This release is for the non-beta 50.13 release of DF. For the DF v51.01 adventure mode beta, please subscribe to the DFHack adventure-beta beta branch on Steam. The adventure-beta DFHack branch includes everything in this release as well.

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

Run gui/quantum and you'll get a visual, interactive interface for creating quantum stockpiles.

Quantum stockpiles simplify fort management by allowing a small stockpile to contain a large number of items. This reduces the complexity of your storage design, lets your dwarves find items more efficiently, and increases FPS. Until now, though, they were a bit fiddly to set up and it was easy to make a mistake that would prevent them from working correctly.

Quantum stockpiles work by linking a “feeder” or "input" stockpile to a one-tile minecart hauling route. Whenever an item from the feeder stockpile is placed in the minecart, the minecart is tipped and the item spills out onto an adjacent tile. The single-tile "output" stockpile in that adjacent tile holds all the items spilled out of the minecart and is your quantum stockpile. You can also choose to not have a receiving stockpile and instead have the minecart dump into a pit (perhaps a pit filled with magma).

The gui/quantum UI will walk you through the steps:

Select a stockpile to be the feeder by clicking on it.
Set configuration (like what the quantum stockpile will be named) with the onscreen options.
Click on a free tile on the map to build the minecart stop and (optionally) designate the output stockpile.

If there are minecarts available, one will be automatically assigned to the track stop for you. If you don’t have a free minecart, gui/quantum will enqueue a manager order to make a wooden one. Once it is manufactured, you’ll have to run assign-minecarts all to assign it to the route, or you can open the (H)auling menu and assign the minecart manually. The quantum stockpile will not function until the minecart is in place.

See the wiki for more information on quantum stockpiles.

[h3]Extended unit info summary[/h3]

This handy lookup tool will give you detailed (but non-spoilery) data on the currently selected unit and their race. Among other things, it will tell you if a creature needs grass or lays eggs. It will even tell you the unit's current size in cubic centimeters.

If you have any ghosts walking (floating?) around, you'll get some interesting info on them as well : )
[h2]Announcements[/h2][h3]PSAs[/h3]
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

[h2]New Tools[/h2]

gui/quantum: (reinstated) point and click interface for creating quantum stockpiles or quantum dumps
gui/unit-info-viewer: (reinstated) give detailed information on a unit, such as egg laying behavior, body size, birth date, age, and information about their afterlife behavior (if a ghost)

[h2]Fixes[/h2]

Fixed incorrect DFHack background window texture when DF is started in ascii mode and subsequently switched to graphics mode
Fixed misidentification of visitors from your own civ as residents; affects all tools that iterate through citizens/residents
cursecheck: act on selected unit only if a unit is selected
exterminate: don't classify dangerous non-invader units as friendly (e.g. snatchers)
gui/create-item:
- properly restrict bags to bag materials by default
- allow gloves and shoees to be made out of textiles by default
open-legends: don't interfere with the dragging of vanilla list scrollbars

[h2]Misc Improvements[/h2]

gui/gm-unit: changes to unit appearance will now immediately be reflected in the unit portrait
open-legends: allow player to cancel the "DF will now exit" dialog and continue browsing
suspendmanager: Account for walls planned on the z-layer below when determining accessibility to a job

[h2]Structures[/h2]

biome_type: add enum attrs for caption and plant_raw_flags

[h2]Documentation[/h2]

autoclothing: add section comparing autoclothing and tailor to guide players choosing which to enable

DF adventure mode beta support

We've been working with Tarn and Putnam in the lead-up to this beta, and DFHack is prepared to keep pace with DF beta updates. If you're on the DF beta Steam branch, please also subscribe to the DFHack adventure-beta Steam branch to keep the two apps in sync.

DFHack 50.12-r3

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

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:

[h3]Dig through warm or damp tiles without interruption[/h3]
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

[h3]Unlink buildings from levers[/h3]

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.

[h2]Announcements[/h2][h3]PSAs[/h3]
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

[h2]New Tools[/h2]

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

[h2]New Features[/h2]

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

[h2]Fixes[/h2]

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

[h2]Misc Improvements[/h2]

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

[h2]Removed[/h2]

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

[h2]API[/h2]

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

[h2]Lua[/h2]

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

[h2]Structures[/h2]

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

[h2]Documentation[/h2]

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

DFHack 50.12-r3rc1

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

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!
[h2]What needs testing[/h2][h3]Dig through warm or damp tiles without interruption[/h3]
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

[h3]Open legends mode directly from an active fort[/h3]
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.
[h3]Unlink levers[/h3]
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.
[h3]PSAs[/h3]
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.
[h2]New Tools[/h2]

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

[h2]New Features[/h2]

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

[h2]Fixes[/h2]

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

[h2]Misc Improvements[/h2]

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

[h2]Removed[/h2]

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

[h2]API[/h2]

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

[h2]Lua[/h2]

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

[h2]Structures[/h2]

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

[h2]Documentation[/h2]

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