README: move keybinding to the start and add a section for scripts.

develop
Alexander Gavrilov 2012-09-20 15:38:58 +04:00
parent e2d6a14720
commit 1403bb126c
2 changed files with 425 additions and 271 deletions

@ -1,3 +1,7 @@
#############
DFHack Readme
#############
============ ============
Introduction Introduction
============ ============
@ -97,11 +101,49 @@ the issues tracker on github, contact me (peterix@gmail.com) or visit the
============= =============
The init file The init file
============= =============
If your DF folder contains a file named dfhack.init, its contents will be run If your DF folder contains a file named ``dfhack.init``, its contents will be run
every time you start DF. This allows setting up keybindings. An example file every time you start DF. This allows setting up keybindings. An example file
is provided as dfhack.init-example - you can tweak it and rename to dfhack.init is provided as ``dfhack.init-example`` - you can tweak it and rename to dfhack.init
if you want to use this functionality. if you want to use this functionality.
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 also meaningful
in the DFHack init file.
Currently it supports any combination of Ctrl/Alt/Shift with F1-F9, or A-Z.
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]
where the *KEY* part can be F1-F9 or A-Z, 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.
for context ``foo/bar/baz``, possible matches are any of ``@foo/bar/baz``, ``@foo/bar``,
``@foo`` or none.
======== ========
Commands Commands
======== ========
@ -576,27 +618,6 @@ Duplicate the selected job in a workshop:
* In 'q' mode, when a job is highlighted within a workshop or furnace building, * In 'q' mode, when a job is highlighted within a workshop or furnace building,
instantly duplicates the job. instantly duplicates the job.
keybinding
==========
Manages DFHack keybindings.
Currently it supports any combination of Ctrl/Alt/Shift with F1-F9, or A-Z.
Options
-------
: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.
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.
liquids liquids
======= =======
Allows adding magma, water and obsidian to the game. It replaces the normal Allows adding magma, water and obsidian to the game. It replaces the normal
@ -1378,6 +1399,70 @@ also tries to have dwarves specialize in specific skills.
For detailed usage information, see 'help autolabor'. For detailed usage information, see 'help autolabor'.
=======
Scripts
=======
Lua or ruby scripts placed in the hack/scripts/ directory are considered for
execution as if they were native DFHack commands. They are listed at the end
of the 'ls' command output.
Note: scripts in subdirectories of hack/scripts/ can still be called, but will
only be listed by ls if called as 'ls -a'. This is intended as a way to hide
scripts that are obscure, developer-oriented, or should be used as keybindings.
Some notable scripts:
quicksave
=========
If called in dwarf mode, makes DF immediately auto-save the game by setting a flag
normally used in seasonal auto-save.
setfps
======
Run ``setfps <number>`` to set the FPS cap at runtime, in case you want to watch
combat in slow motion or something :)
fix/*
=====
Scripts in this subdirectory fix various bugs and issues, some of them obscure.
* fix/dead-units
Removes uninteresting dead units from the unit list. Doesn't seem to give any
noticeable performance gain, but migrants normally stop if the unit list grows
to around 3000 units, and this script reduces it back.
* fix/population-cap
Run this after every migrant wave to ensure your population cap is not exceeded.
The issue with the cap is that it is compared to the population number reported
by the last caravan, so once it drops below the cap, migrants continue to come
until that number is updated again.
* fix/stable-temp
Instantly sets the temperature of all free-lying items to be in equilibrium with
the environment and stops temperature updates. In order to maintain this efficient
state however, use ``tweak stable-temp`` and ``tweak fast-heat``.
* fix/item-occupancy
Diagnoses and fixes issues with nonexistant 'items occupying site', usually
caused by autodump bugs or other hacking mishaps.
gui/*
=====
Scripts that implement dialogs inserted into the main game window are put in this
directory.
growcrops growcrops
========= =========
Instantly grow seeds inside farming plots. Instantly grow seeds inside farming plots.

File diff suppressed because it is too large Load Diff