=== User Pref Files ===

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

Hengband 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 user directory, which is
"~/.angband/Hengband/" on Unix, otherwise "lib/user/" , 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 Hengband 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.

Next, the preference files for object auto-picker/destroyer will be
loaded.  "pickpref.prf" is for every characters, and
"pickpref-<<player's name>>.prf" is for specific player.

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.

In Hengband, all preference which will be generated in-game are not
simply appended to old files but replaces old lines. You don't need to
delete old lines with text editor.

***** <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.
 
Reload auto-picker/destroyer preference ($)
     This command will reload "pickpref.prf" and
     "pickpref-<<playername>>.prf" for object auto-picker/destroyer
     after you edit these files with your text editor.

Edit auto-picker/destroyer pref (_)
     Allow the user to edit the pickpref-<player's name>.prf in the
     user directry.  Basic usage of the editor is almost same as vi,
     and also have emacs like commands.  Most commands is always
     displayed on the first line and the right half of the screen.

     Important commands 
      'a', 'i' or ^Q :  Enter insert mode from command mode
      ESC  or ^Q     :  Return to command mode from insert mode
      'q'            :  Quit the editor (command mode only)
      'hjkl2468'     :  Move cursor (command mode only)
      ^B ^N ^P ^F    :  Move cursor (always)
      ^I  : Choose an item from inventry/equipment, then insert its name
      ^S  : Rotates action (pick up / destroy / leave on floor)
      ^U  : Rotates idendify state (identified / unidentified / ...)


***** <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". 

In Hengband, name of special keys as macro-trigger is displayed using
its real name, for example the Control-key plus the F1-key is
displayed as "\[control-F2]", and the Alt-key plus the G is displayed
as "\[Alt-G]". In other variant these special keys will be, currently,
displayed using its key-code.

Note that the "action" of a macro will not be checked against other
macro triggers, 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 Hengband
command set. For a list of the Hengband 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.
Hengband 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 pairs of lines of the
form "A:<str>" "C:<T>:<key>", where <str> is the encoded keymap
action, <T> is the keyset (0 for original and 1 for roguelike), <key>
is the encoded trigger key.


***** <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, and pressing "^N", "^A", and "^C" will let you
directly enter a number and set the entry, attr or char value to that
number.  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.

Visuals can be modified in user pref files as lines of the form
"R:<N>:<A>/<C>" or "K:<N>:<A>/<C>" or "F:<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 Hengband, and perhaps even allow you to define new colors which
are not currently used by Hengband.

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.

This method of preference line might be useful in the macro. For
example, if you want to cast some spell repeatedly, you can use macro
such that;

A:"X:avoid_abort\rR\rmbc"Y:avoid_abort\r
P:\[F1]

When you press the F1 repeatedly, your character cast spell "c" of
spellbook "b", and rest to restore mana, and repeat.  "X:avoid_abort"
is needed because the Rest command will usually be stopped by any key
input.

