Fix formatted_scroller::line_down() returning wrong boolean
[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-alphanumeric 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 Ins 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
56 settings/ directory. You can change where the file is read from and
57 written to by specifying an alternate directory with the macro_dir
58 option in your init file (see options_guide.txt for details). The
59 macro.txt file is human readable and editable, but you might have to
60 figure out the key codes for non-alphanumeric keys through in-game
61 experimentation or external utilities.
62
63 Lines beginning with the '#' are comments and will be ignored. Note
64 that Crawl won't necessarily preserve your comments when saving macros
65 and keymaps to the macro.txt file.
66
67 Each macro definition consists of exactly two lines. The first one
68 describes the macro trigger key and consists of "M:" followed by the
69 character or keycode of that key (for example 'a', 'A' or \{9} for
70 the A, Shift-A or Tab keys). The second one describes the macro action
71 and consists of "A:" followed by the command sequence to be associated
72 with the above key (for example "zap" for zapping the spell in slot a
73 at the previous target). Individual macro definitions should be
74 separated by empty lines.
75
76 For keymaps just replace the "M:" on the first line of the definition
77 with one of the following:
78 "K:"  default,
79 "K1:" level-map,
80 "K2:" targeting or
81 "K3:" confirmation.
82
83
84 Examples
85 ========
86
87 This section contains some examples to give you an idea what macros and
88 keymaps can be used for. Note that for the sake of completeness, both
89 key line and command line are given, but that you should probably
90 substitute your own keys here as these may not always work for you.
91
92
93 '@' is a character that may not work by default on some keyboard
94 layouts. The following should remedy that by mapping '@' to '@'.
95
96 # @: display character status
97 K:\{17}
98 A:@
99
100
101 Playing a summoner can be annoying because you often need to cast the
102 same spells multiple times in a row, each casting requiring multiple
103 keystrokes. This macro allows casting the spell in slot 'a' with a
104 single keystroke. Note that you can redefine spell slots with the '='
105 key. We emphasise again that the F1 key may get a different code on
106 your system.
107
108 # F1: cast spell 'a'
109 M:\{368}
110 A:za
111
112
113 Now that we've taken care of summoning, we still need to command our
114 summoned creatures. The following macro should make that easier as
115 well. Note that this macro assumes that the default_target option is
116 set to true (it is by default; see crawl_options.txt for details).
117
118 # Tab: Order allies to attack your previous or the nearest target
119 M:\{9}
120 A:ta.
121
122
123 Conjurers need a slightly different macros for casting, such as this
124 one, as they need to press '.' or Return to confirm firing at a target.
125 Again, this macro assumes that the default_target option is set to
126 true.
127
128 # F1: cast spell 'a' at your previous or the nearest target
129 M:\{368}
130 A:za.
131
132
133 However, even conjurers might not always want to fire at their previous
134 target, so the following set of macros allows them to cast the spell
135 in slot 'a' and then cycle through the available targets with the same
136 key and then confirming with the same key we used for firing in the
137 previous macro. This example also tries to illustrate how to take
138 advantage of the fact that keys can have different functions in the
139 different keymaps.
140
141 # Shift-F1: cast spell 'a'
142 M:\{1392}
143 A:za
144
145 # Shift-F1: cycle through targets when in targeting mode
146 K2:\{1392}
147 A:+
148
149 # F1: fire at target when in targeting mode
150 K2:\{368}
151 A:.