DFHack - Dwarf Fortress Modding Engine News

This release is compatible with all distributions of Dwarf Fortress: Steam, Itch, and Classic.

If you are running the DF Steam-only adventure beta, please download by subscribing to DFHack's adventure-beta branch on Steam.

• 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]Unstick stuck wildlife[/h3]
Have you noticed that wildlife sometimes gets stuck on the map? This happens most frequently with birds who just seem to freeze in mid-air, but you will also find the occasional giant elephant stuck in a tree (take that, physics!). Stuck wildlife causes issues because they prevent any new wildlife from entering the map, reducing the player's opportunity for FUN.

When the wildlife system is working properly, a small group of creatures enters the map, wanders around for a while (or aggressively attacks you if it is an agitated group), and then leaves the map. Once all members of the group have left, have been killed, or have been caught in cages, then a new wave (potentially of a different species/agitation level) can enter the map.

You can run the fix/wildlife script without parameters to immediately remove currently stuck wildlife, or you can enable it in gui/control-panel on the Bug Fixes tab to monitor and manage wildlife in the background. When enabled from the control panel, it will monitor for stuck wildlife and remove wildlife that has been stuck for 7 days.



Unlike most bugfixes, this one is not enabled by default since some players like to keep wildlife around for creative purposes (e.g. for intentionally stalling wildlife waves or for controlled startling of friendly necromancers). These players can selectively ignore the wildlife they want to keep captive before they enable fix/wildlife.



In related news, the force command has gained the ability to spawn new waves of wildlife: force Wildlife will allow a new wave of wildlife to enter the map regardless of how much wildlife is already wandering around.

Have fun : )
[h3]Improved lifestyles for immortals[/h3]
There's no question about it: being immortal is tough! Fort citizens who are immortal (like necromancers or vampires) have no bodily reason to eat or drink. However, they still have personality needs that can only be satisfied by eating or drinking! Despite not needing the nourishment, they can become distracted and unhappy when they go too long without a good meal.

If you enable immortal-cravings in the DFHack control panel, your distracted immortals will be allowed to satisfy their needs for food and drink like any other citizen. This will help reduce their stress (and solve what many players consider to be a bug), but beware that it will make vampires harder to detect -- they'll no longer have a telltale unmet need for food displayed on their info sheet!


[h3]The sky is no longer the limit[/h3]
Do you dream of castles in the clouds? Enable infinite-sky in the DFHack control panel and go build one!



When enabled, infinite-sky will automatically create new z-levels of sky as you build taller and taller constructions.


[h3]Realistic returns from melting items[/h3]
DF has an odd quirk (just one?) when calculating how many bars of metal you get when melting an item. Depending on the item type, you sometimes get more bars from melting than you used for manufacturing the item in the first place! If this bothers you, you can enable realistic-melting in the Gameplay tab of the DFHack control panel. It normalizes melting returns to about 95% of forging cost per item, with efficiency reductions if the item is damaged.


[h3]Text navigation keys[/h3]
Thanks to the new custom keybindings added in DF 50.14, DFHack text boxes can now support more advanced cursor navigation keys:

• Delete the character at the cursor with the Delete key
• Move the cursor by one word left or right with Ctrl+Left and Ctrl+Right
• Move the cursor to the beginning or end of the line with Home and End

If any of these hotkeys do not work well for you on your system, you can remap them in the vanilla DF Keybindings config screen. For example, Mac users may want to remap Custom: Ctrl + Left to Meta+Left to avoid conflicts with workspace switching hotkeys.


[h3]Dreamfort tutorial video series[/h3]
The popular Dreamfort quickfort blueprint set now has a video walkthrough! After a showcase of the finished fort, I guide you through each step of fort creation, demonstrating and discussing the design choices of Dreamfort along the way.



Start your journey here: https://youtu.be/N3YpK00Z2VE or browse the entire playlist: https://www.youtube.com/playlist?list=PLzXx9JcB9oXxmrtkO1y8ZXzBCFEZrKxve



