1. DFHack - Dwarf Fortress Modding Engine
  2. News

DFHack - Dwarf Fortress Modding Engine News

DFHack 50.08-r3

Generated release notes
[h2]Fixes[/h2]
  • Fix crash for some players when they launch DF outside of the Steam client

DFHack 50.08-r2

This 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]Announcements[/h2][h3]Armok mode vs. Mortal mode[/h3]
If DFHack makes the game less fun for you because the tools are too powerful, please consider enabling "Mortal mode". Open the "Preferences" tab of gui/control-panel and toggle the "Show armok tools" setting. This will hide any tools that are tagged as "armok" (that is, god-mode tools) from gui/launcher, gui/control-panel, the DFHack logo popup menu, and anywhere else DFHack commands are listed. Global hotkeys for those tools will also cease to function. All productivity, analysis, bugfix, and design tools will still be shown as normal.
[h3]Ongoing large projects[/h3]
Here are the projects we're working on right now (and the [@ person] on DFHack Discord you should talk to if you have opinions). If you are interested in early access, please join the "Beta - DFHack pre-releases" branch in your Steam client. You can also download pre-releases from GitHub.
  • buildingplan v2 [@TaxiService] - clearer UI, easier configuration, filter history
  • stocks [@silver_fly] - item management interface, including bulk actions like "mark all worn clothing for trade"
  • stockpiles, logistics, quickfort [@myk002] - stockpile configuration presets, automatic dumping, trading, or melting of stockpile contents, stockpile and zone support for quickfort
  • gui/design v2 [@coskerstrike] - UI overhaul, performance improvements

and, of course, a host of smaller bugfixes and features.
[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 in the DF settings, and you can show it by entering mining mode or selecting the dump/forbid tool. We're working on making DFHack tools more mouse-aware and accessible.
[h2]Highlights[/h2][h3]exportlegends[/h3]

There are a variety of tools for digging into the stories in legends mode. Most of them use the extra legends information DFHack exports with the exportlegends tool to give you a more complete picture of what is going on.

How to use:
  1. Enter legends mode as usual from DF
  2. Click the green button to do the vanilla export
  3. Open gui/launcher and run exportlegends

exportlegends might take a while to run if your world is large. Now you should have two .xml files in your Dwarf Fortress folder. The ...-legends_plus.xml file is the extended export from DFHack.

Note that DF itself used to export more information than it does now, and many tools can't cope with the lack of vanilla information. The current best tool to use for external legends browsing is the cross-platform Legends Browser 2

Happy legends browsing!
[h3]gui/mod-manager[/h3]

For those of us who use mods, creating a new world can be very frustrating. Each mod must be manually re-enabled for every new created world, and for long mod lists, that is quite a chore.

Enter gui/mod-manager. You don't actually have to run the command. It will show up as an overlay automatically when you create a new world. If you have a default mod list saved already, you don't even need to go into the DF "Mods" page. As soon as you start the world creation process, gui/mod-manager will automatically apply your mod list.

To set it up, start creating a world and set up your mods as normal. Then click on the "Mod manager" button at the bottom of the page or hit the m hotkey. This will bring up a dialog where you can save your current mod list and set it as the default for future worlds. That's it.
[h3]gui/sandbox[/h3]

This tool stretches the bounds of "Armok mode". It gives you an interface for willing units, trees, and items into existence. Feeling like you need a challenge? Set units to "hostile" and spawn yourself up an invading army : )
[h3]necronomicon[/h3]

Sometimes you want your dwarves to become necromancers, and sometimes you don't. However, you can't control what visitors or returning raiders bring back into your fort. It used to be that you'd have to manually scan through every book and see whether it contains the "secrets of life and death". Now, a quick run of the necronomicon command will give you a summary of whether you have any books with secrets in your fort and what their titles (and powers) are. Then you can sequester those books or promote them on display in your library, as per your agenda.
Generated release notes
[h2]New Plugins[/h2]
  • add-spatter: (reinstated) allow mods to add poisons and magical effects to weapons
  • changeitem: (reinstated) change item material, quality, and subtype
  • createitem: (reinstated) create arbitrary items from the command line
  • deramp: (reinstated) removes all ramps designated for removal from the map
  • flows: (reinstated) counts map blocks with flowing liquids
  • lair: (reinstated) mark the map as a monster lair (this avoids item scatter when the fortress is abandoned)
  • luasocket: (reinstated) provides a Lua API for accessing network sockets
  • work-now: (reinstated, renamed from workNow) prevent dwarves from wandering aimlessly with "No job" after completing a task
