PSAs

Standard alpha release warnings:

• DFHack tools probably won't corrupt your savegame, but it would be really smart to keep backups of the forts that you care about. DFHack may not have fully adapted to the changes in the new version of Dwarf Fortress, and, especially at this early stage of release and ongoing rapid development, there WILL be bugs. Please always inform us quickly about crash bugs. We prioritize getting those fixed first.
• Many tools have not been tested thoroughly with Steam DF. The tools that are untested will show a warning if you try to run them and exit immediately. You can run the command again to override the warning (though of course the tools may not work).
• The in-game interface for running DFHack commands (gui/launcher) will not show untested 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 autocomplete as normal. Some tools do not compile yet and are not available at all, even when in dev mode.

For those of you using sdl12compat, note that you will need to replace the "SDLreal.dll" file that DFHack installs with the SDL.dll (renamed to "SDLreal.dll") from sdl12compat. While we do not specifically recommend using sdl12compat, we have generally heard positive feedback about it.

Steam deck users: To avoid blocking the screen with the DFHack terminal window, please edit the dfhack-config/init/dfhack.init file and add a line with the word hide. This will hide the DFHack terminal and get it out of the way. You can show it again if you need it by running the command show from gui/launcher.

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.

Easily plan out buildings before you have materials with buildingplan:

Ensure your screw pumps are magma-safe with just one click:

Control the quality of items used as materials:

Select which materials you want to build with:

Select specific items if you want to:

Symmetrical shapes with gui/dig:

The centerpiece feature of this release is buildingplan. We will be iterating on its design over the next few releases, but this first version is already useful, stable, and ready to help take some of the frustration out of building placement!

buildingplan lets you place furniture, constructions, and other buildings, regardless of whether the required materials are available. It attaches items as they become available and your dwarves build the buildings when they can. This allows you to focus purely on design elements when you are laying out your fort, and defers item production concerns to a more convenient time.

The buildingplan UI appears over the vanilla widgets when you choose a building type to build, and is intended to be a complete replacement for vanilla building placement. If you find that you just don't like it, you can turn the buildingplan.planner overlay off in gui/control-panel. Then please tell us why you don't like it so we can make it better : P

buildingplan also gives you a few more options when laying down constructions. You can choose the type of staircase that gets built at the top and bottom of a stair designation, for example. You can also choose to place hollow areas instead of solid, for example to easily surround a large area with a wall. It also allows you to place constructions over areas where some tiles cannot be built over. If you try to build a wall through a tree, for example, the tree tile will simply be skipped instead of blocking the entire wall.

buildingplan gives you whatever level of control you want over how materials are chosen to build your planned buildings:

• You can just click and place buildings and buildingplan will choose appropriate materials when they appear. No hassle, no worry.
• You can set filters for which materials are acceptable for each type of building you plan. Want your walls all made out of marble blocks? You can configure that with a few clicks, and buildingplan will only choose marble blocks to build those walls. Want to use only masterwork, decorated, gold tables for your monarch's dining hall? buildingplan can do that too.
• If you want, and if you have items already available, buildingplan can let you choose specific items for the building that you're planning. If you want a particular mix of weapons in your weapon trap, for example, you might want this level of control.
• If you are choosing specific items, buildingplan will also remember which materials you have chosen recently and put those items at the top of the list (by default) so you can easily find them again.

We have lots of plans for making buildingplan better and better, but we'd also love to hear your thoughts about how this version is working for you. Tell us here in this thread or join the "buildingplan feedback" discussion on the DFHack discord: https://dfhack.org/discord

See the full docs for buildingplan here: https://docs.dfhack.org/en/latest/docs/tools/buildingplan.html#buildingplan or just try it out in-game!

Also:

• dig-now now handles designations that have already been converted into active jobs, so you won't be left with an outline of undug tiles anymore. multi-level channeling is now properly handled as well.
• gui/dig now allows you to create free-form shapes, and can automatically mirror your lines to create symmetrical shapes
• stockpiles allows you to export and import stockpile configurations. This is an early version that only supports a commandline interface. UI integration is coming soon!

Fixes

• dig-now: fixed multi-layer channel designations only channeling every second layer
• gui/create-item: fix generic corpsepiece spawning
• dfhack.job.isSuitableMaterial: now properly detects lack of fire and magma safety for vulnerable materials with high melting points
• widgets.HotkeyLabel: don't trigger on click if the widget is disabled

Misc Improvements

• buildingplan: entirely new UI for building placement, item selection, and materials filtering!
• dig-now: added handling of dig designations that have been converted into active jobs
• gui/create-item: added ability to spawn 'whole' corpsepieces (every layer of a part)
• gui/dig:
  • Allow placing an extra point (curve) while still placing the second main point
  • Allow placing n-point shapes, shape rotation/mirroring
  • Allow second bezier point, mirror-mode for freeform shapes, symmetry mode

Removed

• automaterial: all functionality has been merged into buildingplan
• gui.THIN_FRAME: replaced by gui.INTERIOR_FRAME

API

• Gui focus strings will no longer get the "dfhack/" prefix if the string "dfhack/" already exists in the focus string
• Maps::GetBiomeTypeRef renamed to Maps::getBiomeTypeRef for consistency
• Maps::GetBiomeType renamed to Maps::getBiomeType for consistency
• Military:
  • New module for military functionality
  • new makeSquad to create a squad
  • changed getSquadName to take a squad identifier
  • new updateRoomAssignments for assigning a squad to a barracks and archery range

Lua

• dfhack.job.attachJobItem(): allows you to attach specific items to a job
• dfhack.screen.paintTile(): you can now explicitly clear the interface cursor from a map tile by passing 0 as the tile value
• gui.INTERIOR_FRAME: a panel frame style for use in highlighting off interior areas of a UI
• maps.getBiomeType: exposed preexisting function to Lua
• widgets.CycleHotkeyLabel: add label_below attribute for compact 2-line output
• widgets.FilteredList: search key matching is now case insensitive by default
• widgets.Label: token tile properties can now be functions that return a value

Structures

• history_eventst: Removed history_event_masterpiece_created_arch_designst and related enum value
• plot_infost.unk_8: renamed to theft_intrigues. Fields unk_1 thru unk_8 renamed to target_item, mastermind_hf, mastermind_plot_id, corruptor_hf, corruptor, corruptee_hf, corruptee, and theft_agreement. unk_1 renamed to item_known_pos.
• specific_ref_type: Removed BUILDING_PARTY, PETINFO_PET, and PETINFO_OWNER enum values to fix alignment.