Merge pull request #2247 from DFHack/docs

Doc system and tool help overhaul
develop
Myk 2022-08-31 23:44:02 -07:00 committed by GitHub
commit b954cd7a0d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
246 changed files with 7343 additions and 9135 deletions

@ -129,14 +129,14 @@ jobs:
python-version: 3 python-version: 3
- name: Install dependencies - name: Install dependencies
run: | run: |
pip install 'sphinx<4.4.0' pip install 'sphinx'
- name: Clone DFHack - name: Clone DFHack
uses: actions/checkout@v1 uses: actions/checkout@v1
with: with:
submodules: true submodules: true
- name: Build docs - name: Build docs
run: | run: |
sphinx-build -W --keep-going -j3 --color . docs/html sphinx-build -W --keep-going -j auto --color . docs/html
- name: Upload docs - name: Upload docs
uses: actions/upload-artifact@v1 uses: actions/upload-artifact@v1
with: with:

7
.gitignore vendored

@ -15,9 +15,14 @@ build/VC2010
!build/ !build/
# Sphinx generated documentation # Sphinx generated documentation
docs/_* docs/changelogs/
docs/html/ docs/html/
docs/pdf/ docs/pdf/
docs/pseudoxml/
docs/tags/
docs/text/
docs/tools/
docs/xml/
# in-place build # in-place build
build/Makefile build/Makefile