[h2]New Scripts[/h2]
  • assign-minecarts: (reinstated) quickly assign minecarts to hauling routes
  • diplomacy: view or alter diplomatic relationships
  • exportlegends: (reinstated) export extended legends information for external browsing
  • fix/stuck-instruments: fix instruments that are attached to invalid jobs, making them unusable. turn on automatic fixing in gui/control-panel in the Maintenance tab.
  • gui/autodump: point and click item teleportation and destruction interface (available only if armok tools are shown)
  • gui/mod-manager: automatically restore your list of active mods when generating new worlds
  • gui/sandbox: creation interface for units, trees, and items (available only if armok tools are shown)
  • light-aquifers-only: (reinstated) convert heavy aquifers to light
  • modtools/create-item: (reinstated) commandline and API interface for creating items
  • necronomicon: search fort for items containing the secrets of life and death
[h2]Fixes[/h2]
  • DFHack screen backgrounds now use appropriate tiles in DF Classic
  • RemoteServer: fix crash on malformed json in dfhack-config/remote-server.json
  • autolabor: work detail override warning now only appears on the work details screen
  • deathcause: fix incorrect weapon sometimes being reported
  • gui/create-item: allow armor to be made out of leather when using the restrictive filters
  • gui/design: Fix building and stairs designation
  • quickfort:
    • properly allow dwarves to smooth, engrave, and carve beneath walkable tiles of buildings
    • fixed detection of tiles where machines are allowed (e.g. water wheels can be built on stairs if there is a machine support nearby)
    • fixed rotation of blueprints with carved track tiles
  • RemoteFortressReader: ensured names are transmitted in UTF-8 instead of CP437
