
======================= Preferences, Macros and Keymaps  ======================

Once you've played Halls of Mist for a while, you may decide to customize commands
and various other things to better suit your tastes.  

The first thing you'll discover a use for are keymaps and macros.  They can be
set up relatively easily, and allow you to perform common tasks with a single
keystroke.  Setting and changing ASCII (textual symbol) preferences works 
similarly.

Some people also wind up editing user preference files directly, which gives 
them considerable control over commands, graphics, and various other things.


=== An Introduction to Macros and Keymaps ===

Lets say you are a mage, and often find yourself casting "a", Acid Bolt,
in spellbook "a", [Elementary Incantations] , at the lowest power level, "a".
In both keysets, that's "maaa", plus "*" to enter targeting mode, and finally
"t" to target.  Wouldn't it be nice if you could do all this with a single 
keypress?  

You can.  Choose an unused command (we shall pick "'" by way of example). Bring
up the macro/keymap screen by typing "@".  Press "8" to create a keymap, and 
the game will ask you for a keypress.  Type "'".  When you press Return, you
shift to the action field, where you input all the commands you want "'" to
perform when pressed.  In this case, you would enter:  "maaa*t", and press 
ENTER.  Now save your new keymap by typing "6", and either allow the game to 
choose your character's name for the preference file, or (if you want all of 
your characters to use the same keymap) save to "user.prf".

This is only the beginning.  What you can do with a spell, you can do with 
arrows, Rods of Trap Location, resting, activating the Phial, searching; all 
sorts of command combinations can profitably be keymapped.  Keymaps are even
more flexible when used in combination with object inscriptions - see the help
file "playing.txt".

=== User Pref Files ===

Halls of Mist allows you to change various aspects of the game to suit your tastes.
You may define keymaps (changing the way Halls of Mist 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).

Halls of Mist 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.  The default pref files, which 
control system compatibility and several default mappings, are found in the 
"lib/pref/" directory.  User-files, which can be used to override the defaults
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 multi-user
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 Halls of Mist 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.


=== 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 Halls of Mist command set.  For a
list of the Halls of Mist command set, see the "cmdlist.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.


=== 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.  Halls of Mist 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 "cmdlist.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/1 for original/roguelike), 
<key> is the encoded trigger key, and <str> is the encoded keymap action.


=== 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 (which is normally disabled in most Halls of Mist releases), 
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.

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

This command doesn't allow remapping of graphics for uniques based on other 
monster types, nor does it allow remapping of trap/glyph symbols.  The former
is currently impossible, while the latter requires manual editing of the pref
files.


=== 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 Halls of Mist, and 
perhaps even allow you to define new colors which are not currently used by 
Halls of Mist.

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


=== 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:O:<option>" or "Y:O:<option>" respectively for regular options, and 
"X:B:<option>" or "Y:B:<option>" respectively for birth options.
