Sep 7, 2023
DFHack - Dwarf Fortress Modding Engine - myk002
This release is compatible with all distributions of Dwarf Fortress: Steam, Itch, and Classic.
For the Dwarf Fortress beta branch on Steam, this release works with the Linux version (50.09-linux1) but NOT the Windows version. Windows users have to move to the DF default branch to be able to use DFHack. Note that the Windows version currently on the beta branch has no new features compared to the default branch, so you won't be missing out on anything.
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!
Both DF and DFHack now run natively on Linux. If you're on Linux, we encourage you to try it out! The interface is noticeably snappier, FPS is up, and load times are reduced. If you're subscribed to DF and DFHack on Steam, here's how to switch over:
Then, turn off the compatibility layer for DFHack. dfhooks.dll will disappear and you'll get libdfhooks.so and the dfhack script in its place.
Sometimes, Steam says you've got the Linux version, but when you look you see you still have Dwarf Fortress.exe instead of dwarfort. Try re-enabling the Proton compatibility layer and then turning off the compatibility layer again until it "sticks".
Major caveat for DF 50.09-linux1
This particular beta release of Dwarf Fortress has address layout randomization enabled. This causes some trouble for DFHack since DFHack needs to know the memory addresses of several key data structures. For this release only, be sure to start DF by launching DFHack from the Steam client or by running the ./dfhack commandline startup script. That will normalize the address space and allow DF to run with DFHack. Otherwise, DF will crash on startup. Again, this is only for this release. Future releases will not need this workaround and should go back to allowing you to start DF from either the Dwarf Fortress or DFHack Steam client entries, or from either the ./dwarfort or ./dfhack commandline commands.
The DFHack terminal console works differently on Linux
You can run DF with DFHack by starting DFHack in the Steam client. However, if you want an external DFHack terminal console, you have to run from the commandline.
On Windows, you could use the show command to pop up an external DFHack terminal console. You could use this for running DFHack commands from outside the game window, and the external terminal is the only way to run commandline-interactive DFHack commands like tiletypes and the interactive mode of the lua interpreter.
Linux has a different method of providing a terminal console. You can't spawn it dynamically like you can on Windows. You have to start DF from the commandline, and the terminal from which you ran ./dwarfort becomes the terminal console. This should be a familiar process to many Linux users (most Linux commands work this way), but the change is jarring if you're not expecting it. We're also looking into providing a virtual console that doesn't depend on an existing system console so you can still get a console even if you run from Steam, but that work is far from being completed.
You can still launch DFHack from Steam if you want to. Many tools log information and errors to the console, though, so if you run into strange issues, it might be useful to try running from the commandline to see if there is diagnostic output there that can help you.
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.
Once you've played a few forts, you probably don't need the tutorial popups that <del>assault</del> assist you when you open certain screens. Enable hide-tutorials in the System tab of gui/control-panel and never be bothered by them again!
When you bring up the screen to assign units to squads, there are now widgets for searching, sorting, and filtering. The default sort is by "melee effectiveness", which takes both weapon skill and physical attributes into account, but you can choose from a variety of relevant ascending or descending sorting orders.
Thanks to research into combat mechanics by community contributor Halifay, you can also sort by melee and ranged "potential", which predicts how effective a unit could become in the future, given adequate training.
There are also configurable filters to show or hide units in other squads, appointed/elected officials (like your manager, high priests, and doctors), and nobility.
Of course, if you know exactly who you're looking for, you can also search for units by name.
The "Assign to pasture" screen released in the previous DFHack version has been expanded and generalized to support cages, restraints, and pits/ponds. Please tell us if you have any additional needs for animal assignment that those screens don't meet!
The "Bring goods to trade depot" screen can now see inside bins, and you can select individual items within bins for trade instead of the entire bin, if you so choose. You can also search for contents within bins, even when in "bring the bin" mode. For example, you can find the "Gem bin"s that contain rubies by searching for "ruby".
exportlegends now sports a new integration with the vanilla "Export XML" button. Now you can generate both the vanilla export and the extended data export with a single click!
hide-interface hides all the vanilla UI elements for clean screenshots or distraction-free fortress watching. Even with the interface hidden, you can still pause/unpause the game with spacebar and move around the map with the keyboard or mouse. Hide that cluster of urgent notifications bubbles for a while and just enjoy watching your citizens scurry around for a while : )
For the Dwarf Fortress beta branch on Steam, this release works with the Linux version (50.09-linux1) but NOT the Windows version. Windows users have to move to the DF default branch to be able to use DFHack. Note that the Windows version currently on the beta branch has no new features compared to the default branch, so you won't be missing out on anything.
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!
Announcements
Linux support!
Both DF and DFHack now run natively on Linux. If you're on Linux, we encourage you to try it out! The interface is noticeably snappier, FPS is up, and load times are reduced. If you're subscribed to DF and DFHack on Steam, here's how to switch over:
- In the Steam client, open the properties for Dwarf Fortress
- In the "Betas" section, switch to the "beta" branch
- Let that finish updating
- Select the "Compatibility" section and deselect "Force the use of a specific Steam Play compatibility tool"
- DF should update again with the Linux native version
Then, turn off the compatibility layer for DFHack. dfhooks.dll will disappear and you'll get libdfhooks.so and the dfhack script in its place.
Sometimes, Steam says you've got the Linux version, but when you look you see you still have Dwarf Fortress.exe instead of dwarfort. Try re-enabling the Proton compatibility layer and then turning off the compatibility layer again until it "sticks".
Major caveat for DF 50.09-linux1
This particular beta release of Dwarf Fortress has address layout randomization enabled. This causes some trouble for DFHack since DFHack needs to know the memory addresses of several key data structures. For this release only, be sure to start DF by launching DFHack from the Steam client or by running the ./dfhack commandline startup script. That will normalize the address space and allow DF to run with DFHack. Otherwise, DF will crash on startup. Again, this is only for this release. Future releases will not need this workaround and should go back to allowing you to start DF from either the Dwarf Fortress or DFHack Steam client entries, or from either the ./dwarfort or ./dfhack commandline commands.
The DFHack terminal console works differently on Linux
You can run DF with DFHack by starting DFHack in the Steam client. However, if you want an external DFHack terminal console, you have to run from the commandline.
On Windows, you could use the show command to pop up an external DFHack terminal console. You could use this for running DFHack commands from outside the game window, and the external terminal is the only way to run commandline-interactive DFHack commands like tiletypes and the interactive mode of the lua interpreter.
Linux has a different method of providing a terminal console. You can't spawn it dynamically like you can on Windows. You have to start DF from the commandline, and the terminal from which you ran ./dwarfort becomes the terminal console. This should be a familiar process to many Linux users (most Linux commands work this way), but the change is jarring if you're not expecting it. We're also looking into providing a virtual console that doesn't depend on an existing system console so you can still get a console even if you run from Steam, but that work is far from being completed.
You can still launch DFHack from Steam if you want to. Many tools log information and errors to the console, though, so if you run into strange issues, it might be useful to try running from the commandline to see if there is diagnostic output there that can help you.
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.
Highlights
Hide tutorial popups
Once you've played a few forts, you probably don't need the tutorial popups that <del>assault</del> assist you when you open certain screens. Enable hide-tutorials in the System tab of gui/control-panel and never be bothered by them again!
Search and sort for squad assignment screen
When you bring up the screen to assign units to squads, there are now widgets for searching, sorting, and filtering. The default sort is by "melee effectiveness", which takes both weapon skill and physical attributes into account, but you can choose from a variety of relevant ascending or descending sorting orders.
Thanks to research into combat mechanics by community contributor Halifay, you can also sort by melee and ranged "potential", which predicts how effective a unit could become in the future, given adequate training.
There are also configurable filters to show or hide units in other squads, appointed/elected officials (like your manager, high priests, and doctors), and nobility.
Of course, if you know exactly who you're looking for, you can also search for units by name.
Animal assignment
The "Assign to pasture" screen released in the previous DFHack version has been expanded and generalized to support cages, restraints, and pits/ponds. Please tell us if you have any additional needs for animal assignment that those screens don't meet!
Trade good selection
The "Bring goods to trade depot" screen can now see inside bins, and you can select individual items within bins for trade instead of the entire bin, if you so choose. You can also search for contents within bins, even when in "bring the bin" mode. For example, you can find the "Gem bin"s that contain rubies by searching for "ruby".
One-click UI integration for exportlegends
exportlegends now sports a new integration with the vanilla "Export XML" button. Now you can generate both the vanilla export and the extended data export with a single click!
Onscreen HUD getting in your way? Hide it!
hide-interface hides all the vanilla UI elements for clean screenshots or distraction-free fortress watching. Even with the interface hidden, you can still pause/unpause the game with spacebar and move around the map with the keyboard or mouse. Hide that cluster of urgent notifications bubbles for a while and just enjoy watching your citizens scurry around for a while : )
Generated release notes
New Tools
- devel/scan-vtables: scan and dump likely vtable addresses (for memory research)
- hide-interface: hide the vanilla UI elements for clean screenshots or laid-back fortress observing
- hide-tutorials: hide the DF tutorial popups; enable in the System tab of gui/control-panel
- set-orientation: tinker with romantic inclinations (reinstated from back catalog of tools)
New Features
- buildingplan: one-click magma/fire safety filter for planned buildings
- exportlegends: new overlay that integrates with the vanilla "Export XML" button. Now you can generate both the vanilla export and the extended data export with a single click!
- sort: search, sort, and filter for squad assignment screen
- zone: advanced unit assignment screens for cages, restraints, and pits/ponds
Fixes
- Core:
- reload scripts in mods when a world is unloaded and immediately loaded again
- fix text getting added to DFHack text entry widgets when Alt- or Ctrl- keys are hit
- autobutcher: fix ticks commandline option incorrectly rejecting positive integers as valid values
- buildingplan: ensure selected barrels and buckets are empty (or at least free of lye and milk) as per the requirements of the building
- caravan:
- corrected prices for cages that have units inside of them
- correct price adjustment values in trade agreement details screen
- apply both import and export trade agreement price adjustments to items being both bought or sold to align with how vanilla DF calculates prices
- cancel any active TradeAtDepot jobs if all caravans are instructed to leave
- emigration:
- fix errors loading forts after dwarves assigned to work details or workshops have emigrated
- fix citizens sometimes "emigrating" to the fortress site
- fix/retrieve-units: fix retrieved units sometimes becoming duplicated on the map
- gui/launcher, gui/gm-editor: recover gracefully when the saved frame position is now offscreen
- gui/sandbox: correctly load equipment materials in modded games that categorize non-wood plants as wood
- orders: prevent import/export overlay from appearing on the create workorder screen
- quickfort: cancel old dig jobs that point to a tile when a new designation is applied to the tile
- seedwatch: ignore unplantable tree seeds
- starvingdead: ensure sieges end properly when undead siegers starve
- suspendmanager:
- Fix the overlay enabling/disabling suspendmanager unexpectedly
- improve the detection on "T" and "+" shaped high walls
- tailor: remove crash caused by clothing items with an invalid maker_race
- dialogs.MessageBox: fix spacing around scrollable text
Misc Improvements
- Surround DFHack-specific UI elements with square brackets instead of red-yellow blocks for better readability
- autobutcher: don't mark animals for butchering if they are already marked for some kind of training (war, hunt)
- caravan: optionally display items within bins in bring goods to depot screen
- createitem: support creating items inside of bags
- devel/lsmem: added support for filtering by memory addresses and filenames
- gui/design: change "auto commit" hotkey from c to Alt-c to avoid conflict with the default keybinding for z-level down
- gui/gm-editor:
- hold down shift and right click to exit, regardless of how many substructures deep you are
- display in the title bar whether the editor window is scanning for live updates
- gui/liquids: support removing river sources by converting them into stone floors
- gui/quickfort: blueprint details screen can now be closed with Ctrl-D (the same hotkey used to open the details)
- hotkeys: don't display DFHack logo in legends mode since it covers up important interface elements. the Ctrl-Shift-C hotkey to bring up the menu and the mouseover hotspot still function, though.
- quickfort: linked stockpiles and workshops can now be specified by ID instead of only by name. this is mostly useful when dynamically generating blueprints and applying them via the quickfort API
- sort: animals are now sortable by race on the assignment screens
- suspendmanager: display a different color for jobs suspended by suspendmanager
API
- RemoteFortressReader: add a force_reload option to the GetBlockList RPC API to return blocks regardless of whether they have changed since the last request
- Gui: getAnyStockpile and getAnyCivzone (along with their getSelected variants) now work through layers of ZScreens. This means that they will still return valid results even if a DFHack tool window is in the foereground.
- Items::getValue(): remove caravan_buying parameter since the identity of the selling party doesn't actually affect the item value
- Units: new animal propery check functions isMarkedForTraining(unit), isMarkedForTaming(unit), isMarkedForWarTraining(unit), and isMarkedForHuntTraining(unit)
Lua
- dfhack.gui: new getAnyCivZone and getAnyStockpile functions; also behavior of getSelectedCivZone and getSelectedStockpile functions has changes as per the related API notes
- dfhack.items.getValue(): remove caravan_buying param as per C++ API change
- dfhack.screen.readTile(): now populates extended tile property fields (like top_of_text) in the returned Pen object
- dfhack.units: new animal propery check functions isMarkedForTraining(unit), isMarkedForTaming(unit), isMarkedForWarTraining(unit), and isMarkedForHuntTraining(unit)
- new(): improved error handling so that certain errors that were previously uncatchable (creating objects with members with unknown vtables) are now catchable with pcall()
- widgets.BannerPanel: panel with distinctive border for marking DFHack UI elements on otherwise vanilla screens
- widgets.Panel: new functions to override instead of setting corresponding properties (useful when subclassing instead of just setting attributes): onDragBegin, onDragEnd, onResizeBegin, onResizeEnd
Structures
- Added global_table global and corresponding global_table_entry type
- help_context_type: fix typo in enum name: EMBARK_TUTORIAL_CHICE -> EMBARK_TUTORIAL_CHOICE
- plotinfo: name the fields related to tutorial popups
- viewscreen_legendsst: realign structure
- viewscreen_new_arenast: added (first appeared in 50.06)
Share: 