[h2]Misc Improvements[/h2]
  • Core: new commandline flag/environment var: pass --disable-dfhack on the Dwarf Fortress commandline or specify DFHACK_DISABLE=1 in the environment to disable DFHack for the current session.
  • Dreamfort: improve traffic patterns throughout the fortress
  • Settings: recover gracefully when settings files become corrupted (e.g. by DF CTD)
  • Window behavior:
    • non-resizable windows now allow dragging by their frame edges by default
    • if you have multiple DFHack tool windows open, scrolling the mouse wheel while over an unfocused window will focus it and raise it to the top
  • autodump: no longer checks for a keyboard cursor before executing, so autodump destroy (which doesn't require a cursor) can still function
  • gui/autodump: fort-mode keybinding: Ctrl-H (when armok tools are enabled in gui/control-panel)
  • gui/blueprint: recording of stockpile layouts and categories is now supported. note that detailed stockpile configurations will not be saved (yet)
  • gui/control-panel: new preference for whether filters in lists search for substrings in the middle of words (e.g. if set to true, then "ee" will match "steel")
  • gui/create-item: ask for number of items to spawn by default
  • gui/design: Improved performance for drawing shapes
  • gui/gm-editor:
    • when passing the --freeze option, further ensure that the game is frozen by halting all rendering (other than for DFHack tool windows)
    • Alt-A now enables auto-update mode, where you can watch values change live when the game is unpaused
  • gui/quickfort:
    • blueprints that designate items for dumping/forbidding/etc. no longer show an error highlight for tiles that have no items on them
    • place (stockpile layout) mode is now supported. note that detailed stockpile configurations were part of query mode and are not yet supported
    • you can now generate manager orders for items required to complete bluerpints
  • light-aquifers-only: now available as a fort Autostart option in gui/control-panel. note that it will only appear if "armok" tools are configured to be shown on the Preferences tab.
  • orders: update orders in library for prepared meals, bins, archer uniforms, and weapons
  • overlay: add links to the quickstart guide and the control panel on the DF title screen
  • stockpiles: allow filtering creatures by tameability
[h2]Removed[/h2]
  • orders: library/military_include_artifact_materials library file removed since recent research indicates that platinum blunt weapons and silver crossbows are not more effective than standard steel. the alternate military orders file was also causing unneeded confusion.
[h2]Internals[/h2]
  • dfhack.internal: added memory analysis functions: msizeAddress, getHeapState, heapTakeSnapshot, isAddressInHeap, isAddressActiveInHeap, isAddressUsedAfterFreeInHeap, getAddressSizeInHeap, and getRootAddressOfHeapObject
[h2]Lua[/h2]
  • ensure_keys: walks a series of keys, creating new tables for any missing values
  • gui: changed frame naming scheme to FRAME_X rather than X_FRAME, and added aliases for backwards compatibility. (for example BOLD_FRAME is now called FRAME_BOLD)
  • overlay.reload(): has been renamed to overlay.rescan() so as not to conflict with the global reload() function. If you are developing an overlay, please take note of the new function name for reloading your overlay during development.
[h2]Structures[/h2]
  • abstract_building_contents: identify fields and flags related to location item counts
  • arena_tree: identify fields related to tree creation
  • arena_unit: identify fields related to unit creation
  • mod_headerst: rename non_vanilla flag to vanilla to reflect its actual usage
  • profession: renamed captions Cheese Maker to Cheesemaker, Bee Keeper to Beekeeper, and Bone Setter to Bone Doctor

DFHack 50.08-r2rc1

[h2]New Plugins[/h2]
  • add-spatter: reinstated: allow mods to add poisons and magical effects to weapons
  • changeitem: reinstated: change item material, quality, and subtype
  • createitem: reinstated: create arbitrary items, from the command line
  • deramp: reinstated: removes all ramps designated for removal from the map
  • flows: reinstated: counts map blocks with flowing liquids
  • lair: reinstated: mark the map as a monster lair (this avoids item scatter when the fortress is abandoned)
  • luasocket: reinstated: provides a Lua API for accessing network sockets
  • work-now: reinstated, renamed from workNow: reduce the time that dwarves are left without a task after completing a job
[h2]New Scripts[/h2]
  • exportlegends: reinstated: export extended legends information for external browsing
  • gui/autodump: point and click item teleportation and destruction interface
  • gui/mod-manager: automatically restore your list of active mods when generating new worlds
  • light-aquifers-only: reinstated: convert heavy aquifers to light
  • modtools/create-item: reinstated: commandline and API interface for creating items
  • necronomicon: search fort for items containing the secrets of life and death
[h2]Fixes[/h2]
  • DFHack screen backgrounds now use appropriate tiles in DF Classic
  • RemoteServer: fix crash on malformed json in dfhack-config/remote-server.json
  • autolabor: work detail override warning now only appears on the work details screen
  • gui/design: Fix building and stairs designation
[h2]Misc Improvements[/h2]
  • Core: For debugging purposes, you can now pass --disable-dfhack on the Dwarf Fortress commandline or specify DFHACK_DISABLE=1 in the environment to disable DFHack for the current session.
  • Dreamfort: improve traffic patterns throughout the fortress (stockpiles and zones are still not working, pending updates in quickfort)
  • Terminal console no longer appears in front of the game window on startup
  • gui/autodump: fort-mode keybinding: Ctrl-H
  • gui/control-panel: new preference for whether filters in lists search for substrings in the middle of words (e.g. if set to true, then "ee" will match "steel")
  • gui/create-item: ask for number of items to spawn by default
  • gui/design: Improved performance for drawing shapes
  • gui/gm-editor: when passing the --freeze option, further ensure that the game is frozen by halting all rendering (other than for the gm-editor window itself)
  • light-aquifers-only: now available as a fort Autostart option in gui/control-panel. note that it will only appear if "armok" tools are configured to be shown on the Preferences tab.
  • orders: update orders in orders library for prepared meals, bins, archer uniforms, and weapons
[h2]Removed[/h2]
  • orders: library/military_include_artifact_materials library file removed since recent research indicates that platinum blunt weapons and silver crossbows are not more effective than standard steel. the alternate military orders file was also causing unneeded confusion.
[h2]Lua[/h2]
  • gui: changed frame naming scheme to FRAME_X rather than X_FRAME, and added aliases for backwards compatibility. (for example BOLD_FRAME is now called FRAME_BOLD)
  • overlay.reload(): has been renamed to overlay.rescan() so as not to conflict with the global reload() function. If you are developing an overlay, please take note of the new function name for reloading your overlay during development.
[h2]Structures[/h2]
  • mod_headerst: rename non_vanilla flag to vanilla to reflect its actual usage

DFHack 50.08-r1

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]Announcements[/h2][h3]What's next?[/h3]
Here are the projects we're working on right now (and the [@ person] on DFHack Discord you should talk to if you have opinions). If you are interested in early access, please join the "Beta - DFHack pre-releases" branch in your Steam client. You can also download pre-releases from GitHub.
  • buildingplan v2 [@TaxiService] - clearer UI, easier configuration, filter history
  • stocks [@silver_fly] - item management interface, including bulk actions like "mark all worn clothing for trade"
  • stockpiles and logistics [@myk002] - stockpile configuration presets, automatic dumping, trading, or melting of stockpile contents
  • gui/design v2 [@coskerstrike] - UI overhaul, performance improvements
  • gui/create-unit [@Thazzeus] - unit spawning interface