Of course, the written walkthrough is available in-game and online as well if you would rather read: https://docs.google.com/spreadsheets/d/15TDBebP8rBNvsFbezb9xuKPmGWNzv7j4XZWq1AsfCio/edit?gid=0#gid=0
[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.

Some 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 listed as "unavailable" in the docs do not compile yet and are not accessible 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/wildlife: prevent wildlife from getting stuck when trying to exit the map. This fix needs to be enabled manually in gui/control-panel on the Bug Fixes tab since not all players want this bug to be fixed (you can intentionally stall wildlife incursions by trapping wildlife in an enclosed area so they are not caged but still cannot escape).
• forceequip: (reinstated) forcibly move items into a unit's inventory
• immortal-cravings: allow immortals to satisfy their cravings for food and drink
• infinite-sky: (reinstated, renamed from infiniteSky) automatically create new z-levels of sky to build in
• justice: pardon a criminal's prison sentence

[h2]New Features[/h2]

• force: add support for a Wildlife event to allow additional wildlife to enter the map
• tweak: realistic-melting: change melting return for inorganic armor parts, shields, weapons, trap components and tools to stop smelters from creating metal, bring melt return for adamantine in line with other metals to ~95% of forging cost. wear reduces melt return by 10% per level

[h2]Fixes[/h2]

• Fix mouse clicks bleeding through resizable DFHack windows when clicking in the space between the frame and the window content
• autobutcher: don't run a scanning and marking cycle on the first tick of a fortress to allow for all custom configuration to be set first
• control-panel: fix error when setting numeric preferences from the commandline
• emigration: save-and-reload no longer resets the emigration cycle timeout
• exportlegends: ensure historical figure race filter is usable after re-entering legends mode with a different loaded world
• fix/loyaltycascade: allow the fix to work on non-dwarven citizens
• geld, ungeld: save-and-reload no longer loses changes done by geld and ungeld for units who are historical figures
• gui/notify: don't classify (peacefully) visiting night creatures as hostile
• gui/quickfort:
  • only print a help blueprint's text once even if the repeat setting is enabled
  • fix build mode evaluation rules to allow placement of furniture and constructions on tiles with stair shapes or without orthagonal floors
• logistics: don't ignore rotten items when applying stockpile logistics operations (e.g. autodump, autoclaim, etc.)
• makeown:
  • quell any active enemy or conflict relationships with converted creatures
  • halt any hostile jobs the unit may be engaged in, like kidnapping
• nestboxes: don't consider eggs to be infertile just because the mother has left the nest; eggs can still hatch in this situation
• rejuvenate: fix error when specifying --age parameter
• timestream:
  • adjust the incubation counter on fertile eggs so they hatch at the expected time
  • adjust the timeout on traps so they can be re-triggered at normal rates

[h2]Misc Improvements[/h2]

• DFHack now verifies that critical DF data structures have known sizes and refuses to start if there is a mismatch
• DFHack text edit fields now delete the character at the cursor when you hit the Delete key
• DFHack text edit fields now move the cursor by one word left or right with Ctrl-Left and Ctrl-Right
• DFHack text edit fields now move the cursor to the beginning or end of the line with Home and End
• Quickfort blueprint library:
  • aquifer_tap blueprint walkthough rewritten for clarity
  • aquifer_tap blueprint now designated at priority 3 and marks the stairway tile below the tap in "blueprint" mode to prevent drips while the drainage pipe is being prepared
• buildingplan: add value info to item selection dialog (effectively ungrouping items with different values) and add sorting by value
• fix/occupancy: additionally handle the case where tile building occupancy needs to be set instead of cleared
• fix/stuck-worship: reduced console output by default. Added --verbose and --quiet options.
• gui/design:
  • add dimensions tooltip to vanilla zone painting interface
  • new gui/design.rightclick overlay that allows you to cancel out of partially drawn box and minecart designations without canceling completely out of drawing mode
• gui/gm-editor: automatically resolve and display names for language_name fields
• gui/pathable: improve calculation and visualization of wagon path to depot
• idle-crafting: also support making shell crafts for workshops with linked input stockpiles
• necronomicon: new --world option to list all secret-containing items in the entire world
• orders: orders sort now moves orders that are tied to a specific workshop to the top of the list in the global manager orders screen
• preserve-rooms: automatically release room reservations for captured squad members. we were kidding ourselves with our optimistic kept reservations. they're unlikely to come back : ((
• timestream: improve FPS by a further 10%

[h2]Documentation[/h2]

• Dreamfort: add link to Dreamfort tutorial youtube series: https://www.youtube.com/playlist?list=PLzXx9JcB9oXxmrtkO1y8ZXzBCFEZrKxve
• The error message that comes up if there is a version mismatch between DF and DFHack now informs you which DF versions are supported by the installed version of DFHack

[h2]Removed[/h2]

• UI focus strings for squad panel flows combined into a single tree: dwarfmode/SquadEquipment -> dwarfmode/Squads/Equipment, dwarfmode/SquadSchedule -> dwarfmode/Squads/Schedule
• faststart: removed since the vanilla startup sequence is now sufficiently fast
• modtools/force: merged into force

[h2]API[/h2]

• DFHack :: Units: new function setPathGoal
• Units :: setAutomaticProfessions: bay12-provided entry point to assign labors based on work details

[h2]Lua[/h2]

• dfhack.units: new function setPathGoal
• widgets.TabBar: updated to allow for horizontal scrolling of tabs when there are too many to fit in the available space

[h2]Structures[/h2]

• added unitst_set_automatic_professions entry point export to list of known globals

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]

