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!

Highlights

Taking the frustration out of irritation

agitation-rebalance alters the mechanics of irritation-related attacks, that is, agitated surface wildlife and cavern invaders, so they are less constant and are more responsive to ongoing player behavior. Many people find the constant vanilla irritation attacks to be overwhelming, or at least un-fun. This gameplay mod tempers the retaliation so once you get attacked, you won't get attacked again until you specifically provoke nature further. Instead of hitting a threshold and then getting a never-ending stream of attackers, chances of a subsequent attack smoothly ramp up over time in proportion to your tree-chopping, fishing, or noise-making activity in the relevant area. 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/stable/docs/tools/agitation-rebalance.html#how-the-df-agitation-system-works

How to use

Open up gui/control-panel and go to the "Gameplay" tab. Turn on agitation-rebalance. If your game difficulty settings for "Enemies" 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 because you found them annoying, run this command: agitation-rebalance preset lenient If you want a tougher experience, you can instead run: agitation-rebalance preset strict And if you want the visible monitor that shows the current threat level on the surface and in the caverns, run: agitation-rebalance enable monitor
Many thanks to rome of oxtrot for digging through the DF logic to identify the formulas used to calculate the chances of agitation and invasion. This mod would not have been possible without her dedicated research.

Fixing longstanding vanilla bugs

This release features solutions for no fewer than three longstanding vanilla bugs.

fix/stuck-worship

fix/stuck-worship fixes prayer so units don't get stuck in uninterruptible "Worship!" states. 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. Despite having needs to pray to several different gods, the dwarf only ever 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. 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, your fort should seem more productive and when your dwarves worship, it should be a friendly (interruptible) green instead of a dire (uninterruptible) purple.

fix/noexert-exhaustion

fix/noexert-exhaustion fixes an issue with assigning necromancers, vampires, and intelligent undead to military training. These kinds of units aren't supposed to ever get exhausted -- in game RAW language, they have the NOEXERT token. However, military training ignores that token and makes them tired anyway. Unfortunately, because of NOEXERT, these units also never recover from being tired, which gets them stuck in an exhausted state. With this fix running, they are properly kept free of exhaustion, even when training in the military.

fix/ownership

fix/ownership detects and fixes the case where multiple citizens claim the same item, preventing "Store owned item" job loops as each "owner" takes turns at stealing the item back from the other owner's room. All three are enabled by default, so you don't have to do anything special to benefit from them. You should just see your forts working a little bit smoother now.

Instrument component lookup

Instruments. How do they work? Well, nobody really knows (except maybe Tarn), but now at least you can follow a recipe to get their parts assembled. The new instruments command provides information on how to craft the instruments used by the player civilization. Each component is listed along with the required raw materials. Moreover, you can see which instruments are hand held and which need to be "built" as stationary buildings, in case you're looking for a specific type for your taverns and temples.

Automatically retrain partially trained livestock

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. 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"), or you can autostart it for new forts in gui/control-panel.

Skill level and labor type restrictions for workshops

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. For example, if you have general manager workorders set up to produce weapons and armor, you can configure one forge to only accept armoring jobs and a different forge to only accept Weaponsmithing jobs. General workorder jobs for armor will only be distributed to the one specialized in Armoring, and general workorder jobs for weapons will only be distributed to the one specialized in Weaponsmithing. Then you can assign a master armorer and a master weaponsmith to the respective forges to make more productive use of their abilities. As an alternative to assigning specific workshop masters, you can leave the workshop at "This workshop is free for anybody to use" and instead set limits for the worker's skill level. Then, only citizens that have a skill level within that range will come to do jobs at that workshop. For example, if you have many highly skilled armorers, you can set the labor restriction to Armoring and the skill limits to Master and above. Then, any of your available skilled armorers can come to complete jobs at that forge. When one armorer needs rest, falls in the well, or gets eaten by a forgotten beast, the others can immediately take up the slack without requiring micromanagement from the player.
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. The labor and skill restrictions can also be set from quickfort blueprints. The four Craftsdwarf's workshops on the Dreamfort industry level, for example, are now automatically specialized for Stonecrafting, Woodcrafting, Bone Carving, and miscellaneous tasks, respectively.

