DFHack - Dwarf Fortress Modding Engine News

DFHack 51.03-r1

This release is just a quick compatibility update for the latest stable DF release (51.03).

Changelog

[h2]Fixes[/h2]

gui/gm-editor: fix Enter key not being recognized for opening the selected object

DFHack 51.02-r1

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

Please report any issues (or feature requests) on the DFHack GitHub issue tracker. When reporting issues, please upload a zip file of your savegame and a zip file of your mods directory to the cloud and add links to the GitHub issue. Make sure your files are downloadable by "everyone with the link". We need your savegame to reproduce the problem and test the fix, and we need your active mods so we can load your savegame. Issues with savegames and mods attached get fixed first!
[h2]Announcements[/h2][h3]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.

Changelog

[h2]Fixes[/h2]

deathcause: fix error when retrieving the name of a historical figure

[h2]Misc Improvements[/h2]

DFHack edit field widgets, such as the commandline editor in gui/launcher, now support text selection and other advanced text editing features from gui/journal
stonesense:
- keybinds.txt config file is now read from dfhack-config/stonesense/keybinds.txt
- added some missing artwork for bookcases, displays, and offering places
- reorganized the position of some existing art to be more intuitive
- added index numbers empty sprite slots to aid in making the xml files for the sprites
- zoom levels in stonesense now mirror the main game when in follow mode

DFHack 50.15-r2

