Installation instructions here: https://docs.dfhack.org/en/latest/docs/Installing.html#installing

Quickstart guide here: https://docs.dfhack.org/en/latest/docs/Quickstart.html#quickstart

This release requires the Steam version of DF (see below)

Hi all! We know there has been a lot of excitement around this release of DFHack, so we want to start by setting some expectations. This is an alpha release. This means that:

• 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, there WILL be bugs.
• Most 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.
• 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.

Note that DF's "manual" and "timeline" saves are buggy at the moment, and you should instead copy the entire save directory to somewhere else on your hard drive. Alternately, you can copy the entire DF directory somewhere else, install DFHack in that directory, and keep it completely separate from your Steam installation.

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.

Also note that this release only supports the Steam version of DF due to some technical limitations. You don't have to run it through Steam, but it does require DF to be downloaded from Steam. We're hoping that a future version of DF will resolve these technical limitations, and we plan to support all builds (including Itch and Classic) by the time we reach a stable release of DFHack.

What's new

DFHack has significantly advanced from the days of DF 0.47.05. There is a much greater focus on allowing you to do everything from inside the game, not requiring you to open the external terminal window to run commands or go to the web to look up syntax documentation. More and more tools have graphical configuration screens, and most of those screens have full mouse integration (though keyboard-only setups are still fully supported where DF itself allows).

As soon as you start up DF with DFHack installed, the first thing you're likely to notice is the DFHack logo in the upper left of the screen. If you move your mouse over the logo, a panel will pop up showing you a list of DFHack tools that are relevant to the current screen. If you're wondering "what can I do with DFHack right now", open this panel and find out. DFHack's "context detection" code has not been fully updated for the new version of DF, so the list of tools in the popup menu is very short right now. However, this list will expand greatly over the next few releases of DFHack.

The first thing you should do is hover over the DFHack logo and select the quickstart guide (hotkey: ?). This will go into more depth about how to use DFHack than the quick notes I'm adding here.

The main interface for running DFHack tools in-game is gui/launcher. It will always be first in the DFHack logo popup list for easy access. It has integrated help for all tools, showing you the usage syntax, real-world examples, and other useful information. It also allows you to autocomplete partially-typed commands and pull commandlines you have run before out of your history to run again.

DFHack windows have also progressed significantly. They are now draggable, resizable, and pinnable. For example, you can bring up gui/autochop, configure your desired log stock levels, minimize the window, pin it, and drag it off to the side of the screen to leave it up as a live status report for your logging industry. The quickstart guide walks you through exactly how to do this.

There are also many changes in the DFHack tools themselves -- too many to mention. We can just suggest that you go exploring!

So which tools are available?

You can get live updates and see which tools have been tested here: https://docs.google.com/spreadsheets/d/1hiDlo8M_bB_1jE-5HRs2RrrA_VZ4cRu9VXaTctX_nwk/edit#gid=1774645373

Is your favorite tool not tested yet? Vote for it here: https://strawpoll.com/polls/poy9R95NwnJ

Here's are some of the more popular tools that are available now (even with the small percentage of tools that are tested, it's still a long list):

autobutcher and the gui/autobutcher config frontend - automatically butcher excess livestock
autochop (and the gui/autochop config frontend) - automatically designate trees for chopping
autofarm - automatically select crops for planting
ban-cooking - keep your chefs from cooking ingredients that are useful for other things
blueprint (and the gui/blueprint point and click interface) - record the design of your fortress
clean - remove contaminants
cleanowned - force dwarves to drop tattered clothing and go get new clothing
cursecheck - check for cursed creatures
deathcause - find out the cause of death by selecting a corpse or body part
dig-now - fulfill dig designations instantly
drain-aquifer - dry out all aquifers on the map
fastdwarf - make your dwarves super speedy
fix/stable-temp - speed up the game by allowing temperature calculations to quickly find equilibrium
gui/gm-editor - general game memory editor
gui/gm-unit - general unit property editor
gui/launcher - in-game DFHack command launcher with integrated help and autocomplete
gui/pathable - show which tiles are reachable from the selected position
gui/quickcmd - customizable list of favorite DFHack commands
lever - interact with levers (including pulling them with the "hand of Armok")
list-agreements - show which temples and guildhalls you have agreed to build
locate-ore - find ores of specific types on the map
migrants-now - attempt to spawn a migrant wave asap
nestboxes - protect fertile eggs in nestboxes from being gathered and eaten
orders - import, export, and sort manager orders
overlay (and the gui/overlay config frontend) - configure DFHack informational and widget overlays
prioritize - get your dwarves to actually do important jobs (like food hauling)
quickfort (and the gui/quickfort point and click interface) - apply blueprints to your map
quicksave - force the game to save now
quickstart-guide (check this out!) - get new DFHack players oriented
regrass - regrow all grass on the map
remove-stress - calm unhappy dwarves
reveal - reveal map tiles (note that you have to switch into ASCII mode to see underground tiles)
seedwatch - protect your seeds from being cooked when you need them for planting
showmood - explain what a dwarf is looking for for their strange mood project
source - create liquid sources and sinks
stonesense - show the map in 3d
tame - tame wild animals
tiletypes - redraw the map with tiles of your choice
unforbid - remove the "forbidden" flag from items
unsuspend - resume suspended building jobs, also visually marks suspended buildings on the map
warn-starving - warns you when your animals and dwarves are starving or dehydrated
weather - control the weather
workorder - generate manager orders

