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.
On Steam, this beta release is available on the DFHack beta
channel (for DF 50.13) and the adventure-beta
channel (for DF 51.01-beta).
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!
Highlights
Designating digging and constructions with shapes, Interactive map editing, Quick find and zoom for people, locations, and artifacts, Controlling rate of immigration, Plant and tree manipulation, Locale-sensitive number formatting
Designating digging and constructions with shapes
Our digging design tool, gui/design
has had a major usability overhaul.
There are now icons for selecting modes and shapes, and the overall experience of designating shapes, stretching, rotating, and moving them, and finally applying them to the map is much easier than it was before.
Have fun with those curves!
Interactive map editing
You may have heard of tiletypes
as the command to use for editing the map. It has a reputation for being difficult to understand, and startlingly easy to get wrong. Thanks to community member tatoyoda600's efforts, we now have gui/tiletypes
, which turns map editing into simple point and click!
You can now easily fill in gaps in accidentally-dug areas, spawn tiles of the material of your choice for digging, or reshape the surface terrain to your liking!
Quick find and zoom for people, locations, and artifacts
The new gui/sitemap
tool helps you find and zoom to things quickly.
It works in both adventure and fort mode. In adventure mode, its primary use is to find what you're looking for when you get to a site. If you have a quest to talk to a specific person or find a specific artifact, it can be very frustrating to arrive at the correct site but then be completely unable to find what you're looking for on the map. It doesn't help that nobody at the site can give you directions! gui/sitemap
will list all the people, places, and things of interest and let you zoom the screen to their location with a click. You'll still have to find your way over there, though, which can be a challenge if it's deep underground.
In fort mode, it serves as a faster alternative to the vanilla overview screens. It also has the unique benefit of telling you both the Dwarven and the English names of artifacts. Now, when you get a notification that Thunderbanner has been stolen, you can search for the artifact in gui/sitemap
and see that it's actually warning you about Amudzulban. Then you can zoom to its current location and search some pockets.
Controlling rate of immigration
A common complaint is that very large migrant waves can overwhelm fort infrastructure. If you enable the pop-control
tool in gui/control-panel
(Gameplay tab), you can limit migration waves to a reasonable size. The default is 10, but you can adjust it to any number you feel comfortable with.
Note that this tool will overwrite the population caps set in the vanilla settings, so if you have those numbers customized, be sure to update the setting for pop-control
itself. For example, if you want a maximum population of 100 (along with the default per-wave maximum of 10 immigrants), run
pop-control set max-pop 100
after you enable pop-control
.
Plant and tree manipulation
For those looking to meddle in the natural order, we now have the commandline plant
tool for spawning, growing, and removing plant life.
For example, to grow a sapling into a tree, enter mining mode, enable the keyboard cursor, and highlight the tile with the sapling on it. Then, run plant grow here
to increase the sapling's age. Once you unpause the game, the sapling will instantly grow into a tree!
Locale-sensitive number formatting
DFHack tools can display a lot of large numbers, especially where prices and weights are involved. We have traditionally formatted those numbers exactly the same as DF itself does -- that is, no formatting; just numbers. For example, one million is written as 1000000
.
This can be hard to read, but it's also not perfectly clear how else the numbers should be formatted. In English, we often add commas to numbers, one comma every third digit, so one million would be written as 1,000,000
. That would make it easier to read, assuming English is your native language. People from India might prefer to see one million as 10,00,000
, and people from Germany might prefer 1.000.000
.
So now you have a choice. In gui/control-panel
, in the Preferences tab, there is now a Large number formatting
preference that you can set.
You have several options:
- None (the default), which formats the numbers without embellishment like vanilla DF does (e.g.
1234567
) - English, which formats the numbers with commas every third digit (e.g.
1,234,567
) - System locale, which formats the numbers according to the locale settings for your operating system (system-dependent)
- SI suffix, which shows up to three significant digits and a metric-system suffix (e.g.
1.23M
) - Scientific, which shows numbers in scientific notation (e.g.
1.2e+06
)
Your choice will apply to DFHack displays, such as gui/unit-info-viewer
or the prices on the DFHack trade screens. Vanilla DF displays will not be affected.
Announcements
Behind-the-scenes changes, Dreamfort has been updated, PSAs
Behind-the-scenes changes
This release marks a significant step forward in aligning the DFHack names for variables with the actual names used internally by the Dwarf Fortress code. Not only does this help smooth communication between DFHack and DF devs, but it opens up a whole new world for modders who can now access large new sections of the game state. Expect new tools soon that capitalize on this improvement in accessibility, especially in regards to the world map!
One of the major reasons for this beta is to test the existing DFHack tools and ensure they were all properly migrated to the new naming scheme. Please be on the lookout for commands that you know worked before but that now spit out errors.
Dreamfort has been updated
The Dreamfort quickfort
blueprints have seen significant updates in this release. If you are in the middle of building from the Dreamfort blueprints, expect some minor errors or misplaced furniture if you started building from the Dreamfort blueprints in the previous DFHack version.
Starting from a new embark, of course, will work perfectly fine.
If you're not already familiar with it, Dreamfort is DFHack's marquee blueprint set for a complete fort layout. It demonstrates good design patterns for new players and shows what the game is capable of. For more experienced players, it provides a simple, yet complete fortress that you can quickly get up and running when you want to focus on specific aspects of the game and not worry too much about infrastructure.
Screenshots are available here: https://docs.dfhack.org/en/latest/docs/guides/quickfort-library-guide.html#dreamfort
and the walkthrough is available via the blueprint notes (which you can display with gui/quickfort) or online here: https://docs.google.com/spreadsheets/d/15TDBebP8rBNvsFbezb9xuKPmGWNzv7j4XZWq1AsfCio/edit?gid=0#gid=0
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
advtools
: collection of useful commands and overlays for adventure modebodyswap
: (reinstated) take control of another unit in adventure modedevel/tree-info
: print a technical visualization of tree datafix/occupancy
: fixes issues where you can't build somewhere because the game tells you an item/unit/building is in the way but there's nothing therefix/population-cap
: fixes the situation where you continue to get migrant waves even when you are above your configured population capgui/sitemap
: list and zoom to people, locations, and artifactsgui/tiletypes
: interface for modifying map tiles and tile propertiesplant
: (reinstated) tool for creating/growing/removing plantspop-control
: (reinstated) limit the maximum size of migrant waves
New Features
buildingplan
: dimension tooltip is now displayed for constructions and buildings that are designated over an area, like bridges and farm plotsgui/notify
: new notification type: injured citizens; click to zoom to injured units; also displays a warning if your hospital is not functional (or if you have no hospital)plant
: can nowremove
shrubs and saplings;list
all valid shrub/sapling raw IDs;grow
can make mature trees older; many new command optionsprioritize
: new info panel on under-construction buildings showing if the construction job has been taken and by whom. click to zoom to builder; toggle high priority status for job if it's not yet taken and you need it to be built ASAPtweak
:named-codices
: display book titles instead of a material description in the stocks/trade screens
Fixes
- Mortal mode: prevent keybindings that run armok tools from being recognized when in mortal mode
assign-profile
: fix handling ofunit
option for setting target unit idbuildingplan
: properly identify appropriate construction items for modded buildings built from threadcaravan
: fix errors in trade dialog if all fort items are traded away while the trade dialog is showing fort items and theconfirm
trade confirmation is shownconfirm
: fix confirmation prompt behavior when overwriting a hotkey zoom locationcontrol-panel
: restore non-default values of per-save enabled/disabled settings for repeat-based commandsdig
: don't leave phantom dig designations behind when autodigging warm/damp designated tilesgui/create-item
: allow creation of adamantine thread, wool, and yarngui/gm-unit
: correctly display skill levels above Legendary+5gui/sandbox
:- spawned citizens can now be useful military squad members
- spawned undead now have a purple shade (only after save and reload, though)
item
: don't match uncollected spider webs when you search for "silk"makeown
: set animals to tame and domesticatedquickfort
:- fix incorrect splitting of disjoint stockpiles that are given the same label (indicating that they should be part of the same stockpile)
- allow farm plots to be built on muddy stone
regrass
: don't remove mud on regrass, consistent with vanilla behaviorseedwatch
:- display a limit of
-
instead of0
for a seed that is present in inventory but not being watched - do not include unplantable tree seeds in status report
- display a limit of
suspend
: remove broken--onlyblocking
option; restore functionality tosuspend all
tiletypes
: make aquifers functional when adding theaquifer
propertyBuildings::containsTile
: fix result for buildings that are solid and have no extent structuresGui::makeAnnouncement
,Gui::autoDFAnnouncement
: fix skipping index 0 when iterating reports vector
Misc Improvements
- Dreamfort:
- add a full complement of beds and chests to both barracks
- redesign guildhall/temple/library level for better accessibility
- walkthough documentation refresh
- add milking/shearing station in surface grazing pasture
- integrate building prioritization into the blueprints and remove
prioritize
checklist steps - add plumbing template for filling cisterns with running water
autobutcher
: do not butcher pregnant (or brooding) femalesautonestbox
: wait until juveniles become adults before they are assigned to nestboxesblueprint
: capture track carving designations in addition to already-carved tracksbuildingplan
: add option to ignore items from a specified burrowcaravan
:- optional overlay to hide vanilla "bring trade goods to depot" button (if you prefer to always use the DFHack version and don't want to accidentally click on the vanilla button). enable
caravan.movegoods_hider
ingui/control-panel
UI Overlays tab to use. - bring goods to depot screen now shows (approximate) distance from item to depot
- add shortcut to the trade request screen for selecting item types by value (e.g. so you can quickly select expensive gems or cheap leather)
- optional overlay to hide vanilla "bring trade goods to depot" button (if you prefer to always use the DFHack version and don't want to accidentally click on the vanilla button). enable
changevein
: follow veins into adjacent map blocks so you can run the command once instead of once per map block that the vein touchesexterminate
: addall
target for convenient scorched earth tacticsgui/civ-alert
: you can now register multiple burrows as civilian alert safe spacesgui/control-panel
: highlight prefrences that have been changed from the defaultsgui/create-item
: allow right click to cancel out of material dialog submenusgui/design
:- significant redesign of UI for much improved usability
- circles are more circular (now matches behavior of
digcircle
)
gui/launcher
:- "space space to toggle pause" behavior is skipped if the game was paused when
gui/launcher
came up to prevent accidental unpausing - refresh default tag filter when mortal mode is toggled in
gui/control-panel
so changes to which tools autocomplete take effect immediately
- "space space to toggle pause" behavior is skipped if the game was paused when
gui/notify
: notification panel extended to apply to adventure modegui/quickfort
:- you can now delete your blueprints from the blueprint load dialog
- allow farm plots, dirt roads, and paved roads to be designated around partial obstructions without callling it an error, matching vanilla behavior
- buildings can now be constructed in a "high priority" state, giving them first dibs on
buildingplan
materials and setting their construction jobs to the highest priority
gui/unit-info-viewer
:- now displays a unit's weight, relative to either dwarves, elephants, or cats
- shows a unit's relative size compared to its race's average.
- add precise unit size in cc (cubic centimeters) for comparison against the wiki values. you can set your preferred number format for large numbers like this in the preferences of
control-panel
orgui/control-panel
logistics
: automatically forbid or claim items brought to a stockpilenestboxes
: increase the scanning frequency for fertile eggs to reduce the chance that they get snarfed by eager dwarvesquickfort
:- support buildable instruments
- new
delete
command for deleting player-owned blueprints (library and mod-added blueprints cannot be deleted) - support enabling
logistics
features for autoforbid and autoclaim on stockpiles
regrass
: now accepts numerical IDs for grass raws;regrass --list
replacesregrass --plant ""
suspendmanager
: add option tounsuspend
that unsuspends all jobs, regardless of potential issuestiletypes
:- performance improvements when affecting tiles over a large range
- support for heavy aquifers
- new
surroundings
property for autocorrecting adjacent tiles when making changes (e.g. adding ramp tops when you add a ramp)
Removed
adv-rumors
: merged intoadvtools
devel/find-offsets
,devel/find-twbt
,devel/prepare-save
: remove development scripts that are no longer usefulfix/item-occupancy
,fix/tile-occupancy
: merged intofix/occupancy
max-wave
: merged intopop-control
plants
: renamed toplant
dfhack.HIDE_CONSOLE_ON_STARTUP
anddfhack.HIDE_ARMOK_TOOLS
are no longer directly accessible. Please usecontrol-panel
orgui/control-panel
to interact wtih those settings.gui.FramedScreen
: this class is now deprecated; please usegui.ZScreen
andwidgets.Window
instead
API
- Focus strings have moved for stockpile states:
dwarfmode/CustomStockpile
is nowdwarfmode/Stockpile/Some/Customize
and similar fordwarfmode/StockpileTools
anddwarfmode/StockpileLink
Buildings::getName
: get a building's name, convenience method for easier use from Luaformat_number
: format numbers according to the configured player formatting preferenceItems::remove
: now cancels related jobs and marks the item as hidden and forbiddenMaps::isTileAquifer
: check if tile is an aquiferMaps::isTileHeavyAquifer
: check if tile is a heavy aquiferMaps::removeAreaAquifer
: remove aquifers from all tiles in a cuboid, with the option to provide a filterMaps::removeTileAquifer
: remove aquifer from tileMaps::setAreaAquifer
: make all tiles in a cuboid into aquifers, with the option to provide a filterMaps::setTileAquifer
: make tile into an aquiferUnits::create
,Units::makeown
: new APIs to use bay12-provided entry points for low-level operations
Lua
dfhack.formatInt
,dfhack.formatFloat
: formats numbers according to the player preferences for number formatting set ingui/control-panel
dfhack.gui.getSelectedJob
: can now return the job with a destination under the keyboard cursor (e.g. digging/carving/engraving jobs)dfhack.maps.isTileAquifer
,dfhack.maps.isTileHeavyAquifer
,dfhack.maps.setTileAquifer
,dfhack.maps.removeTileAquifer
: access to new aquifer APIdfhack.units.create
,dfhack.units.makeown
: Lua access to new module APIdialogs.showYesNoPrompt
: extend options so the standard dialog can be used forgui/confirm
-style confirmation promptsplugins.tiletypes.tiletypes_setTile
: can now accept a table for access to previously unavailable optionssafe_index
: will now return nil when attempting to index into a non-indexable objectscript-manager
: addgetModSourcePath
andgetModStatePath
so modders can get the directory path to their own fileswidgets.ButtonGroup
: subclass of CycleHotkeyLabel that additionally displays clickable graphical buttonswidgets.CycleHotkeyLabel
: when the widget has both forward and backward hotkeys defined, support moving backwards by clicking on the appropriate hotkey hintwidgets.DimensionsTooltip
: reusable selected dimensions tooltip that follows the mouse cursor aroundwidgets.FilteredList
: don't restrict the player from inputting multiple successive space characterswidgets.makeButtonLabelText
: create text and graphical buttons from character/color/tile maps and/or dynamically loaded tilesets
Structures
- added several bay12 exported entry points to list of known globals
- canonicalized a wide swath of type names, field names, and structure organization to match DF's internal names and organization. fields that already had useful names were largely left alone, but all
unk
,anon
, and other "placeholder" names have been changed. structures that differed from reality were also corrected (e.g. collections of fields that were actually substructures and vice versa). job.item_category
is nowjob.specflag
, contains a union of flag fields, and depends on the job typeplant_flags
: renameis_burning
,is_drowning
,is_dead
to Bay12 namesunused_01
,season_dead
,dead
slab_engraving_type
: correct order of items (last two were swapped)unitst
: correct return type ofcreate_nemesis
vmethodworld_data
: identify many fields and substructures
Documentation
installing
: add instructions for how to use Steam DFHack with non-Steam DF (ito benefit from DFHack auto-updates and cloud backups)modding-guide
: add a section on persistent storage, both for global settings and world-specific settings