[h3]Q: How do I download DFHack?[/h3]
A: Either add to your Steam library from our Steam page or scroll to the latest release on our GitHub releases page, expand the "Assets" list, and download the file for your platform (e.g. dfhack-XX.XX-rX-Windows-64bit.zip. If you are on Windows and are manually installing from the zip file, please remember to right click on the file after downloading, open the file properties, and select the "Unblock" checkbox. This will prevent issues with Windows antivirus programs.

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

Here are some new things to try:

Hit semicolon (;) to toggle fog (huge performance boost)
Hit a to toggle announcements (which are now neatly tucked away in the lower right corner)

You can edit the startup configuration in the new dfhack-config/stonesense/init.txt file. For example, you can set the initial window size to 1920x1200 or increase the size of the font used to render text.

Give it a try if you haven't already! It can be breathtaking to see your fortress creations in full 3D!
[h3]Rescue missions for lost squads[/h3]
Occasionally, squads that you send out on a mission get stuck on the world map. They lose their ability to navigate and are unable to return to your fortress. This tool allows a messenger that is returning from a holding or any other of your squads that is returning from a mission to rescue the lost squad along the way and bring them home.

This fix is enabled by default in the DFHack control panel, so you don't need to do anything special to benefit from it. However, it is still up to you to send out a messenger or squad that can be tasked with the rescue. If you have a holding that is linked to your fort, you can send out a messenger – you don’t have to actually request any workers. Otherwise, you can send a squad out on a mission with minimal risk, like “Demand one-time tribute”.

This tool is also integrated with the DFHack notifcation panel, so you will get a notification when a squad is stuck and there are no squads or messengers currently out traveling that can rescue them.

Note that there might be other reasons why your squad appears missing – if it got wiped out in combat and nobody survived to report back, for example – but this tool should allow you to recover from the cases that are actual bugs.
[h3]Rename anything that can be named[/h3]
Sure, you can rename your fortress before you embark, but what about second rename?

Fire up gui/rename, and you can choose from a list of nameable entities in your environment to give a custom name to. This tool works with DFs in-world languages, so you get an interface similar to the one you use to give names to fortresses and governments on embark. It is a little more informative and flexible compared to the vanilla UI, though. For example, you can search for or sort by the English word or the translated language word. You can also change the language of a name, and you can give units new "real" first names.

You can click on something (e.g. a unit) and then run gui/rename to rename it, or you can choose any of the following from an in-tool selection dialog:

An artifact on the current map
A unit on the current map
A squad belonging to the current fortress
A location (e.g. tavern, hospital, guildhall, temple) on the current map
The current fortress (or adventurer site)
The government of the current fortress
The civilization of the current fortress
The world

If you run gui/rename while on the “prepare carefully” embark screen, you can choose new names for your starting dwarves.

Modders and power users can also pass game IDs on the commandline to rename other entities like foreign sites or religions.

gui/rename also comes with an overlay for convenience. When generating a new world, you'll get a button for renaming the world before you save it for the first time.

As a side bonus, this tool transparently fixes a DF bug on the embark screen where you are unable to give your starting dwarves nicknames. You'll be able to set nicknames normally now.

More info here: https://docs.dfhack.org/en/stable/docs/tools/gui/rename.html#gui-rename
[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.

Changelog

[h2]New Tools[/h2]

fix/stuck-squad: allow squads and messengers returning from missions to rescue squads that have gotten stuck on the world map
gui/rename: (reinstated) give new in-game language-based names to anything that can be named (units, governments, fortresses, the world, etc.)

[h2]New Features[/h2]

gui/notify: new notification type: save reminder; appears if you have gone more than 15 minutes without saving; click to autosave
gui/rename:
- add overlay to worldgen screen allowing you to rename the world before the new world is saved
- add overlay to the "Prepare carefully" embark screen that transparently fixes a DF bug where you can't give units nicknames or custom professions
gui/settings-manager:
- new overlay on the Labor -> Standing Orders tab for configuring the number of barrels to reserve for job use (so you can brew alcohol and not have all your barrels claimed by stockpiles for container storage)
- standing orders save/load now includes the reserved barrels setting
orders: add transparent overlays to the manager orders screen that allow right clicks to cancel edit of quantities or condition details instead of exiting to the main screen
stockpiles: add simple import/export dialogs to stockpile overlay panel
stonesense:
- added hotkey to toggle fog ; (default keybinding)
- added hotkey to toggle announcements: a (default keybinding)
- added hotkey to toggle debug mode: ~ (default keybinding)
- added init file config to show announcements (on by default)
- added init file config for whether Esc is recognized for closing the stonesense window (on by default to match previous behavior)
- added init file config for whether creature moods and jobs are displayed (off by default)

[h2]Fixes[/h2]

caravan: no longer incorrectly identify wood-based plant items and plant-based soaps as being ethically unsuitable for trading with the elves
fix/dry-buckets: don't empty buckets for wells that are actively in use
gui/design: don't require an extra right click on the first cancel of building area designations
gui/gm-unit: refresh unit sprite when profession is changed
gui/unit-info-viewer: skill progress bars now show correct XP thresholds for skills past Legendary+5
preserve-rooms:
- don't erroneously release reservations for units that have returned from their missions but have not yet entered the fort map
- handle case where unit records are culled by DF immediately after a unit leaves the map
preserve-tombs: properly re-enable after loading a game that had the tool enabled
stockpiles: don't set use_links_only flag to a random value when the flag is not set to anything in the settings that are being imported
stonesense:
- fixed crash when maximizing or resizing the window
- fixed crash when turning the onscreen display (OSD) layer off
strangemood: ensure generated names for artifacts match what the game itself would generate
zone: assign animal to cage/restraint dialog now allows you to unassign a pet from the cage or restraint if the pet is already somehow assigned (e.g. war dog was in cage and was subsequently assigned to a dwarf)

[h2]Misc Improvements[/h2]

caravan: add filter for written works in display furniture assignment dialog
dig-now: handle digging in pool and river tiles
fix/wildlife: don't vaporize stuck wildlife that is onscreen -- kill them instead (as if they died from old age)
gui/sitemap: show primary group affiliation for visitors and invaders (e.g. civilization name or performance troupe)
immortal-cravings: goblins and other naturally non-eating/non-drinking races will now also satisfy their needs for eating and drinking
stonesense:
- changed announcements to be right-aligned and limited to only show the most recent 10 announcements
- init.txt config file is now read from dfhack-configs/stonesense/init.txt
- creature names are now hidden by default (they can still be shown by pressing n (default keybinding) while stonesense window is active)
- use smaller increments for zooming in and out
- OSD is now hidden by default; hit F2 (default keybinding) to show it again
strangemood: add ability to choose Stone Cutting and Stone Carving as the mood skill
suspendmanager: add more specific messages for submerged job sites and those managed by buildingplan

[h2]Documentation[/h2]

Added example code for creating plugin RPC endpoints that can be used to extend the DFHack API

[h2]Removed[/h2]

dfhack.TranslateName has been renamed to dfhack.translation.translateName

[h2]API[/h2]

Persistence :: getUnsavedSeconds: returns the number of seconds since last save or load
Translation :: generateName: generates in-game names, mirroring DF's internal logic
Units :: getVisibleName: when acting on a unit without an impersonated identity, returns the unit's name structure instead of the associated histfig's name structure
Units :: isUnitInBox, Units :: getUnitsInBox: add versions accepting pos arguments

[h2]Internals[/h2]

Errors when unloading a plugin's DLL are now checked and reported
Plugin command callbacks are now called with the core suspended by default so DF memory is always safe to access without extra steps

[h2]Lua[/h2]

dfhack.persistent.getUnsavedSeconds: Lua API for Persistence :: getUnsavedSeconds
dfhack.translation.generateName: Lua API for Translation :: generateName
dfhack.units.isUnitInBox, dfhack.units.getUnitsInBox: add versions accepting pos arguments
widgets.FilteredList: search keys for list items can now be functions that return a string

[h2]Structures[/h2]

fixed incorrect vtable address for widget superclass on Linux

DFHack 50.15-r1

A quick compatibility update for 50.15. No new features beyond the major release just announced yesterday: https://steamcommunity.com/games/2346660/announcements/detail/519699278946371794

DFHack 50.14-r2.1

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.

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.

Changelog

[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