Merge pull request #702 from PeridexisErrant/documentation-updates

Documentation updates
develop
expwnent 2015-09-26 03:02:13 -04:00
commit 79e904efa7
14 changed files with 1235 additions and 762 deletions

@ -1,198 +1,200 @@
-------------------------------------------------------------------------------- License of DFHack
License of dfhack =================
https://github.com/peterix/dfhack https://github.com/peterix/dfhack
Copyright (c) 2009-2012 Petr Mrázek (peterix@gmail.com) Copyright (c) 2009-2012 Petr Mrázek (peterix@gmail.com)
::
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any
damages arising from the use of this software.
This software is provided 'as-is', without any express or implied Permission is granted to anyone to use this software for any
warranty. In no event will the authors be held liable for any purpose, including commercial applications, and to alter it and
damages arising from the use of this software. redistribute it freely, subject to the following restrictions:
Permission is granted to anyone to use this software for any 1. The origin of this software must not be misrepresented; you must
purpose, including commercial applications, and to alter it and not claim that you wrote the original software. If you use this
redistribute it freely, subject to the following restrictions: software in a product, an acknowledgment in the product documentation
would be appreciated but is not required.
1. The origin of this software must not be misrepresented; you must 2. Altered source versions must be plainly marked as such, and
not claim that you wrote the original software. If you use this must not be misrepresented as being the original software.
software in a product, an acknowledgment in the product documentation
would be appreciated but is not required.
2. Altered source versions must be plainly marked as such, and 3. This notice may not be removed or altered from any source
must not be misrepresented as being the original software. distribution.
3. This notice may not be removed or altered from any source
distribution.
--------------------------------------------------------------------------------
License of the used XML reader library License of the used XML reader library
======================================
http://www.sourceforge.net/projects/tinyxml
Original code, 2.0 and earlier, copyright 2000-2006 Lee Thomason (http://www.grinninglizard.com)
::
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any
damages arising from the use of this software.
Permission is granted to anyone to use this software for any
purpose, including commercial applications, and to alter it and
redistribute it freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must
not claim that you wrote the original software. If you use this
software in a product, an acknowledgment in the product documentation
would be appreciated but is not required.
2. Altered source versions must be plainly marked as such, and
must not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source
distribution.
dirent.h - dirent API for Microsoft Visual Studio
=================================================
Copyright (C) 2006 Toni Ronkko
::
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
www.sourceforge.net/projects/tinyxml THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
Original code (2.0 and earlier )copyright (c) 2000-2006 Lee Thomason (www.grinninglizard.com) OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
This software is provided 'as-is', without any express or implied IN NO EVENT SHALL TONI RONKKO BE LIABLE FOR ANY CLAIM, DAMAGES OR
warranty. In no event will the authors be held liable for any OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
damages arising from the use of this software. ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
Permission is granted to anyone to use this software for any
purpose, including commercial applications, and to alter it and
redistribute it freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must
not claim that you wrote the original software. If you use this
software in a product, an acknowledgment in the product documentation
would be appreciated but is not required.
2. Altered source versions must be plainly marked as such, and
must not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source
distribution.
--------------------------------------------------------------------------------
* dirent.h - dirent API for Microsoft Visual Studio
*
* Copyright (C) 2006 Toni Ronkko
*
* Permission is hereby granted, free of charge, to any person obtaining
* a copy of this software and associated documentation files (the
* ``Software''), to deal in the Software without restriction, including
* without limitation the rights to use, copy, modify, merge, publish,
* distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so, subject to
* the following conditions:
*
* The above copyright notice and this permission notice shall be included
* in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND, EXPRESS
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
* IN NO EVENT SHALL TONI RONKKO BE LIABLE FOR ANY CLAIM, DAMAGES OR
* OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
* ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
* OTHER DEALINGS IN THE SOFTWARE.
--------------------------------------------------------------------------------
Parts of dfhack are based on linenoise:
linenoise.c -- guerrilla line editing library against the idea that a
line editing lib needs to be 20,000 lines of C code.
You can find the latest source code at:
http://github.com/antirez/linenoise
Does a number of crazy assumptions that happen to be true in 99.9999% of
the 2010 UNIX computers around.
--------------------------------------------------------------------------------
Copyright (c) 2010, Salvatore Sanfilippo <antirez at gmail dot com>
Copyright (c) 2010, Pieter Noordhuis <pcnoordhuis at gmail dot com>
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
--------------------------------------------------------------------------------
linenoise.c
===========
Parts of dfhack are based on linenoise: a line editing library against the
idea that a line editing lib needs to be 20,000 lines of C code.
You can find the latest source code at http://github.com/antirez/linenoise
::
Copyright (c) 2010, Salvatore Sanfilippo <antirez at gmail dot com>
Copyright (c) 2010, Pieter Noordhuis <pcnoordhuis at gmail dot com>
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
UTF-8 Decoder
=============
See http://bjoern.hoehrmann.de/utf-8/decoder/dfa/ for details. See http://bjoern.hoehrmann.de/utf-8/decoder/dfa/ for details.
::
Copyright (c) 2008-2010 Bjoern Hoehrmann <bjoern@hoehrmann.de> Copyright (c) 2008-2010 Bjoern Hoehrmann <bjoern@hoehrmann.de>
Permission is hereby granted, free of charge, to any person obtaining a copy Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions: furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software. copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
--------------------------------------------------------------------------------
luafilesystem
=============
Parts of dfhack are based on luafilesystem: Parts of dfhack are based on luafilesystem:
::
Copyright (c) 2003-2014 Kepler Project.
Copyright (c) 2003-2014 Kepler Project.
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation Permission is hereby granted, free of charge, to any person
files (the "Software"), to deal in the Software without obtaining a copy of this software and associated documentation
restriction, including without limitation the rights to use, copy, files (the "Software"), to deal in the Software without
modify, merge, publish, distribute, sublicense, and/or sell copies restriction, including without limitation the rights to use, copy,
of the Software, and to permit persons to whom the Software is modify, merge, publish, distribute, sublicense, and/or sell copies
furnished to do so, subject to the following conditions: of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software. The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
SOFTWARE. CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
--------------------------------------------------------------------------------
jsoncpp license jsoncpp
========
Copyright (c) 2007-2010 Baptiste Lepilleur ::
Permission is hereby granted, free of charge, to any person Copyright (c) 2007-2010 Baptiste Lepilleur
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without Permission is hereby granted, free of charge, to any person
restriction, including without limitation the rights to use, copy, obtaining a copy of this software and associated documentation
modify, merge, publish, distribute, sublicense, and/or sell copies files (the "Software"), to deal in the Software without
of the Software, and to permit persons to whom the Software is restriction, including without limitation the rights to use, copy,
furnished to do so, subject to the following conditions: modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is
The above copyright notice and this permission notice shall be furnished to do so, subject to the following conditions:
included in all copies or substantial portions of the Software.
The above copyright notice and this permission notice shall be
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, included in all copies or substantial portions of the Software.
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
SOFTWARE. ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-------------------------------------------------------------------------------- SOFTWARE.
JSON.lua license
Copyright 2010-2014 Jeffrey Friedl JSON.lua
http://regex.info/blog/ ========
Copyright 2010-2014 Jeffrey Friedl, http://regex.info/blog/
Latest version: http://regex.info/blog/lua/json Latest version: http://regex.info/blog/lua/json

13
NEWS

@ -1,3 +1,10 @@
.. comment
This is the changelog file for DFHack. If you add or change anything, note
it here under the heading "DFHack Future", in the appropriate section.
Items within each section are listed in alphabetical order to minimise merge
conflicts. Try to match the style and level of detail of the other entries.
DFHack Future DFHack Future
============= =============
:: ::
@ -72,6 +79,12 @@ DFHack Future
- Note: Existing stuck jobs must be cancelled and re-added - Note: Existing stuck jobs must be cancelled and re-added
zone: Fixed a crash when using "zone set" (and a few other potential crashes) zone: Fixed a crash when using "zone set" (and a few other potential crashes)
Misc Improvements Misc Improvements
DFHack documentation:
- massively reorganised, into files of more readable size
- added many missing entries
- indexes, internal links, offline search all documents
- includes documentation of linked projects (df-structures, 3rdparty scripts)
- better HTML generation with Sphinx
autolabor: autolabor:
- Stopped modification of labors that shouldn't be modified for brokers/diplomats - Stopped modification of labors that shouldn't be modified for brokers/diplomats
- Prioritize skilled dwarves more efficiently - Prioritize skilled dwarves more efficiently

@ -4,13 +4,13 @@
<html lang="en-US"> <html lang="en-US">
<head> <head>
<meta charset="UTF-8"> <meta charset="UTF-8">
<meta http-equiv="refresh" content="0;url=./docs/_build/html/README.html"> <meta http-equiv="refresh" content="0;url=./docs/html/README.html">
<script type="text/javascript"> <script type="text/javascript">
window.location.href = "./docs/_build/html/README.html" window.location.href = "./docs/html/README.html"
</script> </script>
<title>Page Redirection</title> <title>Page Redirection</title>
</head> </head>
<body> <body>
If you are not redirected automatically, follow the <a href='./docs/_build/html/README.html'>link to the documentation.</a> If you are not redirected automatically, follow the <a href='./docs/html/README.html'>link to the documentation.</a>
</body> </body>
</html> </html>

@ -8,32 +8,33 @@ and plugins implementing a wide variety of useful functions and tools.
For users, it provides a significant suite of bugfixes and interface For users, it provides a significant suite of bugfixes and interface
enhancements by default, and more can be enabled. There are also many tools 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 (such as `plugins/workflow` or `plugins/autodump`) which can make life easier.
even add third-party scripts and plugins to do almost anything! You can even add third-party scripts and plugins to do almost anything!
For modders, DFHack makes many things possible. Custom reactions, new For modders, DFHack makes many things possible. Custom reactions, new
interactions, magic creature abilities, and more can be set through scripts interactions, magic creature abilities, and more can be set through `scripts <scripts/modtools>`
and custom raws. Non-standard DFHack scripts and inits can be stored in the 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 - raw directory, making raws or saves fully self-contained for distribution -
or for coexistence in a single DF install, even with incompatible components. or for coexistence in a single DF install, even with incompatible components.
For developers, DFHack unites the various ways tools access DF memory and For developers, DFHack unites the various ways tools access DF memory and
allows easier development of new tools. As an open-source project under allows easier development of new tools. As an open-source project under
various copyleft licences, contributions are welcome. `various copyleft licences <license>`, contributions are welcome.
Documentation Documentation
============= =============
DFHack documentation is generated by Sphinx. Check out the table of contents DFHack documentation is generated by Sphinx. Check out the table of contents
below, or the sources in the docs folder! below, or the sources in the `docs folder`_!
.. _`docs folder`: ./docs
User Manual: User Manual:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
docs/Readme docs/Core
docs/Plugins docs/Plugins
docs/Scripts docs/Scripts
@ -54,3 +55,5 @@ For Developers:
docs/Contributing docs/Contributing
docs/Compile docs/Compile
docs/Lua API docs/Lua API
library/xml/SYNTAX
docs/Binpatches

Before

Width:  |  Height:  |  Size: 2.4 KiB

After

Width:  |  Height:  |  Size: 2.4 KiB

@ -1,13 +1,13 @@
List of Authors List of Authors
=============== ===============
The following is a list of people who have contributed to **DFHack**, in no The following is a list of people who have contributed to DFHack, in no
particular order. particular order.
If you should be here and aren't, please get in touch or make a pull request! If you should be here and aren't, please get in touch or make a pull request!
======================= ==================== =========================== ======================= ======================= ===========================
Name Github Email Name Github Email
======================= ==================== =========================== ======================= ======================= ===========================
Petr Mrázek peterix peterix@gmail.com Petr Mrázek peterix peterix@gmail.com
Alexander Gavrilov angavrilov angavrilov@gmail.com Alexander Gavrilov angavrilov angavrilov@gmail.com
doomchild doomchild lee.crabtree@gmail.com doomchild doomchild lee.crabtree@gmail.com
@ -86,4 +86,4 @@ Vjek
Kris Parker kaypy Kris Parker kaypy
Jonas Ask jonask84@gmail.com Jonas Ask jonask84@gmail.com
8Z 8Z git8z@ya.ru 8Z 8Z git8z@ya.ru
======================= ==================== =========================== ======================= ======================= ===========================

@ -0,0 +1,180 @@
.. _binpatches:
######################
Patching the DF binary
######################
Writing scripts and plugins for DFHack is not the only way to modify Dwarf
Fortress. Before DFHack, it was common for tools to manually patch the
binary to change behaviour, and DFHack still contains tools to do this via
the `scripts/binpatch` command.
.. warning::
We recommend using a script or plugin instead of a raw patch if
at all possible - that way your work will work for many versions
across multiple operating systems. There's a reason nobody has
written patches since ``0.34.11``!
.. contents::
Getting a patch
===============
There are no binary patches available for Dwarf Fortress versions after 0.34.11
This system is kept for the chance that someone will find it useful, so some
hints on how to write your own follow. This will require disassembly and
decent skill in `memory research <contributing-memory-research>`.
* The patches are expected to be encoded in text format used by IDA.
* See `this commit <https://github.com/DFHack/dfhack/commit/8a9e3d1a728>`_,
when the 0.34.11 patches were discarded, for example patches.
* `Issue #546 <https://github.com/DFHack/dfhack/issues/546>`_ is about the
future of the binpatches, and may be useful reading.
If you want to write a patch, the armory patches discussed here and documented
below would probably be the best place to start.
Using a patch
=============
There are two methods to apply a patch.
Patching at runtime
-------------------
The `scripts/binpatch` script checks, applies or removes binary patches
directly in memory at runtime::
binpatch [check|apply|remove] <patchname>
If the name of the patch has no extension or directory separators, the
script uses ``hack/patches/<df-version>/<name>.dif``, thus auto-selecting
the version appropriate for the currently loaded executable.
This is the preferred method; it's easier to debug, does not cause persistent
problems, and leaves file checksums alone. As with many other commands, users
can simply add it to ``dfhack.init`` to reapply the patch every time DF is run.
Patching on disk
----------------
.. warning::
This method of patching is deprecated, and may be removed without notice.
You should use the runtime patching option above.
DFHack includes a small stand-alone utility for applying and removing
binary patches from the game executable. Use it from the regular operating
system console:
``binpatch check "Dwarf Fortress.exe" patch.dif``
Checks and prints if the patch is currently applied.
``binpatch apply "Dwarf Fortress.exe" patch.dif``
Applies the patch, unless it is already applied or in conflict.
``binpatch remove "Dwarf Fortress.exe" patch.dif``
Removes the patch, unless it is already removed.
If you use a permanent patch under OSX or Linux, you must update
``symbols.xml`` with the new checksum of the executable. Find the relevant
section, and add a new line::
<md5-hash value='????????????????????????????????'/>
In order to find the correct value of the hash, look into stderr.log;
DFHack prints an error there if it does not recognize the hash.
.. _binpatches/needs-patch:
Tools reliant on binpatches
===========================
Some DFHack tools require the game to be patched to work. As no patches
are currently available, the full description of each is included here.
fix-armory
----------
Enables a fix for storage of squad equipment in barracks.
Specifically, it prevents your haulers from moving squad equipment
to stockpiles, and instead queues jobs to store it on weapon racks,
armor stands, and in containers.
.. note::
In order to actually be used, weapon racks have to be patched and
manually assigned to a squad. See `scripts/gui/assign-rack`.
Note that the buildings in the armory are used as follows:
* Weapon racks (when patched) are used to store any assigned weapons.
Each rack belongs to a specific squad, and can store up to 5 weapons.
* Armor stands belong to specific squad members and are used for
armor and shields.
* Cabinets are used to store assigned clothing for a specific squad member.
They are **never** used to store owned clothing.
* Chests (boxes, etc) are used for a flask, backpack or quiver assigned
to the squad member. Due to a probable bug, food is dropped out of the
backpack when it is stored.
.. warning::
Although armor stands, cabinets and chests properly belong only to one
squad member, the owner of the building used to create the barracks will
randomly use any containers inside the room. Thus, it is recommended to
always create the armory from a weapon rack.
Contrary to the common misconception, all these uses are controlled by the
*Individual Equipment* usage flag. The *Squad Equipment* flag is actually
intended for ammo, but the game does even less in that area than for armor
and weapons. This plugin implements the following rules almost from scratch:
* Combat ammo is stored in chests inside rooms with Squad Equipment enabled.
* If a chest is assigned to a squad member due to Individual Equipment also
being set, it is only used for that squad's ammo; otherwise, any squads
with Squad Equipment on the room will use all of the chests at random.
* Training ammo is stored in chests inside archery ranges designated from
archery targets, and controlled by the same Train flag as archery training
itself. This is inspired by some defunct code for weapon racks.
There are some minor traces in the game code to suggest that the first of
these rules is intended by Toady; the rest are invented by this plugin.
gui/assign-rack
---------------
Bind to a key (the example config uses P), and activate when viewing a weapon
rack in the ``q`` mode.
.. image:: images/assign-rack.png
This script is part of a group of related fixes to make the armory storage
work again. The existing issues are:
* Weapon racks have to each be assigned to a specific squad, like with
beds/boxes/armor stands and individual squad members, but nothing in
the game does this. This issue is what this script addresses.
* Even if assigned by the script, **the game will unassign the racks again
without a binary patch**. This patch is called ``weaponrack-unassign``,
and has not been updated since 0.34.11. See `the bug report`_ for more info.
.. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445
* Haulers still take equipment stored in the armory away to the stockpiles,
unless `plugins/fix-armory` is used.
The script interface simply lets you designate one of the squads that
are assigned to the barracks/armory containing the selected stand as
the intended user. In order to aid in the choice, it shows the number
of currently assigned racks for every valid squad.

@ -16,13 +16,14 @@ DFHack doesn't have any kind of system of code snapshots in place, so you will h
get code from the github repository using git. get code from the github repository using git.
The code resides at https://github.com/DFHack/dfhack The code resides at https://github.com/DFHack/dfhack
On Linux and OS X, having a 'git' package installed is the minimal requirement (see below for OS X instructions), On Linux and OS X, having a ``git`` package installed is the minimal requirement (see below for OS X instructions),
but some sort of git gui or git integration for your favorite text editor/IDE will certainly help. but some sort of git gui or git integration for your favorite text editor/IDE will certainly help.
On Windows, you will need some sort of Windows port of git, or a GUI. Some examples: On Windows, you will need some sort of Windows port of git, or a GUI. Some examples:
* http://msysgit.github.io/ - this is a command line version of git for windows. Most tutorials on git usage will apply. * http://msysgit.github.io - this is a command line version of git for windows.
* http://code.google.com/p/tortoisegit/ - this puts a pretty, graphical face on top of msysgit Most tutorials on git usage will apply.
* http://code.google.com/p/tortoisegit - this puts a pretty, graphical face on top of msysgit
To get the code:: To get the code::
@ -75,15 +76,18 @@ Before you can build anything, you'll also need ``cmake``. It is advisable to al
``ccmake`` on distributions that split the cmake package into multiple parts. ``ccmake`` on distributions that split the cmake package into multiple parts.
You also need perl and the XML::LibXML and XML::LibXSLT perl packages (for the code generation parts). You also need perl and the XML::LibXML and XML::LibXSLT perl packages (for the code generation parts).
You should be able to find them in your distro repositories (on Arch linux 'perl-xml-libxml' and 'perl-xml-libxslt') or through ``cpan``. You should be able to find them in your distro repositories (on Arch linux
``perl-xml-libxml`` and ``perl-xml-libxslt``) or through ``cpan``.
To build Stonesense, you'll also need OpenGL headers. To build Stonesense, you'll also need OpenGL headers.
Some additional dependencies for other distros are listed on the `wiki <https://github.com/DFHack/dfhack/wiki/Linux-dependencies>`_. Some additional dependencies for other distros are listed on the
`wiki <https://github.com/DFHack/dfhack/wiki/Linux-dependencies>`_.
Build Build
===== =====
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::
cd build cd build
cmake .. -DCMAKE_BUILD_TYPE:string=Release -DCMAKE_INSTALL_PREFIX=/home/user/DF cmake .. -DCMAKE_BUILD_TYPE:string=Release -DCMAKE_INSTALL_PREFIX=/home/user/DF
@ -205,7 +209,8 @@ Snow Leopard Changes
Yosemite Changes Yosemite Changes
================ ================
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
all the required packages.
Build Build
===== =====

@ -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.

@ -1,6 +1,6 @@
############# ###########
DFHack Readme DFHack Core
############# ###########
.. contents:: .. contents::
@ -21,6 +21,7 @@ Even older versions are available here_.
All new releases are announced in `the bay12 forums thread`_, which is also a All new releases are announced in `the bay12 forums thread`_, which is also a
good place for discussion and questions. good place for discussion and questions.
.. _`the Bay12 DFHack thread`:
.. _`the bay12 forums thread`: http://www.bay12forums.com/smf/index.php?topic=139553 .. _`the bay12 forums thread`: http://www.bay12forums.com/smf/index.php?topic=139553
If this sounds too complicated, you might prefer to `get a Starter Pack`_. If this sounds too complicated, you might prefer to `get a Starter Pack`_.
@ -48,18 +49,18 @@ Installation/Removal
Installing DFhack involves copying files into your DF folder. Installing DFhack involves copying files into your DF folder.
Copy the files from a release archive so that: Copy the files from a release archive so that:
* On Windows, SDL.dll is replaced * On Windows, ``SDL.dll`` is replaced
* On Linux, the 'dfhack' script is placed in the same folder as the 'df' script * On Linux or OSX, the ``dfhack`` script is placed in the same folder as the ``df`` script
Uninstalling is basically the same, in reverse: Uninstalling is basically the same, in reverse:
* On Windows, first delete SDL.dll and rename SDLreal.dll to SDL.dll. Then * On Windows, first delete ``SDL.dll`` and rename ``SDLreal.dll`` to ``SDL.dll``,
remove the other DFHack files then remove the other DFHack files
* On Linux, Remove the DFHack files. * On Linux, remove the DFHack files.
The stonesense plugin might require some additional libraries on Linux. The stonesense plugin might require some additional libraries on Linux.
If any of the plugins or dfhack itself refuses to load, check the stderr.log If any of the plugins or dfhack itself refuses to load, check the ``stderr.log``
file created in your DF folder. file created in your DF folder.
@ -71,7 +72,7 @@ window once DF is started as usual on windows. Linux and Mac OS X require
running the dfhack script from the terminal, and will use that terminal for running the dfhack script from the terminal, and will use that terminal for
the console. the console.
**NOTE**: The dfhack-run executable is there for calling DFHack commands in **NOTE**: The ``dfhack-run`` executable is there for calling DFHack commands in
an already running DF+DFHack instance from external OS scripts and programs, an already running DF+DFHack instance from external OS scripts and programs,
and is *not* the way how you use DFHack normally. and is *not* the way how you use DFHack normally.
@ -86,18 +87,16 @@ called ``dfhack.init``; the installation comes with an example version called
features and can be simply renamed to ``dfhack.init``. You are encouraged to look features and can be simply renamed to ``dfhack.init``. You are encouraged to look
through it to learn which features it makes available under which key combinations. through it to learn which features it makes available under which key combinations.
For more information, refer to the rest of this document.
Using DFHack Using DFHack
============ ============
DFHack basically extends what DF can do with something similar to the drop-down DFHack basically extends what DF can do with something similar to the drop-down
console found in Quake engine games. On Windows, this is a separate command line console found in Quake engine games. On Windows, this is a separate command line
window. On linux, the terminal used to launch the dfhack script is taken over window. On Linux, the terminal used to launch the dfhack script is taken over
(so, make sure you start from a terminal). Basic interaction with dfhack (so, make sure you start from a terminal). Basic interaction with dfhack
involves entering commands into the console. For some basic instructions, involves entering commands into the console. For some basic instructions,
use the 'help' command. To list all possible commands, use the 'ls' command. use the ``help`` command. To list all possible commands, use the ``ls`` command.
Many commands have their own help or detailed description. You can use Many commands have their own help or detailed description. You can use
'command help' or 'command ?' to show that. ``command help`` or ``command ?`` to show that.
The command line has some nice line editing capabilities, including history The command line has some nice line editing capabilities, including history
that's preserved between different runs of DF (use up/down keys to go through that's preserved between different runs of DF (use up/down keys to go through
@ -105,17 +104,21 @@ the history).
The second way to interact with DFHack is to bind the available commands The second way to interact with DFHack is to bind the available commands
to in-game hotkeys. The old way to do this is via the hotkey/zoom menu (normally to in-game hotkeys. The old way to do this is via the hotkey/zoom menu (normally
opened with the 'h' key). Binding the commands is done by assigning a command as opened with the ``h`` key). Binding the commands is done by assigning a command as
a hotkey name (with 'n'). a hotkey name (with ``n``).
A new and more flexible way is the keybinding command in the dfhack console. A new and more flexible way is the keybinding command in the dfhack console.
However, bindings created this way are not automatically remembered between runs However, bindings created this way are not automatically remembered between runs
of the game, so it becomes necessary to use the dfhack.init file to ensure that of the game, so it becomes necessary to use the dfhack.init file to ensure that
they are re-created every time it is loaded. they are re-created every time it is loaded.
Interactive commands like 'liquids' cannot be used as hotkeys. Interactive commands like `plugins/liquids` cannot be used as hotkeys.
Most of the commands come from plugins. Those reside in 'hack/plugins/'. Many commands come from plugins, which are stored in ``hack/plugins/``
and must be compiled with the same version of DFHack. Others come
from scripts, which are stored in ``hack/scripts``. Scripts are much
more flexible about versions, and easier to distribute - so most third-party
DFHack addons are scripts.
Something doesn't work, help! Something doesn't work, help!
============================= =============================
@ -125,11 +128,14 @@ Second, dfhack keeps a few log files in DF's folder (``stderr.log`` and
``stdout.log``). Looking at these might help you solve the problem. ``stdout.log``). Looking at these might help you solve the problem.
If it doesn't, you can ask for help in the forum thread or on IRC. If it doesn't, you can ask for help in the forum thread or on IRC.
If you found a bug, you can report it in the Bay12 DFHack thread, the issues If you found a bug, you can report it in `the Bay12 DFHack thread`_,
tracker on github, or visit the #dfhack IRC channel on freenode. `the issues tracker on github <https://github.com/DFHack/dfhack/issues>`_,
or visit `the #dfhack IRC channel on freenode
<https://webchat.freenode.net/?channels=dfhack>`_.
Commands =============
======== Core Commands
=============
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::
<md5-hash value='????????????????????????????????'/>
In order to find the correct value of the hash, look into stderr.log;
DFHack prints an error there if it does not recognize the hash.
DFHack includes a small stand-alone utility for applying and removing
binary patches from the game executable. Use it from the regular operating
system console:
``binpatch check "Dwarf Fortress.exe" patch.dif``
Checks and prints if the patch is currently applied.
``binpatch apply "Dwarf Fortress.exe" patch.dif``
Applies the patch, unless it is already applied or in conflict.
``binpatch remove "Dwarf Fortress.exe" patch.dif``
Removes the patch, unless it is already removed.
The patches are expected to be encoded in text format used by IDA.