• autobutcher: fix regression in ordering of butcherable animals
• preserve-rooms: don't reserve a room for citizens that you expel from the fort

On Steam, this release is available on the DFHack default "None" channel (for DF 50.13), the adventure-beta channel (for DF 51.01-beta), and the 50.14testing channel (for DF 50.14-beta).

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]Idle crafting[/h3]
Dwarves will now have to option to go craft something when they have the need. The only thing you have to do is designate a Craftsdwarf's workshop as a place where dwarves can elect to go to do their crafting.

At the bottom of the "Workers" tab, you'll now see an option for "Allow idle dwarves to satisfy crafting needs". The option will only be toggleable if the workshop is not already assigned to a master. If you set this option to "yes", then you'll see crafting jobs start to appear as your idle dwarves figure it's time to go craft something. Feel free to trade those crafts away to the next caravan!

Although you can designate any Craftsdwarf's workshop as an idle crafting designation, this feature works best if you build a separate Craftsdwarf's workshop (or two) specifically for idle crafting. If you set the number of "General work orders allowed" to zero on the "Work orders" tab for the workshop then the workshop is kept free for dwarves to use in their down time.

If you have the "Permitted General Work Order Labors" customized for the workshop, the kinds of crafting jobs that dwarves will do there will respect the setting. Note that you must have at least one of Stonecrafting or Bone Carving enabled for the workshop to be used for idle crafting. You can also link the workshop to a stockpile to control which materials will be used for the crafts.


[h3]Room reservations[/h3]
This is actually two features in one: a bugfix and a quality of life tool. The bugfix part takes effect automatically when a unit leaves the map. The most common situation is a squad going out on a raid. You may have noticed that when a unit leaves the map, they lose ownership of all their rooms. If you have carefully assigned specific bedrooms to your squad members, you'll be annoyed to see the rooms snagged by some random dwarf while your squad is away. This is even more impactful if you have nobility or administrators in the squad: their room requirements will be suddenly unmet.

Now, when your units leave the map, their room will be reserved in their names for when they get back. The room's zone will be disabled, and you'll see a message when you click on the zone telling you who the room is reserved for. You have the option of cancelling the reservation and making the room available for general use, if you want to. The reservation is automatically canceled if the owner is killed while away on their raid.

The second part of this feature is the ability to reserve rooms for specific noble or administrative roles. You can make a fine office and pre-reserve it for when a baron is appointed. The office will be disabled until a baron appears, and when the role becomes filled, the room will be automatically assigned to the role holder. You can even prepare for the situation where you have many barons. If you reserve 10 fine offices for the baron role, one office will be assigned to each of your 10 barons as they appear.

This is also very useful for administrative roles like managers. If you switch managers frequently, it can be a hassle to reassign the office each time. When you reserve the room for the manager role, the room will be automatically reassigned when a new citizen is appointed to the role.


[h3]Ethics violation warning[/h3]
It is now much harder to accidentally offend the elves. To be clear, you can still offend them if you want to. It's just harder to do it unintentionally.

Elves will refuse to trade for any item that could have come from harming an animal or a tree. They'll then refuse any further trades and leave the map in a huff. It is not always easy to figure out which items will trigger their ire. If a stone craft has a wooden decoration, they'll notice. If you sell innocent sand in an animal leather bag, they'll notice. If your artifact warhammer menaces with spikes of yak bone, they'll definitely notice.

If you do select any of those items in the bartering menu (that is, when you are actually specifying which fort items to trade for which merchant items), you'll see an "Ethics warning" badge next to the Trade button. Clicking on this badge will list the offending items, and it will give you an option to deselect them. If you click the Trade button anyway, you'll get one final confirmation to make absolutely sure you know what you're doing.

Give it a try! Remember, happy elves bring friendly giant animals instead of hostile ones! : )

For elves, the check is for animal and tree ethics, but this feature also works on modded races that have any other combination of ethical requirements.


