DFHack - Dwarf Fortress Modding Engine News

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!
[h2]What needs testing?[/h2][h3]agitation-rebalance updates[/h3]
agitation-rebalance has seen significant internal improvements, especially around the calculations of chance of invasion. In the previous beta, after a cavern invasion, you'd see the cavern danger level immediately drop to None and then, after sufficient subsequent irritation, it would jump to High in one go.

Now, after clearing an invasion, you'll see your chances of a subsequent invasion smoothly increase from Low to High as you chop more trees and make more noise, which is much closer to the behavior `agitation-rebalance` provides on the surface for agitated wildlife attacks. Moreover, if you have the monitor panel visible, you will not see the danger level of the caverns update until you clear the current invasion. This is to avoid spoiling exactly when and where a cavern invasion has occurred. This mod is supposed to fix the mechanics of irritation -- it's not supposed to spoil the surprise when it happens!
[h2]Announcements[/h2][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 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.
[h2]New Tools[/h2]

• fix/ownership: fix instances of multiple citizens claiming the same items, resulting in "Store owned item" job loops
• modtools/if-entity: (reinstated) modder's resource for triggering scripted content depending on the race of the loaded fort

[h2]Fixes[/h2]

• autoclothing: don't produce clothes for dead units
• caravan: fix trade price calculations when the same item was requested for both import and export

[h2]Misc Improvements[/h2]

• Many tools that previously only worked for citizens or only for dwarves now work for all citizens and residents, e.g. fastdwarf, rejuvenate, etc.
• allneeds:
  • select a dwarf in the UI to see a summary of needs for just that dwarf
  • provide options for sorting the cumulative needs by different criteria
• buildingplan: persist hiding of unavailable materials between filterselection invocations
• dwarfvet:
  • automatically unassign animals from pastures when they need treatment so they can make their way to the hospital. reassign them to their original pasture when treatment is complete.
  • ignore animals assigned to cages or restraints
• gui/notify: Shift click or Shift Enter on a zoomable notification to zoom to previous target
• prioritize: print out custom reaction and hauling jobs in the same format that is used for prioritize command arguments so the player can just copy and paste

[h2]API[/h2]

• Units :: getCitizens: now includes residents by default
• Units :: isResident: property check for residents (as opposed to citizens)

[h2]Lua[/h2]

• dfhack.units.getCitizens: now includes residents by default

[h2]Structures[/h2]

• activity_event: identify fields and type values
• unit: identify and define many previously unknown fields, types, and enums

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!
[h2]What needs testing?[/h2]
There are several large new features for this release that could use testing and feedback.
[h3]agitation-rebalance smooths out agitated creature attacks and cavern invasions[/h3]


This is the one that needs the most feedback, especially from people who have found the cavern invasions to be frustrating. The basic question is: after you turn this mod on, do you still find the caverns frustrating? Do you feel like the caverns are more fun to explore and utilize?

If you're just confused by the whole agitated animal and cavern invasion thing, there is an overview of how the vanilla system works here: https://docs.dfhack.org/en/latest/docs/tools/agitation-rebalance.html#how-the-df-agitation-system-works

The tl;dr is that your actions annoy nature, and nature retaliates..endlessly. Many people find the constant nature of the retaliation to be overwhelming. This mod tempers the retaliation so once you get attacked, you won't get attacked again until you specifically provoke nature further.

How to use

Open up gui/control-panel and go to the "Gameplay" tab. Turn on agitation-rebalance. If your difficulty settings are at any of the vanilla presets, that's all you have to do. If you have customized the difficulty settings, say to disable cavern invaders, run this command in gui/launcher:

agitation-rebalance preset lenient

If you want a tougher experience, you can instead run:

agitation-rebalance preset strict

If you want the visible monitor that shows your current chances of being attacked by nature, run:

agitation-rebalance enable monitor
[h3]fix/stuck-worship[/h3]


You may have noticed that some dwarves can never satisfy their need to worship. They get stuck praying to the same god over and over, but they never seem to get enough. Their job is listed as a purple "Worship!", which means that the need is so strong that they are unable to do anything else. The issue is that despite having needs to pray to several different gods, the dwarf only prays to one, even if they have already satisfied their need for that particular god. This fix ensures that each god gets their fair share of prayer time.

The fix is on by default -- it will start up as soon as you install this beta and load a fort -- but we'd like some verification that it works well in a wide variety of fort setups. If you have dwarves that are already stuck in a Worship! loop and have a backlog of gods they need to pray to, it may still take them a few days to pray themselves out of that hole. However, after a month or so, does your fort seem more productive than it was before? When your dwarves worship, is is now a friendly green instead of a dire purple?
[h3]work details import/export[/h3]


If you go to the Work Details screen (under "Labor"), you'll now see buttons for exporting, importing, and auto-importing your work details for new forts. Try it out! does it make setting up new forts easier?
[h3]autoretrain livestock[/h3]


This one is for those who like to domesticate wild animals. A newborn animal inherits the training level of its parents. If the parents were not yet fully domesticated, the newborn won't be either. If you don't notice that the animal was born and that it doesn't have a trainer assigned, the partial training will decay over time, and eventually the animal will revert to wild, possibly attacking your dwarves or other livestock.

The autoretrainer watches for newborn partially-trained livestock and assigns a trainer. That's it.

You can enable it from the Pets/Livestock screen (under "Creatures")
[h3]labor and skill restrictions for workshops[/h3]


This is a new overlay for workshop and furnace buildings where you can configure the workshop to only accept general work orders that pertain to specific labors (the list of allowed labors is different for every workshop).

For example, by default, all weapon, armor, and blacksmithing general manager orders get sent to all forges. With labor restrictions, you can designate specific forges to handle just weapons, just armor, or just metalsmithing. Then, you can assign appropriate legendary masters to each forge, and they will only receive orders for appropriate products.

Or, instead of assigning a workshop master, you can restrict the skill level to Master and above and leave the workshop at "This workshop is free for anybody to use.". This will allow any citizen that is at least a master of armorsmithing to use the workshop to complete the jobs there.

With labor and skill restrictions, you can simplify your work orders, leaving them generalized and not tied to specific shops. The restrictions will self-organize the orders so they get completed at the right places with the right pool of people, even if one or two masters meet an untimely demise.

Veteran players may remember this as a vanilla feature in pre-v50 Dwarf Fortress. This is actually still the case. The DFHack overlay simply provides a UI for the vanilla feature hiding beneath the surface, just like the civilian alert. There was a previous announcement and discussion of this feature here.
[h2]New Linux Steam launch behavior[/h2]

This one's just for the Linux folks. It's important that DF playtime metrics get to DF, so we updated our launcher on Linux to ensure that both DFHack and DF get marked as "running" when you're playing the game from the Steam client. If you're on Linux, could you try:

• Launching DFHack from the Steam client
• Launching DF from the Steam client

In both cases, Steam should show that both DF and DFHack are "running". Could you report back whether this is the case for you on your system?
[h2]Announcements[/h2][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 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.
[h2]New Tools[/h2]

• agitation-rebalance: alter mechanics of irriation-related attacks so they are less constant and are more responsive to recent player bahavior
• fix/stuck-worship: fix prayer so units don't get stuck in uninterruptible "Worship!" states
• instruments: provides information on how to craft the instruments used by the player civilization.
• modtools/item-trigger: (reinstated) modder's resource for triggering scripted content when specific items are used

[h2]New Features[/h2]

• exterminate: new "disintegrate" kill method that additionally destroys carried items
• gui/settings-manager: add import, export, and autoload for work details
• logistics: autoretrain will automatically assign trainers to your partially-trained (but not yet domesticated) livestock. this prevents children of partially-trained parents from reverting to wild if you don't notice they were born
• orders: add overlay for configuring labor and skill level restrictions for workshops
• quickfort: allow setting of workshop profile properties (e.g. labor, skill restrictions) from build blueprints
• sort: updated and reinstated military status/squad membership/burrow membership filter for work animal assignment screen
• stocks: add button/hotkey for removing empty categories from the stocks list

[h2]Fixes[/h2]

• autochop: fix underestimation of log yield for cavern mushrooms
• catsplosion: only cause pregnancies in adults
• control-panel: fix filtering not filtering when running the list command
• gui/launcher:
  • fix detection on Shift-Enter for running commands and autoclosing the launcher
  • fix history scanning (Up/Down arrow keys) being slow to respond when in minimal mode
• gui/notify:
  • prevent notification overlay from showing up in arena mode
  • don't zoom to forbidden depots for merchants ready to trade notification
• logistics:
  • don't melt/trade/dump empty containers that happen to be sitting on the stockpile unless the stockpile accepts those item types
  • don't send autotrade items to forbidden depots

[h2]Misc Improvements[/h2]

• Dreamfort: the four Craftsdwarf's workshops on the industry level are now specialized for Stonecrafting, Woodcrafting, Bone Carving, and miscellaneous tasks, respectively
• When launched from the Steam client on Linux, both Dwarf Fortress and DFHack will be shown as "Running". This ensures that DF has proper accounting for Linux player usage.
• autobutcher: prefer butchering partially trained animals and save fully domesticated animals to assist in wildlife domestication programs
• autodump: can now teleport items loosely stored in buildings (clutter)
• clean: protect farm plots when cleaning mud
• control-panel: enable tweaks quietly on fort load so we don't spam the console
• devel/tile-browser: simplify interface now that SDL automatically normalizes texture scale
• exterminate: make race name matching case and space insensitive
• gui/gm-editor: support opening engraved art for inspection
• gui/launcher:
  • add interface for browsing and filtering commands by tags
  • add support for history search (Alt-s hotkey) when in minimal mode
  • add support for the clear command and clearing the scrollback buffer
• gui/teleport: add global Ctrl-Shift-T keybinding (only avaiable when DFHack mortal mode is disabled)
• suspendmanager: improve performance when there are many active jobs
• tweak: add quiet option for silent enablement and disablement of tweaks

[h2]API[/h2]

• Units :: isForgottenBeast: property check for forgotten beasts
• Units :: isGreatDanger: now includes forgotten beasts

[h2]Lua[/h2]

• helpdb: search_entries now returns a match if all filters in the include list are matched. previous behavior was to match if any include filter matched.
• dfhack.units.isForgottenBeast: make new units method available to Lua
• matinfo.decode: now directly handles plant objects
• widgets.Label:
• pen attributes can now either be a pen or a function that dynamically returns a pen

[h2]Structures[/h2]

• plant_tree_info: define tree body and branch flags
• plotinfo.hauling: name fields related to the hauling route panel

[h2]Documentation[/h2]

• introduction: refresh getting started content
• overlay-dev-guide: updated examples and troubleshooting steps
• quickstart: refresh quickstart guide

This 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!
[h2]Announcements[/h2][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 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.
[h2]Fixes[/h2]

• gui/design: no longer comes up when Ctrl-D is pressed but other DFHack windows have focus
• gui/notify: persist notification settings when toggled in the UI

[h2]Misc Improvements[/h2]

• gui/launcher: developer mode hotkey restored to Ctrl-D
• sort: squad assignment overlay rewritten for compatiblity with new vanilla data structures and screen layouts

[h2]Removed[/h2]

• burrow: removed overlay 3D box select since it is now provided by the vanilla UI
• sort: removed Search widgets for screens that now have vanilla search

[h2]API[/h2]

• Gui :: getWidget: retrieve a vanilla DF widget by name or index

[h2]Lua[/h2]

• dfhack.gui.getWidgetChildren: retrieve a list of child widgets for a given widget container
• dfhack.gui.getWidget: retrieve a vanilla DF widget by hierarchy path, with each step specified by a widget name or index

>

This 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!
[h2]Highlights[/h2][h3]Extended notification and quick-zoom panel[/h3]


There are some things that the game doesn't notify you about, despite being very useful to know. The DFHack notification panel fills in those gaps. A small panel will now appear in the lower left corner when you're on the main map and specific conditions are met:

• When agitated creatures enter the map. Clicking on the notification will zoom you to the first one. You can zoom to each agitated creature in turn by repeatedly clicking on the notification (or hitting the Enter key).
• When invaders (or other hostiles) enter the map. You can zoom to each individual hostile just like you can for agitated creatures.
• When a production mandate is nearing its deadline and someone will soon be punished for violating the mandate. Clicking on the notification will open the nobles screen so you can see what you're supposed to be producing. It will be the icon in angry red.
• When a dwarf is in a strange mood. The notification will tell you what stage of the mood they are in (finding workshop, gathering materials, working on artifact) and will tell you if they can't find what they are looking for or are otherwise stuck.
• When you have agreed to build a guildhall or temple, but have not yet done so. Clicking on the notification will give you details about what it was that you agreed to build.
• When a merchant finishes unloading goods and is ready to trade. Clicking on the notification will zoom you to the trade depot.
• When a unit is starving or stranded. Clicking on the notification will zoom you to the unit(s).
• When a "curious" creature enters the map that will seek to steal your stuff.

If there are notifications you'd rather not see, click on the gear icon on the notification window and turn those notifications off. Don't worry if you don't see the notification window at all -- if there aren't any notifications to show, the notification window won't be visible. You can still get to the configuration interface by running gui/notify directly.


[h3]Tweak's bugfixes[/h3]


The tweak tool has been reinstated, along with its library of small tweaks that improve the UI or fix bugs from the DF bug tracker. These tweaks are on by default, but can be disabled (if you so wish) on the "Bug Fixes" tab of gui/control-panel.

It includes the following tweaks/fixes:

• adamantine-cloth-wear: Prevents adamantine clothing from wearing out while being worn (Bug 6481).
• craft-age-wear: Fixes crafted items not wearing out over time (Bug 6003). With this tweak, items made from cloth and leather will gain a level of wear every 20 in-game years.
• eggs-fertile: Displays an indicator on fertile eggs.
• fast-heat: Improves temperature update performance by ensuring that 1 degree of item temperature is crossed in no more than 100 ticks when updating from the environment temperature. This reduces the time it takes for temperature to reach equilibrium and improves FPS when there are many items.
• flask-contents: Names filled waterskins, flasks, and vials according to their contents, the same way other containers such as barrels, bins, and cages are named. (Bug 4914)
• partial-items: Displays percentages on partially-consumed items such as hospital cloth.
• reaction-gloves: Fixes reactions to produce gloves in sets with correct handedness (Bug 6273).

[h3]Animal assignment UI improvements[/h3]


The DFHack animal assignment screen now displays the distance the creature is from the selected pasture/pit/cage/restraint. You can now also sort by distance.

There is now also an indicator for how many creatures you have assigned to the pasture/pit/cage/restraint.
[h3]Toggle animal designations from the animal info sheet[/h3]


When viewing the info sheet for an animal, you'll now get a small panel that allows you to mark (or unmark) the animal for butchering, gelding, or adoption. If the animal is not already domesticated, you'll also get a toggle for whether a trainer is assigned.


[h2]Announcements[/h2][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 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.
[h2]New Tools[/h2]

• add-thought: (reinstated) add custom thoughts to a dwarf
• combat-harden: (reinstated) set a dwarf's resistence to being affected by visible corpses
• devel/input-monitor: interactive UI for debugging input issues
• gui/notify: display important notifications that vanilla doesn't support yet and provide quick zoom links to notification targets.
• gui/petitions: (reinstated) show outstanding (or all historical) petition agreements for guildhalls and temples
• list-waves: (reinstated) show migration wave information
• make-legendary: (reinstated) make a dwarf legendary in specified skills
• pet-uncapper: (reinstated, renamed from petcapRemover) allow pets to breed beyond the default population cap of 50
• tweak: (reinstated) a collection of small bugfixes and gameplay tweaks
• undump-buildings: (reinstated) remove dump designation from in-use building materials

[h2]New Features[/h2]

• cleanowned: Add a "nodump" option to allow for confiscating items without dumping
• tweak: Add "flask-contents", makes flasks/vials/waterskins be named according to their contents

[h2]Fixes[/h2]

• autoclothing: Fix enabled behavior
• caravan: display book and scroll titles in the goods and trade dialogs instead of generic scroll descriptions
• dig-now: fix digging stairs in the surface sometimes creating underworld gates.
• dig: overlay that shows damp designations in ASCII mode now propertly highlights tiles that are damp because of an aquifer in the layer above
• fix/retrieve-units: prevent pulling in duplicate units from offscreen
• gui/blueprint: changed hotkey for setting blueprint origin tile so it doesn't conflict with default map movement keys
• gui/control-panel: fix error when toggling autostart settings
• gui/design: clicking the center point when there is a design mark behind it will no longer simultaneously enter both mark dragging and center dragging modes. Now you can click once to move the shape, and click twice to move only the mark behind the center point.
• gui/launcher: developer mode hotkey changed from Ctrl-D to Alt-D so as not to conflict with the hotkey for gui/design
• item: avoid error when scanning items that have no quality rating (like bars and other construction materials)
• source: fix issue where removing sources would make some other sources inactive
• strangemood: correctly recognize Stonecutter and Stone Carver as moodable skills, move the Mason's boosted mood chance to the Stone Carver, and select Fell/Macabre based on long-term stress
• warn-stranded:
  • don't complain about units that aren't on the map (e.g. soldiers out on raids)
  • when there was at least one truly stuck unit and miners were actively mining, the miners were also confusingly shown in the stuck units list
• gui.View: getMouseFramePos: function now detects the correct coordinates even when the widget is nested within other frames
• Gui:: makeAnnouncement, Gui:: autoDFAnnouncement: don't display popup for all announcement types
• Gui:: revealInDwarfmodeMap: properly center the zoom even when the target tile is near the edge of the map
• Units:: getVisibleName: don't reveal the true identities of units that are impersonating other historical figures

[h2]Misc Improvements[/h2]

• autonestbox: assign egg layers to the nestbox they have chosen if they have already chosen a nestbox
• buildingplan: use closest matching item rather than newest matching item
• caravan: move goods to trade depot dialog now allocates more space for the display of the value of very expensive items
• exportlegends: make progress increase smoothly over the entire export and increase precision of progress percentage
• extinguish: allow selecting units/items/buildings in the UI to target them for extinguishing; keyboard cursor is only required for extinguishing map tiles that cannot be selected any other way
• gui/autobutcher: ask for confirmation before zeroing out targets for all races
• gui/mod-manager: will automatically unmark the default mod profile from being the default if it fails to load (due to missing or incompatible mods)
• gui/quickfort:
  • can now dynamically adjust the dig priority of tiles designated by dig blueprints
  • can now opt to apply dig blueprints in marker mode
• item:
  • change syntax so descriptions can be searched for without indicating the --description option. e.g. it's now item count royal instead of item count --description royal
  • add --verbose option to print each item as it is matched
• probe: act on the selected building/unit instead of requiring placement of the keyboard cursor for bprobe and cprobe
• regrass: also regrow depleted cavern moss
• zone:
  • animal assignment dialog now shows distance to pasture/cage and allows sorting by distance
  • animal assignment dialog shows number of creatures assigned to this pasture/cage/etc.

[h2]Removed[/h2]

• gui/create-tree: replaced by gui/sandbox
• gui/manager-quantity: the vanilla UI can now modify manager order quantities after creation
• warn-starving: combined into gui/notify
• warn-stealers: combined into gui/notify

[h2]API[/h2]

• Gui focus strings will now include dwarfmode/Default if the only other panel open is the Squads panel
• Gui module Announcement functions now use DF's new announcement alert system
• Gui:: addCombatReport, Gui:: addCombatReportAuto: add versions that take report
• instead of report vector index
• Gui:: MTB_clean, Gui:: MTB_parse, Gui:: MTB_set_width: new functions for manipulating markup_text_boxst
• Gui:: revealInDwarfmodeMap: unfollow any currently followed units/items so the viewport doesn't just jump back to where it was
• toupper_cp437(char), tolower_cp437(char): new MiscUtils functions, return a char with case changed, respecting CP437
• toUpper, toLower: MiscUtils functions renamed to toUpper_cp437 and toLower_cp437, CP437 compliant

[h2]Lua[/h2]

• Overlay framework now respects active and visible widget attributes
• dfhack.gui announcement functions use default arguments when omitted
• dfhack.units.getCitizens now only returns units that are on the map
• dfhack.upperCp437(string), dfhack.lowerCp437(string): new functions, return string with all chars changed, respecting CP437 code page

[h2]Structures[/h2]

• buildings_other: add correct types for civzone building vectors
• job_skill: correct moodable property for several professions

This 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!
[h2]Highlights[/h2]
The end-of-year holidays have brought a surge of DFHack development! There are many new features and tools to play with. In order to keep these highlights to a reasonable length, we can't even go through them all in detail -- see the Changelog section for a full list.
[h3]Be master of your domain with gui/embark-anywhere[/h3]


By popular request, you can now ask Armok to allow you to 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).

The DFHack logo isn't shown on the embark screen (since it would cover the vanilla embark size adjustment widgets), but DFHack hotkeys still work, so you can still bring up the logo menu with Ctrl-Shift-C. There is also a convenience hotkey for running gui/embark-anywhere directly: Ctrl-A, which is only active when on the site choosing screen.

Note that this command (and its hotkey) will not be shown for those who have DFHack's "Mortal Mode" enabled in the gui/control-panel Preferences tab.


[h3]Bulk item management[/h3]


The new item commandline tool allows you to filter items in you fort by various properties (item type, material, wear-level, quality, etc.), 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.




[h3]Squad equipment assignment fixing tool[/h3]


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 issues, like:

• squad members assigned to labors that cause issues with military uniforms: mining, hunting, and tree chopping
• a single piece of equipment assigned to multiple squad members
• citizens retaining squad membership (and equipment configuration) from previous 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. It will remove assignments for conflicting gear or will force your dwarves to drop what they have so they can pick it up in the correct order. Remember to click "Update equipment" after running the fixer so that new equipment gets assigned to units that need it.

It may take a few tries (give your dwarves some time to go get their new gear before you try again), but your forever-yellow equipment icons should finally turn green!


[h3]Visualize biome boundaries with gui/biomes[/h3]


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 savagery rating.


[h3]Bulk building management with gui/mass-remove[/h3]


gui/mass-remove has been around for a while, but has received a significant overhaul. You can box select a region and schedule all buildings, constructions, stockpiles, and/or zones for removal. Planned and fully built buildings/constructions can be selected independently. No need to rage quit if you accidentally plan a solid block of 400 walls instead of flooring! Clear it all away in a few clicks!

It can easily cancel removal of buildings or constructions that you have marked for removal as well.

Bring it up when on the main map with the Ctrl-M hotkey.


[h3]Auto-restore difficulty settings and standing orders for new embarks[/h3]


Do you find yourself having to remember to go turn corpse hauling off for your dear, bearded, impressionable 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!

Both difficulty settings (in the pre-embark setup screen or the Settings screen when a fort is loaded) and standing orders (Labor -> Standing orders) can be saved and restored independently. When on those configuration screens, look for a DFHack overlay toggle where you can enable auto-restore for new embarks.


[h2]Announcements[/h2][h3]DFHack control panel changes[/h3]


The DFHack gui/control-panel interface 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 will be seamlessly migrated to the new format. Other than the layout changes, which should make the tools you want easier to find, the primary 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 and what they do. For example, each overlay now has a short description.
[h3]Plugin ABI version bump[/h3]
If you are developing an external plugin for DFHack, be aware that the plugin binary interface (ABI) has changed in this version 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. Any external plugins that target DF 50.11 will need to be recompiled against DFHack 50.11-r5 sources.
[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 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.
[h2]New Tools[/h2]

• control-panel: new commandline interface for control panel functions
• gui/biomes: visualize and inspect biome regions on the map
• gui/embark-anywhere:
  • new keybinding (active when choosing an embark site): Ctrl-A
  • bypass those pesky warnings and embark anywhere you want to
• 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
• item: 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

[h2]New Features[/h2]

• gui/mass-remove: new global keybinding: Ctrl-M while on the fort map
• gui/settings-manager: save and load embark difficulty settings and standing orders; options for auto-load on new embark
• 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 (attempt to) fix
• zone: add button to location details page for retiring unused locations

[h2]Fixes[/h2]

• 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 error
• buildingplan:
  • 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
  • treat items in wheelbarrows as unavailable, just as vanilla DF does. Make sure the fix/empty-wheelbarrows fix is enabled so those items aren't permanently unavailable!
  • show correct number of materials required when laying down areas of constructions and some of those constructions are on invalid tiles
• caravan: ensure items are marked for trade when the move trade goods dialog is closed even when they were selected and then the list filters were changed such that the items were no longer actively shown
• 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) location
• fastdwarf:
  • 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
• getplants: fix crash when processing mod-added plants with invalid materials
• gui/design:
  • fix incorrect highlight when box selecting area in ASCII mode
  • fix incorrect dimensions being shown when you're placing a stockpile, but a start coordinate hasn't been selected yet
• 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 and sinks now persist with fort across saves and loads
• stonesense: fix crash in cleanup code after mega screenshot (Ctrl-F5) completes; however, the mega screenshot will still make stonesense unresponsive. close and open the stonesense window to continue using it.
• suspendmanager: correctly handle building collisions with smoothing designations when the building is on the edge of the map
• warn-stranded: don't warn for citizens who are only transiently stranded, like those on stepladders gathering plants or digging themselves out of a hole
• Maps::getBiomeType, Maps::getBiomeTypeWithRef: fix identification of tropical oceans

[h2]Misc Improvements[/h2]

• 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 commandline
• autoclothing : now does not consider worn (x) clothing as usable/available; reduces overproduction when using tailor at same time
• buildingplan: add option for preventing constructions from being planned on top of existing constructions (e.g. don't build floors on top of floors)
• 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
• fix/stuck-instruments: now handles instruments that are left in the "in job" state but that don't have any actual jobs associated with them
• 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
  • 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 operations
• orders: reduce prepared meal target and raise booze target in basic importable orders in the orders library
• 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)
• warn-stranded: center the screen on the unit when you select one in the list
• 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
  • show geld status and custom profession (if set, it's the lower editable line in creature description) in pasture/pit/cage/restraint assignment screen

[h2]Removed[/h2]

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

[h2]API[/h2]

• 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
• Constructions::designateRemove: no longer designates the non-removable "pseudo" construtions that represent the top of walls
• 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
• Units.isDanger: now returns true for agitated wildlife
• 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

[h2]Lua[/h2]

• 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

[h2]Structures[/h2]

• 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
• feature_init_flags: more enum values defined
• 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
• viewscreen_choose_start_sitest: fix structure of warning flags -- convert series of bools to a proper bitmask
• world_raws: unk_v50_1, unk_v50_2, unk_v50_3 renamed to text_set, music, sound

[h2]Documentation[/h2]

• DFHack developer's guide updated, with refreshed architectural-diagrams
• 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