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

Designating digging and constructions with shapes

Our digging layout tool, gui/design has had a major usability overhaul.
There is a new, button-oriented interface for selecting modes and shapes, and the overall experience of designating, stretching, rotating, moving, and applying to the map is much easier than it was before. Have fun with those curves!

Keep notes in-game with the new fort journal

Brought to you by community member psychowico, gui/journal is a multi-line text editor that allows you to take notes on your fort's goals, plans, and progress. The text is saved with your fort, and the editor provides many mouse- and keyboard-friendly text editing conveniences, like cursor movement, text selection, and copy/paste (fully integrated with the system clipboard). It is especially useful for jotting down what you're in the middle of doing so you can remind yourself when you load the game later.

Fix FPS death with timestream

timestream has a simple premise: when the FPS drops, speed up reality to compensate. It dynamically adjusts the calendar so that the flow of time scales to match a target FPS (usually 100). Put simply, it makes the game move as quickly as it did when you first embarked, even when you have hundreds of units on the map. With timestream active, you can keep the game running at full speed as long as the vanilla FPS counter stays above 15 FPS. At that point, the game will still run faster than it would otherwise, but you'll start noticing the slowdown. This tool breathes new life into old forts. If you start to feel frustrated that the game is getting sluggish, give timestream a try. It's on the "Gameplay" tab of gui/control-panel.

Interactive map editing

You may have heard of tiletypes as the command to use for editing the map. It has a reputation for being difficult to understand, and startlingly easy to get wrong. Thanks to community member tatoyoda600's efforts, we now have gui/tiletypes, which turns map editing into simple point and click!
You can now easily fill in gaps in accidentally-dug areas, change tiles to the materials of your choice for decoration, or reshape the terrain to your liking!

Control the rate of immigration

A common complaint is that very large migrant waves can overwhelm fort infrastructure. If you enable the pop-control tool in gui/control-panel (Gameplay tab), you can limit migration waves to a reasonable size. The default is 10, but you can adjust it to any number you feel comfortable with.
Note that this tool will overwrite the population caps set in the vanilla settings, so if you have those numbers customized, be sure to update the setting for pop-control itself. For example, if you want a maximum population of 100 (along with the default per-wave maximum of 10 immigrants), run pop-control set max-pop 100 after you enable pop-control.

Quick find and zoom for people, locations, and artifacts

The new gui/sitemap tool helps you find and zoom to things quickly.
It works in both adventure and fort mode. In adventure mode, its primary use is to find what you're looking for when you get to a site. If you have a quest to talk to a specific person or find a specific artifact, it can be very frustrating to arrive at the correct site but then be completely unable to find what you're looking for on the map. It doesn't help that nobody at the site can give you directions! gui/sitemap will list all the people, places, and things of interest and let you zoom the screen to their location with a click. You'll still have to find your way over there, though, which can be a challenge if it's deep underground. In fort mode, it serves as a faster alternative to the vanilla overview screens. It also has the unique benefit of telling you both the Dwarven and the English names of artifacts. Now, when you get a notification that Thunderbanner has been stolen, you can search for the artifact in gui/sitemap and see that it's actually warning you about Amudzulban. Then you can zoom to its current location and search some pockets.

Trade depot pathability visualization for wagons

Veteran players may remember a feature from Dwarf Fortress in its pre-Steam times: the ability to show where caravan wagons can path on their way to your trade depot. This feature was not brought forward to DF v50, so DFHack offers a replacement. If you are concerned about whether wagons can get to your depot, or if you'd like to identify the choke points, start up gui/pathable and select the "Depot" tab. That will highlight the tiles that wagons can traverse on their way to your trade depot (or any of your trade depots, if you have more than one).

Announcements

What does DFHack do for Adventure mode?

DFHack supports the DF adventure mode beta on its own adventure-beta Steam branch. If you're subscribed to the beta branch for Dwarf Fortress, please subscribe to the adventure-beta branch for DFHack. DFHack automatically applies a number of bugfixes and interface enhancements by default, such as:

• fix corrupt throwing/shooting state, preventing save/load crashes after shooting a weapon
• extend the searchable keywords in the conversation topic list to make it easier to find the topic you're looking for
• add "ask whereabouts of" conversation topics so you can discover the location of people with whom you have some sort of relationship (before, you could only ask whereabouts of people involved in rumors)
• add drowning/suffocation and blood loss countdown displays so you can tell how dire your situation is