[h3]Matchmaking interface[/h3]
By popular request by matchmaking role players, we now have an interface for assigning (or reassigning) spouses and lovers: gui/family-affairs. You can also initiate pregnancies with the partners of your choice, regardless of existing relationships. Go forth and meddle!

You can open the tool with the pregnancy tab pre-selected by invoking it as gui/pregnancy.


[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]

• embark-anyone: allows you to embark as any civilization, including dead and non-dwarven civs
• gui/family-affairs: (reinstated) inspect or meddle with pregnancies, marriages, or lover relationships
• idle-crafting: allow dwarves to independently satisfy their need to craft objects
• notes: attach notes to locations on a fort map
• preserve-rooms: manage room assignments for off-map units and noble roles. reserves rooms owned by traveling units and reinstates their ownership when they return to the site. also allows you to assign rooms to noble/administrator roles, and the rooms will be automatically assigned whenever the holder of the role changes

[h2]New Features[/h2]

• caravan:
  • DFHack dialogs for trade screens (both Bring goods to depot and the Trade barter screen) can now filter by item origins (foreign vs. fort-made) and can filter bins by whether they have a mix of ethically acceptable and unacceptable items in them
  • If you have managed to select an item that is ethically unacceptable to the merchant, an "Ethics warning" badge will now appear next to the "Trade" button. Clicking on the badge will show you which items that you have selected are problematic. The dialog has a button that you can click to deselect the problematic items in the trade list.
• confirm: If you have ethically unacceptable items selected for trade, the "Are you sure you want to trade" confirmation will warn you about them
• exportlegends: option to filter by race on historical figures page
• quickfort: #zone blueprints now integrated with preserve-rooms so you can create a zone and automatically assign it to a noble or administrative role

[h2]Fixes[/h2]

• DFHack screens that allow keyboard cursor and camera movement while focused now also allow diagonal and Z-change keyboard cursor keys
• DFHack state for a site is now properly saved when retiring a fort
• prevent hang when buildings in zones are destroyed in the case where the buildings were not added to the zone in the same order that they were created (uncommon)
• System clipboard: when pasting single lines from the system clipboard, replace newlines with spaces so they don't show up as strange CP437 glyphs in-game
• buildingplan:
  • improved performance in forts with large numbers of items
  • fixed processing errors when using quick material filter slot '0'
• deep-embark:
  • fix error when embarking where there is no land to stand on (e.g. when embarking in the ocean with gui/embark-anywhere)
  • fix failure to transport units and items when embarking where there is no room to spawn the starting wagon
• empty-bin: --liquids option now correctly empties containers filled with LIQUID_MISC (like lye)
• exterminate: don't kill friendly undead (unless --include-friendly is passed) when specifying undead as the target
• gui/create-item, modtools/create-item: items of type "VERMIN", "PET", "REMANS", "FISH", "RAW FISH", and "EGG" no longer spawn creature item "nothing" and will now stack correctly
• gui/design: don't overcount "affected tiles" for Line & Freeform drawing tools
• gui/pathable:
  • fix hang when showing trade depot wagon access and a trade depot is submerged under water or magma
  • fix representation of wagon paths over stairs and through doors
• gui/settings-manager: work details overlay no longer disappears when you click on a unit in the unit list
• gui/teleport: fix issue when teleporting units that are not prone, resulting in later issues with phantom "cannot build here: unit blocking tile" messages
• regrass:
  • no longer add all compatible grass types when using --force without --new
  • --mud now converts muddy slade to grass, consistent with normal DF behavior
• rejuvenate:
  • don't set a lifespan limit for creatures that are immortal (e.g. elves, goblins)
  • properly disconnect babies from mothers when aging babies up to adults
