=== User Pref Files ===

Zangband allows you to change various aspects of the game to suit your
tastes. You may define keymaps (changing the way Zangband maps your
keypresses to underlying commands), create macros (allowing you to map
a single keypress to a series of keypresses), modify the visuals
(allowing you to change the appearance of monsters, objects, or terrain
features), change the colors (allowing you to make a given color
brighter, darker, or even completely different), or set options
(turning them off or on).

Zangband stores your preferences in files called "user pref files",
which contain comments and "user pref commands", which are simple
strings describing one aspect of the system about which the user has a
preference. There are many ways to load a user pref file, and in fact,
some of these files are automatically loaded for you by the game. All
of the files are kept in the "lib/user/" directory, though you may have
to use one of the command line arguments to redirect this directory,
especially on multiuser systems. You may also enter single user pref
commands directly, using the special "Enter a user pref command"
command, activated by "double quote". You may have to use the "redraw"
command (^R) after changing certain of the aspects of the game, to
allow Zangband to adapt to your changes.

When the game starts up, after you have loaded an old character, or
created a new character, some user pref files are loaded automatically.
First, the "pref.prf" file is loaded. This file contains some user
pref commands which will work on all platforms. Then one of
"font-xxx.prf" (for normal usage) or "graf-xxx.prf" (for bitmap usage)
is loaded. These files contain attr/char changes to allow the monsters,
objects, and/or terrain features to look "better" on your system. Then
the "pref-xxx.prf" file is loaded. This file contains pre-defined
system specific stuff (macros, color definitions, etc). Then, the
"user-xxx.prf" file is loaded. This file contains user-defined system
specific stuff. The "user-xxx.prf" file is used as the "default" user
pref file in many places. The "xxx" is the "system suffix" for your
system, taken from the "main-xxx.c" file which was used to generate
your executable. Finally, the "Race.prf", "Class.prf", and "Name.prf"
files are loaded, where "Race", "Class", and "Name" are replaced by the
actual race, class, and name of the current character.

Several commands allow you to both load existing user pref files,
create new user pref files, append information to existing user pref
files, and/or interact with various of the user preferences in a more
intuitive way than the user pref commands allow. The commands include
"Interact with macros" (@), "Interact with visuals" (%), and "Interact
with colors" (&), described below.


***** <Commands>
--- User pref file commands ---

Interact with options (=)
     Allow you to interact with options. Note that using the "cheat"
     options may mark your savefile as unsuitable for the high score
     list. You may change normal options using the "X" and "Y" user
     pref commands. You must use the "redraw" command (^R) after
     changing certain options.

Interact with macros (@)
     Allow you to interact with macros. You may load or save macros
     from user pref files, create macros of various types, or define
     keymaps. You must define a "current action", shown at the bottom
     of the screen, before you attempt to use any of the "create macro"
     commands, which use that "current action" as their action. This
     is a horrible interface, and will be fixed eventually.

Interact with visuals (%)
     Allow you to interact with visuals. You may load or save visuals
     from user pref files, or modify the attr/char mappings for the
     monsters, objects, and terrain features. You must use the "redraw"
     command (^R) to redraw the map after changing attr/char mappings.

Interact with colors (&)
     Allow the user to interact with colors. This command only
     works on some systems.
 
Interact with the system (!)
     Allow the user to interact with the underlying visual system.
     This command is currently unused.


***** <Macros>
--- User Pref Files (Macros) ---

The "Interact with macros" command allows you to define or remove
"macros", which are mappings from a single logical keypress to a
sequence of keypresses, allowing you to use special keys on the
keyboard, such as function keys or keypad keys, possibly in conjunction
with modifier keys, to "automate" repetitive multi-keypress commands
that you use a lot.

Since macros represent keypress sequences, and not all keypresses have
a printable representation, macro triggers and actions must often be
"encoded" into a human readable form. This is done using several types
of encoding, including "\xHH" for character number HH in hexadecimal,
"\e" for the "escape" code, "\n" for the "newline" code, "\r" for the
"return" code, "\s" for the "space" code, "\\" for backslash, "\^" for
caret, and "^X" for the code for any "control" key "ctrl-X". Note that
the "action" of a macro will not be checked against other macro
triggers (unless the macro action contains a "control-backslash"), so
you cannot make infinite loops. You may specify extremely long macros,
but you are limited in length by the underlying input mechanisms,
which in general limit you to about 1024 keys in both triggers and
actions.

