diff --git a/docs/Core.rst b/docs/Core.rst index 2ad51db70..fda08b676 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -1,152 +1,197 @@ +.. _dfhack-core: + ########### DFHack Core ########### +DFHack commands can be implemented in three ways, all of which +are used in the same way: + +:builtin: commands are implemented by the core of DFHack, and quite rare. + +:plugins: are stored in ``hack/plugins/`` and must be compiled with the + same version of DFHack. They are less flexible than scripts, + but used for complex or ongoing tasks becasue they run faster. + +:scripts: are Ruby or Lua scripts stored in ``hack/scripts/``. + Because they don't need to be compiled, scripts are + more flexible about versions, and easier to distribute. + Most third-party DFHack addons are scripts. + + .. contents:: -============== -Getting DFHack -============== -The project is currently hosted at http://www.github.com/ +Built-in Commands +================= +The following commands are provided by the 'core' components +of DFhack, rather than plugins or scripts. + + +.. _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. -Recent releases are available in source and binary formats `on the releases -page`_, while the binaries for releases 0.40.15-r1 to 0.34.11-r4 are on DFFD_. -Even older versions are available here_. +To enable or disable plugins that support this, use their names as +arguments for the command:: -.. _`on the releases page`: http://github.com/DFHack/dfhack/releases -.. _DFFD: http://dffd.bay12games.com/search.php?string=DFHack&id=15 -.. _here: http://dethware.org/dfhack/download + enable manipulator search -All new releases are announced in `the bay12 forums thread`_, which is also a -good place for discussion and questions. -.. _`the Bay12 DFHack thread`: -.. _`the bay12 forums thread`: http://www.bay12forums.com/smf/index.php?topic=139553 +.. _fpause: -If this sounds too complicated, you might prefer to `get a Starter Pack`_. -These are packages for new players or those who don't want to set up everything -themselves, and are available - with DFHack configured - for all OSes. +fpause +------ +Forces DF to pause. This is useful when your FPS drops below 1 and you lose +control of the game. -.. _`get a Starter Pack`: http://dwarffortresswiki.org/index.php/Utility:Lazy_Newb_Pack -Compatibility -============= -DFHack is available for Windows (XP or later), Linux (any modern distribution), -or OS X (10.6.8 to 10.9). +.. _help: -Most releases only support the version of DF mentioned in their title - for -example, DFHack 0.40.24-r2 only supports DF 0.40.24 - but some releases -support earlier DF versions as well. Wherever possible, use the latest version -built for the target version of DF. +help +---- +Most commands support using the ``help `` built-in command +to retrieve further help without having to look at this document. +``? `` and ``man `` are aliases. -On Windows, DFHack is compatible with the SDL version of DF, but not the legacy version. +Some commands (including many scripts) instead take ``help`` or ``?`` +as an option on their command line - ie `` help``. -It is also possible to use the Windows DFHack with Wine under Linux and OS X. -Installation/Removal -==================== -Installing DFhack involves copying files into your DF folder. -Copy the files from a release archive so that: +.. _hide: -* On Windows, ``SDL.dll`` is replaced -* On Linux or OSX, the ``dfhack`` script is placed in the same folder as the ``df`` script +hide +---- +Hides the DFHack terminal window. Only available on Windows. -Uninstalling is basically the same, in reverse: -* On Windows, first delete ``SDL.dll`` and rename ``SDLreal.dll`` to ``SDL.dll``, - then remove the other DFHack files -* On Linux, remove the DFHack files. +.. _keybinding: -The stonesense plugin might require some additional libraries on Linux. +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`. -If any of the plugins or dfhack itself refuses to load, check the ``stderr.log`` -file created in your DF folder. +Currently, any combinations of Ctrl/Alt/Shift with A-Z, 0-9, or F1-F12 are supported. +Possible ways to call the command: -=============== -Getting started -=============== -If DFHack is installed correctly, it will automatically pop up a console -window once DF is started as usual on windows. Linux and Mac OS X require -running the dfhack script from the terminal, and will use that terminal for -the console. +``keybinding list `` + List bindings active for the key combination. +``keybinding clear ...`` + Remove bindings for the specified keys. +``keybinding add "cmdline" "cmdline"...`` + Add bindings for the specified key. +``keybinding set "cmdline" "cmdline"...`` + Clear, and then add bindings for the specified key. -**NOTE**: The ``dfhack-run`` executable is there for calling DFHack commands in -an already running DF+DFHack instance from external OS scripts and programs, -and is *not* the way how you use DFHack normally. +The ```` parameter above has the following *case-sensitive* syntax:: -DFHack has a lot of features, which can be accessed by typing commands in the -console, or by mapping them to keyboard shortcuts. Most of the newer and more -user-friendly tools are designed to be at least partially used via the latter -way. + [Ctrl-][Alt-][Shift-]KEY[@context[|context...]] -In order to set keybindings, you have to create a text configuration file -called ``dfhack.init``; the installation comes with an example version called -``dfhack.init-example``, which is fully functional, covers all of the recent -features and can be simply renamed to ``dfhack.init``. You are encouraged to look -through it to learn which features it makes available under which key combinations. +where the *KEY* part can be any recognized key and [] denote optional parts. -Using DFHack -============ -DFHack basically extends what DF can do with something similar to the drop-down -console found in Quake engine games. On Windows, this is a separate command line -window. On Linux, the terminal used to launch the dfhack script is taken over -(so, make sure you start from a terminal). Basic interaction with dfhack -involves entering commands into the console. For some basic instructions, -use the ``help`` command. To list all possible commands, use the ``ls`` command. -Many commands have their own help or detailed description. You can use -``command help`` or ``command ?`` to show that. +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 command line has some nice line editing capabilities, including history -that's preserved between different runs of DF (use up/down keys to go through -the history). +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. -The second way to interact with DFHack is to bind the available commands -to in-game hotkeys. The old way to do this is via the hotkey/zoom menu (normally -opened with the ``h`` key). Binding the commands is done by assigning a command as -a hotkey name (with ``n``). +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. -A new and more flexible way is the keybinding command in the dfhack console. -However, bindings created this way are not automatically remembered between runs -of the game, so it becomes necessary to use the dfhack.init file to ensure that -they are re-created every time it is loaded. +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. -Many commands come from plugins, which are stored in ``hack/plugins/`` -and must be compiled with the same version of DFHack. Others come -from scripts, which are stored in ``hack/scripts``. Scripts are much -more flexible about versions, and easier to distribute - so most third-party -DFHack addons are scripts. -Something doesn't work, help! -============================= -First, don't panic :) +.. _kill-lua: -Second, dfhack keeps a few log files in DF's folder (``stderr.log`` and -``stdout.log``). Looking at these might help you solve the problem. -If it doesn't, you can ask for help in the forum thread or on IRC. +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. -If you found a bug, you can report it in `the Bay12 DFHack thread`_, -`the issues tracker on github `_, -or visit `the #dfhack IRC channel on freenode -`_. -============= -Core Commands -============= -DFHack command syntax consists of a command name, followed by arguments separated -by whitespace. To include whitespace in an argument, quote it in double quotes. -To include a double quote character, use ``\"`` inside double quotes. +.. _load: +.. _unload: +.. _reload: -If the first non-whitespace character of a line is ``#``, the line is treated -as a comment, i.e. a silent no-op command. +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:: -When reading commands from dfhack.init or with the ``script`` command, if the final -character on a line is a backslash then the next uncommented line is considered a -continuation of that line, with the backslash deleted. Commented lines are skipped, -so it is possible to comment out parts of a command with the ``#`` character. + load|unload|reload PLUGIN|all + +Allows dealing with plugins individually by name, or all at once. + + +.. _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 : List subcommands for the given plugin. + + +.. _plug: + +plug +---- +Lists available plugins (*not* commands implemented by plugins). + +``plug [PLUGIN|v]`` - list plugin state and detailed description. + + +.. _rb_eval: + +rb_eval +------- +Evaluate the following arguments as a ruby string. Best used as +``:rb_eval [string]``, for the special parsing mode: If the first non-whitespace character is ``:``, the command is parsed in a special alternative mode: first, non-whitespace characters immediately following the ``:`` @@ -157,160 +202,200 @@ The following two command lines are exactly equivalent:: :foo a b "c d" e f foo "a b \"c d\" e f" -This is intended for commands like ``rb_eval`` that evaluate script language statements. -Almost all the commands support using the ``help `` built-in command -to retrieve further help without having to look at this document. Alternatively, -some accept a ``help`` or ``?`` as an option on their command line. +.. _sc-script: -.. note:: +sc-script +--------- +Allows additional scripts to be run when certain events occur +(similar to onLoad*.init scripts) - Some tools work by displaying dialogs or overlays in the game window. - In order to avoid confusion, these tools display the word "DFHack" while active. If they - merely add keybinding hints to existing screens, they use red instead of green for the key. +.. _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 -========== -DFHack allows users to automatically run commonly-used DFHack commands when DF is first -loaded, when a game is loaded, and when a game is unloaded. +Some other tools, such as `autobutcher` and `workflow`, export +their settings as the commands to create them - which are later +loaded with ``script`` -Init scripts function the same way they would if the user manually typed in their contents, -but are much more convenient. If your DF folder contains at least one file with a name -following the format ``dfhack*.init`` where ``*`` is a placeholder for any string (including -the empty string), then all such files are executed in alphabetical order as init scripts when -DF is first loaded. -If your DF folder does not contain any such files, then DFHack will execute ``dfhack.init-example`` -as an example of useful commands to be run automatically. If you want DFHack to do nothing on -its own, then create an empty ``dfhack.init`` file in the main DF directory, or delete ``dfhack.init-example``. +.. _show: -The file ``dfhack.init-example`` is included as an example for users to follow if they need DFHack -command executed automatically. We recommend modifying or deleting ``dfhack.init-example`` as -its settings will not be optimal for all players. +show +---- +Shows the terminal window after it has been `hidden `. +Only available on Windows. You'll need to use it from a +`keybinding` set beforehand, or the in-game `command-prompt`. -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. -DFHack looks for init files in three places. -It will look for them in the main DF directory, and in ``data/save/_____/raw`` and -``data/save/_____/raw/objects`` where ``_____`` is the name of the current savegame. +.. important-commands: -When a game is loaded, DFHack looks for files of the form ``onLoad*.init``, where -``*`` can be any string, including the empty string. +Other Important Commands +======================== -When a game is unloaded, DFHack looks for files of the form ``onUnload*.init``. Again, -these files may be in any of the above three places. All matching init files will be -executed in alphebetical order. +.. _command-prompt: -Setting keybindings -=================== -To set keybindings, use the built-in ``keybinding`` command. Like any other -command it can be used at any time from the console, but it is most useful -in the DFHack init file. +command-prompt +-------------- +An in-game DFHack terminal, where you can enter other commands. +Best used from a keybinding; by default :kbd:`Ctrl`:kbd:`Shift`:kbd:`P`. -Currently, any combinations of Ctrl/Alt/Shift with A-Z, 0-9, or F1-F12 are supported. +Usage: ``command-prompt [entry]`` -Possible ways to call the command: +If called with an entry, it starts with that text filled in. +Most useful for developers, who can set a keybinding to open +a laungage interpreter for lua or Ruby by starting with the +`:lua ` or `:rb_eval ` commands. -``keybinding list `` - List bindings active for the key combination. -``keybinding clear ...`` - Remove bindings for the specified keys. -``keybinding add "cmdline" "cmdline"...`` - Add bindings for the specified key. -``keybinding set "cmdline" "cmdline"...`` - Clear, and then add bindings for the specified key. +Otherwise somewhat similar to `gui/quickcmd`. -The ```` parameter above has the following *case-sensitive* syntax:: +.. image:: images/command-prompt.png - [Ctrl-][Alt-][Shift-]KEY[@context[|context...]] -where the *KEY* part can be any recognized key and [] denote optional parts. +.. _hotkeys: -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. +hotkeys +------- +Opens an in-game screen showing which DFHack keybindings are +active in the current context. -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. -for context ``foo/bar/baz``, possible matches are any of ``@foo/bar/baz``, ``@foo/bar``, -``@foo`` or none. Multiple contexts can be specified by separating them with a -pipe (``|``) - for example, ``@foo|bar|baz/foo``. +.. image:: images/hotkeys.png -Hotkeys -======= -Opens an in-game screen showing DFHack keybindings that are active in the current context. +Type ``hotkeys`` into the DFHack console to open the screen, +or bind the command to a globally active hotkey. The default +keybinding is :kbd:`Ctrl`:kbd:`F1`. See also `hotkey-notes`. -.. image:: images/hotkeys.png +lua +--- +The `lua` script provides an interactive interpreter, allows +loading and saving of lua files, or runs a single line of code. -Type ``hotkeys`` into the DFHack console to open the screen, or bind the command to a -globally active hotkey. The default keybinding is ``Ctrl-F1``. +multicmd +-------- +The `multicmd` script calls many commands in one line. -.. _command-prompt: +.. _nopause: -In-game command prompt -====================== -The ``command-prompt`` plugin adds an in-game DFHack terminal, where you -can enter other commands. It's default keybinding is Ctrl-Shift-P. +nopause +------- +Disables pausing (both manual and automatic) with the exception of pause forced +by `reveal` ``hell``. This is nice for digging under rivers. -A one line command prompt in df. Same as entering command into dfhack console. Best -used as a keybinding. Can be called with optional "entry" that will start prompt with -that pre-filled. +quicksave +--------- +The `quicksave` script saves the game immediately without exiting. -.. image:: images/command-prompt.png +repeat +------ +The `repeat` script sets a command to be called regularly. -Enabling plugins -================ -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. +.. _init-files: -To enable or disable plugins that support this, use their names as -arguments for the command:: +Init Files +========== +DFHack allows users to automatically run commonly-used DFHack commands +when DF is first loaded, when a game is loaded, and when a game is unloaded. - enable manipulator search +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. +DFHack looks for init files in three places each time they could be run: -Game progress -============= +#. The main DF directory +#. :file:`data/save/{world}/raw`, where ``world`` is the current save, and +#. :file:`data/save/{world}/raw/objects` -die ---- -Instantly kills DF without saving. +When reading commands from dfhack.init or with the `script` command, if the final +character on a line is a backslash then the next uncommented line is considered a +continuation of that line, with the backslash deleted. Commented lines are skipped, +so it is possible to comment out parts of a command with the ``#`` character. -quicksave ---------- -Save immediately, without exiting. Only available in fortress mode. -forcepause ----------- -Forces DF to pause. This is useful when your FPS drops below 1 and you lose -control of the game. Activate with ``forcepause 1``; deactivate with ``forcepause 0``. +.. _dfhack.init: -.. _`hide, show`: +dfhack*.init +------------ +If your DF folder contains at least one file named ``dfhack*.init`` +(where ``*`` is a placeholder for any string), then all such files +are executed in alphabetical order when DF is first started. -hide / show ------------ -Hides or shows the DFHack terminal window, respectively. To use ``show``, use -the in-game console (default keybinding ``Ctrl-Shift-P``). Only available on Windows. +DFHack is distributed with :download:`/dfhack.init-example` as an example +with an up-to-date collection of basic commands; mostly setting standard +keybindings and `enabling ` plugins. You are encouraged to look +through this file to learn which features it makes available under which +key combinations. You may also customise it and rename it to ``dfhack.init``. -nopause -------- -Disables pausing (both manual and automatic) with the exception of pause forced -by 'reveal hell'. This is nice for digging under rivers. +If your DF folder does not contain any ``dfhack*.init`` files, the example +will be run as a fallback. + +These files are best used for keybindings and enabling persistent plugins +which do not require a world to be loaded. + + +.. _onLoad.init: + +onLoad*.init +------------ +When a world is loaded, DFHack looks for files of the form ``onLoad*.init``, +where ``*`` can be any string, including the empty string. + +All matching init files will be executed in alphebetical order. +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 +a `fix ` script to run on `repeat`. + + +.. _onUnload.init: + +onUnload*.init +-------------- +When a world is unloaded, DFHack looks for files of the form ``onUnload*.init``. +Again, these files may be in any of the above three places. +All matching init files will be executed in alphebetical order. + +Modders often use such scripts to disable tools which should not affect +an unmodded save. + + +Other init files +---------------- +* 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. + + +Miscellaneous Notes +=================== +This section is for odd but important notes that don't fit anywhere else. + +* The ``dfhack-run`` executable is there for calling DFHack commands in + an already running DF+DFHack instance from external OS scripts and programs, + and is *not* the way how you use DFHack normally. + +* If a DF hotkey (:kbd:`H`) is named with a DFHack command, pressing + the corresponding :kbd:`Fx` button will run that command, instead of + zooming to the set location. + +* The command line has some nice line editing capabilities, including history + that's preserved between different runs of DF (use up/down keys 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 ``\"``. + +* The binaries for 0.40.15-r1 to 0.34.11-r4 are on DFFD_. + Older versions are available here_. + + .. _DFFD: http://dffd.bay12games.com/search.php?string=DFHack&id=15&limit=1000 + .. _here: http://dethware.org/dfhack/download diff --git a/docs/Introduction.rst b/docs/Introduction.rst new file mode 100644 index 000000000..f0fc0a0bf --- /dev/null +++ b/docs/Introduction.rst @@ -0,0 +1,107 @@ +.. _introduction: + +######################### +Introduction and Overview +######################### + +DFHack is a Dwarf Fortress memory access library, distributed with +a wide variety of useful scripts and plugins. + +The project is currently hosted at https://www.github.com/DFHack/dfhack, +and can be downloaded from `the releases page +`_. + +All new releases are announced in :forums:`the bay12 forums thread <139553>`, +which is also a good place for discussion and questions. + +For users, it provides a significant suite of bugfixes and interface +enhancements by default, and more can be enabled. There are also many tools +(such as `workflow` or `autodump`) which can make life easier. +You can even add third-party scripts and plugins to do almost anything! + +For modders, DFHack makes many things possible. Custom reactions, new +interactions, magic creature abilities, and more can be set through `modtools` +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 - +or for coexistence in a single DF install, even with incompatible components. + +For developers, DFHack unites the various ways tools access DF memory and +allows easier development of new tools. As an open-source project under +`various copyleft licences `, contributions are welcome. + + +.. contents:: + + +.. _installing: + +Installing DFHack +================= +New players are encouraged to :wiki:`get a pack with DFHack preinstalled +`. + +DFHack is available for the SDL version of Dwarf Frtress on Windows, +any modern Linux distribution, and OS X (10.6.8 to 10.9). +It is possible to use Windows DF+DFHack under Wine on Linux or OS X. + +Most releases only support the version of DF mentioned in their title - for +example, DFHack 0.40.24-r2 only supports DF 0.40.24 - but some releases +support earlier DF versions as well. Wherever possible, use the latest version +of DFHack built for the target version of DF. + +Installing DFhack involves copying files from a release archive +into your DF folder, so that: + +* On Windows, ``SDL.dll`` is replaced +* On Linux or OSX, the ``dfhack`` script is placed in the same folder as the ``df`` script + +Uninstalling is basically the same, in reverse: + +* On Windows, replace ``SDL.dll`` with ``SDLreal.dll``, then remove the DFHack files. +* On Linux or OSX, remove the DFHack files. + + +Getting started +=============== +DFHack basically extends DF with something similar to the +console found in many PC games. + +If DFHack is installed correctly, it will automatically pop up a console +window once DF is started as usual on Windows. Linux and Mac OS X require +running the dfhack script from the terminal, and will use that terminal for +the console. + +* Basic interaction with dfhack involves entering commands into the console. + To learn what commands are available, you can keep reading this documentation + or skip ahead and use the `ls` and `help` commands. + +* Another way to interact with DFHack is to set in-game `keybindings ` + for certain commands. Many of the newer and user-friendly tools are designed + to be used this way. + +* Commands can also run at startup via `init files `, + on in batches at other times with the `script` command. + +* 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. + + +.. _troubleshooting: + +Troubleshooting +=============== +Don't panic! Even if you need this section, it'll be OK :) + +If something goes wrong, check the log files in DF's folder +(``stderr.log`` and ``stdout.log``). Looking at these might help you - +or someone else - solve the problem. Take screenshots of any weird +error messages, and take notes on what you did to cause them. + +If the search function in this documentation isn't enough and +:wiki:`the DF Wiki <>` hasn't helped, try asking in: + +- the `#dfhack IRC channel on freenode `_ +- the :forums:`Bay12 DFHack thread <139553>` +- the `/r/dwarffortress `_ questions thread +- the thread for the mod or Starter Pack you're using (if any) +