• strangemood: manually-triggered Macabre moods will now correctly request up to 3 bones/remains for the primary component instead of only 1
• timestream: ensure child growth events (that is, a child's transition to adulthood) are not skipped; existing "overage" children will be automatically fixed within a year

[h2]Misc Improvements[/h2]

• Dreamfort:
  • integrate with preserve-rooms to assign relevant rooms to nobles/adimistrators
  • smooth tiles under statues and other large furniture that you can't easily smooth later
• assign-minecarts: reassign vehicles to routes where the vehicle has been destroyed (or has otherwise gone missing)
• buildingplan: only consider building materials that can be accessed by at least one citizen/resident
• exterminate:
  • show descriptive names for the listed races in addition to their IDs
  • show actual names for unique creatures such as forgotten beasts and titans
• fix/dry-buckets: prompt DF to recheck requests for aid (e.g. "bring water" jobs) when a bucket is unclogged and becomes available for use
• fix/ownership: now also checks and fixes room ownership links
• gui/control-panel: include option for turning off dumping of old clothes for tailor, for players who have magma pit dumps and want to save old clothes from being dumped into the magma
• gui/family-affairs: you can start this tool by the name gui/pregnancy to start directly on the "Pregnancies" tab
• gui/sitemap:
  • show whether a unit is friendly, hostile, or wild
  • show whether a unit is caged
• position:
  • report current historical era (e.g., "Age of Myth"), site/adventurer world coords, and mouse map tile coords
  • option to copy keyboard cursor position to the clipboard
• sort: can now search for stockpiles on the Places>Stockpile tab by name, number, or enabled item categories

[h2]Documentation[/h2]

• add documentation for dfhack.items.findType(string) and dfhack.items.findSubtype(string)
• gui/embark-anywhere: add information about how the game determines world tile pathability and instructions for bridging two landmasses
• modding-guide:
  • added examples for reading and writing various types of persistent storage
  • updated all code snippets for greater clarity

[h2]Removed[/h2]

• quickfortress.csv: remove old sample blueprints for "The Quick Fortress", which were unmaintained and non-functional in DF v50+. Online blueprints are available at https://docs.google.com/spreadsheets/d/1WuLYZBM6S2nt-XsPS30kpDnngpOQCuIdlw4zjrcITdY if anyone is interested in giving these blueprints some love

[h2]API[/h2]

• DFHack :: cuboid: cuboid :: clampMap now returns the cuboid itself (instead of boolean) to allow method chaining; call cuboid :: isValid to determine success
• Items :: createItem: removed growth_print parameter; now determined automatically
• Units: new isWildlife and isAgitated property checks

[h2]Lua[/h2]

• Overlay widgets can now assume their active and visible functions will only execute in a context that matches their viewscreens associations
• dfhack.items.createItem: removed growth_print parameter to match C++ API
• dfhack.units.isDanger: no longer unconditionally returns true for intelligent undead
• dfhack.units: isWildlife and isAgitated property checks
• gui.simulateInput: do not generate spurious keycode from _STRING key inputs

This beta release is available on the DFHack "beta" channel (for DF 50.13), the "adventure-beta" channel (for DF 51.01-beta), and the "50.14testing" channel (for DF 50.14-beta).

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]Idle crafting[/h3]
Dwarves will now have to option to go craft something when they have the need. The only thing you have to do is designate a Craftsdwarf's workshop as a place where dwarves can elect to go to do their crafting.

At the bottom of the "Workers" tab, you'll now see an option for "Allow idle dwarves to satisfy crafting needs". The option will only be toggleable if the workshop is not assigned to a master. If you set this option to "yes", then you'll see crafting jobs start to appear as your idle dwarves figure it's time to go craft something. Feel free to trade those crafts away to the next caravan.

This feature works best if you build a separate Craftsdwarf's workshop (or two) specifically for idle crafting, and you set the number of "General work orders allowed" to zero on the "Work orders" tab for the workshop. That way, the workshop is kept free for dwarves to use in their down time.

If you have the "Permitted General Work Order Labors" customized for the workshop, the kinds of crafting jobs that dwarves will do there will respect the setting. Note that you must have at least one of Stonecrafting or Bone Carving enabled for the workshop to be used for idle crafting.


[h3]Room reservations[/h3]
This is actually two things in one: a bugfix and a quality of life tool. The bugfix part takes effect automatically when a unit leaves the map. The most common situation is a squad going out on a raid. You may have noticed that when a unit leaves the map, they lose ownership of all their rooms. If you have carefully assigned specific bedrooms to your squad members, you'll be annoyed to see the rooms snagged by some random dwarf while your squad is away. This is even more impactful if you have nobility or administrators in the squad: their room requirements will be suddenly unmet.

Now, when your units leave the map, their room will be reserved in their name for when they get back. The room's zone will be disabled, and you'll see a message when you click on the zone telling you who the room is reserved for. You have the option of cancelling the reservation and making the room available for general use, if you want to.

The second part of this feature is the ability to reserve rooms for specific noble or administrative roles. You can make a fine office and pre-reserve it for when a baron is appointed. The office will be disabled until a baron appears, and when someone is appointed to that role, the room will be automatically assigned to them. You can even prepare for the situation where you have many barons. If you prepare and reserve 10 offices for the baron role, one office will be assigned to up to 10 barons when they appear.