The special "\" command (which must be encoded in macros as "\\") is
very useful in macros, since it bypasses all keymaps and allows the
next keystroke to be considered a command in the underlying Zangband
command set. For a list of the Zangband command set, see the
"command.txt" help file. For example, a macro which maps Shift-KP6 to
"\" + "." + "6" will induce the "run east" behavior, regardless of what
keyset the user has chosen, and regardless of what keymaps have been
defined.

Macros can be specified in user pref files as a pair of lines, one of
the form "A:<str>", which defines the encoded macro action, and one of
the form "P:<str>", which defines the encoded macro trigger.


***** <KeyMaps>
--- User Pref Files (Keymaps) ---

The "Interact with macros" command also allows you to define "keymaps",
which are vaguely related to macros. A keymap maps a single keypress to
a series of keypresses, which bypass both other keymaps and any macros.
Zangband uses keymaps to map the original and the roguelike keysets to
the underlying command set, and allows the user to modify or add
keymaps of their own. Note that all keymap actions must be specified
using underlying commands, not keypresses from the original or
roguelike keysets. The original keyset is almost identical to the
underlying keyset, except that "numbers" are mapped to ";" plus a
direction, "5" is mapped to ",", and a few control-keys are mapped to
various things. See "command.txt" for the full set of underlying
commands. Some uses for keymaps include the ability to "disable" a
command by mapping it to "\x00".

Keymaps can be specified in user pref files as lines of the form
"M:<T> <key> <str>", where <T> is the keyset (0 for original and 1 for
roguelike), <key> is the encoded trigger key, and <str> is the encoded
keymap action.


***** <Visuals>
--- User Pref Files (Visuals) ---

You can use the "Interact with visuals" command to change various
visual information, currently including the choice of what attr/char
values are used to represent various monsters, objects, or terrain
features. Note that in combination appropriate support in "main-xxx.c",
and with the use of the "use_graphics" flag, you may be able to specify
that "graphic bitmaps" should be used instead of normal "colored
characters" for various things.

When interactively modifying the attr/char values for monsters,
objects, or terrain features, pressing "n" or "N" will change which
entry you are changing, pressing "a" or "A" will rotate through the
available attr values, and pressing "c" or "C" will rotate though the
available char values. Note that attr/char values with the "high bit"
set may induce the display of special "graphic" pictures if the
"use_graphics" flag is set, and your system supports the "use_graphics"
flag.

Note that this command can be abused in various ways, and if you must
do so, remember that you are only cheating yourself.

Keymaps can be specified in user pref files as lines of the form
"R:<N>:<A>/<C>" or "K:<N>:<A>/<C>" or "F:<N>:<A>/<C>" or
"U:<N>:<A>/<C>".


***** <Colors>
--- User Pref Files (Colors) ---

The "Interact with colors" command allows you to change the actual
internal values used to display various colors. This command may or may
not have any effect on your machine. Advanced machines may allow you to
change the actual RGB values used to represent each of the 16 colors
used by Zangband, and perhaps even allow you to define new colors which
are not currently used by Zangband.

Colors can be specified in user pref files as lines of the form
"V:<N>:<V>:<R>:<G>:<B>".


***** <Options>
--- User Pref Files (Options) ---

The "Interact with options" command allows you to turn options on or
off. You may turn options off or on using the user pref commands of the
form "X:<option>" or "Y:<option>" respectively.

 
-- 
Original   : Alexander Cutler and Andy Astrand
Updated    : (2.7.6) by Russ Allbery (rra@cs.stanford.edu)
Updated    : (2.7.9) by Ben Harrison (benh@phial.com)
Updated    : Zangband 2.2.0 through 2.2.6c by Robert Ruehlmann
Updated    : Zangband DevTeam
Last update: January 13, 2000
