Jun 1, 2023

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!

Announcements

Armok mode vs. Mortal mode

If DFHack makes the game less fun for you because the tools are too powerful, please consider enabling "Mortal mode". Open the "Preferences" tab of gui/control-panel and toggle the "Show armok tools" setting. This will hide any tools that are tagged as "armok" (that is, god-mode tools) from gui/launcher, gui/control-panel, the DFHack logo popup menu, and anywhere else DFHack commands are listed. Global hotkeys for those tools will also cease to function. All productivity, analysis, bugfix, and design tools will still be shown as normal.

Ongoing large projects

Here are the projects we're working on right now (and the [@ person] on DFHack Discord you should talk to if you have opinions). If you are interested in early access, please join the "Beta - DFHack pre-releases" branch in your Steam client. You can also download pre-releases from GitHub.

buildingplan v2 [@TaxiService] - clearer UI, easier configuration, filter history
stocks [@silver_fly] - item management interface, including bulk actions like "mark all worn clothing for trade"
stockpiles, logistics, quickfort [@myk002] - stockpile configuration presets, automatic dumping, trading, or melting of stockpile contents, stockpile and zone support for quickfort
gui/design v2 [@coskerstrike] - UI overhaul, performance improvements

and, of course, a host of smaller bugfixes and features.

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 in the DF settings, and you can show it by entering mining mode or selecting the dump/forbid tool. We're working on making DFHack tools more mouse-aware and accessible.

Highlights

exportlegends

There are a variety of tools for digging into the stories in legends mode. Most of them use the extra legends information DFHack exports with the exportlegends tool to give you a more complete picture of what is going on.

How to use:

Enter legends mode as usual from DF
Click the green button to do the vanilla export
Open gui/launcher and run exportlegends

exportlegends might take a while to run if your world is large. Now you should have two .xml files in your Dwarf Fortress folder. The ...-legends_plus.xml file is the extended export from DFHack.

Note that DF itself used to export more information than it does now, and many tools can't cope with the lack of vanilla information. The current best tool to use for external legends browsing is the cross-platform Legends Browser 2

Happy legends browsing!

gui/mod-manager

For those of us who use mods, creating a new world can be very frustrating. Each mod must be manually re-enabled for every new created world, and for long mod lists, that is quite a chore.

Enter gui/mod-manager. You don't actually have to run the command. It will show up as an overlay automatically when you create a new world. If you have a default mod list saved already, you don't even need to go into the DF "Mods" page. As soon as you start the world creation process, gui/mod-manager will automatically apply your mod list.

To set it up, start creating a world and set up your mods as normal. Then click on the "Mod manager" button at the bottom of the page or hit the m hotkey. This will bring up a dialog where you can save your current mod list and set it as the default for future worlds. That's it.

gui/sandbox

This tool stretches the bounds of "Armok mode". It gives you an interface for willing units, trees, and items into existence. Feeling like you need a challenge? Set units to "hostile" and spawn yourself up an invading army : )

necronomicon

Sometimes you want your dwarves to become necromancers, and sometimes you don't. However, you can't control what visitors or returning raiders bring back into your fort. It used to be that you'd have to manually scan through every book and see whether it contains the "secrets of life and death". Now, a quick run of the necronomicon command will give you a summary of whether you have any books with secrets in your fort and what their titles (and powers) are. Then you can sequester those books or promote them on display in your library, as per your agenda.

Generated release notes

New Plugins

add-spatter: (reinstated) allow mods to add poisons and magical effects to weapons
changeitem: (reinstated) change item material, quality, and subtype
createitem: (reinstated) create arbitrary items from the command line
deramp: (reinstated) removes all ramps designated for removal from the map
flows: (reinstated) counts map blocks with flowing liquids
lair: (reinstated) mark the map as a monster lair (this avoids item scatter when the fortress is abandoned)
luasocket: (reinstated) provides a Lua API for accessing network sockets
work-now: (reinstated, renamed from workNow) prevent dwarves from wandering aimlessly with "No job" after completing a task

New Scripts

