Building is fairly straightforward. Enter the ``build`` folder (or create an empty folder in the DFHack directory to use instead) and start the build like this::
Building is fairly straightforward. Enter the ``build`` folder (or create an
empty folder in the DFHack directory to use instead) and start the build like this::
If you have issues building on OS X Yosemite (or above), try definining the following environment variable::
If you have issues building on OS X Yosemite (or above), try definining the
following environment variable::
export MACOSX_DEPLOYMENT_TARGET=10.9
export MACOSX_DEPLOYMENT_TARGET=10.9
@ -227,9 +232,13 @@ Grab it from Microsoft's site.
You'll also need the Visual Studio 2010 SP1 update.
You'll also need the Visual Studio 2010 SP1 update.
For the code generation parts, you'll need perl with XML::LibXML and XML::LibXSLT. Strawberry Perl works nicely for this: http://strawberryperl.com/
For the code generation parts, you'll need perl with XML::LibXML and XML::LibXSLT.
`Strawberry Perl <http://strawberryperl.com>`_ works nicely for this.
If you already have a different version of perl (for example the one from cygwin), you can run into some trouble. Either remove the other perl install from PATH, or install libxml and libxslt for it instead. Strawberry perl works though and has all the required packages.
If you already have a different version of perl (for example the one from cygwin),
you can run into some trouble. Either remove the other perl install from PATH, or
install libxml and libxslt for it instead. Strawberry perl works though and has
@ -130,34 +130,52 @@ Other than through plugins, it is possible to use DFHack via remote access inter
The most important parts of DFHack are the Core, Console, Modules and Plugins.
The most important parts of DFHack are the Core, Console, Modules and Plugins.
* Core acts as the centerpiece of DFHack - it acts as a filter between DF and SDL and synchronizes the various plugins with DF.
* Core acts as the centerpiece of DFHack - it acts as a filter between DF and
SDL and synchronizes the various plugins with DF.
* Console is a thread-safe console that can be used to invoke commands exported by Plugins.
* Console is a thread-safe console that can be used to invoke commands exported by Plugins.
* Modules actually describe the way to access information in DF's memory. You can get them from the Core. Most modules are split into two parts: high-level and low-level. High-level is mostly method calls, low-level publicly visible pointers to DF's data structures.
* Modules actually describe the way to access information in DF's memory. You
* Plugins are the tools that use all the other stuff to make things happen. A plugin can have a list of commands that it exports and an onupdate function that will be called each DF game tick.
can get them from the Core. Most modules are split into two parts: high-level
and low-level. High-level is mostly method calls, low-level publicly visible
Rudimentary API documentation can be built using doxygen (see build options with ``ccmake`` or ``cmake-gui``).
pointers to DF's data structures.
* Plugins are the tools that use all the other stuff to make things happen.
A plugin can have a list of commands that it exports and an onupdate function
that will be called each DF game tick.
Rudimentary API documentation can be built using doxygen (see build options
with ``ccmake`` or ``cmake-gui``). The full DFHack documentation is built
with Sphinx, which runs automatically at compile time.
DFHack consists of variously licensed code, but invariably weak copyleft.
DFHack consists of variously licensed code, but invariably weak copyleft.
The main license is zlib/libpng, some bits are MIT licensed, and some are BSD licensed.
The main license is zlib/libpng, some bits are MIT licensed, and some are
BSD licensed. See the `license` document for more information.
Feel free to add your own extensions and plugins. Contributing back to
Feel free to add your own extensions and plugins. Contributing back to
the dfhack repository is welcome and the right thing to do :)
the dfhack repository is welcome and the right thing to do :)
DF data structure definitions
DF data structure definitions
-----------------------------
-----------------------------
DFHack uses information about the game data structures, represented via xml files
in the ``library/xml/`` submodule.
DFHack uses information about the game data structures, represented via xml files in the library/xml/ submodule.
See https://github.com/DFHack/df-structures, and the documentation linked in the index.
See https://github.com/DFHack/df-structures
Data structure layouts are described in files following the df.\*.xml name pattern. This information is transformed by a perl script into C++ headers describing the structures, and associated metadata for the Lua wrapper. These headers and data are then compiled into the DFHack libraries, thus necessitating a compatibility break every time layouts change; in return it significantly boosts the efficiency and capabilities of DFHack code.
Data structure layouts are described in files following the ``df.\*.xml`` name pattern.
This information is transformed by a perl script into C++ headers describing the
structures, and associated metadata for the Lua wrapper. These headers and data
are then compiled into the DFHack libraries, thus necessitating a compatibility
break every time layouts change; in return it significantly boosts the efficiency
and capabilities of DFHack code.
Global object addresses are stored in symbols.xml, which is copied to the dfhack release package and loaded as data at runtime.
Global object addresses are stored in ``symbols.xml``, which is copied to the dfhack
release package and loaded as data at runtime.
Remote access interface
Remote access interface
-----------------------
-----------------------
DFHack supports remote access by exchanging Google protobuf messages via a TCP socket. Both the core and plugins can define remotely accessible methods. The ``dfhack-run`` command uses this interface to invoke ordinary console commands.
DFHack supports remote access by exchanging Google protobuf messages via a TCP
socket. Both the core and plugins can define remotely accessible methods. The
``dfhack-run`` command uses this interface to invoke ordinary console commands.
Currently the supported set of requests is limited, because the developers don't know what exactly is most useful.
Currently the supported set of requests is limited, because the developers don't
``remotefortressreader`` provides a fairly comprehensive interface for visualisers such as Armok Vision.
know what exactly is most useful. ``remotefortressreader`` provides a fairly
comprehensive interface for visualisers such as Armok Vision.
Installing DFhack involves copying files into your DF folder.
Installing DFhack involves copying files into your DF folder.
Copy the files from a release archive so that:
Copy the files from a release archive so that:
* On Windows, SDL.dll is replaced
* On Windows, ``SDL.dll`` is replaced
* On Linux, the 'dfhack' script is placed in the same folder as the 'df' script
* On Linux or OSX, the ``dfhack`` script is placed in the same folder as the ``df`` script
Uninstalling is basically the same, in reverse:
Uninstalling is basically the same, in reverse:
* On Windows, first delete SDL.dll and rename SDLreal.dll to SDL.dll. Then
* On Windows, first delete ``SDL.dll`` and rename ``SDLreal.dll`` to ``SDL.dll``,
remove the other DFHack files
then remove the other DFHack files
* On Linux, Remove the DFHack files.
* On Linux, remove the DFHack files.
The stonesense plugin might require some additional libraries on Linux.
The stonesense plugin might require some additional libraries on Linux.
If any of the plugins or dfhack itself refuses to load, check the stderr.log
If any of the plugins or dfhack itself refuses to load, check the ``stderr.log``
file created in your DF folder.
file created in your DF folder.
@ -71,7 +71,7 @@ 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
running the dfhack script from the terminal, and will use that terminal for
the console.
the console.
**NOTE**: The dfhack-run executable is there for calling DFHack commands in
**NOTE**: The ``dfhack-run`` executable is there for calling DFHack commands in
an already running DF+DFHack instance from external OS scripts and programs,
an already running DF+DFHack instance from external OS scripts and programs,
and is *not* the way how you use DFHack normally.
and is *not* the way how you use DFHack normally.
@ -86,18 +86,16 @@ called ``dfhack.init``; the installation comes with an example version called
features and can be simply renamed to ``dfhack.init``. You are encouraged to look
features and can be simply renamed to ``dfhack.init``. You are encouraged to look
through it to learn which features it makes available under which key combinations.
through it to learn which features it makes available under which key combinations.
For more information, refer to the rest of this document.
Using DFHack
Using DFHack
============
============
DFHack basically extends what DF can do with something similar to the drop-down
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
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
window. On Linux, the terminal used to launch the dfhack script is taken over
(so, make sure you start from a terminal). Basic interaction with dfhack
(so, make sure you start from a terminal). Basic interaction with dfhack
involves entering commands into the console. For some basic instructions,
involves entering commands into the console. For some basic instructions,
use the 'help' command. To list all possible commands, use the 'ls' command.
use the ``help`` command. To list all possible commands, use the ``ls`` command.
Many commands have their own help or detailed description. You can use
Many commands have their own help or detailed description. You can use
'command help' or 'command ?' to show that.
``command help`` or ``command ?`` to show that.
The command line has some nice line editing capabilities, including history
The command line has some nice line editing capabilities, including history
that's preserved between different runs of DF (use up/down keys to go through
that's preserved between different runs of DF (use up/down keys to go through
@ -105,17 +103,21 @@ the history).
The second way to interact with DFHack is to bind the available commands
The second way to interact with DFHack is to bind the available commands
to in-game hotkeys. The old way to do this is via the hotkey/zoom menu (normally
to in-game hotkeys. The old way to do this is via the hotkey/zoom menu (normally
opened with the 'h' key). Binding the commands is done by assigning a command as
opened with the ``h`` key). Binding the commands is done by assigning a command as
a hotkey name (with 'n').
a hotkey name (with ``n``).
A new and more flexible way is the keybinding command in the dfhack console.
A new and more flexible way is the keybinding command in the dfhack console.
However, bindings created this way are not automatically remembered between runs
However, bindings created this way are not automatically remembered between runs
of the game, so it becomes necessary to use the dfhack.init file to ensure that
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.
they are re-created every time it is loaded.
Interactive commands like 'liquids' cannot be used as hotkeys.
Interactive commands like `plugins/liquids` cannot be used as hotkeys.
Most of the commands come from plugins. Those reside in 'hack/plugins/'.
Many commands come from plugins, which are stored in ``hack/plugins/``
and must be compiled with the same version of DFHack. Others come
from scripts, which are stored in ``hack/scripts``. Scripts are much
more flexible about versions, and easier to distribute - so most third-party
DFHack addons are scripts.
Something doesn't work, help!
Something doesn't work, help!
=============================
=============================
@ -151,27 +153,44 @@ The following two command lines are exactly equivalent::
This is intended for commands like ``rb_eval`` that evaluate script language statements.
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
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,
to retrieve further help without having to look at this document. Alternatively,
some accept a 'help'/'?' option on their command line.
some accept a ``help`` or ``?`` as an option on their command line.
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. If your DF folder contains at least one file with a name
following the format ``dfhack*.init`` where ``*`` is a placeholder for any string (including
the empty string), then all such files are executed in alphabetical order as init scripts when
DF is first loaded.
If your DF folder does not contain any such files, then DFHack will execute ``dfhack.init-example``
as an example of useful commands to be run automatically. If you want DFHack to do nothing on
its own, then create an empty ``dfhack.init`` file in the main DF directory, or delete ``dfhack.init-example``.
The file ``dfhack.init-example`` is included as an example for users to follow if they need DFHack
command executed automatically. We recommend modifying or deleting ``dfhack.init-example`` as
its settings will not be optimal for all players.
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.
The init file
=============
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.
If your DF folder contains at least one file with a name following the format ``dfhack*.init`` where ``*`` is a placeholder for any string (including the empty string), then all such files are executed in alphabetical order as init scripts when DF is first loaded.
If your DF folder does not contain any such files, then DFHack will execute ``dfhack.init-example`` as an example of useful commands to be run automatically.
If you want DFHack to do nothing on its own, then create an empty ``dfhack.init`` file in the main DF directory, or delete ``dfhack.init-example``.
The file ``dfhack.init-example`` is included as an example for users to follow if they need DFHack command executed automatically.
We highly recommend modifying or deleting ``dfhack.init-example`` as its settings will not be optimal for all players.
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.
DFHack looks for init files in three places.
It will look for them in the main DF directory, and in ``data/save/_____/raw`` and ``data/save/_____/raw/objects`` where ``_____`` is the name of the current savegame.
When a game is loaded, DFHack looks for files of the form ``onLoad*.init``, where ``*`` can be any string, including the empty string.
It will look for them in the main DF directory, and in ``data/save/_____/raw`` and
When a game is unloaded, DFHack looks for files of the form ``onUnload*.init``.
``data/save/_____/raw/objects`` where ``_____`` is the name of the current savegame.
Again, these files may be in any of the above three places.
All matching init files will be sorted and executed in alphebetical order.
When a game is loaded, DFHack looks for files of the form ``onLoad*.init``, where
``*`` can be any string, including the empty string.
When a game 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.
Setting keybindings
Setting keybindings
===================
===================
@ -192,22 +211,22 @@ Possible ways to call the command:
``keybinding set <key> "cmdline" "cmdline"...``
``keybinding set <key> "cmdline" "cmdline"...``
Clear, and then add bindings for the specified key.
Clear, and then add bindings for the specified key.
The *<key>* parameter above has the following *case-sensitive* syntax::
The ``<key>`` parameter above has the following *case-sensitive* syntax::
[Ctrl-][Alt-][Shift-]KEY[@context[|context...]]
[Ctrl-][Alt-][Shift-]KEY[@context[|context...]]
where the *KEY* part can be any recognized key and [] denote optional parts.
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
When multiple commands are bound to the same key combination, DFHack selects
the first applicable one. Later 'add' commands, and earlier entries within one
the first applicable one. Later ``add`` commands, and earlier entries within one
'add' command have priority. Commands that are not specifically intended for use
``add`` command have priority. Commands that are not specifically intended for use
as a hotkey are always considered applicable.
as a hotkey are always considered applicable.
The *context* part in the key specifier above can be used to explicitly restrict
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 UI state where the binding would be applicable. If called without parameters,
the ``keybinding`` command among other things prints the current context string.
the ``keybinding`` command among other things prints the current context string.
Only bindings with a *context* tag that either matches the current context fully,
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.
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``,
for context ``foo/bar/baz``, possible matches are any of ``@foo/bar/baz``, ``@foo/bar``,
``@foo`` or none. Multiple contexts can be specified by separating them with a
``@foo`` or none. Multiple contexts can be specified by separating them with a
PeridexisErrant