1086 lines
39 KiB
ReStructuredText
1086 lines
39 KiB
ReStructuredText
|
##############
|
||
|
DFHack Scripts
|
||
|
##############
|
||
|
|
||
|
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
|
||
|
of the 'ls' command output.
|
||
|
|
||
|
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
|
||
|
scripts that are obscure, developer-oriented, or should be used as keybindings.
|
||
|
|
||
|
``kill-lua`` stops any currently-running Lua scripts. By default, scripts can
|
||
|
only be interrupted every 256 instructions. Use ``kill-lua force`` to interrupt
|
||
|
the next instruction.
|
||
|
|
||
|
.. contents::
|
||
|
|
||
|
=======
|
||
|
devel/*
|
||
|
=======
|
||
|
Scripts in this subdirectory are intended for developers, or still substantially
|
||
|
under development. If you don't already know what they do, best to leave them alone.
|
||
|
|
||
|
================================================
|
||
|
fix/* - scripts that fix bugs or common problems
|
||
|
================================================
|
||
|
Scripts in this subdirectory fix various bugs and issues, some of them obscure.
|
||
|
|
||
|
fix/blood-del
|
||
|
=============
|
||
|
Makes it so that future caravans won't bring barrels full of blood, ichor, or goo.
|
||
|
|
||
|
fix/build-location
|
||
|
==================
|
||
|
Fixes construction jobs that are stuck trying to build a wall while standing
|
||
|
on the same exact tile (bug 5991), designates the tile restricted traffic to
|
||
|
hopefully avoid jamming it again, and unsuspends them.
|
||
|
|
||
|
fix/dead-units
|
||
|
==============
|
||
|
Removes uninteresting dead units from the unit list. Doesn't seem to give any
|
||
|
noticeable performance gain, but migrants normally stop if the unit list grows
|
||
|
to around 3000 units, and this script reduces it back.
|
||
|
|
||
|
fix/fat-dwarves
|
||
|
===============
|
||
|
Avoids 5-10% FPS loss due to constant recalculation of insulation for dwarves at
|
||
|
maximum fatness, by reducing the cap from 1,000,000 to 999,999.
|
||
|
|
||
|
fix/feeding-timers
|
||
|
==================
|
||
|
Reset the GiveWater and GiveFood timers of all units as appropriate.
|
||
|
|
||
|
fix/growth-bug
|
||
|
==============
|
||
|
Fixes locally born units such that they will grow larger than their birth size.
|
||
|
Note that this bug was fixed in DF version 0.40.02.
|
||
|
|
||
|
fix/item-occupancy
|
||
|
==================
|
||
|
Diagnoses and fixes issues with nonexistant 'items occupying site', usually
|
||
|
caused by autodump bugs or other hacking mishaps.
|
||
|
|
||
|
fix/loyaltycascade
|
||
|
==================
|
||
|
Aborts loyalty cascades by fixing units whose own civ is the enemy.
|
||
|
|
||
|
fix/population-cap
|
||
|
==================
|
||
|
Run this after every migrant wave to ensure your population cap is not exceeded.
|
||
|
The issue with the cap is that it is compared to the population number reported
|
||
|
by the last caravan, so once it drops below the cap, migrants continue to come
|
||
|
until that number is updated again.
|
||
|
|
||
|
fix/stable-temp
|
||
|
===============
|
||
|
Instantly sets the temperature of all free-lying items to be in equilibrium with
|
||
|
the environment and stops temperature updates. In order to maintain this efficient
|
||
|
state however, use ``tweak stable-temp`` and ``tweak fast-heat``.
|
||
|
|
||
|
fix/stuckdoors
|
||
|
==============
|
||
|
Fix doors that are stuck open due to incorrect map occupancy flags, eg due to
|
||
|
incorrect use of teleport.
|
||
|
|
||
|
========================================
|
||
|
gui/* - scripts with an ingame interface
|
||
|
========================================
|
||
|
Scripts that implement dialogs inserted into the main game window are put in this
|
||
|
directory.
|
||
|
|
||
|
.. note::
|
||
|
|
||
|
In order to avoid user confusion, as a matter of policy all these tools
|
||
|
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.
|
||
|
|
||
|
|
||
|
gui/advfort
|
||
|
===========
|
||
|
This script allows to perform jobs in adventure mode. For more complete help
|
||
|
press '?' while script is running. It's most confortable to use this as a
|
||
|
keybinding. (e.g. keybinding set Ctrl-T gui/advfort). Possible arguments:
|
||
|
|
||
|
* -a or --nodfassign - uses different method to assign items.
|
||
|
|
||
|
* -i or --inventory - checks inventory for possible items to use in the job.
|
||
|
|
||
|
* -c or --cheat - relaxes item requirements for buildings (e.g. walls from bones).
|
||
|
implies -a
|
||
|
|
||
|
* job - selects that job (e.g. Dig or FellTree)
|
||
|
|
||
|
An example of player digging in adventure mode:
|
||
|
|
||
|
.. image:: images/advfort.png
|
||
|
|
||
|
.. admonition:: DISCLAIMER
|
||
|
|
||
|
advfort changes only persist in non procedural sites. Namely: player forts, caves, camps.
|
||
|
|
||
|
gui/assign-rack
|
||
|
===============
|
||
|
Bind to a key (the example config uses P), and activate when viewing a weapon
|
||
|
rack in the 'q' mode.
|
||
|
|
||
|
.. image:: images/assign-rack.png
|
||
|
|
||
|
This script is part of a group of related fixes to make the armory storage
|
||
|
work again. The existing issues are:
|
||
|
|
||
|
* Weapon racks have to each be assigned to a specific squad, like with
|
||
|
beds/boxes/armor stands and individual squad members, but nothing in
|
||
|
the game does this. This issue is what this script addresses.
|
||
|
|
||
|
* Even if assigned by the script, **the game will unassign the racks again without a binary patch**.
|
||
|
This patch is called ``weaponrack-unassign``, and can be applied via
|
||
|
the binpatch program, or the matching script. See `the bug report`_ for more info.
|
||
|
|
||
|
.. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445
|
||
|
|
||
|
* Haulers still take equipment stored in the armory away to the stockpiles,
|
||
|
unless the ``fix-armory`` plugin above is used.
|
||
|
|
||
|
The script interface simply lets you designate one of the squads that
|
||
|
are assigned to the barracks/armory containing the selected stand as
|
||
|
the intended user. In order to aid in the choice, it shows the number
|
||
|
of currently assigned racks for every valid squad.
|
||
|
|
||
|
gui/choose-weapons
|
||
|
==================
|
||
|
Bind to a key (the example config uses Ctrl-W), and activate in the Equip->View/Customize
|
||
|
page of the military screen.
|
||
|
|
||
|
Depending on the cursor location, it rewrites all 'individual choice weapon' entries
|
||
|
in the selected squad or position to use a specific weapon type matching the assigned
|
||
|
unit's top skill. If the cursor is in the rightmost list over a weapon entry, it rewrites
|
||
|
only that entry, and does it even if it is not 'individual choice'.
|
||
|
|
||
|
Rationale: individual choice seems to be unreliable when there is a weapon shortage,
|
||
|
and may lead to inappropriate weapons being selected.
|
||
|
|
||
|
gui/clone-uniform
|
||
|
=================
|
||
|
Bind to a key (the example config uses Ctrl-C), and activate in the Uniforms
|
||
|
page of the military screen with the cursor in the leftmost list.
|
||
|
|
||
|
When invoked, the script duplicates the currently selected uniform template,
|
||
|
and selects the newly created copy.
|
||
|
|
||
|
gui/companion-order
|
||
|
===================
|
||
|
A script to issue orders for companions. Select companions with lower case chars, issue orders with upper
|
||
|
case. Must be in look or talk mode to issue command on tile.
|
||
|
|
||
|
.. image:: images/companion-order.png
|
||
|
|
||
|
* move - orders selected companions to move to location. If companions are following they will move no more than 3 tiles from you.
|
||
|
* equip - try to equip items on the ground.
|
||
|
* pick-up - try to take items into hand (also wield)
|
||
|
* unequip - remove and drop equipment
|
||
|
* unwield - drop held items
|
||
|
* wait - temporarily remove from party
|
||
|
* follow - rejoin the party after "wait"
|
||
|
* leave - remove from party (can be rejoined by talking)
|
||
|
|
||
|
gui/create-item
|
||
|
===============
|
||
|
A graphical interface for creating items.
|
||
|
|
||
|
gui/dfstatus
|
||
|
============
|
||
|
Show a quick overview of critical stock quantities, including food, drinks, wood, and various bars.
|
||
|
Sections can be enabled/disabled/configured by editing ``dfhack-config/dfstatus.lua``.
|
||
|
|
||
|
gui/gm-editor
|
||
|
=============
|
||
|
There are three ways to open this editor:
|
||
|
|
||
|
* using gui/gm-editor command/keybinding - opens editor on what is selected
|
||
|
or viewed (e.g. unit/item description screen)
|
||
|
|
||
|
* using gui/gm-editor <lua command> - executes lua command and opens editor on
|
||
|
its results (e.g. gui/gm-editor "df.global.world.items.all" shows all items)
|
||
|
|
||
|
* using gui/gm-editor dialog - shows an in game dialog to input lua command. Works
|
||
|
the same as version above.
|
||
|
|
||
|
.. image:: images/gm-editor.png
|
||
|
|
||
|
This editor allows to change and modify almost anything in df. Press '?' for an
|
||
|
in-game help.
|
||
|
|
||
|
gui/guide-path
|
||
|
==============
|
||
|
Bind to a key (the example config uses Alt-P), and activate in the Hauling menu with
|
||
|
the cursor over a Guide order.
|
||
|
|
||
|
.. image:: images/guide-path.png
|
||
|
|
||
|
The script displays the cached path that will be used by the order; the game
|
||
|
computes it when the order is executed for the first time.
|
||
|
|
||
|
gui/liquids
|
||
|
===========
|
||
|
To use, bind to a key (the example config uses Alt-L) and activate in the 'k' mode.
|
||
|
|
||
|
.. image:: images/liquids.png
|
||
|
|
||
|
This script is a gui front-end to the liquids plugin and works similar to it,
|
||
|
allowing you to add or remove water & magma, and create obsidian walls & floors.
|
||
|
Note that there is **no undo support**, and that bugs in this plugin have been
|
||
|
known to create pathfinding problems and heat traps.
|
||
|
|
||
|
The ``b`` key changes how the affected area is selected. The default *Rectangle*
|
||
|
mode works by selecting two corners like any ordinary designation. The ``p``
|
||
|
key chooses between adding water, magma, obsidian walls & floors, or just
|
||
|
tweaking flags.
|
||
|
|
||
|
When painting liquids, it is possible to select the desired level with ``+-``,
|
||
|
and choose between setting it exactly, only increasing or only decreasing
|
||
|
with ``s``.
|
||
|
|
||
|
In addition, ``f`` allows disabling or enabling the flowing water computations
|
||
|
for an area, and ``r`` operates on the "permanent flow" property that makes
|
||
|
rivers power water wheels even when full and technically not flowing.
|
||
|
|
||
|
After setting up the desired operations using the described keys, use ``Enter`` to apply them.
|
||
|
|
||
|
gui/mechanisms
|
||
|
==============
|
||
|
To use, bind to a key (the example config uses Ctrl-M) and activate in the 'q' mode.
|
||
|
|
||
|
.. image:: images/mechanisms.png
|
||
|
|
||
|
Lists mechanisms connected to the building, and their links. Navigating the list centers
|
||
|
the view on the relevant linked buildings.
|
||
|
|
||
|
To exit, press ESC or Enter; ESC recenters on the original building, while Enter leaves
|
||
|
focus on the current one. Shift-Enter has an effect equivalent to pressing Enter, and then
|
||
|
re-entering the mechanisms ui.
|
||
|
|
||
|
gui/mod-manager
|
||
|
===============
|
||
|
A simple way to install and remove small mods.
|
||
|
|
||
|
It looks for specially formatted mods in df subfolder 'mods'. Mods are not
|
||
|
included, but some examples are `available here`_.
|
||
|
|
||
|
.. _`available here`: https://github.com/warmist/df-mini-mods
|
||
|
|
||
|
.. image:: images/mod-manager.png
|
||
|
|
||
|
gui/rename
|
||
|
==========
|
||
|
Backed by the rename plugin, this script allows entering the desired name
|
||
|
via a simple dialog in the game ui.
|
||
|
|
||
|
* ``gui/rename [building]`` in 'q' mode changes the name of a building.
|
||
|
|
||
|
.. image:: images/rename-bld.png
|
||
|
|
||
|
The selected building must be one of stockpile, workshop, furnace, trap, or siege engine.
|
||
|
It is also possible to rename zones from the 'i' menu.
|
||
|
|
||
|
* ``gui/rename [unit]`` with a unit selected changes the nickname.
|
||
|
|
||
|
Unlike the built-in interface, this works even on enemies and animals.
|
||
|
|
||
|
* ``gui/rename unit-profession`` changes the selected unit's custom profession name.
|
||
|
|
||
|
.. image:: images/rename-prof.png
|
||
|
|
||
|
Likewise, this can be applied to any unit, and when used on animals it overrides
|
||
|
their species string.
|
||
|
|
||
|
The ``building`` or ``unit`` options are automatically assumed when in relevant ui state.
|
||
|
|
||
|
The example config binds building/unit rename to Ctrl-Shift-N, and
|
||
|
unit profession change to Ctrl-Shift-T.
|
||
|
|
||
|
gui/room-list
|
||
|
=============
|
||
|
To use, bind to a key (the example config uses Alt-R) and activate in the 'q' mode,
|
||
|
either immediately or after opening the assign owner page.
|
||
|
|
||
|
.. image:: images/room-list.png
|
||
|
|
||
|
The script lists other rooms owned by the same owner, or by the unit selected in the assign
|
||
|
list, and allows unassigning them.
|
||
|
|
||
|
gui/stockpiles
|
||
|
==============
|
||
|
Load and save stockpile settings from the 'q' menu.
|
||
|
Usage::
|
||
|
|
||
|
gui/stockpiles -save to save the current stockpile
|
||
|
gui/stockpiles -load to load settings into the current stockpile
|
||
|
gui/stockpiles -dir <path> set the default directory to save settings into
|
||
|
gui/stockpiles -help to see this message
|
||
|
|
||
|
Don't forget to `enable stockpiles` and create the `stocksettings` directory in
|
||
|
the DF folder before trying to use this plugin.
|
||
|
|
||
|
gui/workflow
|
||
|
============
|
||
|
Bind to a key (the example config uses Alt-W), and activate with a job selected
|
||
|
in a workshop in the 'q' mode.
|
||
|
|
||
|
.. image:: images/workflow.png
|
||
|
|
||
|
This script provides a simple interface to constraints managed by the workflow
|
||
|
plugin. When active, it displays a list of all constraints applicable to the
|
||
|
current job, and their current status.
|
||
|
|
||
|
A constraint specifies a certain range to be compared against either individual
|
||
|
*item* or whole *stack* count, an item type and optionally a material. When the
|
||
|
current count is below the lower bound of the range, the job is resumed; if it
|
||
|
is above or equal to the top bound, it will be suspended. Within the range, the
|
||
|
specific constraint has no effect on the job; others may still affect it.
|
||
|
|
||
|
Pressing 'I' switches the current constraint between counting stacks or items.
|
||
|
Pressing 'R' lets you input the range directly; 'e', 'r', 'd', 'f' adjust the
|
||
|
bounds by 5, 10, or 20 depending on the direction and the 'I' setting (counting
|
||
|
items and expanding the range each gives a 2x bonus).
|
||
|
|
||
|
Pressing 'A' produces a list of possible outputs of this job as guessed by
|
||
|
workflow, and lets you create a new constraint by choosing one as template. If you
|
||
|
don't see the choice you want in the list, it likely means you have to adjust
|
||
|
the job material first using ``job item-material`` or ``gui/workshop-job``,
|
||
|
as described in ``workflow`` documentation above. In this manner, this feature
|
||
|
can be used for troubleshooting jobs that don't match the right constraints.
|
||
|
|
||
|
.. image:: images/workflow-new1.png
|
||
|
|
||
|
If you select one of the outputs with Enter, the matching constraint is simply
|
||
|
added to the list. If you use Shift-Enter, the interface proceeds to the
|
||
|
next dialog, which allows you to edit the suggested constraint parameters to
|
||
|
suit your need, and set the item count range.
|
||
|
|
||
|
.. image:: images/workflow-new2.png
|
||
|
|
||
|
Pressing 'S' (or, with the example config, Alt-W in the 'z' stocks screen)
|
||
|
opens the overall status screen, which was copied from the C++ implementation
|
||
|
by falconne for better integration with the rest of the lua script:
|
||
|
|
||
|
.. image:: images/workflow-status.png
|
||
|
|
||
|
This screen shows all currently existing workflow constraints, and allows
|
||
|
monitoring and/or changing them from one screen. The constraint list can
|
||
|
be filtered by typing text in the field below.
|
||
|
|
||
|
The color of the stock level number indicates how "healthy" the stock level
|
||
|
is, based on current count and trend. Bright green is very good, green is good,
|
||
|
red is bad, bright red is very bad.
|
||
|
|
||
|
The limit number is also color-coded. Red means that there are currently no
|
||
|
workshops producing that item (i.e. no jobs). If it's yellow, that means the
|
||
|
production has been delayed, possibly due to lack of input materials.
|
||
|
|
||
|
The chart on the right is a plot of the last 14 days (28 half day plots) worth
|
||
|
of stock history for the selected item, with the rightmost point representing
|
||
|
the current stock value. The bright green dashed line is the target
|
||
|
limit (maximum) and the dark green line is that minus the gap (minimum).
|
||
|
|
||
|
gui/workshop-job
|
||
|
================
|
||
|
Bind to a key (the example config uses Alt-A), and activate with a job selected in
|
||
|
a workshop in the 'q' mode.
|
||
|
|
||
|
.. image:: images/workshop-job.png
|
||
|
|
||
|
The script shows a list of the input reagents of the selected job, and allows changing
|
||
|
them like the ``job item-type`` and ``job item-material`` commands.
|
||
|
|
||
|
Specifically, pressing the 'i' key pops up a dialog that lets you select an item
|
||
|
type from a list.
|
||
|
|
||
|
.. image:: images/workshop-job-item.png
|
||
|
|
||
|
Pressing 'm', unless the item type does not allow a material,
|
||
|
lets you choose a material.
|
||
|
|
||
|
.. image:: images/workshop-job-material.png
|
||
|
|
||
|
Since there are a lot more materials than item types, this dialog is more complex
|
||
|
and uses a hierarchy of sub-menus. List choices that open a sub-menu are marked
|
||
|
with an arrow on the left.
|
||
|
|
||
|
.. warning::
|
||
|
|
||
|
Due to the way input reagent matching works in DF, you must select an item type
|
||
|
if you select a material, or the material will be matched incorrectly in some cases.
|
||
|
If you press 'm' without choosing an item type, the script will auto-choose it
|
||
|
if there is only one valid choice, or pop up an error message box instead of the
|
||
|
material selection dialog.
|
||
|
|
||
|
Note that both materials and item types presented in the dialogs are filtered
|
||
|
by the job input flags, and even the selected item type for material selection,
|
||
|
or material for item type selection. Many jobs would let you select only one
|
||
|
input item type.
|
||
|
|
||
|
For example, if you choose a *plant* input item type for your prepare meal job,
|
||
|
it will only let you select cookable materials.
|
||
|
|
||
|
If you choose a *barrel* item instead (meaning things stored in barrels, like
|
||
|
drink or milk), it will let you select any material, since in this case the
|
||
|
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*;
|
||
|
you have to unset the material first.
|
||
|
|
||
|
========================
|
||
|
modtools/* - for modders
|
||
|
========================
|
||
|
Scripts which provide tools for modders, often with changes to the raw files.
|
||
|
Not intended to be called manually by end-users.
|
||
|
|
||
|
These scripts are mostly useful for raw modders and scripters. They all have
|
||
|
standard arguments: arguments are of the form ``tool -argName1 argVal1
|
||
|
-argName2 argVal2``. This is equivalent to ``tool -argName2 argVal2 -argName1
|
||
|
argVal1``. It is not necessary to provide a value to an argument name: ``tool
|
||
|
-argName3`` is fine. Supplying the same argument name multiple times will
|
||
|
result in an error. Argument names are preceded with a dash. The ``-help``
|
||
|
argument will print a descriptive usage string describing the nature of the
|
||
|
arguments. For multiple word argument values, brackets must be used: ``tool
|
||
|
-argName4 [ sadf1 sadf2 sadf3 ]``. In order to allow passing literal braces as
|
||
|
part of the argument, backslashes are used: ``tool -argName4 [ \] asdf \foo ]``
|
||
|
sets ``argName4`` to ``\] asdf foo``. The ``*-trigger`` scripts have a similar
|
||
|
policy with backslashes.
|
||
|
|
||
|
add-syndrome
|
||
|
============
|
||
|
This allows adding and removing syndromes from units.
|
||
|
|
||
|
anonymous-script
|
||
|
================
|
||
|
This allows running a short simple Lua script passed as an argument instead of running a script from a file. This is useful when you want to do something too complicated to make with the existing modtools, but too simple to be worth its own script file.
|
||
|
|
||
|
create-item
|
||
|
===========
|
||
|
This is mostly the same as the other create item tools, but it uses standard arguments. The other versions will be phased out in a later version.
|
||
|
|
||
|
force
|
||
|
=====
|
||
|
This tool triggers events like megabeasts, caravans, invaders, and migrants.
|
||
|
|
||
|
interaction-trigger
|
||
|
===================
|
||
|
This triggers events when a unit uses an interaction on another. It works by scanning the announcements for the correct attack verb, so the attack verb must be specified in the interaction. It includes an option to suppress this announcement after it finds it.
|
||
|
|
||
|
invader-item-destroyer
|
||
|
======================
|
||
|
This tool configurably destroys invader items to prevent clutter or to prevent the player from getting tools exclusive to certain races.
|
||
|
|
||
|
item-trigger
|
||
|
============
|
||
|
This powerful tool triggers DFHack commands when a unit equips, unequips, or attacks another unit with specified item types, specified item materials, or specified item contaminants.
|
||
|
|
||
|
moddable-gods
|
||
|
=============
|
||
|
This is a standardized version of Putnam's moddableGods script. It allows you to create gods on the command-line.
|
||
|
|
||
|
outside-only
|
||
|
============
|
||
|
This allows you to specify certain custom buildings as outside only, or inside only. If the player attempts to build a building in an inappropriate location, the building will be destroyed.
|
||
|
|
||
|
projectile-trigger
|
||
|
==================
|
||
|
This triggers dfhack commands when projectiles hit their targets.
|
||
|
|
||
|
random-trigger
|
||
|
==============
|
||
|
This triggers random dfhack commands with specified probabilities.
|
||
|
|
||
|
reaction-product-trigger
|
||
|
========================
|
||
|
This triggers dfhack commands when reaction products are produced, once per product.
|
||
|
|
||
|
reaction-trigger
|
||
|
================
|
||
|
Triggers dfhack commands when custom reactions complete, regardless of whether it produced anything, once per completion.
|
||
|
|
||
|
reaction-trigger-transition
|
||
|
===========================
|
||
|
Scans raw files and creates a file to help modders transition from autoSyndrome to reaction-trigger.
|
||
|
|
||
|
skill-change
|
||
|
============
|
||
|
Sets or modifies a skill of a unit.
|
||
|
|
||
|
spawn-flow
|
||
|
==========
|
||
|
Creates flows at the specified location.
|
||
|
|
||
|
syndrome-trigger
|
||
|
================
|
||
|
Triggers dfhack commands when syndromes are applied to units.
|
||
|
|
||
|
transform-unit
|
||
|
==============
|
||
|
Transforms a unit into another unit type, possibly permanently.
|
||
|
|
||
|
|
||
|
=============
|
||
|
Other Scripts
|
||
|
=============
|
||
|
These scripts are not stored in any subdirectory, and can be invoked directly.
|
||
|
|
||
|
adaptation
|
||
|
==========
|
||
|
View or set level of cavern adaptation for the selected unit or the whole fort.
|
||
|
Usage: ``adaptation <show|set> <him|all> [value]``. The ``value`` must be
|
||
|
between 0 and 800,000 inclusive.
|
||
|
|
||
|
add-thought
|
||
|
===========
|
||
|
Adds a thought or emotion to the selected unit. Can be used by other scripts,
|
||
|
or the gui invoked by running ``add-thought gui`` with a unit selected.
|
||
|
|
||
|
armoks-blessing
|
||
|
===============
|
||
|
Runs the equivalent of rejuvenate, elevate-physical, elevate-mental, and brainwash
|
||
|
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.
|
||
|
Use in moderation; it's as 'cheaty' as DFHack gets.
|
||
|
|
||
|
autofarm
|
||
|
========
|
||
|
Automatically handle crop selection in farm plots based on current plant stocks.
|
||
|
Selects a crop for planting if current stock is below a threshold.
|
||
|
Selected crops are dispatched on all farmplots.
|
||
|
|
||
|
Usage::
|
||
|
|
||
|
autofarm start
|
||
|
autofarm default 30
|
||
|
autofarm threshold 150 helmet_plump tail_pig
|
||
|
|
||
|
autounsuspend
|
||
|
=============
|
||
|
Automatically unsuspend construction jobs, on a recurring basis.
|
||
|
See ``unsuspend`` for one-off use, or ``resume all``.
|
||
|
|
||
|
ban-cooking
|
||
|
===========
|
||
|
A more convenient way to ban cooking various categories of foods than the
|
||
|
kitchen interface. Usage: ``ban-cooking <type>``. Valid types are ``booze``,
|
||
|
``honey``, ``tallow``, ``oil``, and ``seeds`` (non-tree plants with seeds).
|
||
|
|
||
|
binpatch
|
||
|
========
|
||
|
Checks, applies or removes binary patches directly in memory at runtime::
|
||
|
|
||
|
binpatch check/apply/remove <patchname>
|
||
|
|
||
|
If the name of the patch has no extension or directory separators, the
|
||
|
script uses ``hack/patches/<df-version>/<name>.dif``, thus auto-selecting
|
||
|
the version appropriate for the currently loaded executable.
|
||
|
|
||
|
brainwash
|
||
|
=========
|
||
|
Modify the personality traits of the selected dwarf to match an 'ideal'
|
||
|
personality - as stable and reliable as possible. This makes dwarves very
|
||
|
stable, preventing tantrums even after months of misery.
|
||
|
|
||
|
burial
|
||
|
======
|
||
|
Sets all unowned coffins to allow burial. ``burial -pets`` also allows burial
|
||
|
of pets.
|
||
|
|
||
|
command-prompt
|
||
|
==============
|
||
|
A one line command prompt in df. Same as entering command into dfhack console. Best
|
||
|
used as a keybinding. Can be called with optional "entry" that will start prompt with
|
||
|
that pre-filled.
|
||
|
|
||
|
.. image:: images/command-prompt.png
|
||
|
|
||
|
create-items
|
||
|
============
|
||
|
Spawn arbitrary items under the cursor.
|
||
|
|
||
|
The first argument gives the item category, the second gives the material,
|
||
|
and the optionnal third gives the number of items to create (defaults to 20).
|
||
|
|
||
|
Currently supported item categories: ``boulder``, ``bar``, ``plant``, ``log``,
|
||
|
``web``.
|
||
|
|
||
|
Instead of material, using ``list`` makes the script list eligible materials.
|
||
|
|
||
|
The ``web`` item category will create an uncollected cobweb on the floor.
|
||
|
|
||
|
Note that the script does not enforce anything, and will let you create
|
||
|
boulders of toad blood and stuff like that.
|
||
|
However the ``list`` mode will only show 'normal' materials.
|
||
|
|
||
|
Examples::
|
||
|
|
||
|
create-items boulders COAL_BITUMINOUS 12
|
||
|
create-items plant tail_pig
|
||
|
create-items log list
|
||
|
create-items web CREATURE:SPIDER_CAVE_GIANT:SILK
|
||
|
create-items bar CREATURE:CAT:SOAP
|
||
|
create-items bar adamantine
|
||
|
|
||
|
deathcause
|
||
|
==========
|
||
|
Focus a body part ingame, and this script will display the cause of death of
|
||
|
the creature.
|
||
|
Also works when selecting units from the (``u``) unitlist viewscreen.
|
||
|
|
||
|
digfort
|
||
|
=======
|
||
|
A script to designate an area for digging according to a plan in csv format.
|
||
|
|
||
|
This script, inspired from quickfort, can designate an area for digging.
|
||
|
Your plan should be stored in a .csv file like this::
|
||
|
|
||
|
# this is a comment
|
||
|
d;d;u;d;d;skip this tile;d
|
||
|
d;d;d;i
|
||
|
|
||
|
Available tile shapes are named after the 'dig' menu shortcuts:
|
||
|
``d`` for dig, ``u`` for upstairs, ``d`` downstairs, ``i`` updown,
|
||
|
``h`` channel, ``r`` upward ramp, ``x`` remove designation.
|
||
|
Unrecognized characters are ignored (eg the 'skip this tile' in the sample).
|
||
|
|
||
|
Empty lines and data after a ``#`` are ignored as comments.
|
||
|
To skip a row in your design, use a single ``;``.
|
||
|
|
||
|
One comment in the file may contain the phrase ``start(3,5)``. It is interpreted
|
||
|
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.
|
||
|
|
||
|
The script takes the plan filename, starting from the root df folder (where
|
||
|
Dwarf Fortress.exe is found).
|
||
|
|
||
|
drain-aquifer
|
||
|
=============
|
||
|
Remove all 'aquifer' tag from the map blocks. Irreversible.
|
||
|
|
||
|
elevate-mental
|
||
|
==============
|
||
|
Set all mental attributes of a dwarf to 2600, which is very high.
|
||
|
Other numbers can be passed as an argument: ``elevate-mental 100``
|
||
|
for example would make the dwarf very stupid indeed.
|
||
|
|
||
|
elevate-physical
|
||
|
================
|
||
|
As for elevate-mental, but for physical traits. High is good for soldiers,
|
||
|
while having an ineffective hammerer can be useful too...
|
||
|
|
||
|
exportlegends
|
||
|
=============
|
||
|
Controls legends mode to export data - especially useful to set-and-forget large
|
||
|
worlds, or when you want a map of every site when there are several hundred.
|
||
|
|
||
|
The 'info' option exports more data than is possible in vanilla, to a
|
||
|
``region-date-legends_plus.xml`` file developed to extend the World
|
||
|
Viewer utility and potentially compatible with others.
|
||
|
|
||
|
Options:
|
||
|
|
||
|
:info: Exports the world/gen info, the legends XML, and a custom XML with more information
|
||
|
:sites: Exports all available site maps
|
||
|
:maps: Exports all seventeen detailed maps
|
||
|
:all: Equivalent to calling all of the above, in that order
|
||
|
|
||
|
exterminate
|
||
|
===========
|
||
|
Kills any unit of a given race.
|
||
|
|
||
|
With no argument, lists the available races and count eligible targets.
|
||
|
|
||
|
With the special argument ``him``, targets only the selected creature.
|
||
|
|
||
|
With the special argument ``undead``, targets all undeads on the map,
|
||
|
regardless of their race.
|
||
|
|
||
|
When specifying a race, a caste can be specified to further restrict the
|
||
|
targeting. To do that, append and colon and the caste name after the race.
|
||
|
|
||
|
Any non-dead non-caged unit of the specified race gets its ``blood_count``
|
||
|
set to 0, which means immediate death at the next game tick. For creatures
|
||
|
such as vampires, it also sets animal.vanish_countdown to 2.
|
||
|
|
||
|
An alternate mode is selected by adding a 2nd argument to the command,
|
||
|
``magma``. In this case, a column of 7/7 magma is generated on top of the
|
||
|
targets until they die (Warning: do not call on magma-safe creatures. Also,
|
||
|
using this mode on birds is not recommended.)
|
||
|
|
||
|
Will target any unit on a revealed tile of the map, including ambushers,
|
||
|
but ignore caged/chained creatures.
|
||
|
|
||
|
Ex::
|
||
|
|
||
|
exterminate gob
|
||
|
exterminate gob:male
|
||
|
|
||
|
To kill a single creature, select the unit with the 'v' cursor and::
|
||
|
|
||
|
exterminate him
|
||
|
|
||
|
To purify all elves on the map with fire (may have side-effects)::
|
||
|
|
||
|
exterminate elve magma
|
||
|
|
||
|
fixnaked
|
||
|
========
|
||
|
Removes all unhappy thoughts due to lack of clothing.
|
||
|
|
||
|
fix-ster
|
||
|
========
|
||
|
Utilizes the orientation tag to either fix infertile creatures or inflict
|
||
|
infertility on creatures that you do not want to breed. Usage::
|
||
|
|
||
|
fix-ster [fert|ster] [all|animals|only:<creature>]
|
||
|
|
||
|
``fert`` or ``ster`` is a required argument; whether to make the target fertile
|
||
|
or sterile. Optional arguments specify the target: no argument for the
|
||
|
selected unit, ``all`` for all units on the map, ``animals`` for all non-dwarf
|
||
|
creatures, or ``only:<creature>`` to only process matching creatures.
|
||
|
|
||
|
forum-dwarves
|
||
|
=============
|
||
|
Saves a copy of a text screen, formatted in bbcode for posting to the Bay12 Forums.
|
||
|
Use ``forum-dwarves help`` for more information.
|
||
|
|
||
|
full-heal
|
||
|
=========
|
||
|
Attempts to fully heal the selected unit. ``full-heal -r`` attempts to resurrect the unit.
|
||
|
|
||
|
gaydar
|
||
|
======
|
||
|
Shows the sexual orientation of units, useful for social engineering or checking
|
||
|
the viability of livestock breeding programs. Use ``gaydar -help`` for information
|
||
|
on available filters for orientation, citizenship, species, etc.
|
||
|
|
||
|
growcrops
|
||
|
=========
|
||
|
Instantly grow seeds inside farming plots.
|
||
|
|
||
|
With no argument, this command list the various seed types currently in
|
||
|
use in your farming plots.
|
||
|
With a seed type, the script will grow 100 of these seeds, ready to be
|
||
|
harvested. You can change the number with a 2nd argument.
|
||
|
|
||
|
For example, to grow 40 plump helmet spawn::
|
||
|
|
||
|
growcrops plump 40
|
||
|
|
||
|
hfs-pit
|
||
|
=======
|
||
|
Creates a pit to the underworld at the cursor.
|
||
|
|
||
|
Takes three arguments: diameter of the pit in tiles, whether to wall off
|
||
|
the pit, and whether to insert stairs. If no arguments are given, the default
|
||
|
is "hfs-pit 1 0 0", ie single-tile wide with no walls or stairs.::
|
||
|
|
||
|
hfs-pit 4 0 1
|
||
|
hfs-pit 2 1 0
|
||
|
|
||
|
First example is a four-across pit with stairs but no walls; second is a
|
||
|
two-across pit with stairs but no walls.
|
||
|
|
||
|
hotkey-notes
|
||
|
============
|
||
|
Lists the key, name, and jump position of your hotkeys in the DFHack console.
|
||
|
|
||
|
lever
|
||
|
=====
|
||
|
Allow manipulation of in-game levers from the dfhack console.
|
||
|
|
||
|
Can list levers, including state and links, with::
|
||
|
|
||
|
lever list
|
||
|
|
||
|
To queue a job so that a dwarf will pull the lever 42, use ``lever pull 42``.
|
||
|
This is the same as 'q'uerying the building and queue a 'P'ull request.
|
||
|
|
||
|
To magically toggle the lever immediately, use::
|
||
|
|
||
|
lever pull 42 --now
|
||
|
|
||
|
locate-ore
|
||
|
==========
|
||
|
Scan the map for metal ores.
|
||
|
|
||
|
Finds and designate for digging one tile of a specific metal ore.
|
||
|
Only works for native metal ores, does not handle reaction stuff (eg STEEL).
|
||
|
|
||
|
When invoked with the ``list`` argument, lists metal ores available on the map.
|
||
|
|
||
|
Examples::
|
||
|
|
||
|
locate-ore list
|
||
|
locate-ore hematite
|
||
|
locate-ore iron
|
||
|
|
||
|
log-region
|
||
|
==========
|
||
|
When enabled in dfhack.init, each time a fort is loaded identifying information will be written to the gamelog. Assists in parsing the file if you switch between forts, and adds information for story-building.
|
||
|
lua
|
||
|
===
|
||
|
There are the following ways to invoke this command:
|
||
|
|
||
|
1. ``lua`` (without any parameters)
|
||
|
|
||
|
This starts an interactive lua interpreter.
|
||
|
|
||
|
2. ``lua -f "filename"`` or ``lua --file "filename"``
|
||
|
|
||
|
This loads and runs the file indicated by filename.
|
||
|
|
||
|
3. ``lua -s ["filename"]`` or ``lua --save ["filename"]``
|
||
|
|
||
|
This loads and runs the file indicated by filename from the save
|
||
|
directory. If the filename is not supplied, it loads "dfhack.lua".
|
||
|
|
||
|
4. ``:lua`` *lua statement...*
|
||
|
|
||
|
Parses and executes the lua statement like the interactive interpreter would.
|
||
|
|
||
|
make-legendary
|
||
|
==============
|
||
|
Makes the selected dwarf legendary in one skill, a group of skills, or all
|
||
|
skills. View groups with ``make-legendary classes``, or all skills with
|
||
|
``make-legendary list``. Use ``make-legendary MINING`` when you need something
|
||
|
dug up, or ``make-legendary all`` when only perfection will do.
|
||
|
|
||
|
make-monarch
|
||
|
============
|
||
|
Make the selected unit King or Queen of your civilisation.
|
||
|
|
||
|
markdown
|
||
|
========
|
||
|
Save a copy of a text screen in markdown (for reddit among others).
|
||
|
Use 'markdown help' for more details.
|
||
|
|
||
|
masspit
|
||
|
=======
|
||
|
Designate all creatures in cages on top of a pit/pond activity zone for pitting.
|
||
|
Works best with an animal stockpile on top of the zone.
|
||
|
|
||
|
Works with a zone number as argument (eg ``Activity Zone #6`` -> ``masspit 6``)
|
||
|
or with the game cursor on top of the area.
|
||
|
|
||
|
multicmd
|
||
|
========
|
||
|
Run multiple dfhack commands. The argument is split around the
|
||
|
character ; and all parts are run sequentially as independent
|
||
|
dfhack commands. Useful for hotkeys.
|
||
|
|
||
|
Example::
|
||
|
|
||
|
multicmd locate-ore iron ; digv
|
||
|
|
||
|
points
|
||
|
======
|
||
|
Sets available points at the embark screen to the specified number. Eg.
|
||
|
``points 1000000`` would allow you to buy everything, or ``points 0`` would
|
||
|
make life quite difficult.
|
||
|
|
||
|
position
|
||
|
========
|
||
|
Reports the current time: date, clock time, month, and season. Also reports
|
||
|
location: z-level, cursor position, window size, and mouse location.
|
||
|
|
||
|
pref-adjust
|
||
|
===========
|
||
|
A two-stage script: ``pref-adjust clear`` removes preferences from all dwarves,
|
||
|
and ``pref-adjust`` inserts an 'ideal' set which is easy to satisfy::
|
||
|
|
||
|
Feb Idashzefon likes wild strawberries for their vivid red color, fisher berries
|
||
|
for their round shape, prickle berries for their precise thorns, plump helmets
|
||
|
for their rounded tops, prepared meals, plants, drinks, doors, thrones, tables and
|
||
|
beds. When possible, she prefers to consume wild strawberries, fisher berries,
|
||
|
prickle berries, plump helmets, strawberry wine, fisher berry wine, prickle berry
|
||
|
wine, and dwarven wine.
|
||
|
|
||
|
putontable
|
||
|
==========
|
||
|
Makes item appear on the table, like in adventure mode shops. Arguments: '-a'
|
||
|
or '--all' for all items.
|
||
|
|
||
|
quicksave
|
||
|
=========
|
||
|
If called in dwarf mode, makes DF immediately auto-save the game by setting a flag
|
||
|
normally used in seasonal auto-save.
|
||
|
|
||
|
region-pops
|
||
|
===========
|
||
|
Show or modify the populations of animals in the region. Use ``region-pops`` for details.
|
||
|
|
||
|
rejuvenate
|
||
|
==========
|
||
|
Set the age of the selected dwarf to 20 years. Useful if valuable citizens are
|
||
|
getting old, or there are too many babies around...
|
||
|
|
||
|
remove-stress
|
||
|
=============
|
||
|
Sets stress to -1,000,000; the normal range is 0 to 500,000 with very stable or
|
||
|
very stressed dwarves taking on negative or greater values respectively.
|
||
|
Applies to the selected unit, or use "remove-stress -all" to apply to all units.
|
||
|
|
||
|
remove-wear
|
||
|
===========
|
||
|
Sets the wear on all items in your fort to zero.
|
||
|
|
||
|
repeat
|
||
|
======
|
||
|
Repeatedly calls a lua script at the specified interval.
|
||
|
|
||
|
This allows neat background changes to the function of the game, especially when
|
||
|
invoked from an init file. For detailed usage instructions, use ``repeat -help``.
|
||
|
|
||
|
Usage examples::
|
||
|
|
||
|
repeat -name jim -time delay -timeUnits units -printResult true -command [ printArgs 3 1 2 ]
|
||
|
repeat -time 1 -timeUnits months -command [ multicmd cleanowned scattered x; clean all ] -name clean
|
||
|
|
||
|
The first example is abstract; the second will regularly remove all contaminants
|
||
|
and worn items from the game.
|
||
|
|
||
|
``-name`` sets the name for the purposes of cancelling and making sure you don't schedule the
|
||
|
same repeating event twice. If not specified, it's set to the first argument after ``-command``.
|
||
|
``-time delay -timeUnits units``; delay is some positive integer, and units is some valid time
|
||
|
unit for ``dfhack.timeout(delay,timeUnits,function)``. ``-command [ ... ]`` specifies the
|
||
|
command to be run.
|
||
|
|
||
|
setfps
|
||
|
======
|
||
|
Run ``setfps <number>`` to set the FPS cap at runtime, in case you want to watch
|
||
|
combat in slow motion or something :)
|
||
|
|
||
|
show-unit-syndromes
|
||
|
===================
|
||
|
Show syndromes affecting units and the remaining and maximum duration, along
|
||
|
with (optionally) substantial detail on the effects. Call
|
||
|
``show-unit-syndromes help`` for further options.
|
||
|
|
||
|
siren
|
||
|
=====
|
||
|
Wakes up sleeping units, cancels breaks and stops parties either everywhere,
|
||
|
or in the burrows given as arguments. In return, adds bad thoughts about
|
||
|
noise, tiredness and lack of protection. Also, the units with interrupted
|
||
|
breaks will go on break again a lot sooner. The script is intended for
|
||
|
emergencies, e.g. when a siege appears, and all your military is partying.
|
||
|
|
||
|
soundsense-season
|
||
|
=================
|
||
|
It is a well known issue that Soundsense cannot detect the correct
|
||
|
current season when a savegame is loaded and has to play random
|
||
|
season music until a season switch occurs.
|
||
|
|
||
|
This script registers a hook that prints the appropriate string
|
||
|
to gamelog.txt on every map load to fix this. For best results
|
||
|
call the script from ``dfhack.init``.
|
||
|
|
||
|
source
|
||
|
======
|
||
|
Create an infinite magma or water source or drain on a tile.
|
||
|
|
||
|
This script registers a map tile as a liquid source, and every 12 game ticks
|
||
|
that tile receives or remove 1 new unit of flow based on the configuration.
|
||
|
|
||
|
Place the game cursor where you want to create the source (must be a
|
||
|
flow-passable tile, and not too high in the sky) and call::
|
||
|
|
||
|
source add [magma|water] [0-7]
|
||
|
|
||
|
The number argument is the target liquid level (0 = drain, 7 = source).
|
||
|
|
||
|
To add more than 1 unit everytime, call the command again on the same spot.
|
||
|
|
||
|
To delete one source, place the cursor over its tile and use ``delete``.
|
||
|
To remove all existing sources, call ``source clear``.
|
||
|
|
||
|
The ``list`` argument shows all existing sources.
|
||
|
|
||
|
Ex::
|
||
|
|
||
|
source add water - water source
|
||
|
source add magma 7 - magma source
|
||
|
source add water 0 - water drain
|
||
|
|
||
|
startdwarf
|
||
|
==========
|
||
|
Use at the embark screen to embark with the specified number of dwarves. Eg.
|
||
|
``startdwarf 500`` would lead to a severe food shortage and FPS issues, while
|
||
|
``startdwarf 10`` would just allow a few more warm bodies to dig in.
|
||
|
The number must be 7 or greater.
|
||
|
|
||
|
stripcaged
|
||
|
==========
|
||
|
For dumping items inside cages. Will mark selected items for dumping, then
|
||
|
a dwarf may come and actually dump it. See also ``autodump``.
|
||
|
|
||
|
With the ``items`` argument, only dumps items laying in the cage, excluding
|
||
|
stuff worn by caged creatures. ``weapons`` will dump worn weapons, ``armor``
|
||
|
will dump everything worn by caged creatures (including armor and clothing),
|
||
|
and ``all`` will dump everything, on a creature or not.
|
||
|
|
||
|
``stripcaged list`` will display on the dfhack console the list of all cages
|
||
|
and their item content.
|
||
|
|
||
|
Without further arguments, all commands work on all cages and animal traps on
|
||
|
the map. With the ``here`` argument, considers only the in-game selected cage
|
||
|
(or the cage under the game cursor). To target only specific cages, you can
|
||
|
alternatively pass cage IDs as arguments::
|
||
|
|
||
|
stripcaged weapons 25321 34228
|
||
|
|
||
|
superdwarf
|
||
|
==========
|
||
|
Similar to fastdwarf, per-creature.
|
||
|
|
||
|
To make any creature superfast, target it ingame using 'v' and::
|
||
|
|
||
|
superdwarf add
|
||
|
|
||
|
Other options available: ``del``, ``clear``, ``list``.
|
||
|
|
||
|
This plugin also shortens the 'sleeping' and 'on break' periods of targets.
|
||
|
|
||
|
teleport
|
||
|
========
|
||
|
Teleports a unit to given coordinates.
|
||
|
|
||
|
Examples::
|
||
|
|
||
|
teleport -showunitid - prints unitid beneath cursor
|
||
|
teleport -showpos - prints coordinates beneath cursor
|
||
|
teleport -unit 1234 -x 56 -y 115 -z 26 - teleports unit 1234 to 56,115,26
|
||
|
|
||
|
undump-buildings
|
||
|
================
|
||
|
Undesignates building base materials for dumping.
|
||
|
|
||
|
unsuspend
|
||
|
=========
|
||
|
Unsuspend construction jobs, on a one-off basis. See ``autounsuspend`` for regular use.
|
||
|
Equivalent to ``resume all``.
|
||
|
|
||
|
view-item-info
|
||
|
==============
|
||
|
A script to extend the item or unit viewscreen with additional information
|
||
|
including a custom description of each item (when available), and properties
|
||
|
such as material statistics, weapon attacks, armor effectiveness, and more.
|
||
|
|
||
|
The associated script ``item-descriptions.lua`` supplies custom descriptions
|
||
|
of items. Individual descriptions can be added or overridden by a similar
|
||
|
script ``raw/scripts/more-item-descriptions.lua``. Both work as sparse lists,
|
||
|
so missing items simply go undescribed if not defined in the fallback.
|
||
|
|
||
|
warn-starving
|
||
|
=============
|
||
|
If any (live) units are starving, very thirsty, or very drowsy, the game will
|
||
|
be paused and a warning shown and logged to the console. Use with the
|
||
|
``repeat`` command for regular checks.
|
||
|
|
||
|
Use ``warn-starving all`` to display a list of all problematic units.
|