2015-11-05 06:58:18 -07:00
|
|
|
.. _dfhack-core:
|
|
|
|
|
2015-09-24 22:15:05 -06:00
|
|
|
###########
|
|
|
|
DFHack Core
|
|
|
|
###########
|
2012-09-20 05:38:58 -06:00
|
|
|
|
2020-07-08 00:13:37 -06:00
|
|
|
.. contents:: Contents
|
|
|
|
:local:
|
|
|
|
:depth: 2
|
2016-08-12 03:04:23 -06:00
|
|
|
|
|
|
|
|
2022-09-14 14:19:26 -06:00
|
|
|
Command implementation
|
2016-08-12 03:04:23 -06:00
|
|
|
======================
|
2022-07-08 15:43:41 -06:00
|
|
|
DFHack commands can be implemented in any of three ways:
|
2015-11-05 06:58:18 -07:00
|
|
|
|
2015-11-05 17:44:43 -07:00
|
|
|
:builtin: commands are implemented by the core of DFHack. They manage
|
2020-07-22 00:23:29 -06:00
|
|
|
other DFHack tools, interpret commands, and control basic
|
2022-07-10 00:01:31 -06:00
|
|
|
aspects of DF (force pause or quit).
|
2015-11-05 06:58:18 -07:00
|
|
|
|
|
|
|
:plugins: are stored in ``hack/plugins/`` and must be compiled with the
|
|
|
|
same version of DFHack. They are less flexible than scripts,
|
2020-07-22 00:23:29 -06:00
|
|
|
but used for complex or ongoing tasks because they run faster.
|
2015-11-05 06:58:18 -07:00
|
|
|
|
2022-12-06 07:40:39 -07:00
|
|
|
:scripts: are Lua scripts stored in ``hack/scripts/`` or other
|
2022-12-31 00:30:11 -07:00
|
|
|
directories in the `script-paths`. Because they don't need to
|
|
|
|
be compiled, scripts are more flexible about versions, and
|
|
|
|
they are easier to distribute. Most third-party DFHack addons
|
|
|
|
are scripts.
|
2022-07-10 00:01:31 -06:00
|
|
|
|
2022-12-05 14:12:07 -07:00
|
|
|
All tools distributed with DFHack are documented `here <tools>`.
|
2015-11-05 06:58:18 -07:00
|
|
|
|
2022-09-14 14:19:26 -06:00
|
|
|
Using DFHack commands
|
2016-08-12 03:04:23 -06:00
|
|
|
=====================
|
|
|
|
DFHack commands can be executed in a number of ways:
|
|
|
|
|
|
|
|
#. Typing the command into the DFHack console (see below)
|
|
|
|
#. From the OS terminal (see below)
|
|
|
|
#. Pressing a key combination set up with `keybinding`
|
|
|
|
#. From one of several `init-files`, automatically
|
|
|
|
#. Using `script` to run a batch of commands from a file
|
2022-12-31 00:30:11 -07:00
|
|
|
#. From an in-game command launcher interface like `gui/launcher`, the
|
|
|
|
`hotkeys` overlay widget, or `gui/quickcmd`.
|
2016-08-12 03:04:23 -06:00
|
|
|
|
2022-09-14 14:19:26 -06:00
|
|
|
The DFHack console
|
2016-08-12 21:42:12 -06:00
|
|
|
------------------
|
2016-08-12 03:04:23 -06:00
|
|
|
The command line has some nice line editing capabilities, including history
|
|
|
|
that's preserved between different runs of DF - use :kbd:`↑` and :kbd:`↓`
|
|
|
|
to go through the history.
|
|
|
|
|
|
|
|
To include whitespace in the argument/s to some command, quote it in
|
|
|
|
double quotes. To include a double quote character, use ``\"``.
|
|
|
|
|
|
|
|
If the first non-whitespace character is ``:``, the command is parsed in
|
|
|
|
an alternative mode. The non-whitespace characters following the ``:`` are
|
|
|
|
the command name, and the remaining part of the line is used verbatim as
|
|
|
|
the first argument. This is very useful for the `lua` and `rb` commands.
|
|
|
|
As an example, the following two command lines are exactly equivalent::
|
|
|
|
|
|
|
|
:foo a b "c d" e f
|
|
|
|
foo "a b \"c d\" e f"
|
|
|
|
|
2016-08-12 21:42:12 -06:00
|
|
|
Using an OS terminal
|
|
|
|
--------------------
|
|
|
|
DFHack commands can be run from an OS terminal at startup, using '+ args',
|
|
|
|
or at any other time using the ``dfhack-run`` executable.
|
2016-08-12 03:04:23 -06:00
|
|
|
|
2016-08-12 21:42:12 -06:00
|
|
|
If DF/DFHack is started with arguments beginning with ``+``, the remaining
|
|
|
|
text is treated as a command in the DFHack console. It is possible to use
|
2020-10-08 23:15:42 -06:00
|
|
|
multiple such commands, which are split on ``+``. For example:
|
|
|
|
|
|
|
|
.. code-block:: shell
|
2016-08-12 03:04:23 -06:00
|
|
|
|
2016-08-12 21:42:12 -06:00
|
|
|
./dfhack +load-save region1
|
|
|
|
"Dwarf Fortress.exe" +devel/print-args Hello! +enable workflow
|
|
|
|
|
|
|
|
The first example (\*nix), `load-save`, skips the main menu and loads
|
|
|
|
``region1`` immediately. The second (Windows) example prints
|
|
|
|
:guilabel:`Hello!` in the DFHack console, and `enables <enable>` `workflow`.
|
|
|
|
Note that the ``:foo`` syntax for whitespace in arguments is not compatible \
|
|
|
|
with '+ args'.
|
|
|
|
|
|
|
|
|
2018-07-02 22:02:53 -06:00
|
|
|
.. _dfhack-run:
|
|
|
|
|
|
|
|
dfhack-run
|
|
|
|
..........
|
|
|
|
|
2016-08-12 21:42:12 -06:00
|
|
|
If DF and DFHack are already running, calling ``dfhack-run my command``
|
|
|
|
in an external terminal is equivalent to calling ``my command`` in the
|
2020-07-21 21:14:59 -06:00
|
|
|
DFHack console. Direct use of the DFHack console is generally easier,
|
2016-08-12 21:42:12 -06:00
|
|
|
but ``dfhack-run`` can be useful in a variety of circumstances:
|
|
|
|
|
|
|
|
- if the console is unavailable
|
|
|
|
|
|
|
|
- with the init setting ``PRINT_MODE:TEXT``
|
2020-07-22 00:23:29 -06:00
|
|
|
- while running an interactive command (e.g. `liquids` or `tiletypes`)
|
2016-08-12 21:42:12 -06:00
|
|
|
|
|
|
|
- from external programs or scripts
|
|
|
|
- if DF or DFHack are not responding
|
|
|
|
|
2020-10-08 23:15:42 -06:00
|
|
|
Examples:
|
|
|
|
|
|
|
|
.. code-block:: shell
|
2016-08-12 21:42:12 -06:00
|
|
|
|
|
|
|
./dfhack-run cursecheck
|
2018-07-02 22:02:53 -06:00
|
|
|
dfhack-run kill-lua
|
2016-08-12 21:42:12 -06:00
|
|
|
|
|
|
|
The first (\*nix) example `checks for vampires <cursecheck>`; the
|
2018-07-02 22:02:53 -06:00
|
|
|
second (Windows) example uses `kill-lua` to stop a Lua script.
|
2012-02-04 20:28:20 -07:00
|
|
|
|
2020-07-21 21:14:59 -06:00
|
|
|
.. note::
|
|
|
|
|
|
|
|
``dfhack-run`` attempts to connect to a server on TCP port 5000. If DFHack
|
|
|
|
was unable to start this server, ``dfhack-run`` will not be able to connect.
|
|
|
|
This could happen if you have other software listening on port 5000, or if
|
|
|
|
you have multiple copies of DF running simultaneously. To assign a different
|
|
|
|
port, see `remote-server-config`.
|
|
|
|
|
2022-07-10 09:54:55 -06:00
|
|
|
.. _dfhack-config:
|
|
|
|
|
2022-09-14 14:19:26 -06:00
|
|
|
Configuration files
|
2022-07-10 09:54:55 -06:00
|
|
|
===================
|
|
|
|
|
|
|
|
Most DFHack settings can be changed by modifying files in the ``dfhack-config``
|
|
|
|
folder (which is in the DF folder). The default versions of these files, if they
|
|
|
|
exist, are in ``dfhack-config/default`` and are installed when DFHack starts if
|
|
|
|
necessary.
|
|
|
|
|
2015-11-05 06:58:18 -07:00
|
|
|
.. _init-files:
|
2013-09-30 03:19:51 -06:00
|
|
|
|
2022-09-14 14:19:26 -06:00
|
|
|
Init files
|
2022-07-10 09:54:55 -06:00
|
|
|
----------
|
2016-08-12 03:04:23 -06:00
|
|
|
|
|
|
|
.. contents::
|
|
|
|
:local:
|
|
|
|
|
2015-11-05 06:58:18 -07:00
|
|
|
DFHack allows users to automatically run commonly-used DFHack commands
|
2022-07-10 09:54:55 -06:00
|
|
|
when DF is first loaded, when a world is loaded, when a map is loaded, when a
|
|
|
|
map is unloaded, and when a world is unloaded.
|
2013-09-30 03:19:51 -06:00
|
|
|
|
2015-11-05 06:58:18 -07:00
|
|
|
Init scripts function the same way they would if the user manually typed
|
|
|
|
in their contents, but are much more convenient. In order to facilitate
|
|
|
|
savegave portability, mod merging, and general organization of init files,
|
|
|
|
DFHack supports multiple init files both in the main DF directory and
|
|
|
|
save-specific init files in the save folders.
|
2013-09-30 03:19:51 -06:00
|
|
|
|
2023-01-16 00:13:58 -07:00
|
|
|
DFHack looks for init files in two places each time they could be run:
|
2012-09-27 01:19:28 -06:00
|
|
|
|
2023-01-16 00:13:58 -07:00
|
|
|
#. The :file:`dfhack-config/init` subdirectory in the main DF directory and
|
|
|
|
#. :file:`save/{world}/init`, where ``{world}`` is the current save
|
2012-09-21 02:19:48 -06:00
|
|
|
|
2022-07-10 09:54:55 -06:00
|
|
|
For each of those directories, all matching init files will be executed in
|
|
|
|
alphabetical order.
|
2012-09-21 02:19:48 -06:00
|
|
|
|
2022-07-10 09:54:55 -06:00
|
|
|
Before running matched init scripts in any of those locations, the
|
|
|
|
:file:`dfhack-config/init/default.*` file that matches the event will be run to
|
|
|
|
load DFHack defaults. Only the :file:`dfhack-config/init` directory is checked
|
2023-01-16 00:13:58 -07:00
|
|
|
for this file, not any :file:`save` directories. If you want DFHack to load
|
2022-07-10 09:54:55 -06:00
|
|
|
without running any of its default configuration commands, edit the
|
|
|
|
:file:`dfhack-config/init/default.*` files and comment out the commands you see
|
|
|
|
there.
|
2015-09-22 07:30:22 -06:00
|
|
|
|
2022-07-10 09:54:55 -06:00
|
|
|
When reading commands from the init files or with the `script` command, if the
|
|
|
|
final character on a line is a backslash then the next uncommented line is
|
|
|
|
considered a continuation of that line, with the backslash deleted. Commented
|
|
|
|
lines are skipped, so it is possible to comment out parts of a command with the
|
|
|
|
``#`` character.
|
2012-09-21 02:19:48 -06:00
|
|
|
|
2022-07-10 09:54:55 -06:00
|
|
|
.. _dfhack.init:
|
2015-08-13 20:30:45 -06:00
|
|
|
|
2022-07-10 09:54:55 -06:00
|
|
|
dfhack\*.init
|
|
|
|
.............
|
|
|
|
On startup, DFHack looks for files of the form ``dfhack*.init`` (where ``*`` is
|
|
|
|
a placeholder for any string, including the empty string).
|
2015-11-05 06:58:18 -07:00
|
|
|
|
2022-12-31 00:30:11 -07:00
|
|
|
These files are best used for keybindings and enabling persistent tools
|
2015-11-05 06:58:18 -07:00
|
|
|
which do not require a world to be loaded.
|
|
|
|
|
|
|
|
|
|
|
|
.. _onLoad.init:
|
|
|
|
|
2022-07-10 09:54:55 -06:00
|
|
|
onLoad\*.init
|
|
|
|
.............
|
2015-11-05 06:58:18 -07:00
|
|
|
When a world is loaded, DFHack looks for files of the form ``onLoad*.init``,
|
|
|
|
where ``*`` can be any string, including the empty string.
|
|
|
|
|
|
|
|
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
|
2022-09-21 18:53:51 -06:00
|
|
|
a `bugfix-tag-index` script to run on `repeat`.
|
2015-11-05 06:58:18 -07:00
|
|
|
|
|
|
|
|
2022-07-10 09:54:55 -06:00
|
|
|
.. _onMapLoad.init:
|
2015-11-05 06:58:18 -07:00
|
|
|
|
2022-07-10 09:54:55 -06:00
|
|
|
onMapLoad\*.init
|
|
|
|
................
|
|
|
|
When a map is loaded, either in adventure or fort mode, DFHack looks for files
|
|
|
|
of the form ``onMapLoad*.init``, where ``*`` can be any string, including the
|
|
|
|
empty string.
|
2015-11-05 06:58:18 -07:00
|
|
|
|
2022-07-10 09:54:55 -06:00
|
|
|
These files are best used for commands that are only relevant once there is a
|
|
|
|
game map loaded.
|
2015-11-05 06:58:18 -07:00
|
|
|
|
|
|
|
|
2022-07-10 09:54:55 -06:00
|
|
|
.. _onMapUnload.init:
|
|
|
|
.. _onUnload.init:
|
2015-11-05 17:44:43 -07:00
|
|
|
|
2022-07-10 09:54:55 -06:00
|
|
|
onMapUnload\*.init and onUnload\*.init
|
|
|
|
......................................
|
|
|
|
When a map or world is unloaded, DFHack looks for files of the form
|
|
|
|
``onMapUnload*.init`` or ``onUnload*.init``, respectively.
|
2015-11-05 17:44:43 -07:00
|
|
|
|
2022-07-10 09:54:55 -06:00
|
|
|
Modders often use unload init scripts to disable tools which should not run
|
|
|
|
after a modded save is unloaded.
|
2015-11-05 06:58:18 -07:00
|
|
|
|
|
|
|
|
2022-07-10 09:54:55 -06:00
|
|
|
.. _other_init_files:
|
2020-11-09 22:48:27 -07:00
|
|
|
|
2022-07-10 09:54:55 -06:00
|
|
|
raw/init.d/\*.lua
|
|
|
|
.................
|
|
|
|
|
|
|
|
Any lua script named ``raw/init.d/*.lua``, in the save or main DF directory,
|
|
|
|
will be run when any world or that save is loaded.
|
2020-11-09 22:48:27 -07:00
|
|
|
|
|
|
|
|
|
|
|
.. _script-paths:
|
|
|
|
|
|
|
|
Script paths
|
|
|
|
------------
|
|
|
|
|
|
|
|
Script paths are folders that DFHack searches to find a script when a command is
|
|
|
|
run. By default, the following folders are searched, in order (relative to the
|
|
|
|
root DF folder):
|
|
|
|
|
2022-12-31 00:30:11 -07:00
|
|
|
#. :file:`dfhack-config/scripts`
|
2023-01-16 00:13:58 -07:00
|
|
|
#. :file:`save/{world}/scripts` (only if a save is loaded)
|
2022-12-31 00:30:11 -07:00
|
|
|
#. :file:`hack/scripts`
|
2020-11-09 22:48:27 -07:00
|
|
|
|
|
|
|
For example, if ``teleport`` is run, these folders are searched in order for
|
2023-01-16 00:13:58 -07:00
|
|
|
``teleport.lua``, and the first matching file is run.
|
2020-11-09 22:48:27 -07:00
|
|
|
|
|
|
|
Script paths can be added by modifying :file:`dfhack-config/script-paths.txt`.
|
|
|
|
Each line should start with one of these characters:
|
|
|
|
|
|
|
|
- ``+``: adds a script path that is searched *before* the default paths (above)
|
|
|
|
- ``-``: adds a script path that is searched *after* the default paths
|
|
|
|
- ``#``: a comment (the line is ignored)
|
|
|
|
|
|
|
|
Paths can be absolute or relative - relative paths are interpreted relative to
|
|
|
|
the root DF folder.
|
|
|
|
|
|
|
|
.. admonition:: Tip
|
|
|
|
|
2021-05-11 17:46:01 -06:00
|
|
|
When developing scripts in the :source-scripts:`dfhack/scripts repo <>`,
|
2020-11-09 22:48:27 -07:00
|
|
|
it may be useful to add the path to your local copy of the repo with ``+``.
|
|
|
|
This will allow you to make changes in the repo and have them take effect
|
|
|
|
immediately, without needing to re-install or copy scripts over manually.
|
|
|
|
|
2022-03-31 14:20:54 -06:00
|
|
|
Note that ``script-paths.txt`` is only read at startup, but the paths can also be
|
|
|
|
modified programmatically at any time through the `Lua API <lua-api-internal>`.
|
2020-11-09 22:48:27 -07:00
|
|
|
|
|
|
|
|
2020-07-21 19:39:37 -06:00
|
|
|
.. _env-vars:
|
|
|
|
|
2022-09-14 14:19:26 -06:00
|
|
|
Environment variables
|
2018-02-11 01:07:25 -07:00
|
|
|
=====================
|
|
|
|
|
|
|
|
DFHack's behavior can be adjusted with some environment variables. For example,
|
2020-10-08 23:15:42 -06:00
|
|
|
on UNIX-like systems:
|
|
|
|
|
|
|
|
.. code-block:: shell
|
2018-02-11 01:07:25 -07:00
|
|
|
|
|
|
|
DFHACK_SOME_VAR=1 ./dfhack
|
|
|
|
|
|
|
|
- ``DFHACK_PORT``: the port to use for the RPC server (used by ``dfhack-run``
|
|
|
|
and `remotefortressreader` among others) instead of the default ``5000``. As
|
|
|
|
with the default, if this port cannot be used, the server is not started.
|
2020-07-21 19:39:37 -06:00
|
|
|
See `remote` for more details.
|
2018-02-11 01:07:25 -07:00
|
|
|
|
|
|
|
- ``DFHACK_DISABLE_CONSOLE``: if set, the DFHack console is not set up. This is
|
|
|
|
the default behavior if ``PRINT_MODE:TEXT`` is set in ``data/init/init.txt``.
|
|
|
|
Intended for situations where DFHack cannot run in a terminal window.
|
|
|
|
|
|
|
|
- ``DFHACK_HEADLESS``: if set, and ``PRINT_MODE:TEXT`` is set, DF's display will
|
|
|
|
be hidden, and the console will be started unless ``DFHACK_DISABLE_CONSOLE``
|
|
|
|
is also set. Intended for non-interactive gameplay only.
|
|
|
|
|
|
|
|
- ``DFHACK_NO_GLOBALS``, ``DFHACK_NO_VTABLES``: ignores all global or vtable
|
|
|
|
addresses in ``symbols.xml``, respectively. Intended for development use -
|
|
|
|
e.g. to make sure tools do not crash when these addresses are missing.
|
|
|
|
|
|
|
|
- ``DFHACK_NO_DEV_PLUGINS``: if set, any plugins from the plugins/devel folder
|
|
|
|
that are built and installed will not be loaded on startup.
|
|
|
|
|
|
|
|
- ``DFHACK_LOG_MEM_RANGES`` (macOS only): if set, logs memory ranges to
|
|
|
|
``stderr.log``. Note that `devel/lsmem` can also do this.
|
|
|
|
|
2021-02-27 22:52:54 -07:00
|
|
|
- ``DFHACK_ENABLE_LUACOV``: if set, enables coverage analysis of Lua scripts.
|
2021-03-06 08:02:55 -07:00
|
|
|
Use the `devel/luacov` script to generate coverage reports from the collected
|
2021-02-27 22:52:54 -07:00
|
|
|
metrics.
|
|
|
|
|
2018-02-11 01:07:25 -07:00
|
|
|
Other (non-DFHack-specific) variables that affect DFHack:
|
|
|
|
|
|
|
|
- ``TERM``: if this is set to ``dumb`` or ``cons25`` on \*nix, the console will
|
|
|
|
not support any escape sequences (arrow keys, etc.).
|
|
|
|
|
|
|
|
- ``LANG``, ``LC_CTYPE``: if either of these contain "UTF8" or "UTF-8" (not case
|
|
|
|
sensitive), ``DF2CONSOLE()`` will produce UTF-8-encoded text. Note that this
|
|
|
|
should be the case in most UTF-8-capable \*nix terminal emulators already.
|
|
|
|
|
2022-09-14 14:19:26 -06:00
|
|
|
Miscellaneous notes
|
2015-11-05 06:58:18 -07:00
|
|
|
===================
|
|
|
|
This section is for odd but important notes that don't fit anywhere else.
|
|
|
|
|
2015-11-05 17:44:43 -07:00
|
|
|
* If a DF :kbd:`H` hotkey is named with a DFHack command, pressing
|
2015-11-05 06:58:18 -07:00
|
|
|
the corresponding :kbd:`Fx` button will run that command, instead of
|
|
|
|
zooming to the set location.
|
2016-08-12 03:04:23 -06:00
|
|
|
*This feature will be removed in a future version.* (see :issue:`731`)
|
2015-11-05 06:58:18 -07:00
|
|
|
|
|
|
|
* The binaries for 0.40.15-r1 to 0.34.11-r4 are on DFFD_.
|
|
|
|
Older versions are available here_.
|
2016-08-12 03:04:23 -06:00
|
|
|
*These files will eventually be migrated to GitHub.* (see :issue:`473`)
|
2015-11-05 06:58:18 -07:00
|
|
|
|
2020-10-09 17:04:40 -06:00
|
|
|
.. _DFFD: https://dffd.bay12games.com/search.php?string=DFHack&id=15&limit=1000
|
|
|
|
.. _here: https://dethware.org/dfhack/download
|