More internal links and consistent formatting

Links everywhere, and formatting throughout Plugins.rst
develop
PeridexisErrant 2015-09-25 14:15:05 +10:00
parent f25694d745
commit 00a261cc81
5 changed files with 289 additions and 257 deletions

@ -12,7 +12,7 @@ enhancements by default, and more can be enabled. There are also many tools
You can 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.
@ -25,8 +25,9 @@ allows easier development of new tools. As an open-source project under
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:

@ -125,6 +125,7 @@ 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.

@ -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`_.
@ -127,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.
@ -139,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 ``:``
@ -157,6 +163,14 @@ Almost all the commands support using the ``help <command-name>`` built-in comma
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`` or ``?`` as an 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 Init files
========== ==========
DFHack allows users to automatically run commonly-used DFHack commands when DF is first DFHack allows users to automatically run commonly-used DFHack commands when DF is first
@ -259,15 +273,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
============= =============

@ -148,31 +148,33 @@ Options:
:all: Also estimate vein mineral amounts. :all: Also estimate vein mineral amounts.
.. _plugins/reveal:
reveal reveal
------ ------
This reveals the map. By default, HFS will remain hidden so that the demons This reveals the map. By default, HFS will remain hidden so that the demons
don't spawn. You can use 'reveal hell' to reveal everything. With hell revealed, don't spawn. You can use ``reveal hell`` to reveal everything. With hell revealed,
you won't be able to unpause until you hide the map again. If you really want you won't be able to unpause until you hide the map again. If you really want
to unpause with hell revealed, use 'reveal demons'. to unpause with hell revealed, use ``reveal demons``.
Reveal also works in adventure mode, but any of its effects are negated once Reveal also works in adventure mode, but any of its effects are negated once
you move. When you use it this way, you don't need to run 'unreveal'. you move. When you use it this way, you don't need to run ``unreveal``.
unreveal unreveal
-------- ~~~~~~~~
Reverts the effects of 'reveal'. Reverts the effects of ``reveal``.
revtoggle revtoggle
--------- ~~~~~~~~~
Switches between 'reveal' and 'unreveal'. Switches between ``reveal`` and ``unreveal``.
revflood revflood
-------- ~~~~~~~~
This command will hide the whole map and then reveal all the tiles that have This command will hide the whole map and then reveal all the tiles that have
a path to the in-game cursor. a path to the in-game cursor.
revforget revforget
--------- ~~~~~~~~~
When you use reveal, it saves information about what was/wasn't visible before When you use reveal, it saves information about what was/wasn't visible before
revealing everything. Unreveal uses this information to hide things again. revealing everything. Unreveal uses this information to hide things again.
This command throws away the information. For example, use in cases where This command throws away the information. For example, use in cases where
@ -211,13 +213,12 @@ This plugin fixes issues with unit occupancy, notably issues with phantom
"unit blocking tile" messages (`Bug 3499`_). It can be run manually, or "unit blocking tile" messages (`Bug 3499`_). It can be run manually, or
periodically when enabled with the built-in enable/disable commands: periodically when enabled with the built-in enable/disable commands:
* ``fix-unit-occupancy``: Run the plugin immediately. Available options: :(no argument): Run the plugin once immediately, for the whole map.
:-h, here, cursor: Run immediately, only operate on the tile at the cursor
* ``-h``, ``here``, ``cursor``: Only operate on the tile at the cursor :-n, dry, dry-run: Run immediately, do not write changes to map
* ``-n``, ``dry``, ``dry-run``: Do not write changes to map :interval <X>: Run the plugin every ``X`` ticks (when enabled).
The default is 1200 ticks, or 1 day.
* ``fix-unit-occupancy interval X``: Run the plugin every ``X`` ticks (when enabled). Ticks are only counted when the game is unpaused.
The default is 1200 ticks, or 1 day. Ticks are only counted when the game is unpaused.
.. _`Bug 3499`: http://bay12games.com/dwarves/mantisbt/view.php?id=3499 .. _`Bug 3499`: http://bay12games.com/dwarves/mantisbt/view.php?id=3499
@ -304,22 +305,24 @@ Subcommands that persist until disabled or DF quits:
:fast-trade: Makes Shift-Down in the Move Goods to Depot and Trade screens select :fast-trade: Makes Shift-Down in the Move Goods to Depot and Trade screens select
the current item (fully, in case of a stack), and scroll down one line. the current item (fully, in case of a stack), and scroll down one line.
:fps-min: Fixes the in-game minimum FPS setting :fps-min: Fixes the in-game minimum FPS setting
:import-priority-category: Allows changing the priority of all goods in a :import-priority-category:
Allows changing the priority of all goods in a
category when discussing an import agreement with the liaison category when discussing an import agreement with the liaison
:kitchen-keys: Fixes DF kitchen meal keybindings (bug 614) :kitchen-keys: Fixes DF kitchen meal keybindings (bug 614)
:kitchen-prefs-color: Changes color of enabled items to green in kitchen preferences :kitchen-prefs-color: Changes color of enabled items to green in kitchen preferences
:kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs (bug 9000) :kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs (bug 9000)
:manager-quantity: Removes the limit of 30 jobs per manager order :manager-quantity: Removes the limit of 30 jobs per manager order
:max-wheelbarrow: Allows assigning more than 3 wheelbarrows to a stockpile :max-wheelbarrow: Allows assigning more than 3 wheelbarrows to a stockpile
:military-color-assigned: Color squad candidates already assigned to other squads in yellow/green :military-color-assigned:
Color squad candidates already assigned to other squads in yellow/green
to make them stand out more in the list. to make them stand out more in the list.
.. image:: images/tweak-mil-color.png .. image:: images/tweak-mil-color.png
:military-stable-assign: Preserve list order and cursor position when assigning to squad, :military-stable-assign:
Preserve list order and cursor position when assigning to squad,
i.e. stop the rightmost list of the Positions page of the military i.e. stop the rightmost list of the Positions page of the military
screen from constantly resetting to the top. screen from constantly resetting to the top.
:nestbox-color: Fixes the color of built nestboxes :nestbox-color: Fixes the color of built nestboxes
:shift-8-scroll: Gives Shift-8 (or ``*``) priority when scrolling menus, instead of scrolling the map :shift-8-scroll: Gives Shift-8 (or ``*``) priority when scrolling menus, instead of scrolling the map
:stable-cursor: Saves the exact cursor position between t/q/k/d/b/etc menus of fortress mode. :stable-cursor: Saves the exact cursor position between t/q/k/d/b/etc menus of fortress mode.
@ -397,14 +400,14 @@ manipulator
=========== ===========
An in-game equivalent to the popular program Dwarf Therapist. An in-game equivalent to the popular program Dwarf Therapist.
To activate, open the unit screen and press 'l'. To activate, open the unit screen and press ``l``.
.. image:: images/manipulator.png .. image:: images/manipulator.png
The far left column displays the unit's Happiness (color-coded based on its The far left column displays the unit's Happiness (color-coded based on its
value), Name, Profession/Squad, and the right half of the screen displays each value), Name, Profession/Squad, and the right half of the screen displays each
dwarf's labor settings and skill levels (0-9 for Dabbling thru Professional, A-E for dwarf's labor settings and skill levels (0-9 for Dabbling through Professional,
Great thru Grand Master, and U-Z for Legendary thru Legendary+5). A-E for Great through Grand Master, and U-Z for Legendary through Legendary+5).
Cells with teal backgrounds denote skills not controlled by labors, e.g. Cells with teal backgrounds denote skills not controlled by labors, e.g.
military and social skills. military and social skills.
@ -418,7 +421,7 @@ Press ``t`` to toggle between Profession and Squad view.
Use the arrow keys or number pad to move the cursor around, holding Shift to Use the arrow keys or number pad to move the cursor around, holding Shift to
move 10 tiles at a time. move 10 tiles at a time.
Press the Z-Up (<) and Z-Down (>) keys to move quickly between labor/skill Press the Z-Up (``<``) and Z-Down (``>``) keys to move quickly between labor/skill
categories. The numpad Z-Up and Z-Down keys seek to the first or last unit categories. The numpad Z-Up and Z-Down keys seek to the first or last unit
in the list. Backspace seeks to the top left corner. in the list. Backspace seeks to the top left corner.
@ -443,7 +446,7 @@ The following mouse shortcuts are also available:
* Left-click on a unit's name, profession or squad to view its properties. * Left-click on a unit's name, profession or squad to view its properties.
* Right-click on a unit's name, profession or squad to zoom to it. * Right-click on a unit's name, profession or squad to zoom to it.
Pressing ESC normally returns to the unit screen, but Shift-ESC would exit Pressing ``ESC`` normally returns to the unit screen, but ``Shift-ESC`` would exit
directly to the main dwarf mode screen. directly to the main dwarf mode screen.
search search
@ -455,7 +458,7 @@ Noble (assignment candidates), Military (position candidates), Burrows
.. image:: images/search.png .. image:: images/search.png
Searching works the same way as the search option in "Move to Depot" does. Searching works the same way as the search option in "Move to Depot" does.
You will see the Search option displayed on screen with a hotkey (usually 's'). You will see the Search option displayed on screen with a hotkey (usually ``s``).
Pressing it lets you start typing a query and the relevant list will start Pressing it lets you start typing a query and the relevant list will start
filtering automatically. filtering automatically.
@ -463,16 +466,16 @@ Pressing ENTER, ESC or the arrow keys will return you to browsing the now
filtered list, which still functions as normal. You can clear the filter filtered list, which still functions as normal. You can clear the filter
by either going back into search mode and backspacing to delete it, or by either going back into search mode and backspacing to delete it, or
pressing the "shifted" version of the search hotkey while browsing the pressing the "shifted" version of the search hotkey while browsing the
list (e.g. if the hotkey is 's', then hitting 'shift-s' will clear any list (e.g. if the hotkey is ``s``, then hitting ``Shift-s`` will clear any
filter). filter).
Leaving any screen automatically clears the filter. Leaving any screen automatically clears the filter.
In the Trade screen, the actual trade will always only act on items that In the Trade screen, the actual trade will always only act on items that
are actually visible in the list; the same effect applies to the Trade are actually visible in the list; the same effect applies to the Trade
Value numbers displayed by the screen. Because of this, the 't' key is Value numbers displayed by the screen. Because of this, the ``t`` key is
blocked while search is active, so you have to reset the filters first. blocked while search is active, so you have to reset the filters first.
Pressing Alt-C will clear both search strings. Pressing ``Alt-C`` will clear both search strings.
In the stockpile screen the option only appears if the cursor is in the In the stockpile screen the option only appears if the cursor is in the
rightmost list: rightmost list:
@ -520,7 +523,7 @@ preferred material type.
.. image:: images/automaterial-mat.png .. image:: images/automaterial-mat.png
Pressing 'a' while highlighting any material will enable that material for "auto select" Pressing ``a`` while highlighting any material will enable that material for "auto select"
for this construction type. You can enable multiple materials as autoselect. Now the next for this construction type. You can enable multiple materials as autoselect. Now the next
time you place this type of construction, the plugin will automatically choose materials time you place this type of construction, the plugin will automatically choose materials
for you from the kinds you enabled. If there is enough to satisfy the whole placement, for you from the kinds you enabled. If there is enough to satisfy the whole placement,
@ -531,10 +534,10 @@ When choosing the construction placement, you will see a couple of options:
.. image:: images/automaterial-pos.png .. image:: images/automaterial-pos.png
Use 'a' here to temporarily disable the material autoselection, e.g. if you need Use ``a`` here to temporarily disable the material autoselection, e.g. if you need
to go to the material selection screen so you can toggle some materials on or off. to go to the material selection screen so you can toggle some materials on or off.
The other option (auto type selection, off by default) can be toggled on with 't'. If you The other option (auto type selection, off by default) can be toggled on with ``t``. If you
toggle this option on, instead of returning you to the main construction menu after selecting toggle this option on, instead of returning you to the main construction menu after selecting
materials, it returns you back to this screen. If you use this along with several autoselect materials, it returns you back to this screen. If you use this along with several autoselect
enabled materials, you should be able to place complex constructions more conveniently. enabled materials, you should be able to place complex constructions more conveniently.
@ -546,13 +549,16 @@ Implements several confirmation dialogs for potentially destructive actions
Usage: Usage:
* ``enable confirm`` or ``confirm enable all``: Enable all confirmations (replace with ``disable`` to disable) :enable confirm, confirm enable all:
* ``confirm enable option1 [option2...]``: Enable (or disable) specific confirmations. Run ``confirm help`` for a complete list of options. Enable all confirmations (replace with ``disable`` to disable)
:confirm enable option1 [option2...]:
Enable (or disable) specific confirmations. Run ``confirm help``
for a complete list of options.
follow follow
------ ------
Makes the game view follow the currently highlighted unit after you exit from Makes the game view follow the currently highlighted unit after you exit from the
current menu/cursor mode. Handy for watching dwarves running around. Deactivated current menu or cursor mode. Handy for watching dwarves running around. Deactivated
by moving the view manually. by moving the view manually.
.. _plugins/resume: .. _plugins/resume:
@ -597,10 +603,10 @@ See `scripts/gui/stockpiles` for an in-game interface.
:loadstock: Loads a saved stockpile settings file and applies it to the currently selected :loadstock: Loads a saved stockpile settings file and applies it to the currently selected
stockpile. eg: ``loadstock food_settings.dfstock`` stockpile. eg: ``loadstock food_settings.dfstock``
To use savestock and loadstock, use the 'q' command to highlight a stockpile. To use savestock and loadstock, use the ``q`` command to highlight a stockpile.
Then run savestock giving it a descriptive filename. Then, in a different (or Then run savestock giving it a descriptive filename. Then, in a different (or
same!) gameworld, you can highlight any stockpile with 'q' then execute the the same!) gameworld, you can highlight any stockpile with ``q`` then execute the
'loadstock' command passing it the name of that file. The settings will be ``loadstock`` command passing it the name of that file. The settings will be
applied to that stockpile. applied to that stockpile.
Note that files are relative to the DF folder, so put your files there or in a Note that files are relative to the DF folder, so put your files there or in a
@ -619,7 +625,7 @@ When querying a stockpile, options will appear to toggle automation settings for
When automelt is enabled for a stockpile, any meltable items placed in it will be designated When automelt is enabled for a stockpile, any meltable items placed in it will be designated
to be melted. When autotrade is enabled for a stockpile, any items placed in it will be to be melted. When autotrade is enabled for a stockpile, any items placed in it will be
designated to be taken to the Trade Depot whenever merchants are on the map. designated to be taken to the Trade Depot whenever merchants are on the map.
When autotrade is enabled for a stockpile, any items placed in this stockpile will When autodump is enabled for a stockpile, any items placed in this stockpile will
automatically be designated to be dumped. automatically be designated to be dumped.
.. _plugins/rename: .. _plugins/rename:
@ -647,24 +653,17 @@ Options:
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 `the Bay12 forum thread`_. black color in palette to non totally black. For more info see
`the Bay12 Rendermax thread <http://www.bay12forums.com/smf/index.php?topic=128487>`_.
.. _`the Bay12 forum thread`: http://www.bay12forums.com/smf/index.php?topic=128487
Options: Options:
``rendermax trippy`` :trippy: Randomizes the color of each tiles. Used for fun, or testing.
Randomizes the color of each tiles. Used for fun, or testing. :light: Enable lighting engine.
``rendermax light`` :light reload: Reload the settings file.
Enable lighting engine. :light sun <x>|cycle: Set time to <x> (in hours) or set it to df time cycle.
``rendermax light reload`` :occlusionON, occlusionOFF: Show debug occlusion info.
Reload the settings file. :disable: Disable any filter that is enabled.
``rendermax light sun <x>|cycle``
Set time to <x> (in hours) or set it to df time cycle.
``rendermax occlusionON|occlusionOFF``
Show debug occlusion info.
``rendermax disable``
Disable any filter that is enabled.
An image showing lava and dragon breath. Not pictured here: sunlight, shining items/plants, An image showing lava and dragon breath. Not pictured here: sunlight, shining items/plants,
materials that color the light etc... materials that color the light etc...
@ -682,25 +681,25 @@ expansion while digging.
Options: Options:
**enable feature ...** :enable feature ...:
Enable features of the plugin. Enable features of the plugin.
**disable feature ...** :disable feature ...:
Disable features of the plugin. Disable features of the plugin.
**clear-unit burrow burrow ...** :clear-unit burrow burrow ...:
Remove all units from the burrows. Remove all units from the burrows.
**clear-tiles burrow burrow ...** :clear-tiles burrow burrow ...:
Remove all tiles from the burrows. Remove all tiles from the burrows.
**set-units target-burrow src-burrow ...** :set-units target-burrow src-burrow ...:
Clear target, and adds units from source burrows. Clear target, and adds units from source burrows.
**add-units target-burrow src-burrow ...** :add-units target-burrow src-burrow ...:
Add units from the source burrows to the target. Add units from the source burrows to the target.
**remove-units target-burrow src-burrow ...** :remove-units target-burrow src-burrow ...:
Remove units in source burrows from the target. Remove units in source burrows from the target.
**set-tiles target-burrow src-burrow ...** :set-tiles target-burrow src-burrow ...:
Clear target and adds tiles from the source burrows. Clear target and adds tiles from the source burrows.
**add-tiles target-burrow src-burrow ...** :add-tiles target-burrow src-burrow ...:
Add tiles from the source burrows to the target. Add tiles from the source burrows to the target.
**remove-tiles target-burrow src-burrow ...** :remove-tiles target-burrow src-burrow ...:
Remove tiles in source burrows from the target. Remove tiles in source burrows from the target.
For these three options, in place of a source burrow it is For these three options, in place of a source burrow it is
@ -714,18 +713,22 @@ Features:
This final '+' may be omitted in burrow name args of commands above. This final '+' may be omitted in burrow name args of commands above.
Digging 1-wide corridors with the miner inside the burrow is SLOW. Digging 1-wide corridors with the miner inside the burrow is SLOW.
dig
---
This plugin makes many automated or complicated dig patterns easy.
digv digv
---- ~~~~
Designates a whole vein for digging. Requires an active in-game cursor placed Designates a whole vein for digging. Requires an active in-game cursor placed
over a vein tile. With the 'x' option, it will traverse z-levels (putting stairs over a vein tile. With the 'x' option, it will traverse z-levels (putting stairs
between the same-material tiles). between the same-material tiles).
digvx digvx
----- ~~~~~
A permanent alias for 'digv x'. A permanent alias for 'digv x'.
digl digl
---- ~~~~
Designates layer stone for digging. Requires an active in-game cursor placed Designates layer stone for digging. Requires an active in-game cursor placed
over a layer stone tile. With the 'x' option, it will traverse z-levels over a layer stone tile. With the 'x' option, it will traverse z-levels
(putting stairs between the same-material tiles). With the 'undo' option it (putting stairs between the same-material tiles). With the 'undo' option it
@ -733,11 +736,11 @@ will remove the dig designation instead (if you realize that digging out a 50
z-level deep layer was not such a good idea after all). z-level deep layer was not such a good idea after all).
diglx diglx
----- ~~~~~
A permanent alias for 'digl x'. A permanent alias for 'digl x'.
digexp digexp
------ ~~~~~~
This command is for `exploratory mining`_. This command is for `exploratory mining`_.
.. _`exploratory mining`: http://dwarffortresswiki.org/index.php/cv:Exploratory_mining .. _`exploratory mining`: http://dwarffortresswiki.org/index.php/cv:Exploratory_mining
@ -771,7 +774,7 @@ Examples:
Take current designations and replace them with the ladder pattern Take current designations and replace them with the ladder pattern
digcircle digcircle
--------- ~~~~~~~~~
A command for easy designation of filled and hollow circles. A command for easy designation of filled and hollow circles.
It has several types of options. It has several types of options.
@ -801,11 +804,13 @@ repeats with the last selected parameters.
Examples: Examples:
* 'digcircle filled 3' = Dig a filled circle with diameter = 3. ``digcircle filled 3``
* 'digcircle' = Do it again. Dig a filled circle with diameter = 3.
``digcircle``
Do it again.
digtype digtype
------- ~~~~~~~
For every tile on the map of the same vein type as the selected tile, this command designates it to have the same designation as the selected tile. If the selected tile has no designation, they will be dig designated. For every tile on the map of the same vein type as the selected tile, this command designates it to have the same designation as the selected tile. If the selected tile has no designation, they will be dig designated.
If an argument is given, the designation of the selected tile is ignored, and all appropriate tiles are set to the specified designation. If an argument is given, the designation of the selected tile is ignored, and all appropriate tiles are set to the specified designation.
@ -897,9 +902,9 @@ Options:
:-c: Clear designations instead of setting them :-c: Clear designations instead of setting them
:-x: Apply selected action to all plants except those specified (invert :-x: Apply selected action to all plants except those specified (invert
selection) selection)
:-a: Select every type of plant (obeys -t/-s) :-a: Select every type of plant (obeys ``-t``/``-s``)
Specifying both -t and -s will have no effect. If no plant IDs are specified, Specifying both ``-t`` and ``-s`` will have no effect. If no plant IDs are specified,
all valid plant IDs will be listed. all valid plant IDs will be listed.
@ -921,8 +926,10 @@ which dwarf or dwarves should take new jobs for that labor, and sets labors acco
Labors with equiptment (mining, hunting, and woodcutting), which are abandoned Labors with equiptment (mining, hunting, and woodcutting), which are abandoned
if labors change mid-job, are handled slightly differently to minimise churn. if labors change mid-job, are handled slightly differently to minimise churn.
*Warning: autolabor will override any manual changes you make to labors* .. warning::
*while it is enabled, including through other tools such as Dwarf Therapist*
*autolabor will override any manual changes you make to labors while
it is enabled, including through other tools such as Dwarf Therapist*
Simple usage: Simple usage:
@ -931,28 +938,6 @@ Simple usage:
Anything beyond this is optional - autolabor works well on the default settings. Anything beyond this is optional - autolabor works well on the default settings.
Advanced usage:
:autolabor <labor> <minimum> [<maximum>]:
Set number of dwarves assigned to a labor.
:autolabor <labor> haulers: Set a labor to be handled by hauler dwarves.
:autolabor <labor> disable: Turn off autolabor for a specific labor.
:autolabor <labor> reset: Return a labor to the default handling.
:autolabor reset-all: Return all labors to the default handling.
:autolabor list: List current status of all labors.
:autolabor status: Show basic status information.
See `scripts/autolabor-artisans` for a differently-tunde setup.
Examples:
:autolabor MINE: Keep at least 5 dwarves with mining enabled.
:autolabor CUT_GEM 1 1: Keep exactly 1 dwarf with gemcutting enabled.
:autolabor COOK 1 1 3: Keep 1 dwarf with cooking enabled, selected only from the top 3.
:autolabor FEED_WATER_CIVILIANS haulers:
Have haulers feed and water wounded dwarves.
:autolabor CUTWOOD disable: Turn off autolabor for wood cutting.
By default, each labor is assigned to between 1 and 200 dwarves (2-200 for mining). By default, each labor is assigned to between 1 and 200 dwarves (2-200 for mining).
By default 33% of the workforce become haulers, who handle all hauling jobs as well By default 33% of the workforce become haulers, who handle all hauling jobs as well
as cleaning, pulling levers, recovering wounded, removing constructions, and filling ponds. as cleaning, pulling levers, recovering wounded, removing constructions, and filling ponds.
@ -974,6 +959,31 @@ and then assign additional dwarfs that meet any of these conditions:
We stop assigning dwarfs when we reach the maximum allowed. We stop assigning dwarfs when we reach the maximum allowed.
Advanced usage:
:autolabor <labor> <minimum> [<maximum>]:
Set number of dwarves assigned to a labor.
:autolabor <labor> haulers: Set a labor to be handled by hauler dwarves.
:autolabor <labor> disable: Turn off autolabor for a specific labor.
:autolabor <labor> reset: Return a labor to the default handling.
:autolabor reset-all: Return all labors to the default handling.
:autolabor list: List current status of all labors.
:autolabor status: Show basic status information.
See `scripts/autolabor-artisans` for a differently-tunde setup.
Examples:
``autolabor MINE``
Keep at least 5 dwarves with mining enabled.
``autolabor CUT_GEM 1 1``
Keep exactly 1 dwarf with gemcutting enabled.
``autolabor COOK 1 1 3``
Keep 1 dwarf with cooking enabled, selected only from the top 3.
``autolabor FEED_WATER_CIVILIANS haulers``
Have haulers feed and water wounded dwarves.
``autolabor CUTWOOD disable``
Turn off autolabor for wood cutting.
Job management Job management
@ -1038,10 +1048,10 @@ Usage:
``stockflow status`` ``stockflow status``
Display whether the plugin is enabled. Display whether the plugin is enabled.
While enabled, the 'q' menu of each stockpile will have two new options: While enabled, the ``q`` menu of each stockpile will have two new options:
* j: Select a job to order, from an interface like the manager's screen. * ``j``: Select a job to order, from an interface like the manager's screen.
* J: Cycle between several options for how many such jobs to order. * ``J``: Cycle between several options for how many such jobs to order.
Whenever the bookkeeper updates stockpile records, new work orders will Whenever the bookkeeper updates stockpile records, new work orders will
be placed on the manager's queue for each such selection, reduced by the be placed on the manager's queue for each such selection, reduced by the
@ -1098,15 +1108,14 @@ the frequency of jobs being toggled.
Constraint format Constraint format
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
The constraint 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 page`_ for more info. for a custom reaction input. For more information, see
`this page. <http://dwarffortresswiki.org/index.php/Material_token>`_
.. _`this page`: http://dwarffortresswiki.org/index.php/Material_token
The subsequent parts are optional: The subsequent parts are optional:
@ -1117,11 +1126,9 @@ The subsequent parts are optional:
METAL STONE SAND GLASS CLAY MILK METAL STONE SAND GLASS CLAY MILK
- 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 the link above for more details on the unabbreviated raw syntax.
.. _`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.
@ -1176,6 +1183,8 @@ Maintain 10-100 locally-made crafts of exceptional quality::
Cleanup and garbage disposal Cleanup and garbage disposal
============================ ============================
.. _plugins/clean:
clean clean
----- -----
Cleans all the splatter that get scattered all over the map, items and Cleans all the splatter that get scattered all over the map, items and
@ -1188,15 +1197,15 @@ Options:
:units: Clean the creatures. Will also clean hostiles. :units: Clean the creatures. Will also clean hostiles.
:items: Clean all the items. Even a poisoned blade. :items: Clean all the items. Even a poisoned blade.
Extra options for 'map': Extra options for ``map``:
:mud: Remove mud in addition to the normal stuff. :mud: Remove mud in addition to the normal stuff.
:snow: Also remove snow coverings. :snow: Also remove snow coverings.
spotclean spotclean
--------- ---------
Works like 'clean map snow mud', but only for the tile under the cursor. Ideal Works like ``clean map snow mud``, but only for the tile under the cursor. Ideal
if you want to keep that bloody entrance 'clean map' would clean up. if you want to keep that bloody entrance ``clean map`` would clean up.
.. _plugins/autodump: .. _plugins/autodump:
@ -1218,8 +1227,8 @@ Options:
:forbidden: Only process forbidden items (default: only unforbidden). :forbidden: Only process forbidden items (default: only unforbidden).
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
a container. If called again before the game is resumed, cancels destroy. a container. If called again before the game is resumed, cancels destroy.
cleanowned cleanowned
@ -1252,18 +1261,13 @@ Records dwarf activity to measure fort efficiency.
Options: Options:
``dwarfmonitor enable <mode>``: :enable <mode>: Start monitoring ``mode``. ``mode`` can be "work", "misery",
Start monitoring ``mode``. ``mode`` can be "work", "misery", "weather", or "all". "weather", or "all". This will enable all corresponding widgets,
This will enable all corresponding widgets, if applicable. if applicable.
``dwarfmonitor disable <mode>``: :disable <mode>: Stop monitoring ``mode``, and disable corresponding widgets, if applicable.
Stop monitoring ``mode`` (see above) :stats: Show statistics summary
This will disable all corresponding widgets, if applicable. :prefs: Show dwarf preferences summary
``dwarfmonitor stats``: :reload: Reload configuration file (``dfhack-config/dwarfmonitor.json``)
Show statistics summary
``dwarfmonitor prefs``:
Show dwarf preferences summary
``dwarfmonitor reload``:
Reload configuration file (``dfhack-config/dwarfmonitor.json``)
Widget configuration: Widget configuration:
@ -1520,15 +1524,15 @@ opposite sex or have been gelded) will be butchered before those who will.
Older adults and younger children will be butchered first if the population Older adults and younger children will be butchered first if the population
is above the target (default 1 male, 5 female kids and adults). Note that is above the target (default 1 male, 5 female kids and adults). Note that
you may need to set a target above 1 to have a reliable breeding population you may need to set a target above 1 to have a reliable breeding population
due to asexuality etc. due to asexuality etc. See `scripts/fix-ster` if this is a problem.
Options: Options:
:example: Print some usage examples.
:start: Start running every X frames (df simulation ticks). :start: Start running every X frames (df simulation ticks).
Default: X=6000, which would be every 60 seconds at 100fps. Default: X=6000, which would be every 60 seconds at 100fps.
:stop: Stop running automatically. :stop: Stop running automatically.
:sleep: Must be followed by number X. Changes the timer to sleep :sleep <x>: Changes the timer to sleep X frames between runs.
X frames between runs.
:watch R: Start watching a race. R can be a valid race RAW id (ALPACA, :watch R: Start watching a race. R can be a valid race RAW id (ALPACA,
BIRD_TURKEY, etc) or a list of ids seperated by spaces or BIRD_TURKEY, etc) or a list of ids seperated by spaces or
the keyword 'all' which affects all races on your current the keyword 'all' which affects all races on your current
@ -1544,17 +1548,26 @@ Options:
:list: Print the current status and watchlist. :list: Print the current status and watchlist.
:list_export: Print the commands needed to set up status and watchlist, :list_export: Print the commands needed to set up status and watchlist,
which can be used to import them to another save (see notes). which can be used to import them to another save (see notes).
:target fk mk fa ma R: Set target count for specified race(s). :target <fk> <mk> <fa> <ma> <R>:
fk = number of female kids, Set target count for specified race(s). The first four arguments
mk = number of male kids, are the number of female and male kids, and female and male adults.
fa = number of female adults, R can be a list of spceies ids, or the keyword ``all`` or ``new``.
ma = number of female adults. ``R = 'all'``: change target count for all races on watchlist
R can be a list of ids or the keyword 'all' or 'new'. and set the new default for the future. ``R = 'new'``: don't touch
R = 'all': change target count for all races on watchlist
and set the new default for the future. R = 'new': don't touch
current settings on the watchlist, only set the new default current settings on the watchlist, only set the new default
for future entries. for future entries.
:example: Print some usage examples. :list_export: Print the commands required to rebuild your current settings.
.. note::
Settings and watchlist are stored in the savegame, so that you can have
different settings for each save. If you want to copy your watchlist to
another savegame you must export the commands required to recreate your settings.
To export, open an external terminal in the DF directory, and run
``dfhack-run autobutcher list_export > filename.txt``. To import, load your
new save and run ``script filename.txt`` in the DFHack terminal.
Examples: Examples:
@ -1562,8 +1575,7 @@ You want to keep max 7 kids (4 female, 3 male) and max 3 adults (2 female,
1 male) of the race alpaca. Once the kids grow up the oldest adults will get 1 male) of the race alpaca. Once the kids grow up the oldest adults will get
slaughtered. Excess kids will get slaughtered starting with the youngest slaughtered. Excess kids will get slaughtered starting with the youngest
to allow that the older ones grow into adults. Any unnamed cats will to allow that the older ones grow into adults. Any unnamed cats will
be slaughtered as soon as possible. be slaughtered as soon as possible. ::
::
autobutcher target 4 3 2 1 ALPACA BIRD_TURKEY autobutcher target 4 3 2 1 ALPACA BIRD_TURKEY
autobutcher target 0 0 0 0 CAT autobutcher target 0 0 0 0 CAT
@ -1572,8 +1584,7 @@ be slaughtered as soon as possible.
Automatically put all new races onto the watchlist and mark unnamed tame units Automatically put all new races onto the watchlist and mark unnamed tame units
for slaughter as soon as they arrive in your fort. Settings already made for slaughter as soon as they arrive in your fort. Settings already made
for specific races will be left untouched. for specific races will be left untouched. ::
::
autobutcher target 0 0 0 0 new autobutcher target 0 0 0 0 new
autobutcher autowatch autobutcher autowatch
@ -1588,16 +1599,6 @@ add some new races with 'watch'. If you simply want to stop it completely use
autobutcher unwatch ALPACA CAT autobutcher unwatch ALPACA CAT
**Note:**
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
another savegame you can export the commands required to recreate your settings.
To export, open an external terminal in the DF directory, and run
``dfhack-run autobutcher list_export > filename.txt``. To import, load your
new save and run ``script filename.txt`` in the DFHack terminal.
autochop autochop
--------- ---------
Automatically manage tree cutting designation to keep available logs withing given Automatically manage tree cutting designation to keep available logs withing given
@ -1632,18 +1633,13 @@ Usage:
advtools advtools
======== ========
A package of different adventure mode tools. A package of different adventure mode tools. Usage:
Usage: :list-equipped [all]: List armor and weapons equipped by your companions.
``list-equipped [all]``
List armor and weapons equipped by your companions.
If all is specified, also lists non-metal clothing. If all is specified, also lists non-metal clothing.
``metal-detector [all-types] [non-trader]`` :metal-detector [all-types] [non-trader]:
Reveal metal armor and weapons in Reveal metal armor and weapons in shops. The options
shops. The options disable the checks disable the checks on item type and being in shop.
on item type and being in shop.
================ ================
Map modification Map modification
@ -1662,7 +1658,9 @@ care to exactly preserve the mineral counts reported by `plugins/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.
Note that there is no undo option other than restoring from backup. .. warning::
There is no undo option other than restoring from backup.
changelayer changelayer
=========== ===========
@ -1673,7 +1671,7 @@ changes only the layer at the cursor position. Note that one layer can stretch
across lots of z levels. By default changes only the geology which is linked across lots of z levels. By default changes only the geology which is linked
to the biome under the cursor. That geology might be linked to other biomes to the biome under the cursor. That geology might be linked to other biomes
as well, though. Mineral veins and gem clusters will stay on the map. Use as well, though. Mineral veins and gem clusters will stay on the map. Use
'changevein' for them. `plugins/changevein` for them.
tl;dr: You will end up with changing quite big areas in one go, especially if tl;dr: You will end up with changing quite big areas in one go, especially if
you use it in lower z levels. Use with care. you use it in lower z levels. Use with care.
@ -1725,6 +1723,8 @@ Examples:
Try reverting the changes manually or even better use an older savegame. Try reverting the changes manually or even better use an older savegame.
You did save your game, right? You did save your game, right?
.. _plugins/changevein:
changevein changevein
========== ==========
Changes material of the vein under cursor to the specified inorganic RAW Changes material of the vein under cursor to the specified inorganic RAW
@ -1765,17 +1765,19 @@ Examples:
colonies colonies
======== ========
Allows listing all the vermin colonies on the map and optionally turning them into honey bee colonies. Allows listing all the vermin colonies on the map and optionally turning
them into honey bee colonies.
Options: Options:
:bees: turn colonies into honey bee colonies :bees: turn colonies into honey bee colonies
deramp 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
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). 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).
feature feature
======= =======
@ -1799,19 +1801,20 @@ fortplan
Usage: fortplan [filename] Usage: fortplan [filename]
Designates furniture for building according to a .csv file with Designates furniture for building according to a .csv file with
quickfort-style syntax. Companion to digfort. quickfort-style syntax. Companion to `scripts/digfort`.
The first line of the file must contain the following:: The first line of the file must contain the following::
#build start(X; Y; <start location description>) #build start(X; Y; <start location description>)
...where X and Y are the offset from the top-left corner of the file's area ...where X and Y are the offset from the top-left corner of the file's area
where the in-game cursor should be located, and <start location description> where the in-game cursor should be located, and ``<start location description>``
is an optional description of where that is. You may also leave a description is an optional description of where that is. You may also leave a description
of the contents of the file itself following the closing parenthesis on the of the contents of the file itself following the closing parenthesis on the
same line. 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 `scripts/digfort` or
`quickfort <http://www.bay12forums.com/smf/index.php?topic=35931>`_. 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::
@ -1855,6 +1858,8 @@ dfhack command line and can't be used from a hotkey. Settings will be remembered
as long as dfhack runs. Intended for use in combination with the command as long as dfhack runs. Intended for use in combination with the command
``liquids-here`` (which can be bound to a hotkey). ``liquids-here`` (which can be bound to a hotkey).
See also `this issue. <https://github.com/DFHack/dfhack/issues/80>`_
.. note:: .. note::
Spawning and deleting liquids can F up pathing data and Spawning and deleting liquids can F up pathing data and
@ -1994,7 +1999,7 @@ This will change the brush to a rectangle spanning 10x10 tiles on one z-level.
The range starts at the position of the cursor and goes to the east, south and The range starts at the position of the cursor and goes to the east, south and
up. up.
For more details, see the 'help' command while using this. For more details, use ``tiletypes help``.
tiletypes-command tiletypes-command
----------------- -----------------
@ -2093,24 +2098,24 @@ Options:
fastdwarf fastdwarf
========= =========
Controls speedydwarf and teledwarf. Speedydwarf makes dwarves move quickly and perform tasks quickly. Teledwarf makes dwarves move instantaneously, but do jobs at the same speed. Controls speedydwarf and teledwarf. Speedydwarf makes dwarves move quickly
and perform tasks quickly. Teledwarf makes dwarves move instantaneously,
but do jobs at the same speed.
* 'fastdwarf 0 0' disables both :fastdwarf 0: disables both (also ``0 0``)
* 'fastdwarf 0 1' disables speedydwarf and enables teledwarf :fastdwarf 1: enables speedydwarf and disables teledwarf (also ``1 0``)
* 'fastdwarf 1 0' enables speedydwarf and disables teledwarf :fastdwarf 2: sets a native debug flag in the game memory that implements an
* 'fastdwarf 1 1' enables both even more aggressive version of speedydwarf.
* 'fastdwarf 0' disables both :fastdwarf 0 1: disables speedydwarf and enables teledwarf
* 'fastdwarf 1' enables speedydwarf and disables teledwarf :fastdwarf 1 1: enables both
* 'fastdwarf 2 ...' sets a native debug flag in the game memory
that implements an even more aggressive version of speedydwarf.
lair lair
==== ====
This command allows you to mark the map as 'monster lair', preventing item This command allows you to mark the map as a monster lair, preventing item
scatter on abandon. When invoked as 'lair reset', it does the opposite. scatter on abandon. When invoked as ``lair reset``, it does the opposite.
Unlike reveal, this command doesn't save the information about tiles - you Unlike `plugins/reveal`, this command doesn't save the information about tiles - you
won't be able to restore state of real monster lairs using 'lair reset'. won't be able to restore state of real monster lairs using ``lair reset``.
Options: Options:
@ -2134,21 +2139,24 @@ Usage:
mode mode
==== ====
This command lets you see and change the game mode directly. This command lets you see and change the game mode directly.
.. warning::
Only use ``mode`` after making a backup of your save!
Not all combinations are good for every situation and most of them will Not all combinations are good for every situation and most of them will
produce undesirable results. There are a few good ones though. produce undesirable results. There are a few good ones though.
.. admonition:: Example Examples:
You are in fort game mode, managing your fortress and paused. * You are in fort game mode, managing your fortress and paused.
You switch to the arena game mode, *assume control of a creature* and then * You switch to the arena game mode, *assume control of a creature* and then
switch to adventure game mode(1). * switch to adventure game mode(1).
You just lost a fortress and gained an adventurer. You just lost a fortress and gained an adventurer. Alternatively:
OR
You are in fort game mode, managing your fortress and paused at the esc menu.
You switch to the adventure game mode, assume control of a creature, then save or retire.
You just created a returnable mountain home and gained an adventurer.
Only use ``mode`` after making a backup of your save! * You are in fort game mode, managing your fortress and paused at the esc menu.
* You switch to the adventure game mode, assume control of a creature, then save or retire.
* You just created a returnable mountain home and gained an adventurer.
strangemood strangemood
=========== ===========
@ -2156,12 +2164,17 @@ Creates a strange mood job the same way the game itself normally does it.
Options: Options:
:-force: Ignore normal strange mood preconditions (no recent mood, minimum moodable population, artifact limit not reached). :-force: Ignore normal strange mood preconditions (no recent mood, minimum
:-unit: Make the strange mood strike the selected unit instead of picking one randomly. Unit eligibility is still enforced. moodable population, artifact limit not reached).
:-type T: Force the mood to be of a particular type instead of choosing randomly based on happiness. :-unit: Make the strange mood strike the selected unit instead of picking
Valid values are "fey", "secretive", "possessed", "fell", and "macabre". one randomly. Unit eligibility is still enforced.
:-type <T>: Force the mood to be of a particular type instead of choosing randomly based on happiness.
Valid values for Tare "fey", "secretive", "possessed", "fell", and "macabre".
:-skill S: Force the mood to use a specific skill instead of choosing the highest moodable skill. :-skill S: Force the mood to use a specific skill instead of choosing the highest moodable skill.
Valid values are "miner", "carpenter", "engraver", "mason", "tanner", "weaver", "clothier", "weaponsmith", "armorsmith", "metalsmith", "gemcutter", "gemsetter", "woodcrafter", "stonecrafter", "metalcrafter", "glassmaker", "leatherworker", "bonecarver", "bowyer", and "mechanic". Valid values are "miner", "carpenter", "engraver", "mason", "tanner", "weaver",
"clothier", "weaponsmith", "armorsmith", "metalsmith", "gemcutter", "gemsetter",
"woodcrafter", "stonecrafter", "metalcrafter", "glassmaker", "leatherworker",
"bonecarver", "bowyer", and "mechanic".
Known limitations: if the selected unit is currently performing a job, the mood will not be started. Known limitations: if the selected unit is currently performing a job, the mood will not be started.
@ -2177,23 +2190,21 @@ objects to add features not otherwise present.
Siege Engine Siege Engine
------------ ------------
The siege-engine plugin enables siege engines to be linked to stockpiles, and
aimed at an arbitrary rectangular area across Z levels, instead of the original
four directions. Also, catapults can be ordered to load arbitrary objects, not
just stones.
Rationale
~~~~~~~~~
Siege engines are a very interesting feature, but sadly almost useless in the current state Siege engines are a very interesting feature, but sadly almost useless in the current state
because they haven't been updated since 2D and can only aim in four directions. This is an because they haven't been updated since 2D and can only aim in four directions. This is an
attempt to bring them more up to date until Toady has time to work on it. Actual improvements, attempt to bring them more up to date until Toady has time to work on it. Actual improvements,
e.g. like making siegers bring their own, are something only Toady can do. e.g. like making siegers bring their own, are something only Toady can do.
The siege-engine plugin enables siege engines to be linked to stockpiles, and
aimed at an arbitrary rectangular area across Z levels, instead of the original
four directions. Also, catapults can be ordered to load arbitrary objects, not
just stones.
Configuration UI Configuration UI
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
The configuration front-end to the plugin is implemented by `scripts/gui/siege-engine`. The configuration front-end to the plugin is implemented by `scripts/gui/siege-engine`.
Bind it to a key (the example config uses Alt-A) and activate after selecting Bind it to a key (the example config uses Alt-A) and activate after selecting
a siege engine in 'q' mode. a siege engine in ``q`` mode.
.. image:: images/siege-engine.png .. image:: images/siege-engine.png
@ -2202,19 +2213,19 @@ the allowed operator skill range. The map tile color is changed to signify if it
hit by the selected engine: green for fully reachable, blue for out of range, red for blocked, hit by the selected engine: green for fully reachable, blue for out of range, red for blocked,
yellow for partially blocked. yellow for partially blocked.
Pressing 'r' changes into the target selection mode, which works by highlighting two points Pressing ``r`` changes into the target selection mode, which works by highlighting two points
with Enter like all designations. When a target area is set, the engine projectiles are with Enter like all designations. When a target area is set, the engine projectiles are
aimed at that area, or units within it (this doesn't actually change the original aiming aimed at that area, or units within it (this doesn't actually change the original aiming
code, instead the projectile trajectory parameters are rewritten as soon as it appears). code, instead the projectile trajectory parameters are rewritten as soon as it appears).
After setting the target in this way for one engine, you can 'paste' the same area into others After setting the target in this way for one engine, you can 'paste' the same area into others
just by pressing 'p' in the main page of this script. The area to paste is kept until you quit just by pressing ``p`` in the main page of this script. The area to paste is kept until you quit
DF, or select another area manually. DF, or select another area manually.
Pressing 't' switches to a mode for selecting a stockpile to take ammo from. Pressing ``t`` switches to a mode for selecting a stockpile to take ammo from.
Exiting from the siege engine script via ESC reverts the view to the state prior to starting Exiting from the siege engine script via ESC reverts the view to the state prior to starting
the script. Shift-ESC retains the current viewport, and also exits from the 'q' mode to main the script. Shift-ESC retains the current viewport, and also exits from the ``q`` mode to main
menu. menu.
.. _plugins/power-meter: .. _plugins/power-meter:
@ -2238,8 +2249,6 @@ Steam Engine
The steam-engine plugin detects custom workshops with STEAM_ENGINE in The steam-engine plugin detects custom workshops with STEAM_ENGINE in
their token, and turns them into real steam engines. their token, and turns them into real steam engines.
Rationale
~~~~~~~~~
The vanilla game contains only water wheels and windmills as sources of The vanilla game contains only water wheels and windmills as sources of
power, but windmills give relatively little power, and water wheels require power, but windmills give relatively little power, and water wheels require
flowing water, which must either be a real river and thus immovable and flowing water, which must either be a real river and thus immovable and
@ -2334,7 +2343,7 @@ Add Spatter
This plugin makes reactions with names starting with ``SPATTER_ADD_`` This plugin makes reactions with names starting with ``SPATTER_ADD_``
produce contaminants on the items instead of improvements. The produced produce contaminants on the items instead of improvements. The produced
contaminants are immune to being washed away by water or destroyed by contaminants are immune to being washed away by water or destroyed by
the ``clean items`` command. the `plugins/clean` ``items`` command.
The plugin is intended to give some use to all those poisons that can The plugin is intended to give some use to all those poisons that can
be bought from caravans. :) be bought from caravans. :)

@ -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
@ -502,6 +503,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
======================== ========================
@ -637,7 +640,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.
@ -683,6 +687,8 @@ If the name of the patch has no extension or directory separators, the
script uses ``hack/patches/<df-version>/<name>.dif``, thus auto-selecting script uses ``hack/patches/<df-version>/<name>.dif``, thus auto-selecting
the version appropriate for the currently loaded executable. the version appropriate for the currently loaded executable.
.. _scripts/brainwash:
brainwash brainwash
========= =========
Modify the personality traits of the selected dwarf to match an 'ideal' Modify the personality traits of the selected dwarf to match an 'ideal'
@ -739,6 +745,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.
@ -763,18 +771,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,
@ -839,6 +851,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
@ -1047,6 +1061,8 @@ Usage:
:region-pops incr-all <pattern> <factor>: :region-pops incr-all <pattern> <factor>:
Same as above, but match using a pattern acceptable to list. Same as above, but match using a pattern acceptable to list.
.. _scripts/rejuvenate:
rejuvenate rejuvenate
========== ==========
Set the age of the selected dwarf to 20 years. Useful if valuable citizens are Set the age of the selected dwarf to 20 years. Useful if valuable citizens are