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.
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
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.
Commented lines are skipped, so it is possible to comment out parts of a command with the ``#`` character.
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. 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
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,
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
@ -259,15 +273,6 @@ arguments for the command::
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.
Take current designations and replace them with the ladder pattern
digcircle
---------
~~~~~~~~~
A command for easy designation of filled and hollow circles.
It has several types of options.
@ -801,11 +804,13 @@ repeats with the last selected parameters.
Examples:
* 'digcircle filled 3' = Dig a filled circle with diameter = 3.
* 'digcircle' = Do it again.
``digcircle filled 3``
Dig a filled circle with diameter = 3.
``digcircle``
Do it again.
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.
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
:-x:Apply selected action to all plants except those specified (invert
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.
@ -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
if labors change mid-job, are handled slightly differently to minimise churn.
*Warning: autolabor will override any manual changes you make to labors*
*while it is enabled, including through other tools such as Dwarf Therapist*
..warning::
*autolabor will override any manual changes you make to labors while
it is enabled, including through other tools such as Dwarf Therapist*
Simple usage:
@ -931,28 +938,6 @@ Simple usage:
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 33% of the workforce become haulers, who handle all hauling jobs as well
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.
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
@ -1038,10 +1048,10 @@ Usage:
``stockflow status``
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: Cycle between several options for how many such jobs to order.
* ``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.
Whenever the bookkeeper updates stockpile records, new work orders will
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
~~~~~~~~~~~~~~~~~
The constraint spec consists of 4 parts, separated with '/' characters::
The constraint spec consists of 4 parts, separated with ``/`` characters::
@ -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
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
due to asexuality etc.
due to asexuality etc. See `scripts/fix-ster` if this is a problem.
Options:
:example:Print some usage examples.
:start:Start running every X frames (df simulation ticks).
Default: X=6000, which would be every 60 seconds at 100fps.
:stop:Stop running automatically.
:sleep:Must be followed by number X. Changes the timer to sleep
X frames between runs.
:sleep <x>:Changes the timer to sleep X frames between runs.
: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
the keyword 'all' which affects all races on your current
@ -1544,26 +1548,34 @@ Options:
:list:Print the current 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).
:target fk mk fa ma R:Set target count for specified race(s).
fk = number of female kids,
mk = number of male kids,
fa = number of female adults,
ma = number of female adults.
R can be a list of ids or the keyword 'all' or 'new'.
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
for future entries.
:example:Print some usage examples.
:target <fk> <mk> <fa> <ma> <R>:
Set target count for specified race(s). The first four arguments
are the number of female and male kids, and female and male adults.
R can be a list of spceies ids, or the keyword ``all`` or ``new``.
``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
for future entries.
: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:
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
slaughtered. Excess kids will get slaughtered starting with the youngest
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 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
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 autowatch
@ -1584,20 +1595,10 @@ settings so that you can use 'unwatch' without the need to enter the
values again. Note: 'autobutcher unwatch all' works, but only makes sense
if you want to keep the plugin running with the 'autowatch' feature or manually
add some new races with 'watch'. If you simply want to stop it completely use
'autobutcher stop' instead.::
'autobutcher stop' instead.::
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
---------
Automatically manage tree cutting designation to keep available logs withing given
@ -1632,18 +1633,13 @@ Usage:
advtools
========
A package of different adventure mode tools.
Usage:
``list-equipped [all]``
List armor and weapons equipped by your companions.
If all is specified, also lists non-metal clothing.
``metal-detector [all-types] [non-trader]``
Reveal metal armor and weapons in
shops. The options disable the checks
on item type and being in shop.
A package of different adventure mode tools. Usage:
:list-equipped [all]:List armor and weapons equipped by your companions.
If all is specified, also lists non-metal clothing.
:metal-detector [all-types] [non-trader]:
Reveal metal armor and weapons in shops. The options
disable the checks on item type and being in shop.
================
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
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
===========
@ -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
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
'changevein' for them.
`plugins/changevein` for them.
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.
@ -1725,6 +1723,8 @@ Examples:
Try reverting the changes manually or even better use an older savegame.
You did save your game, right?
.._plugins/changevein:
changevein
==========
Changes material of the vein under cursor to the specified inorganic RAW
@ -1765,17 +1765,19 @@ Examples:
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:
:bees:turn colonies into honey bee colonies
deramp
======
Removes all ramps designated for removal from the map. This is useful for replicating the old channel digging designation.
It also removes any and all 'down ramps' that can remain after a cave-in (you don't have to designate anything for that to happen).
Removes all ramps designated for removal from the map. This is useful for
replicating the old channel digging designation. It also removes any and
all 'down ramps' that can remain after a cave-in (you don't have to designate
anything for that to happen).
feature
=======
@ -1799,19 +1801,20 @@ fortplan
Usage: fortplan [filename]
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::
#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 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
of the contents of the file itself following the closing parenthesis on the
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
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
``liquids-here`` (which can be bound to a hotkey).
See also `this issue. <https://github.com/DFHack/dfhack/issues/80>`_
..note::
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
up.
For more details, see the 'help' command while using this.
For more details, use ``tiletypes help``.
tiletypes-command
-----------------
@ -2093,29 +2098,29 @@ Options:
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 1' disables speedydwarf and enables teledwarf
* 'fastdwarf 1 0' enables speedydwarf and disables teledwarf
* 'fastdwarf 1 1' enables both
* 'fastdwarf 0' disables both
* 'fastdwarf 1' enables speedydwarf and disables teledwarf
* 'fastdwarf 2 ...' sets a native debug flag in the game memory
that implements an even more aggressive version of speedydwarf.
:fastdwarf 0:disables both (also ``0 0``)
:fastdwarf 1:enables speedydwarf and disables teledwarf (also ``1 0``)
:fastdwarf 2:sets a native debug flag in the game memory that implements an
even more aggressive version of speedydwarf.
:fastdwarf 0 1:disables speedydwarf and enables teledwarf
:fastdwarf 1 1:enables both
lair
====
This command allows you to mark the map as 'monster lair', preventing item
scatter on abandon. When invoked as 'lair reset', it does the opposite.
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.
Unlike 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'.
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``.
Options:
:lair:Mark the map as monster lair
:lair reset:Mark the map as ordinary (not lair)
:lair:Mark the map as monster lair
:lair reset:Mark the map as ordinary (not lair)
misery
======
@ -2134,21 +2139,24 @@ Usage:
mode
====
This command lets you see and change the game mode directly.
Not all combinations are good for every situation and most of them will
produce undesirable results. There are a few good ones though.
..admonition:: Example
..warning::
Only use ``mode`` after making a backup of your save!
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
switch to adventure game mode(1).
You just lost a fortress and gained an adventurer.
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.
Not all combinations are good for every situation and most of them will
produce undesirable results. There are a few good ones though.
Only use ``mode`` after making a backup of your save!
Examples:
* 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
* switch to adventure game mode(1).
You just lost a fortress and gained an adventurer. Alternatively:
* 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
===========
@ -2156,12 +2164,17 @@ Creates a strange mood job the same way the game itself normally does it.
Options:
:-force:Ignore normal strange mood preconditions (no recent mood, minimum moodable population, artifact limit not reached).
:-unit:Make the strange mood strike the selected unit instead of picking one randomly. Unit eligibility is still enforced.
:-type T:Force the mood to be of a particular type instead of choosing randomly based on happiness.
Valid values are "fey", "secretive", "possessed", "fell", and "macabre".
:-skill S:Force the mood to use a specific skill instead of choosing the highest moodable skill.
PeridexisErrant