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!

New features in need of feedback and testing

gui/control-panel layout overhaul

The control panel received a significant overhaul. Tools are now categorized into subtabs, gathering the automation, bugfix, and gameplay tools into sublists. The file format for storing control panel configuration has changed as well. When you load this release of DFHack, your previous control panel settings should be seamlessly migrated to the new format. The main behavior change is that some things that were only configured globally (like the tools on the now-gone "Maintenance" tab) are now configurable per-fort. There is also more information about what things are. For example, each overlay now has a short description. What do you think of the new layout and tab structure? Is it easier to find the tools you're looking for? Do you feel more confident about enabling new things?

gui/autobutcher mousification

gui/autobutcher finally got updated with modern widgets and mouse gestures. You can now select fields to edit by double clicking on them. The list of livestock now also shows you the total counts per race, and the list of race targets is sortable and filterable. What do you think? Is it easier to use than the previous version? Pro tip: to unmark the slaughter tag from all animals of a particular race, double click on the number in the "Butchering ordered" column.

confirm rewrite and new prompts

The confirm framework has been completely rewritten, and thanks to many good suggestions on Reddit, there are now a wide variety of new confirmation prompts that protect you from accidentally invoking irreversible and highly impactful UI operations (like disbanding a squad or deconstructing the trade depot while merchants are using it). Is there anything you think we've missed? What do you think of the new confirmation prompts? Is it easy to pause them when you want to (e.g. when deleting a bunch of manager orders)?

uniform-unstick uniform fixing tool

When you look at your squad equipment, there will be a new button that says "Detect conflicts". This will bring up a report of squad equipment problems, such as squad members being assigned to conflicting labors like mining or hunting, or the same piece of equipment being assigned to multiple squad members, or even citizens being members of squads from different forts (this can happen with migrants from forts that you have retired). There's a button at the top of the report that attempts to fix all the problems. Does it work for you? Do your forever-yellow equipment icons finally turn green? Remember to click "Update equipment" after running the fixer so that new equipment gets assigned to units that need it.

gui/mass-remove now easier to use

gui/mass-remove is our tool for easily removing multiple buildings and other things. It gained much more configurability, so you can now, for example, have it just remove planned buildings and ignore fully built ones. It can also cancel removal of buildings and constructions via area select. It has a global hotkey for quick access: Ctrl-M while on the main fort map. Give it a try and tell us if it works well for you when you need to remove a bunch of stuff.

gui/reveal for temporary xray vision

I've seen people talk on Reddit and the Discord servers about how to plan your fort layout after you embark but before you unpause. Frequently, I see people advising use of reveal to see where the caverns are so you can plan your fort around them. This is always followed by the warning "Remember to run unreveal before you unpause! Otherwise the caverns get "discovered" early and then if you unreveal later then parts that you dug out will be hidden again and things get weird." To make this process less error-prone, we now have gui/reveal. It reveals the map when it comes up and forces the game to pause while the gui/reveal window is open. You can scan around the map and designate digging for your fort. When you right click on the little gui/reveal window to close it, the map is hidden again, and you can play the game as normal. You can choose to keep the map revealed, of course, but the more common case where only a temporary reveal is desired is much easier to handle now.

gui/biomes for biome boundary visualization

If you have embarked at the intersection of two or more biomes, you may have trouble finding a place for your farm plots so that you can grow the crops you want. gui/biomes can show you where the boundaries are, and will also give you information about the biomes themselves, such as their wildness rating.

gui/teleport for mouse-driven unit teleporting

Another painful process I've seen discussed on Reddit relates to when a unit gets into an impossible situation, like when they dodge into a wall or (sometimes) into the unexplored regions of a cavern and they can't get out. This tends to tank your FPS and make the game unplayable. The commandline teleport command does exist, but it's a multi-step process. You have to find the unit ID of the rogue unit, enable the keyboard cursor, get the position of where to teleport the unit to, and feed all that information into the teleport command. Now, with gui/teleport, it's point and click. It also comes with some handy filters for when you're trying to rescue friendly units from among hostiles. You can area select and only pick out the citizens and friendly units.

Announcements

Plugin ABI version bump

If you are developing an external plugin for DFHack, be aware that the plugin binary interface (ABI) has changed to support the new site-local persistence model. See changes to the sample code in https://github.com/DFHack/dfhack/tree/develop/plugins/examples for details.

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

• control-panel: new commandline interface for control panel functions
• gui/biomes: visualize and inspect biome regions on the map
• gui/reveal: temporarily unhide terrain and then automatically hide it again when you're ready to unpause
• gui/teleport: mouse-driven interface for selecting and teleporting units
• uniform-unstick: (reinstated) force squad members to drop items that they picked up in the wrong order so they can get everything equipped properly

New Features

• gui/mass-remove: new global keybinding: Ctrl-M while on the fort map
• sort: search and sort for the "choose unit to elevate to the barony" screen. units are sorted by the number of item preferences they have and the units are annotated with the items that they have preferences for
• uniform-unstick: add overlay to the squad equipment screen to show a equipment conflict report and give you a one-click button to fix

Fixes

• When passing map movement keys through to the map from DFHack tool windows, also pass fast z movements (shift-scroll by default)
• ban-cooking: fix banning creature alcohols resulting in error
• confirm: properly detect clicks on the remove zone button even when the unit selection screen is also open (e.g. the vanilla assign animal to pasture panel)
• getplants: fix crash when processing mod-added plants with invalid materials
• misery: fix error when changing the misery factor
• quickfort: if a blueprint specifies an up/down stair, but the tile the blueprint is applied to cannot make an up stair (e.g. it has already been dug out), still designate a down stair if possible
• reveal: now avoids revealing blocks that contain divine treasures, encased horrors, and deep vein hollows (so the surprise triggers are not triggered prematurely)
• sort:
  • fix mouse clicks falling through the squad assignment overlay panel when clicking on the panel but not on a clickable widget
  • fix potential crash when removing jobs directly from the Tasks info screen