There are also bugfixes, productivity tools, and sandbox (armok) tools specifically designed for adventure mode that you can run as needed:

• advtools party: promotes one of your companions to become a controllable adventurer
• advtools pets: fixes issues with companions' pets and pets you gift to others in adventure mode
• fix/sleepers: fix sleeping units belonging to a camp that never wake up
• gui/sitemap: list and zoom to people, locations, and artifacts
• unretire-anyone: start an adventure as any historical figure in the world (use on embark preparation screen)
• gui/reveal: reveal the adventure mode map and keep it revealed as you move
• bodyswap: move adventurer control to another unit (any other unit)
• flashstep: jump your adventurer across the map by hovering over a tile with the mouse and hitting a hotkey (Ctrl-t)
• ghostly: allow your adventurer to walk through walls
• resurrect-adv: revive a newly dead adventurer
• reveal-adv-map: reveal hidden sites on the adventure travel map

In addition, most general tools that act upon a selected unit, like set-orientation, gui/gm-unit, etc. should work without trouble. You can select the adventurer with the z key, and any other unit by right clicking on them. DFHack is continuing to build support for the new adventure mode, so you can expect even more in upcoming releases!

Locale-sensitive number formatting

DFHack tools can display a lot of large numbers, especially where prices and weights are involved. We have traditionally formatted those numbers exactly the same as DF itself does -- that is, no formatting; just numbers. For example, one million is written as 1000000. This can be hard to read, but it's also not perfectly clear how else the numbers should be formatted. In English, we often add commas to numbers, one comma every third digit, so one million would be written as 1,000,000. That would make it easier to read if English is your native language. People from India might prefer to see one million as 10,00,000, and people from Germany might prefer 1.000.000. So now you have a choice. In gui/control-panel, in the Preferences tab, there is now a Large number formatting preference that you can set.
You have several options:

• None (the default), which formats the numbers without embellishment like vanilla DF does (e.g. 1234567)
• English, which formats the numbers with commas every third digit (e.g. 1,234,567)
• System locale, which formats the numbers according to the locale settings for your operating system (system-dependent)
• SI suffix, which shows up to three significant digits and a metric-system suffix (e.g. 1.23M)
• Scientific, which shows numbers in scientific notation (e.g. 1.2e+06)

Your choice will apply to DFHack displays, such as gui/unit-info-viewer or the prices on the DFHack trade screens. Vanilla DF displays will not be affected.

Dreamfort updates

The Dreamfort quickfort blueprints have seen significant updates in this release. If you are in the middle of building from the Dreamfort blueprints, expect some minor errors or misplaced furniture if you started building from the Dreamfort blueprints in a previous DFHack version. Starting from a new embark, of course, will work perfectly fine. If you're not already familiar with it, Dreamfort is DFHack's marquee blueprint set for a complete fort layout. It demonstrates good design patterns for new players and shows what the game is capable of. For more experienced players, it provides a simple, yet complete fortress that you can quickly get up and running when you want to focus on specific aspects of the game and not worry too much about infrastructure.
Screenshots are available here: https://docs.dfhack.org/en/latest/docs/guides/quickfort-library-guide.html#dreamfort and the walkthrough is available via the blueprint notes (which you can display with gui/quickfort) or online here: https://docs.google.com/spreadsheets/d/15TDBebP8rBNvsFbezb9xuKPmGWNzv7j4XZWq1AsfCio/edit?gid=0#gid=0

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

• advtools:
  • collection of useful commands and overlays for adventure mode
  • added an overlay that automatically fixes corrupt throwing/shooting state, preventing save/load crashes
  • advtools party - promotes one of your companions to become a controllable adventurer
  • advtools pets - fixes pets you gift in adventure mode.
