Dfhack Documentation Release 0.44.05-R1
Total Page:16
File Type:pdf, Size:1020Kb
DFHack Documentation Release 0.44.05-r1 The DFHack Team 2018-02-05 Contents 1 Introduction 1 2 User Manual 3 2.1 Introduction and Overview........................................3 2.2 DFHack Core...............................................5 2.3 DFHack Plugins............................................. 12 2.4 DFHack Scripts............................................. 63 3 Other Contents 123 3.1 List of Authors.............................................. 123 3.2 Licenses................................................. 126 3.3 Changelog................................................ 128 3.4 Removed scripts............................................. 149 4 For Developers 151 4.1 How to contribute to DFHack...................................... 151 4.2 Compiling DFHack........................................... 155 4.3 Development Changelog......................................... 166 4.4 DFHack Lua API............................................. 174 4.5 Data Structure Definition Syntax..................................... 231 4.6 Updating DF-structures for a new DF version.............................. 249 4.7 Patching the DF binary.......................................... 256 i ii CHAPTER 1 Introduction DFHack is a Dwarf Fortress memory access library, distributed with a wide variety of useful scripts and plugins. The project is currently hosted at https://www.github.com/DFHack/dfhack, and can be downloaded from the releases page. All new releases are announced in the bay12 forums thread, which is also a good place for discussion and questions. For users, it 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 copyleft licences, contributions are welcome. 1 DFHack Documentation, Release 0.44.05-r1 2 Chapter 1. Introduction CHAPTER 2 User Manual 2.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 at https://www.github.com/DFHack/dfhack, and can be downloaded from the releases page. All new releases are announced in the bay12 forums thread, which is also a good place for discussion and questions. For users, it 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 copyleft licences, contributions are welcome. Contents • Introduction and Overview – Installing DFHack – Getting started – Troubleshooting 3 DFHack Documentation, Release 0.44.05-r1 2.1.1 Installing DFHack DFHack is available for the SDL version of Dwarf Fortress on Windows, any modern Linux distribution, and Mac OS X (10.6.8 and later). It is possible to use Windows DF+DFHack under Wine on Linux or OS X. Most releases only support the version of DF mentioned in their title - for example, DFHack 0.40.24-r2 only supports DF 0.40.24 - but some releases support earlier DF versions as well. Wherever possible, use the latest version of DFHack built for the target version of DF. Installing DFhack involves copying files from a release archive into your DF folder, so that: • On Windows, SDL.dll is replaced • On Linux or OS X, the dfhack script is placed in the same folder as the df script Uninstalling is basically the same, in reverse: • On Windows, replace SDL.dll with SDLreal.dll, then remove the DFHack files. • On Linux or OS X, remove the DFHack files. New players may wish to get a pack with DFHack preinstalled. 2.1.2 Getting started DFHack basically extends DF with something similar to the console found in many PC games. If DFHack is installed correctly, it will automatically pop up a console window once DF is started as usual on Windows. Linux and Mac OS X require running the dfhack script from the terminal, and will use that terminal for the console. • 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. 2.1.3 Troubleshooting Don’t panic! Even if you need this section, it’ll be OK :) If something goes wrong, check the log files in DF’s folder (stderr.log and stdout.log). Looking at these might help you - or someone else - solve the problem. Take screenshots of any weird error messages, and take notes on what you did to cause them. If the search function in this documentation isn’t enough and the DF Wiki hasn’t helped, try asking in: • the #dfhack IRC channel on freenode • the Bay12 DFHack thread • the /r/dwarffortress questions thread • the thread for the mod or Starter Pack you’re using (if any) 4 Chapter 2. User Manual DFHack Documentation, Release 0.44.05-r1 2.2 DFHack Core Contents • DFHack Core – Command Implementation – Using DFHack Commands – Built-in Commands – Init Files – Miscellaneous Notes 2.2.1 Command Implementation DFHack commands can be implemented in three ways, all of which are used in the same way: builtin commands are implemented by the core of DFHack. They manage other DFhack tools, interpret commands, and control basic aspects of DF (force pause or quit). plugins are stored in hack/plugins/ and must be compiled with the same version of DFHack. They are less flexible than scripts, but used for complex or ongoing tasks becasue they run faster. scripts are Ruby or Lua scripts stored in hack/scripts/. Because they don’t need to be compiled, scripts are more flexible about versions, and easier to distribute. Most third-party DFHack addons are scripts. 2.2.2 Using DFHack Commands DFHack commands can be executed in a number of ways: 1. Typing the command into the DFHack console (see below) 2. From the OS terminal (see below) 3. Pressing a key combination set up with keybinding 4. From one of several Init Files, automatically 5. Using script to run a batch of commands from a file The DFHack Console The command line has some nice line editing capabilities, including history that’s preserved between different runs of DF - use ↑ and ↓ to go through the history. To include whitespace in the argument/s to some command, quote it in double quotes. To include a double quote character, use \". If the first non-whitespace character is :, the command is parsed in an alternative mode. The non-whitespace characters following the : are the command name, and the remaining part of the line is used verbatim as the first argument. This is very useful for the lua and ruby commands. As an example, the following two command lines are exactly equivalent: 2.2. DFHack Core 5 DFHack Documentation, Release 0.44.05-r1 :foo a b"c d"ef foo"a b \"c d\" e f" Using an OS terminal DFHack commands can be run from an OS terminal at startup, using ‘+ args’, or at any other time using the dfhack-run executable. If DF/DFHack is started with arguments beginning with +, the remaining text is treated as a command in the DFHack console. It is possible to use multiple such commands, which are split on +. For example: ./dfhack +load-save region1 "Dwarf Fortress.exe" +devel/print-args Hello! +enable workflow The first example (*nix), load-save, skips the main menu and loads region1 immediately. The second (Windows) example prints Hello! in the DFHack console, and enables workflow. Note that the :foo syntax for whitespace in arguments is not compatible with ‘+ args’. If DF and DFHack are already running, calling dfhack-run my command in an external terminal is equivalent to calling my command in the DFHack console. Direct use of the DFhack console is generally easier, but dfhack-run can be useful in a variety of circumstances: • if the console is unavailable – with the init setting PRINT_MODE:TEXT – while running an interactive command (eg. liquids or tiletypes) • from external programs or scripts • if DF or DFHack are not responding Examples: ./dfhack-run cursecheck dfhack-run multicmd kill-lua; die The first (*nix) example checks for vampires; the second (Windows) example uses kill-lua to cancel a script and exits. 2.2.3 Built-in Commands The following commands are provided by the ‘core’ components of DFhack, rather than plugins or scripts. • alias • cls • die • enable • fpause • help • hide • keybinding 6 Chapter 2.