• source: water and magma sources now persist with fort across saves and loads
• warn-stranded:
  • Automatically ignore citizens who are gathering plants or digging to avoid issues with gathering fruit via stepladders and weird issues with digging
  • Update onZoom to use df's centering functionality

Misc Improvements

• The "PAUSE FORCED" badge will blink briefly to draw attention if the player attempts to unpause when a DFHack tool window requires the game to be paused
• wherever units are listed in DFHack tools, properties like "agitated" or (-trained-) are now shown
• autochop: better error output when target burrows are not specified on the commandline
• autoclothing : now does not consider worn (x) clothing as usable/available, should help with using with tailor at same time
• burrow: flood fill now requires an explicit toggle before it is enabled to help prevent accidental flood fills
• confirm:
  • updated confirmation dialogs to use clickable widgets and draggable windows
  • added confirmation prompt for right clicking out of the trade agreement screen (so your trade agreement selections aren't lost)
  • added confirmation prompts for irreversible actions on the trade screen
  • added confirmation prompt for deleting a uniform
  • added confirmation prompt for convicting a criminal
  • added confirmation prompt for re-running the embark site finder
  • added confirmation prompt for reassigning or clearing zoom hotkeys
  • added confirmation prompt for exiting the uniform customization page without saving
• fastdwarf:
  • now saves its state with the fort
  • prevent units from teleporting to inaccessible areas when in teledwarf mode
  • allow units to meander and satisfy needs when they have no current job and teledwarf mode is enabled
• gui/autobutcher: interface redesigned to better support mouse control
• gui/control-panel:
  • reduce frequency for warn-stranded check to once every 2 days
  • tools are now organized by type: automation, bugfix, and gameplay
• gui/launcher: now persists the most recent 32KB of command output even if you close it and bring it back up
• gui/mass-remove:
  • can now differentiate planned constructions, stockpiles, and regular buildings
  • can now remove zones
  • can now cancel removal for buildings and constructions
• gui/quickcmd: clickable buttons for command add/remove/edit operations
• sort:
  • add "Toggle all filters" hotkey button to the squad assignment panel
  • rename "Weak mental fortitude" filter to "Dislikes combat", which should be more understandable
• uniform-unstick: warn if a unit belongs to a squad from a different site (can happen with migrants from previous forts)
• work-now: now saves its enabled status with the fort
• zone: add include/only/exclude filter for juveniles to the pasture/pit/cage/restraint assignment screen

Removed

• channel-safely: (temporarily) removed due to stability issues with the underlying DF API
• persist-table: replaced by new dfhack.persistent API

API

• New plugin API for saving and loading persistent data. See plugins/examples/skeleton.cpp and plugins/examples/persistent_per_save_example.cpp for details
• Plugin ABI (binary interface) version bump! Any external plugins must be recompiled against this version of DFHack source code in order to load.
• capitalize_string_words: new MiscUtils function, returns string with all words capitalized
• grab_token_string_pos: new MiscUtils function, used for parsing tokens
• Items: add item melting logic canMelt(item), markForMelting(item), and cancelMelting(item)
• Persistence:
  • persistent keys are now namespaced by an entity_id (e.g. a player fort site ID)
  • data is now stored one file per entity ID (plus one for the global world) in the DF savegame directory
• random_index, vector_get_random: new MiscUtils functions, for getting a random entry in a vector
• World:
  • GetCurrentSiteId() returns the loaded fort site ID (or -1 if no site is loaded)
  • IsSiteLoaded() check to detect if a site (e.g. a player fort) is active (as opposed to the world or a map)
  • AddPersistentData and related functions replaced with AddPersistentSiteData and AddPersistentWorldData equivalents

Lua

• dfhack.capitalizeStringWords: new function, returns string with all words capitalized
• dfhack.isSiteLoaded: returns whether a site (e.g. a player fort) is loaded
• dfhack.items: access to canMelt(item), markForMelting(item), and cancelMelting(item) from Items module
• dfhack.persistent: new, table-driven API for easier world- and site-associated persistent storage. See the Lua API docs for details.
• dfhack.world.getCurrentSite: returns the df.world_site instance of the currently loaded fort
• widgets.Divider: linear divider to split an existing frame; configurable T-junction edges and frame style matching

Structures

• alert_button_announcement_id: now int32_t vector (contains report ids)
• announcement_alertst: defined
• announcement_alert_type: enum defined
• announcement_type: added alert_type enum attribute
• markup_text_boxst: updated based on information from Bay12
• markup_text_linkst, markup_text_wordst, script_environmentst: defined
• occupation: realigned
• plotinfost: unk23c8_flags renamed to flags, updated based on information from Bay12
• service_orderst: type defined
• service_order_type: enum defined
• soundst: defined
• world_raws: unk_v50_1, unk_v50_2, unk_v50_3 renamed to text_set, music, sound

Documentation

• UTF-8 text in tool docs is now properly displayed in-game in gui/launcher (assuming that it can be converted to cp-437)
• installing: Add installation instructions for wineskin on Mac
• modding-guide: Add examples for script-only and blueprint-only mods that you can upload to DF's Steam Workshop