• bodyswap: (reinstated) take control of another unit in adventure mode
• devel/luacov: (reinstated) add Lua script coverage reporting for use in testing and performance analysis
• devel/tree-info: print a technical visualization of tree data
• fix/occupancy: fixes issues where you can't build somewhere because the game tells you an item/unit/building is in the way but there's nothing there
• fix/population-cap: fixes the situation where you continue to get migrant waves even when you are above your configured population cap
• fix/sleepers: (reinstated) fixes sleeping units belonging to a camp that never wake up.
• gui/journal: fort journal with a multi-line text editor
• gui/sitemap: list and zoom to people, locations, and artifacts
• gui/tiletypes: interface for modifying map tiles and tile properties
• plant: (reinstated) tool for creating/growing/removing plants
• pop-control: (reinstated) limit the maximum size of migrant waves
• timestream: (reinstated) keep the game running quickly even when there are large numbers of units on the map

New Features

• Locale-senstive number formatting: select your preferred format in gui/control-panel. prices and other large numbers in DFHack UIs can be displayed with commas (English formatting), the number formatting used by your system locale, in SI units (e.g. 12.3k), or even in scientific notation
• advtools: automatically add a conversation option to "ask whereabouts of" for all your relationships (before, you could only ask whereabouts of people involved in rumors)
• buildingplan: dimension tooltip is now displayed for constructions and buildings that are designated over an area, like bridges and farm plots
• gui/design: all-new visually-driven UI for much improved usability
• gui/notify:
  • new notification type: injured citizens; click to zoom to injured units; also displays a warning if your hospital is not functional (or if you have no hospital)
  • new notification type: drowning and suffocation progress bars for adventure mode
• gui/pathable: new "Depot" mode that shows whether wagons can path to your trade depot
• gui/unit-info-viewer: new overlay for displaying progress bars for skills on the unit info sheet
• logistics: automatically forbid or claim items brought to a stockpile
• plant: can now remove shrubs and saplings; list all valid shrub/sapling raw IDs; grow can make mature trees older; many new command options
• prioritize: new info panel on under-construction buildings showing if the construction job has been taken and by whom. click to zoom to builder; toggle high priority status for job if it's not yet taken and you need it to be built ASAP
• tweak: named-codices: display book titles instead of a material description in the stocks/trade screens

Fixes

• Mortal mode: prevent keybindings that run armok tools from being recognized when in mortal mode
• assign-profile: fix handling of unit option for setting target unit id
• autobutcher: fix inverted ranking of which animals to butcher first
• buildingplan: properly identify appropriate construction items for modded buildings built from thread
• caravan: fix errors in trade dialog if all fort items are traded away while the trade dialog is showing fort items and the confirm trade confirmation is shown
• clear-smoke: properly tag smoke flows for garbage collection to avoid memory leak
• confirm: fix confirmation prompt behavior when overwriting a hotkey zoom location
• control-panel: restore non-default values of per-save enabled/disabled settings for repeat-based commands
• dig: don't leave phantom dig designations behind when autodigging warm/damp designated tiles
• gui/create-item: allow creation of adamantine thread, wool, and yarn
• gui/gm-unit:
  • correctly display skill levels above Legendary+5
  • fix errors when editing/randomizing colors and body appearance
• gui/notify: the notification panel no longer responds to the Enter key so Enter key is passed through to the vanilla UI
• gui/sandbox:
  • spawned citizens can now be useful military squad members
  • spawned undead now have a purple shade (only after save and reload, though)
• makeown: set animals to tame and domesticated
• overlay: overlay positions are now adjusted according to the configured max interface width percentage in the DF settings
• prioritize: also boost priority of already-claimed jobs when boosting priority of a job type so those jobs are not interrupted
• quickfort:
  • fix incorrect handling of stockpiles that are split into multiple separate areas but are given the same label (indicating that they should be part of the same stockpile)
  • allow farm plots to be built on muddy stone (as per vanilla behavior)
• regrass: don't remove mud on regrass, consistent with vanilla behavior
• seedwatch:
  • display a limit of - instead of 0 for a seed that is present in inventory but not being watched
  • do not include unplantable tree seeds in status report
• suspend: remove broken --onlyblocking option; restore functionality to suspend all
• tiletypes: make aquifers functional when adding the aquifer property and there are no existing aquifer tiles in the same map block
• warn-stranded: don't warn for babies carried by mothers who happen to be gathering fruit from trees
• zone:
  • animal assignment overlay button moved to not conflict with vanilla aquarium/terrarium button on glass cages
  • allow friendly creatures to be released from cages by assigning them to a pasture zone and then unassigning them
