May 9, 2024

DFHack - Dwarf Fortress Modding Engine - myk002

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!

Highlights

Localization support

You can now install both DFHack and the Dwarf Fortress localization project for translating essential parts of the DF UI into your native language!

It currently has good support for:

Spanish
Italian
Russian
German
Portuguese (Brazil)
French
Polish

The translations are done by volunteers. Please consider contributing to the translations if you are bilingual -- these translations help make Dwarf Fortress more accessible to non-English speakers.

More details at the Dwarf Fortress localization project home page: https://github.com/dfint

Adventure mode support

Dwarf Fortress adventure mode is currently available on DF's Steam beta branch. DFHack supports the adventure beta on its own adventure-beta branch. Please make sure you are subscribed to DFHack's adventure-beta branch if you are running the DF adventure beta!

We are going through our back catalog and steadily updating adventure mode tools. Moreover, we are modifying existing tools as necessary to be useful for adventure mode.

Here's what's been validated so far:

flashstep: teleport the adventurer to the mouse cursor
ghostly: allow the adventurer to walk through walls
gui/create-item: create arbitrary items
gui/reveal: reveal the map beyond your cone of vision
gui/sandbox: create units or trees (or items too)
gui/unit-info-viewer: get extended information on the selected unit
resurrect-adv: bring your adventurer back to life
reveal-adv-map: reveal hidden world map tiles
reveal-hidden-sites: reveal hidden world map sites
reveal-hidden-units: reveal hidden units on the local map
unretire-anyone: start an adventure as anybody in the world

In addition, all tools that aren't mode-specific, such as the mod manager and the new markdown unit/item description export, should work just fine too. If you try to use a tool in adventure mode and it doesn't behave as you'd expect, please tell us so we can improve the experience!

Expectations for the adventure mode beta

DFHack needs to release a new compatible build whenever a new DF beta is pushed, just like we need to release a new compatible build whenever a stable DF version is released.

The good news is that DFHack now has a process in place to automatically build a compatible DFHack version when a new DF beta drops. DFHack should be compatible with new DF betas within 15 minutes. Sometimes, however, Steam gets one update but not the other. If you get a message that DFHack does not recognize the version of Dwarf Fortress, try going into the app settings in your Steam client for both DFHack and Dwarf Fortress, click on Installed Files, and click the Verify integrity of game files button. That will poke Steam to ensure that both DF and DFHack are fully updated.

In addition to compatibility bumps, the adventure-beta branch of DFHack will be updated frequently as DFHack's support for adventure mode is improved.

Export unit and item descriptions

This release includes a unit/item description exporter that will write details about the selected unit or item to a formatted markdown text file.

Just select a unit or item and hit the Ctrl-t hotkey (or select markdown from the DFHack logo context menu)! The text will be written to a file in your Dwarf Fortress game directory, named after your current world. If you export multiple times, the text will be appended to the same file, so feel free to run markdown on all your forgotten beasts and expensive artifacts. The whole list will be ready for you when you're done.

Quick switch favorites for building planner materials

When you want to use a specific material for construction, say because you are designing a pattern in your tavern floor, it can be annoying to have to set the material filter each time. Now, you can set your favorite material filters and quickly switch among them with the new building planner favorites panel!

Your favorites are saved with your fort, so they'll be there for you if you save and load the game.

You can also rename a favorite by shift-clicking on the name.

Announcements

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

Updated for adventure mode:
- reveal
- gui/sandbox, gui/create-item, gui/reveal
adaptation: (reinstated) inspect or set unit cave adaptation levels
fix/engravings: fix corrupt engraving tiles
flashstep: (reinstated) teleport your adventurer to the mouse cursor
ghostly: (reinstated) allow your adventurer to phase through walls
markdown: (reinstated) export description of selected unit or item to a text file
resurrect-adv: (reinstated) allow your adventurer to recover from death
reveal-adv-map: (reinstated) reveal (or hide) the adventure map
unretire-anyone: (reinstated) choose anybody in the world as an adventurer

