MetzNet
/
dfhack
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update and clarify readme 

Fixed typos.  Made hyperlinks inline.  Some editorial changes for
clarification.  Updated and expanded introduction.  Fixed a few
formatting errors.
develop
PeridexisErrant 2015-02-15 18:13:58 +11:00
parent 49e53db063
commit 5223891984
1 changed files with 115 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

220
Readme.rst
Unescape Escape View File

@ -6,39 +6,56 @@ DFHack Readme
Introduction Introduction
============ ============
DFHack is a Dwarf Fortress memory access library and a set of basic DFHack is a Dwarf Fortress memory access library, distributed with scripts
tools that use it. Tools come in the form of plugins or (not yet) and plugins implementing a wide variety of useful functions and tools.
external tools. It is an attempt to unite the various ways tools
access DF memory and allow for easier development of new tools. For users, it provides a significant suite of bugfixes and interface
enhancements by default, and more can be enabled. There are also many tools
(such as ``workflow`` or ``autodump``) which can make life easier. You can
even add third-party scripts and plugins to do almost anything!
For modders, DFHack makes many things possible. Custom reactions, new
interactions, magic creature abilities, and more can be set through scripts
and custom raws. Non-standard DFHack scripts and inits can be stored in the
raw directory, making raws or saves fully self-contained for distribution -
or for coexistence in a single DF install, even with incompatible components.
For developers, DFHack unites the various ways tools access DF memory and
allows easier development of new tools. As an open-source project under
various copyleft licences, contributions are welcome.
.. contents:: .. contents::
============== ==============
Getting DFHack Getting DFHack
============== ==============
The project is currently hosted on github_ The project is currently hosted at http://www.github.com/
at http://github.com/DFHack/dfhack
Recent releases are available in source and binary formats `on the releases
page`_, while the binaries for releases 40.15-r1 to 34.11-r4 are on DFFD_.
Even older versions are available here_.
.. _github: http://www.github.com/ .. _`on the releases page`: http://github.com/DFHack/dfhack/releases
.. _DFFD: http://dffd.bay12games.com/search.php?string=DFHack&id=15
.. _here: http://dethware.org/dfhack/download
Older releases can be downloaded from here: http://dethware.org/dfhack/download All new releases are announced in `the bay12 forums thread`_, which is also a
good place for discussion and questions.
All new releases are announced in the bay12 thread: .. _`the bay12 forums thread`: http://www.bay12forums.com/smf/index.php?topic=139553
http://www.bay12forums.com/smf/index.php?topic=139553.0
============= =============
Compatibility Compatibility
============= =============
DFHack works on Windows XP, Vista, 7, any modern Linux distribution, or OS X DFHack is available for Windows (XP or later), Linux (any modern distribution),
10.6.8-10.9. or OS X (10.6.8 to 10.9).
Recent versions can be found on the releases_ page. Most releases only support Most releases only support the version of DF mentioned in their title - for
the version of DF mentioned in their title (e.g. DFHack 0.40.24-r2 only supports example, DFHack 0.40.24-r2 only supports DF 0.40.24 - but some releases
DF 0.40.24), but some releases support earlier DF versions as well. support earlier DF versions as well. Wherever possible, use the latest version
built for the target version of DF.
.. _releases: http://github.com/DFHack/dfhack/releases On Windows, DFHack is compatible with the SDL version of DF, but not the legacy version.
On Windows, you have to use the SDL version of DF.
It is also possible to use the Windows DFHack with Wine under Linux and OS X. It is also possible to use the Windows DFHack with Wine under Linux and OS X.
@ -95,7 +112,7 @@ 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 instroduction, 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.
@ -158,22 +175,28 @@ In this case, updating symbols.xml is not necessary.
============================= =============================
Something doesn't work, help! Something doesn't work, help!
============================= =============================
First, don't panic :) Second, dfhack keeps a few log files in DF's folder First, don't panic :)
- stderr.log and stdout.log. You can look at those and possibly find out what's
happening. Second, dfhack keeps a few log files in DF's folder (``stderr.log`` and
If you found a bug, you can either report it in the bay12 DFHack thread, ``stdout.log``). Looking at these might help you solve the problem.
the issues tracker on github, contact me (peterix@gmail.com) or visit the If it doesn't, you can ask for help in the forum thread or on IRC.
#dfhack IRC channel on freenode.
If you found a bug, you can report it in the Bay12 DFHack thread, the issues
tracker on github, or visit the #dfhack IRC channel on freenode.
============= =============
The init file The init file
============= =============
If your DF folder contains a file named ``dfhack.init``, its contents will be run If your DF folder contains a file named ``dfhack.init``, its contents will be
every time you start DF. This allows setting up keybindings. An example file run every time you start DF. This allows keybindings and other settings to
is provided as ``dfhack.init-example`` - you can tweak it and rename to dfhack.init persist across runs. An example file is provided as ``dfhack.init-example`` -
if you want to use this functionality. you can tweak it and rename to ``dfhack.init`` if you want to use this
functionality. If only the example init file is found, will be used and a
warning will be shown.
When a savegame is loaded, the ``onLoad.init`` file in its raw folder is run. It works the same way as ``dfhack.init``. It is recommended that modders use this to improve mobility of save games. When a savegame is loaded, an ``onLoad.init`` file in its raw folder is run,
as a save-portable alternative to ``dfhack.init``. It is recommended that
modders use this to improve mobility of save games and compatibility of mods.
Setting keybindings Setting keybindings
=================== ===================
@ -252,10 +275,10 @@ If the first non-whitespace character is ``:``, the command is parsed in a speci
alternative mode: first, non-whitespace characters immediately following the ``:`` alternative mode: first, non-whitespace characters immediately following the ``:``
are used as the command name; the remaining part of the line, starting with the first are used as the command name; the remaining part of the line, starting with the first
non-whitespace character *after* the command name, is used verbatim as the first argument. non-whitespace character *after* the command name, is used verbatim as the first argument.
The following two command lines are exactly equivalent: The following two command lines are exactly equivalent::
* ``:foo a b "c d" e f`` :foo a b "c d" e f
* ``foo "a b \"c d\" e f"`` foo "a b \"c d\" e f"
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.
@ -396,13 +419,14 @@ that pre-filled.
rendermax rendermax
--------- ---------
A collection of renderer replacing/enhancing filters. For better effect try changing the A collection of renderer replacing/enhancing filters. For better effect try changing the
black color in palette to non totally black. For more info see thread in forums: black color in palette to non totally black. For more info see `the Bay12 forum thread`_.
http://www.bay12forums.com/smf/index.php?topic=128487.0
.. _`the Bay12 forum thread`: http://www.bay12forums.com/smf/index.php?topic=128487
Options: Options:
``rendermax trippy`` ``rendermax trippy``
Randomizes each tiles color. Used for fun mainly. Randomizes the color of each tiles. Used for fun, or testing.
``rendermax light`` ``rendermax light``
Enable lighting engine. Enable lighting engine.
``rendermax light reload`` ``rendermax light reload``
@ -467,8 +491,6 @@ care to exactly preserve the mineral counts reported by ``prospect all``.
The amounts of different layer stones may slightly change in some cases The amounts of different layer stones may slightly change in some cases
if vein mass shifts between Z layers. if vein mass shifts between Z layers.
This command is very unlikely to work on maps generated before version 0.34.08.
Note that there is no undo option other than restoring from backup. Note that there is no undo option other than restoring from backup.
changelayer changelayer
@ -609,8 +631,8 @@ Options:
: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. :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
------------------ ------
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.
It also removes any and all 'down ramps' that can remain after a cave-in (you don't have to designate anything for that to happen). It also removes any and all 'down ramps' that can remain after a cave-in (you don't have to designate anything for that to happen).
@ -1006,9 +1028,9 @@ A permanent alias for 'digl x'.
digexp digexp
------ ------
This command can be used for exploratory mining. This command is for `exploratory mining`_.
See: http://df.magmawiki.com/index.php/DF2010:Exploratory_mining .. _`exploratory mining`: http://dwarffortresswiki.org/index.php/cv:Exploratory_mining
There are two variables that can be set: pattern and filter. There are two variables that can be set: pattern and filter.
@ -1207,16 +1229,11 @@ Cursor must be placed on a floor tile so the items can be dumped there.
Options: Options:
:destroy: Destroy instead of dumping. Doesn't require a cursor. :destroy: Destroy instead of dumping. Doesn't require a cursor.
:destroy-here: Destroy items only under the cursor. :destroy-here: Destroy items only under the cursor. Alias ``autodump-destroy-here``, for keybindings.
:visible: Only process items that are not hidden. :visible: Only process items that are not hidden.
:hidden: Only process hidden items. :hidden: Only process hidden items.
:forbidden: Only process forbidden items (default: only unforbidden). :forbidden: Only process forbidden items (default: only unforbidden).
autodump-destroy-here
---------------------
Destroy items marked for dumping under cursor. Identical to autodump
destroy-here, but intended for use as keybinding.
autodump-destroy-item autodump-destroy-item
--------------------- ---------------------
Destroy the selected item. The item may be selected in the 'k' list, or inside Destroy the selected item. The item may be selected in the 'k' list, or inside
@ -1359,8 +1376,9 @@ armor stands, and in containers.
Also, the default capacity of armor stands is way too low, so you Also, the default capacity of armor stands is way too low, so you
may want to also apply the ``armorstand-capacity`` patch. Check out may want to also apply the ``armorstand-capacity`` patch. Check out
http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445 `the bug report`_ for more information.
for more information about the bugs.
.. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445
Note that the buildings in the armory are used as follows: Note that the buildings in the armory are used as follows:
@ -1435,8 +1453,7 @@ produce undesirable results. There are a few good ones though.
You just lost a fortress and gained an adventurer. You just lost a fortress and gained an adventurer.
You could also do this. You could also do this.
You are in fort game mode, managing your fortress and paused at the esc menu. You are in fort game mode, managing your fortress and paused at the esc menu.
You switch to the adventure game mode, then use Dfusion to *assume control of a creature* and then You switch to the adventure game mode, assume control of a creature, then save or retire.
save or retire.
You just created a returnable mountain home and gained an adventurer. You just created a returnable mountain home and gained an adventurer.
@ -1446,31 +1463,31 @@ I take no responsibility of anything that happens as a result of using this tool
Visualizer and data export Visualizer and data export
========================== ==========================
ssense / stonesense stonesense
------------------- ----------
An isometric visualizer that runs in a second window. This requires working An isometric visualizer that runs in a second window. This requires working
graphics acceleration and at least a dual core CPU (otherwise it will slow graphics acceleration and at least a dual core CPU (otherwise it will slow
down DF). down DF). Invoked with ``stonesense``, or alias ``ssense``.
All the data resides in the 'stonesense' directory. For detailed instructions,
see stonesense/README.txt
Compatible with Windows > XP SP3 and most modern Linux distributions. For detailed information, see the `stonesense readme`_, the `wiki page`_,
or the `Bay12 forum thread`_.
Older versions, support and extra graphics can be found in the bay12 forum .. _`stonesense readme`: https://github.com/DFHack/stonesense/blob/master/README.md
thread: http://www.bay12forums.com/smf/index.php?topic=43260.0 .. _`wiki page`: http://dwarffortresswiki.org/index.php/Utility:Stonesense
.. _`Bay12 forum thread`: http://www.bay12forums.com/smf/index.php?topic=43260
Some additional resources: Stonesense works on Windows XP SP3 or later, and most modern Linux distributions.
http://df.magmawiki.com/index.php/Utility:Stonesense/Content_repository Each stonesense version is built for a particular version of DFHack, so
releases are now done through DFHack.
mapexport mapexport
--------- ---------
Export the current loaded map as a file. This will be eventually usable Export the current loaded map as a file. This was used by visualizers for
with visualizers. DF 34.11, but is now basically obsolete.
dwarfexport dwarfexport
----------- -----------
Export dwarves to RuneSmith-compatible XML. Export dwarves to RuneSmith-compatible XML; also unused by modern tools.
exportlegends exportlegends
------------- -------------
@ -1478,7 +1495,7 @@ Controls legends mode to export data - especially useful to set-and-forget large
worlds, or when you want a map of every site when there are several hundred. worlds, or when you want a map of every site when there are several hundred.
The 'info' option exports more data than is possible in vanilla, to a The 'info' option exports more data than is possible in vanilla, to a
region-date-legends_plus.xml" file developed to extend the World ``region-date-legends_plus.xml`` file developed to extend the World
Viewer utility and potentially compatible with others. Viewer utility and potentially compatible with others.
Options: Options:
@ -1626,13 +1643,15 @@ in the game UI.
Constraint format Constraint format
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
The contstraint spec consists of 4 parts, separated with '/' characters:: The constraint spec consists of 4 parts, separated with '/' characters::
ITEM[:SUBTYPE]/[GENERIC_MAT,...]/[SPECIFIC_MAT:...]/[LOCAL,<quality>] ITEM[:SUBTYPE]/[GENERIC_MAT,...]/[SPECIFIC_MAT:...]/[LOCAL,<quality>]
The first part is mandatory and specifies the item type and subtype, The first part is mandatory and specifies the item type and subtype,
using the raw tokens for items, in the same syntax you would e.g. use using the raw tokens for items, in the same syntax you would e.g. use
for a custom reaction input. See this list for more info: http://dwarffortresswiki.org/index.php/Item_token for a custom reaction input. See `this page`_ for more info.
.. _`this page`: http://dwarffortresswiki.org/index.php/Material_token
The subsequent parts are optional: The subsequent parts are optional:
@ -1645,9 +1664,9 @@ The subsequent parts are optional:
- A specific material spec chooses the material exactly, using the - A specific material spec chooses the material exactly, using the
raw syntax for reaction input materials, e.g. INORGANIC:IRON, raw syntax for reaction input materials, e.g. INORGANIC:IRON,
although for convenience it also allows just IRON, or ACACIA:WOOD etc. although for convenience it also allows just IRON, or ACACIA:WOOD etc.
See this page for more details on the unabbreviated raw syntax: See `this page`_ for more details on the unabbreviated raw syntax.
http://dwarffortresswiki.org/index.php/Material_token .. _`this page`: http://dwarffortresswiki.org/index.php/Material_token
- A comma-separated list of miscellaneous flags, which currently can - A comma-separated list of miscellaneous flags, which currently can
be used to ignore imported items or items below a certain quality. be used to ignore imported items or items below a certain quality.
@ -1975,15 +1994,11 @@ add some new races with 'watch'. If you simply want to stop it completely use
Settings and watchlist are stored in the savegame, so that you can have Settings and watchlist are stored in the savegame, so that you can have
different settings for each world. If you want to copy your watchlist to different settings for each world. If you want to copy your watchlist to
another savegame you can use the command list_export: another savegame you can export and then import them with ``list_export``:
::
Load savegame where you made the settings.
Start a CMD shell and navigate to the df directory. Type the following into the shell:
dfhack-run autobutcher list_export > autobutcher.bat
Load the savegame where you want to copy the settings to, run the batch file (from the shell):
autobutcher.bat
To export them, open a terminal in the DF directory, and run
``dfhack-run autobutcher list_export > autobutcher.bat`` (or ``.sh`` on OSX or
Linux). To import, load your new save and run the script you created.
autochop autochop
--------- ---------
@ -1994,7 +2009,7 @@ Open the dashboard by running::
getplants autochop getplants autochop
The plugin must be activated (with 'a') before it can be used. You can then set logging quotas The plugin must be activated (with ``c``) before it can be used. You can then set logging quotas
and restrict designations to specific burrows (with 'Enter') if desired. The plugin's activity and restrict designations to specific burrows (with 'Enter') if desired. The plugin's activity
cycle runs once every in game day. cycle runs once every in game day.
@ -2055,16 +2070,16 @@ Other jobs are automatically assigned as described above. Each of these setting
Jobs are rarely assigned to nobles with responsibilities for meeting diplomats or merchants, Jobs are rarely assigned to nobles with responsibilities for meeting diplomats or merchants,
never to the chief medical dwarf, and less often to the bookeeper and manager. never to the chief medical dwarf, and less often to the bookeeper and manager.
Hunting is never assigned without a butchery, and fishing is nver assigned without a fishery. Hunting is never assigned without a butchery, and fishing is never assigned without a fishery.
For each labor a preference order is calculated based on skill, biased against masters of other For each labor a preference order is calculated based on skill, biased against masters of other
trades and excluding those who can't do the job. The labor is then added to the best <minimum> trades and excluding those who can't do the job. The labor is then added to the best <minimum>
dwarves for that labor. We assign at least the minimum number of dwarfs, in order of preference, dwarves for that labor. We assign at least the minimum number of dwarfs, in order of preference,
and then assign additional dwarfs that meet any of these conditions: and then assign additional dwarfs that meet any of these conditions:
* The dwarf is idle and there are no idle dwarves assigned to this labor * The dwarf is idle and there are no idle dwarves assigned to this labor
* The dwarf has nonzero skill associated with the labor * The dwarf has non-zero skill associated with the labor
* The labor is mining, hunting, or woodcutting and the dwarf currently has it enabled. * The labor is mining, hunting, or woodcutting and the dwarf currently has it enabled.
We stop assigning dwarfs when we reach the maximum allowed. We stop assigning dwarfs when we reach the maximum allowed.
@ -2078,18 +2093,10 @@ twice.
dfusion dfusion
------- -------
This is the DFusion lua plugin system by Warmist, running as a DFHack plugin. There are two parts to this plugin: an interactive script that shows a text based menu and lua modules. Some of the functionality of is intentionaly left out of the menu: This is the DFusion system (a DFHack precursor) by Warmist, running as a DFHack
plugin. For detail on this legacy system, see the `Bay12 forums thread`_.
:Friendship: a binary plugin that allows multi race forts (to use make a script that imports plugins.dfusion.friendship and use Friendship:install{table} table should contain list of race names.) .. _`Bay12 forums thread`: http://www.bay12forums.com/smf/index.php?topic=93317
:Embark: a binary plugin that allows multi race embark (to use make a script that imports plugins.dfusion.embark and use Embark:install{table} table should contain list of race names or list of pairs (race-name, caste_id)).
See the bay12 thread for details: http://www.bay12forums.com/smf/index.php?topic=93317.0
.. note::
* Some of the DFusion plugins aren't completely ported yet. This can lead to crashes.
* The game will be suspended while you're using dfusion. Don't panic when it doesn't respond.
embark-tools embark-tools
------------ ------------
@ -2201,7 +2208,8 @@ Scripts in this subdirectory fix various bugs and issues, some of them obscure.
* fix/growth-bug * fix/growth-bug
Fixes locally born units such that they will grow larger than their birth size. Note that this bug was fixed in DF version 0.40.02. Fixes locally born units such that they will grow larger than their birth size.
Note that this bug was fixed in DF version 0.40.02.
* fix/item-occupancy * fix/item-occupancy
@ -2235,7 +2243,7 @@ directory.
* gui/stockpiles * gui/stockpiles
Load and save stockpile settings from the 'q' menu. Load and save stockpile settings from the 'q' menu.
Usage: Usage::
gui/stockpiles -save to save the current stockpile gui/stockpiles -save to save the current stockpile
gui/stockpiles -load to load settings into the current stockpile gui/stockpiles -load to load settings into the current stockpile
@ -2317,11 +2325,11 @@ deathcause
========== ==========
Focus a body part ingame, and this script will display the cause of death of Focus a body part ingame, and this script will display the cause of death of
the creature. the creature.
Also works when selecting units from the 'u'nitlist viewscreen. Also works when selecting units from the (``u``) unitlist viewscreen.
dfstatus dfstatus
======== ========
Show a quick overview of critical stock quantities, including food, dirnks, wood, and various bars. Show a quick overview of critical stock quantities, including food, drinks, wood, and various bars.
exterminate exterminate
=========== ===========
@ -2344,7 +2352,7 @@ such as vampires, it also sets animal.vanish_countdown to 2.
An alternate mode is selected by adding a 2nd argument to the command, An alternate mode is selected by adding a 2nd argument to the command,
``magma``. In this case, a column of 7/7 magma is generated on top of the ``magma``. In this case, a column of 7/7 magma is generated on top of the
targets until they die (Warning: do not call on magma-safe creatures. Also, targets until they die (Warning: do not call on magma-safe creatures. Also,
using this mode on birds is not recommanded.) using this mode on birds is not recommended.)
Will target any unit on a revealed tile of the map, including ambushers, Will target any unit on a revealed tile of the map, including ambushers,
but ignore caged/chained creatures. but ignore caged/chained creatures.
@ -2381,7 +2389,7 @@ same line.
The syntax of the file itself is similar to digfort or quickfort. At present, The syntax of the file itself is similar to digfort or quickfort. At present,
only buildings constructed of an item with the same name as the building only buildings constructed of an item with the same name as the building
are supported. All other characters are ignored. For example: are supported. All other characters are ignored. For example::
`,`,d,`,` `,`,d,`,`
`,f,`,t,` `,f,`,t,`
@ -2424,7 +2432,7 @@ two-across pit with stairs but no walls.
hotkey-notes hotkey-notes
============ ============
Lists the key, name, and jump position of your hotkeys. Lists the key, name, and jump position of your hotkeys in the DFHack console.
lever lever
===== =====
@ -2916,11 +2924,11 @@ work again. The existing issues are:
* Even if assigned by the script, **the game will unassign the racks again without a binary patch**. * Even if assigned by the script, **the game will unassign the racks again without a binary patch**.
This patch is called ``weaponrack-unassign``, and can be applied via This patch is called ``weaponrack-unassign``, and can be applied via
the binpatch program, or the matching script. See this for more info the binpatch program, or the matching script. See `the bug report`_ for more info.
about the bug:
http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445 .. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445
* Haulers still take equpment stored in the armory away to the stockpiles, * Haulers still take equipment stored in the armory away to the stockpiles,
unless the ``fix-armory`` plugin above is used. unless the ``fix-armory`` plugin above is used.
The script interface simply lets you designate one of the squads that The script interface simply lets you designate one of the squads that