This is also very useful for administrative roles like managers. If you switch managers frequently, it can be a hassle to reassign the office each time. When you reserve the room for the manager role, the room will be automatically reassigned when a new citizen is appointed to the role.


[h3]Ethics violation warning[/h3]
It is now much harder to accidentally offend the elves. To be clear, you can still offend them if you want to. It's just harder to do it unintentionally.

When you select items for trade in the bartering menu (when you are actually specifying which fort items to trade for which merchant items) and have an item selected that will cause the elves to declare you a heathen, you'll see an "Ethics warning" badge next to the Trade button. Clicking on this badge will list the offending items, and it will give you an option to deselect them. If you click the Trade button anyway, you'll get one final confirmation to make absolutely sure you know what you're doing.

Give it a try! Remember, happy elves bring friendly giant animals instead of hostile ones! : )


[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]

• embark-anyone: allows you to embark as any civilization, including dead and non-dwarven civs
• gui/family-affairs: (reinstated) inspect or meddle with pregnancies, marriages, or lover relationships
• idle-crafting: allow dwarves to independently satisfy their need to craft objects
• notes: manage map-specific notes
• preserve-rooms: manage room assignments for off-map units and noble roles. reserves rooms owned by traveling units and reinstates their ownership when they return to the site. also allows you to assign rooms to noble/administrator roles, and the rooms will be automatically assigned whenever the holder of the role changes

[h2]New Features[/h2]

• caravan:
  • DFHack dialogs for trade screens (both Bring goods to depot and the Trade barter screen) can now filter by item origins (foreign vs. fort-made) and can filter bins by whether they have a mix of ethically acceptable and unacceptable items in them
  • If you have managed to select an item that is ethically unacceptable to the merchant, an "Ethics warning" badge will now appear next to the "Trade" button. Clicking on the badge will show you which items that you have selected are problematic. The dialog has a button that you can click to deselect the problematic items in the trade list.
• confirm: If you have ethically unacceptable items selected for trade, the "Are you sure you want to trade" confirmation will warn you about them
• exportlegends: option to filter by race on historical figures page
• quickfort: #zone blueprints now integrated with preserve-rooms so you can create a zone and automatically assign it to a noble or administrative role

[h2]Fixes[/h2]

• DFHack screens that allow keyboard cursor and camera movement while focused now also allow diagonal and Z-change keyboard cursor keys
• DFHack state for a site is now properly saved when retiring a fort
• prevent hang when buildings in zones are destroyed in the case where the buildings were not added to the zone in the same order that they were created (uncommon)
• System clipboard: when pasting single lines from the system clipboard, replace newlines with spaces so they don't show up as strange CP437 glyphs in-game
• buildingplan:
  • improved performance in forts with large numbers of items
  • fixed processing errors when using quick material filter slot '0'
• deep-embark:
  • fix error when embarking where there is no land to stand on (e.g. when embarking in the ocean with gui/embark-anywhere)
  • fix failure to transport units and items when embarking where there is no room to spawn the starting wagon
• empty-bin: --liquids option now correctly empties containers filled with LIQUID_MISC (like lye)
• exterminate: don't kill friendly undead (unless --include-friendly is passed) when specifying undead as the target
• gui/create-item, modtools/create-item: items of type "VERMIN", "PET", "REMANS", "FISH", "RAW FISH", and "EGG" no longer spawn creature item "nothing" and will now stack correctly
• gui/design: don't overcount "affected tiles" for Line & Freeform drawing tools
• gui/pathable:
  • fix hang when showing trade depot wagon access and a trade depot is submerged under water
  • fix representation of wagon paths over stairs and through doors
• gui/settings-manager: work details overlay no longer disappears when you click on a unit in the unit list
• gui/teleport: fix issue when teleporting units that are not prone, resulting in later issues with phantom "cannot build here: unit blocking tile" messages
• regrass:
  • no longer add all compatible grass types when using --force without --new
  • --mud now converts muddy slade to grass, consistent with normal DF behavior
• rejuvenate:
  • don't set a lifespan limit for creatures that are immortal (e.g. elves, goblins)
  • properly disconnect babies from mothers when aging babies up to adults