Announcements

New Linux Steam launch behavior

This one's just for the Linux folks. It's important that playtime metrics get to both DF and DFHack, 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, regardless of which "game" you selected to launch. This brings the Linux launcher in line with what we have for the Windows launcher and should ensure that both DF and DFHack have proper accounting for playtime for Linux players.

PSAs

As always, remember that, just like the vanilla DF game, DFHack tools can also have bugs. It is a good idea to save often and keep backups of the forts that you care about. Many DFHack tools that worked in previous (pre-Steam) versions of DF have not been updated yet and are marked with the "unavailable" tag in their docs. If you try to run them, they will show a warning and exit immediately. You can run the command again to override the warning (though of course the tools may not work). We make no guarantees of reliability for the tools that are marked as "unavailable". The in-game interface for running DFHack commands (gui/launcher) will not show "unavailable" tools by default. You can still run them if you know their names, or you can turn on dev mode by hitting Ctrl-D while in gui/launcher and they will be added to the autocomplete list. Some tools do not compile yet and are not available at all, even when in dev mode. If you see a tool complaining about the lack of a cursor, know that it's referring to the keyboard cursor (which used to be the only real option in Dwarf Fortress). You can enable the keyboard cursor by entering mining mode or selecting the dump/forbid tool and hitting Alt-K (the DFHack keybinding for toggle-kbd-cursor). We're working on making DFHack tools more mouse-aware and accessible so this step isn't necessary in the future.

Changelog

New Tools

• agitation-rebalance: alter mechanics of irriation-related attacks so they are less constant and are more responsive to recent player bahavior
• devel/block-borders: (reinstated) highlights boundaries of map blocks or embark tile blocks
• fix/noexert-exhaustion: fix "Tired" NOEXERT units. Enabling via gui/control-panel prevents NOEXERT units from getting stuck in a "Tired" state
• fix/ownership: fix instances of multiple citizens claiming the same items, resulting in "Store owned item" job loops
• 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/if-entity: (reinstated) modder's resource for triggering scripted content depending on the race of the loaded fort
• modtools/item-trigger: (reinstated) modder's resource for triggering scripted content when specific items are used

New Features

• 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

Fixes

• autochop: fix underestimation of log yield for cavern mushrooms
• autoclothing: don't produce clothes for dead units
• caravan: fix trade price calculations when the same item was requested for both import and export
• 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

Misc Improvements

• Dreamfort:
  • the four Craftsdwarf's workshops on the industry level are now specialized for Stonecrafting, Woodcrafting, Bone Carving, and miscellaneous tasks, respectively
  • update embark profile recommendations and example embark profile
• Many tools that previously only worked for citizens or only for dwarves now work for all citizens and residents, e.g. fastdwarf, rejuvenate, etc.
• 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.
• 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
• 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)
• buildingplan:
  • remember player preference for whether unavailable materials should be hidden in the filter selection dialog
  • sort by available quantity by default int he filter selection dialog
• 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
• 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
• 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/notify: Shift click or Shift Enter on a zoomable notification to zoom to previous target
• gui/teleport: add global Ctrl-Shift-T keybinding (only available when DFHack mortal mode is disabled)
• 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
• suspendmanager: improve performance when there are many active jobs
• tweak: add quiet option for silent enablement and disablement of tweaks

API

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

Lua

• 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.getCitizens: now includes residents by default
• 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

Structures

• activity_event: identify fields and type values
• plant_tree_info: define tree body and branch flags
• plotinfo.hauling: name fields related to the hauling route panel
• unit: identify and define many previously unknown fields, types, and enums

Documentation

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