$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
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
@ -17,6 +17,61 @@ If you're not comfortable pregramming, you can help by:
All those things are crucial, and all under-represented. So if that's
All those things are crucial, and all under-represented. So if that's
your thing, the rest of this document is about contributing code - go get started!
your thing, the rest of this document is about contributing code - go get started!
Documentation Standards
=======================
Whether you're adding new code or just fixing old documentation (and there's plenty),
there are a few important standards for completeness and consistent style. Treat
this section as a guide rather than iron law, match the surrounding text, and you'll
be fine.
Every script, plugin, or command should be documented. This is an active project,
and the best place to put this documentation might change. For now, it's usually
either ``docs/Scripts.rst`` or ``docs/Plugins.rst``.
Where the heading for a section is also the name of a command, the spelling
and case should exactly match the command to enter in the DFHack command line.
Try to keep lines within 80-100 characters, so it's readable in plain text -
Sphinx (our documentation system) will make sure paragraphs flow.
If there aren't many options or examples to show, they can go in a paragraph of
text. Use double-backticks to put commands in monospaced font, like this::
You can use ``cleanall scattered x`` to dump tattered or abandoned items.
If the command takes more than three arguments, format the list as a table
called Options. The table *only* lists arguments, not full commands.
Input values are specified in angle brackets. Example::
Options:
:arg1:A simple argument.
:arg2 <input>:Does something based on the input value.
:Very long argument:
Is very specific.
To demonstrate usage - useful mainly when the syntax is complicated, list the
full command with arguments in monospaced font, then indent the next line and
describe the effect::
``resume all``
Resumes all suspended constructions.
If it would be helpful to mention another DFHack command, don't just type the
name - add a hyperlink! Specify the link target in backticks, and it will be
replaced with the corresponding title and linked: eg ```plugins/autolabor```
=> `plugins/autolabor`. Link targets should be the path to the file
described (without file extension), and placed above the heading of that
section like this::
.._plugins/autolabor:
autolabor
=========
Add link targets if you need them, but otherwise plain headings are preferred.
Contributing Code
Contributing Code
=================
=================
Several things should be kept in mind when contributing code to DFHack.
Several things should be kept in mind when contributing code to DFHack.
@ -46,6 +101,8 @@ How to get new code into DFHack
* Work done against Github issues tagged "bug report" get priority
* Work done against Github issues tagged "bug report" get priority
* Submit ideas and bug reports as issues on Github. Posts in the forum thread can easily get missed or forgotten.
* Submit ideas and bug reports as issues on Github. Posts in the forum thread can easily get missed or forgotten.
.._contributing-memory-research:
Memory research
Memory research
---------------
---------------
If you want to do memory research, you'll need some tools and some knowledge.
If you want to do memory research, you'll need some tools and some knowledge.
@ -70,39 +127,58 @@ Using the library as a developer
Currently, the most direct way to use the library is to write a script or plugin that can be loaded by it.
Currently, the most direct way to use the library is to write a script or plugin that can be loaded by it.
All the plugins can be found in the 'plugins' folder. There's no in-depth documentation
All the plugins can be found in the 'plugins' folder. There's no in-depth documentation
on how to write one yet, but it should be easy enough to copy one and just follow the pattern.
on how to write one yet, but it should be easy enough to copy one and just follow the pattern.
``plugins/skeleton/skeleton.cpp`` is provided for this purpose.
Other than through plugins, it is possible to use DFHack via remote access interface, or by writing Lua scripts.
Other than through plugins, it is possible to use DFHack via remote access interface, or by writing Lua scripts.
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.
DFHack command syntax consists of a command name, followed by arguments separated
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.
by whitespace. To include whitespace in an argument, quote it in double quotes.
To include a double quote character, use ``\"`` inside double quotes.
To include a double quote character, use ``\"`` inside double quotes.
@ -137,8 +143,10 @@ To include a double quote character, use ``\"`` inside double quotes.
If the first non-whitespace character of a line is ``#``, the line is treated
If the first non-whitespace character of a line is ``#``, the line is treated
as a comment, i.e. a silent no-op command.
as a comment, i.e. a silent no-op command.
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.
When reading commands from dfhack.init or with the ``script`` command, if the final
Commented lines are skipped, so it is possible to comment out parts of a command with the ``#`` character.
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.
If the first non-whitespace character is ``:``, the command is parsed in a special
If the first non-whitespace character is ``:``, the command is parsed in a special
alternative mode: first, non-whitespace characters immediately following the ``:``
alternative mode: first, non-whitespace characters immediately following the ``:``
@ -151,27 +159,52 @@ 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.
..note::
Some tools work by displaying dialogs or overlays in the game window.
In order to avoid confusion, these tools display the word "DFHack" while active. If they
merely add keybinding hints to existing screens, they use red instead of green for the key.
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 +225,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
pipe (``|``) - for example, ``@foo|bar|baz/foo``.
pipe (``|``) - for example, ``@foo|bar|baz/foo``.
@ -221,6 +254,11 @@ Opens an in-game screen showing DFHack keybindings that are active in the curren
Type ``hotkeys`` into the DFHack console to open the screen, or bind the command to a
Type ``hotkeys`` into the DFHack console to open the screen, or bind the command to a
globally active hotkey. The default keybinding is ``Ctrl-F1``.
globally active hotkey. The default keybinding is ``Ctrl-F1``.
In-game Console
===============
The ``command-prompt`` plugin adds an in-game DFHack terminal, where you
can enter other commands. It's default keybinding is Ctrl-Shift-P.
Enabling plugins
Enabling plugins
================
================
Many plugins can be in a distinct enabled or disabled state. Some of
Many plugins can be in a distinct enabled or disabled state. Some of
@ -240,15 +278,6 @@ arguments for the command::
enable manipulator search
enable manipulator search
In-game interface tools
=======================
Some tools work by displaying dialogs or overlays in the game window.
In order to avoid user confusion, as a matter of policy all these tools
must display the word "DFHack" on the screen somewhere while active.
When that is not appropriate because they merely add keybinding hints to
existing DF screens, they deliberately use red instead of green for the key.
Game progress
Game progress
=============
=============
@ -275,31 +304,3 @@ nopause
Disables pausing (both manual and automatic) with the exception of pause forced
Disables pausing (both manual and automatic) with the exception of pause forced
by 'reveal hell'. This is nice for digging under rivers.
by 'reveal hell'. This is nice for digging under rivers.
Patched binaries
================
As an alternative to permanently modifying the binary, you can use the
``binpatch`` dfhack command to apply patches live in memory during a DF session.
In this case, updating symbols.xml is not necessary - otherwise 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::
the version appropriate for the currently loaded executable.
brainwash
brainwash
=========
=========
@ -702,6 +734,8 @@ dfusion
=======
=======
Interface to a lecacy script system.
Interface to a lecacy script system.
.._scripts/digfort:
digfort
digfort
=======
=======
A script to designate an area for digging according to a plan in csv format.
A script to designate an area for digging according to a plan in csv format.
@ -726,18 +760,22 @@ as an offset for the pattern: instead of starting at the cursor, it will start
3 tiles left and 5 tiles up from the cursor.
3 tiles left and 5 tiles up from the cursor.
The script takes the plan filename, starting from the root df folder (where
The script takes the plan filename, starting from the root df folder (where
Dwarf Fortress.exe is found).
``Dwarf Fortress.exe`` is found).
drain-aquifer
drain-aquifer
=============
=============
Remove all 'aquifer' tag from the map blocks. Irreversible.
Remove all 'aquifer' tag from the map blocks. Irreversible.
.._scripts/elevate-mental:
elevate-mental
elevate-mental
==============
==============
Set all mental attributes of a dwarf to 2600, which is very high.
Set all mental attributes of a dwarf to 2600, which is very high.
Other numbers can be passed as an argument: ``elevate-mental 100``
Other numbers can be passed as an argument: ``elevate-mental 100``
for example would make the dwarf very stupid indeed.
for example would make the dwarf very stupid indeed.
.._scripts/elevate-physical:
elevate-physical
elevate-physical
================
================
As for elevate-mental, but for physical traits. High is good for soldiers,
As for elevate-mental, but for physical traits. High is good for soldiers,
@ -802,6 +840,8 @@ fixnaked
========
========
Removes all unhappy thoughts due to lack of clothing.
Removes all unhappy thoughts due to lack of clothing.
.._scripts/fix-ster:
fix-ster
fix-ster
========
========
Utilizes the orientation tag to either fix infertile creatures or inflict
Utilizes the orientation tag to either fix infertile creatures or inflict
@ -863,7 +903,7 @@ Lists the key, name, and jump position of your hotkeys in the DFHack console.
item-descriptions
item-descriptions
=================
=================
Exports a table with custom description text for every item in the game.
Exports a table with custom description text for every item in the game.
Used by ``view-item-info``.
Used by `scripts/view-item-info`.
lever
lever
=====
=====
@ -897,7 +937,10 @@ Examples::
log-region
log-region
==========
==========
When enabled in dfhack.init, each time a fort is loaded identifying information will be written to the gamelog. Assists in parsing the file if you switch between forts, and adds information for story-building.
When enabled in dfhack.init, each time a fort is loaded identifying information
will be written to the gamelog. Assists in parsing the file if you switch
between forts, and adds information for story-building.
lua
lua
===
===
There are the following ways to invoke this command:
There are the following ways to invoke this command:
@ -988,7 +1031,26 @@ normally used in seasonal auto-save.
region-pops
region-pops
===========
===========
Show or modify the populations of animals in the region. Use ``region-pops`` for details.
Show or modify the populations of animals in the region.
Usage:
:region-pops list [pattern]:
Lists encountered populations of the region, possibly restricted by pattern.
:region-pops list-all [pattern]:
Lists all populations of the region.
:region-pops boost <TOKEN> <factor>:
Multiply all populations of TOKEN by factor.
If the factor is greater than one, increases the
population, otherwise decreases it.
:region-pops boost-all <pattern> <factor>:
Same as above, but match using a pattern acceptable to list.
:region-pops incr <TOKEN> <factor>:
Augment (or diminish) all populations of TOKEN by factor (additive).
:region-pops incr-all <pattern> <factor>:
Same as above, but match using a pattern acceptable to list.
.._scripts/rejuvenate:
rejuvenate
rejuvenate
==========
==========
@ -1005,6 +1067,8 @@ remove-wear
===========
===========
Sets the wear on all items in your fort to zero.
Sets the wear on all items in your fort to zero.
.._scripts/repeat:
repeat
repeat
======
======
Repeatedly calls a lua script at the specified interval.
Repeatedly calls a lua script at the specified interval.
@ -1034,8 +1098,22 @@ combat in slow motion or something :)
show-unit-syndromes
show-unit-syndromes
===================
===================
Show syndromes affecting units and the remaining and maximum duration, along
Show syndromes affecting units and the remaining and maximum duration, along
with (optionally) substantial detail on the effects. Call
with (optionally) substantial detail on the effects.
``show-unit-syndromes help`` for further options.
Use one or more of the following options:
:showall:Show units even if not affected by any syndrome
:showeffects:Show detailed effects of each syndrome
:showdisplayeffects:Show effects that only change the look of the unit
:ignorehiddencurse:Hide syndromes the user should not be able to know about (TODO)
lethosor