move builtin docs to individual files
myk002
parent
e650bd0942
commit
301c8e93a1
@ -1,280 +0,0 @@
|
||||
.. _built-in-commands:
|
||||
|
||||
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 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. 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 online. ``? <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 explicitly enable
|
||||
them. 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:
|
||||
.. _dir:
|
||||
|
||||
ls
|
||||
--
|
||||
``ls`` (or ``dir``) does not list files like the Unix command, but rather
|
||||
available commands. 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. Usage:
|
||||
|
||||
:``ls``: Lists all available commands and the tags associated with them
|
||||
(if any).
|
||||
:``ls TAG``: Shows only commands that have the given tag. Use the `tags` command
|
||||
to see the list of available tags.
|
||||
:``ls STRING``: Shows commands that include the given string. E.g. ``ls auto``
|
||||
will show all the commands with "auto" in their names. If the string is also
|
||||
the name of a tag, then it will be interpreted as a tag name.
|
||||
|
||||
You can also pass some optional parameters to change how ``ls`` behaves:
|
||||
|
||||
:``--notags``: Don't print out the tags associated with each command.
|
||||
:``--dev``: Include commands intended for developers and modders.
|
||||
|
||||
|
||||
.. _plug:
|
||||
|
||||
plug
|
||||
----
|
||||
Lists available plugins and whether they are enabled.
|
||||
|
||||
``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 can later be reloaded 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`.
|
||||
|
||||
|
||||
.. _tags:
|
||||
|
||||
tags
|
||||
----
|
||||
|
||||
List the strings that the DFHack tools can be tagged with. You can find groups
|
||||
of related tools by passing the tag name to `ls`.
|
||||
|
||||
.. _type:
|
||||
|
||||
type
|
||||
----
|
||||
``type command`` shows where ``command`` is implemented.
|
||||
|
||||
.. _devel/dump-rpc:
|
||||
|
||||
devel/dump-rpc
|
||||
--------------
|
||||
|
||||
Writes RPC endpoint information to the specified file.
|
||||
|
||||
Usage::
|
||||
|
||||
devel/dump-rpc FILENAME
|
||||
|
||||
Other Commands
|
||||
--------------
|
||||
The following commands are *not* built-in, but offer similarly useful functions.
|
||||
|
||||
* `command-prompt`
|
||||
* `hotkeys`
|
||||
* `lua`
|
||||
* `multicmd`
|
||||
* `nopause`
|
||||
* `quicksave`
|
||||
* `rb`
|
||||
* `repeat`
|
||||
@ -0,0 +1,29 @@
|
||||
alias
|
||||
-----
|
||||
|
||||
Configure helper aliases for 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.
|
||||
|
||||
Example::
|
||||
|
||||
[DFHack]# alias add pargs devel/print-args example
|
||||
[DFHack]# pargs text
|
||||
example
|
||||
text
|
||||
@ -0,0 +1,4 @@
|
||||
clear
|
||||
-----
|
||||
|
||||
Clear the terminal screen. This command is an alias for `cls`.
|
||||
@ -0,0 +1,5 @@
|
||||
cls
|
||||
---
|
||||
|
||||
Clear the terminal screen. Can also be invoked as ``clear``. Note that this
|
||||
command does not delete command history. It just clears the text on the screen.
|
||||
@ -0,0 +1,8 @@
|
||||
devel/dump-rpc
|
||||
--------------
|
||||
|
||||
Writes RPC endpoint information to the specified file.
|
||||
|
||||
Usage::
|
||||
|
||||
devel/dump-rpc <filename>
|
||||
@ -0,0 +1,4 @@
|
||||
die
|
||||
---
|
||||
|
||||
Instantly exits DF without saving.
|
||||
@ -0,0 +1,4 @@
|
||||
dir
|
||||
---
|
||||
|
||||
List available DFHack commands. This is an alias of the `ls` command.
|
||||
@ -0,0 +1,20 @@
|
||||
disable
|
||||
-------
|
||||
|
||||
Deactivate a DFHack tool that has some persistent effect. 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. For example, to disable the `manipulator` plugin::
|
||||
|
||||
disable manipulator
|
||||
|
||||
It is also possible to enable or disable multiple plugins at once::
|
||||
|
||||
disable manipulator search
|
||||
@ -0,0 +1,20 @@
|
||||
enable
|
||||
------
|
||||
|
||||
Activate a DFHack tool that has some persistent effect. 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. For example, to enable the `manipulator` plugin::
|
||||
|
||||
enable manipulator
|
||||
|
||||
It is also possible to enable or disable multiple plugins at once::
|
||||
|
||||
enable manipulator search
|
||||
@ -0,0 +1,5 @@
|
||||
fpause
|
||||
------
|
||||
|
||||
Forces DF to pause. This is useful when your FPS drops below 1 and you lose
|
||||
control of the game.
|
||||
@ -0,0 +1,19 @@
|
||||
help
|
||||
----
|
||||
|
||||
Display help about a command or plugin.
|
||||
|
||||
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,8 @@
|
||||
hide
|
||||
----
|
||||
|
||||
Hides the DFHack terminal window. 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.
|
||||
@ -0,0 +1,56 @@
|
||||
keybinding
|
||||
----------
|
||||
|
||||
Create hotkeys that will run DFHack commands. 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
|
||||
``\```.
|
||||
|
||||
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,6 @@
|
||||
kill-lua
|
||||
--------
|
||||
|
||||
Gracefully stops any currently-running Lua scripts. Use this command to stop
|
||||
a misbehaving script that appears to be stuck. Use ``kill-lua force`` if just
|
||||
``kill-lua`` doesn't work.
|
||||
@ -0,0 +1,13 @@
|
||||
load
|
||||
----
|
||||
|
||||
Load and register a plugin library. 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,34 @@
|
||||
ls
|
||||
--
|
||||
|
||||
List available DFHack commands. 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. The `dir` command is an alias of this
|
||||
command.
|
||||
|
||||
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.
|
||||
|
||||
You can also pass some optional parameters to change how ``ls`` behaves:
|
||||
|
||||
- ``--notags``
|
||||
Don't print out the tags associated with each command.
|
||||
- ``--dev``
|
||||
Include commands intended for developers and modders.
|
||||
|
||||
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"
|
||||
@ -0,0 +1,12 @@
|
||||
plug
|
||||
----
|
||||
|
||||
Lists available plugins and whether they are enabled.
|
||||
|
||||
Usage:
|
||||
|
||||
- ``plug``
|
||||
Lists available plugins and whether they are enabled.
|
||||
- ``plug <plugin> [<plugin> ...]``
|
||||
Shows the commands implemented by the named plugins and whether the plugins
|
||||
are enabled.
|
||||
@ -0,0 +1,14 @@
|
||||
reload
|
||||
------
|
||||
|
||||
Reload a loaded plugin. Developer 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,9 @@
|
||||
sc-script
|
||||
---------
|
||||
|
||||
Runs commands when game state changes occur. This is similar to the static
|
||||
`init-files` but can be set dynamically.
|
||||
|
||||
Usage::
|
||||
|
||||
sc-script
|
||||
@ -0,0 +1,19 @@
|
||||
script
|
||||
------
|
||||
|
||||
Executes a batch file of DFHack commands. 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>
|
||||
|
||||
Examples:
|
||||
|
||||
- ``script startup.txt``
|
||||
Executes the commands in ``startup.txt``, which exists in your DF game
|
||||
directory.
|
||||
@ -0,0 +1,9 @@
|
||||
show
|
||||
----
|
||||
|
||||
Unhides the DFHack terminal window. 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.
|
||||
@ -0,0 +1,9 @@
|
||||
tags
|
||||
----
|
||||
|
||||
List the strings that DFHack tools can be tagged with. You can find groups of
|
||||
related tools by passing the tag name to the `ls` command.
|
||||
|
||||
Usage::
|
||||
|
||||
tags
|
||||
@ -0,0 +1,10 @@
|
||||
type
|
||||
----
|
||||
|
||||
Describes how a command is implemented. 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,11 @@
|
||||
unload
|
||||
------
|
||||
|
||||
Unload a plugin from memory. 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.
|
||||
@ -1,24 +1,15 @@
|
||||
.. _tools-index:
|
||||
|
||||
============
|
||||
DFHack Tools
|
||||
============
|
||||
==================
|
||||
DFHack Tools Index
|
||||
==================
|
||||
|
||||
These pages contain information about the plugins, scripts, and built-in
|
||||
commands distributed with DFHack.
|
||||
|
||||
.. 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.
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:glob:
|
||||
|
||||
/docs/Tags
|
||||
/docs/Builtin
|
||||
/docs/tools/*
|
||||
/docs/tools/*/*
|
||||
|
||||
Loading…
Reference in New Issue