If you belong here and are missing, please add yourself and send me (peterix) a pull request :-)
+The following is a list of people who have contributed to DFHack.
+And those are the cool people who made stonesense.
+DFHack is a Dwarf Fortress memory access library and a set of basic tools that use it. Tools come in the form of plugins or (not yet) external tools. It is an attempt to unite the various ways tools @@ -326,253 +334,222 @@ access DF memory and allow for easier development of new tools.
Contents
The project is currently hosted on github, for both source and binaries at http://github.com/peterix/dfhack
Releases can be downloaded from here: https://github.com/peterix/dfhack/downloads
All new releases are announced in the bay12 thread: http://tinyurl.com/dfhack-ng
DFHack works on Windows XP, Vista, 7 or any modern Linux distribution. OSX is not supported due to lack of developers with a Mac.
-Currently, versions 0.34.08 - 0.34.11 are supported. If you need DFHack +
Currently, version 0.34.11 is supported (and tested). If you need DFHack for older versions, look for older releases.
On Windows, you have to use the SDL version of DF.
It is possible to use the Windows DFHack under wine/OSX.
Installing DFhack involves copying files into your DF folder. Copy the files from a release archive so that:
@@ -594,7 +571,7 @@ remove the other DFHack files file created in your DF folder.
DFHack basically extends what DF can do with something similar to the drop-down console found in Quake engine games. On Windows, this is a separate command line window. On linux, the terminal used to launch the dfhack script is taken over @@ -616,9 +593,37 @@ of the game, so it becomes necessary to use the dfhack.init file to ensure that they are re-created every time it is loaded.
Interactive commands like 'liquids' cannot be used as hotkeys.
Most of the commands come from plugins. Those reside in 'hack/plugins/'.
+On linux and OSX, users of patched binaries may have to find the relevant +section in symbols.xml, and add a new line with the checksum of their +executable:
++<md5-hash value='????????????????????????????????'/> ++
In order to find the correct value of the hash, look into stderr.log; +DFHack prints an error there if it does not recognize the hash.
+DFHack includes a small stand-alone utility for applying and removing +binary patches from the game executable. Use it from the regular operating +system console:
++++
+- +
binpatch check "Dwarf Fortress.exe" patch.dif
+Checks and prints if the patch is currently applied.
+- +
binpatch apply "Dwarf Fortress.exe" patch.dif
+Applies the patch, unless it is already applied or in conflict.
+- +
binpatch remove "Dwarf Fortress.exe" patch.dif
+Removes the patch, unless it is already removed.
+
The patches are expected to be encoded in text format used by IDA.
+First, don't panic :) Second, dfhack keeps a few log files in DF's folder
- stderr.log and stdout.log. You can look at those and possibly find out what's
happening.
@@ -627,24 +632,181 @@ the issues tracker on github, contact me (
- If your DF folder contains a file named dfhack.init, its contents will be run
+ If your DF folder contains a file named dfhack.init, its contents will be run
every time you start DF. This allows setting up keybindings. An example file
-is provided as dfhack.init-example - you can tweak it and rename to dfhack.init
+is provided as dfhack.init-example - you can tweak it and rename to dfhack.init
if you want to use this functionality. To set keybindings, use the built-in keybinding command. Like any other
+command it can be used at any time from the console, but it is also meaningful
+in the DFHack init file. Currently it supports any combination of Ctrl/Alt/Shift with F1-F9, or A-Z. Possible ways to call the command: The <key> parameter above has the following case-sensitive syntax: where the KEY part can be F1-F9 or A-Z, and [] denote optional parts. When multiple commands are bound to the same key combination, DFHack selects
+the first applicable one. Later 'add' commands, and earlier entries within one
+'add' command have priority. Commands that are not specifically intended for use
+as a hotkey are always considered applicable. The context part in the key specifier above can be used to explicitly restrict
+the UI state where the binding would be applicable. If called without parameters,
+the keybinding command among other things prints the current context string.
+Only bindings with a context tag that either matches the current context fully,
+or is a prefix ending at a '/' boundary would be considered for execution, i.e.
+for context foo/bar/baz, possible matches are any of @foo/bar/baz, @foo/bar,
+@foo or none.The init file
-The init file
+Setting keybindings
+
+
+keybinding list <key>: List bindings active for the key combination.
+keybinding clear <key> <key>...: Remove bindings for the specified keys.
+keybinding add <key> "cmdline" "cmdline"...: Add bindings for the specified
+key.
+keybinding set <key> "cmdline" "cmdline"...: Clear, and then add bindings for
+the specified key.
+
+[Ctrl-][Alt-][Shift-]KEY[@context]
+
+
DFHack command syntax consists of a command name, followed by arguments separated +by whitespace. To include whitespace in an argument, quote it in double quotes. +To include a double quote character, use \" inside double quotes.
+If the first non-whitespace character of a line is #, the line is treated +as a comment, i.e. a silent no-op command.
+If the first non-whitespace character is :, the command is parsed in a special +alternative mode: first, non-whitespace characters immediately following the : +are used as the command name; the remaining part of the line, starting with the first +non-whitespace character after the command name, is used verbatim as the first argument. +The following two command lines are exactly equivalent:
++++
+- :foo a b "c d" e f
+- foo "a b \"c d\" e f"
+
This is intended for commands like rb_eval that evaluate script language statements.
Almost all the commands support using the 'help <command-name>' built-in command to retrieve further help without having to look at this document. Alternatively, some accept a 'help'/'?' option on their command line.
+Instantly kills DF without saving.
+Forces DF to pause. This is useful when your FPS drops below 1 and you lose +control of the game.
++++
+- Activate with 'forcepause 1'
+- Deactivate with 'forcepause 0'
+
Disables pausing (both manual and automatic) with the exception of pause forced +by 'reveal hell'. This is nice for digging under rivers.
+Controls speedydwarf and teledwarf. Speedydwarf makes dwarves move quickly and perform tasks quickly. Teledwarf makes dwarves move instantaneously, but do jobs at the same speed.
++++
+- 'fastdwarf 0 0' disables both
+- 'fastdwarf 0 1' disables speedydwarf and enables teledwarf
+- 'fastdwarf 1 0' enables speedydwarf and disables teledwarf
+- 'fastdwarf 1 1' enables both
+- 'fastdwarf 0' disables both
+- 'fastdwarf 1' enables speedydwarf and disables teledwarf
+- 'fastdwarf 2 ...' sets a native debug flag in the game memory +that implements an even more aggressive version of speedydwarf.
+
Makes the game view follow the currently highlighted unit after you exit from +current menu/cursor mode. Handy for watching dwarves running around. Deactivated +by moving the view manually.
+Toggle between all possible positions where the idlers count can be placed.
+Toggle between displaying/not displaying liquid depth as numbers.
+Copies the parameters of the currently highlighted stockpile to the custom +stockpile settings and switches to custom stockpile placement mode, effectively +allowing you to copy/paste stockpiles easily.
+Allows renaming various things.
+Options:
++++
++ + + + rename squad <index> "name": + Rename squad by index to 'name'. ++ rename hotkey <index> "name": + Rename hotkey by index. This allows assigning +longer commands to the DF hotkeys. ++ rename unit "nickname": + Rename a unit/creature highlighted in the DF user +interface. ++ rename unit-profession "custom profession": + Change proffession name of the +highlighted unit/creature. ++ rename building "name": + + Set a custom name for the selected building. +The building must be one of stockpile, workshop, furnace, trap, +siege engine or an activity zone. +
This allows taking control over your followers and other creatures in adventure mode. For example, you can make them pick up new arms and armor and equip them properly.
-Usage:
- When viewing unit details, body-swaps into that unit.
@@ -652,12 +814,11 @@ properly.
Changes material of the geology layer under cursor to the specified inorganic RAW material. Can have impact on all surrounding regions, not only your embark! By default changing stone to soil and vice versa is not allowed. By default @@ -687,8 +851,8 @@ as well, though. Mineral veins and gem clusters will stay on the map. Use 'changevein' for them.
tl;dr: You will end up with changing quite big areas in one go, especially if you use it in lower z levels. Use with care.
- -Examples:
++
- changelayer GRANITE
- Convert layer at cursor position into granite.
@@ -731,6 +895,7 @@ soil.- changelayer MARBLE all_biomes all_layers
- Convert all layers of all biomes which are not soil into marble.
Note
Changes material of the vein under cursor to the specified inorganic RAW material. Only affects tiles within the current 16x16 block - for veins and large clusters, you will need to use this command multiple times.
-Example:
+-
- changevein NATIVE_PLATINUM
- Convert vein at cursor position into platinum ore.
Allows changing item material and base quality. By default the item currently selected in the UI will be changed (you can select items in the 'k' list or inside containers/inventory). By default change is only allowed if materials @@ -774,8 +938,8 @@ with 'force'. Note that some attributes will not be touched, possibly resulting in weirdness. To get an idea how the RAW id should look like, check some items with 'info'. Using 'force' might create items which are not touched by crafters/haulers.
- -Examples:
++
- changeitem m INORGANIC:GRANITE here
- Change material of all items under the cursor to granite.
- changeitem q 5
- Change currently selected item to masterpiece quality.
Checks a single map tile or the whole map/world for cursed creatures (ghosts, -vampires, necromancers, werebeasts, zombies).
-With an active in-game cursor only the selected tile will be observed. -Without a cursor the whole map will be checked.
-By default cursed creatures will be only counted in case you just want to find -out if you have any of them running around in your fort. Dead and passive -creatures (ghosts who were put to rest, killed vampires, ...) are ignored. -Undead skeletons, corpses, bodyparts and the like are all thrown into the curse -category "zombie". Anonymous zombies and resurrected body parts will show -as "unnamed creature".
-Allows listing all the vermin colonies on the map and optionally turning them into honey bee colonies.
+Options:
++
- - detail: Print full name, date of birth, date of curse and some status -info (some vampires might use fake identities in-game, though). -- nick: Set the type of curse as nickname (does not always show up -in-game, some vamps don't like nicknames). -- all: Include dead and passive cursed creatures (can result in a quite -long list after having FUN with necromancers). -verbose: Print all curse tags (if you really want to know it all). +bees: turn colonies into honey bee colonies
Note
-Makes the game view follow the currently highlighted unit after you exit from -current menu/cursor mode. Handy for watching dwarves running around. Deactivated -by moving the view manually.
+Removes all ramps designated for removal from the map. This is useful for replicating the old channel digging designation. +It also removes any and all 'down ramps' that can remain after a cave-in (you don't have to designate anything for that to happen).
Forces DF to pause. This is useful when your FPS drops below 1 and you lose -control of the game.
-