DFHack 0.47.05-r7

This is the first usability-focused DFHack release. The major new feature is the in-game command launcher with integrated help, autocomplete, command history (including history search), related tools display, and mouse integration.

You can access the new command launcher by clicking on the "[ DFHack Launcher ]" button in the lower left corner of the screen or by tapping the backquote (`) key. If the backquote key isn't convenient or isn't available for your keyboard layout, there is an alternate hotkey of Ctrl-Shift-D.

You can type part of a command to see autocomplete options. Hit Tab or click on an option to autocomplete. To pull a full commandline from your history, hit Alt-S or click on the "history search" button instead. When you type a command, its help text will be displayed in the large panel at the bottom. Hit Enter or click on the 'run" button to run. That's it! More info on the launcher here (which you can also see in-game when you type "gui/launcher" in the command box : )

From the screenshots, you may notice that text areas now have scrollbars. Click on the arrows at the end to scroll by one line, or on the empty area above or below the green part of the bar to scroll by half pages. You can also click on the command text that you are writing to reposition the cursor for editing.

Many thanks to the community members and beta testers who provided feedback on the launcher! Many of the best usability features were suggested by them! In particular, u/ZergTDG, u/Skitlee5, u/Thebuda, and u/tmPreston. You're awesome! Also D.B. Cooper, Quietust, and everyone else on the DFHack discord who gave feedback throughout development.

DFHack help itself has also been overhauled. More than 300 pages of help text has been reformatted and rewritten to make them more informative, easier to read, and easier to understand. Moreover, all DFHack tools are now tagged so that you can find them easier. Try running the new tags command to explore the categories! These tags also control what is in the list of related tools that appears in the right panel of the launcher when you are running a command.

New stuff

Apart from the aforementioned gui/launcher and tags, there's a bunch of great new stuff in this release:

• u/wolfboyft wrote the DFHack modding guide, which will get you up to speed if you'd like to explore how to use DFHack to extend your raws modding.
• run enable gui/kitchen-info to add more info to the Kitchen screen, including what each ingredient is good for besides cooking.
• Hit "D" on the workorder details screen (where you can, say, set which kind of stone to use for a particular workorder) to get more control over the materials used to fulfill workorder jobs.
• We finally have a good way to dynamically limit the size of the next migration wave with max-wave and limit growth over time with pop-control (or even enforce a hermit challenge!).
• Get notified when creatures that may steal your food, drinks, or items become visible (e.g. keas) with warn-stealers.
• DFHack now comes with a super useful library of manager orders! See them with orders list and import them into your game with orders import. Try orders import library/basic to get a great set of orders for basic fort necessities! More info here.
• DFHack's implementation of DwarfTherapist (manipulator -- accessible from the u-l screen) now comes with a library of pre-made professions that you can apply to your dwarves. More info here.

We are also working mouse controls into more of the DFHack tools. For example, you can now move the blueprint preview around by clicking on the map when using gui/quickfort. You can interact with the map with the mouse in similar ways when using gui/quantum and gui/blueprint. Expect more mouse capabilities for DFHack tools in the future!

How to upgrade

A few files have moved around in this release, so if you're upgrading an existing installation, please read this section.

• When upgrading to this release, please remove the dfhack-config/dwarfmonitor.json file. It will get regenerated the next time you run DF. If you don't regenerate this file, the weather indicator (e.g. "Rain") will overlap with the new DFHack button in the lower left corner. If you have custom modifications to this file that you'd like to keep, please merge them back in once the file has been regenerated.
• DFHack init scripts (dfhack.init, onLoad.init, onMapLoad.init, etc.) have moved into dfhack-config/init/. If you have not made any custom modifications to these files, you don't need to do anything. Default configuration will be generated and used. If you have custom changes, please run DF once to generate the default config files and then move just your custom changes into the corresponding init files. See the docs for details.
• The history files for the various interactive DFHack commandline tools have moved into dfhack-config/. If you want to keep your command histories, please move your existing *.history files into dfhack-config/. Note that the new gui/launcher interface will make the commands in your old dfhack.history file available for searching even if you never get around to moving that file to the new directory.

And, just like every DFHack release, please remove the hack/ directory in your DF game folder before extracting the new version of DFHack into your DF folder. There were several scripts and other files that were removed in this release. If you don't remove the hack/ directory before upgrading, the old, unusable scripts will clutter the autocomplete list in the command launcher.

Screenshots:

DFHack 0.47.05-r7

New Plugins

• autobutcher: split off from zone into its own plugin. Note that to enable, the command has changed from autobutcher start to enable autobutcher.
• autonestbox: split off from zone into its own plugin. Note that to enable, the command has changed from autonestbox start to enable autonestbox.
• overlay: display a "DFHack" button in the lower left corner that you can click to start the new GUI command launcher. The dwarfmonitor weather display had to be moved to make room for the button. If you are seeing the weather indicator rendered over the overlay button, please remove the dfhack-config/dwarfmonitor.json file to fix the weather indicator display offset.

New Scripts

• gui/kitchen-info: adds more info to the Kitchen screen
• gui/launcher: in-game command launcher with autocomplete, history, and context-sensitive help
• gui/workorder-details: adjusts work orders' input item, material, traits
• max-wave: dynamically limit the next immigration wave, can be set to repeat
• pop-control: persistent per fortress population cap, hermit, and max-wave management
• warn-stealers: warn when creatures that may steal your food, drinks, or items become visible

New Internal Commands

• tags: new built-in command to list the tool category tags and their definitions. tags associated with each tool are visible in the tool help and in the output of ls.

Fixes

• autochop: designate largest trees for chopping first, instead of the smallest
• devel/query: fixed error when --tile is specified
• dig-now: Fix direction of smoothed walls when adjacent to a door or floodgate
• dwarf-op: fixed error when applying the Miner job to dwarves
• emigration: fix emigrant logic so unhappy dwarves leave as designed
• gui/gm-unit: allow + and - to adjust skill values as intended instead of letting the filter intercept the characters
• gui/unit-info-viewer: fix logic for displaying undead creature names
• gui/workflow: restore functionality to the add/remove/order hotkeys on the workflow status screen
• quickfort: Dreamfort <quickfort-blueprint-guide> blueprint set: declare the hospital zone before building the coffer; otherwise DF fails to stock the hospital with materials
• view-item-info: fixed a couple errors when viewing items without materials
• dfhack.buildings.findCivzonesAt: no longer return duplicate civzones after loading a save with existing civzones
• dfhack.run_script: ensure the arguments passed to scripts are always strings. This allows other scripts to call run_script with numeric args and it won't break parameter parsing.
• job.removeJob(): ensure jobs are removed from the world list when they are canceled

Misc Improvements

• History files: dfhack.history, tiletypes.history, lua.history, and liquids.history have moved to the dfhack-config directory. If you'd like to keep the contents of your current history files, please move them to dfhack-config.
• Init scripts: dfhack.init and other init scripts have moved to dfhack-config/init/. If you have customized your dfhack.init file and want to keep your changes, please move the part that you have customized to the new location at dfhack-config/init/dfhack.init. If you do not have changes that you want to keep, do not copy anything, and the new defaults will be used automatically.
• UX:
  • You can now move the cursor around in DFHack text fields in gui/ scripts (e.g. gui/blueprint, gui/quickfort, or gui/gm-editor). You can move the cursor by clicking where you want it to go with the mouse or using the Left/Right arrow keys. Ctrl+Left/Right will move one word at a time, and Alt+Left/Right will move to the beginning/end of the text.
  • You can now click on the hotkey hint text in many gui/ script windows to activate the hotkey, like a button. Not all scripts have been updated to use the clickable widget yet, but you can try it in gui/blueprint or gui/quickfort.
  • Label widget scroll icons are replaced with scrollbars that represent the percentage of text on the screen and move with the position of the visible text, just like web browser scrollbars.
• devel/query:
  • inform the user when a query has been truncated due to --maxlength being hit.
  • increased default maxlength value from 257 to 2048
• do-job-now: new global keybinding for boosting the priority of the jobs associated with the selected building/work order/unit/item etc.: Alt-N
• dwarf-op: replaces [ a b c ] option lists with a,b,c option lists
• gui/gm-unit: don't clear the list filter when you adjust a skill value
• gui/quickfort:
  • better formatting for the generated manager orders report
  • you can now click on the map to move the blueprint anchor point to that tile instead of having to use the cursor movement keys
  • display an error message when the blueprints directory cannot be found
• gui/workorder-details: new keybinding on the workorder details screen: D
• keybinding: support backquote (`) as a hotkey (and assign the hotkey to the new gui/launcher interface)
• ls: can now filter tools by substring or tag. note that dev scripts are hidden by default. pass the --dev option to show them.
• manipulator:
  • add a library of useful default professions
  • move professions configuration from professions/ to dfhack-config/professions/ to keep it together with other dfhack configuration. If you have saved professions that you would like to keep, please manually move them to the new folder.