@ -1,7 +1,7 @@
# main project file. use it from a build sub-folder, see COMPILE for details # main project file. use it from a build sub-folder, see COMPILE for details
## some generic CMake magic ## some generic CMake magic
cmake_minimum_required(VERSION 2.8.12 FATAL_ERROR) cmake_minimum_required(VERSION 3.6 FATAL_ERROR)
cmake_policy(SET CMP0048 NEW) cmake_policy(SET CMP0048 NEW)
project(dfhack) project(dfhack)
@ -442,43 +442,67 @@ endif()
add_subdirectory(data) add_subdirectory(data)
add_subdirectory(scripts) add_subdirectory(scripts)
find_package(Sphinx QUIET)
if(BUILD_DOCS) if(BUILD_DOCS)
find_package(Python3)
find_package(Sphinx)
if(NOT SPHINX_FOUND) if(NOT SPHINX_FOUND)
message(SEND_ERROR "Sphinx not found but BUILD_DOCS enabled") message(SEND_ERROR "Sphinx not found but BUILD_DOCS enabled")
endif() endif()
file(GLOB SPHINX_DEPS file(GLOB SPHINX_GLOB_DEPS
"${CMAKE_CURRENT_SOURCE_DIR}/docs/*.rst" LIST_DIRECTORIES false
"${CMAKE_CURRENT_SOURCE_DIR}/docs/guides/*.rst"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/changelog.txt"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_changelog.py"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/images/*.png" "${CMAKE_CURRENT_SOURCE_DIR}/docs/images/*.png"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/styles/*" "${CMAKE_CURRENT_SOURCE_DIR}/docs/styles/*"
"${CMAKE_CURRENT_SOURCE_DIR}/conf.py" "${CMAKE_CURRENT_SOURCE_DIR}/data/init/*init"
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/about.txt" )
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/about.txt" file(GLOB_RECURSE SPHINX_GLOB_RECURSE_DEPS
"${CMAKE_CURRENT_SOURCE_DIR}/*.rst"
"${CMAKE_CURRENT_SOURCE_DIR}/changelog.txt"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/*py"
)
list(FILTER SPHINX_GLOB_RECURSE_DEPS
EXCLUDE REGEX "docs/changelogs"
)
list(FILTER SPHINX_GLOB_RECURSE_DEPS
EXCLUDE REGEX "docs/html"
) )
file(GLOB_RECURSE SPHINX_SCRIPT_DEPS list(FILTER SPHINX_GLOB_RECURSE_DEPS
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.lua" EXCLUDE REGEX "docs/tags"
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.rb"
) )
set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} list(FILTER SPHINX_GLOB_RECURSE_DEPS
"${CMAKE_CURRENT_SOURCE_DIR}/LICENSE.rst" EXCLUDE REGEX "docs/text"
)
list(FILTER SPHINX_GLOB_RECURSE_DEPS
EXCLUDE REGEX "docs/tools"
)
set(SPHINX_DEPS ${SPHINX_GLOB_DEPS} ${SPHINX_GLOB_RECURSE_DEPS} ${SPHINX_SCRIPT_DEPS}
"${CMAKE_CURRENT_SOURCE_DIR}/CMakeLists.txt" "${CMAKE_CURRENT_SOURCE_DIR}/CMakeLists.txt"
"${CMAKE_CURRENT_SOURCE_DIR}/conf.py"
) )
set(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo") set(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo")
set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE) set_property(
DIRECTORY PROPERTY ADDITIONAL_CLEAN_FILES TRUE
"${CMAKE_CURRENT_SOURCE_DIR}/docs/changelogs"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/html"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/pdf"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/pseudoxml"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/tags"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/text"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/tools"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/xml"
"${CMAKE_BINARY_DIR}/docs/html"
"${CMAKE_BINARY_DIR}/docs/pdf"
"${CMAKE_BINARY_DIR}/docs/pseudoxml"
"${CMAKE_BINARY_DIR}/docs/text"
"${CMAKE_BINARY_DIR}/docs/xml"
)
add_custom_command(OUTPUT ${SPHINX_OUTPUT} add_custom_command(OUTPUT ${SPHINX_OUTPUT}
COMMAND ${SPHINX_EXECUTABLE} COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/docs/build.py"
-a -E -q -b html html text --sphinx="${SPHINX_EXECUTABLE}" -- -q
"${CMAKE_CURRENT_SOURCE_DIR}"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/html"
-w "${CMAKE_CURRENT_SOURCE_DIR}/docs/_sphinx-warnings.txt"
-j 2
DEPENDS ${SPHINX_DEPS} DEPENDS ${SPHINX_DEPS}
COMMENT "Building HTML documentation with Sphinx" COMMENT "Building documentation with Sphinx"
) )
add_custom_target(dfhack_docs ALL add_custom_target(dfhack_docs ALL
@ -490,8 +514,12 @@ if(BUILD_DOCS)
COMMAND ${CMAKE_COMMAND} -E touch ${SPHINX_OUTPUT}) COMMAND ${CMAKE_COMMAND} -E touch ${SPHINX_OUTPUT})
install(DIRECTORY ${dfhack_SOURCE_DIR}/docs/html/ install(DIRECTORY ${dfhack_SOURCE_DIR}/docs/html/
DESTINATION ${DFHACK_USERDOC_DESTINATION}/docs
FILES_MATCHING PATTERN "*"
PATTERN html/_sources EXCLUDE)
install(DIRECTORY ${dfhack_SOURCE_DIR}/docs/text/
DESTINATION ${DFHACK_USERDOC_DESTINATION}/docs) DESTINATION ${DFHACK_USERDOC_DESTINATION}/docs)
install(FILES docs/_auto/news.rst docs/_auto/news-dev.rst DESTINATION ${DFHACK_USERDOC_DESTINATION}) install(FILES docs/changelogs/news.rst docs/changelogs/news-dev.rst DESTINATION ${DFHACK_USERDOC_DESTINATION})
install(FILES "README.html" DESTINATION "${DFHACK_DATA_DESTINATION}") install(FILES "README.html" DESTINATION "${DFHACK_DATA_DESTINATION}")
endif() endif()

@ -15,186 +15,128 @@ serve to show the default.
# pylint:disable=redefined-builtin # pylint:disable=redefined-builtin
import datetime import datetime
from io import open
import os import os
import re import re
import shlex # pylint:disable=unused-import import shlex # pylint:disable=unused-import
import sphinx import sphinx
import sys import sys
sys.path.append(os.path.join(os.path.abspath(os.path.dirname(__file__)), 'docs', 'sphinx_extensions'))
from dfhack.util import write_file_if_changed
# -- Support :dfhack-keybind:`command` ------------------------------------ if os.environ.get('DFHACK_DOCS_BUILD_OFFLINE'):
# this is a custom directive that pulls info from default keybindings # block attempted image downloads, particularly for the PDF builder
def request_disabled(*args, **kwargs):
raise RuntimeError('Offline build - network request blocked')
from docutils import nodes import urllib3.util
from docutils.parsers.rst import roles urllib3.util.create_connection = request_disabled
sphinx_major_version = sphinx.version_info[0] import urllib3.connection
urllib3.connection.HTTPConnection.connect = request_disabled
def get_keybinds(root, files, keybindings): import requests
"""Add keybindings in the specified files to the requests.request = request_disabled
given keybindings dict. requests.get = request_disabled
"""
for file in files:
with open(os.path.join(root, file)) as f: # -- Autodoc for DFhack plugins and scripts -------------------------------
lines = [l.replace('keybinding add', '').strip() for l in f.readlines()
if l.startswith('keybinding add')] def doc_dir(dirname, files, prefix):
for k in lines: """Yield (name, includepath) for each file in the directory."""
first, command = k.split(' ', 1)
bind, context = (first.split('@') + [''])[:2]
if ' ' not in command:
command = command.replace('"', '')
tool = command.split(' ')[0].replace('"', '')
keybindings[tool] = keybindings.get(tool, []) + [
(command, bind.split('-'), context)]
def get_all_keybinds(root_dir):
"""Get the implemented keybinds, and return a dict of
{tool: [(full_command, keybinding, context), ...]}.
"""
keybindings = dict()
for root, _, files in os.walk(root_dir):
get_keybinds(root, files, keybindings)
return keybindings
KEYBINDS = get_all_keybinds('data/init')
# pylint:disable=unused-argument,dangerous-default-value,too-many-arguments
def dfhack_keybind_role_func(role, rawtext, text, lineno, inliner,
options={}, content=[]):
"""Custom role parser for DFHack default keybinds."""
roles.set_classes(options)
if text not in KEYBINDS:
msg = inliner.reporter.error(
'no keybinding for {} in dfhack.init-example'.format(text),
line=lineno)
prb = inliner.problematic(rawtext, rawtext, msg)
return [prb], [msg]
newnode = nodes.paragraph()
for cmd, key, ctx in KEYBINDS[text]:
n = nodes.paragraph()
newnode += n
n += nodes.strong('Keybinding: ', 'Keybinding: ')
for k in key:
n += nodes.inline(k, k, classes=['kbd'])
if cmd != text:
n += nodes.inline(' -> ', ' -> ')
n += nodes.literal(cmd, cmd, classes=['guilabel'])
if ctx:
n += nodes.inline(' in ', ' in ')
n += nodes.literal(ctx, ctx)
return [newnode], []
roles.register_canonical_role('dfhack-keybind', dfhack_keybind_role_func)
# -- Autodoc for DFhack scripts -------------------------------------------
def doc_dir(dirname, files):
"""Yield (command, includepath) for each script in the directory."""
sdir = os.path.relpath(dirname, '.').replace('\\', '/').replace('../', '') sdir = os.path.relpath(dirname, '.').replace('\\', '/').replace('../', '')
if prefix == '.':
prefix = ''
else:
prefix += '/'
for f in files: for f in files:
if f[-3:] not in ('lua', '.rb'): if f[-4:] != '.rst':
continue continue
with open(os.path.join(dirname, f), 'r', encoding='utf8') as fstream: yield prefix + f[:-4], sdir + '/' + f
text = [l.rstrip() for l in fstream.readlines() if l.strip()]
# Some legacy lua files use the ruby tokens (in 3rdparty scripts)
tokens = ('=begin', '=end')
if f[-4:] == '.lua' and any('[====[' in line for line in text):
tokens = ('[====[', ']====]')
command = None
for line in text:
if command and line == len(line) * '=':
yield command, sdir + '/' + f, tokens[0], tokens[1]
break
command = line
def doc_all_dirs(): def doc_all_dirs():
"""Collect the commands and paths to include in our docs.""" """Collect the commands and paths to include in our docs."""
scripts = [] tools = []
for root, _, files in os.walk('scripts'): # TODO: as we scan the docs, parse out the tags and short descriptions and
scripts.extend(doc_dir(root, files)) # build a map for use in generating the tags pages and links in the tool
return tuple(scripts) # doc footers
for root, _, files in os.walk('docs/builtins'):
tools.extend(doc_dir(root, files, os.path.relpath(root, 'docs/builtins')))
for root, _, files in os.walk('docs/plugins'):
tools.extend(doc_dir(root, files, os.path.relpath(root, 'docs/plugins')))
for root, _, files in os.walk('scripts/docs'):
tools.extend(doc_dir(root, files, os.path.relpath(root, 'scripts/docs')))
return tuple(tools)
DOC_ALL_DIRS = doc_all_dirs() DOC_ALL_DIRS = doc_all_dirs()
def document_scripts(): def get_tags():
"""Autodoc for files with the magic script documentation marker strings. groups = {}
group_re = re.compile(r'"([^"]+)"')
Returns a dict of script-kinds to lists of .rst include directives. tag_re = re.compile(r'- `tag/([^`]+)`: (.*)')
with open('docs/Tags.rst') as f:
lines = f.readlines()
for line in lines:
line = line.strip()
m = re.match(group_re, line)
if m:
group = m.group(1)
groups[group] = []
continue
m = re.match(tag_re, line)
if m:
tag = m.group(1)
desc = m.group(2)
groups[group].append((tag, desc))
return groups
def generate_tag_indices():
os.makedirs('docs/tags', mode=0o755, exist_ok=True)
tag_groups = get_tags()
for tag_group in tag_groups:
with write_file_if_changed(('docs/tags/by{group}.rst').format(group=tag_group)) as topidx:
for tag_tuple in tag_groups[tag_group]:
tag = tag_tuple[0]
with write_file_if_changed(('docs/tags/{name}.rst').format(name=tag)) as tagidx:
tagidx.write('TODO: add links to the tools that have this tag')
topidx.write(('.. _tag/{name}:\n\n').format(name=tag))
topidx.write(('{name}\n').format(name=tag))
topidx.write(('{underline}\n').format(underline='*'*len(tag)))
topidx.write(('{desc}\n\n').format(desc=tag_tuple[1]))
topidx.write(('.. include:: /docs/tags/{name}.rst\n\n').format(name=tag))
def write_tool_docs():
""" """
# Next we split by type and create include directives sorted by command Creates a file for each tool with the ".. include::" directives to pull in
kinds = {'base': [], 'devel': [], 'fix': [], 'gui': [], 'modtools': []} the original documentation. Then we generate a label and useful info in the
for s in DOC_ALL_DIRS: footer.
k_fname = s[0].split('/', 1)
if len(k_fname) == 1:
kinds['base'].append(s)
else:
kinds[k_fname[0]].append(s)
def template(arg):
tmp = '.. _{}:\n\n.. include:: /{}\n' +\
' :start-after: {}\n :end-before: {}\n'
if arg[0] in KEYBINDS:
tmp += '\n:dfhack-keybind:`{}`\n'.format(arg[0])
return tmp.format(*arg)
return {key: '\n\n'.join(map(template, sorted(value)))
for key, value in kinds.items()}
def write_script_docs():
""" """
Creates a file for eack kind of script (base/devel/fix/gui/modtools) for k in DOC_ALL_DIRS:
with all the ".. include::" directives to pull out docs between the header = ':orphan:\n'
magic strings. label = ('.. _{name}:\n\n').format(name=k[0])
""" include = ('.. include:: /{path}\n\n').format(path=k[1])
kinds = document_scripts() # TODO: generate a footer with links to tools that share at least one
head = { # tag with this tool. Just the tool names, strung across the bottom of
'base': 'Basic Scripts', # the page in one long wrapped line, similar to how the wiki does it
'devel': 'Development Scripts', os.makedirs(os.path.join('docs/tools', os.path.dirname(k[0])),
'fix': 'Bugfixing Scripts', mode=0o755, exist_ok=True)
'gui': 'GUI Scripts', with write_file_if_changed('docs/tools/{}.rst'.format(k[0])) as outfile:
'modtools': 'Scripts for Modders'} outfile.write(header)
for k in head: if k[0] != 'search':
title = ('.. _scripts-{k}:\n\n{l}\n{t}\n{l}\n\n' outfile.write(label)
'.. include:: /scripts/{a}about.txt\n\n' outfile.write(include)
'.. contents:: Contents\n'
' :local:\n\n').format(
k=k, t=head[k],
l=len(head[k])*'#',
a=('' if k == 'base' else k + '/')
)
mode = 'w' if sys.version_info.major > 2 else 'wb'
with open('docs/_auto/{}.rst'.format(k), mode) as outfile:
outfile.write(title)
outfile.write(kinds[k])
def all_keybinds_documented():
"""Check that all keybindings are documented with the :dfhack-keybind:
directive somewhere."""
configured_binds = set(KEYBINDS)
script_commands = set(i[0] for i in DOC_ALL_DIRS)
with open('./docs/Plugins.rst') as f:
plugin_binds = set(re.findall(':dfhack-keybind:`(.*?)`', f.read()))
undocumented_binds = configured_binds - script_commands - plugin_binds
if undocumented_binds:
raise ValueError('The following DFHack commands have undocumented '
'keybindings: {}'.format(sorted(undocumented_binds)))
# Actually call the docs generator and run test # Actually call the docs generator and run test
write_script_docs() write_tool_docs()
all_keybinds_documented() generate_tag_indices()
# -- General configuration ------------------------------------------------ # -- General configuration ------------------------------------------------
sys.path.append(os.path.join(os.path.abspath(os.path.dirname(__file__)), 'docs', 'sphinx_extensions'))
# If your documentation needs a minimal Sphinx version, state it here. # If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '1.8' needs_sphinx = '1.8'
@ -205,8 +147,11 @@ extensions = [
'sphinx.ext.extlinks', 'sphinx.ext.extlinks',
'dfhack.changelog', 'dfhack.changelog',
'dfhack.lexer', 'dfhack.lexer',
'dfhack.tool_docs',
] ]
sphinx_major_version = sphinx.version_info[0]
def get_caption_str(prefix=''): def get_caption_str(prefix=''):
return prefix + (sphinx_major_version >= 5 and '%s' or '') return prefix + (sphinx_major_version >= 5 and '%s' or '')
@ -286,12 +231,18 @@ today_fmt = html_last_updated_fmt = '%Y-%m-%d'
# directories to ignore when looking for source files. # directories to ignore when looking for source files.
exclude_patterns = [ exclude_patterns = [
'README.md', 'README.md',
'docs/html*',
'depends/*',
'build*', 'build*',
'docs/_auto/news*', 'depends/*',
'docs/_changelogs/', 'docs/html/*',
'docs/tags/*',
'docs/text/*',
'docs/builtins/*',
'docs/pdf/*',
'docs/plugins/*',
'docs/pseudoxml/*',
'docs/xml/*',
'scripts/docs/*', 'scripts/docs/*',
'plugins/*',
] ]
# The reST default role (used for this markup: `text`) to use for all # The reST default role (used for this markup: `text`) to use for all
@ -367,8 +318,11 @@ html_sidebars = {
# If false, no module index is generated. # If false, no module index is generated.
html_domain_indices = False html_domain_indices = False
# If false, no index is generated. # If false, no genindex.html is generated.
html_use_index = False html_use_index = True
# don't link to rst sources in the generated pages
html_show_sourcelink = False
html_css_files = [ html_css_files = [
'dfhack.css', 'dfhack.css',
@ -388,3 +342,11 @@ latex_documents = [
] ]
latex_toplevel_sectioning = 'part' latex_toplevel_sectioning = 'part'
# -- Options for text output ---------------------------------------------
from sphinx.writers import text
text.MAXWIDTH = 52
text_sectionchars = '=-~`+"*'

@ -11,8 +11,7 @@ DFHack Core
Command Implementation Command Implementation
====================== ======================
DFHack commands can be implemented in three ways, all of which DFHack commands can be implemented in any of three ways:
are used in the same way:
:builtin: commands are implemented by the core of DFHack. They manage :builtin: commands are implemented by the core of DFHack. They manage
other DFHack tools, interpret commands, and control basic other DFHack tools, interpret commands, and control basic
@ -27,6 +26,7 @@ are used in the same way:
more flexible about versions, and easier to distribute. more flexible about versions, and easier to distribute.
Most third-party DFHack addons are scripts. Most third-party DFHack addons are scripts.
All tools distributed with DFHack are documented `here <genindex>`.
Using DFHack Commands Using DFHack Commands
===================== =====================
@ -113,260 +113,6 @@ second (Windows) example uses `kill-lua` to stop a Lua script.
you have multiple copies of DF running simultaneously. To assign a different you have multiple copies of DF running simultaneously. To assign a different
port, see `remote-server-config`. port, see `remote-server-config`.
Built-in Commands
=================
The following commands are provided by the 'core' components
of DFHack, rather than plugins or scripts.
.. contents::
:local:
.. _alias:
alias
-----
The ``alias`` command allows configuring aliases to other DFHack commands.
Aliases are resolved immediately after built-in commands, which means that an
alias cannot override a built-in command, but can override a command implemented
by a plugin or script.
Usage:
:``alias list``: lists all configured aliases
:``alias add <name> <command> [arguments...]``: adds an alias
:``alias replace <name> <command> [arguments...]``: replaces an existing
alias with a new command, or adds the alias if it does not already exist
:``alias delete <name>``: removes the specified alias
Aliases can be given additional arguments when created and invoked, which will
be passed to the underlying command in order. An example with `devel/print-args`::
[DFHack]# alias add pargs devel/print-args example
[DFHack]# pargs text
example
text
.. _cls:
cls
---
Clear the terminal. Does not delete command history.
.. _die:
die
---
Instantly kills DF without saving.
.. _disable:
.. _enable:
enable
------
Many plugins can be in a distinct enabled or disabled state. Some of
them activate and deactivate automatically depending on the contents
of the world raws. Others store their state in world data. However a
number of them have to be enabled globally, and the init file is the
right place to do it.
Most such plugins or scripts support the built-in ``enable`` and ``disable``
commands. Calling them at any time without arguments prints a list
of enabled and disabled plugins, and shows whether that can be changed
through the same commands. Passing plugin names to these commands will enable
or disable the specified plugins. For example, to enable the `manipulator`
plugin::
enable manipulator
It is also possible to enable or disable multiple plugins at once::
enable manipulator search
.. _fpause:
fpause
------
Forces DF to pause. This is useful when your FPS drops below 1 and you lose
control of the game.
.. _help:
help
----
Most commands support using the ``help <command>`` built-in command
to retrieve further help without having to look at this document.
``? <cmd>`` and ``man <cmd>`` are aliases.
Some commands (including many scripts) instead take ``help`` or ``?``
as an option on their command line - ie ``<cmd> help``.
.. _hide:
hide
----
Hides the DFHack terminal window. Only available on Windows.
.. _keybinding:
keybinding
----------
To set keybindings, use the built-in ``keybinding`` command. Like any other
command it can be used at any time from the console, but bindings are not
remembered between runs of the game unless re-created in `dfhack.init`.
Currently, any combinations of Ctrl/Alt/Shift with A-Z, 0-9, F1-F12 or \`
are supported.
Possible ways to call the command:
``keybinding list <key>``
List bindings active for the key combination.
``keybinding clear <key> <key>...``
Remove bindings for the specified keys.
``keybinding add <key> "cmdline" "cmdline"...``
Add bindings for the specified key.
``keybinding set <key> "cmdline" "cmdline"...``
Clear, and then add bindings for the specified key.
The ``<key>`` parameter above has the following *case-sensitive* syntax::
[Ctrl-][Alt-][Shift-]KEY[@context[|context...]]
where the *KEY* part can be any recognized key and [] denote optional parts.
When multiple commands are bound to the same key combination, DFHack selects
the first applicable one. Later ``add`` commands, and earlier entries within one
``add`` command have priority. Commands that are not specifically intended for use
as a hotkey are always considered applicable.
The ``context`` part in the key specifier above can be used to explicitly restrict
the UI state where the binding would be applicable. If called without parameters,
the ``keybinding`` command among other things prints the current context string.
Only bindings with a ``context`` tag that either matches the current context fully,
or is a prefix ending at a ``/`` boundary would be considered for execution, i.e.
when in context ``foo/bar/baz``, keybindings restricted to any of ``@foo/bar/baz``,
``@foo/bar``, ``@foo`` or none will be active.
Multiple contexts can be specified by separating them with a
pipe (``|``) - for example, ``@foo|bar|baz/foo`` would match
anything under ``@foo``, ``@bar``, or ``@baz/foo``.
Interactive commands like `liquids` cannot be used as hotkeys.
.. _kill-lua:
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.
.. _load:
.. _unload:
.. _reload:
load
----
``load``, ``unload``, and ``reload`` control whether a plugin is loaded
into memory - note that plugins are loaded but disabled unless you do
something. Usage::
load|unload|reload PLUGIN|(-a|--all)
Allows dealing with plugins individually by name, or all at once.
Note that plugins do not maintain their enabled state if they are reloaded, so
you may need to use `enable` to re-enable a plugin after reloading it.
.. _ls:
ls
--
``ls`` does not list files like the Unix command, but rather
available commands - first built in commands, then plugins,
and scripts at the end. Usage:
:ls -a: Also list scripts in subdirectories of ``hack/scripts/``,
which are generally not intended for direct use.
:ls <plugin>: List subcommands for the given plugin.
.. _plug:
plug
----
Lists available plugins, including their state and detailed description.
``plug``
Lists available plugins (*not* commands implemented by plugins)
``plug [PLUGIN] [PLUGIN] ...``
List state and detailed description of the given plugins,
including commands implemented by the plugin.
.. _sc-script:
sc-script
---------
Allows additional scripts to be run when certain events occur
(similar to onLoad*.init scripts)
.. _script:
script
------
Reads a text file, and runs each line as a DFHack command
as if it had been typed in by the user - treating the
input like `an init file <init-files>`.
Some other tools, such as `autobutcher` and `workflow`, export
their settings as the commands to create them - which are later
loaded with ``script``
.. _show:
show
----
Shows the terminal window after it has been `hidden <hide>`.
Only available on Windows. You'll need to use it from a
`keybinding` set beforehand, or the in-game `command-prompt`.
.. _type:
type
----
``type command`` shows where ``command`` is implemented.
Other Commands
--------------
The following commands are *not* built-in, but offer similarly useful functions.
* `command-prompt`
* `hotkeys`
* `lua`
* `multicmd`
* `nopause`
* `quicksave`
* `rb`
* `repeat`
.. _dfhack-config: .. _dfhack-config:
Configuration Files Configuration Files
@ -439,7 +185,7 @@ where ``*`` can be any string, including the empty string.
A world being loaded can mean a fortress, an adventurer, or legends mode. A world being loaded can mean a fortress, an adventurer, or legends mode.
These files are best used for non-persistent commands, such as setting These files are best used for non-persistent commands, such as setting
a `fix <scripts-fix>` script to run on `repeat`. a `tag/bugfix` script to run on `repeat`.
.. _onMapLoad.init: .. _onMapLoad.init:

@ -41,7 +41,7 @@ Installed plugins live in the ``hack/plugins`` folder of a DFHack installation,
and the `load` family of commands can be used to load a recompiled plugin and the `load` family of commands can be used to load a recompiled plugin
without restarting DF. without restarting DF.
See `plugins-index` for a list of all plugins included in DFHack. Run `plug` at the DFHack prompt for a list of all plugins included in DFHack.
Scripts Scripts
------- -------
@ -51,10 +51,10 @@ is more complete and currently better-documented, however. Referring to existing
scripts as well as the API documentation can be helpful when developing new scripts as well as the API documentation can be helpful when developing new
scripts. scripts.
`Scripts included in DFHack <scripts-index>` live in a separate `scripts repository <https://github.com/dfhack/scripts>`_. Scripts included in DFHack live in a separate
This can be found in the ``scripts`` submodule if you have :source-scripts:`scripts repository <>`. This can be found in the ``scripts``
`cloned DFHack <compile-how-to-get-the-code>`, or the ``hack/scripts`` folder submodule if you have `cloned DFHack <compile-how-to-get-the-code>`, or the
of an installed copy of DFHack. ``hack/scripts`` folder of an installed copy of DFHack.
Core Core
---- ----

@ -5,20 +5,24 @@ DFHack Documentation System
########################### ###########################
DFHack documentation, like the file you are reading now, is created as ``.rst`` files, DFHack documentation, like the file you are reading now, is created as a set of
which are in `reStructuredText (reST) <https://www.sphinx-doc.org/rest.html>`_ format. ``.rst`` files in `reStructuredText (reST) <https://www.sphinx-doc.org/rest.html>`_
This is a documentation format common in the Python community. It is very format. This is a documentation format common in the Python community. It is very
similar in concept - and in syntax - to Markdown, as found on GitHub and many other similar in concept - and in syntax - to Markdown, as found on GitHub and many other
places. However it is more advanced than Markdown, with more features available when places. However it is more advanced than Markdown, with more features available when
compiled to HTML, such as automatic tables of contents, cross-linking, special compiled to HTML, such as automatic tables of contents, cross-linking, special
external links (forum, wiki, etc) and more. The documentation is compiled by a external links (forum, wiki, etc) and more. The documentation is compiled by a
Python tool, `Sphinx <https://www.sphinx-doc.org>`_. Python tool named `Sphinx <https://www.sphinx-doc.org>`_.
The DFHack build process will compile the documentation, but this is disabled The DFHack build process will compile and install the documentation so it can be
by default due to the additional Python and Sphinx requirements. You typically displayed in-game by the `help` and `ls` commands (and any other command or GUI that
only need to build the docs if you're changing them, or perhaps displays help text), but this is disabled by default due to the additional Python and
if you want a local HTML copy; otherwise, you can read an Sphinx requirements. If you already have a version of the docs installed (say from a
`online version hosted by ReadTheDocs <https://dfhack.readthedocs.org>`_. downloaded release binary), then you only need to build the docs if you're changing them
and want to see the changes reflected in your game.
You can also build the docs if you just want a local HTML- or text-rendered copy, though
you can always read the `online version <https://dfhack.readthedocs.org>`_ too.
(Note that even if you do want a local copy, it is certainly not necessary to (Note that even if you do want a local copy, it is certainly not necessary to
compile the documentation in order to read it. Like Markdown, reST documents are compile the documentation in order to read it. Like Markdown, reST documents are
@ -28,116 +32,307 @@ The main thing you lose in plain text format is hyperlinking.)
.. contents:: Contents .. contents:: Contents
:local: :local:
Concepts and general guidance
=============================
The source ``.rst`` files are compiled to HTML for viewing in a browser and to text
format for viewing in-game. For in-game help, the help text is read from its installed
location in ``hack/docs`` under the DF directory.
When writing documentation, remember that everything should be documented! If it's not
clear *where* a particular thing should be documented, ask on Discord or in the DFHack
thread on Bay12 -- you'll not only be getting help, you'll also be providing valuable
feedback that makes it easier for future contributers to find documentation on how to
write the documentation!
Try to keep lines within 80-100 characters, so it's readable in plain text
in the terminal - Sphinx (our documentation system) will make sure
paragraphs flow.
Short descriptions
------------------
Each command that a user can run, as well as every plugin that can be enabled for some
lasting effect, needs to have a short (~54 character) descriptive string associated with
it. This description text is:
- used in-game by the `ls` command and DFHack UI screens that list commands
- used in the generated index entries in the HTML docs
Tags
----
To make it easier for players to find related commands, all plugins and commands are marked
with relevant tags. These are used to compile indices and generate cross-links between the
commands, both in the HTML documents and in-game. See the list of available `tag-list` and
think about which categories your new tool belongs in.
Links
-----
If it would be helpful to mention another DFHack command, don't just type the
name - add a hyperlink! Specify the link target in backticks, and it will be
replaced with the corresponding title and linked: e.g. ```autolabor```
=> `autolabor`. Scripts and plugins have link targets that match their names
created for you automatically.
If you want to link to a heading in your own page, you can specifiy it like this::
`Heading text exactly as written`_
Note that the DFHack documentation is configured so that single backticks (with
no prefix or suffix) produce links to internal link targets, such as the
``autolabor`` target shown above. This is different from the reStructuredText
default behavior of rendering such text in italics (as a reference to a title).
For alternative link behaviors, see:
- `The reStructuredText documentation on roles <https://docutils.sourceforge.io/docs/ref/rst/roles.html>`__
- `The reStructuredText documentation on external links <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets>`__
- `The Sphinx documentation on roles <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`__
- ``:doc:`` is useful for linking to another document outside of DFHack.
.. _docs-standards: .. _docs-standards:
Documentation standards Documentation standards
======================= =======================
.. highlight:: rst
Whether you're adding new code or just fixing old documentation (and there's plenty), Whether you're adding new code or just fixing old documentation (and there's plenty),
there are a few important standards for completeness and consistent style. Treat there are a few important standards for completeness and consistent style. Treat
this section as a guide rather than iron law, match the surrounding text, and you'll this section as a guide rather than iron law, match the surrounding text, and you'll
be fine. be fine.
Command documentation Where do I add the help text?
--------------------- -----------------------------
Each command should have a short (~54 character) help string, which is shown For scripts and plugins that are distributed as part of DFHack, documentation files
by the `ls` command. For scripts, this is a comment on the first line should be added to the :source-scripts:`scripts/docs <docs>` and :source:`docs/plugins` directories,
(the comment marker and whitespace is stripped). For plugins it's the second respectively, in a file named after the script or plugin. For example, a script named
argument to ``PluginCommand``. Please make this brief but descriptive! ``gui/foobar.lua`` (which provides the ``gui/foobar`` command) should be documented
in a file named ``docs/gui/foobar.rst`` in the scripts repo. Similarly, a plugin named
``foobaz`` should be documented in a file named ``docs/plugins/foobaz.rst`` in the dfhack repo.
For plugins, all commands provided by that plugin should be documented in that same file.
Everything should be documented! If it's not clear *where* a particular Short descriptions (the ~54 character short help) are taken from the first "sentence" of
thing should be documented, ask on IRC or in the DFHack thread on Bay12 - the help text for scripts and plugins that can be enabled. This means that the help should
as well as getting help, you'll be providing valuable feedback that begin with a sentence fragment that begins with a capital letter and ends in a full stop
makes it easier for future readers! (``.``). Please make this brief but descriptive!
Scripts can use a custom autodoc function, based on the Sphinx ``include`` Short descriptions for commands provided by plugins are taken from the ``description``
directive - anything between the tokens is copied into the appropriate scripts parameter passed to the ``PluginCommand`` constructor used when the command is registered
documentation page. For Ruby, we follow the built-in docstring convention in the plugin source file.
(``=begin`` and ``=end``). For Lua, the tokens are ``[====[`` and ``]====]``
- ordinary multi-line strings. It is highly encouraged to reuse this string
as the in-console documentation by (e.g.) printing it when a ``-help`` argument
is given.
The docs **must** have a heading which exactly matches the command, underlined Header format
with ``=====`` to the same length. For example, a lua file would have: -------------
.. code-block:: lua The docs **must** begin with a heading which exactly matches the script or plugin name, underlined
with ``=====`` to the same length. This should be followed by a ``.. dfhack-tool:`` directive with
at least the following parameters:
local helpstr = [====[ * ``:summary:`` - a short, single-sentence description of the tool
* ``:tags:`` - a space-separated list of tags that apply to the tool
add-thought By default, ``dfhack-tool`` generates both a description of a tool and a command
=========== with the same name. For tools (specifically plugins) that do not provide exactly
Adds a thought or emotion to the selected unit. Can be used by other scripts, 1 command with the same name as the tool, pass the ``:no-command:`` parameter (with
or the gui invoked by running ``add-thought gui`` with a unit selected. no content after it) to prevent the command block from being generated.
]====] For tools that provide multiple commands, or a command by the same name but with
significantly different functionality (e.g. a plugin that can be both enabled
and invoked as a command for different results), use the ``.. dfhack-command:``
directive for each command. This takes only a ``:summary:`` argument, with the
same meaning as above.
For example, documentation for the ``build-now`` script might look like::
.. highlight:: rst build-now
=========
Where the heading for a section is also the name of a command, the spelling .. dfhack-tool::
and case should exactly match the command to enter in the DFHack command line. :summary: Instantly completes unsuspended building construction jobs.
:tags: fort armok buildings
Try to keep lines within 80-100 characters, so it's readable in plain text By default, all buildings on the map are completed, but the area of effect is configurable.
in the terminal - Sphinx (our documentation system) will make sure
paragraphs flow.
Command usage And documentation for the ``autodump`` plugin might look like::
-------------
autodump
========
.. dfhack-tool::
:summary: Automatically set items in a stockpile to be dumped.
:tags: fort armok fps productivity items stockpiles
:no-command:
.. dfhack-command:: autodump
:summary: Teleports items marked for dumping to the cursor position.
.. dfhack-command:: autodump-destroy-here
:summary: Destroy items marked for dumping under the cursor.
If there aren't many options or examples to show, they can go in a paragraph of .. dfhack-command:: autodump-destroy-item
text. Use double-backticks to put commands in monospaced font, like this:: :summary: Destroys the selected item.
You can use ``cleanowned scattered x`` to dump tattered or abandoned items. When `enabled <enable>`, this plugin adds an option to the :kbd:`q` menu for
stockpiles.
If the command takes more than three arguments, format the list as a table When invoked as a command, it can instantly move all unforbidden items marked
called Usage. The table *only* lists arguments, not full commands. for dumping to the tile under the cursor.
Input values are specified in angle brackets. Example::
Usage help
----------
The first section after the header and introductory text should be the usage block. You can
choose between two formats, based on whatever is cleaner or clearer for your syntax. The first
option is to show usage formats together, with an explanation following the block::
Usage::
build-now [<options>]
build-now here [<options>]
build-now [<pos> [<pos>]] [<options>]
Where the optional ``<pos>`` pair can be used to specify the
coordinate bounds within which ``build-now`` will operate. If
they are not specified, ``build-now`` will scan the entire map.
If only one ``<pos>`` is specified, only the building at that
coordinate is built.
The ``<pos>`` parameters can either be an ``<x>,<y>,<z>`` triple
(e.g. ``35,12,150``) or the string ``here``, which means the
position of the active game cursor.
The second option is to arrange the usage options in a list, with the full command
and arguments in monospaced font. Then indent the next line and describe the effect::
Usage: Usage:
:arg1: A simple argument. ``build-now [<options>]``
:arg2 <input>: Does something based on the input value. Scan the entire map and build all unsuspended constructions
:Very long argument: and buildings.
Is very specific. ``build-now here [<options>]``
Build the unsuspended construction or building under the
cursor.
``build-now [<pos> [<pos>]] [<options>]``
Build all unsuspended constructions within the specified
coordinate box.
The ``<pos>`` parameters are specified as...
Note that in both options, the entire commandline syntax is written, including the command itself.
Literal text is written as-is (e.g. the word ``here`` in the above example), and text that
describes the kind of parameter that is being passed (e.g. ``pos`` or ``options``) is enclosed in
angle brackets (``<`` and ``>``). Optional elements are enclosed in square brackets (``[`` and ``]``).
Examples
--------
If the only way to run the command is to type the command itself, then this section is not necessary.
Otherwise, please consider adding a section that shows some real, practical usage examples. For
many users, this will be the **only** section they will read. It is so important that it is a good
idea to include the ``Examples`` section **before** you describe any extended options your command
might take. Write examples for what you expect the popular use cases will be. Also be sure to write
examples showing specific, practical values being used for any parameter that takes a value.
Examples should go in their own subheading with a single dash underline (``--------``). The examples
themselves should be organized in a list, the same as in option 2 for Usage above. Here is an
example Examples section::
Examples
--------
``build-now``
Completes all unsuspended construction jobs on the map.
``build-now 37,20,154 here``
Builds the unsuspended, unconstructed buildings in the box
bounded by the coordinate x=37,y=20,z=154 and the cursor.
Options
-------
To demonstrate usage - useful mainly when the syntax is complicated, list the The options header should follow the examples, with each option in the same list format as the
full command with arguments in monospaced font, then indent the next line and examples::
describe the effect::
``resume all`` Options
Resumes all suspended constructions. -------
Links ``-h``, ``--help``
----- Show help text.
``-l``, ``--quality <level>``
Set the quality of the architecture for built architected
builtings.
``-q``, ``--quiet``
Suppress informational output (error messages are still
printed).
If it would be helpful to mention another DFHack command, don't just type the Note that for parameters that have both short and long forms, any values that those options
name - add a hyperlink! Specify the link target in backticks, and it will be take only need to be specified once (e.g. ``<level>``).
replaced with the corresponding title and linked: e.g. ```autolabor```
=> `autolabor`. Link targets should be equivalent to the command
described (without file extension), and placed above the heading of that
section like this::
.. _autolabor: External scripts and plugins
============================
autolabor Scripts and plugins distributed separately from DFHack's release packages don't have the
========= opportunity to add their documentation to the rendered HTML or text output. However, these
scripts and plugins can use a different mechanism to at least make their help text available
in-game.
Add link targets if you need them, but otherwise plain headings are preferred. Note that since help text for external scripts and plugins is not rendered by Sphinx,
Scripts have link targets created automatically. it should be written in plain text. Any reStructuredText markup will not be processed.
Note that the DFHack documentation is configured so that single backticks (with For external scripts, the short description comes from a comment on the first line
no prefix or suffix) produce links to internal link targets, such as the (the comment marker and extra whitespace is stripped). For Lua, this would look like:
``autolabor`` target shown above. This is different from the reStructuredText
default behavior of rendering such text in italics (as a reference to a title).
For alternative link behaviors, see:
- `The reStructuredText documentation on roles <https://docutils.sourceforge.io/docs/ref/rst/roles.html>`__ .. code-block:: lua
- `The reStructuredText documentation on external links <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets>`__
- `The Sphinx documentation on roles <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`__ -- A short description of my cool script.
- ``:doc:`` is useful for linking to another document and for Ruby scripts it would look like:
.. code-block:: ruby
# A short description of my cool script.
The main help text for an external script needs to appear between two markers. For
Lua, these markers are ``[====[`` and ``]====]``, and for Ruby they are ``=begin`` and
``=end``. The documentation standards above still apply to external tools, but there is
no need to include backticks for links or monospaced fonts. Here is a Lua example for an
entire script header::
-- Inventory management for adventurers.
-- [====[
gui/adv-inventory
=================
Tags: adventure, items
Allows you to quickly move items between containers. This
includes yourself and any followers you have.
Usage:
gui/adv-inventory [<options>]
Examples:
gui/adv-inventory
Opens the GUI with nothing preselected
gui/adv-inventory take-all
Opens the GUI with all container items already selected and
ready to move into the adventurer's inventory.
Options:
take-all
Starts the GUI with container items pre-selected
give-all
Starts the GUI with your own items pre-selected
]====]
For external plugins, help text for provided commands can be passed as the ``usage``
parameter when registering the commands with the ``PluginCommand`` constructor. There
is currently no way for associating help text with the plugin itself, so any
information about what the plugin does when enabled should be combined into the command
help.
Required dependencies Required dependencies
===================== =====================
@ -258,33 +453,48 @@ ways to do this:
* On Windows, if you prefer to use the batch scripts, you can run * On Windows, if you prefer to use the batch scripts, you can run
``generate-msvc-gui.bat`` and set ``BUILD_DOCS`` through the GUI. If you are ``generate-msvc-gui.bat`` and set ``BUILD_DOCS`` through the GUI. If you are
running another file, such as ``generate-msvc-all.bat``, you will need to edit running another file, such as ``generate-msvc-all.bat``, you will need to edit
it to add the flag. You can also run ``cmake`` on the command line, similar to the batch script to add the flag. You can also run ``cmake`` on the command line,
other platforms. similar to other platforms.
The generated documentation will be stored in ``docs/html`` in the root DFHack By default, both HTML and text docs are built by CMake. The generated
folder, and will be installed to ``hack/docs`` when you next install DFHack in a documentation is stored in ``docs/html`` and ``docs/text`` (respectively) in the
DF folder. root DFHack folder, and will be installed to ``hack/docs`` when you install
DFHack.
Running Sphinx manually Running Sphinx manually
----------------------- -----------------------
You can also build the documentation without running CMake - this is faster if You can also build the documentation without running CMake - this is faster if
you only want to rebuild the documentation regardless of any code changes. There you only want to rebuild the documentation regardless of any code changes. The
is a ``docs/build.sh`` script provided for Linux and macOS that will run ``docs/build.py`` script will build the documentation in any specified formats
essentially the same command that CMake runs when building the docs - see the (HTML only by default) using essentially the same command that CMake runs when
script for additional options. building the docs. Run the script with ``--help`` to see additional options.
Examples:
* ``docs/build.py``
Build just the HTML docs
* ``docs/build.py html text``
Build both the HTML and text docs
* ``docs/build.py --clean``
Build HTML and force a clean build (all source files are re-read)
To build the documentation with default options, run the following command from The resulting documentation will be stored in ``docs/html`` and/or ``docs/text``.
the root DFHack folder::
Alternatively, you can run Sphinx manually with::
sphinx-build . docs/html sphinx-build . docs/html
The resulting documentation will be stored in ``docs/html`` (you can specify or, to build plain-text output::
a different path when running ``sphinx-build`` manually, but be warned that
Sphinx may overwrite existing files in this folder). sphinx-build -b text . docs/text
Sphinx has many options to enable clean builds, parallel builds, logging, and Sphinx has many options to enable clean builds, parallel builds, logging, and
more - run ``sphinx-build --help`` for details. more - run ``sphinx-build --help`` for details. If you specify a different
output path, be warned that Sphinx may overwrite existing files in the output
folder.
Building a PDF version Building a PDF version
---------------------- ----------------------
@ -295,10 +505,11 @@ want to build a PDF version locally, you will need ``pdflatex``, which is part
of a TeX distribution. The following command will then build a PDF, located in of a TeX distribution. The following command will then build a PDF, located in
``docs/pdf/latex/DFHack.pdf``, with default options:: ``docs/pdf/latex/DFHack.pdf``, with default options::
sphinx-build -M latexpdf . docs/pdf docs/build.py pdf
There is a ``docs/build-pdf.sh`` script provided for Linux and macOS that runs Alternatively, you can run Sphinx manually with::
this command for convenience - see the script for additional options.
sphinx-build -M latexpdf . docs/pdf
.. _build-changelog: .. _build-changelog:
@ -318,10 +529,10 @@ changelogs are combined as part of the changelog build process:
* ``scripts/changelog.txt`` for changes made to scripts in the ``scripts`` repo * ``scripts/changelog.txt`` for changes made to scripts in the ``scripts`` repo
* ``library/xml/changelog.txt`` for changes made in the ``df-structures`` repo * ``library/xml/changelog.txt`` for changes made in the ``df-structures`` repo
Building the changelogs generates two files: ``docs/_auto/news.rst`` and Building the changelogs generates two files: ``docs/changelogs/news.rst`` and
``docs/_auto/news-dev.rst``. These correspond to `changelog` and `dev-changelog` ``docs/changelogs/news-dev.rst``. These correspond to `changelog` and
and contain changes organized by stable and development DFHack releases, `dev-changelog` and contain changes organized by stable and development DFHack
respectively. For example, an entry listed under "0.44.05-alpha1" in releases, respectively. For example, an entry listed under "0.44.05-alpha1" in
changelog.txt will be listed under that version in the development changelog as changelog.txt will be listed under that version in the development changelog as
well, but under "0.44.05-r1" in the stable changelog (assuming that is the well, but under "0.44.05-r1" in the stable changelog (assuming that is the
closest stable release after 0.44.05-alpha1). An entry listed under a stable closest stable release after 0.44.05-alpha1). An entry listed under a stable

@ -1350,7 +1350,7 @@ Misc improvements
- `createitem`: in adventure mode it now defaults to the controlled unit as maker. - `createitem`: in adventure mode it now defaults to the controlled unit as maker.
- `autotrade`: adds "(Un)mark All" options to both panes of trade screen. - `autotrade`: adds "(Un)mark All" options to both panes of trade screen.
- `mousequery`: several usability improvements; show live overlay (in menu area) of what's on the tile under the mouse cursor. - `mousequery`: several usability improvements; show live overlay (in menu area) of what's on the tile under the mouse cursor.
- `search`: workshop profile search added. - `search-plugin`: workshop profile search added.
- `dwarfmonitor`: add screen to summarise preferences of fortress dwarfs. - `dwarfmonitor`: add screen to summarise preferences of fortress dwarfs.
- `getplants`: add autochop function to automate woodcutting. - `getplants`: add autochop function to automate woodcutting.
- `stocks`: added more filtering and display options. - `stocks`: added more filtering and display options.
@ -1510,7 +1510,7 @@ New binary patches
New Plugins New Plugins
----------- -----------
- `fix-armory`: Together with a couple of binary patches and the `gui/assign-rack` script, this plugin makes weapon racks, armor stands, chests and cabinets in properly designated barracks be used again for storage of squad equipment. - `fix-armory`: Together with a couple of binary patches and the `gui/assign-rack` script, this plugin makes weapon racks, armor stands, chests and cabinets in properly designated barracks be used again for storage of squad equipment.
- `search`: Adds an incremental search function to the Stocks, Trading, Stockpile and Unit List screens. - `search-plugin`: Adds an incremental search function to the Stocks, Trading, Stockpile and Unit List screens.
- `automaterial`: Makes building constructions (walls, floors, fortifications, etc) a little bit easier by saving you from having to trawl through long lists of materials each time you place one. - `automaterial`: Makes building constructions (walls, floors, fortifications, etc) a little bit easier by saving you from having to trawl through long lists of materials each time you place one.
- Dfusion: Reworked to make use of lua modules, now all the scripts can be used from other scripts. - Dfusion: Reworked to make use of lua modules, now all the scripts can be used from other scripts.
- Eventful: A collection of lua events, that will allow new ways to interact with df world. - Eventful: A collection of lua events, that will allow new ways to interact with df world.

@ -96,13 +96,14 @@ When you `download DFHack <downloading>`, you will end up with a release archive
operating system should have built-in utilities capable of extracting files from operating system should have built-in utilities capable of extracting files from
these archives. these archives.
The release archives contain several files and folders, including a ``hack`` The release archives contain several folders, including a ``hack`` folder where
folder, a ``dfhack-config`` folder, and a ``dfhack.init-example`` file. To DFHack binary and system data is stored, a ``dfhack-config`` folder where user
install DFHack, copy all of the files from the DFHack archive into the root DF data and configuration is stored, and a ``blueprints`` folder where `quickfort`
folder, which should already include a ``data`` folder and a ``raw`` folder, blueprints are stored. To install DFHack, copy all of the files from the DFHack
among other things. Some packs and other redistributions of Dwarf Fortress may archive into the root DF folder, which should already include a ``data`` folder
place DF in another folder, so ensure that the ``hack`` folder ends up next to and a ``raw`` folder, among other things. Some packs and other redistributions
the ``data`` folder. of Dwarf Fortress may place DF in another folder, so ensure that the ``hack``
folder ends up next to the ``data`` folder.
.. note:: .. note::

@ -21,7 +21,7 @@ enhancements by default, and more can be enabled. There are also many tools
You can even add third-party scripts and plugins to do almost anything! You can even add third-party scripts and plugins to do almost anything!
For modders, DFHack makes many things possible. Custom reactions, new For modders, DFHack makes many things possible. Custom reactions, new
interactions, magic creature abilities, and more can be set through `scripts-modtools` interactions, magic creature abilities, and more can be set through `DFHack tools <genindex>`
and custom raws. Non-standard DFHack scripts and inits can be stored in the and custom raws. Non-standard DFHack scripts and inits can be stored in the
raw directory, making raws or saves fully self-contained for distribution - raw directory, making raws or saves fully self-contained for distribution -
or for coexistence in a single DF install, even with incompatible components. or for coexistence in a single DF install, even with incompatible components.
@ -59,7 +59,43 @@ used by the DFHack console.
* Finally, some commands are persistent once enabled, and will sit in the * Finally, some commands are persistent once enabled, and will sit in the
background managing or changing some aspect of the game if you `enable` them. background managing or changing some aspect of the game if you `enable` them.
.. note::
In order to avoid user confusion, as a matter of policy all GUI tools
display the word :guilabel:`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.
.. _support:
Getting help Getting help
============ ============
There are several support channels available - see `support` for details.
DFHack has several ways to get help online, including:
- The `DFHack Discord server <https://dfhack.org/discord>`__
- The ``#dfhack`` IRC channel on `Libera <https://libera.chat/>`__
- GitHub:
- for bugs, use the :issue:`issue tracker <>`
- for more open-ended questions, use the `discussion board
<https://github.com/DFHack/dfhack/discussions>`__. Note that this is a
relatively-new feature as of 2021, but maintainers should still be
notified of any discussions here.
- The `DFHack thread on the Bay 12 Forum <https://dfhack.org/bay12>`__
Some additional, but less DFHack-specific, places where questions may be answered include:
- The `/r/dwarffortress <https://dwarffortress.reddit.com>`_ questions thread on Reddit
- If you are using a starter pack, the relevant thread on the `Bay 12 Forum <http://www.bay12forums.com/smf/index.php?board=2.0>`__ -
see the :wiki:`DF Wiki <Utility:Lazy_Newb_Pack>` for a list of these threads
When reaching out to any support channels regarding problems with DFHack, please
remember to provide enough details for others to identify the issue. For
instance, specific error messages (copied text or screenshots) are helpful, as
well as any steps you can follow to reproduce the problem. Sometimes, log output
from ``stderr.log`` in the DF folder can point to the cause of issues as well.
Some common questions may also be answered in documentation, including:
- This documentation (`online here <https://dfhack.readthedocs.io>`__; search functionality available `here <search>`)
- :wiki:`The DF wiki <>`

@ -4397,7 +4397,7 @@ blueprint files:
The names of the functions are also available as the keys of the The names of the functions are also available as the keys of the
``valid_phases`` table. ``valid_phases`` table.
.. _building-hacks: .. _building-hacks-api:
building-hacks building-hacks
============== ==============
@ -4536,7 +4536,7 @@ Native functions:
The lua module file also re-exports functions from ``dfhack.burrows``. The lua module file also re-exports functions from ``dfhack.burrows``.
.. _cxxrandom: .. _cxxrandom-api:
cxxrandom cxxrandom
========= =========
@ -4706,7 +4706,7 @@ The dig-now plugin exposes the following functions to Lua:
command ``dig-now <pos> <pos>``. See the `dig-now` documentation for details command ``dig-now <pos> <pos>``. See the `dig-now` documentation for details
on default settings. on default settings.
.. _eventful: .. _eventful-api:
eventful eventful
======== ========
@ -4874,7 +4874,7 @@ Integrated tannery::
b=require "plugins.eventful" b=require "plugins.eventful"
b.addReactionToShop("TAN_A_HIDE","LEATHERWORKS") b.addReactionToShop("TAN_A_HIDE","LEATHERWORKS")
.. _luasocket: .. _luasocket-api:
luasocket luasocket
========= =========
@ -4945,7 +4945,7 @@ A class with all the tcp functionality.
Tries connecting to that address and port. Returns ``client`` object. Tries connecting to that address and port. Returns ``client`` object.
.. _map-render: .. _map-render-api:
map-render map-render
========== ==========
@ -4961,7 +4961,7 @@ Functions
returns a table with w*h*4 entries of rendered tiles. The format is same as ``df.global.gps.screen`` (tile,foreground,bright,background). returns a table with w*h*4 entries of rendered tiles. The format is same as ``df.global.gps.screen`` (tile,foreground,bright,background).
.. _pathable: .. _pathable-api:
pathable pathable
======== ========
@ -4995,7 +4995,7 @@ sort
The `sort <sort>` plugin does not export any native functions as of now. The `sort <sort>` plugin does not export any native functions as of now.
Instead, it calls Lua code to perform the actual ordering of list items. Instead, it calls Lua code to perform the actual ordering of list items.
.. _xlsxreader: .. _xlsxreader-api:
xlsxreader xlsxreader
========== ==========

@ -63,7 +63,7 @@ are not built by default, but can be built by setting the ``BUILD_DEVEL``
Scripts Scripts
~~~~~~~ ~~~~~~~
Several `development scripts <scripts-devel>` can be useful for memory research. Several `development tools <tag/dev>` can be useful for memory research.
These include (but are not limited to): These include (but are not limited to):
- `devel/dump-offsets` - `devel/dump-offsets`

@ -17,4 +17,4 @@ See `changelog` for a list of changes grouped by stable releases.
:local: :local:
:depth: 1 :depth: 1
.. include:: /docs/_auto/news-dev.rst .. include:: /docs/changelogs/news-dev.rst

@ -17,7 +17,7 @@ See `dev-changelog` for a list of changes grouped by development releases.
:local: :local:
:depth: 1 :depth: 1
.. include:: /docs/_auto/news.rst .. include:: /docs/changelogs/news.rst
Older Changelogs Older Changelogs

File diff suppressed because it is too large Load Diff

@ -48,6 +48,14 @@ existing .csv files. Just move them to the ``blueprints`` folder in your DF
installation, and instead of ``digfort file.csv``, run installation, and instead of ``digfort file.csv``, run
``quickfort run file.csv``. ``quickfort run file.csv``.
.. _fix-armory:
fix-armory
==========
Allowed the military to store equipment in barracks containers. Removed because
it required a binary patch to DF in order to function, and no such patch has
existed since DF 0.34.11.
.. _fix/build-location: .. _fix/build-location:
fix/build-location fix/build-location
@ -74,9 +82,9 @@ Replaced by `gui/create-item`.
gui/no-dfhack-init gui/no-dfhack-init
================== ==================
No longer useful since the user doesn't have to create their own ``dfhack.init`` Tool that warned the user when the ``dfhack.init`` file did not exist. Now that
file now that init files have moved to ``dfhack-config/init``. It used to show ``dfhack.init`` is autogenerated in ``dfhack-config/init``, this warning is no
a warning at startup if :file:`dfhack.init` file was not found. longer necessary.
.. _warn-stuck-trees: .. _warn-stuck-trees:

@ -1,19 +0,0 @@
.. _scripts-index:
##############
DFHack Scripts
##############
Lua or ruby scripts placed in the :file:`hack/scripts/` directory
are considered for execution as if they were native DFHack commands.
The following pages document all the scripts in the DFHack standard library.
.. toctree::
:maxdepth: 2
/docs/_auto/base
/docs/_auto/devel
/docs/_auto/fix
/docs/_auto/gui
/docs/_auto/modtools

@ -1,34 +1,3 @@
.. _support: :orphan:
=============== Please continue to the new `support` page.
Getting Support
===============
DFHack has several ways to get help online, including:
- The `DFHack Discord server <https://dfhack.org/discord>`__
- The ``#dfhack`` IRC channel on `Libera <https://libera.chat/>`__
- GitHub:
- for bugs, use the :issue:`issue tracker <>`
- for more open-ended questions, use the `discussion board
<https://github.com/DFHack/dfhack/discussions>`__. Note that this is a
relatively-new feature as of 2021, but maintainers should still be
notified of any discussions here.
- The `DFHack thread on the Bay 12 Forum <https://dfhack.org/bay12>`__
Some additional, but less DFHack-specific, places where questions may be answered include:
- The `/r/dwarffortress <https://dwarffortress.reddit.com>`_ questions thread on Reddit
- If you are using a starter pack, the relevant thread on the `Bay 12 Forum <http://www.bay12forums.com/smf/index.php?board=2.0>`__ -
see the :wiki:`DF Wiki <Utility:Lazy_Newb_Pack>` for a list of these threads
When reaching out to any support channels regarding problems with DFHack, please
remember to provide enough details for others to identify the issue. For
instance, specific error messages (copied text or screenshots) are helpful, as
well as any steps you can follow to reproduce the problem. Sometimes, log output
from ``stderr.log`` in the DF folder can point to the cause of issues as well.
Some common questions may also be answered in documentation, including:
- This documentation (`online here <https://dfhack.readthedocs.io>`__; search functionality available `here <search>`)
- :wiki:`The DF wiki <>`

@ -0,0 +1,48 @@
:orphan:
.. _tag-list:
DFHack tool tags
================
A tool often has at least one tag per group, encompassing when you use the tool,
why you might want to use it, and what kind of thing you're trying to affect.
See https://docs.google.com/spreadsheets/d/1hiDlo8M_bB_1jE-5HRs2RrrA_VZ4cRu9VXaTctX_nwk/edit#gid=1774645373
for the tag assignment spreadsheet.
"when" tags
-----------
- `tag/adventure`: Tools that are useful while in adventure mode. Note that some tools only tagged with "fort" might also work in adventure mode, but not always in expected ways. Feel free to experiment, though!
- `tag/dfhack`: Tools that you use to run DFHack commands or interact with the DFHack library. This tag also includes tools that help you manage the DF game itself (e.g. settings, saving, etc.)
- `tag/embark`: Tools that are useful while on the fort embark screen or while creating an adventurer.
- `tag/fort`: Tools that are useful while in fort mode.
- `tag/legends`: Tools that are useful while in legends mode.
"why" tags
----------
- `tag/armok`: Tools that give you complete control over an aspect of the game or provide access to information that the game intentionally keeps hidden.
- `tag/auto`: Tools that run in the background and automatically manage routine, toilsome aspects of your fortress.
- `tag/bugfix`: Tools that fix specific bugs, either permanently or on-demand.
- `tag/design`: Tools that help you design your fort.
- `tag/dev`: Tools that are useful when developing scripts or mods.
- `tag/fps`: Tools that help you manage FPS drop.
- `tag/gameplay`: Tools that introduce new gameplay elements.
- `tag/inspection`: Tools that let you view information that is otherwise difficult to find.
- `tag/productivity`: Tools that help you do things that you could do manually, but using the tool is better and faster.
"what" tags
-----------
- `tag/animals`: Tools that interact with animals.
- `tag/buildings`: Tools that interact with buildings and furniture.
- `tag/graphics`: Tools that interact with game graphics.
- `tag/interface`: Tools that interact with or extend the DF user interface.
- `tag/items`: Tools that interact with in-game items.
- `tag/jobs`: Tools that interact with jobs.
- `tag/labors`: Tools that deal with labor assignment.
- `tag/map`: Tools that interact with the game map.
- `tag/military`: Tools that interact with the military.
- `tag/plants`: Tools that interact with trees, shrubs, and crops.
- `tag/stockpiles`: Tools that interact wtih stockpiles.
- `tag/units`: Tools that interact with units.
- `tag/workorders`: Tools that interact with workorders.

@ -0,0 +1,50 @@
.. _tools:
DFHack tools
============
DFHack has **a lot** of tools. This page attempts to make it clearer what they
are, how they work, and how to find the ones you want.
.. contents:: Contents
:local:
What tools are and how they work
--------------------------------
DFHack is a Dwarf Fortress memory access and modification framework, so DFHack
tools normally access Dwarf Fortress internals and make some specific changes.
Some tools just make a targeted change when you run them, like `unforbid`, which
scans through all your items and removes the ``forbidden`` flag from each of
them.
Some tools need to be enabled, and then they run in the background and make
changes to the game on your behalf, like `autobutcher`, which monitors your
livestock population and automatically marks excess animals for butchering.
And some tools just exist to give you information that is otherwise hard to
come by, like `gui/petitions`, which shows you the active petitions for
guildhalls and temples that you have agreed to.
Finding the tool you need
-------------------------
DFHack tools are tagged with categories to make them easier to find. Note that a
tool can belong to more than one category. If you'd like to see the full list of
tools in one flat list, please refer to the `index <genindex>`.
DFHack tools by game mode
-------------------------
.. include:: tags/bywhen.rst
DFHack tools by theme
---------------------
.. include:: tags/bywhy.rst
DFHack tools by what they affect
--------------------------------
.. include:: tags/bywhat.rst

@ -1 +0,0 @@
*.rst

@ -1 +0,0 @@
*.txt

@ -1,23 +0,0 @@
#!/bin/sh
# usage:
# ./build-pdf.sh
# SPHINX=/path/to/sphinx-build ./build-pdf.sh
# JOBS=3 ./build-pdf.sh ...
# all command-line arguments are passed directly to sphinx-build - run
# ``sphinx-build --help`` for a list, or see
# https://www.sphinx-doc.org/en/master/man/sphinx-build.html
cd $(dirname "$0")
cd ..
sphinx=sphinx-build
if [ -n "$SPHINX" ]; then
sphinx=$SPHINX
fi
if [ -z "$JOBS" ]; then
JOBS=2
fi
"$sphinx" -M latexpdf . ./docs/pdf -w ./docs/_sphinx-warnings.txt -j "$JOBS" "$@"

@ -0,0 +1,100 @@
#!/usr/bin/env python3
# for help, run: python3 build.py --help
import argparse
import os
import subprocess
import sys
class SphinxOutputFormat:
def __init__(self, name, pre_args):
self.name = str(name)
self.pre_args = tuple(pre_args)
@property
def args(self):
output_dir = os.path.join('docs', self.name)
artifacts_dir = os.path.join('build', 'docs', self.name) # for artifacts not part of the final documentation
return [
*self.pre_args,
'.', # source dir
output_dir,
'-d', artifacts_dir,
'-w', os.path.join(artifacts_dir, 'sphinx-warnings.txt'),
]
OUTPUT_FORMATS = {
'html': SphinxOutputFormat('html', pre_args=['-b', 'html']),
'text': SphinxOutputFormat('text', pre_args=['-b', 'text']),
'pdf': SphinxOutputFormat('pdf', pre_args=['-M', 'latexpdf']),
'xml': SphinxOutputFormat('xml', pre_args=['-b', 'xml']),
'pseudoxml': SphinxOutputFormat('pseudoxml', pre_args=['-b', 'pseudoxml']),
}
def _parse_known_args(parser, source_args):
# pass along any arguments after '--'
ignored_args = []
if '--' in source_args:
source_args, ignored_args = source_args[:source_args.index('--')], source_args[source_args.index('--')+1:]
args, forward_args = parser.parse_known_args(source_args)
forward_args += ignored_args
return args, forward_args
def parse_args(source_args):
def output_format(s):
if s in OUTPUT_FORMATS:
return s
raise ValueError
parser = argparse.ArgumentParser(usage='%(prog)s [{} ...] [options] [--] [sphinx_options]'.format('|'.join(OUTPUT_FORMATS.keys())), description='''
DFHack wrapper around sphinx-build.
Any unrecognized options are passed directly to sphinx-build, as well as any
options following a '--' argument, if specified.
''')
parser.add_argument('format', nargs='*', type=output_format, action='append',
help='Documentation format(s) to build - choose from {}'.format(', '.join(OUTPUT_FORMATS.keys())))
parser.add_argument('-E', '--clean', action='store_true',
help='Re-read all input files')
parser.add_argument('--sphinx', type=str, default=os.environ.get('SPHINX', 'sphinx-build'),
help='Sphinx executable to run [environment variable: SPHINX; default: "sphinx-build"]')
parser.add_argument('-j', '--jobs', type=str, default=os.environ.get('JOBS', 'auto'),
help='Number of Sphinx threads to run [environment variable: JOBS; default: "auto"]')
parser.add_argument('--debug', action='store_true',
help='Log commands that are run, etc.')
parser.add_argument('--offline', action='store_true',
help='Disable network connections')
args, forward_args = _parse_known_args(parser, source_args)
# work around weirdness with list args
args.format = args.format[0]
if not args.format:
args.format = ['html']
return args, forward_args
if __name__ == '__main__':
os.chdir(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
if not os.path.isfile('conf.py'):
print('Could not find conf.py', file=sys.stderr)
exit(1)
args, forward_args = parse_args(sys.argv[1:])
sphinx_env = os.environ.copy()
if args.offline:
sphinx_env['DFHACK_DOCS_BUILD_OFFLINE'] = '1'
for format_name in args.format:
command = [args.sphinx] + OUTPUT_FORMATS[format_name].args + ['-j', args.jobs]
if args.clean:
command += ['-E']
command += forward_args
if args.debug:
print('Building:', format_name)
print('Running:', command)
subprocess.run(command, check=True, env=sphinx_env)
print('')

@ -1,23 +0,0 @@
#!/bin/sh
# usage:
# ./build.sh
# SPHINX=/path/to/sphinx-build ./build.sh
# JOBS=3 ./build.sh ...
# all command-line arguments are passed directly to sphinx-build - run
# ``sphinx-build --help`` for a list, or see
# https://www.sphinx-doc.org/en/master/man/sphinx-build.html
cd $(dirname "$0")
cd ..
sphinx=sphinx-build
if [ -n "$SPHINX" ]; then
sphinx=$SPHINX
fi
if [ -z "$JOBS" ]; then
JOBS=2
fi
"$sphinx" -a -b html . ./docs/html -w ./docs/_sphinx-warnings.txt -j "$JOBS" "$@"

@ -0,0 +1,36 @@
alias
=====
.. dfhack-tool::
:summary: Configure helper aliases for other DFHack commands.
:tags: dfhack
Aliases are resolved immediately after built-in commands, which means that an
alias cannot override a built-in command, but can override a command implemented
by a plugin or script.
Usage
-----
``alias list``
Lists all configured aliases
``alias add <name> <command> [arguments...]``
Adds an alias
``alias replace <name> <command> [arguments...]``
Replaces an existing alias with a new command, or adds the alias if it does
not already exist
``alias delete <name>``
Removes the specified alias
Aliases can be given additional arguments when created and invoked, which will
be passed to the underlying command in order.
Example
-------
::
[DFHack]# alias add pargs devel/print-args example
[DFHack]# pargs text
example
text

@ -0,0 +1,16 @@
cls
===
.. dfhack-tool::
:summary: Clear the terminal screen.
:tags: dfhack
Can also be invoked as ``clear``. Note that this command does not delete command
history. It just clears the text on the screen.
Usage
-----
::
cls

@ -0,0 +1,15 @@
devel/dump-rpc
==============
.. dfhack-tool::
:summary: Dump RPC endpoint info.
:tags: dev
Write RPC endpoint information to the specified file.
Usage
-----
::
devel/dump-rpc <filename>

@ -0,0 +1,15 @@
die
===
.. dfhack-tool::
:summary: Instantly exit DF without saving.
:tags: dfhack
Use to exit DF quickly and safely.
Usage
-----
::
die

@ -0,0 +1,15 @@
disable
=======
.. dfhack-tool::
:summary: Deactivate a DFHack tool that has some persistent effect.
:tags: dfhack
See the `enable` command for more info.
Usage
-----
::
disable <plugin> [<plugin> ...]

@ -0,0 +1,33 @@
enable
======
.. dfhack-tool::
:summary: Activate a DFHack tool that has some persistent effect.
:tags: dfhack
Many plugins and scripts can be in a distinct enabled or disabled state. Some
of them activate and deactivate automatically depending on the contents of the
world raws. Others store their state in world data. However a number of them
have to be enabled globally, and the init file is the right place to do it.
Most such plugins or scripts support the built-in ``enable`` and `disable`
commands. Calling them at any time without arguments prints a list of enabled
and disabled plugins, and shows whether that can be changed through the same
commands. Passing plugin names to these commands will enable or disable the
specified plugins.
Usage
-----
::
enable
enable <plugin> [<plugin> ...]
Examples
--------
``enable manipulator``
Enable the ``manipulator`` plugin.
``enable manipulator search``
Enable multiple plugins at once.

@ -0,0 +1,15 @@
fpause
======
.. dfhack-tool::
:summary: Forces DF to pause.
:tags: dfhack
This is useful when your FPS drops below 1 and you lose control of the game.
Usage
-----
::
fpause

@ -0,0 +1,29 @@
help
====
.. dfhack-tool::
:summary: Display help about a command or plugin.
:tags: dfhack
Can also be invoked as ``?`` or ``man`` (short for "manual").
Usage
-----
::
help|?|man
help|?|man <command or plugin>
Examples
--------
::
help blueprint
man blueprint
Both examples above will display the help text for the `blueprint` command.
Some commands also take ``help`` or ``?`` as an option on their command line
for the same effect -- e.g. ``blueprint help``.

@ -0,0 +1,18 @@
hide
====
.. dfhack-tool::
:summary: Hide the DFHack terminal window.
:tags: dfhack
You can show it again with the `show` command, though you'll need to use it from
a `keybinding` set beforehand or the in-game `command-prompt`.
Only available on Windows.
Usage
-----
::
hide

@ -0,0 +1,61 @@
keybinding
==========
.. dfhack-tool::
:summary: Create hotkeys that will run DFHack commands.
:tags: dfhack
Like any other command, it can be used at any time from the console, but
bindings are not remembered between runs of the game unless re-created in
`dfhack.init`.
Hotkeys can be any combinations of Ctrl/Alt/Shift with A-Z, 0-9, F1-F12, or
``\``` (the key below the ``Esc`` key.
Usage
-----
``keybinding``
Show some useful information, including the current game context.
``keybinding list <key>``
List bindings active for the key combination.
``keybinding clear <key> [<key>...]``
Remove bindings for the specified keys.
``keybinding add <key> "cmdline" ["cmdline"...]``
Add bindings for the specified key.
``keybinding set <key> "cmdline" ["cmdline"...]``
Clear, and then add bindings for the specified key.
The ``<key>`` parameter above has the following **case-sensitive** syntax::
[Ctrl-][Alt-][Shift-]KEY[@context[|context...]]
where the ``KEY`` part can be any recognized key and [] denote optional parts.
When multiple commands are bound to the same key combination, DFHack selects
the first applicable one. Later ``add`` commands, and earlier entries within one
``add`` command have priority. Commands that are not specifically intended for
use as a hotkey are always considered applicable.
The ``context`` part in the key specifier above can be used to explicitly
restrict the UI state where the binding would be applicable.
Only bindings with a ``context`` tag that either matches the current context
fully, or is a prefix ending at a ``/`` boundary would be considered for
execution, i.e. when in context ``foo/bar/baz``, keybindings restricted to any
of ``@foo/bar/baz``, ``@foo/bar``, ``@foo``, or none will be active.
Multiple contexts can be specified by separating them with a pipe (``|``) - for
example, ``@foo|bar|baz/foo`` would match anything under ``@foo``, ``@bar``, or
``@baz/foo``.
Interactive commands like `liquids` cannot be used as hotkeys.
Examples
--------
``keybinding add Alt-F1 hotkeys``
Bind Alt-F1 to run the `hotkeys` command on any screen at any time.
``keybinding add Alt-F@dwarfmode gui/quickfort``
Bind Alt-F to run `gui/quickfort`, but only when on a screen that shows the
main map.

@ -0,0 +1,18 @@
kill-lua
========
.. dfhack-tool::
:summary: Gracefully stop any currently-running Lua scripts.
:tags: dfhack
Use this command to stop a misbehaving script that appears to be stuck.
Usage
-----
::
kill-lua
kill-lua force
Use ``kill-lua force`` if just ``kill-lua`` doesn't seem to work.

@ -0,0 +1,19 @@
load
====
.. dfhack-tool::
:summary: Load and register a plugin library.
:tags: dfhack
Also see `unload` and `reload` for related actions.
Usage
-----
::
load <plugin> [<plugin> ...]
load -a|--all
You can load individual named plugins or all plugins at once. Note that plugins
are disabled after loading/reloading until you explicitly `enable` them.

@ -0,0 +1,40 @@
ls
==
.. dfhack-tool::
:summary: List available DFHack commands.
:tags: dfhack
In order to group related commands, each command is associated with a list of
tags. You can filter the listed commands by a tag or a substring of the
command name. Can also be invoked as ``dir``.
Usage
-----
``ls [<options>]``
Lists all available commands and the tags associated with them.
``ls <tag> [<options>]``
Shows only commands that have the given tag. Use the `tags` command to see
the list of available tags.
``ls <string> [<options>]``
Shows commands that include the given string. E.g. ``ls quick`` will show
all the commands with "quick" in their names. If the string is also the
name of a tag, then it will be interpreted as a tag name.
Examples
--------
- ``ls adventure``
Lists all commands with the ``adventure`` tag.
- ``ls --dev trigger``
Lists all commands, including developer and modding commands, that match the
substring "trigger"
Options
-------
``--notags``
Don't print out the tags associated with each command.
``--dev``
Include commands intended for developers and modders.

@ -0,0 +1,16 @@
plug
====
.. dfhack-tool::
:summary: List available plugins and whether they are enabled.
:tags: dfhack
Usage
-----
::
plug [<plugin> [<plugin> ...]]
If run with parameters, it lists only the named plugins. Otherwise it will list
all available plugins.

@ -0,0 +1,21 @@
reload
======
.. dfhack-tool::
:summary: Reload a loaded plugin.
:tags: dfhack
Developers use this command to reload a plugin that they are actively modifying.
Also see `load` and `unload` for related actions.
Usage
-----
::
reload <plugin> [<plugin> ...]
reload -a|--all
You can reload individual named plugins or all plugins at once. Note that
plugins are disabled after loading/reloading until you explicitly `enable`
them.

@ -0,0 +1,26 @@
sc-script
=========
.. dfhack-tool::
:summary: Run commands when game state changes occur.
:tags: dfhack
This is similar to the static `init-files` but is slightly more flexible since
it can be set dynamically.
Usage
-----
``sc-script [help]``
Show the list of valid event names.
``sc-script list [<event>]``
List the currently registered files for all events or the specified event.
``sc-script add|remove <event> <file> [<file> ...]``
Register or unregister a file to be run for the specified event.
Example
-------
``sc-script add SC_MAP_LOADED spawn_extra_monsters.init``
Registers the ``spawn_extra_monsters.init`` file to be run whenever a new
map is loaded.

@ -0,0 +1,26 @@
script
======
.. dfhack-tool::
:summary: Execute a batch file of DFHack commands.
:tags: dfhack
It reads a text file and runs each line as a DFHack command as if it had been
typed in by the user -- treating the input like `an init file <init-files>`.
Some other tools, such as `autobutcher` and `workflow`, export their settings as
the commands to create them - which can later be reloaded with ``script``.
Usage
-----
::
script <filename>
Example
-------
``script startup.txt``
Executes the commands in ``startup.txt``, which exists in your DF game
directory.

@ -0,0 +1,19 @@
show
====
.. dfhack-tool::
:summary: Unhides the DFHack terminal window.
:tags: dfhack
Useful if you have hidden the terminal with `hide` and you want it back. Since
the terminal window won't be available to run this command, you'll need to use
it from a `keybinding` set beforehand or the in-game `command-prompt`.
Only available on Windows.
Usage
-----
::
show

@ -0,0 +1,16 @@
tags
====
.. dfhack-tool::
:summary: List the strings that DFHack tools can be tagged with.
:tags: dfhack
You can find groups of related tools by passing the tag name to the `ls`
command.
Usage
-----
::
tags

@ -0,0 +1,17 @@
type
====
.. dfhack-tool::
:summary: Describe how a command is implemented.
:tags: dfhack
DFHack commands can be provided by plugins, scripts, or by the core library
itself. The ``type`` command can tell you which is the source of a particular
command.
Usage
-----
::
type <command>

@ -0,0 +1,18 @@
unload
======
.. dfhack-tool::
:summary: Unload a plugin from memory.
:tags: dfhack
Also see `load` and `reload` for related actions.
Usage
-----
::
unload <plugin> [<plugin> ...]
unload -a|--all
You can unload individual named plugins or all plugins at once.

@ -39,6 +39,9 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
## New Tweaks ## New Tweaks
## New Internal Commands
- `tags`: new built-in command to list the tool category tags and their definitions. tags associated with each tool are visible in the tool help and in the output of `ls`.
## Fixes ## Fixes
- ``job.removeJob()``: ensure jobs are removed from the world list when they are canceled - ``job.removeJob()``: ensure jobs are removed from the world list when they are canceled
@ -47,6 +50,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
- History files: ``dfhack.history``, ``tiletypes.history``, ``lua.history``, and ``liquids.history`` have moved to the ``dfhack-config`` directory. If you'd like to keep the contents of your current history files, please move them to ``dfhack-config``. - History files: ``dfhack.history``, ``tiletypes.history``, ``lua.history``, and ``liquids.history`` have moved to the ``dfhack-config`` directory. If you'd like to keep the contents of your current history files, please move them to ``dfhack-config``.
- `do-job-now`: new global keybinding for boosting the priority of the jobs associated with the selected building/work order/unit/item etc.: Alt-N - `do-job-now`: new global keybinding for boosting the priority of the jobs associated with the selected building/work order/unit/item etc.: Alt-N
- `keybinding`: support backquote (\`) as a hotkey (and assign the hotkey to the new `gui/launcher` interface) - `keybinding`: support backquote (\`) as a hotkey (and assign the hotkey to the new `gui/launcher` interface)
- `ls`: can now filter tools by substring or tag. note that dev scripts are hidden by default. pass the ``--dev`` option to show them.
- `manipulator`: add a library of useful default professions - `manipulator`: add a library of useful default professions
- `manipulator`: move professions configuration from ``professions/`` to ``dfhack-config/professions/`` to keep it together with other dfhack configuration. If you have saved professions that you would like to keep, please manually move them to the new folder. - `manipulator`: move professions configuration from ``professions/`` to ``dfhack-config/professions/`` to keep it together with other dfhack configuration. If you have saved professions that you would like to keep, please manually move them to the new folder.
- ``materials.ItemTraitsDialog``: added a default ``on_select``-handler which toggles the traits. - ``materials.ItemTraitsDialog``: added a default ``on_select``-handler which toggles the traits.
@ -58,6 +62,8 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
- `quickfort`: `Dreamfort <quickfort-blueprint-guide>` blueprint set improvements: set traffic designations to encourage dwarves to eat in the grand hall instead of the manager's office and to eat cooked food instead of raw ingredients - `quickfort`: `Dreamfort <quickfort-blueprint-guide>` blueprint set improvements: set traffic designations to encourage dwarves to eat in the grand hall instead of the manager's office and to eat cooked food instead of raw ingredients
## Documentation ## Documentation
- Update all DFHack tool documentation with standard syntax formatting, usage examples, and overall clarified text.
- Group DFHack tools by `tag <tools>` so similar tools are grouped and easy to find
## API ## API
- Removed "egg" ("eggy") hook support (Linux only). The only remaining method of hooking into DF is by interposing SDL calls, which has been the method used by all binary releases of DFHack. - Removed "egg" ("eggy") hook support (Linux only). The only remaining method of hooking into DF is by interposing SDL calls, which has been the method used by all binary releases of DFHack.
@ -1056,7 +1062,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
- `caravan`: documented (new in 0.44.10-alpha1) - `caravan`: documented (new in 0.44.10-alpha1)
- `deathcause`: added "slaughtered" to descriptions - `deathcause`: added "slaughtered" to descriptions
- `fix/retrieve-units`: now re-adds units to active list to counteract `fix/dead-units` - `fix/retrieve-units`: now re-adds units to active list to counteract `fix/dead-units`
- `item-descriptions`: fixed several grammatical errors - ``item-descriptions``: fixed several grammatical errors
- `modtools/create-unit`: - `modtools/create-unit`:
- added quantity argument - added quantity argument
- now selects a caste at random if none is specified - now selects a caste at random if none is specified

@ -28,8 +28,8 @@ it is useful (and customizable) for any fort. It includes the following config:
- Calls `ban-cooking` for items that have important alternate uses and should - Calls `ban-cooking` for items that have important alternate uses and should
not be cooked. This configuration is only set when a fortress is first not be cooked. This configuration is only set when a fortress is first
started, so later manual changes will not be overridden. started, so later manual changes will not be overridden.
- Automates calling of various fort maintenance and `scripts-fix`, like - Automates calling of various fort maintenance scripts, like `cleanowned` and
`cleanowned` and `fix/stuckdoors`. `fix/stuckdoors`.
- Keeps your manager orders intelligently ordered with `orders` ``sort`` so no - Keeps your manager orders intelligently ordered with `orders` ``sort`` so no
orders block other orders from ever getting completed. orders block other orders from ever getting completed.
- Periodically enqueues orders to shear and milk shearable and milkable pets. - Periodically enqueues orders to shear and milk shearable and milkable pets.

@ -5,9 +5,7 @@ Blueprint Library Index
======================= =======================
This guide contains a high-level overview of the blueprints available in the This guide contains a high-level overview of the blueprints available in the
:source:`quickfort blueprint library <data/blueprints/library>`. You can list :source:`quickfort blueprint library <data/blueprints/library>`.
library blueprints by running ``quickfort list --library`` or by hitting
:kbd:`Alt`:kbd:`l` in the ``gui/quickfort`` file load dialog.
Each file is hyperlinked to its online version so you can see exactly what the Each file is hyperlinked to its online version so you can see exactly what the
blueprints do before you run them. Also, if you use `gui/quickfort`, you will blueprints do before you run them. Also, if you use `gui/quickfort`, you will

@ -29,7 +29,7 @@ For those just looking to apply existing blueprints, check out the `quickfort
command's documentation <quickfort>` for syntax. There are also many command's documentation <quickfort>` for syntax. There are also many
ready-to-use blueprints available in the ``blueprints/library`` subfolder in ready-to-use blueprints available in the ``blueprints/library`` subfolder in
your DFHack installation. Browse them on your computer or your DFHack installation. Browse them on your computer or
:source:`online <data/blueprints/library>`, or run ``quickfort list -l`` at the :source:`online <data/blueprints/library>`, or run ``quickfort list`` at the
``[DFHack]#`` prompt to list them, and then ``quickfort run`` to apply them to ``[DFHack]#`` prompt to list them, and then ``quickfort run`` to apply them to
your fort! your fort!

Binary file not shown.

After

Width:  |  Height:  |  Size: 600 KiB

@ -0,0 +1,37 @@
3dveins
=======
.. dfhack-tool::
:summary: Rewrite layer veins to expand in 3D space.
:tags: fort gameplay map
Existing, flat veins are removed and new 3D veins that naturally span z-levels
are generated in their place. The transformation preserves the mineral counts
reported by `prospect`.
Usage
-----
::
3dveins [verbose]
The ``verbose`` option prints out extra information to the console.
Example
-------
::
3dveins
New veins are generated using 3D Perlin noise in order to produce a layout that
flows smoothly between z-levels. The vein distribution is based on the world
seed, so running the command for the second time should produce no change. It is
best to run it just once immediately after embark.
This command is intended as only a cosmetic change, so it takes care to exactly
preserve the mineral counts reported by ``prospect all``. The amounts of layer
stones may slightly change in some cases if vein mass shifts between z layers.
The only undo option is to restore your save from backup.

@ -0,0 +1,24 @@
RemoteFortressReader
====================
.. dfhack-tool::
:summary: Backend for Armok Vision.
:tags: dev graphics
:no-command:
.. dfhack-command:: RemoteFortressReader_version
:summary: Print the loaded RemoteFortressReader version.
.. dfhack-command:: load-art-image-chunk
:summary: Gets an art image chunk by index.
This plugin provides an API for realtime remote fortress visualization. See
:forums:`Armok Vision <146473>`.
Usage
-----
``RemoteFortressReader_version``
Print the loaded RemoteFortressReader version.
``load-art-image-chunk <chunk id>``
Gets an art image chunk by index, loading from disk if necessary.

@ -0,0 +1,14 @@
add-spatter
===========
.. dfhack-tool::
:summary: Make tagged reactions produce contaminants.
:tags: adventure fort gameplay items
:no-command:
Give some use to all those poisons that can be bought from caravans! The plugin
automatically enables itself when you load a world with reactions that include
names starting with ``SPATTER_ADD_``, so there are no commands to run to use it.
These reactions will then produce contaminants on items instead of improvements.
The contaminants are immune to being washed away by water or destroyed by
`clean`.

@ -0,0 +1,111 @@
autobutcher
===========
.. dfhack-tool::
:summary: Automatically butcher excess livestock.
:tags: fort auto fps animals
This plugin monitors how many pets you have of each gender and age and assigns
excess lifestock for slaughter. It requires that you add the target race(s) to a
watch list. Units will be ignored if they are:
* Untamed
* Nicknamed (for custom protection; you can use the `rename` ``unit`` tool
individually, or `zone` ``nick`` for groups)
* Caged, if and only if the cage is defined as a room (to protect zoos)
* Trained for war or hunting
Creatures who will not reproduce (because they're not interested in the
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 (defaults are: 1 male kid, 5 female kids, 1 male adult,
5 female adults). Note that you may need to set a target above 1 to have a
reliable breeding population due to asexuality etc. See `fix-ster` if this is a
problem.
Usage
-----
``enable autobutcher``
Start processing livestock according to the configuration. Note that
no races are watched by default. You have to add the ones you want to
monitor with ``autobutcher watch``, ``autobutcher target`` or
``autobutcher autowatch``.
``autobutcher autowatch``
Automatically add all new races (animals you buy from merchants, tame
yourself, or get from migrants) to the watch list using the default target
counts.
``autobutcher noautowatch``
Stop auto-adding new races to the watch list.
``autobutcher target <fk> <mk> <fa> <ma> all|new|<race> [<race> ...]``
Set target counts for the specified races:
- fk = number of female kids
- mk = number of male kids
- fa = number of female adults
- ma = number of female adults
If you specify ``all``, then this command will set the counts for all races
on your current watchlist (including the races which are currenly set to
'unwatched') and sets the new default for future watch commands. If you
specify ``new``, then this command just sets the new default counts for
future watch commands without changing your current watchlist. Otherwise,
all space separated races listed will be modified (or added to the watchlist
if they aren't there already).
``autobutcher ticks <ticks>``
Change the number of ticks between scanning cycles when the plugin is
enabled. By default, a cycle happens every 6000 ticks (about 8 game days).
``autobutcher watch all|<race> [<race> ...]``
Start watching the listed races. If they aren't already in your watchlist,
then they will be added with the default target counts. If you specify the
keyword ``all``, then all races in your watchlist that are currently marked
as unwatched will become watched.
``autobutcher unwatch all|<race> [<race> ...]``
Stop watching the specified race(s) (or all races on your watchlist if
``all`` is given). The current target settings will be remembered.
``autobutcher forget all|<race> [<race> ...]``
Unwatch the specified race(s) (or all races on your watchlist if ``all`` is
given) and forget target settings for it/them.
``autobutcher [list]``
Print status and current settings, including the watchlist. This is the
default command if autobutcher is run without parameters.
``autobutcher list_export``
Print commands required to set the current settings in another fort.
To see a list of all races, run this command:
devel/query --table df.global.world.raws.creatures.all --search ^creature_id --maxdepth 1
Though not all the races listed there are tameable/butcherable.
.. note::
Settings and watchlist are stored in the savegame, so you can have different
settings for each save. 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.
Examples
--------
Keep at most 7 kids (4 female, 3 male) and at most 3 adults (2 female, 1 male)
for turkeys. Once the kids grow up, the oldest adults will get slaughtered.
Excess kids will get slaughtered starting the the youngest to allow that the
older ones grow into adults::
autobutcher target 4 3 2 1 BIRD_TURKEY
Configure useful limits for dogs, cats, geese (for eggs, leather, and bones),
alpacas, sheep, and llamas (for wool), and pigs (for milk and meat). All other
unnamed tame units will be marked for slaughter as soon as they arrive in your
fortress::
enable autobutcher
autobutcher target 2 2 2 2 DOG
autobutcher target 1 1 2 2 CAT
autobutcher target 50 50 14 2 BIRD_GOOSE
autobutcher target 2 2 4 2 ALPACA SHEEP LLAMA
autobutcher target 5 5 6 2 PIG
autobutcher target 0 0 0 0 new
autobutcher autowatch

@ -0,0 +1,27 @@
autochop
========
.. dfhack-tool::
:summary: Auto-harvest trees when low on stockpiled logs.
:tags: fort auto plants
:no-command:
This plugin can designate trees for chopping when your stocks are low on logs.
Usage
-----
::
enable autochop
Then, open the settings menu with :kbd:`c` from the designations menu (the
option appears when you have "Chop Down Trees" selected with :kbd:`d`-:kbd:`t`).
Set your desired thresholds and enable autochopping with :kbd:`a`.
You can also restrict autochopping to specific burrows. Highlight a burrow name
with the Up/Down arrow keys and hit :kbd:`Enter` to mark it as the autochop
burrrow.
Autochop checks your stock of logs and designates trees once every in game day.

@ -0,0 +1,32 @@
autoclothing
============
.. dfhack-tool::
:summary: Automatically manage clothing work orders.
:tags: fort auto workorders
This command allows you to set how many of each clothing type every citizen
should have.
Usage
-----
::
autoclothing
autoclothing <material> <item> [quantity]
``material`` can be "cloth", "silk", "yarn", or "leather". The ``item`` can be
anything your civilization can produce, such as "dress" or "mitten".
When invoked without parameters, it shows a summary of all managed clothing
orders. When invoked with a material and item, but without a quantity, it shows
the current configuration for that material and item.
Examples
--------
``autoclothing cloth "short skirt" 10``
Sets the desired number of cloth short skirts available per citizen to 10.
``autoclothing cloth dress``
Displays the currently set number of cloth dresses chosen per citizen.

@ -0,0 +1,71 @@
autodump
========
.. dfhack-tool::
:summary: Automatically set items in a stockpile to be dumped.
:tags: fort armok fps productivity items stockpiles
:no-command:
.. dfhack-command:: autodump
:summary: Teleports items marked for dumping to the cursor position.
.. dfhack-command:: autodump-destroy-here
:summary: Destroy items marked for dumping under the cursor.
.. dfhack-command:: autodump-destroy-item
:summary: Destroys the selected item.
When `enabled <enable>`, this plugin adds an option to the :kbd:`q` menu for
stockpiles. When the ``autodump`` option is selected for the stockpile, any
items placed in the stockpile will automatically be designated to be dumped.
When invoked as a command, it can instantly move all unforbidden items marked
for dumping to the tile under the cursor. After moving the items, the dump flag
is unset and the forbid flag is set, just as if it had been dumped normally. Be
aware that dwarves that are en route to pick up the item for dumping may still
come and move the item to your dump zone.
The cursor must be placed on a floor tile so the items can be dumped there.
Usage
-----
::
enable autodump
autodump [<options>]
autodump-destroy-here
autodump-destroy-item
``autodump-destroy-here`` is an alias for ``autodump destroy-here`` and is
intended for use as a keybinding.
``autodump-destroy-item`` destroys only the selected item. The item may be
selected in the :kbd:`k` list or in the container item list. If called again
before the game is resumed, cancels destruction of the item.
Options
-------
``destroy``
Destroy instead of dumping. Doesn't require a cursor. If ``autodump`` is
called again with this option before the game is resumed, it cancels
pending destroy actions.
``destroy-here``
Destroy items marked for dumping under the cursor.
``visible``
Only process items that are not hidden.
``hidden``
Only process hidden items.
``forbidden``
Only process forbidden items (default: only unforbidden).
Examples
--------
``autodump``
Teleports items marked for dumping to the cursor position.
``autodump destroy``
Destroys all unforbidden items marked for dumping
``autodump-destroy-item``
Destroys the selected item.

@ -0,0 +1,37 @@
autofarm
========
.. dfhack-tool::
:summary: Automatically manage farm crop selection.
:tags: fort auto plants
Periodically scan your plant stocks and assign crops to your farm plots based on
which plant stocks are low (as long as you have the appropriate seeds). The
target threshold for each crop type is configurable.
Usage
-----
``enable autofarm``
Enable the plugin and start managing crop assignment.
``autofarm runonce``
Updates all farm plots once, without enabling the plugin.
``autofarm status``
Prints status information, including any defined thresholds.
``autofarm default <number>``
Sets the default threshold.
``autofarm threshold <number> <type> [<type> ...]``
Sets thresholds of individual plant types.
You can find the identifiers for the crop types in your world by running the
following command::
lua "for _,plant in ipairs(df.global.world.raws.plants.all) do if plant.flags.SEED then print(plant.id) end end"
Examples
--------
``autofarm default 30``
Set the default threshold to 30.
``autofarm threshold 150 MUSHROOM_HELMET_PLUMP GRASS_TAIL_PIG``
Set the threshold for Plump Helmets and Pig Tails to 150

@ -0,0 +1,26 @@
autogems
========
.. dfhack-tool::
:summary: Automatically cut rough gems.
:tags: fort auto workorders
:no-command:
.. dfhack-command:: autogems-reload
:summary: Reloads the autogems configuration file.
Automatically cut rough gems. This plugin periodically scans your stocks of
rough gems and creates manager orders for cutting them at a Jeweler's Workshop.
Usage
-----
``enable autogems``
Enables the plugin and starts autocutting gems according to its
configuration.
``autogems-reload``
Reloads the autogems configuration file. You might need to do this if you
have manually modified the contents while the game is running.
Run `gui/autogems` for a configuration UI, or access the ``Auto Cut Gems``
option from the Current Workshop Orders screen (:kbd:`o`-:kbd:`W`).

@ -0,0 +1,57 @@
autohauler
==========
.. dfhack-tool::
:summary: Automatically manage hauling labors.
:tags: fort auto labors
Similar to `autolabor`, but instead of managing all labors, ``autohauler`` only
addresses hauling labors, leaving the assignment of skilled labors entirely up
to you. You can use the in-game `manipulator` UI or an external tool like Dwarf
Therapist to do so.
Idle dwarves who are not on active military duty will be assigned the hauling
labors; everyone else (including those currently hauling) will have the hauling
labors removed. This is to encourage every dwarf to do their assigned skilled
labors whenever possible, but resort to hauling when those jobs are not
available. This also implies that the user will have a very tight skill
assignment, with most skilled labors only being assigned to just a few dwarves
and almost every non-military dwarf having at least one skilled labor assigned.
Autohauler allows a skill to be used as a flag to exempt a dwarf from
``autohauler``'s effects. By default, this is the unused ALCHEMIST labor, but it
can be changed by the user.
Usage
-----
``enable autohauler``
Start managing hauling labors. This is normally all you need to do.
Autohauler works well on default settings.
``autohauler status``
Show autohauler status and status of fort dwarves.
``autohauler <labor> haulers``
Set whether a particular labor should be assigned to haulers.
``autohauler <labor> allow|forbid``
Set whether a particular labor should mark a dwarf as exempt from hauling.
By default, only the ``ALCHEMIST`` labor is set to ``forbid``.
``autohauler reset-all|<labor> reset``
Reset a particular labor (or all labors) to their default
haulers/allow/forbid state.
``autohauler list``
Show the active configuration for all labors.
``autohauler frameskip <number>``
Set the number of frames between runs of autohauler.
``autohauler debug``
In the next cycle, output the state of every dwarf.
Examples
--------
``autohauler HAUL_STONE haulers``
Set stone hauling as a hauling labor (this is already the default).
``autohauler RECOVER_WOUNDED allow``
Allow the "Recover wounded" labor to be manually assigned by the player. By
default it is automatically given to haulers.
``autohauler MINE forbid``
Don't assign hauling labors to dwarves with the Mining labor enabled.

@ -0,0 +1,92 @@
autolabor
=========
.. dfhack-tool::
:summary: Automatically manage dwarf labors.
:tags: fort auto labors
Autolabor attempts to keep as many dwarves as possible busy while allowing
dwarves to specialize in specific skills.
Autolabor frequently checks how many jobs of each type are available and sets
labors proportionally in order to get them all done quickly. Labors with
equipment -- mining, hunting, and woodcutting -- which are abandoned if labors
change mid-job, are handled slightly differently to minimise churn.
Dwarves on active military duty or dwarves assigned to burrows are left
untouched by autolabor.
.. warning::
autolabor will override any manual changes you make to labors while it is
enabled, including through other tools such as Dwarf Therapist.
Usage
-----
::
enable autolabor
Anything beyond this is optional - autolabor works well with the default
settings. Once you have enabled it in a fortress, it stays enabled until you
explicitly disable it, even if you save and reload your game.
By default, each labor is assigned to between 1 and 200 dwarves (2-200 for
mining). 33% of the workforce become haulers, who handle all hauling jobs as
well as cleaning, pulling levers, recovering wounded, removing constructions,
and filling ponds. Other jobs are automatically assigned as described above.
Each of these settings can be adjusted.
Jobs are rarely assigned to nobles with responsibilities for meeting diplomats
or merchants, never to the chief medical dwarf, and less often to the bookeeper
and manager.
Hunting is never assigned without a butchery, and fishing is never assigned
without a fishery.
For each labor, a preference order is calculated based on skill, biased against
masters of other trades and excluding those who can't do the job. The labor is
then added to the best <minimum> dwarves for that labor, then to additional
dwarfs that meet any of these conditions:
* The dwarf is idle and there are no idle dwarves assigned to this labor
* The dwarf has non-zero skill associated with the labor
* The labor is mining, hunting, or woodcutting and the dwarf currently has it enabled.
We stop assigning dwarves when we reach the maximum allowed.
Examples
--------
``autolabor MINE 5``
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.
Advanced usage
--------------
``autolabor list``
List current status of all labors. Use this command to see the IDs for all
labors.
``autolabor status``
Show basic status information.
``autolabor <labor> <minimum> [<maximum>] [<talent pool>]``
Set range of dwarves assigned to a labor, optionally specifying the size of
the pool of most skilled dwarves that will ever be considered for this
labor.
``autolabor <labor> haulers``
Set a labor to be handled by hauler dwarves.
``autolabor <labor> disable``
Turn off autolabor for a specific labor.
``autolabor reset-all|<labor> reset``
Return a labor (or all labors) to the default handling.
See `autolabor-artisans` for a differently-tuned setup.

@ -0,0 +1,53 @@
automaterial
============
.. dfhack-tool::
:summary: Sorts building materials by recent usage.
:tags: fort design productivity buildings map
:no-command:
This plugin makes building constructions (walls, floors, fortifications, etc)
much easier by saving you from having to trawl through long lists of materials
each time you place one.
It moves the last used material for a given construction type to the top of the
list, if there are any left. So if you build a wall with chalk blocks, the next
time you place a wall the chalk blocks will be at the top of the list,
regardless of distance (it only does this in "grouped" mode, as individual item
lists could be huge). This means you can place most constructions without having
to search for your preferred material type.
Usage
-----
::
enable automaterial
.. image:: ../images/automaterial-mat.png
Pressing :kbd:`a` while highlighting any material will enable that material for
"auto select" for this construction type. You can enable multiple materials. Now
the next time you place this type of construction, the plugin will automatically
choose materials for you from the kinds you enabled. If there is enough to
satisfy the whole placement, you won't be prompted with the material screen at
all -- the construction will be placed and you will be back in the construction
menu.
When choosing the construction placement, you will see a couple of options:
.. image:: ../images/automaterial-pos.png
Use :kbd:`a` here to temporarily disable the material autoselection, e.g. if you
need to go to the material selection screen so you can toggle some materials on
or off.
The other option (auto type selection, off by default) can be toggled on with
:kbd:`t`. If you toggle this option on, instead of returning you to the main
construction menu after selecting materials, it returns you back to this screen.
If you use this along with several autoselect enabled materials, you should be
able to place complex constructions more conveniently.
The ``automaterial`` plugin also enables extra contruction placement modes, such
as designating areas larger than 10x10 and allowing you to designate hollow
rectangles instead of the default filled ones.

@ -0,0 +1,18 @@
automelt
========
.. dfhack-tool::
:summary: Quickly designate items to be melted.
:tags: fort productivity items stockpiles
:no-command:
When `enabled <enable>`, this plugin adds an option to the :kbd:`q` menu for
stockpiles. When the ``automelt`` option is selected for the stockpile, any
items placed in the stockpile will automatically be designated to be melted.
Usage
-----
::
enable automelt

@ -0,0 +1,33 @@
autonestbox
===========
.. dfhack-tool::
:summary: Auto-assign egg-laying female pets to nestbox zones.
:tags: fort auto animals
To use this feature, you must create pen/pasture zones above nestboxes. If the
pen is bigger than 1x1, the nestbox must be in the top left corner. Only 1 unit
will be assigned per pen, regardless of the size. Egg layers who are also
grazers will be ignored, since confining them to a 1x1 pasture is not a good
idea. Only tame and domesticated own units are processed since pasturing
half-trained wild egg layers could destroy your neat nestbox zones when they
revert to wild.
Note that the age of the units is not checked, so you might get some egg-laying
kids assigned to the nestbox zones. Most birds grow up quite fast, though, so
they should be adults and laying eggs soon enough.
Usage
-----
``enable autonestbox``
Start checking for unpastured egg-layers and assigning them to nestbox
zones.
``autonestbox``
Print current status.
``autonestbox now``
Run a scan and assignment cycle right now. Does not require that the plugin
is enabled.
``autonestbox ticks <ticks>``
Change the number of ticks between scan and assignment cycles when the
plugin is enabled. The default is 6000 (about 8 days).

@ -0,0 +1,18 @@
autotrade
=========
.. dfhack-tool::
:summary: Quickly designate items to be traded.
:tags: fort productivity items stockpiles
:no-command:
When `enabled <enable>`, this plugin adds an option to the :kbd:`q` menu for
stockpiles. When the ``autotrade`` option is selected for the stockpile, any
items placed in the stockpile will automatically be designated to be traded.
Usage
-----
::
enable autotrade

@ -0,0 +1,133 @@
blueprint
=========
.. dfhack-tool::
:summary: Record a live game map in a quickfort blueprint.
:tags: fort design buildings map stockpiles
With ``blueprint``, you can export the structure of a portion of your fortress
in a blueprint file that you (or anyone else) can later play back with
`quickfort`.
Blueprints are ``.csv`` or ``.xlsx`` files created in the ``blueprints``
subdirectory of your DF folder. The map area to turn into a blueprint is either
selected interactively with the ``blueprint gui`` command or, if the GUI is not
used, starts at the active cursor location and extends right and down for the
requested width and height.
Usage
-----
::
blueprint <width> <height> [<depth>] [<name> [<phases>]] [<options>]
blueprint gui [<name> [<phases>]] [<options>]
Examples
--------
``blueprint gui``
Runs `gui/blueprint`, the interactive frontend, where all configuration for
a ``blueprint`` command can be set visually and interactively.
``blueprint 30 40 bedrooms``
Generates blueprints for an area 30 tiles wide by 40 tiles tall, starting
from the active cursor on the current z-level. Blueprints are written to
``bedrooms.csv`` in the ``blueprints`` directory.
``blueprint 30 40 bedrooms dig --cursor 108,100,150``
Generates only the ``#dig`` blueprint in the ``bedrooms.csv`` file, and
the start of the blueprint area is set to a specific value instead of using
the in-game cursor position.
Positional parameters
---------------------
``width``
Width of the area (in tiles) to translate.
``height``
Height of the area (in tiles) to translate.
``depth``
Number of z-levels to translate. Positive numbers go *up* from the cursor
and negative numbers go *down*. Defaults to 1 if not specified, indicating
that the blueprint should only include the current z-level.
``name``
Base name for blueprint files created in the ``blueprints`` directory. If no
name is specified, "blueprint" is used by default. The string must contain
some characters other than numbers so the name won't be confused with the
optional ``depth`` parameter.
Phases
------
If you want to generate blueprints only for specific phases, add their names to
the commandline, anywhere after the blueprint base name. You can list multiple
phases; just separate them with a space.
``dig``
Generate quickfort ``#dig`` blueprints for digging natural stone.
``carve``
Generate quickfort ``#dig`` blueprints for smoothing and carving.
``build``
Generate quickfort ``#build`` blueprints for constructions and buildings.
``place``
Generate quickfort ``#place`` blueprints for placing stockpiles.
``zone``
Generate quickfort ``#zone`` blueprints for designating zones.
``query``
Generate quickfort ``#query`` blueprints for configuring rooms.
If no phases are specified, phases are autodetected. For example, a ``#place``
blueprint will be created only if there are stockpiles in the blueprint area.
Options
-------
``-c``, ``--cursor <x>,<y>,<z>``
Use the specified map coordinates instead of the current cursor position for
the upper left corner of the blueprint range. If this option is specified,
then an active game map cursor is not necessary.
``-e``, ``--engrave``
Record engravings in the ``carve`` phase. If this option is not specified,
engravings are ignored.
``-f``, ``--format <format>``
Select the output format of the generated files. See the `Output formats`_
section below for options. If not specified, the output format defaults to
"minimal", which will produce a small, fast ``.csv`` file.
``-h``, ``--help``
Show command help text.
``-s``, ``--playback-start <x>,<y>,<comment>``
Specify the column and row offsets (relative to the upper-left corner of the
blueprint, which is ``1,1``) where the player should put the cursor when the
blueprint is played back with `quickfort`, in
`quickfort start marker <quickfort-start>` format, for example:
``10,10,central stairs``. If there is a space in the comment, you will need
to surround the parameter string in double quotes:
``"-s10,10,central stairs"`` or ``--playback-start "10,10,central stairs"``
or ``"--playback-start=10,10,central stairs"``.
``-t``, ``--splitby <strategy>``
Split blueprints into multiple files. See the `Splitting output into
multiple files`_ section below for details. If not specified, defaults to
"none", which will create a standard quickfort
`multi-blueprint <quickfort-packaging>` file.
Output formats
--------------
Here are the values that can be passed to the ``--format`` flag:
``minimal``
Creates ``.csv`` files with minimal file size that are fast to read and
write. This is the default.
``pretty``
Makes the blueprints in the ``.csv`` files easier to read and edit with a
text editor by adding extra spacing and alignment markers.
Splitting output into multiple files
------------------------------------
The ``--splitby`` flag can take any of the following values:
``none``
Writes all blueprints into a single file. This is the standard format for
quickfort fortress blueprint bundles and is the default.
``phase``
Creates a separate file for each phase.

@ -0,0 +1,9 @@
building-hacks
==============
.. dfhack-tool::
:summary: Provides a Lua API for creating powered workshops.
:tags: fort gameplay buildings
:no-command:
See `building-hacks-api` for more details.

@ -0,0 +1,92 @@
buildingplan
============
.. dfhack-tool::
:summary: Plan building construction before you have materials.
:tags: fort design buildings
This plugin adds a planning mode for building placement. You can then place
furniture, constructions, and other buildings before the required materials are
available, and they will be created in a suspended state. Buildingplan will
periodically scan for appropriate items, and the jobs will be unsuspended when
the items are available.
This is very useful when combined with manager work orders or `workflow` -- you
can set a constraint to always have one or two doors/beds/tables/chairs/etc.
available, and place as many as you like. Materials are used to build the
planned buildings as they are produced, with minimal space dedicated to
stockpiles.
Usage
-----
::
enable buildingplan
buildingplan set
buildingplan set <setting> true|false
Running ``buildingplan set`` without parameters displays the current settings.
.. _buildingplan-settings:
Global settings
---------------
The buildingplan plugin has global settings that can be set from the UI
(:kbd:`G` from any building placement screen, for example:
:kbd:`b`:kbd:`a`:kbd:`G`). These settings can also be set via the
``buildingplan set`` command. The available settings are:
``all_enabled`` (default: false)
Enable planning mode for all building types.
``blocks``, ``boulders``, ``logs``, ``bars`` (defaults: true, true, true, false)
Allow blocks, boulders, logs, or bars to be matched for generic "building
material" items.
``quickfort_mode`` (default: false)
Enable compatibility mode for the legacy Python Quickfort (this setting is
not required for DFHack `quickfort`)
The settings for ``blocks``, ``boulders``, ``logs``, and ``bars`` are saved with
your fort, so you only have to set them once and they will be persisted in your
save.
If you normally embark with some blocks on hand for early workshops, you might
want to add this line to your ``dfhack-config/init/onMapLoad.init`` file to
always configure buildingplan to just use blocks for buildings and
constructions::
on-new-fortress buildingplan set boulders false; buildingplan set logs false
.. _buildingplan-filters:
Item filtering
--------------
While placing a building, you can set filters for what materials you want the
building made out of, what quality you want the component items to be, and
whether you want the items to be decorated.
If a building type takes more than one item to construct, use
:kbd:`Ctrl`:kbd:`Left` and :kbd:`Ctrl`:kbd:`Right` to select the item that you
want to set filters for. Any filters that you set will be used for all buildings
of the selected type placed from that point onward (until you set a new filter
or clear the current one). Buildings placed before the filters were changed will
keep the filter values that were set when the building was placed.
For example, you can be sure that all your constructed walls are the same color
by setting a filter to accept only certain types of stone.
Quickfort mode
--------------
If you use the external Python Quickfort to apply building blueprints instead of
the native DFHack `quickfort` script, you must enable Quickfort mode. This
temporarily enables buildingplan for all building types and adds an extra blank
screen after every building placement. This "dummy" screen is needed for Python
Quickfort to interact successfully with Dwarf Fortress.
Note that Quickfort mode is only for compatibility with the legacy Python
Quickfort. The DFHack `quickfort` script does not need this Quickfort mode to be
enabled. The `quickfort` script will successfully integrate with buildingplan as
long as the buildingplan plugin itself is enabled.

@ -0,0 +1,54 @@
burrows
=======
.. dfhack-tool::
:summary: Auto-expand burrows as you dig.
:tags: fort auto design productivity map units
:no-command:
.. dfhack-command:: burrow
:summary: Quickly add units/tiles to burrows.
When a wall inside a burrow with a name ending in ``+`` is dug out, the burrow
will be extended to newly-revealed adjacent walls.
Usage
-----
``burrow enable auto-grow``
When a wall inside a burrow with a name ending in '+' is dug out, the burrow
will be extended to newly-revealed adjacent walls. This final '+' may be
omitted in burrow name args of other ``burrow`` commands. Note that digging
1-wide corridors with the miner inside the burrow is SLOW.
``burrow disable auto-grow``
Disables auto-grow processing.
``burrow clear-unit <burrow> [<burrow> ...]``
Remove all units from the named burrows.
``burrow clear-tiles <burrow> [<burrow> ...]``
Remove all tiles from the named burrows.
``burrow set-units target-burrow <burrow> [<burrow> ...]``
Clear all units from the target burrow, then add units from the named source
burrows.
``burrow add-units target-burrow <burrow> [<burrow> ...]``
Add units from the source burrows to the target.
``burrow remove-units target-burrow <burrow> [<burrow> ...]``
Remove units in source burrows from the target.
``burrow set-tiles target-burrow <burrow> [<burrow> ...]``
Clear target burrow tiles and adds tiles from the names source burrows.
``burrow add-tiles target-burrow <burrow> [<burrow> ...]``
Add tiles from the source burrows to the target.
``burrow remove-tiles target-burrow <burrow> [<burrow> ...]``
Remove tiles in source burrows from the target.
In place of a source burrow, you can use one of the following keywords:
- ``ABOVE_GROUND``
- ``SUBTERRANEAN``
- ``INSIDE``
- ``OUTSIDE``
- ``LIGHT``
- ``DARK``
- ``HIDDEN``
- ``REVEALED``
to add tiles with the given properties.

@ -0,0 +1,44 @@
changeitem
==========
.. dfhack-tool::
:summary: Change item material or base quality.
:tags: adventure fort armok items
By default, a change is only allowed if the existing and desired item materials
are of the same subtype (for example wood -> wood, stone -> stone, etc). But
since some transformations work pretty well and may be desired you can override
this with ``force``. Note that forced changes can possibly result in items that
crafters and haulers refuse to touch.
Usage
-----
``changeitem info``
Show details about the selected item. Does not change the item. You can use
this command to discover RAW ids for existing items.
``changeitem [<options>]``
Change the item selected in the ``k`` list or inside a container/inventory.
``changeitem here [<options>]``
Change all items at the cursor position. Requires in-game cursor.
Examples
--------
``changeitem here m INORGANIC:GRANITE``
Change material of all stone items under the cursor to granite.
``changeitem q 5``
Change currently selected item to masterpiece quality.
Options
-------
``m``, ``material <RAW id>``
Change material. Must be followed by valid material RAW id.
``s``, ``subtype <RAW id>``
Change subtype. Must be followed by a valid subtype RAW id."
``q``, ``quality <quality>``
Change base quality. Must be followed by number (0-5) with 0 being no quality
and 5 being masterpiece quality.
``force``
Ignore subtypes and force the change to the new material.

@ -0,0 +1,76 @@
changelayer
===========
.. dfhack-tool::
:summary: Change the material of an entire geology layer.
:tags: fort armok map
Note that one layer can stretch across many z-levels, and changes to the geology
layer will affect all surrounding regions, not just your embark! Mineral veins
and gem clusters will not be affected. Use `changevein` if you want to modify
those.
tl;dr: You will end up with changing large areas in one go, especially if you
use it in lower z levels. Use this command with care!
Usage
-----
::
changelayer <material RAW id> [<options>]
When run without options, ``changelayer`` will:
- only affect the geology layer at the current cursor position
- only affect the biome that covers the current cursor position
- not allow changing stone to soil and vice versa
You can use the `probe` command on various tiles around your map to find valid
material RAW ids and to get an idea how layers and biomes are distributed.
Examples
--------
``changelayer GRANITE``
Convert the layer at the cursor position into granite.
``changelayer SILTY_CLAY force``
Convert teh layer at the cursor position into clay, even if it's stone.
``changelayer MARBLE all_biomes all_layers``
Convert all layers of all biomes which are not soil into marble.
.. note::
* If you use changelayer and nothing happens, try to pause/unpause the game
for a while and move the cursor to another tile. Then try again. If that
doesn't help, then try to temporarily change some other layer, undo your
changes, and try again for the layer you want to change. Saving and
reloading your map also sometimes helps.
* You should be fine if you only change single layers without the use
of 'force'. Still, it's advisable to save your game before messing with
the map.
* When you force changelayer to convert soil to stone, you might see some
weird stuff (flashing tiles, tiles changed all over place etc). Try
reverting the changes manually or even better use an older savegame. You
did save your game, right?
Options
-------
``all_biomes``
Change the corresponding geology layer for all biomes on your map. Be aware
that the same geology layer can AND WILL be on different z-levels for
different biomes.
``all_layers``
Change all geology layers on your map (only for the selected biome unless
``all_biomes`` is also specified). Candy mountain, anyone? Will make your map
quite boring, but tidy.
``force``
Allow changing stone to soil and vice versa. **THIS CAN HAVE WEIRD EFFECTS,
USE WITH CARE AND SAVE FIRST**. Note that soil will not be magically replaced
with stone. You will, however, get a stone floor after digging, so it will
allow the floor to be engraved. Similarly, stone will not be magically
replaced with soil, but you will get a soil floor after digging, so it could
be helpful for creating farm plots on maps with no soil.
``verbose``
Output details about what is being changed.

@ -0,0 +1,26 @@
changevein
==========
.. dfhack-tool::
:summary: Change the material of a mineral inclusion.
:tags: fort armok map
You can change a vein to any incorganic material RAW id. Note that this command
only affects tiles within the current 16x16 block - for large veins and
clusters, you will need to use this command multiple times.
You can use the `probe` command to discover the material RAW ids for existing
veins that you want to duplicate.
Usage
-----
::
changevein <material RAW id>
Example
-------
``changevein NATIVE_PLATINUM``
Convert vein at cursor position into platinum ore.

@ -0,0 +1,18 @@
cleanconst
==========
.. dfhack-tool::
:summary: Cleans up construction materials.
:tags: fort fps buildings
This tool alters all constructions on the map so that they spawn their building
component when they are disassembled, allowing their actual build items to be
safely deleted. This can improve FPS when you have many constructions on the
map.
Usage
-----
::
cleanconst

@ -0,0 +1,57 @@
.. _clean:
.. _spotclean:
cleaners
========
.. dfhack-tool::
:summary: Provides commands for cleaning spatter from the map.
:tags: adventure fort armok fps items map units
:no-command:
.. dfhack-command:: clean
:summary: Removes contaminants.
.. dfhack-command:: spotclean
:summary: Remove all contaminants from the tile under the cursor.
This plugin provides commands that clean the splatter that get scattered all
over the map and that clings to your items and units. In an old fortress,
cleaning with this tool can significantly reduce FPS lag! It can also spoil your
!!FUN!!, so think before you use it.
Usage
-----
::
clean all|map|items|units|plants [<options>]
spotclean
By default, cleaning the map leaves mud and snow alone. Note that cleaning units
includes hostiles, and that cleaning items removes poisons from weapons.
``spotclean`` works like ``clean map snow mud``, removing all contaminants from
the tile under the cursor. This is ideal if you just want to clean a specific
tile but don't want the `clean` command to remove all the glorious blood from
your entranceway.
Examples
--------
``clean all``
Clean everything that can be cleaned (except mud and snow).
``clean all mud item snow``
Removes all spatter, including mud, leaves, and snow from map tiles.
Options
-------
When cleaning the map, you can specify extra options for extra cleaning:
``mud``
Also remove mud.
``item``
Also remove item spatter, like fallen leaves and flowers.
``snow``
Also remove snow coverings.

@ -0,0 +1,41 @@
cleanowned
==========
.. dfhack-tool::
:summary: Confiscates and dumps garbage owned by dwarves.
:tags: fort productivity items
This tool gets dwarves to give up ownership of scattered items and items with
heavy wear and then marks those items for dumping. Now you can finally get your
dwarves to give up their rotten food and tattered loincloths and go get new
ones!
Usage
-----
::
cleanowned [<types>] [dryrun]
When run without parameters, ``cleanowned`` will confiscate and dump rotten
items and owned food that is left behind on the floor. Specify the ``dryrun``
parameter to just print out what would be done, but don't actually confiscate
anything.
You can confiscate additional types of items by adding them to the commandline:
``scattered``
Confiscate/dump all items scattered on the floor.
``x``
Confiscate/dump items with wear level 'x' (lightly worn) and more.
``X``
Confiscate/dump items with wear level 'X' (heavily worn) and more.
Or you can confiscate all owned items by specifying ``all``.
Example
-------
``cleanowned scattered X``
Confiscate and dump rotten and dropped food, garbage on the floors, and any
worn items with 'X' damage and above.

@ -0,0 +1,22 @@
command-prompt
==============
.. dfhack-tool::
:summary: An in-game DFHack terminal where you can run other commands.
:tags: dfhack
Usage
-----
::
command-prompt [entry]
If called with parameters, it starts with that text in the command edit area.
This is most useful for developers, who can set a keybinding to open a laungage
interpreter for lua or Ruby by starting with the `:lua <lua>` or `:rb <rb>`
portions of the command already filled in.
Also see `gui/quickcmd` for a different take on running commands from the UI.
.. image:: ../images/command-prompt.png

@ -0,0 +1,20 @@
confirm
=======
.. dfhack-tool::
:summary: Adds confirmation dialogs for destructive actions.
:tags: fort interface
Now you can get the chance to avoid seizing goods from traders or deleting a
hauling route in case you hit the key accidentally.
Usage
-----
``enable confirm``, ``confirm enable all``
Enable all confirmation options. Replace with ``disable`` to disable all.
``confirm enable option1 [option2...]``
Enable (or ``disable``) specific confirmation dialogs.
When run without parameters, ``confirm`` will report which confirmation dialogs
are currently enabled.

@ -0,0 +1,54 @@
createitem
==========
.. dfhack-tool::
:summary: Create arbitrary items.
:tags: adventure fort armok items
You can create new items of any type and made of any material. A unit must be
selected in-game to use this command. By default, items created are spawned at
the feet of the selected unit.
Specify the item and material information as you would indicate them in custom
reaction raws, with the following differences:
* Separate the item and material with a space rather than a colon
* If the item has no subtype, the ``:NONE`` can be omitted
* If the item is ``REMAINS``, ``FISH``, ``FISH_RAW``, ``VERMIN``, ``PET``, or
``EGG``, then specify a ``CREATURE:CASTE`` pair instead of a material token.
* If the item is a ``PLANT_GROWTH``, specify a ``PLANT_ID:GROWTH_ID`` pair
instead of a material token.
Corpses, body parts, and prepared meals cannot be created using this tool.
Usage
-----
``createitem <item> <material> [<count>]``
Create <count> copies (default is 1) of the specified item made out of the
specified material.
``createitem inspect``
Obtain the item and material tokens of an existing item. Its output can be
used directly as arguments to ``createitem`` to create new matching items
(as long as the item type is supported).
``createitem floor|item|building``
Subsequently created items will be placed on the floor beneath the selected
unit's, inside the selected item, or as part of the selected building.
.. note::
``createitem building`` is good for loading traps, but if you use it with
workshops, you will have to deconstruct the workshop to access the item.
Examples
--------
``createitem GLOVES:ITEM_GLOVES_GAUNTLETS INORGANIC:STEEL 2``
Create 2 pairs of steel gauntlets (that is, 2 left gauntlets and 2 right
gauntlets).
``createitem WOOD PLANT_MAT:TOWER_CAP:WOOD 100``
Create 100 tower-cap logs.
``createitem PLANT_GROWTH BILBERRY:FRUIT``
Create a single bilberry.
For more examples, :wiki:`the wiki <Utility:DFHack/createitem>`.

@ -0,0 +1,61 @@
cursecheck
==========
.. dfhack-tool::
:summary: Check for cursed creatures.
:tags: fort armok inspection units
This command checks a single map tile (or the whole map/world) for cursed
creatures (ghosts, vampires, necromancers, werebeasts, zombies, etc.).
With an active in-game cursor, only the selected tile will be checked. Without a
cursor, the whole map will be checked.
By default, you will just see the count of cursed creatures in case you just
want to find out if you have any of them running around in your fort. Dead and
passive creatures (ghosts who were put to rest, killed vampires, etc.) are
ignored. Undead skeletons, corpses, bodyparts and the like are all thrown into
the curse category "zombie". Anonymous zombies and resurrected body parts will
show as "unnamed creature".
Usage
-----
::
cursecheck [<options>]
Examples
--------
- ``cursecheck``
Display a count of cursed creatures on the map (or under the cursor).
- ``cursecheck detail all``
Give detailed info about all cursed creatures including deceased ones.
- ``cursecheck nick``
Give a nickname all living/active cursed creatures.
.. note::
If you do a full search (with the option "all") former ghosts will show up
with the cursetype "unknown" because their ghostly flag is not set.
If you see any living/active creatures with a cursetype of "unknown", then
it is most likely a new type of curse introduced by a mod.
Options
-------
``detail``
Print full name, date of birth, date of curse, and some status info (some
vampires might use fake identities in-game, though).
``nick``
Set the type of curse as nickname (does not always show up in-game; some
vamps don't like nicknames).
``ids``
Print the creature and race IDs.
``all``
Include dead and passive cursed creatures (this can result in quite a long
list after having !!FUN!! with necromancers).
``verbose``
Print all curse tags (if you really want to know it all).

@ -0,0 +1,9 @@
cxxrandom
=========
.. dfhack-tool::
:summary: Provides a Lua API for random distributions.
:tags: dev
:no-command:
See `cxxrandom-api` for details.

@ -0,0 +1,77 @@
debug
=====
.. dfhack-tool::
:summary: Provides commands for controlling debug log verbosity.
:tags: dev
:no-command:
.. dfhack-command:: debugfilter
:summary: Configure verbosity of DFHack debug output.
Debug output is grouped by plugin name, category name, and verbosity level.
The verbosity levels are:
- ``Trace``
Possibly very noisy messages which can be printed many times per second.
- ``Debug``
Messages that happen often but they should happen only a couple of times per
second.
- ``Info``
Important state changes that happen rarely during normal execution.
- ``Warning``
Enabled by default. Shows warnings about unexpected events which code
managed to handle correctly.
- ``Error``
Enabled by default. Shows errors which code can't handle without user
intervention.
The runtime message printing is controlled using filters. Filters set the
visible messages of all matching categories. Matching uses regular expression
syntax, which allows listing multiple alternative matches or partial name
matches. This syntax is a C++ version of the ECMA-262 grammar (Javascript
regular expressions). Details of differences can be found at
https://en.cppreference.com/w/cpp/regex/ecmascript
Persistent filters are stored in ``dfhack-config/runtime-debug.json``. Oldest
filters are applied first. That means a newer filter can override the older
printing level selection.
Usage
-----
``debugfilter category [<plugin regex>] [<category regex>]``
List available debug plugin and category names. If filters aren't givenm
then all plugins/categories are matched. This command is a good way to test
regex parameters before you pass them to ``set``.
``debugfilter filter [<id>]``
List active and passive debug print level changes. The optional ``id``
parameter is the id listed as first column in the filter list. If ``id`` is
given, then the command shows extended information for the given filter
only.
``debugfilter set [<level>] [<plugin regex>] [<category regex>]``
Create a new debug filter to set category verbosity levels. This filter
will not be saved when the DF process exists or the plugin is unloaded.
``debugfilter set persistent [<level>] [<plugin regex>] [<category regex>]``
Store the filter in the configuration file to until ``unset`` is used to
remove it.
``debugfilter unset <id> [<id> ...]``
Delete a space separated list of filters.
``debugfilter disable <id> [<id> ...]``
Disable a space separated list of filters but keep it in the filter list.
``debugfilter enable <id> [<id> ...]``
Enable a space sperate list of filters.
``debugfilter header [enable] | [disable] [<element> ...]``
Control which header metadata is shown along with each log message. Run it
without parameters to see the list of configurable elements. Include an
``enable`` or ``disable`` keyword to change whether specific elements are
shown.
Example
-------
``debugfilter set Warning core script``
Hide script execution log messages (e.g. "Loading script:
dfhack-config/dfhack.init"), which are normally output at Info verbosity
in the "core" plugin with the "script" category.

@ -0,0 +1,15 @@
deramp
======
.. dfhack-tool::
:summary: Removes all ramps designated for removal from the map.
:tags: fort armok map
It also removes any "floating" down ramps that can remain after a cave-in.
Usage
-----
::
deramp

@ -0,0 +1,67 @@
dig-now
=======
.. dfhack-tool::
:summary: Instantly complete dig designations.
:tags: fort armok map
This tool will magically complete non-marker dig designations, modifying tile
shapes and creating boulders, ores, and gems as if a miner were doing the mining
or engraving. By default, the entire map is processed and boulder generation
follows standard game rules, but the behavior is configurable.
Note that no units will get mining or engraving experience for the dug/engraved
tiles.
Trees and roots are not currently handled by this plugin and will be skipped.
Requests for engravings are also skipped since they would depend on the skill
and creative choices of individual engravers. Other types of engraving (i.e.
smoothing and track carving) are handled.
Usage
-----
::
dig-now [<pos> [<pos>]] [<options>]
Where the optional ``<pos>`` pair can be used to specify the coordinate bounds
within which ``dig-now`` will operate. If they are not specified, ``dig-now``
will scan the entire map. If only one ``<pos>`` is specified, only the tile at
that coordinate is processed.
Any ``<pos>`` parameters can either be an ``<x>,<y>,<z>`` triple (e.g.
``35,12,150``) or the string ``here``, which means the position of the active
game cursor should be used. You can use the `position` command to get the
current cursor position if you need it.
Examples
--------
``dig-now``
Dig designated tiles according to standard game rules.
``dig-now --clean``
Dig all designated tiles, but don't generate any boulders, ores, or gems.
``dig-now --dump here``
Dig tiles and teleport all generated boulders, ores, and gems to the tile
under the game cursor.
Options
-------
``-c``, ``--clean``
Don't generate any boulders, ores, or gems. Equivalent to
``--percentages 0,0,0,0``.
``-d``, ``--dump <pos>``
Dump any generated items at the specified coordinates. If the tile at those
coordinates is open space or is a wall, items will be generated on the
closest walkable tile below.
``-e``, ``--everywhere``
Generate a boulder, ore, or gem for every tile that can produce one.
Equivalent to ``--percentages 100,100,100,100``.
``-p``, ``--percentages <layer>,<vein>,<small cluster>,<deep>``
Set item generation percentages for each of the tile categories. The
``vein`` category includes both the large oval clusters and the long stringy
mineral veins. Default is ``25,33,100,100``.
``-z``, ``--cur-zlevel``
Restricts the bounds to the currently visible z-level.

@ -0,0 +1,177 @@
.. _digv:
.. _digtype:
dig
===
.. dfhack-tool::
:summary: Provides commands for designating tiles for digging.
:tags: fort design productivity map
:no-command:
.. dfhack-command:: digv
:summary: Designate all of the selected vein for digging.
.. dfhack-command:: digvx
:summary: Dig a vein across z-levels, digging stairs as needed.
.. dfhack-command:: digl
:summary: Dig all of the selected layer stone.
.. dfhack-command:: diglx
:summary: Dig layer stone across z-levels, digging stairs as needed.
.. dfhack-command:: digcircle
:summary: Designate circles.
.. dfhack-command:: digtype
:summary: Designate all vein tiles of the selected type.
.. dfhack-command:: digexp
:summary: Designate dig patterns for exploratory mining.
This plugin provides commands to make complicated dig patterns easy.
Usage
-----
``digv [x] [-p<number>]``
Designate all of the selected vein for digging.
``digvx [-p<number>]``
Dig a vein across z-levels, digging stairs as needed. This is an alias for
``digv x``.
``digl [x] [undo] [-p<number>]``
Dig all of the selected layer stone. If ``undo`` is specified, removes the
designation instead (for if you accidentally set 50 levels at once).
``diglx [-p<number>]``
Dig layer stone across z-levels, digging stairs as needed. This is an alias
for ``digl x``.
``digcircle [<diameter>] [<solidity>] [<action>] [<designation>] [-p<number>]``
Designate circles. The diameter is the number of tiles across the center of
the circle that you want to dig. See the `digcircle`_ section below for
options.
``digtype [<designation>] [-p<number>]``
Designate all vein tiles of the selected type. See the `digtype`_ section
below for options.
``digexp [<pattern>] [<filter>] [-p<number>]``
Designate dig patterns for exploratory mining. See the `digexp`_ section
below for options.
All commands support specifying the priority of the dig designations with
``-p<number>``, where the number is from 1 to 7. If a priority is not specified,
the priority selected in-game is used as the default.
Examples
--------
``digcircle filled 3 -p2``
Dig a filled circle with a diameter of 3 tiles at dig priority 2.
``digcircle``
Do it again (previous parameters are reused).
``expdig diag5 hidden``
Designate the diagonal 5 pattern over all hidden tiles on the current
z-level.
``expdig ladder designated``
Take existing designations on the current z-level and replace them with the
ladder pattern.
``expdig``
Do it again (previous parameters are reused).
digcircle
---------
The ``digcircle`` command can accept up to one option of each type below.
Solidity options:
``hollow``
Designates hollow circles (default).
``filled``
Designates filled circles.
Action options:
``set``
Set designation (default).
``unset``
Unset current designation.
``invert``
Invert designations already present.
Designation options:
``dig``
Normal digging designation (default).
``ramp``
Dig ramps.
``ustair``
Dig up staircases.
``dstair``
Dig down staircases.
``xstair``
Dig up/down staircases.
``chan``
Dig channels.
After you have set the options, the command called with no options repeats with
the last selected parameters.
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.
Designation options:
``dig``
Normal digging designation.
``channel``
Dig channels.
``ramp``
Dig ramps.
``updown``
Dig up/down staircases.
``up``
Dig up staircases.
``down``
Dig down staircases.
``clear``
Clear any designations.
digexp
------
This command is for :wiki:`exploratory mining <Exploratory_mining>`.
There are two variables that can be set: pattern and filter.
Patterns:
``diag5``
Diagonals separated by 5 tiles.
``diag5r``
The diag5 pattern rotated 90 degrees.
``ladder``
A 'ladder' pattern.
``ladderr``
The ladder pattern rotated 90 degrees.
``cross``
A cross, exactly in the middle of the map.
``clear``
Just remove all dig designations.
Filters:
``hidden``
Designate only hidden tiles of z-level (default)
``all``
Designate the whole z-level.
``designated``
Take current designation and apply the selected pattern to it.
After you have a pattern set, you can use ``expdig`` to apply it again.

@ -0,0 +1,42 @@
digFlood
========
.. dfhack-tool::
:summary: Digs out veins as they are discovered.
:tags: fort auto map
Once you register specific vein types, this tool will automatically designate
tiles of those types of veins for digging as your miners complete adjacent
mining jobs. Note that it will *only* dig out tiles that are adjacent to a
just-finished dig job, so if you want to autodig a vein that has already been
discovered, you may need to manually designate one tile of the tile for digging
to get started.
Usage
-----
``enable digflood``
Enable the plugin.
``digflood 1 <vein type> [<vein type> ...]``
Start monitoring for the specified vein types.
``digFlood 0 <vein type> [<vein type> ...] 1``
Stop monitoring for the specified vein types. Note the required ``1`` at the
end.
``digFlood CLEAR``
Remove all inorganics from monitoring.
``digFlood digAll1``
Ignore the monitor list and dig any vein.
``digFlood digAll0``
Disable digAll mode.
You can get the list of valid vein types with this command::
lua "for i,mat in ipairs(df.global.world.raws.inorganics) do if mat.material.flags.IS_STONE and not mat.material.flags.NO_STONE_STOCKPILE then print(i, mat.id) end end"
Examples
--------
``digFlood 1 MICROCLINE COAL_BITUMINOUS``
Automatically dig microcline and bituminous coal veins.
``digFlood 0 MICROCLINE 1``
Stop automatically digging microcline.

@ -0,0 +1,60 @@
diggingInvaders
===============
.. dfhack-tool::
:summary: Invaders dig and destroy to get to your dwarves.
:tags: fort gameplay military units
Usage
-----
``enable diggingInvaders``
Enable the plugin.
``diggingInvaders add <race>``
Register the specified race as a digging invader.
``diggingInvaders remove <race>``
Unregisters the specified race as a digging invader.
``diggingInvaders now``
Makes invaders try to dig now (if the plugin is enabled).
``diggingInvaders clear``
Clears the registry of digging invader races.
``diggingInvaders edgesPerTick <n>``
Makes the pathfinding algorithm work on at most n edges per tick. Set to 0
or lower to make it unlimited.
``diggingInvaders setCost <race> <action> <n>``
Set the pathing cost per tile for a particular action. This determines what
invaders consider to be the shortest path to their target.
``diggingInvaders setDelay <race> <action> <n>``
Set the time cost (in ticks) for performing a particular action. This
determines how long it takes for invaders to get to their target.
Note that the race is case-sensitive. You can get a list of races for your world
with this command::
devel/query --table df.global.world.raws.creatures.all --search creature_id --maxdepth 1 --maxlength 5000
but in general, the race is what you'd expect, just capitalized (e.g. ``GOBLIN``
or ``ELF``).
Actions:
``walk``
Default cost: 1, default delay: 0. This is the base cost for the pathing
algorithm.
``destroyBuilding``
Default cost: 2, default delay: 1,000,
``dig``
Default cost: 10,000, default delay: 1,000. This is for digging soil or
natural stone.
``destroyRoughConstruction``
Default cost: 1,000, default delay: 1,000. This is for destroying
constructions made from boulders.
``destroySmoothConstruction``
Default cost: 100, default delay: 100. This is for destroying constructions
made from blocks or bars.
Example
-------
``diggingInvaders add GOBLIN``
Registers members of the GOBLIN race as a digging invader.

@ -0,0 +1,94 @@
dwarfmonitor
============
.. dfhack-tool::
:summary: Measure fort happiness and efficiency.
:tags: fort inspection jobs units
It can also show heads-up display widgets with live fort statistics.
Usage
-----
``enable dwarfmonitor``
Enable the plugin.
``dwarfmonitor enable <mode>``
Start tracking a specific facet of fortress life. The ``mode`` can be
"work", "misery", "date", "weather", or "all". This will show the
corresponding on-screen widgets, if applicable.
``dwarfmonitor disable <mode>``
Stop monitoring ``mode`` and disable corresponding widgets.
``dwarfmonitor stats``
Show statistics summary.
``dwarfmonitor prefs``
Show summary of dwarf preferences.
``dwarfmonitor reload``
Reload the widget configuration file (``dfhack-config/dwarfmonitor.json``).
Widget configuration
--------------------
The following types of widgets (defined in
:file:`hack/lua/plugins/dwarfmonitor.lua`) can be displayed on the main fortress
mode screen:
``misery``
Show overall happiness levels of all dwarves.
``date``
Show the in-game date.
``weather``
Show current weather (e.g. rain/snow).
``cursor``
Show the current mouse cursor position.
The file :file:`dfhack-config/dwarfmonitor.json` can be edited to control the
positions and settings of all widgets. This file should contain a JSON object
with the key ``widgets`` containing an array of objects:
.. code-block:: lua
{
"widgets": [
{
"type": "widget type (weather, misery, etc.)",
"x": X coordinate,
"y": Y coordinate
<...additional options...>
}
]
}
X and Y coordinates begin at zero (in the upper left corner of the screen).
Negative coordinates will be treated as distances from the lower right corner,
beginning at 1 - e.g. an x coordinate of 0 is the leftmost column, while an x
coordinate of -1 is the rightmost column.
By default, the x and y coordinates given correspond to the leftmost tile of
the widget. Including an ``anchor`` option set to ``right`` will cause the
rightmost tile of the widget to be located at this position instead.
Some widgets support additional options:
* ``date`` widget:
* ``format``: specifies the format of the date. The following characters
are replaced (all others, such as punctuation, are not modified)
* ``Y`` or ``y``: The current year
* ``M``: The current month, zero-padded if necessary
* ``m``: The current month, *not* zero-padded
* ``D``: The current day, zero-padded if necessary
* ``d``: The current day, *not* zero-padded
The default date format is ``Y-M-D``, per the ISO8601_ standard.
.. _ISO8601: https://en.wikipedia.org/wiki/ISO_8601
* ``cursor`` widget:
* ``format``: Specifies the format. ``X``, ``x``, ``Y``, and ``y`` are
replaced with the corresponding cursor cordinates, while all other
characters are unmodified.
* ``show_invalid``: If set to ``true``, the mouse coordinates will both be
displayed as ``-1`` when the cursor is outside of the DF window; otherwise,
nothing will be displayed.

@ -0,0 +1,23 @@
dwarfvet
========
.. dfhack-tool::
:summary: Allows animals to be treated at animal hospitals.
:tags: fort gameplay animals
Annoyed your dragons become useless after a minor injury? Well, with dwarfvet,
injured animals will be treated at an animal hospital, which is simply a hospital
that is also an animal training zone. Dwarfs with the Animal Caretaker labor
enabled will come to the hospital to treat animals. Normal medical skills are
used (and trained), but no experience is given to the Animal Caretaker skill
itself.
Usage
-----
``enable dwarfvet``
Enables the plugin.
``dwarfvet report``
Reports all zones that the game considers animal hospitals.
``dwarfvet report-usage``
Reports on animals currently being treated.

@ -0,0 +1,26 @@
embark-assistant
================
.. dfhack-tool::
:summary: Embark site selection support.
:tags: embark fort interface
Run this command while the pre-embark screen is displayed to show extended (and
reasonably correct) resource information for the embark rectangle as well as
normally undisplayed sites in the current embark region. You will also have
access to a site selection tool with far more options than DF's vanilla search
tool.
If you enable the plugin, you'll also be able to invoke ``embark-assistant``
with the :kbd:`A` key on the pre-embark screen.
Usage
-----
::
enable embark-assistant
embark-assistant
Note the site selection tool requires a display height of at least 46 lines to
display properly.

@ -0,0 +1,34 @@
embark-tools
============
.. dfhack-tool::
:summary: Extend the embark screen functionality.
:tags: embark fort interface
Usage
-----
::
enable embark-tools
embark-tools enable|disable all
embark-tools enable|disable <tool> [<tool> ...]
Avaliable tools are:
``anywhere``
Allows embarking anywhere (including sites, mountain-only biomes, and
oceans). Use with caution.
``mouse``
Implements mouse controls (currently in the local embark region only).
``sand``
Displays an indicator when sand is present in the currently-selected area,
similar to the default clay/stone indicators.
``sticky``
Maintains the selected local area while navigating the world map.
Example
-------
``embark-tools enable all``
Enable all embark screen extensions.

@ -0,0 +1,9 @@
eventful
========
.. dfhack-tool::
:summary: Provides a Lua API for reacting to in-game events.
:tags: dev gameplay
:no-command:
See `eventful-api` for details.

@ -0,0 +1,38 @@
fastdwarf
=========
.. dfhack-tool::
:summary: Dwarves teleport and/or finish jobs instantly.
:tags: fort armok units
Usage
-----
::
enable fastdwarf
fastdwarf <speed mode> [<tele mode>]
Examples
--------
``fastdwarf 1``
Make all your dwarves move and work at maximum speed.
``fastdwarf 1 1``
In addition to working at maximum speed, dwarves also teleport to their
destinations.
Options
-------
Speed modes:
:0: Dwarves move and work at normal rates.
:1: Dwarves move and work at maximum speed.
:2: ALL units move (and work) at maximum speed, including creatures and
hostiles.
Tele modes:
:0: No teleportation.
:1: Dwarves teleport to their destinations.

@ -0,0 +1,53 @@
.. _restrictice:
.. _restrictliquids:
filltraffic
===========
.. dfhack-tool::
:summary: Set traffic designations using flood-fill starting at the cursor.
:tags: fort design productivity map
.. dfhack-command:: alltraffic
:summary: Set traffic designations for every single tile of the map.
.. dfhack-command:: restrictice
:summary: Restrict traffic on all tiles on top of visible ice.
.. dfhack-command:: restrictliquids
:summary: Restrict traffic on all visible tiles with liquid.
Usage
-----
::
filltraffic <designation> [<options>]
alltraffic <designation>
restrictice
restrictliquids
For ``filltraffic``, flood filling stops at walls and doors.
Examples
--------
``filltraffic H``
When used in a room with doors, it will set traffic to HIGH in just that
room.
Options
-------
Traffic designations:
:H: High Traffic.
:N: Normal Traffic.
:L: Low Traffic.
:R: Restricted Traffic.
Filltraffic extra options:
:X: Fill across z-levels.
:B: Include buildings and stockpiles.
:P: Include empty space.

@ -0,0 +1,41 @@
fix-unit-occupancy
==================
.. dfhack-tool::
:summary: Fix phantom unit occupancy issues.
:tags: fort bugfix map
If you see "unit blocking tile" messages that you can't account for
(:bug:`3499`), this tool can help.
Usage
-----
::
enable fix-unit-occupancy
fix-unit-occupancy [here] [-n]
fix-unit-occupancy interval <num_ticks>
When run without arguments (or with just the ``here`` or ``-n`` parameters),
the fix just runs once. You can also have it run periodically by enbling the
plugin.
Examples
--------
``fix-unit-occupancy``
Run once and fix all occupancy issues on the map.
``fix-unit-occupancy -n``
Report on, but do not fix, all occupancy issues on the map.
Options
-------
``here``
Only operate on the tile at the cursor.
``-n``
Report issues, but do not any write changes to the map.
``interval <num_ticks>``
Set how often the plugin will check for and fix issues when it is enabled.
The default is 1200 ticks, or 1 game day.

@ -0,0 +1,16 @@
fixveins
========
.. dfhack-tool::
:summary: Restore missing mineral inclusions.
:tags: fort bugfix map
This tool can also remove invalid references to mineral inclusions if you broke
your embark with tools like `tiletypes`.
Usage
-----
::
fixveins

@ -0,0 +1,16 @@
flows
=====
.. dfhack-tool::
:summary: Counts map blocks with flowing liquids.
:tags: fort inspection map
If you suspect that your magma sea leaks into HFS, you can use this tool to be
sure without revealing the map.
Usage
-----
::
flows

@ -0,0 +1,17 @@
follow
======
.. dfhack-tool::
:summary: Make the screen follow the selected unit.
:tags: fort interface units
Once you exit from the current menu or cursor mode, the screen will stay
centered on the unit. Handy for watching dwarves running around. Deactivated by
moving the cursor manually.
Usage
-----
::
follow

@ -0,0 +1,104 @@
forceequip
==========
.. dfhack-tool::
:summary: Move items into a unit's inventory.
:tags: adventure fort animals items military units
This tool is typically used to equip specific clothing/armor items onto a dwarf,
but can also be used to put armor onto a war animal or to add unusual items
(such as crowns) to any unit. Make sure the unit you want to equip is standing
on the target items, which must be on the ground and be unforbidden. If multiple
units are standing on the same tile, the first one will be equipped.
The most reliable way to set up the environment for this command is to pile
target items on a tile of floor with a garbage dump activity zone or the
`autodump` command, then walk/pasture a unit (or use `gui/teleport`) on top of
the items. Be sure to unforbid the items that you want to work with!
.. note::
Weapons are not currently supported.
Usage
-----
::
forceequip [<options>]
As mentioned above, this plugin can be used to equip items onto units (such as
animals) who cannot normally equip gear. There's an important caveat here: such
creatures will automatically drop inappropriate gear almost immediately (within
10 game ticks). If you want them to retain their equipment, you must forbid it
AFTER using forceequip to get it into their inventory. This technique can also
be used to clothe dwarven infants, but only if you're able to separate them from
their mothers.
By default, the ``forceequip`` command will attempt to abide by game rules as
closely as possible. For instance, it will skip any item which is flagged for
use in a job, and will not equip more than one piece of clothing/armor onto any
given body part. These restrictions can be overridden via options, but doing so
puts you at greater risk of unexpected consequences. For instance, a dwarf who
is wearing three breastplates will not be able to move very quickly.
Items equipped by this plugin DO NOT become owned by the recipient. Adult
dwarves are free to adjust their own wardrobe, and may promptly decide to doff
your gear in favour of their owned items. Animals, as described above, will tend
to discard ALL clothing immediately unless it is manually forbidden. Armor items
seem to be an exception: an animal will tend to retain an equipped suit of mail
even if you neglect to forbid it.
Please note that armored animals are quite vulnerable to ranged attacks. Unlike
dwarves, animals cannot block, dodge, or deflect arrows, and they are slowed by
the weight of their armor.
Examples
--------
``forceequip``
Attempts to equip all of the clothing and armor under the cursor onto the
unit under the cursor, following game rules regarding which item can be
equipped on which body part and only equipping 1 item onto each body part.
Items owned by other dwarves are ignored.
``forceequip v bp QQQ``
List the bodyparts of the selected unit.
``forceequip bp LH``
Equips an appopriate item onto the unit's left hand.
``forceequip m bp LH``
Equips ALL appropriate items onto the unit's left hand. The unit may end up
wearing a dozen left-handed mittens. Use with caution, and remember that
dwarves tend to drop extra items ASAP.
``forceequip i bp NECK``
Equips an item around the unit's neck, ignoring appropriateness
restrictions. If there's a millstone or an albatross carcass sitting on the
same square as the targeted unit, then there's a good chance that it will
end up around his neck. For precise control, remember that you can
selectively forbid some of the items that are piled on the ground.
``forceequip s``
Equips the item currently selected in the k menu, if possible.
``forceequip s m i bp HD``
Equips the selected item onto the unit's head. Ignores all restrictions and
conflicts. If you know exactly what you want to equip, and exactly where you
want it to go, then this is the most straightforward and reliable option.
Options
-------
``i``, ``ignore``
Bypasses the usual item eligibility checks (such as "Never equip gear
belonging to another dwarf" and "Nobody is allowed to equip a Hive".
``m``, ``multi``
Bypasses the 1-item-per-bodypart limit. Useful for equipping both a mitten
and a gauntlet on the same hand (or twelve breastplates on the upper body).
``m2``, ``m3``, ``m4``
Modifies the 1-item-per-bodypart limit, allowing each part to receive 2, 3,
or 4 pieces of gear.
``s``, ``selected``
Equip only the item currently selected in the k menu and ignore all other
items in the tile.
``bp``, ``bodypart <body part code>``
Specify which body part should be equipped.
``v``, ``verbose``
Provide detailed narration and error messages, including listing available
body parts when an invalid ``bodypart`` code is specified.

@ -0,0 +1,32 @@
generated-creature-renamer
==========================
.. dfhack-tool::
:summary: Automatically renames generated creatures.
:tags: adventure fort legends units
:no-command:
.. dfhack-command:: list-generated
:summary: List the token names of all generated creatures.
.. dfhack-command:: save-generated-raws
:summary: Export a creature graphics file for modding.
Now, forgotten beasts, titans, necromancer experiments, etc. will have raw token
names that match the description given in-game instead of unreadable generated
strings.
Usage
-----
``enable generated-creature-renamer``
Rename generated creatures when a world is loaded.
``list-generated [detailed]``
List the token names of all generated creatures in the loaded save. If
``detailed`` is specified, then also show the accompanying description.
``save-generated-raws``
Save a sample creature graphics file in the Dwarf Fortress root directory to
use as a start for making a graphics set for generated creatures using the
new names that they get with this plugin.
The new names are saved with the world.

Some files were not shown because too many files have changed in this diff Show More