New Features

DFHack and the Dwarf Fortress translation project can now both be run at the same time
buildingplan: quick material filter favorites on main planner panel
instruments: new subcommand instruments order for creating instrument work orders

Fixes

blueprint: correctly define stockpile boundaries in recorded stockpile ("place") blueprints when there are adjacent non-rectangular stockpiles of identical types
caravan: don't include undiscovered divine artifacts in the goods list
combine: respect container volume limits
dig:
- refresh count of tiles that will be modified by "mark all designated tiles on this z-level for warm/damp dig" when the z-level changes
- don't affect already-revealed tiles when marking z-level for warm/damp dig
gui/quantum: fix processing when creating a quantum dump instead of a quantum stockpile
logistics: include semi-wild pets when autoretrain is enabled
modtools/create-item: now functions properly when the reaction-gloves tweak is active
prospect: don't use scientific notation for representing large numbers
quickfort:
- don't designate multiple tiles of the same tree for chopping when applying a tree chopping blueprint to a multi-tile tree
- fix detection of valid tiles for wells
suspendmanager: fully suspend unbuildable dead ends (e.g. buildling second level of a wall when the wall top is only accessible via ramp, causing the planned wall to be pathable but not buildable)
zone:
- fix display of distance from cage/pit for small pets in assignment dialog
- refresh values in distance column when switching selected pastures when the assign animals dialog is open

Misc Improvements

Dreamfort: move wells on services level so brawling drunken tavern patrons are less likely to fall in
New commandline options for controlling the Cloud Save coprocess when launching from Steam. See the dfhack-core documentation for details.
caravan: display who is in the cages you are selecting for trade and whether they are hostile
combine: reduce combined drink sizes to 25
deathcause: automatically find and choose a corpse when a pile of mixed items is selected
dig:
- warm/damp/aquifer status will now be shown in mining mode for tiles that your dwarves can see from the level below
- warm/damp/aquifer status will now be shown when in smoothing/engraving modes
flashstep: new keybinding for teleporting adventurer to the mouse cursor: Ctrl-t (when adventure map is in the default state and mortal mode is disabled in DFHack preferences)
gui/autobutcher: add shortcuts for butchering/unbutchering all animals
gui/launcher: add button for copying output to the system clipboard
gui/quantum:
- add option for whether a minecart automatically gets ordered and/or attached
- when attaching a minecart, show which minecart was attached
- allow multiple feeder stockpiles to be linked to the minecart route
markdown: new keybinding for triggering text export: Ctrl-t (when unit or item is selected)
prioritize: add PutItemOnDisplay jobs to the default prioritization list -- when these kinds of jobs are requested by the player, they generally want them done ASAP
regrass:
- can now add grass to stairs, ramps, ashes, buildings, muddy stone, shrubs, and trees
- can now restrict area of effect to specified tile, block, cuboid, or z-levels
- can now add grass in map blocks where there hasn't been any
- can now choose specific grass type
stockpiles: support import and export "desired items" configuration for route stops
unretire-anyone: new keybinding for adding a historical figure to the adventurer selection list in the adventure mode setup screen: Ctrl-a

API

dfhack.items.getReadableDescription(): easy API for getting a human-readable item description with useful annotations and information (like tattered markers or who is in a cage)
Items::createItem: now returns a list of item pointers rather than a single ID, moved creator parameter to beginning, added growth_print and no_floor parameters at end
World::getAdventurer: returns current adventurer unit
World::ReadPauseState: now returns true when the game is effectively paused due to a large panel obscuring the map. this aligns the return value with the visual state of the pause button when in fort mode.

Lua

dfhack.internal.setClipboardTextCp437Multiline: for copying multiline text to the system clipboard
dfhack.items.createItem: return value and parameters have changed as per C++ API
dfhack.world.getAdventurer: returns current adventurer unit

Documentation

Quickfort Blueprint Library: add demo videos for pump stack and light aquifer tap blueprints
Update docs for dependency requirements and compilation procedures