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!

Highlights

Table of contents in gui/journal

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

timestream bugfixes and improvements

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.

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 Features

• 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

Fixes

• 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)

Misc Improvements

• 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)

Documentation

• improved docs for dfhack.units module functions

Removed

• 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

API

• 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

Lua

• 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

Structures

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