• orders: added useful library of manager orders. see them with orders list and import them with, for example, orders import library/basic
• prioritize: new defaults keyword to prioritize the list of jobs that the community agrees should generally be prioritized. Run prioritize -a defaults to try it out in your fort!
• prospect: add new --show option to give the player control over which report sections are shown. e.g. prospect all --show ores will just show information on ores.
• quickfort:
  • Dreamfort <quickfort-blueprint-guide> blueprint set improvements: set traffic designations to encourage dwarves to eat cooked food instead of raw ingredients
  • library blueprints are now included by default in quickfort list output. Use the new --useronly (or just -u) option to filter out library bluerpints.
  • better error message when the blueprints directory cannot be found
• seedwatch: seedwatch all now adds all plants with seeds to the watchlist, not just the "basic" crops.
• materials.ItemTraitsDialog: added a default on_select-handler which toggles the traits.

Removed

• fix/build-location: The corresponding DF bug (5991) was fixed in DF 0.40.05
• fix/diplomats: DF bug 3295 fixed in 0.40.05
• fix/fat-dwarves: DF bug 5971 fixed in 0.40.05
• fix/feeding-timers: DF bug 2606 is fixed in 0.40.12
• fix/merchants: DF bug that prevents humans from making trade agreements has been fixed
• gui/assign-rack: No longer useful in current DF versions
• gui/hack-wish: Replaced by gui/create-item
• gui/no-dfhack-init: No longer useful since players don't have to create their own dfhack.init files anymore