Hopefully that will be enough to get you started : p

DFHack 50.05-alpha1

New Scripts

• allneeds: list all unmet needs sorted by how many dwarves suffer from them.
• devel/tile-browser: page through available textures and see their texture ids
• gui/autochop: configuration frontend for the autochop plugin. you can pin the window and leave it up on the screen somewhere for live monitoring of your logging industry.

Fixes

• make-legendary: "MilitaryUnarmed" option now functional
• widgets.WrappedLabel: no longer resets scroll position when window is moved or resized

Misc Improvements

• Scrollable widgets now react to mouse wheel events when the mouse is over the widget
• the dfhack-config/scripts/ folder is now searched for scripts by default
• autounsuspend: now saves its state with your fort
• devel/inspect-screen: updated for new rendering semantics and can now also inspect map textures
• emigration: now saves its state with your fort
• gui/cp437-table: converted to a movable, mouse-enabled window
• gui/gm-editor: converted to a movable, resizable, mouse-enabled window
• gui/gm-unit: converted to a movable, resizable, mouse-enabled window
• gui/launcher:
  • now supports a smaller, minimal mode. click the toggle in the launcher UI or start in minimal mode via the Ctrl-Shift-P keybinding
  • can now be dragged from anywhere on the window body
  • now remembers its size and position between invocations
• gui/quickcmd:
  • converted to a movable, resizable, mouse-enabled window
  • commands are now stored globally so you don't have to recreate commands for every fort
• hotkeys: overlay hotspot widget now shows the DFHack logo in graphics mode and "DFHack" in text mode
• prioritize: now saves its state with your fort
• script-paths: removed "raw" directories from default script paths. now the default locations to search for scripts are dfhack-config/scripts, save/*/scripts, and hack/scripts
• unsuspend:
  • overlay now displays different letters for different suspend states so they can be differentiated in graphics mode (P=planning, x=suspended, X=repeatedly suspended)
  • overlay now shows a marker all the time when in graphics mode. ascii mode still only shows when paused so that you can see what's underneath.
• init.d: directories have moved from the raw subfolder (which no longer exists) to the root of the main DF folder or a savegame folder

Removed

• Ruby is no longer a supported DFHack scripting language
• fix-job-postings from the workflow plugin is now obsolete since affected savegames can no longer be loaded

API

• Gui::getDFViewscreen: returns the topmost underlying DF viewscreen
• Gui::getDwarfmodeDims: now only returns map viewport dimensions; menu dimensions are obsolete
• Screen::Pen: now accepts keep_lower and write_to_lower properties to support foreground and background textures in graphics mode

Lua

• Removed os.execute() and io.popen() built-in functions
• overlay: OverlayWidget now inherits from Panel instead of Widget to get all the frame and mouse integration goodies
• dfhack.gui.getDFViewscreen(): returns the topmost underlying DF viewscreen
• gui.CLEAR_PEN: now clears the background and foreground and writes to the background (before it would always write to the foreground)
• gui.KEEP_LOWER_PEN: a general use pen that writes associated tiles to the foreground while keeping the existing background
• gui.View:
  • visible and active can now be functions that return a boolean
  • new function view:getMouseFramePos() for detecting whether the mouse is within (or over) the exterior frame of a view
• gui.ZScreen: Screen subclass that implements window raising, multi-viewscreen input handling, and viewscreen event pass-through so the underlying map can be interacted with and dragged around while DFHack screens are visible
• widgets.CycleHotkeyLabel:
  • now supports rendering option labels in the color of your choice
  • new functions setOption() and getOptionPen()
• widgets.Label: tiles can now have an associated width
• widgets.Panel: new attributes to control window dragging and resizing with mouse or keyboard
• widgets.ToggleHotkeyLabel: now renders the On option in green text
• widgets.Window: Panel subclass with attributes preset for top-level windows

Structures

• Renamed globals to match DF:
  • ui: renamed to plotinfo
  • ui_advmode: renamed to adventure
  • ui_build_selector: renamed to buildreq
  • ui_sidebar_menus: renamed to game
• building_civzonest: identify two variables, dir_x and dir_y, that handle archery range direction.

Documentation

• added DFHack architecture diagrams to the dev intro
• added DFHack Quickstart guide
• devel/hello-world: updated to be a better example from which to start new gui scripts
• overlay-dev-guide: added troubleshooting tips and common development workflows