This is the second usability-focused release of DFHack. In the previous release, we made initial progress with the in-game command launcher with autocomplete and integrated command help. This release builds on that start with improved mouse controls (like draggable scrollbars) and a brand new framework for on-screen informational overlays and interactive widgets that respond to what's currently happening in the game.

The cool thing is that this overlay framework is ready for use by mods, including Steam Workshop mods! All modders have to do is declare an OverlayWidget in their script code and the overlay framework will discover it and attach it to the correct Dwarf Fortress screens. Players can enable, disable, or reposition overlay widgets with the new click-and-drag gui/overlay configuration interface. You can start playing with this interface with the overlay widgets that we've already ported to the new framework, such as the date, happiness meter, and weather indicator from dwarfmonitor.

Q: Wait! Go back! So DFHack is ready for the steam release now??

A: No, sorry, not yet. We have a lot of work to do to adapt DFHack to the new Dwarf Fortress release. It might take us a few months, but you will have your favorite tools back. And we hope to have even more usability improvements ready for you then too!

Q: So, like, why are you releasing now? Don't you know that the Steam release is in a few days?

A: Yeah, we know. This release is more for those who aren't upgrading right away, like players who aren't on Steam, adventure mode players, and, of course, players who want to wait for DFHack to become available for the new version before they switch to it : )

Highlights

The Hotkeys Hotspot

The major new feature is the Hotkeys Hotspot. You may not know this, but DFHack has many default keybindings that are bound to specific Dwarf Fortress screens (like the manager orders screen or the main map) that run useful DFHack commands. For example, when you're on the manager orders screen and have a manager order selected, you can hit Alt-Q to change the number of items that the workorder will produce.

The Hotkeys Hotspot uses the new overlay framework to provide a mouse rollover menu that makes these bound commands available to you in a clickable list. You can also right-click on them to open them in the in-game launcher to modify the command and/or see the associated command help. You can add more commands to this list (or take some away) via the DFHack keybinding command, too.

You can show the rollover menu by moving your mouse near the upper left corner of the screen, a little down from the top. On the main map, this spot is marked by an exclamation point (!), but the spot is "hot" on every screen, even if the exclamation point is covered up by something. You can reposition the hotspot with gui/overlay if you want it in a more convenient place. You can also bring it up with the keyboard instead of the mouse by hitting the Ctrl-Shift-C hotkey.

gui/overlay

gui/overlay is the beginning of a new trend for DFHack: in-game configuration that remembers your choices from game to game without any editing of init files. Also, notice the fancy new mouse controls like mouse hover reactions and click-and-drag widgets. Expect to see more of this from DFHack in the future!

spectate

The spectate plugin has seen a good bit of improvement in this release. Once your fort is in a good, steady state, try firing this tool up to automatically follow dwarves around, switching among them periodically, so you can sit back and watch your dwarves be dwarfy!

channel-safely

The new channel-safely tool protects your dwarves from digging themselves to death while channeling out large projects. Digging a large drowning trap or a magma piston? Give this tool a try!

How to upgrade

• Remove the existing hack/ directory in your Dwarf Fortress game folder
• Extract the DFHack release archive into your Dwarf Fortress directory. If it asks you, let it overwrite files.
• If you use TWBT, you can get an updated version for this release here: https://github.com/thurin/df-twbt/releases/tag/0.47.05-r8

Full upgrade instructions are available online here

Full changelog

New Plugins

• overlay: plugin is transformed from a single line of text that runs gui/launcher on click to a fully-featured overlay injection framework. It now houses a popup menu for keybindings relevant to the current DF screen, all the widgets previously provided by dwarfmonitor (e.g. the current date and number of happy/unhappy dwarves), the overlay that highlights suspended buildings when you pause, and others. See overlay-dev-guide for details.
• channel-safely: auto-manage channel designations to keep dwarves safe

New Scripts

• gui/overlay: configuration interface for the DFHack overlays and overlay widgets. includes a click-and-drag interface for repositioning widgets!

Fixes

