DFHack Core¶
Contents
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. |
Using DFHack Commands¶
DFHack commands can be executed in a number of ways:
- Typing the command into the DFHack console (see below)
- From the OS terminal (see below)
- Pressing a key combination set up with keybinding
- From one of several Init Files, automatically
- 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 rb commands.
As an example, the following two command lines are exactly equivalent:
:foo a b "c d" e f
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
- 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.
Built-in Commands¶
The following commands are provided by the ‘core’ components of DFhack, rather than plugins or scripts.
enable¶
Many plugins can be in a distinct enabled or disabled state. Some of them activate and deactivate automatically depending on the contents of the world raws. Others store their state in world data. However a number of them have to be enabled globally, and the init file is the right place to do it.
Most such plugins or scripts support the built-in enable
and disable
commands. Calling them at any time without arguments prints a list
of enabled and disabled plugins, and shows whether that can be changed
through the same commands.
To enable or disable plugins that support this, use their names as arguments for the command:
enable manipulator search
fpause¶
Forces DF to pause. This is useful when your FPS drops below 1 and you lose control of the game.
help¶
Most commands support using the help <command>
built-in command
to retrieve further help without having to look at this document.
? <cmd>
and man <cmd>
are aliases.
Some commands (including many scripts) instead take help
or ?
as an option on their command line - ie <cmd> help
.
keybinding¶
To set keybindings, use the built-in keybinding
command. Like any other
command it can be used at any time from the console, but bindings are not
remembered between runs of the game unless re-created in dfhack*.init.
Currently, any combinations of Ctrl/Alt/Shift with A-Z, 0-9, or F1-F12 are supported.
Possible ways to call the command:
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.
The <key>
parameter above has the following case-sensitive syntax:
[Ctrl-][Alt-][Shift-]KEY[@context[|context...]]
where the KEY part can be any recognized key 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.
when in context foo/bar/baz
, keybindings restricted to any of @foo/bar/baz
,
@foo/bar
, @foo
or none will be active.
Multiple contexts can be specified by separating them with a
pipe (|
) - for example, @foo|bar|baz/foo
would match
anything under @foo
, @bar
, or @baz/foo
.
Interactive commands like liquids cannot be used as hotkeys.
kill-lua¶
Stops any currently-running Lua scripts. By default, scripts can
only be interrupted every 256 instructions. Use kill-lua force
to interrupt the next instruction.
load¶
load
, unload
, and reload
control whether a plugin is loaded
into memory - note that plugins are loaded but disabled unless you do
something. Usage:
load|unload|reload PLUGIN|(-a|--all)
Allows dealing with plugins individually by name, or all at once.
ls¶
ls
does not list files like the Unix command, but rather
available commands - first built in commands, then plugins,
and scripts at the end. Usage:
ls -a: | Also list scripts in subdirectories of hack/scripts/ ,
which are generally not intended for direct use. |
---|---|
ls <plugin>: | List subcommands for the given plugin. |
plug¶
Lists available plugins, including their state and detailed description.
plug
- Lists available plugins (not commands implemented by plugins)
plug [PLUGIN] [PLUGIN] ...
- List state and detailed description of the given plugins, including commands implemented by the plugin.
sc-script¶
Allows additional scripts to be run when certain events occur (similar to onLoad*.init scripts)
script¶
Reads a text file, and runs each line as a DFHack command as if it had been typed in by the user - treating the input like an init file.
Some other tools, such as autobutcher and workflow, export
their settings as the commands to create them - which are later
loaded with script
show¶
Shows the terminal window after it has been hidden. Only available on Windows. You’ll need to use it from a keybinding set beforehand, or the in-game command-prompt.
Other Commands¶
The following commands are not built-in, but offer similarly useful functions.
Init Files¶
DFHack allows users to automatically run commonly-used DFHack commands when DF is first loaded, when a game is loaded, and when a game is unloaded.
Init scripts function the same way they would if the user manually typed in their contents, but are much more convenient. In order to facilitate savegave portability, mod merging, and general organization of init files, DFHack supports multiple init files both in the main DF directory and save-specific init files in the save folders.
DFHack looks for init files in three places each time they could be run:
- The main DF directory
data/save/world/raw
, whereworld
is the current save, anddata/save/world/raw/objects
When reading commands from dfhack.init or with the script command, if the final
character on a line is a backslash then the next uncommented line is considered a
continuation of that line, with the backslash deleted. Commented lines are skipped,
so it is possible to comment out parts of a command with the #
character.
dfhack*.init¶
If your DF folder contains at least one file named dfhack*.init
(where *
is a placeholder for any string), then all such files
are executed in alphabetical order when DF is first started.
DFHack is distributed with /dfhack.init-example
as an example
with an up-to-date collection of basic commands; mostly setting standard
keybindings and enabling plugins. You are encouraged to look
through this file to learn which features it makes available under which
key combinations. You may also customise it and rename it to dfhack.init
.
If your DF folder does not contain any dfhack*.init
files, the example
will be run as a fallback.
These files are best used for keybindings and enabling persistent plugins which do not require a world to be loaded.
onLoad*.init¶
When a world is loaded, DFHack looks for files of the form onLoad*.init
,
where *
can be any string, including the empty string.
All matching init files will be executed in alphebetical order. A world being loaded can mean a fortress, an adventurer, or legends mode.
These files are best used for non-persistent commands, such as setting a fix script to run on repeat.
onUnload*.init¶
When a world is unloaded, DFHack looks for files of the form onUnload*.init
.
Again, these files may be in any of the above three places.
All matching init files will be executed in alphebetical order.
Modders often use such scripts to disable tools which should not affect an unmodded save.
Other init files¶
onMapLoad*.init
andonMapUnload*.init
are run when a map, distinct from a world, is loaded. This is good for map-affecting commands (eg clean), or avoiding issues in Legends mode.- Any lua script named
raw/init.d/*.lua
, in the save or main DF directory, will be run when any world or that save is loaded.
Miscellaneous Notes¶
This section is for odd but important notes that don’t fit anywhere else.
- If a DF
H
hotkey is named with a DFHack command, pressing the correspondingFx
button will run that command, instead of zooming to the set location. This feature will be removed in a future version. (see Issue 731) - The binaries for 0.40.15-r1 to 0.34.11-r4 are on DFFD. Older versions are available here. These files will eventually be migrated to GitHub. (see Issue 473)