diff options
Diffstat (limited to 'crawl-ref/docs/macros_guide.txt')
-rw-r--r-- | crawl-ref/docs/macros_guide.txt | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/crawl-ref/docs/macros_guide.txt b/crawl-ref/docs/macros_guide.txt new file mode 100644 index 0000000000..252db61abc --- /dev/null +++ b/crawl-ref/docs/macros_guide.txt @@ -0,0 +1,152 @@ +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-alpanumeric 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 Tab 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 main +Crawl directory or your home directory. You can change where the file +is read from and written to by specifying an alternate directory on +the command line with -macro <dir> or with the crawl_dir option in your +init file (see crawl_options.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 definiton +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:!a. + + +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 targetting mode +K2:\{1392} +A:+ + +# F1: fire at target when in targetting mode +K2:\{368} +A:.
\ No newline at end of file |