• Core: ensure foo.init always runs before foo.*.init (e.g. dfhack.init should always run before dfhack.something.init)
• autofarm: flush output so status text is visible immediately after running the command
• autolabor, autohauler: properly handle jobs 241, 242, and 243
• automaterial:
  • fix the cursor jumping up a z level when clicking quickly after box select
  • fix rendering errors with box boundary markers
• buildingplan: fix crash when canceling out of placement mode for a building with planning mode enabled and subsequently attempting to place a building that does not have planning mode enabled and that has no pertinent materials available
• dwarf-op: fixed error when matching dwarves by name
• gui/create-item: prevent materials list filter from intercepting sublist hotkeys
• gui/gm-unit: fixed behavior of + and - to adjust skill values instead of populating the search field
• hotkeys: correctly detect hotkeys bound to number keys, F11, and F12
• labormanager: associate quern construction with the correct labor
• mousequery: fix the cursor jumping up z levels sometimes when using TWBT
• tiletypes: no longer resets dig priority to the default when updating other properties of a tile
• warn-stealers:
  • register callback with correct event name so that units entering the map are detected
  • announce thieving creatures that spawn already revealed
  • cache unit IDs instead of unit objects to avoid referencing stale pointers
• workorder: fix interpretation of json-specified orders that set the item_type field
• EventManager:
  • fix a segmentation fault with the REPORT event
  • fix the JOB_STARTED event only sending events to the first handler listed instead of all registered handlers

Misc Improvements

• UX:
  • List widgets now have mouse-interactive scrollbars
  • You can now hold down the mouse button on a scrollbar to make it scroll multiple times.
  • You can now drag the scrollbar up and down to scroll to a specific spot
• autolabor, autohauler: refactored to use DFHack's messaging system for info/debug/trace messages
• blueprint:
  • new --smooth option for recording all smoothed floors and walls instead of just the ones that require smoothing for later carving
  • record built constructions in blueprints
  • record stockpile/building/zone names in blueprints
  • record room sizes in blueprints
  • generate meta blueprints to reduce the number of blueprints you have to apply
  • support splitting the output file into phases grouped by when they can be applied
  • when splitting output files, number them so they sort into the order you should apply them in
• digtype: new -z option for digtype to restrict designations to the current z-level and down
• dwarfmonitor: widgets have been ported to the overlay framework and can be enabled and configured via the gui/overlay UI
• gui/blueprint: support new blueprint phases and options
• gui/cp437-table: new global keybinding for the clickable on-screen keyboard for players with keyboard layouts that prevent them from using certain keys: Ctrl-Shift-K
• gui/create-item: restrict materials to those normally allowed by the game by default, introduce new --unrestricted option for full freedom in choosing materials
• gui/launcher: show help for commands that start with ':' (like :lua)
• gui/quantum: add option to allow corpses and refuse in your quantum stockpile
• hotkeys:
  • hotkey screen has been transformed into an interactive overlay widget that you can bring up by moving the mouse cursor over the hotspot (in the upper left corner of the screen by default). Enable/disable/reposition the hotspot in the gui/overlay UI. Even if the hotspot is disabled, the menu can be brought up at any time with the Ctrl-Shift-C hotkey.
  • now supports printing active hotkeys to the console with hotkeys list
• ls:
  • indent tag listings and wrap them in the rightmost column for better readability
  • new --exclude option for hiding matched scripts from the output. this can be especially useful for modders who don't want their mod scripts to be included in ls output.
• modtools/create-unit: better unit naming, more argument checks, assign nemesis save data for units without civilization so they can be properly saved when offloaded
• orders: replace shell craft orders in the standard orders list you get with orders import library/basic with orders for shell leggings. They have a slightly higher trade price. Also, "shleggings" is just hilarious.
• quickfort-library-guide: improved layout of marksdwarf barracks in the example Dreamfort blueprints
• spectate:
  • new auto-unpause option for auto-dismissal of announcement pause events (e.g. sieges).
  • new auto-disengage option for auto-disengagement of plugin through player interaction whilst unpaused.
  • new tick-threshold option for specifying the maximum time to follow the same dwarf
  • new animals option for sometimes following animals
  • new hostiles option for sometimes following hostiles
  • new visiting option for sometimes following visiting merchants, diplomats or plain visitors
  • added persistent configuration of the plugin settings
