Q: How do I download DFHack?
A: Either add to your Steam library from our Steam page or scroll to the latest release on our GitHub releases page, expand the "Assets" list, and download the file for your platform (e.g. dfhack-XX.XX-rX-Windows-64bit.zip
. If you are on Windows and are manually installing from the zip file, please remember to right click on the file after downloading, open the file properties, and select the "Unblock" checkbox. This will prevent issues with Windows antivirus programs.
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!
New features in need of feedback and testing
gui/embark-anywhere, item bulk management, difficulty settings and standing orders auto-restore, retire unused locations
Embark wherever you please
By popular request, you can now laugh at Armok and embark wherever you please.
If you run gui/embark-anywhere
when you’re choosing a site for embark, you can bypass any warnings the game gives you about potential embark locations. Want to embark in an inaccessible location on top of a mountain range? Go for it! Want to try a brief existence in the middle of the ocean? Nobody can stop you! Want to tempt fate by embarking inside of a necromancer tower? !!FUN!!
Any and all consequences of embarking in strange locations are up to you to handle (possibly with other armok tools).
Item bulk management
The item
commandline tool allows you to filter items in you fort by various properties (e.g., item type, material, wear-level, quality, …), and perform bulk operations like forbid, dump, melt, and their inverses. With one command, you can hide all boulders that are not in stockpiles, or mark all metal items that are less than masterwork quality for melting!
This tool also provides the underlying logic for a planned (but not yet written) GUI-based item management screen.
Difficulty settings and standing orders auto-restore
If you have preferred custom settings for difficulty or standing orders, it is toilsome to have to go in and manually set them for every embark. Do you find yourself having to remember to go turn corpse hauling off for your children? Now, you can set it once, export, and have your settings automatically restored when you start a new embark. It's seamless, and is a huge time-saver for people with highly customized settings!
Retire unused locations
If you have locations (taverns, libraries, hospitals, temples) you don't need anymore, they just hang around and clutter up your list. Now, there's a button on the location details screen that you can click to retire the location and get it out of the way.
Announcements
PSAs
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, fixes, and improvements
New Tools
control-panel
: new commandline interface for control panel functionsgui/biomes
: visualize and inspect biome regions on the mapgui/embark-anywhere
: bypass those pesky warnings and embark anywhere you want togui/reveal
: temporarily unhide terrain and then automatically hide it again when you're ready to unpausegui/teleport
: mouse-driven interface for selecting and teleporting unitsitem
: perform bulk operations on groups of items.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 mapgui/settings-manager
: save and load (optionally automatically) embark difficulty settings and standing orderssort
: 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 foruniform-unstick
: add overlay to the squad equipment screen to show a equipment conflict report and give you a one-click button to fixzone
: add button to location details page for retiring unused locations
Fixes
- DFHack tabs (e.g. in
gui/control-panel
) are now rendered correctly when there are certain vanilla screen elements behind them - Dreamfort: fix holes in the "Inside+" burrow on the farming level (burrow autoexpand is interrupted by the pre-dug miasma vents to the surface)
- 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 errorbuildingplan
:- when you save a game and load it again, newly planned buildings are now correctly placed in line after existing planned buildings of the same type
- show correct number of materials required when laying down areas of constructions and some of those constructions are on invalid tiles
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)empty-bin
: now correctly sends ammunition in carried quivers to the tile underneath the unit instead of teleporting them to an invalid (or possibly just far away) locationgetplants
: fix crash when processing mod-added plants with invalid materialsgui/design
: fix incorrect dimensions being shown when placing stockpiles, but a start coordinate hasn't been selected yetmisery
: fix error when changing the misery factorquickfort
: 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 possiblereveal
: 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 loadssuspendmanager
: correctly handle building collisions with smoothing designations when the building is on the edge of the mapwarn-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
- Dreamfort: put more chairs adjacent to each other to make the tavern more "social"
- 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 commandlineautoclothing
: now does not consider worn (x) clothing as usable/available, should help with using withtailor
at same timebuildingplan
: add option for preventing constructions from being planned on top of existing constructionsburrow
: flood fill now requires an explicit toggle before it is enabled to help prevent accidental flood fillsconfirm
:- 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
fix/stuck-instruments
: now handles instruments that are left in the "in job" state but that don't have any actual jobs associated with themgui/autobutcher
: interface redesigned to better support mouse controlgui/control-panel
:- reduce frequency for
warn-stranded
check to once every 2 days - tools are now organized by type: automation, bugfix, and gameplay
- reduce frequency for
gui/launcher
:- now persists the most recent 32KB of command output even if you close it and bring it back up
- make autocomplete case insensitive
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 operationssort
:- 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 fortzone
:- add include/only/exclude filter for juveniles to the pasture/pit/cage/restraint assignment screen
- show geld status and custom profession (2nd editable line in creature description) in pasture/pit/cage/restraint assignment screen
Removed
channel-safely
: (temporarily) removed due to stability issues with the underlying DF APIpersist-table
: replaced by newdfhack.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
: newMiscUtils
function, returns string with all words capitalizedgrab_token_string_pos
: newMiscUtils
function, used for parsing tokensItems
: add item melting logiccanMelt(item)
,markForMelting(item)
, andcancelMelting(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
: newMiscUtils
functions, for getting a random entry in a vectorUnits.isDanger
: now returns true for agitated wildlifeWorld
: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 withAddPersistentSiteData
andAddPersistentWorldData
equivalents
Lua
dfhack.capitalizeStringWords
: new function, returns string with all words capitalizeddfhack.isSiteLoaded
: returns whether a site (e.g. a player fort) is loadeddfhack.items
: access tocanMelt(item)
,markForMelting(item)
, andcancelMelting(item)
fromItems
moduledfhack.persistent
: new, table-driven API for easier world- and site-associated persistent storage. See the Lua API docs for details.dfhack.world.getCurrentSite
: returns thedf.world_site
instance of the currently loaded fortwidgets.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
: definedannouncement_alert_type
: enum definedannouncement_type
: addedalert_type
enum attributemarkup_text_boxst
: updated based on information from Bay12markup_text_linkst
,markup_text_wordst
,script_environmentst
: definedoccupation
: realignedplotinfost
:unk23c8_flags
renamed toflags
, updated based on information from Bay12service_orderst
: type definedservice_order_type
: enum definedsoundst
: definedviewscreen_choose_start_sitest
: fix structure of warning flags -- convert series of bools to a proper bitmaskworld_raws
:unk_v50_1
,unk_v50_2
,unk_v50_3
renamed totext_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 Macmodding-guide
: Add examples for script-only and blueprint-only mods that you can upload to DF's Steam Workshop