lib/help/pref.txt

   1 === User Pref Files ===
   2
   3 Hengband allows you to change various aspects of the game to suit your
   4 tastes. You may define keymaps (changing the way Hengband maps your
   5 keypresses to underlying commands), create macros (allowing you to map
   6 a single keypress to a series of keypresses), modify the visuals
   7 (allowing you to change the appearance of monsters, objects, or terrain
   8 features), change the colors (allowing you to make a given color
   9 brighter, darker, or even completely different), or set options
  10 (turning them off or on).
  11
  12 Hengband stores your preferences in files called "user pref files",
  13 which contain comments and "user pref commands", which are simple
  14 strings describing one aspect of the system about which the user has a
  15 preference. There are many ways to load a user pref file, and in fact,
  16 some of these files are automatically loaded for you by the game. All
  17 of the files are kept in the user directory, which is
  18 "~/.angband/Hengband/" on Unix, otherwise "lib/user/" , though you may
  19 have to use one of the command line arguments to redirect this
  20 directory, especially on multiuser systems. You may also enter single
  21 user pref commands directly, using the special "Enter a user pref
  22 command" command, activated by "double quote". You may have to use the
  23 "redraw" command (^R) after changing certain of the aspects of the
  24 game, to allow Hengband to adapt to your changes.
  25
  26 When the game starts up, after you have loaded an old character, or
  27 created a new character, some user pref files are loaded automatically.
  28 First, the "pref.prf" file is loaded. This file contains some user
  29 pref commands which will work on all platforms. Then one of
  30 "font-xxx.prf" (for normal usage) or "graf-xxx.prf" (for bitmap usage)
  31 is loaded. These files contain attr/char changes to allow the monsters,
  32 objects, and/or terrain features to look "better" on your system. Then
  33 the "pref-xxx.prf" file is loaded. This file contains pre-defined
  34 system specific stuff (macros, color definitions, etc). Then, the
  35 "user-xxx.prf" file is loaded. This file contains user-defined system
  36 specific stuff. The "user-xxx.prf" file is used as the "default" user
  37 pref file in many places. The "xxx" is the "system suffix" for your
  38 system, taken from the "main-xxx.c" file which was used to generate
  39 your executable. Finally, the "Race.prf", "Class.prf", and "Name.prf"
  40 files are loaded, where "Race", "Class", and "Name" are replaced by the
  41 actual race, class, and name of the current character.
  42
  43 Next, the preference files for object auto-picker/destroyer will be
  44 loaded.  "pickpref.prf" is for every characters, and
  45 "pickpref-<<player's name>>.prf" is for specific player.
  46
  47 Several commands allow you to both load existing user pref files,
  48 create new user pref files, append information to existing user pref
  49 files, and/or interact with various of the user preferences in a more
  50 intuitive way than the user pref commands allow. The commands include
  51 "Interact with macros" (@), "Interact with visuals" (%), and "Interact
  52 with colors" (&), described below.
  53
  54 In Hengband, all preference which will be generated in-game are not
  55 simply appended to old files but replaces old lines. You don't need to
  56 delete old lines with text editor.
  57
  58 ***** <Commands>
  59 --- User pref file commands ---
  60
  61 Interact with options (=)
  62      Allow you to interact with options. Note that using the "cheat"
  63      options may mark your savefile as unsuitable for the high score
  64      list. You may change normal options using the "X" and "Y" user
  65      pref commands. You must use the "redraw" command (^R) after
  66      changing certain options.
  67
  68 Interact with macros (@)
  69      Allow you to interact with macros. You may load or save macros
  70      from user pref files, create macros of various types, or define
  71      keymaps. You must define a "current action", shown at the bottom
  72      of the screen, before you attempt to use any of the "create macro"
  73      commands, which use that "current action" as their action. This
  74      is a horrible interface, and will be fixed eventually.
  75
  76 Interact with visuals (%)
  77      Allow you to interact with visuals. You may load or save visuals
  78      from user pref files, or modify the attr/char mappings for the
  79      monsters, objects, and terrain features.
  80
  81 Interact with colors (&)
  82      Allow the user to interact with colors. This command only
  83      works on some systems.
  84
  85 Reload auto-picker/destroyer preference ($)
  86      This command will reload "pickpref.prf" and
  87      "pickpref-<<playername>>.prf" for object auto-picker/destroyer
  88      after you edit these files with your text editor.
  89
  90 Edit auto-picker/destroyer pref (_)
  91      Allow the user to edit the pickpref.prf in the user directry.
  92      The ESC key will open the menu in this editor.  You can see and
  93      use all edit commands from the command menu.  Press ^Q or ^W to
  94      quit the editor.
  95
  96
  97 ***** <Macros>
  98 --- User Pref Files (Macros) ---
  99
 100 The "Interact with macros" command allows you to define or remove
 101 "macros", which are mappings from a single logical keypress to a
 102 sequence of keypresses, allowing you to use special keys on the
 103 keyboard, such as function keys or keypad keys, possibly in conjunction
 104 with modifier keys, to "automate" repetitive multi-keypress commands
 105 that you use a lot.
 106
 107 Since macros represent keypress sequences, and not all keypresses have
 108 a printable representation, macro triggers and actions must often be
 109 "encoded" into a human readable form. This is done using several types
 110 of encoding, including "\xHH" for character number HH in hexadecimal,
 111 "\e" for the "escape" code, "\n" for the "newline" code, "\r" for the
 112 "return" code, "\s" for the "space" code, "\\" for backslash, "\^" for
 113 caret, and "^X" for the code for any "control" key "ctrl-X".
 114
 115 In Hengband, name of special keys as macro-trigger is displayed using
 116 its real name, for example the Control-key plus the F1-key is
 117 displayed as "\[control-F2]", and the Alt-key plus the G is displayed
 118 as "\[Alt-G]". In other variant these special keys will be, currently,
 119 displayed using its key-code.
 120
 121 Note that the "action" of a macro will not be checked against other
 122 macro triggers, so you cannot make infinite loops. You may specify
 123 extremely long macros, but you are limited in length by the underlying
 124 input mechanisms, which in general limit you to about 1024 keys in
 125 both triggers and actions.
 126
 127 The special "\" command (which must be encoded in macros as "\\") is
 128 very useful in macros, since it bypasses all keymaps and allows the
 129 next keystroke to be considered a command in the underlying Hengband
 130 command set. For a list of the Hengband command set, see the
 131 "command.txt" help file. For example, a macro which maps Shift-KP6 to
 132 "\" + "." + "6" will induce the "run east" behavior, regardless of what
 133 keyset the user has chosen, and regardless of what keymaps have been
 134 defined.
 135
 136 Macros can be specified in user pref files as a pair of lines, one of
 137 the form "A:<str>", which defines the encoded macro action, and one of
 138 the form "P:<str>", which defines the encoded macro trigger.
 139
 140
 141 ***** <KeyMaps>
 142 --- User Pref Files (Keymaps) ---
 143
 144 The "Interact with macros" command also allows you to define "keymaps",
 145 which are vaguely related to macros. A keymap maps a single keypress to
 146 a series of keypresses, which bypass both other keymaps and any macros.
 147 Hengband uses keymaps to map the original and the roguelike keysets to
 148 the underlying command set, and allows the user to modify or add
 149 keymaps of their own. Note that all keymap actions must be specified
 150 using underlying commands, not keypresses from the original or
 151 roguelike keysets. The original keyset is almost identical to the
 152 underlying keyset, except that "numbers" are mapped to ";" plus a
 153 direction, "5" is mapped to ",", and a few control-keys are mapped to
 154 various things. See "command.txt" for the full set of underlying
 155 commands. Some uses for keymaps include the ability to "disable" a
 156 command by mapping it to "\x00".
 157
 158 Keymaps can be specified in user pref files as pairs of lines of the
 159 form "A:<str>" "C:<T>:<key>", where <str> is the encoded keymap
 160 action, <T> is the keyset (0 for original and 1 for roguelike), <key>
 161 is the encoded trigger key.
 162
 163
 164 ***** <Visuals>
 165 --- User Pref Files (Visuals) ---
 166
 167 You can use the "Interact with visuals" command to change various
 168 visual information, currently including the choice of what attr/char
 169 values are used to represent various monsters, objects, or terrain
 170 features. Note that in combination appropriate support in "main-xxx.c",
 171 and with the use of the "use_graphics" flag, you may be able to specify
 172 that "graphic bitmaps" should be used instead of normal "colored
 173 characters" for various things.
 174
 175 When interactively modifying the attr/char values for monsters,
 176 objects, or terrain features, pressing "n" or "N" will change which
 177 entry you are changing, pressing "a" or "A" will rotate through the
 178 available attr values, and pressing "c" or "C" will rotate though the
 179 available char values, and pressing "^N", "^A", and "^C" will let you
 180 directly enter a number and set the entry, attr or char value to that
 181 number.  Note that attr/char values with the "high bit" set may induce
 182 the display of special "graphic" pictures if the "use_graphics" flag
 183 is set, and your system supports the "use_graphics" flag.
 184
 185 Note that this command can be abused in various ways, and if you must
 186 do so, remember that you are only cheating yourself.
 187
 188 Visuals can be modified in user pref files as lines of the form
 189 "R:<N>:<A>/<C>" or "K:<N>:<A>/<C>" or "F:<N>:<A>/<C>".
 190
 191
 192 ***** <Colors>
 193 --- User Pref Files (Colors) ---
 194
 195 The "Interact with colors" command allows you to change the actual
 196 internal values used to display various colors. This command may or may
 197 not have any effect on your machine. Advanced machines may allow you to
 198 change the actual RGB values used to represent each of the 16 colors
 199 used by Hengband, and perhaps even allow you to define new colors which
 200 are not currently used by Hengband.
 201
 202 Colors can be specified in user pref files as lines of the form
 203 "V:<N>:<V>:<R>:<G>:<B>".
 204
 205
 206 ***** <Options>
 207 --- User Pref Files (Options) ---
 208
 209 The "Interact with options" command allows you to turn options on or
 210 off. You may turn options off or on using the user pref commands of the
 211 form "X:<option>" or "Y:<option>" respectively.
 212
 213 This method of preference line might be useful in the macro. For
 214 example, if you want to cast some spell repeatedly, you can use macro
 215 such that;
 216
 217 A:"X:avoid_abort\rR\rmbc"Y:avoid_abort\r
 218 P:\[F1]
 219
 220 When you press the F1 repeatedly, your character cast spell "c" of
 221 spellbook "b", and rest to restore mana, and repeat.  "X:avoid_abort"
 222 is needed because the Rest command will usually be stopped by any key
 223 input.
 224
 225 An explanation of 'avoid_abort' option is found the section on
 226 Efficiency Options (see option.txt#Efficiency [b])
 227 ***** [b] option.txt#Efficiency
 228
 229
 230 ############################################################
 231
 232
 233 Original   : Alexander Cutler and Andy Astrand
 234 Updated    : (2.7.6) by Russ Allbery (rra@cs.stanford.edu)
 235 Updated    : (2.7.9) by Ben Harrison (benh@phial.com)
 236 Updated    : Zangband 2.2.0 through 2.2.6c by Robert Ruehlmann
 237 Updated    : Zangband DevTeam
 238 Updated    : Hengband 1.7.0