assign-minecarts: (reinstated) quickly assign minecarts to hauling routes
diplomacy: view or alter diplomatic relationships
exportlegends: (reinstated) export extended legends information for external browsing
fix/stuck-instruments: fix instruments that are attached to invalid jobs, making them unusable. turn on automatic fixing in gui/control-panel in the Maintenance tab.
gui/autodump: point and click item teleportation and destruction interface (available only if armok tools are shown)
gui/mod-manager: automatically restore your list of active mods when generating new worlds
gui/sandbox: creation interface for units, trees, and items (available only if armok tools are shown)
light-aquifers-only: (reinstated) convert heavy aquifers to light
modtools/create-item: (reinstated) commandline and API interface for creating items
necronomicon: search fort for items containing the secrets of life and death

Fixes

DFHack screen backgrounds now use appropriate tiles in DF Classic
RemoteServer: fix crash on malformed json in dfhack-config/remote-server.json
autolabor: work detail override warning now only appears on the work details screen
deathcause: fix incorrect weapon sometimes being reported
gui/create-item: allow armor to be made out of leather when using the restrictive filters
gui/design: Fix building and stairs designation
quickfort:
- properly allow dwarves to smooth, engrave, and carve beneath walkable tiles of buildings
- fixed detection of tiles where machines are allowed (e.g. water wheels can be built on stairs if there is a machine support nearby)
- fixed rotation of blueprints with carved track tiles
RemoteFortressReader: ensured names are transmitted in UTF-8 instead of CP437

Misc Improvements

Core: new commandline flag/environment var: pass --disable-dfhack on the Dwarf Fortress commandline or specify DFHACK_DISABLE=1 in the environment to disable DFHack for the current session.
Dreamfort: improve traffic patterns throughout the fortress
Settings: recover gracefully when settings files become corrupted (e.g. by DF CTD)
Window behavior:
- non-resizable windows now allow dragging by their frame edges by default
- if you have multiple DFHack tool windows open, scrolling the mouse wheel while over an unfocused window will focus it and raise it to the top
autodump: no longer checks for a keyboard cursor before executing, so autodump destroy (which doesn't require a cursor) can still function
gui/autodump: fort-mode keybinding: Ctrl-H (when armok tools are enabled in gui/control-panel)
gui/blueprint: recording of stockpile layouts and categories is now supported. note that detailed stockpile configurations will not be saved (yet)
gui/control-panel: new preference for whether filters in lists search for substrings in the middle of words (e.g. if set to true, then "ee" will match "steel")
gui/create-item: ask for number of items to spawn by default
gui/design: Improved performance for drawing shapes
gui/gm-editor:
- when passing the --freeze option, further ensure that the game is frozen by halting all rendering (other than for DFHack tool windows)
- Alt-A now enables auto-update mode, where you can watch values change live when the game is unpaused
gui/quickfort:
- blueprints that designate items for dumping/forbidding/etc. no longer show an error highlight for tiles that have no items on them
- place (stockpile layout) mode is now supported. note that detailed stockpile configurations were part of query mode and are not yet supported
- you can now generate manager orders for items required to complete bluerpints
light-aquifers-only: now available as a fort Autostart option in gui/control-panel. note that it will only appear if "armok" tools are configured to be shown on the Preferences tab.
orders: update orders in library for prepared meals, bins, archer uniforms, and weapons
overlay: add links to the quickstart guide and the control panel on the DF title screen
stockpiles: allow filtering creatures by tameability

Removed

orders: library/military_include_artifact_materials library file removed since recent research indicates that platinum blunt weapons and silver crossbows are not more effective than standard steel. the alternate military orders file was also causing unneeded confusion.

Internals

dfhack.internal: added memory analysis functions: msizeAddress, getHeapState, heapTakeSnapshot, isAddressInHeap, isAddressActiveInHeap, isAddressUsedAfterFreeInHeap, getAddressSizeInHeap, and getRootAddressOfHeapObject

Lua

ensure_keys: walks a series of keys, creating new tables for any missing values
gui: changed frame naming scheme to FRAME_X rather than X_FRAME, and added aliases for backwards compatibility. (for example BOLD_FRAME is now called FRAME_BOLD)
overlay.reload(): has been renamed to overlay.rescan() so as not to conflict with the global reload() function. If you are developing an overlay, please take note of the new function name for reloading your overlay during development.

Structures

abstract_building_contents: identify fields and flags related to location item counts
arena_tree: identify fields related to tree creation
arena_unit: identify fields related to unit creation
mod_headerst: rename non_vanilla flag to vanilla to reflect its actual usage
profession: renamed captions Cheese Maker to Cheesemaker, Bee Keeper to Beekeeper, and Bone Setter to Bone Doctor