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.
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::
@ -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
current settings on the watchlist, only set the new default
and set the new default for the future. R = 'new': don't touch
for future entries.
current settings on the watchlist, only set the new default
:list_export:Print the commands required to rebuild your current settings.
for future entries.
:example:Print some usage examples.
..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
@ -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
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
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
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
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.
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.
: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
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,29 +2098,29 @@ 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:
:lair:Mark the map as monster lair
:lair:Mark the map as monster lair
:lair reset:Mark the map as ordinary (not lair)
:lair reset:Mark the map as ordinary (not lair)
misery
misery
======
======
@ -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.
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!
Not all combinations are good for every situation and most of them will
produce undesirable results. There are a few good ones though.
You are in fort game mode, managing your fortress and paused.
Examples:
You switch to the arena game mode, *assume control of a creature* and then
switch to adventure game mode(1).
* You are in fort game mode, managing your fortress and paused.
You just lost a fortress and gained an adventurer.
* You switch to the arena game mode, *assume control of a creature* and then
OR
* switch to adventure game mode(1).
You are in fort game mode, managing your fortress and paused at the esc menu.
You just lost a fortress and gained an adventurer. Alternatively:
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.
:-skill S:Force the mood to use a specific skill instead of choosing the highest moodable skill.
:-type <T>:Force the mood to be of a particular type instead of choosing randomly based on happiness.
PeridexisErrant