API

• Removed "egg" ("eggy") hook support (Linux only). The only remaining method of hooking into DF is by interposing SDL calls, which has been the method used by all binary releases of DFHack.
• Removed Engravings module (C++-only). Access world.engravings directly instead.
• Removed Notes module (C++-only). Access ui.waypoints.points directly instead.
• Removed Windows module (C++-only) - unused.
• Constructions module (C++-only): removed t_construction, isValid(), getCount(), getConstruction(), and copyConstruction(). Access world.constructions directly instead.
• Gui::getSelectedItem(), Gui::getAnyItem(): added support for the artifacts screen
• Units::teleport(): now sets unit.idle_area to discourage units from walking back to their original location (or teleporting back, if using fastdwarf)

Lua

• Added dfhack.screen.hideGuard(): exposes the C++ Screen::Hide to Lua
• History: added dfhack.getCommandHistory(history_id, history_filename) and dfhack.addCommandToHistory(history_id, history_filename, command) so gui scripts can access a commandline history without requiring a terminal.
• helpdb: database and query interface for DFHack tool help text
• tile-material: fix the order of declarations. The GetTileMat function now returns the material as intended (always returned nil before). Also changed the license info, with permission of the original author.
• utils.df_expr_to_ref(): fixed some errors that could occur when navigating tables
• widgets.CycleHotkeyLabel: clicking on the widget will now cycle the options and trigger on_change(). This also applies to the ToggleHotkeyLabel subclass.
• widgets.EditField:
  • new onsubmit2 callback attribute is called when the user hits Shift-Enter.
  • new function: setCursor(position) sets the input cursor.
  • new attribute: ignore_keys lets you ignore specified characters if you want to use them as hotkeys
• widgets.FilteredList: new attribute: edit_ignore_keys gets passed to the filter EditField as ignore_keys
• widgets.HotkeyLabel: clicking on the widget will now call on_activate().
• widgets.Label: scroll function now interprets the keywords +page, -page, +halfpage, and -halfpage in addition to simple positive and negative numbers.

Structures

• Eliminate all "anon_X" names from structure fields
• army: change squads vector type to world_site_inhabitant, identify min_smell_trigger+max_odor_level+max_low_light_vision+sense_creature_classes
• cave_column_rectangle: identify coordinates
• cave_column: identify Z coordinates
• embark_profile: identify reclaim fields, add missing pet_count vector
• entity_population: identify layer_id
• feature: identify "shiftCoords" vmethod, irritation_level and irritation_attacks fields
• flow_guide: identify "shiftCoords" vmethod
• general_refst: name parameters on getLocation and setLocation vmethods
• general_ref_locationst: name member fields
• historical_entity: confirm hostility_level and siege_tier
• item: identify method notifyCreatedMasterwork that is called when a masterwork is created.
• language_name_type: identify ElfTree and SymbolArtifice thru SymbolFood
• timed_event: identify layer_id
• ui_advmode: identify several fields as containing coordinates
• ui: identify actual contents of unk5b88 field
• unitst: identify histeventcol_id field inside status2
• viewscreen_barterst: name member fields
• viewscreen_tradegoodsst: rename trade_reply OffendedAnimal+OffendedAnimalAlt to OffendedBoth+OffendedAnimal
• world_site_inhabitant: rename outcast_id and founder_outcast_entity_id, identify interaction_id and interaction_effect_idx

Documentation

• Added modding-guide
• Group DFHack tools by tag <tools> so similar tools are grouped and easy to find
• Update all DFHack tool documentation (300+ pages) with standard syntax formatting, usage examples, and overall clarified text.