macros_guide.txt

Macros and Keymaps
==================

What are macros and keymaps? The simple explanation is:

Command macros make keys into commands.
Keymaps make keys into other keys.

Or a bit more verbose:

For the most part, people will probably want command macros. They allow
for things like making a key run a sequence of commands (e.g.
associating a key stroke to the casting of a certain spell) without
having to worry about messing up what that key does at prompts (e.g.
you can macro a number or letter without worrying about it making the
substitution when you're trying to drop an item).

Keymaps are for when you want to fix layout and behavioural problems on
your keyboard (i.e. unrecognised numpad sequences can by mapped into
their numbers, foreign keyboard layouts can be modified to be more
comfortable). There are also special sets of keymaps for the level map,
the targeting mode and confirmation prompts, which allow for mappings
that are restricted to just those situations.


How to create macros and keymaps?
=================================

The simplest way is in-game: Press either the '~' key or Ctrl-D, select
'm' to define a macro, then choose a key to assign for your macro and
enter the command sequence. For some keys (or key combinations), Crawl
will display a strange number (for example \{13} for the Return key).
These numbers are the key codes for certain non-alphanumeric keys and
can vary between different systems.

By default, most upper- and lowercase alphanumeric keys are already
assigned functions in Crawl. While you are free to remap those keys as
well, it might be best to start with some of the currently unused keys,
such as Ins or the function keys (F1 to F12), possibly combined with
Ctrl, Shift or both. On some systems, it may also be possible to
incorporate the Alt (Meta) key.

Defining keymaps works in exactly the same way. Just press 'k'
(default), 'x' (level-map), 't' (targeting) or 'c' (confirmation)
instead of 'm' after pressing '~'.

After defining such a macro or keymap, you should test it. If you are
comfortable with it, you should then save the macro. To save all macros
and keymaps, press '~' and then 's' to save macros at the tilde prompt).


The macro.txt file
==================

Macros and keymaps are stored in a file called macro.txt in your
settings/ directory. You can change where the file is read from and
written to by specifying an alternate directory with the macro_dir
option in your init file (see options_guide.txt for details). The
macro.txt file is human readable and editable, but you might have to
figure out the key codes for non-alphanumeric keys through in-game
experimentation or external utilities.

Lines beginning with the '#' are comments and will be ignored. Note
that Crawl won't necessarily preserve your comments when saving macros
and keymaps to the macro.txt file.

Each macro definition consists of exactly two lines. The first one
describes the macro trigger key and consists of "M:" followed by the
character or keycode of that key (for example 'a', 'A' or \{9} for
the A, Shift-A or Tab keys). The second one describes the macro action
and consists of "A:" followed by the command sequence to be associated
with the above key (for example "zap" for zapping the spell in slot a
at the previous target). Individual macro definitions should be
separated by empty lines.

For keymaps just replace the "M:" on the first line of the definition
with one of the following:
"K:"  default,
"K1:" level-map,
"K2:" targeting or
"K3:" confirmation.


Examples
========

This section contains some examples to give you an idea what macros and
keymaps can be used for. Note that for the sake of completeness, both
key line and command line are given, but that you should probably
substitute your own keys here as these may not always work for you.


'@' is a character that may not work by default on some keyboard
layouts. The following should remedy that by mapping '@' to '@'.

# @: display character status
K:\{17}
A:@


Playing a summoner can be annoying because you often need to cast the
same spells multiple times in a row, each casting requiring multiple
keystrokes. This macro allows casting the spell in slot 'a' with a
single keystroke. Note that you can redefine spell slots with the '='
key. We emphasise again that the F1 key may get a different code on
your system.

# F1: cast spell 'a'
M:\{368}
A:za


Now that we've taken care of summoning, we still need to command our
summoned creatures. The following macro should make that easier as
well. Note that this macro assumes that the default_target option is
set to true (it is by default; see crawl_options.txt for details).

# Tab: Order allies to attack your previous or the nearest target
M:\{9}
A:ta.


Conjurers need a slightly different macros for casting, such as this
one, as they need to press '.' or Return to confirm firing at a target.
Again, this macro assumes that the default_target option is set to
true.

# F1: cast spell 'a' at your previous or the nearest target
M:\{368}
A:za.


However, even conjurers might not always want to fire at their previous
target, so the following set of macros allows them to cast the spell
in slot 'a' and then cycle through the available targets with the same
key and then confirming with the same key we used for firing in the
previous macro. This example also tries to illustrate how to take
advantage of the fact that keys can have different functions in the
different keymaps.

# Shift-F1: cast spell 'a'
M:\{1392}
A:za

# Shift-F1: cycle through targets when in targeting mode
K2:\{1392}
A:+

# F1: fire at target when in targeting mode
K2:\{368}
A:.