@ -1,3 +1,5 @@
.. _license:
######## ########
Licenses Licenses
######## ########
@ -7,4 +9,3 @@ DFHack is distributed under a range of permissive and weakly copyleft licenses.
The core uses the ZLib license; the others are described below. The core uses the ZLib license; the others are described below.
.. include:: ../LICENSE .. include:: ../LICENSE
:literal:

File diff suppressed because it is too large Load Diff

@ -4,11 +4,12 @@ DFHack Scripts
Lua or ruby scripts placed in the ``hack/scripts/`` directory are considered for Lua or ruby scripts placed in the ``hack/scripts/`` directory are considered for
execution as if they were native DFHack commands. They are listed at the end execution as if they were native DFHack commands. They are listed at the end
of the 'ls' command output. of the ``ls`` command output.
Note: scripts in subdirectories of hack/scripts/ can still be called, but will Note: scripts in subdirectories of hack/scripts/ can still be called, but will
only be listed by ls if called as 'ls -a'. This is intended as a way to hide only be listed by ls if called as ``ls -a``. This is intended as a way to hide
scripts that are obscure, developer-oriented, or should be used as keybindings. scripts that are obscure, developer-oriented, or should be used as keybindings
or from the init file.
``kill-lua`` stops any currently-running Lua scripts. By default, scripts can ``kill-lua`` stops any currently-running Lua scripts. By default, scripts can
only be interrupted every 256 instructions. Use ``kill-lua force`` to interrupt only be interrupted every 256 instructions. Use ``kill-lua force`` to interrupt
@ -16,6 +17,30 @@ the next instruction.
.. contents:: .. contents::
=================
3rd-party scripts
=================
This listing is autogenerated from ``.rst`` files in the 3rdparty scripts directory.
.. warning::
Because this documentation is pulled in from external sources,
it may not match the DFHack distribution exactly.
* Some scripts should have a prefix (eg listed as ``myscript``,
should be ``gui/myscript``) but don't.
* Some sections of documentation may refer to scripts which are
not distributed with DFHack.
.. toctree::
:glob:
:maxdepth: 2
/scripts/3rdparty/*/*
======= =======
devel/* devel/*
======= =======
@ -77,7 +102,7 @@ fix/stable-temp
=============== ===============
Instantly sets the temperature of all free-lying items to be in equilibrium with Instantly sets the temperature of all free-lying items to be in equilibrium with
the environment and stops temperature updates. In order to maintain this efficient the environment and stops temperature updates. In order to maintain this efficient
state however, use ``tweak stable-temp`` and ``tweak fast-heat``. state however, use `plugins/tweak` ``stable-temp`` and `plugins/tweak` ``fast-heat``.
fix/stuckdoors fix/stuckdoors
============== ==============
@ -124,39 +149,18 @@ An example of player digging in adventure mode:
gui/advfort_items gui/advfort_items
================= =================
Does something with items in advnedute mode jobs. Does something with items in adventure mode jobs.
.. _scripts/gui/assign-rack:
gui/assign-rack gui/assign-rack
=============== ===============
Bind to a key (the example config uses P), and activate when viewing a weapon `This script requires a binpatch <binpatches/needs-patch>`, which has not
rack in the 'q' mode. been available since DF 0.34.11
.. image:: images/assign-rack.png
This script is part of a group of related fixes to make the armory storage
work again. The existing issues are:
* Weapon racks have to each be assigned to a specific squad, like with
beds/boxes/armor stands and individual squad members, but nothing in
the game does this. This issue is what this script addresses.
* 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
the binpatch program, or the matching script. See `the bug report`_ for more info.
.. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445
* Haulers still take equipment stored in the armory away to the stockpiles,
unless the ``fix-armory`` plugin above is used.
The script interface simply lets you designate one of the squads that
are assigned to the barracks/armory containing the selected stand as
the intended user. In order to aid in the choice, it shows the number
of currently assigned racks for every valid squad.
gui/autobutcher gui/autobutcher
=============== ===============
An in-game interface for the ``autobutcher`` plugin. An in-game interface for `plugins/autobutcher`.
gui/choose-weapons gui/choose-weapons
================== ==================
@ -195,6 +199,8 @@ case. Must be in look or talk mode to issue command on tile.
* 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)
.. _scripts/gui/create-item:
gui/create-item gui/create-item
=============== ===============
A graphical interface for creating items. A graphical interface for creating items.
@ -238,7 +244,7 @@ computes it when the order is executed for the first time.
gui/hack-wish gui/hack-wish
============= =============
An alias for ``gui/create-item``. Deprecated. An alias for `scripts/gui/create-item`. Deprecated.
gui/hello-world gui/hello-world
=============== ===============
@ -250,10 +256,13 @@ To use, bind to a key (the example config uses Alt-L) and activate in the 'k' mo
.. image:: images/liquids.png .. image:: images/liquids.png
This script is a gui front-end to the liquids plugin and works similar to it, This script is a gui front-end to `plugins/liquids` and works similarly,
allowing you to add or remove water & magma, and create obsidian walls & floors. allowing you to add or remove water & magma, and create obsidian walls & floors.
Note that there is **no undo support**, and that bugs in this plugin have been
known to create pathfinding problems and heat traps. .. warning::
There is **no undo support**. Bugs in this plugin have been
known to create pathfinding problems and heat traps.
The ``b`` key changes how the affected area is selected. The default *Rectangle* The ``b`` key changes how the affected area is selected. The default *Rectangle*
mode works by selecting two corners like any ordinary designation. The ``p`` mode works by selecting two corners like any ordinary designation. The ``p``
@ -298,13 +307,17 @@ gui/no-dfhack-init
================== ==================
Shows a warning at startup if no valid ``dfhack.init`` file is found. Shows a warning at startup if no valid ``dfhack.init`` file is found.
.. _scripts/gui/power-meter:
gui/power-meter gui/power-meter
=============== ===============
An in-game interface for the ``power-meter`` plugin. An in-game interface for `plugins/power-meter`.
.. _scripts/gui/rename:
gui/rename gui/rename
========== ==========
Backed by the rename plugin, this script allows entering the desired name Backed by `plugins/rename`, this script allows entering the desired name
via a simple dialog in the game ui. via a simple dialog in the game ui.
* ``gui/rename [building]`` in 'q' mode changes the name of a building. * ``gui/rename [building]`` in 'q' mode changes the name of a building.
@ -340,28 +353,36 @@ either immediately or after opening the assign owner page.
The script lists other rooms owned by the same owner, or by the unit selected in the assign The script lists other rooms owned by the same owner, or by the unit selected in the assign
list, and allows unassigning them. list, and allows unassigning them.
.. _scripts/gui/siege-engine:
gui/siege-engine gui/siege-engine
================ ================
An in-game interface for the ``siege-engine`` plugin. An in-game interface for `plugins/siege-engine`.
.. _scripts/gui/stockpiles:
gui/stockpiles gui/stockpiles
============== ==============
Load and save stockpile settings from the 'q' menu. An in-game interface for `plugins/stocksettings`, to
Usage:: load and save stockpile settings from the 'q' menu.
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
gui/stockpiles -dir <path> set the default directory to save settings into :gui/stockpiles -dir <path>: set the default directory to save settings into
gui/stockpiles -help to see this message :gui/stockpiles -help: to see this message
Don't forget to `enable stockpiles` and create the `stocksettings` directory in Don't forget to ``enable stockpiles`` and create the ``stocksettings`` directory in
the DF folder before trying to use this plugin. the DF folder before trying to use the GUI.
gui/unit-info-viewer gui/unit-info-viewer
==================== ====================
Displays age, birth, maxage, shearing, milking, grazing, egg laying, body size, Displays age, birth, maxage, shearing, milking, grazing, egg laying, body size,
and death info about a unit. Recommended keybinding Alt-I. and death info about a unit. Recommended keybinding Alt-I.
.. _scripts/gui/workflow:
gui/workflow gui/workflow
============ ============
Bind to a key (the example config uses Alt-W), and activate with a job selected Bind to a key (the example config uses Alt-W), and activate with a job selected
@ -369,8 +390,8 @@ in a workshop in the 'q' mode.
.. image:: images/workflow.png .. image:: images/workflow.png
This script provides a simple interface to constraints managed by the workflow This script provides a simple interface to constraints managed by `plugins/workflow`.
plugin. When active, it displays a list of all constraints applicable to the When active, it displays a list of all constraints applicable to the
current job, and their current status. current job, and their current status.
A constraint specifies a certain range to be compared against either individual A constraint specifies a certain range to be compared against either individual
@ -387,8 +408,8 @@ items and expanding the range each gives a 2x bonus).
Pressing 'A' produces a list of possible outputs of this job as guessed by Pressing 'A' produces a list of possible outputs of this job as guessed by
workflow, and lets you create a new constraint by choosing one as template. If you workflow, and lets you create a new constraint by choosing one as template. If you
don't see the choice you want in the list, it likely means you have to adjust don't see the choice you want in the list, it likely means you have to adjust
the job material first using ``job item-material`` or ``gui/workshop-job``, the job material first using `plugins/job` ``item-material`` or `scripts/gui/workshop-job`,
as described in ``workflow`` documentation above. In this manner, this feature as described in `plugins/workflow` documentation. In this manner, this feature
can be used for troubleshooting jobs that don't match the right constraints. can be used for troubleshooting jobs that don't match the right constraints.
.. image:: images/workflow-new1.png .. image:: images/workflow-new1.png
@ -423,6 +444,8 @@ of stock history for the selected item, with the rightmost point representing
the current stock value. The bright green dashed line is the target the current stock value. The bright green dashed line is the target
limit (maximum) and the dark green line is that minus the gap (minimum). limit (maximum) and the dark green line is that minus the gap (minimum).
.. _scripts/gui/workshop-job:
gui/workshop-job gui/workshop-job
================ ================
Bind to a key (the example config uses Alt-A), and activate with a job selected in Bind to a key (the example config uses Alt-A), and activate with a job selected in
@ -431,7 +454,7 @@ a workshop in the 'q' mode.
.. image:: images/workshop-job.png .. image:: images/workshop-job.png
The script shows a list of the input reagents of the selected job, and allows changing The script shows a list of the input reagents of the selected job, and allows changing
them like the ``job item-type`` and ``job item-material`` commands. them like the `plugins/job` ``item-type`` and `plugins/job` ``item-material`` commands.
Specifically, pressing the 'i' key pops up a dialog that lets you select an item Specifically, pressing the 'i' key pops up a dialog that lets you select an item
type from a list. type from a list.
@ -469,6 +492,8 @@ material is matched against the barrel itself. Then, if you select, say, iron,
and then try to change the input item type, now it won't let you select *plant*; and then try to change the input item type, now it won't let you select *plant*;
you have to unset the material first. you have to unset the material first.
.. _scripts/modtools:
======================== ========================
modtools/* - for modders modtools/* - for modders
======================== ========================
@ -508,11 +533,15 @@ modtools/create-unit
==================== ====================
Creates a unit. Creates a unit.
.. _scripts/modtools/equip-item:
modtools/equip-item modtools/equip-item
=================== ===================
Force a unit to equip an item; useful in conjunction with the ``create`` Force a unit to equip an item; useful in conjunction with the ``create``
scripts above. scripts above.
See also `plugins/forceequip`.
modtools/force modtools/force
============== ==============
This tool triggers events like megabeasts, caravans, invaders, and migrants. This tool triggers events like megabeasts, caravans, invaders, and migrants.
@ -604,7 +633,8 @@ or the gui invoked by running ``add-thought gui`` with a unit selected.
armoks-blessing armoks-blessing
=============== ===============
Runs the equivalent of rejuvenate, elevate-physical, elevate-mental, and brainwash Runs the equivalent of `scripts/rejuvenate`, `scripts/elevate-physical`,
`scripts/elevate-mental`, and `scripts/brainwash`
on all dwarves currently on the map. This is an extreme change, which sets every on all dwarves currently on the map. This is an extreme change, which sets every
stat to an ideal - legendary skills, great traits, and easy-to-satisfy preferences. stat to an ideal - legendary skills, great traits, and easy-to-satisfy preferences.
Use in moderation; it's as 'cheaty' as DFHack gets. Use in moderation; it's as 'cheaty' as DFHack gets.
@ -621,14 +651,18 @@ Usage::
autofarm default 30 autofarm default 30
autofarm threshold 150 helmet_plump tail_pig autofarm threshold 150 helmet_plump tail_pig
.. _scripts/autolabor-artisans:
autolabor-artisans autolabor-artisans
================== ==================
Runs the ``autolabor`` plugin, with settings tuned for small but highly skilled workforces. Runs `plugins/autolabor`, with settings tuned for small but highly skilled workforces.
.. _scripts/autounsuspend:
autounsuspend autounsuspend
============= =============
Automatically unsuspend construction jobs, on a recurring basis. Automatically unsuspend jobs in workshops, on a recurring basis.
See ``unsuspend`` for one-off use, or ``resume all``. See `scripts/unsuspend` for one-off use, or `plugins/resume` ``all``.
ban-cooking ban-cooking
=========== ===========
@ -636,15 +670,13 @@ A more convenient way to ban cooking various categories of foods than the
kitchen interface. Usage: ``ban-cooking <type>``. Valid types are ``booze``, kitchen interface. Usage: ``ban-cooking <type>``. Valid types are ``booze``,
``honey``, ``tallow``, ``oil``, and ``seeds`` (non-tree plants with seeds). ``honey``, ``tallow``, ``oil``, and ``seeds`` (non-tree plants with seeds).
.. _scripts/binpatch:
binpatch binpatch
======== ========
Checks, applies or removes binary patches directly in memory at runtime:: Implements functions for in-memory binpatches. See `binpatches`.
binpatch check/apply/remove <patchname>
If the name of the patch has no extension or directory separators, the .. _scripts/brainwash:
script uses ``hack/patches/<df-version>/<name>.dif``, thus auto-selecting
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)
:selected: Show selected unit
:dwarves: Show dwarves
:livestock: Show livestock
:wildanimals: Show wild animals
:hostile: Show hostiles (e.g. invaders, thieves, forgotten beasts etc)
:world: Show all defined syndromes in the world
:export: ``export:<filename>`` sends output to the given file, showing all
syndromes affecting each unit with the maximum and present duration.
siren siren
===== =====
@ -1071,12 +1149,12 @@ The number argument is the target liquid level (0 = drain, 7 = source).
To add more than 1 unit everytime, call the command again on the same spot. To add more than 1 unit everytime, call the command again on the same spot.
To delete one source, place the cursor over its tile and use ``delete``. To delete one source, place the cursor over its tile and use ``source delete``.
To remove all existing sources, call ``source clear``. To remove all existing sources, call ``source clear``.
The ``list`` argument shows all existing sources. The ``list`` argument shows all existing sources.
Ex:: Examples::
source add water - water source source add water - water source
source add magma 7 - magma source source add magma 7 - magma source
@ -1092,7 +1170,7 @@ The number must be 7 or greater.
stripcaged stripcaged
========== ==========
For dumping items inside cages. Will mark selected items for dumping, then For dumping items inside cages. Will mark selected items for dumping, then
a dwarf may come and actually dump it. See also ``autodump``. a dwarf may come and actually dump it. See also `plugins/autodump`.
With the ``items`` argument, only dumps items laying in the cage, excluding With the ``items`` argument, only dumps items laying in the cage, excluding
stuff worn by caged creatures. ``weapons`` will dump worn weapons, ``armor`` stuff worn by caged creatures. ``weapons`` will dump worn weapons, ``armor``
@ -1119,7 +1197,7 @@ To make any creature superfast, target it ingame using 'v' and::
Other options available: ``del``, ``clear``, ``list``. Other options available: ``del``, ``clear``, ``list``.
This plugin also shortens the 'sleeping' and 'on break' periods of targets. This script also shortens the 'sleeping' and 'on break' periods of targets.
teleport teleport
======== ========
@ -1135,10 +1213,14 @@ undump-buildings
================ ================
Undesignates building base materials for dumping. Undesignates building base materials for dumping.
.. _scripts/unsuspend:
unsuspend unsuspend
========= =========
Unsuspend construction jobs, on a one-off basis. See ``autounsuspend`` for regular use. Unsuspend jobs in workshops, on a one-off basis. See `scripts/autounsuspend`
Equivalent to ``resume all``. for regular use.
.. _scripts/view-item-info:
view-item-info view-item-info
============== ==============
@ -1155,6 +1237,6 @@ warn-starving
============= =============
If any (live) units are starving, very thirsty, or very drowsy, the game will If any (live) units are starving, very thirsty, or very drowsy, the game will
be paused and a warning shown and logged to the console. Use with the be paused and a warning shown and logged to the console. Use with the
``repeat`` command for regular checks. `scripts/repeat` command for regular checks.
Use ``warn-starving all`` to display a list of all problematic units. Use ``warn-starving all`` to display a list of all problematic units.

@ -91,7 +91,7 @@ exclude_patterns = ['docs/_build/*', 'depends/*']
# The reST default role (used for this markup: `text`) to use for all # The reST default role (used for this markup: `text`) to use for all
# documents. # documents.
#default_role = None default_role = 'any'
# If true, '()' will be appended to :func: etc. cross-reference text. # If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True #add_function_parentheses = True
@ -145,7 +145,7 @@ html_theme = '@SPHINX_THEME@'
# The name of an image file (within the static path) to use as favicon of the # The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large. # pixels large.
#html_favicon = None html_favicon = 'dfhack-icon.ico'
# Add any paths that contain custom static files (such as style sheets) here, # Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files, # relative to this directory. They are copied after the builtin static files,