An explanation of 'avoid_abort' option is found the section on
Efficiency Options (see option.txt#Efficiency [b])
***** [b] option.txt#Efficiency


***** <Autopick>
==== Object Auto-picker/Destroyer ====

Hengband can automatically pick up or destroy specified objects when
you write objects name in the file "pickpref.prf" or
"pickpref-<<playername>>.prf" in the user directory, this will be
~/.angband/Hengband/ for UNIX, or Hengband\lib\user\ for other
operating systems.

The game will read the file "pickpref-<<playername>>.prf" first and
then read the file "pickpref.prf".  The first-read file takes
priority.

You may use the '$' command within the game to reread auto-picker
files.

Notes:
Maximum number of active lines is 1009.
A line with a header '#' is a comment.

--- Editing the file ---

Command letter:

       Each line determines the actions taken when you step over a
  kind of object.  Starting a line with '!' indicates that you wish to
  destroy this kind of object.  Starting a line with '~' indicates
  that you wish to leave this kind of object on the floor.  Otherwise,
  your character will automatically attempt to pick up the object.
       There is an additional command letter '('.  It indicates that
  you don't wish this item to be displayed in full map. see below.

  Notes:
  If you want to disable the effect of the '!' indicator temporally,
  use 'always_pickup' option.


Keywords:
       After the command letter may come one or more keywords.  They are:

  all               : All items match.
  collecting        : Matches if you already have that same item.
  unidentified      : Unidentified items match.
  identified        : Identified items match.
  *identified*      : *Identified* items match.
  dice boosted      : Weapons with boosted damage dice match.
  more than N dice  : Weapons with dice (dd * ds) better than +N match.
  more bonus than N : Items which has more magical bonus than (+N) match.
  worthless         : Items which you cannot sell match.
  artifact          : Artifacts items match.
  ego               : Ego items match.
  nameless          : Non ego/non artifact items match.
  unaware           : Items with unknown effects match.
  wanted            : Wanted monster's corpses or skeletons match.
  unique monster's  : Unique monster's corpses, skeletons or statues match.
  human             : Human corpses or skeletons match.
  unreadable        : Spellbooks other than those you can read match.
  first realm's     : Your first magic realm's spellbooks match.
  second realm's    : Your second magic realm's spellbooks match.
  first             : First one of four spellbooks in each realm match.
  second            : Second one of four spellbooks in each realm match.
  third             : Third one of four spellbooks in each realm match.
  fourth            : Fourth one of four spellbooks in each realm match.

  items             : All items match. Use it with an adjective for 
                      readability (i.e. "unaware items").
  weapons           : All weapons including missile weapons match.
  armors            : All armors match.
  missiles          : Arrows, bolts, and shots match.
  magical devices   : Wands, staffs, rods and scrolls match.
  lights            : Light sources match.
  junks             : Junk items like Shard of Pottery or etc. match.
  spellbooks        : All books match.
  hafted weapons    : Hafted weapons match. For priests.

  You may also use keywords which match specified kinds of equipment:
  weapons, armors, missiles, magical devices, lights, junks, spellbooks, 
  hafted weapons, shields, bows, rings, amulets, suits, cloaks, helms, 
  gloves, boots


Character strings:
       After the keywords, you may write a character string. Only items 
  whose name contains this character string as part of their name match. 
  Upper or lower case makes no difference.
       You must insert a ':' between your special keywords and character 
  string, if both exist in one line.

Force start-of-line matching:
  If the first character in a character string is '^', then the 
  character string must match the beginning of a line.

!Mace           // Destroy Maces and Lead-Filled Maces.
!^Mace          // Destroy only Maces.


Examples:

!worthless items
Meaning:  "destroy all items that are worthless"

unaware potion
Meaning:  "pick up all unaware potions"

~unidentified lites
Meaning:  "leave all unidentified light sources on the ground"

unidentified more than 25 dice weapons
Meaning:  "pick up all weapons with dice that total more than 25.  A 
     weapon that is 2d13 qualifies, a weapon that is 5d5 does not."

Acquirement
Meaning:  "pick up anything that includes in its name the word 
'Acquirement'"

potion of Experience
Meaning:  "pick up anything named 'potion of experience'"

Lights:stone
Meaning:  "Pick up light sources named stone"

gloves:slaying
Meaning:  "Pick up gauntlets of slaying. Not rings of slaying."


Special Notes:

  Lines will be evaluated in order, and first matched line will be 
  applied. So you can write names of specific excellent items to pick 
  up, followed by a general item name with '!' to destroy useless items.

  ! Tips
  !     In full map command ('M'), you can press M, N, K, or D to 
  ! display locations of items for auto-pickup, leaving, auto-destroy 
  ! or both auto-pickup and leaving.
  !     Additional command letter '(' prevents this display.
  !

  If you begin the last string in a line with '#', this string will
  be automatically inscribed on the item.


  Strict syntax of each line is below.
  
  [! ~ (]
  [[all] [collecting] [unidentified] [identified] [*identified*] 
   [dice boosted] [more than N dice] [more bonus than N] 
   [worthless] [artifact] [ego] [nameless] [unaware] 
   [wanted] [unique monster's] [human] [unreadable] 
   [first realm's] [second realm's] [first] [second] [third] [fourth] 
   [items | weapons | armors | missiles | magical devices | 
    lights | junks | spellbooks | hafted weapons | shields | bows | 
    rings | amulets | suits | cloaks | helms | gloves | boots] :]
  [[^]part-of-item-name] [#auto-inscription-string]


=======  How to use Conditional Expressions  ========

  The lines of pickpref.prf can be disabled/enabled using 
  conditional expressions. 
  The syntax is the same as that of other preference files.

  - usage of condition expressions
    ?:expr
      If result of expr is "0", all lines below are disabled.
      If result of expr is "1", all lines below are enabled.
      Caution:It cannot be nested.

  - usage to include other file
    %:filename
      Read a file named 'filename' as a new pick-pref file. The file 
      must be in the user directory.
      Caution: Avoid naming the parent file, or the game might freeze up.

  - usage of operators
    [EQU arg1 arg2 ...]
      If all args are same, returns "1", or else returns "0".
    [IOR arg1 arg2 ...]
    [AND arg1 arg2 ...]
      IOR evaluates and returns all args' logical OR. IAND is logical AND.
    [NOT arg]
      Returns "0" if arg is "1", or else returns "1"
    [LEQ arg1 arg2 ...]
    [GEQ arg1 arg2 ...]
      Compare args as string. LEQ returns "1" if (arg1 <= arg2 <= ...) ,
      GEQ returns "1" if (arg1 >= arg2 >= ...) otherwise returns "0".

  - Special variables
    $RACE
     Returns name of player race. One of below:
      Human, Half-Elf, Elf, Hobbit, Gnome, Dwarf, Half-Orc,
      Half-Troll, Amberite, High-Elf, Barbarian, Half-Ogre,
      Half-Giant, Half-Titan, Cyclops, Yeek, Klackon, Kobold,
      Nibelung, Dark-Elf, Draconian, Mindflayer, Imp, Golem,
      Skeleton, Zombie, Vampire, Spectre, Sprite, Beastman, Ent,
      Archon, Balrog, Dunadan, Shadow-Fairy, Kutar, Android,

    $CLASS
     Returns name of player class. One of below:
      Warrior, Mage, Priest, Rogue, Ranger, Paladin,
      Warrior-Mage, Chaos-Warrior, Monk, Mindcrafter, High-Mage,
      Tourist, Imitator, BeastMaster, Sorcerer, Archer,
      Magic-Eater, Bard, Red-Mage, Samurai, ForceTrainer,
      Blue-Mage, Cavalry, Berserker, Weaponsmith, Mirror-Master,
      Ninja

    $PLAYER
     Returns player name.
    $REALM1
     Returns player's first magic realm
      none, Life, Sorcery, Nature, Chaos, Death, Trump Arcane,
      Craft, Daemon, Crusade, Music, Kendo
    $REALM2
     Returns player's second magic realm
    $LEVEL
     Returns player level as two-character string.
      Ex. "01","09","10","50" etc.

###############################################################
###############################################################
---------------------------------------------------------------

 There is an example 'pickpref.prf' file below.
 You can copy this file to lib\user\ or ~/.angband/Hengband/.
 (UNIX user must copy to ~/.angband/Hengband/. Others must copy 
 to  lib\user\ .)

---------------------------------------------------------------
###############################################################
###############################################################

wanted corpse
wanted Skeleton

# Berserker cannot use magical devices; rods, wands, and scrolls.
?:[EQU $CLASS Berserker]
!magical devices
?:1

unaware items

#Artifact lights
unidentified lights:^Jewel#!!
unidentified lights:^levitation stone#!!
unidentified lights:^Palantir#!!
unidentified lights:^stone#@A0
unidentified lights:^star#!!
unidentified lights:^Incandescent Light
unidentified lights:^Phial#!!

# auto inscribe resistances (see lib/help/objects.txt#Inscriptions)
~*identified* artifacts#%all

#
# pick all items which can stack your inventory without inscription.
#
collecting rod
collecting potion
collecting scroll
collecting missiles
(collecting items

#
# good items
#
~rod of Perception#@z0!k!!
~rod of speed#!k!!
~rod of Healing#!k!!
~rod of Enlightenment#k!!
~rod of Detection#!k!!

potion of Invulnerability#!k
Acquirement#!k
potion of Experience
potion of Augmentation
*Destruction*
Genocide

potion of strength
potion of wisdom
potion of dexterity
potion of constitution
potion of intelligence
potion of Charisma

potion of life#!k
healing#!k

#
# Magic-Eaters pick up all magical device to absorb.
# Skeletons is material of missiles for Archers.
# Ninja needs lights of darkness.
# Vampire needs darkness.
# 
?:[EQU $CLASS Magic-Eater]
rod of 
staff of 
wand of 
?:[EQU $CLASS Archer]
skeleton of 
?:[EQU $CLASS Ninja]
~lights:darkness
Iron Spike#@v0
?:[EQU $RACE Vampire]
(~scroll of darkness
(~staff of darkness
?:1

# Destroy unless very early stage.
?:[GEQ $LEVEL 10]
(!amulet of Adornment
(!potion of Apple Juice
(!Empty Bottle
(!potion of water
?:1

# These worthless potions have some use at very early stage.
# Command letter '(' means, 'Don't display its location in full map command.'
?:[LEQ $LEVEL 20]
(~potion of booze
(~potion of Slowness
(~potion of Sleep
?:1

# complex example; destroy needless food items.
?:[AND [GEQ $LEVEL 20] [IOR [EQU $REALM1 Life] [EQU $REALM2 Life] [EQU $REALM1 Nature] [EQU $REALM2 Nature] [EQU $REALM1 Craft] [EQU $REALM2 Craft]]]
(!Satisfy Hunger
(!food
(!Slime Mold
(!of Elvish Waybread
?:1


#
# Destroy useless equipment at high level.
#
# Beware!!!!
#    The line '!nameless armors' destroy all dragon armour!
#    '~identified armors:dragon' will prevent this dangerous behavior.
#

?:[GEQ $LEVEL 40]
~identified armors:dragon
~nameless armors:Elven Cloak
~nameless armors:Shadow Cloak
~nameless weapons:Diamond Edge
~nameless weapons:Mace of Disruption
~nameless weapons:Shield of Deflection
!nameless weapons
!nameless armors

?:[GEQ $LEVEL 20]
!nameless weapons:) (+0,+0)
!nameless armors:,+0]
?:1

# higher rank of your spellbooks
first realm's fourth Book of Kendo#!k
first realm's third Book of Kendo#!k
first realm's fourth spellbooks#@md!k
first realm's third spellbooks#@mc!k
second realm's fourth spellbooks#@mh!k
second realm's third spellbooks#@mg!k

# unidentified equipment
unidentified dice boosted weapons
unidentified more than 25 dice weapons
unidentified weapons
unidentified armors
~unidentified missiles

# lower rank of your spellbooks
collecting spellbooks
~first realm's second spellbooks#@mb!k
~first realm's first spellbooks#@ma!k
~second realm's second spellbooks#@mf!k
~second realm's first spellbooks#@me!k

# other spellbooks

?:[GEQ $LEVEL 30]
(!unreadable first spellbooks
(!unreadable second spellbooks
(!unreadable third spellbooks:arcane
(!unreadable fourth spellbooks:arcane
?:1

# pick up for experience
?:[IOR [EQU $CLASS Warrior] [EQU $CLASS Berserker] [AND [EQU $CLASS Paladin] [EQU $REALM1 Life]]]
(~unreadable third spellbooks:arcane
(~unreadable fourth spellbooks:arcane
unreadable fourth spellbooks
unreadable third spellbooks
?:1
?:[AND [EQU $CLASS Paladin] [EQU $REALM1 Death]]
unreadable fourth spellbooks:life
unreadable third spellbooks:life
?:1

# pick up for money
?:[LEQ $LEVEL 29]
(~unreadable third spellbooks:arcane
(~unreadable fourth spellbooks:arcane
unreadable fourth spellbooks
unreadable third spellbooks
?:1

############################################################
 

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
Updated    : Hengband 1.0.11
