<p>On Windows, DFHack replaces the SDL library distributed with DF.</p>
<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.
You will need some sort of Windows port of git, or a GUI. Some examples:</p>
<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>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>
<p>You'll need a copy of Microsoft Visual C++ 2010. The Express version is sufficient.
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>
<ulclass="simple">
<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>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.
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>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>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>Protocol client implementations exist for Java and C#.</p>
</div>
<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>
<h1><aclass="toc-backref"href="#id1">DF data structure wrapper</a></h1>
<p>DF structures described by the xml files in library/xml are exported
to lua code as a tree of objects and functions under the <ttclass="docutils literal">df</tt> global,
which broadly maps to the <ttclass="docutils literal">df</tt> namespace in C++.</p>
<h1><aclass="toc-backref"href="#id3">DF data structure wrapper</a></h1>
<p>Data structures of the game are defined in XML files located in library/xml
(and online at <aclass="reference external"href="http://github.com/DFHack/df-structures">http://github.com/DFHack/df-structures</a>), and automatically exported
to lua code as a tree of objects and functions under the <ttclass="docutils literal">df</tt> global, which
also broadly maps to the <ttclass="docutils literal">df</tt> namespace in the headers generated for C++.</p>
<p><strong>WARNING</strong>: The wrapper provides almost raw access to the memory
of the game, so mistakes in manipulating objects are as likely to
crash the game as equivalent plain C++ code would be. E.g. NULL
@ -485,7 +491,7 @@ both nested types and fields corresponding to global symbols.</p>
<p>In addition to the <ttclass="docutils literal">global</tt> object and top-level types the <ttclass="docutils literal">df</tt>
global also contains a few global builtin utility functions.</p>
<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>
@ -1321,7 +1368,7 @@ or raws. The <tt class="docutils literal">ignore_noble</tt> boolean disables the
<p>A number of lua modules with names starting with <ttclass="docutils literal">gui</tt> are dedicated
to wrapping the natives of the <ttclass="docutils literal">dfhack.screen</tt> module in a way that
is easy to use. This allows relatively easily and naturally creating
@ -2322,12 +2382,12 @@ dialogs that integrate in the main game UI window.</p>
things ranging from the basic <ttclass="docutils literal">Painter</tt>, <ttclass="docutils literal">View</tt> and <ttclass="docutils literal">Screen</tt>
classes, to fully functional predefined dialogs.</p>
<h3><aclass="toc-backref"href="#id58">Events from EventManager</a></h3>
<h3><aclass="toc-backref"href="#id60">Events from EventManager</a></h3>
<p>These events are straight from EventManager module. Each of them first needs to be enabled. See functions for more info. If you register a listener before the game is loaded, be aware that no events will be triggered immediately after loading, so you might need to add another event listener for when the game first loads in some cases.</p>
<p>Enable event checking for EventManager events. For event types use <ttclass="docutils literal">eventType</tt> table. Note that different types of events require different frequencies to be effective. The frequency is how many ticks EventManager will wait before checking if that type of event has happened. If multiple scripts or plugins use the same event type, the smallest frequency is the one that is used, so you might get events triggered more often than the frequency you use here.</p>
<p>Enable callback when sidebar for <ttclass="docutils literal">shop_name</tt> is drawn. Usefull for custom workshop views e.g. using gui.dwarfmode lib.</p>
<dt><ttclass="docutils literal">registerBuilding(table)</tt> where table must contain name, as a workshop raw name, the rest are optional:</dt>
<dd><olclass="first last arabic simple">
<li>name -- custom workshop id e.g. <ttclass="docutils literal">SOAPMAKER</tt></li>
<li>fix_impassible -- if true make impassible tiles impassible to liquids too</li>
<li>consume -- how much machine power is needed to work. Disables reactions if not supplied enough</li>
<li>produce -- how much machine power is produced. Use discouraged as there is no way to change this at runtime</li>
<li>gears -- a table or <ttclass="docutils literal"><spanclass="pre">{x=?,y=?}</span></tt> of connection points for machines</li>
<li>action -- a table of number (how much ticks to skip) and a function which gets called on shop update</li>
<li>animate -- a table of frames which can be a table of:<olclass="loweralpha">
<li>tables of 4 numbers <ttclass="docutils literal">{tile,fore,back,bright}</tt> OR</li>
<li>empty table (tile not modified) OR</li>
<li><ttclass="docutils literal"><spanclass="pre">{x=<number></span><spanclass="pre">y=<number></span> + 4 numbers like in first case}</tt>, this generates full frame useful for animations that change little (1-2 tiles)</li>
</ol>
</li>
</ol>
</dd>
<dt>Animate table also might contain:</dt>
<dd><olclass="first last arabic simple">
<li>frameLenght -- how many ticks does one frame take OR</li>
<li>isMechanical -- a bool that says to try to match to mechanical system (i.e. how gears are turning)</li>
Calculates the base value for an item of the specified type and material.
* ``dfhack.items.getValue(item)``
Calculates the Basic Value of an item, as seen in the View Item screen.
Maps module
-----------
@ -1760,6 +1822,10 @@ and are only documented here for completeness:
The oldval, newval or delta arguments may be used to specify additional constraints.
Returns: *found_index*, or *nil* if end reached.
* ``dfhack.internal.getDir(path)``
List files in a directory.
Returns: *file_names* or empty table if not found.
Core interpreter context
========================
@ -1992,6 +2058,10 @@ utils
way enables applying the same permutation to multiple arrays.
This function is used by the sort plugin.
* ``for link,item in utils.listpairs(list)``
Iterates a df-list structure, for example ``df.global.world.job_list``.
* ``utils.assign(tgt, src)``
Does a recursive assignment of src into tgt.
@ -3110,6 +3180,10 @@ Functions
Enable event checking for EventManager events. For event types use ``eventType`` table. Note that different types of events require different frequencies to be effective. The frequency is how many ticks EventManager will wait before checking if that type of event has happened. If multiple scripts or plugins use the same event type, the smallest frequency is the one that is used, so you might get events triggered more often than the frequency you use here.
5. ``registerSidebar(shop_name,callback)``
Enable callback when sidebar for ``shop_name`` is drawn. Usefull for custom workshop views e.g. using gui.dwarfmode lib.
Examples
--------
Spawn dragon breath on each item attempt to contaminate wound::
@ -28,15 +28,15 @@ All new releases are announced in the bay12 thread: http://tinyurl.com/dfhack-ng
=============
Compatibility
=============
DFHack works on Windows XP, Vista, 7 or any modern Linux distribution.
OSX is not supported due to lack of developers with a Mac.
DFHack works on Windows XP, Vista, 7, any modern Linux distribution, or OS X
10.6.8-10.9.
Currently, version 0.34.11 is supported (and tested). If you need DFHack
for older versions, look for older releases.
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
@ -329,6 +329,13 @@ Options:
The building must be one of stockpile, workshop, furnace, trap,
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
==============
@ -489,7 +496,7 @@ Options:
createitem
----------
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:
* Separate the item and material with a space rather than a colon
@ -506,6 +513,14 @@ Examples:
``createitem FISH FISH_SHAD:MALE 5``
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)
------------------
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
--------
Fills all the adamantine veins again. Veins that were empty will be filled in
too, but might still trigger a demon invasion (this is a known bug).
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.
Fills all the adamantine veins again. Veins that were hollow will be left
alone.
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
:trees:affect all trees on the map
: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
-------
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 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
=======
@ -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``
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/*
=====
@ -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,
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``
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.
@ -2107,6 +2157,7 @@ but ignore caged/chained creatures.
Ex::
exterminate gob
exterminate gob:male
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.
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
============
@ -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
Probably fails if the start time of a triggered invasion is later than the start of the next year.
digmat
======
Designates a tile for digging. Monitors the tile, and when it is dug out, add
@ -2278,6 +2335,10 @@ alternatively pass cage IDs as arguments::
stripcaged weapons 25321 34228
undump-buildings
================
Undesignates building base materials for dumping.
create-items
============
Spawn arbitrary items under the cursor.
@ -2357,12 +2418,16 @@ are mostly implemented by lua scripts.
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.
All of these tools are disabled by default - in order to make them available,
you must enable the plugins which provide them.
Dwarf Manipulator
=================
Implemented by the manipulator plugin. To activate, open the unit screen and
press 'l'.
Implemented by the 'manipulator' plugin.
To activate, open the unit screen and press 'l'.
..image:: images/manipulator.png
@ -2412,6 +2477,8 @@ directly to the main dwarf mode screen.
Search
======
Implemented by the 'search' plugin.
The search plugin adds search to the Stocks, Animals, Trading, Stockpile,
Noble (assignment candidates), Military (position candidates), Burrows
(unit list), Rooms, Announcements, Job List and Unit List screens.
@ -2452,9 +2519,11 @@ using Permit Fats again while the list is filtered.
AutoMaterial
============
The automaterial plugin 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.
Implemented by the 'automaterial' plugin.
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
the list, if there are any left. So if you build a wall with chalk blocks, the next
@ -2585,6 +2654,16 @@ Rationale: individual choice seems to be unreliable when there is a weapon short
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
==============
@ -2739,7 +2818,7 @@ of currently assigned racks for every valid squad.
gui/advfort
=============
===========
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
@ -2754,22 +2833,31 @@ keybinding. (e.g. keybinding set Ctrl-T gui/advfort). Possible arguments:
* 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
=======================
===================
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.
..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.
* equip - try to equip items on the ground.
* pick-up - try to take items into hand (also wield)
* unequip - remove and drop equipment
* unwield - drop held items
* wait - temporarely remove from party
* wait - temporarily remove from party
* follow - rejoin the party after "wait"
* leave - remove from party (can be rejoined by talking)
gui/gm-editor
=============
@ -2779,14 +2867,26 @@ There are three ways to open this editor:
or viewed (e.g. unit/item description screen)
* 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
the same as version above.
..image:: images/gm-editor.png
This editor allows to change and modify almost anything in df. Press '?' for an
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>`_
JapaMala