• unsuspend: new overlay for displaying status of suspended buildings (functionality migrated from removed resume plugin)

Removed

• gui/create-item: removed --restricted option. it is now the default behavior
• resume: functionality (including suspended building overlay) has moved to unsuspend

API

• Constructions module: added insert() to insert constructions into the game's sorted list.
• MiscUtils: added the following string transformation functions (refactored from uicommon.h): int_to_string, ltrim, rtrim, and trim; added string_to_int
• Units module:
  • new action timer API for speeding up of slowing down units
  • added new predicates for:
  • isUnitInBox()
  • isAnimal()
  • isVisiting() any visiting unit (diplomat, merchant, visitor)
  • isVisitor() ie. not merchants or diplomats
  • isInvader()
  • isDemon() returns true for unique/regular demons
  • isTitan()
  • isMegabeast()
  • isGreatDanger() returns true if unit is a demon, titan, or megabeast
  • isSemiMegabeast()
  • isNightCreature()
  • isDanger() returns true if is a 'GreatDanger', semi-megabeast, night creature, undead, or invader
  • modified predicates:
  • isUndead() now optionally ignores vampires instead of always ignoring vampires
  • isCitizen() now optionally ignores insane citizens instead of always ignoring insane citizens
• Gui::anywhere_hotkey: for plugin commands bound to keybindings that can be invoked on any screen
• Gui::autoDFAnnouncement, Gui::pauseRecenter: added functionality reverse-engineered from announcement code
• Gui::revealInDwarfmodeMap: Now enforce valid view bounds when pos invalid, add variant accepting x, y, z
• Lua::Push(): now handles maps with otherwise supported keys and values
• Lua::PushInterfaceKeys(): transforms viewscreen feed() keys into something that can be interpreted by lua-based widgets

Internals

• Constructions module: findAtTile now uses a binary search intead of a linear search
• MSVC warning level upped to /W3, and /WX added to make warnings cause compilations to fail.

Lua

• Lua mouse events now conform to documented behavior in lua-api -- _MOUSE_L_DOWN will be sent exactly once per mouse click and _MOUSE_L will be sent repeatedly as long as the button is held down. Similarly for right mouse button events.
• dfhack.constructions.findAtTile(): exposed preexisting function to Lua.
• dfhack.constructions.insert(): exposed new function to Lua.
• gui.Screen.show(): now returns self as a convenience
• gui.View.getMousePos() now takes an optional ViewRect parameter in case the caller wants to get the mouse pos relative to a rect that is not the frame_body (such as the frame_rect that includes the frame itself)
• widgets.EditField: now allows other widgets to process characters that the on_char callback rejects.
• widgets.FilteredList: now provides a useful default search key for list items made up of text tokens instead of plain text
• widgets.HotkeyLabel: now ignores mouse clicks when on_activate is not defined
• widgets.List:
  • new getIdxUnderMouse() function for detecting the list index under the active mouse cursor. this allows for "selection follows mouse" behavior
  • shift-clicking now triggers the submit2 attribute function if it is defined
• widgets.Panel: new frame_style and frame_title attributes for drawing frames around groups of widgets
• widgets.ResizingPanel: now accounts for frame inset when calculating frame size
• widgets.Scrollbar: new scrollbar widget that can be paired with an associated scrollable widget. Integrated with widgets.Label and widgets.List.

Structures

• general_refst: type virtual union member for ITEM_GENERAL
• historical_figure_info.T_reputation.unk_2c: identify year + year_ticks
• itemst: identify two vmethods related to adding thread improvements to items made of cloth, and label several previously unknown return types
• proj_magicst: correct structure fields (to match 40d)
• unit_action_type_group: added enum and tagged unit_action_type entries with its groups for DFHack's new action timer API.
• world: identify type of a vector (still not known what it's for, but it's definitely an item vector)

Documentation

• overlay-dev-guide: documentation and guide for injecting functionality into DF viewscreens from Lua scripts and creating interactive overlay widgets
• dfhack.gui.revealInDwarfmodeMap: document center bool for Lua API