and, of course, a host of smaller bugfixes and features.
[h3]Poll results[/h3]
We ran a poll on reddit to hear your opinions for what DFHack's Next Big Thing should be. The results:
  1. 30% manipulator - in-game Dwarf Therapist-like labor assignment and unit management interface
  2. 18% search, embark-assistant (tie) - better search functionality for vanilla dialogs, extended options for embark location discovery, respectively
  3. 15% tooltips - in-game help tooltips for DFHack UIs
  4. 11% quickfort - stockpile and zone support for blueprints, including Dreamfort support
  5. 6% exportlegends - extended data for legends export, allowing external tools like Legends Viewer to work

These are all huge projects, and don't expect their completion any time soon, but the results of the poll helped us set priorities for upcoming development. If you have opinions about any of those tools, or if you're just curious about the implementation plans, or if you'd like to help, please check out the GitHub issues where they are being discussed (hyperlinked above).
[h3]Terminal hidden by default[/h3]
From a less formal poll, it seems that most players consider the DFHack terminal (the external DFHack window that pops up when you start DF) to be a nuisance, or at least not necessary. The terminal window will now be hidden and out of the way by default. You can unhide the terminal at any time by running the show command in gui/launcher (and hide it again with the hide command).

If you want to keep the terminal window shown at startup, go to the "Preferences" tab of gui/control-panel and toggle the option there.