• strangemood: manually-triggered Macabre moods will now correctly request up to 3 bones/remains for the primary component instead of only 1
• timestream: ensure child growth events (that is, a child's transition to adulthood) are not skipped; existing "overage" children will be automatically fixed within a year

[h2]Misc Improvements[/h2]

• Dreamfort:
  • integrate with preserve-rooms to assign relevant rooms to nobles/adimistrators
  • smooth tiles under statues and other large furniture that you can't easily smooth later
• assign-minecarts: reassign vehicles to routes where the vehicle has been destroyed (or has otherwise gone missing)
• buildingplan: only consider building materials that can be accessed by at least one citizen/resident
• fix/dry-buckets: prompt DF to recheck requests for aid (e.g. "bring water" jobs) when a bucket is unclogged and becomes available for use
• gui/control-panel: include option for turning off dumping of old clothes for tailor, for players who have magma pit dumps and want to save old clothes from being dumped into the magma
• gui/family-affairs: you can start this tool by the name gui/pregnancy to start directly on the "Pregnancies" tab
• gui/sitemap:
  • show whether a unit is friendly, hostile, or wild
  • show whether a unit is caged
• position:
  • report current historical era (e.g., "Age of Myth"), site/adventurer world coords, and mouse map tile coords
  • option to copy keyboard cursor position to the clipboard
• sort: can now search for stockpiles on the Places>Stockpile tab by name, number, or enabled item categories

[h2]Documentation[/h2]

• add documentation for dfhack.items.findType(string) and dfhack.items.findSubtype(string)
• gui/embark-anywhere: add information about how the game determines world tile pathability and instructions for bridging two landmasses

[h2]Removed[/h2]

• quickfortress.csv: remove old sample blueprints for "The Quick Fortress", which were unmaintained and non-functional in DF v50+. Online blueprints are available at https://docs.google.com/spreadsheets/d/1WuLYZBM6S2nt-XsPS30kpDnngpOQCuIdlw4zjrcITdY if anyone is interested in giving these blueprints some love

[h2]API[/h2]

• DFHack :: cuboid: cuboid :: clampMap now returns the cuboid itself (instead of boolean) to allow method chaining; call cuboid :: isValid to determine success
• Items :: createItem: removed growth_print parameter; now determined automatically
• Units: new isWildlife and isAgitated property checks

[h2]Lua[/h2]

• Overlay widgets can now assume their active and visible functions will only execute in a context that matches their viewscreens associations
• dfhack.items.createItem: removed growth_print parameter to match C++ API
• dfhack.units.isDanger: no longer unconditionally returns true for intelligent undead
• dfhack.units: isWildlife and isAgitated property checks
• gui.simulateInput: do not generate spurious keycode from _STRING key inputs

If you are subscribed to the DF adventure beta (the DF "beta" branch), please subscribe to the DFHack "adventure-beta" branch for a compatible build.

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]Table of contents in gui/journal[/h3]
Community contributor psychowico has continued to deliver improvements to gui/journal. It now supports markdown syntax for section headers, and it will automatically build a hyperlinked table of contents as you add the headers.



To add a header, start a line with "# ", e.g. "# Fortress goals". You can add level 2 subheadings with "## ", and so on.

