<p>On Windows, DFHack replaces the SDL library distributed with DF.</p>
<p>On Windows, DFHack replaces the SDL library distributed with DF.</p>
<divclass="section"id="id1">
<divclass="section"id="id1">
<h2><aclass="toc-backref"href="#id11">How to get the code</a></h2>
<h2><aclass="toc-backref"href="#id12">How to get the code</a></h2>
<p>DFHack doesn't have any kind of system of code snapshots in place, so you will have to get code from the github repository using git.
<p>DFHack doesn't have any kind of system of code snapshots in place, so you will have to get code from the github repository using git.
You will need some sort of Windows port of git, or a GUI. Some examples:</p>
You will need some sort of Windows port of git, or a GUI. Some examples:</p>
<blockquote>
<blockquote>
@ -511,13 +569,14 @@ git submodule update
<p>If you want to get really involved with the development, create an account on github, make a clone there and then use that as your remote repository instead. Detailed instructions are beyond the scope of this document. If you need help, join us on IRC (#dfhack channel on freenode).</p>
<p>If you want to get really involved with the development, create an account on github, make a clone there and then use that as your remote repository instead. Detailed instructions are beyond the scope of this document. If you need help, join us on IRC (#dfhack channel on freenode).</p>
<p>It has the usual installer wizard. Make sure you let it add its binary folder
<p>It has the usual installer wizard. Make sure you let it add its binary folder
to your binary search PATH so the tool can be later run from anywhere.</p>
to your binary search PATH so the tool can be later run from anywhere.</p>
<p>You'll need a copy of Microsoft Visual C++ 2010. The Express version is sufficient.
<p>You'll need a copy of Microsoft Visual C++ 2010. The Express version is sufficient.
Grab it from Microsoft's site.</p>
Grab it from Microsoft's site.</p>
<p>You'll also need the Visual Studio 2010 SP1 update.</p>
<p>For the code generation parts, you'll need perl and XML::LibXML. You can install them like this:</p>
<p>For the code generation parts, you'll need perl and XML::LibXML. You can install them like this:</p>
<ulclass="simple">
<ulclass="simple">
<li>download and install strawberry perl from <aclass="reference external"href="http://strawberryperl.com/">http://strawberryperl.com/</a></li>
<li>download and install strawberry perl from <aclass="reference external"href="http://strawberryperl.com/">http://strawberryperl.com/</a></li>
@ -528,7 +587,7 @@ Grab it from Microsoft's site.</p>
<p>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.</p>
<p>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.</p>
<p>There are several different batch files in the <ttclass="docutils literal">build</tt> folder along with a script that's used for picking the DF path.</p>
<p>There are several different batch files in the <ttclass="docutils literal">build</tt> folder along with a script that's used for picking the DF path.</p>
<p>First, run set_df_path.vbs and point the dialog that pops up at your DF folder that you want to use for development.
<p>First, run set_df_path.vbs and point the dialog that pops up at your DF folder that you want to use for development.
Next, run one of the scripts with <ttclass="docutils literal">generate</tt> prefix. These create the MSVC solution file(s):</p>
Next, run one of the scripts with <ttclass="docutils literal">generate</tt> prefix. These create the MSVC solution file(s):</p>
@ -550,7 +609,7 @@ So pick either Release or RelWithDebInfo build and build the INSTALL target.</p>
<h2><aclass="toc-backref"href="#id16">DF data structure definitions</a></h2>
<h2><aclass="toc-backref"href="#id17">DF data structure definitions</a></h2>
<p>DFHack uses information about the game data structures, represented via xml files in the library/xml/ submodule.</p>
<p>DFHack uses information about the game data structures, represented via xml files in the library/xml/ submodule.</p>
<p>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.</p>
<p>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.</p>
<p>Global object addresses are stored in symbols.xml, which is copied to the dfhack release package and loaded as data at runtime.</p>
<p>Global object addresses are stored in symbols.xml, which is copied to the dfhack release package and loaded as data at runtime.</p>
<p>DFHack supports remote access by exchanging Google protobuf messages via a TCP socket. Both the core and plugins can define remotely accessible methods. The <ttclass="docutils literal"><spanclass="pre">dfhack-run</span></tt> command uses this interface to invoke ordinary console commands.</p>
<p>DFHack supports remote access by exchanging Google protobuf messages via a TCP socket. Both the core and plugins can define remotely accessible methods. The <ttclass="docutils literal"><spanclass="pre">dfhack-run</span></tt> command uses this interface to invoke ordinary console commands.</p>
<p>Currently the supported set of requests is limited, because the developers don't know what exactly is most useful.</p>
<p>Currently the supported set of requests is limited, because the developers don't know what exactly is most useful.</p>
<p>Protocol client implementations exist for Java and C#.</p>
<p>Protocol client implementations exist for Java and C#.</p>
</div>
</div>
<divclass="section"id="contributing-to-dfhack">
<divclass="section"id="contributing-to-dfhack">
<h2><aclass="toc-backref"href="#id18">Contributing to DFHack</a></h2>
<h2><aclass="toc-backref"href="#id19">Contributing to DFHack</a></h2>
<p>Several things should be kept in mind when contributing to DFHack.</p>
<p>Several things should be kept in mind when contributing to DFHack.</p>
<p>Returns a list of tables describing noble position assignments, or <em>nil</em>.
<p>Returns a list of tables describing noble position assignments, or <em>nil</em>.
Every table has fields <ttclass="docutils literal">entity</tt>, <ttclass="docutils literal">assignment</tt> and <ttclass="docutils literal">position</tt>.</p>
Every table has fields <ttclass="docutils literal">entity</tt>, <ttclass="docutils literal">assignment</tt> and <ttclass="docutils literal">position</tt>.</p>
@ -1904,6 +1942,10 @@ Returns: <em>step_idx, sum_idx, found_ptr</em>, or <em>nil</em> if not found.</p
The oldval, newval or delta arguments may be used to specify additional constraints.
The oldval, newval or delta arguments may be used to specify additional constraints.
Returns: <em>found_index</em>, or <em>nil</em> if end reached.</p>
Returns: <em>found_index</em>, or <em>nil</em> if end reached.</p>
@ -28,15 +28,15 @@ All new releases are announced in the bay12 thread: http://tinyurl.com/dfhack-ng
=============
=============
Compatibility
Compatibility
=============
=============
DFHack works on Windows XP, Vista, 7 or any modern Linux distribution.
DFHack works on Windows XP, Vista, 7, any modern Linux distribution, or OS X
OSX is not supported due to lack of developers with a Mac.
10.6.8-10.9.
Currently, version 0.34.11 is supported (and tested). If you need DFHack
Currently, version 0.34.11 is supported (and tested). If you need DFHack
for older versions, look for older releases.
for older versions, look for older releases.
On Windows, you have to use the SDL version of DF.
On Windows, you have to use the SDL version of DF.
It is possible to use the Windows DFHack under wine/OSX.
It is also possible to use the Windows DFHack with Wine under Linux and OS X.
====================
====================
Installation/Removal
Installation/Removal
@ -329,6 +329,13 @@ Options:
The building must be one of stockpile, workshop, furnace, trap,
The building must be one of stockpile, workshop, furnace, trap,
siege engine or an activity zone.
siege engine or an activity zone.
command-prompt
--------------
A one line command prompt in df. Same as entering command into dfhack console. Best
used as a keybinding. Can be called with optional "entry" that will start prompt with
that pre-filled.
..image:: images/command-prompt.png
Adventure mode
Adventure mode
==============
==============
@ -489,7 +496,7 @@ Options:
createitem
createitem
----------
----------
Allows creating new items of arbitrary types and made of arbitrary materials.
Allows creating new items of arbitrary types and made of arbitrary materials.
Any items created are spawned at the feet of the selected unit.
By default, items created are spawned at the feet of the selected unit.
Specify the item and material information as you would indicate them in custom reaction raws, with the following differences:
Specify the item and material information as you would indicate them in custom reaction raws, with the following differences:
* Separate the item and material with a space rather than a colon
* Separate the item and material with a space rather than a colon
@ -506,6 +513,14 @@ Examples:
``createitem FISH FISH_SHAD:MALE 5``
``createitem FISH FISH_SHAD:MALE 5``
Create a stack of 5 cleaned shad, ready to eat.
Create a stack of 5 cleaned shad, ready to eat.
To change where new items are placed, first run the command with a destination type while an appropriate destination is selected.
Options:
:floor:Subsequent items will be placed on the floor beneath the selected unit's feet.
:item:Subsequent items will be stored inside the currently selected item.
:building:Subsequent items will become part of the currently selected building. Best used for loading traps; do not use with workshops, or you will need to deconstruct the building to use the item.
deramp (by zilpin)
deramp (by zilpin)
------------------
------------------
Removes all ramps designated for removal from the map. This is useful for replicating the old channel digging designation.
Removes all ramps designated for removal from the map. This is useful for replicating the old channel digging designation.
@ -676,29 +691,39 @@ tile. Can be used from a hotkey.
tubefill
tubefill
--------
--------
Fills all the adamantine veins again. Veins that were empty will be filled in
Fills all the adamantine veins again. Veins that were hollow will be left
too, but might still trigger a demon invasion (this is a known bug).
alone.
extirpate
---------
A tool for getting rid of trees and shrubs. By default, it only kills
a tree/shrub under the cursor. The plants are turned into ashes instantly.
Options:
Options:
:hollow:fill in naturally hollow veins too
Beware that filling in hollow veins will trigger a demon invasion on top of
your miner when you dig into the region that used to be hollow.
plant
-----
A tool for creating shrubs, growing, or getting rid of them.
Subcommands:
:create:Create a new shrub/sapling.
:grow:Make saplings grow into trees.
:extirpate:Kills trees and shrubs, turning them into ashes instantly.
:immolate:Similar to extirpate, but sets the plants on fire instead. The fires can and *will* spread ;)
``create`` creates a new sapling under the cursor. Takes a raw ID as
argument (e.g. TOWER_CAP). The cursor must be located on a dirt or grass
floor tile.
``grow`` works on the sapling under the cursor, and turns it into a tree.
Works on all shrubs of the map if the cursor is hidden.
``extirpate`` and ``immolate`` work only on the plant under the cursor.
For mass effects, use one of the additional options:
:shrubs:affect all shrubs on the map
:shrubs:affect all shrubs on the map
:trees:affect all trees on the map
:trees:affect all trees on the map
:all:affect every plant!
:all:affect every plant!
grow
----
Makes all saplings present on the map grow into trees (almost) instantly.
immolate
--------
Very similar to extirpate, but additionally sets the plants on fire. The fires
can and *will* spread ;)
regrass
regrass
-------
-------
Regrows grass. Not much to it ;)
Regrows grass. Not much to it ;)
@ -1959,6 +1984,21 @@ Usage:
:misery disable:stop adding new negative thoughts. This will not remove existing duplicated thoughts. Equivalent to "misery 1"
:misery disable:stop adding new negative thoughts. This will not remove existing duplicated thoughts. Equivalent to "misery 1"
:misery clear:remove fake thoughts added in this session of DF. Saving makes them permanent! Does not change factor.
:misery clear:remove fake thoughts added in this session of DF. Saving makes them permanent! Does not change factor.
strangemood
-----------
Creates a strange mood job the same way the game itself normally does it.
Options:
:-force:Ignore normal strange mood preconditions (no recent mood, minimum moodable population, artifact limit not reached).
:-unit:Make the strange mood strike the selected unit instead of picking one randomly. Unit eligibility is still enforced.
:-type T:Force the mood to be of a particular type instead of choosing randomly based on happiness.
Valid values are "fey", "secretive", "possessed", "fell", and "macabre".
:-skill S:Force the mood to use a specific skill instead of choosing the highest moodable skill.
Known limitations: if the selected unit is currently performing a job, the mood will not be started.
=======
=======
Scripts
Scripts
=======
=======
@ -2009,6 +2049,13 @@ Scripts in this subdirectory fix various bugs and issues, some of them obscure.
every time a save game is loaded; putting ``fix/cloth-stockpile enable``
every time a save game is loaded; putting ``fix/cloth-stockpile enable``
in ``dfhack.init`` makes it run automatically.
in ``dfhack.init`` makes it run automatically.
* fix/build-location
Fixes construction jobs that are stuck trying to build a wall while standing
on the same exact tile (bug 5991), designates the tile restricted traffic to
hopefully avoid jamming it again, and unsuspends them.
gui/*
gui/*
=====
=====
@ -2092,6 +2139,9 @@ With the special argument ``him``, targets only the selected creature.
With the special argument ``undead``, targets all undeads on the map,
With the special argument ``undead``, targets all undeads on the map,
regardless of their race.
regardless of their race.
When specifying a race, a caste can be specified to further restrict the
targeting. To do that, append and colon and the caste name after the race.
Any non-dead non-caged unit of the specified race gets its ``blood_count``
Any non-dead non-caged unit of the specified race gets its ``blood_count``
set to 0, which means immediate death at the next game tick. For creatures
set to 0, which means immediate death at the next game tick. For creatures
such as vampires, it also sets animal.vanish_countdown to 2.
such as vampires, it also sets animal.vanish_countdown to 2.
@ -2107,6 +2157,7 @@ but ignore caged/chained creatures.
Ex::
Ex::
exterminate gob
exterminate gob
exterminate gob:male
To kill a single creature, select the unit with the 'v' cursor and::
To kill a single creature, select the unit with the 'v' cursor and::
@ -2171,7 +2222,12 @@ Unrecognized characters are ignored (eg the 'skip this tile' in the sample).
Empty lines and data after a ``#`` are ignored as comments.
Empty lines and data after a ``#`` are ignored as comments.
To skip a row in your design, use a single ``;``.
To skip a row in your design, use a single ``;``.
The script takes the plan filename, starting from the root df folder.
One comment in the file may contain the phrase ``start(3,5)``. It is interpreted
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.
The script takes the plan filename, starting from the root df folder (where
Dwarf Fortress.exe is found).
invasion-now
invasion-now
============
============
@ -2185,6 +2241,7 @@ Triggers an invasion, or several in the near future.
`invasion-now civName start end` trigger an invasion from civName in about 10*start ticks, and continue triggering invasions every ten ticks afterward until about 10*end ticks have passed
`invasion-now civName start end` trigger an invasion from civName in about 10*start ticks, and continue triggering invasions every ten ticks afterward until about 10*end ticks have passed
Probably fails if the start time of a triggered invasion is later than the start of the next year.
Probably fails if the start time of a triggered invasion is later than the start of the next year.
digmat
digmat
======
======
Designates a tile for digging. Monitors the tile, and when it is dug out, add
Designates a tile for digging. Monitors the tile, and when it is dug out, add
@ -2357,12 +2414,16 @@ are mostly implemented by lua scripts.
As an exception, the tweak plugin described above does not follow this
As an exception, the tweak plugin described above does not follow this
guideline because it arguably just fixes small usability bugs in the game UI.
guideline because it arguably just fixes small usability bugs in the game UI.
All of these tools are disabled by default - in order to make them available,
you must enable the plugins which provide them.
Dwarf Manipulator
Dwarf Manipulator
=================
=================
Implemented by the manipulator plugin. To activate, open the unit screen and
Implemented by the 'manipulator' plugin.
press 'l'.
To activate, open the unit screen and press 'l'.
..image:: images/manipulator.png
..image:: images/manipulator.png
@ -2412,6 +2473,8 @@ directly to the main dwarf mode screen.
Search
Search
======
======
Implemented by the 'search' plugin.
The search plugin adds search to the Stocks, Animals, Trading, Stockpile,
The search plugin adds search to the Stocks, Animals, Trading, Stockpile,
Noble (assignment candidates), Military (position candidates), Burrows
Noble (assignment candidates), Military (position candidates), Burrows
(unit list), Rooms, Announcements, Job List and Unit List screens.
(unit list), Rooms, Announcements, Job List and Unit List screens.
@ -2452,9 +2515,11 @@ using Permit Fats again while the list is filtered.
AutoMaterial
AutoMaterial
============
============
The automaterial plugin makes building constructions (walls, floors, fortifications,
Implemented by the 'automaterial' plugin.
etc) a little bit easier by saving you from having to trawl through long lists of
materials each time you place one.
This makes building constructions (walls, floors, fortifications, etc) a little bit
easier by saving you from having to trawl through long lists of materials each time
you place one.
Firstly, it moves the last used material for a given construction type to the top of
Firstly, it moves the last used material for a given construction type to the top of
the list, if there are any left. So if you build a wall with chalk blocks, the next
the list, if there are any left. So if you build a wall with chalk blocks, the next
@ -2585,6 +2650,16 @@ Rationale: individual choice seems to be unreliable when there is a weapon short
and may lead to inappropriate weapons being selected.
and may lead to inappropriate weapons being selected.
gui/clone-uniform
=================
Bind to a key (the example config uses Ctrl-C), and activate in the Uniforms
page of the military screen with the cursor in the leftmost list.
When invoked, the script duplicates the currently selected uniform template,
and selects the newly created copy.
gui/guide-path
gui/guide-path
==============
==============
@ -2739,7 +2814,7 @@ of currently assigned racks for every valid squad.
gui/advfort
gui/advfort
=============
===========
This script allows to perform jobs in adventure mode. For more complete help
This script allows to perform jobs in adventure mode. For more complete help
press '?' while script is running. It's most confortable to use this as a
press '?' while script is running. It's most confortable to use this as a
@ -2754,22 +2829,31 @@ keybinding. (e.g. keybinding set Ctrl-T gui/advfort). Possible arguments:
* job - selects that job (e.g. Dig or FellTree)
* job - selects that job (e.g. Dig or FellTree)
An example of player digging in adventure mode:
..image:: images/advfort.png
..admonition:: DISCLAIMER
advfort changes only persist in non procedural sites. Namely: player forts, caves, camps.
gui/companion-order
gui/companion-order
=======================
===================
A script to issue orders for companions. Select companions with lower case chars, issue orders with upper
A script to issue orders for companions. Select companions with lower case chars, issue orders with upper
case. Must be in look or talk mode to issue command on tile.
case. Must be in look or talk mode to issue command on tile.
..image:: images/companion-order.png
* move - orders selected companions to move to location. If companions are following they will move no more than 3 tiles from you.
* move - orders selected companions to move to location. If companions are following they will move no more than 3 tiles from you.
* equip - try to equip items on the ground.
* equip - try to equip items on the ground.
* pick-up - try to take items into hand (also wield)
* pick-up - try to take items into hand (also wield)
* unequip - remove and drop equipment
* unequip - remove and drop equipment
* unwield - drop held items
* unwield - drop held items
* wait - temporarely remove from party
* wait - temporarily remove from party
* follow - rejoin the party after "wait"
* follow - rejoin the party after "wait"
* leave - remove from party (can be rejoined by talking)
* leave - remove from party (can be rejoined by talking)
gui/gm-editor
gui/gm-editor
=============
=============
@ -2779,14 +2863,26 @@ There are three ways to open this editor:
or viewed (e.g. unit/item description screen)
or viewed (e.g. unit/item description screen)
* using gui/gm-editor <lua command> - executes lua command and opens editor on
* using gui/gm-editor <lua command> - executes lua command and opens editor on
it's results (e.g. gui/gm-editor "df.global.world.items.all" shows all items)
its results (e.g. gui/gm-editor "df.global.world.items.all" shows all items)
* using gui/gm-editor dialog - shows an in game dialog to input lua command. Works
* using gui/gm-editor dialog - shows an in game dialog to input lua command. Works
the same as version above.
the same as version above.
..image:: images/gm-editor.png
This editor allows to change and modify almost anything in df. Press '?' for an
This editor allows to change and modify almost anything in df. Press '?' for an
in-game help.
in-game help.
gui/mod-manager
===============
A way to simply install and remove small mods. It looks for specially formated mods in
df subfolder 'mods'. Mods are not included, for example mods see: `github mini mod repository <https://github.com/warmist/df-mini-mods>`_
Japa