• Buildings :: containsTile: fix result for buildings that are solid and have no extent structures
• Gui :: makeAnnouncement, Gui :: autoDFAnnouncement: fix case where a new announcement is created instead of adding to the count of an existing announcement if the existing announcement was the first one in the reports vector

Misc Improvements

• Dreamfort:
  • add a full complement of beds and chests to both barracks
  • redesign guildhall/temple/library level for better accessibility
  • walkthough documentation refresh
  • add milking/shearing station in surface grazing pasture
  • integrate building prioritization into the blueprints and remove prioritize checklist steps
  • add plumbing template for filling cisterns with running water
• autobutcher: do not butcher pregnant (or brooding) females
• autonestbox: wait until juveniles become adults before they are assigned to nestboxes
• blueprint: capture track carving designations in addition to already-carved tracks
• buildingplan: add option to ignore items from a specified burrow
• caravan:
  • optional overlay to hide vanilla "bring trade goods to depot" button (if you prefer to always use the DFHack version and don't want to accidentally click on the vanilla button). enable caravan.movegoods_hider in gui/control-panel UI Overlays tab to use.
  • bring goods to depot screen now shows (approximate) distance from item to depot
  • remember filter settings for pedestal item assignment dialog
  • add shortcut to the trade request screen for selecting item types by value (e.g. so you can quickly select expensive gems or cheap leather)
• changevein: follow veins into adjacent map blocks so you can run the command once instead of once per map block that the vein crosses
• empty-bin: select a stockpile, tile, or building to empty all containers in the stockpile, tile, or building
• exterminate:
  • add all target for convenient scorched earth tactics
  • add --limit option to limit number of exterminated creatures
  • add knockout and traumatize method for non-lethal incapacitation
• gui/civ-alert: you can now register multiple burrows as civilian alert safe spaces
• gui/control-panel: highlight preferences that have been changed from the defaults
• gui/create-item: allow right click to cancel out of material dialog submenus
• gui/design: circles are more circular (now matches more pleasing shape generated by digcircle)
• gui/launcher:
  • "space space to toggle pause" behavior is skipped if the game was paused when gui/launcher came up to prevent accidental unpausing
  • refresh default tag filter when mortal mode is toggled in gui/control-panel so changes to which tools autocomplete take effect immediately
• gui/notify: notification panel extended to apply to adventure mode
• gui/quickfort:
  • you can now delete your blueprints from the blueprint load dialog
  • allow farm plots, dirt roads, and paved roads to be designated around partial obstructions without callling it an error, matching vanilla behavior
  • buildings can now be constructed in a "high priority" state, giving them first dibs on buildingplan materials and setting their construction jobs to the highest priority
• gui/unit-info-viewer:
  • add precise unit size in cc (cubic centimeters) for comparison against the wiki values. you can set your preferred number format for large numbers like this in the preferences of control-panel or gui/control-panel
  • now displays a unit's weight relative to a similarly-sized well-known creature (dwarves, elephants, or cats)
  • shows a unit's size compared to the average for the unit's race
• gui/unit-syndromes: make werecreature syndromes easier to search for
• item: option for ignoring uncollected spider webs when you search for "silk"
• nestboxes: increase the scanning frequency for fertile eggs to reduce the chance that they get snarfed by eager dwarves
• orders: you can now delete your exported orders from the import dialog
• prioritize:
  • add ButcherAnimal to the default prioritization list (SlaughterAnimal was already there, but ButcherAnimal -- which is different -- was missing)
  • list both unclaimed and total counts for current jobs when the --jobs option is specified
  • boost performance of script by not tracking number of times a job type was prioritized
• quickfort:
  • support buildable instruments
  • new delete command for deleting player-owned blueprints (library and mod-added blueprints cannot be deleted)
  • support enabling logistics features for autoforbid and autoclaim on stockpiles
• regrass: now accepts numerical IDs for grass raws; regrass --list replaces regrass --plant ""
• suspendmanager: add option to unsuspend that unsuspends all jobs, regardless of potential issues (like blocking other construction jobs)
• tiletypes:
  • performance improvements when affecting tiles over a large area
  • support for creating heavy aquifers
  • new autocorrect property for autocorrecting adjacent tiles when making changes (e.g. adding ramp tops when you add a ramp)

Documentation

• Developer's primer for DFHack's type identity system
• installing: add instructions for how to use Steam DFHack with non-Steam DF (e.g. to benefit from DFHack auto-updates and cloud backups)
• modding-guide: add a section on persistent storage, both for global settings and world-specific settings

Removed

• adv-fix-sleepers: renamed to fix/sleepers
• adv-rumors: merged into advtools
• devel/find-offsets, devel/find-twbt, devel/prepare-save: remove development scripts that are no longer useful
• fix/item-occupancy, fix/tile-occupancy: merged into fix/occupancy
• max-wave: merged into pop-control
• plants: renamed to plant
• dfhack.HIDE_CONSOLE_ON_STARTUP and dfhack.HIDE_ARMOK_TOOLS are no longer directly accessible. Please use control-panel or gui/control-panel to interact wtih those settings.
• gui.FramedScreen: this class is now deprecated; please use gui.ZScreen and widgets.Window instead

API

• Focus strings have moved for stockpile states: dwarfmode/CustomStockpile is now dwarfmode/Stockpile/Some/Customize and similar for dwarfmode/StockpileTools and dwarfmode/StockpileLink
• Buildings :: getName: get a building's name
• format_number: format numbers according to the configured player formatting preference
• Items :: remove: now cancels related jobs and marks the item as hidden and forbidden until it can be garbage collected
• Maps :: isTileAquifer, Maps :: isTileHeavyAquifer, Maps :: setTileAquifer, Maps :: removeTileAquifer, Maps :: setAreaAquifer, Maps :: removeAreaAquifer: new aquifer detection and modification API
• Units :: create, Units :: makeown: new APIs to use bay12-provided entry points for low-level operations

Lua

• dfhack.formatInt, dfhack.formatFloat: formats numbers according to the player preferences for number formatting set in gui/control-panel
• dfhack.gui.getSelectedJob: can now return the job with a destination under the keyboard cursor (e.g. digging/carving/engraving jobs)
• dfhack.internal.getClipboardTextCp437Multiline: for retrieving multiline text from the system clipboard
• dfhack.maps.isTileAquifer, dfhack.maps.isTileHeavyAquifer, dfhack.maps.setTileAquifer, dfhack.maps.removeTileAquifer: access to new aquifer API
• dfhack.units.create, dfhack.units.makeown: Lua access to new module API
• dialogs.showYesNoPrompt: extend options so the standard dialog can be used for gui/confirm-style confirmation prompts
• gui.get_interface_rect, gui.get_interface_frame: convenience functions for working with scaled interfaces
• overlay: new attributes: fullscreen and full_interface for overlays that need access to the entire screen or the scaled interface area, respectively
• plugins.tiletypes.tiletypes_setTile: can now accept a table for access to previously unavailable options
• safe_index: will now return nil when attempting to index into a non-indexable object
• script-manager: add getModSourcePath and getModStatePath so modders can get the directory path to their own files
• string : wrap: now preserves inter-word spacing and can return the wrapped lines as a table of strings instead of a single multi-line string
• widgets.ButtonGroup: subclass of CycleHotkeyLabel that additionally displays clickable graphical buttons
• widgets.CycleHotkeyLabel: when the widget has both forward and backward hotkeys defined, support moving backwards by clicking on the appropriate hotkey hint
• widgets.DimensionsTooltip: reusable selected dimensions tooltip that follows the mouse cursor around
• widgets.FilteredList: don't restrict the player from inputting multiple successive space characters
• widgets.makeButtonLabelText: create text and graphical buttons from character/color/tile maps and/or dynamically loaded tilesets

Structures

• added several bay12 exported entry points to list of known globals
• canonicalized a wide swath of type names, field names, and structure organization to match DF's internal names and organization. fields that already had useful names were largely left alone, but all unk, anon, and other "placeholder" names have been changed. structures that differed from reality were also corrected (e.g. collections of fields that were actually substructures and vice versa).
• job.item_category is now job.specflag, contains a union of flag fields, and depends on the job type
• plant_flags: rename is_burning, is_drowning, is_dead to Bay12 names unused_01, season_dead, dead
• slab_engraving_type: correct order of items (last two were swapped)
• unitst: correct return type of create_nemesis vmethod
• world_data: identify many fields and substructures