Due to the tool's popularity, there is now a global hotkey (in fort mode) for launching gui/journal: Ctrl-j
[h3]timestream bugfixes and improvements[/h3]
The FPS fixer timestream has been significantly refined for better behavior at the highest FPS improvement levels. For example, jobs were not being generated quickly enough for the accelerated calendar rate. Also, some non-skill-based jobs, like eating and drinking, were taking too long to complete. With the updates, dwarves will no longer be left jobless or get stuck in the booze stockpile with seemingly unquenchable thirst.
[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 Features[/h2]

• gui/journal:
  • new hotkey, accessible from anywhere in fort mode: Ctrl-j
  • new automatic table of contents. add lines that start with "# ", like "# Entry for 502-04-02", to add hyperlinked headers to the table of contents

[h2]Fixes[/h2]

• Copy/Paste: Fix handling of multi-line text when interacting with the system clipboard on Windows
• add-spatter: fix a crash related to unloading a savegame with add-spatter reactions, then loading a second savegame with add-spatter reactions
• autodump: cancel any jobs that point to dumped items
• build-now: fix error when building buildings that (in previous DF versions) required the architecture labor
• changelayer: fix incorrect lookup of geological region in multi-region embarks
• fix/dead-units: fix error when removing dead units from burrows and the unit with the greatest ID was dead
• full-heal: fix -r --all_citizens option combination not resurrecting citizens
• gui/autodump:
  • prevent dumping into walls or invalid map areas
  • properly turn items into projectiles when they are teleported into mid-air
• gui/settings-manager: fix position of "settings restored" message on embark when the player has no saved embark profiles
• gui/unit-info-viewer: correctly display skill levels when rust is involved
• list-waves: no longer gets confused by units that leave the map and then return (e.g. squads who go out on raids)
• locate-ore: fix sometimes selecting an incorrect tile when there are multiple mineral veins in a single map block
• makeown: ensure names given to adopted units (or units created with gui/sandbox) are respected later in legends mode
• open-legends: don't intercept text bound for vanilla legends mode search widgets
• plant: properly detect trees in a specified cuboid that only have branches/leaves in the cuboid area
• prioritize: fix incorrect restoring of saved settings on Windows
• timestream:
  • fix dwarves spending too long eating and drinking
  • fix jobs not being created at a sufficient rate, leading to dwarves standing around doing nothing
• zone: fix alignment of animal actions overlay panel (the one where you can click to geld/train/etc.) when the animal has a custom portrait (like named dragons)

[h2]Misc Improvements[/h2]

• performance improvements for DFHack tools and infrastructure
• allneeds: display distribution of needs by how severely they are affecting the dwarf
• autodump: allow dumping items into mid-air, converting them into projectiles like gui/autodump does
• build-now: if suspendmanager is running, run an unsuspend cycle immediately before scanning for buildings to build
• gui/pathable: give edge tiles where wagons can enter the map a special highlight to make them more identifiable. this is especially useful when the game decides that only a portion of the map edge is usable by wagons.
• list-waves:
  • now outputs the names of the dwarves in each migration wave
  • can now display information about specific migration waves (e.g. list-waves 0 to identify your starting 7 dwarves)

[h2]Documentation[/h2]

• improved docs for dfhack.units module functions

[h2]Removed[/h2]

• The PRELOAD_LIB environment variable has been renamed to DF_PRELOAD to match the naming scheme of other environment variables used by the dfhack startup script. If you are preloading libraries (e.g. for performance testing) please define DF_PRELOAD instead of PRELOAD_LIB or LD_PRELOAD
• cuboid :: clamp(bool block): renamed to cuboid :: clampMap(bool block), name taken by cuboid :: clamp(cuboid other)
• Units :: getPhysicalDescription: function requires DF call point that is no longer available. alternative is to navigate the unit info sheet and extract the description from the UI (see markdown)
• Units :: MAX_COLORS, Units :: findIndexById, Units :: getNumUnits, Units :: getUnit: replaced by DFHack :: COLOR_MAX and the generated type-specific get_vector functions

[h2]API[/h2]

• cuboid:
  • construct from df :: map_block*, forBlock iterator to access map blocks in cuboid
  • clamp(cuboid other), clampNew(cuboid other) for cuboid intersection. clampNew returns new cuboid instead of modifying.
• Items: no longer need to pass MapCache parameter to moveToGround, moveToContainer, moveToBuilding, moveToInventory, makeProjectile, or remove
• setAreaAquifer, removeAreaAquifer: add overloads that take cuboid range specifiers
• Units :: getCasteRaw: get a caste_raw from a unit or race and caste
• Units :: getProfessionName: bool land_title to append "of Sitename" where applicable, use Prisoner/Slave and noble spouse titles (controlled by ignore_noble)
• Units :: getProfession: account for units with fake identities
• Units :: getRaceChildName, getRaceChildNameById, getRaceBabyName, getRaceBabyNameById: bool plural to get plural form
• Units :: getReadableName: correct display of ghost+curse names w/r/t each other and unit prof, use curse.name instead of iterating syndrome name effects
• Units :: isDanger: added bool hiding_curse, passed to isUndead to avoid spoilers
• Units :: isNaked: now only checks equipped items (including rings, for now). Setting bool no_items to true checks empty inventory like before.
• Units :: isUndead: bool include_vamps renamed to hiding_curse. Fn now checks that instead of bloodsucker syndrome.
• Units :: isUnitInBox, getUnitsInBox: add versions that take a cuboid range, add filter fn parameter for getUnitsInBox
• Units :: isVisible: account for units in cages
• Units: add overloads that take historical figures for getReadableName, getVisibleName, and getProfessionName

[h2]Lua[/h2]

• dfhack.items.moveToInventory: make use_mode and body_part args optional
• dfhack.units:
  • allow historical figures to be passed instead of units for getReadableName, getVisibleName, and getProfessionName
  • add getRaceReadableName, getRaceReadableNameById, getRaceNamePluralById
• gui.ZScreen: new defocused property for starting screens without keyboard focus

[h2]Structures[/h2]

• world_site: rename is_mountain_halls and is_fortress to Bay12 names min_depth and max_depth