Note that text-interactive commands, like the built-in lua interpreter or the tiletypes command, can only be run from that external terminal window. Most players will never have need to run these, though.
[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 in the DF settings, and you can show it by entering mining mode or selecting the dump/forbid tool. We're working on making DFHack tools more mouse-aware and accessible.
[h2]Highlights[/h2][h3]Mortal mode[/h3]


We finally have an answer for those players who want to use DFHack for its bug fixes, interface improvements, and productivity tools, but feel uncomfortable with the tools that grant god-like powers over the game. Armok, if you didn't already know, is the god of Dwarf Fortress. If you don't want to see these "armok" tools, go into gui/control-panel, on the "Preferences" tab, and toggle on the Hide "armok" tools in command lists setting.
[h3]Dude, where's my planner?[/h3]


You may notice that the DFHack building planner appears to be missing. Don't worry, it's not gone. It's just minimized by default. If you want to use it again, just expand it by clicking on the "show planner" button and it will stay expanded, just like it was before.

Why did we do this? Now that DFHack has entered the "stable release" phase, we want to go back to our roots and not supplant vanilla functionality by default. From now on, if there is a DFHack interface enhancement that can replace a vanilla element, it will show up as a minimized panel that you can expand and use. The panels that simply add extra functionality without getting in the way, like order import/export and the trade screen enhancements, will still stay expanded by default.
Generated release notes
[h2]Fixes[/h2]
  • autoclothing: eliminate game lag when there are many inventory items in the fort
  • buildingplan:
    • fixed size limit calculations for rollers
    • fixed items not being checked for accessibility in the filter and item selection dialogs
  • deteriorate: ensure remains of enemy dwarves are properly deteriorated
  • dig-now: properly detect and complete smoothing designations that have been converted into active jobs
  • suspendmanager: Fix over-aggressive suspension of jobs that could still possibly be done (e.g. jobs that are partially submerged in water)
[h2]Misc Improvements[/h2]
  • buildingplan:
    • planner panel is minimized by default and now remembers minimized state
    • can now filter by gems (for gem windows) and yarn (for ropes in wells)
  • combine: Now supports ammo, parts, powders, and seeds, and combines into containers
  • deteriorate: add option to exclude useable parts from deterioration
  • gui/control-panel:
    • add preference option for hiding the terminal console on startup
    • add preference option for hiding "armok" tools in command lists
  • gui/gm-editor:
    • press g to move the map to the currently selected item/unit/building
    • press Ctrl-D to toggle read-only mode to protect from accidental changes; this state persists across sessions
    • new --freeze option for ensuring the game doesn't change while you're inspecting it
  • gui/launcher: DFHack version now shown in the default help text
  • gui/prerelease-warning: widgets are now clickable
  • overlay: add the DFHack version string to the DF title screen
  • Dwarf Therapist: add a warning to the Labors screen when Dwarf Therapist is active so players know that changes they make to that screen will have no effect. If you're starting a new embark and nobody seems to be doing anything, check your Labors tab for this warning to see if Dwarf Therapist thinks it is in control (even if it's not running).
  • toggle-kbd-cursor: add hotkey for toggling the keyboard cursor (Alt-K)
  • version: add alias to display the DFHack help (including the version number) so something happens when players try to run "version"
[h2]Removed[/h2]
  • title-version: replaced by an overlay widget
[h2]Lua[/h2]
  • gui.ZScreenModal: ZScreen subclass for modal dialogs
  • widgets.CycleHotkeyLabel: exposed "key_sep" and "option_gap" attributes for improved stylistic control.
  • widgets.RangeSlider: new mouse-controlled two-headed slider widget

DFHack 50.07-r2rc3

Beta release for those subscribed to the "beta" release channel. Please tell us if you like the new "Hide armok tools" preference in the control panel!
[h2]Fixes[/h2]
  • autoclothing: eliminate game lag when there are many inventory items in the fort
  • buildingplan: fixed size limit calculations for rollers
  • dig-now: properly detect and complete smoothing designations that have been converted into active jobs
  • suspendmanager: Fix over-aggressive suspension of jobs that could still possibly be done (e.g. jobs that are partially submerged in water)
[h2]Misc Improvements[/h2]
  • buildingplan:
    • planner panel is minimized by default and now remembers minimized state
    • can now filter by gems (for gem windows) and yarn (for ropes in wells)
  • gui/gm-editor: new --freeze option for ensuring the game doesn't change while you're inspecting it
  • gui/launcher: DFHack version now shown in the default help text
  • gui/prerelease-warning: widgets are now clickable
  • overlay: add the DFHack version string to the DF title screen
  • Dwarf Therapist: add a warning to the Labors screen when Dwarf Therapist is active so players know that changes they make to that screen will have no effect. If you're starting a new embark and nobody seems to be doing anything, check your Labors tab for this warning to see if Dwarf Therapist thinks it is in control (even if it's not running).
  • version: add alias to display the DFHack help (including the version number) so something happens when players try to run "version"
[h2]Removed[/h2]
  • title-version: replaced by an overlay widget
[h2]Lua[/h2]
  • gui.ZScreenModal: ZScreen subclass for modal dialogs
  • widgets.RangeSlider: new mouse-controlled two-headed slider widget