Dfhack Documentation Release 0.47.05-R3
Total Page:16
File Type:pdf, Size:1020Kb
DFHack Documentation Release 0.47.05-r3 The DFHack Team 2021-09-04 Contents I Quick Links3 II User Manual7 1 Introduction and Overview 9 2 Installing DFHack 11 3 Getting Support 15 4 DFHack Core 17 5 DFHack Plugins 27 6 DFHack Scripts 87 7 User Guides 193 8 About DFHack 247 9 DFHack Development Guide 299 i ii DFHack Documentation, Release 0.47.05-r3 DFHack is a memory editing library for Dwarf Fortress that provides a unified, cross-platform environment where tools can be developed to extend the game. The default distribution contains a variety of tools, including bugfixes, interface improvements, automation tools, modding tools, and more. There are also a variety of third-party tools available. Contents 1 DFHack Documentation, Release 0.47.05-r3 2 Contents Part I Quick Links 3 DFHack Documentation, Release 0.47.05-r3 • Downloads • Installation guide • Source code( important: read Compiling DFHack before attempting to build from source) • Bay 12 forums thread • Bug tracker 5 DFHack Documentation, Release 0.47.05-r3 6 Part II User Manual 7 CHAPTER 1 Introduction and Overview DFHack is a Dwarf Fortress memory access library, distributed with a wide variety of useful scripts and plugins. The project is currently hosted on GitHub, and can be downloaded from the releases page - see Installing DFHack for installation instructions. This is also where the DFHack bug tracker is hosted. All new releases are announced in the Bay12 forums thread, which is also a good place for discussion and questions. For users, DFHack provides a significant suite of bugfixes and interface enhancements by default, and more can be enabled. There are also many tools (such as workflow or autodump) which can make life easier. You can even add third-party scripts and plugins to do almost anything! For modders, DFHack makes many things possible. Custom reactions, new interactions, magic creature abilities, and more can be set through Scripts for Modders and custom raws. Non-standard DFHack scripts and inits can be stored in the raw directory, making raws or saves fully self-contained for distribution - or for coexistence in a single DF install, even with incompatible components. For developers, DFHack unites the various ways tools access DF memory and allows easier development of new tools. As an open-source project under various open-source licences, contributions are welcome. Contents • Getting started • Getting help 1.1 Getting started See Installing DFHack for details on installing DFHack. Once DFHack is installed, it extends DF with a console that can be used to run commands. On Windows, this console will open automatically when DF is started. On Linux and macOS, you will need to run the dfhack script from a terminal (instead of the df script included with DF), and that terminal will be used by the DFHack console. 9 DFHack Documentation, Release 0.47.05-r3 • Basic interaction with DFHack involves entering commands into the console. To learn what commands are available, you can keep reading this documentation or skip ahead and use the ls and help commands. • Another way to interact with DFHack is to set in-game keybindings for certain commands. Many of the newer and user-friendly tools are designed to be used this way. • Commands can also run at startup via init files, on in batches at other times with the script command. • Finally, some commands are persistent once enabled, and will sit in the background managing or changing some aspect of the game if you enable them. 1.2 Getting help There are several support channels available - see Getting Support for details. 10 Chapter 1. Introduction and Overview CHAPTER 2 Installing DFHack • Requirements – Windows – Linux – macOS • Downloading DFHack • Installing DFHack • Uninstalling DFHack • Upgrading DFHack • Pre-packaged DFHack installations • Linux packages 2.1 Requirements DFHack supports Windows, Linux, and macOS, and both 64-bit and 32-bit builds of Dwarf Fortress. DFHack releases generally only support the version of Dwarf Fortress that they are named after. For example, DFHack 0.40.24-r5 only supported DF 0.40.24. DFHack releases never support newer versions of DF, because DFHack requires data about DF that is only possible to obtain after DF has been released. Occasionally, DFHack releases will be able to maintain support for older versions of DF - for example, DFHack 0.34.11-r5 supported both DF 0.34.11 and 0.34.10. For maximum stability, you should usually use the latest versions of both DF and DFHack. 11 DFHack Documentation, Release 0.47.05-r3 2.1.1 Windows • DFHack only supports the SDL version of Dwarf Fortress. The “legacy” version will not work with DFHack (the “small” SDL version is acceptable, however). • Windows XP and older are not supported, due in part to a Visual C++ 2015 bug The Windows build of DFHack should work under Wine on other operating systems, although this is not tested very often. It is recommended to use the native build for your operating system instead. 2.1.2 Linux Generally, DFHack should work on any modern Linux distribution. There are multiple release binaries provided - as of DFHack 0.47.04-r1, there are built with GCC 7 and GCC 4.8 (as indicated by the gcc component of their filenames). Using the newest build that works on your system is recommended. The GCC 4.8 build is built on Ubuntu 14.04 and targets an older glibc, so it should work on older distributions. In the event that none of the provided binaries work on your distribution, you may need to compile DFHack from source. 2.1.3 macOS OS X 10.6.8 or later is required. 2.2 Downloading DFHack Stable builds of DFHack are available on GitHub. GitHub has been known to change their layout periodically, but as of July 2020, downloads are available at the bottom of the release notes for each release, under a section named “Assets” (which you may have to expand). The name of the file indicates which DF version, platform, and architecture the build supports - the platform and architecture (64-bit or 32-bit) must match your build of DF. The DF version should also match your DF version - see above for details. For example: • dfhack-0.47.04-r1-Windows-64bit.zip supports 64-bit DF on Windows • dfhack-0.47.04-r1-Linux-32bit-gcc-7.tar.bz2 supports 32-bit DF on Linux (see Linux for details on the GCC version indicator) The DFHack website also provides links to unstable builds. These files have a different naming scheme, but the same restrictions apply (e.g. a file named Windows64 is for 64-bit Windows DF). Warning: Do not download the source code from GitHub, either from the releases page or by clicking “Download ZIP” on the repo homepage. This will give you an incomplete copy of the DFHack source code, which will not work as-is. (If you want to compile DFHack instead of using a pre-built release, see Compiling DFHack for instructions.) 2.3 Installing DFHack When you download DFHack, you will end up with a release archive (a .zip file on Windows, or a .tar.bz2 file on other platforms). Your operating system should have built-in utilities capable of extracting files from these archives. 12 Chapter 2. Installing DFHack DFHack Documentation, Release 0.47.05-r3 The release archives contain several files and folders, including a hack folder, a dfhack-config folder, and a dfhack.init-example file. To install DFHack, copy all of the files from the DFHack archive into the root DF folder, which should already include a data folder and a raw folder, among other things. Some packs and other redistributions of Dwarf Fortress may place DF in another folder, so ensure that the hack folder ends up next to the data folder. Note: On Windows, installing DFHack will overwrite SDL.dll. This is intentional and necessary for DFHack to work, so be sure to choose to overwrite SDL.dll if prompted. (If you are not prompted, you may be installing DFHack in the wrong place.) 2.4 Uninstalling DFHack Uninstalling DFHack essentially involves reversing what you did to install DFHack. On Windows, replace SDL.dll with SDLreal.dll first. Then, you can remove any files that were part of the DFHack archive. DFHack does not currently maintain a list of these files, so if you want to completely remove them, you should consult the DFHack archive that you installed for a full list. Generally, any files left behind should not negatively affect DF. 2.5 Upgrading DFHack The recommended approach to upgrade DFHack is to uninstall DFHack first, then install the new version. This will ensure that any files that are only part of the older DFHack installation do not affect the new DFHack installation (although this is unlikely to occur). It is also possible to overwrite an existing DFHack installation in-place. To do this, follow the installation instructions above, but overwrite all files that exist in the new DFHack archive (on Windows, this includes SDL.dll again). Note: You may wish to make a backup of your dfhack-config folder first if you have made changes to it. Some archive managers (e.g. Archive Utility on macOS) will overwrite the entire folder, removing any files that you have added. 2.6 Pre-packaged DFHack installations There are several packs available that include DF, DFHack, and other utilities. If you are new to Dwarf Fortress and DFHack, these may be easier to set up. Note that these packs are not maintained by the DFHack team and vary in their release schedules and contents.