Rename part of the documentation:
[crawl.git] / crawl-ref / docs / macros_guide.txt
1 Macros and Keymaps
2 ==================
3
4 What are macros and keymaps? The simple explanation is:
5
6 Command macros make keys into commands.
7 Keymaps make keys into other keys.
8
9 Or a bit more verbose:
10
11 For the most part, people will probably want command macros. They allow
12 for things like making a key run a sequence of commands (e.g.
13 associating a key stroke to the casting of a certain spell) without
14 having to worry about messing up what that key does at prompts (e.g.
15 you can macro a number or letter without worrying about it making the
16 substitution when you're trying to drop an item).
17
18 Keymaps are for when you want to fix layout and behavioural problems on
19 your keyboard (i.e. unrecognised numpad sequences can by mapped into
20 their numbers, foreign keyboard layouts can be modified to be more
21 comfortable). There are also special sets of keymaps for the level map,
22 the targeting mode and confirmation prompts, which allow for mappings
23 that are restricted to just those situations.
24
25
26 How to create macros and keymaps?
27 =================================
28
29 The simplest way is in-game: Press either the '~' key or Ctrl-D, select
30 'm' to define a macro, then choose a key to assign for your macro and
31 enter the command sequence. For some keys (or key combinations), Crawl
32 will display a strange number (for example \{13} for the Return key).
33 These numbers are the key codes for certain non-alpanumeric keys and
34 can vary between different systems.
35
36 By default, most upper- and lowercase alphanumeric keys are already
37 assigned functions in Crawl. While you are free to remap those keys as
38 well, it might be best to start with some of the currently unused keys,
39 such as Tab or the function keys (F1 to F12), possibly combined with
40 Ctrl, Shift or both. On some systems, it may also be possible to
41 incorporate the Alt (Meta) key.
42
43 Defining keymaps works in exactly the same way. Just press 'k'
44 (default), 'x' (level-map), 't' (targeting) or 'c' (confirmation)
45 instead of 'm' after pressing '~'.
46
47 After defining such a macro or keymap, you should test it. If you are 
48 comfortable with it, you should then save the macro. To save all macros 
49 and keymaps, press '~' and then 's' to save macros at the tilde prompt).
50
51
52 The macro.txt file
53 ==================
54
55 Macros and keymaps are stored in a file called macro.txt in your main
56 Crawl directory or your home directory. You can change where the file
57 is read from and written to by specifying an alternate directory on
58 the command line with -macro <dir> or with the crawl_dir option in your
59 init file (see crawl_options.txt for details). The macro.txt file is
60 human readable and editable, but you might have to figure out the key
61 codes for non-alphanumeric keys through in-game experimentation or
62 external utilities.
63
64 Lines beginning with the '#' are comments and will be ignored. Note
65 that Crawl won't necessarily preserve your comments when saving macros
66 and keymaps to the macro.txt file.
67
68 Each macro definition consists of exactly two lines. The first one
69 describes the macro trigger key and consists of "M:" followed by the
70 character or keycode of that key (for example 'a', 'A' or \{9} for
71 the A, Shift-A or Tab keys). The second one describes the macro action
72 and consists of "A:" followed by the command sequence to be associated
73 with the above key (for example "zap" for zapping the spell in slot a
74 at the previous target). Individual macro definitions should be
75 separated by empty lines.
76
77 For keymaps just replace the "M:" on the first line of the definiton
78 with one of the following:
79 "K:"  default, 
80 "K1:" level-map, 
81 "K2:" targeting or 
82 "K3:" confirmation.
83
84
85 Examples
86 ========
87
88 This section contains some examples to give you an idea what macros and
89 keymaps can be used for. Note that for the sake of completeness, both
90 key line and command line are given, but that you should probably
91 substitute your own keys here as these may not always work for you.
92
93
94 '@' is a character that may not work by default on some keyboard
95 layouts. The following should remedy that by mapping '@' to '@'.
96
97 # @: display character status
98 K:\{17}
99 A:@
100
101
102 Playing a summoner can be annoying because you often need to cast the
103 same spells multiple times in a row, each casting requiring multiple
104 keystrokes. This macro allows casting the spell in slot 'a' with a
105 single keystroke. Note that you can redefine spell slots with the '='
106 key. We emphasise again that the F1 key may get a different code on
107 your system.
108
109 # F1: cast spell 'a'
110 M:\{368}
111 A:za
112
113
114 Now that we've taken care of summoning, we still need to command our
115 summoned creatures. The following macro should make that easier as
116 well. Note that this macro assumes that the default_target option is
117 set to true (it is by default; see crawl_options.txt for details).
118
119 # Tab: Order allies to attack your previous or the nearest target
120 M:\{9}
121 A:!a.
122
123
124 Conjurers need a slightly different macros for casting, such as this
125 one, as they need to press '.' or Return to confirm firing at a target.
126 Again, this macro assumes that the default_target option is set to
127 true.
128
129 # F1: cast spell 'a' at your previous or the nearest target
130 M:\{368}
131 A:za.
132
133
134 However, even conjurers might not always want to fire at their previous
135 target, so the following set of macros allows them to cast the spell
136 in slot 'a' and then cycle through the available targets with the same
137 key and then confirming with the same key we used for firing in the
138 previous macro. This example also tries to illustrate how to take
139 advantage of the fact that keys can have different functions in the
140 different keymaps.
141
142 # Shift-F1: cast spell 'a'
143 M:\{1392}
144 A:za
145
146 # Shift-F1: cycle through targets when in targetting mode
147 K2:\{1392}
148 A:+
149
150 # F1: fire at target when in targetting mode
151 K2:\{368}
152 A:.