1 === User Pref Files ===
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).
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.
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.
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.
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.
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.
59 --- User pref file commands ---
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.
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.
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. You must use the "redraw"
80 command (^R) to redraw the map after changing attr/char mappings.
82 Interact with colors (&)
83 Allow the user to interact with colors. This command only
84 works on some systems.
86 Reload auto-picker/destroyer preference ($)
87 This command will reload "pickpref.prf" and
88 "pickpref-<<playername>>.prf" for object auto-picker/destroyer
89 after you edit these files with your text editor.
91 Edit auto-picker/destroyer pref (_)
92 Allow the user to edit the pickpref-<player's name>.prf in the
93 user directory. Basic usage of the editor is almost same as vi,
94 and also have emacs like commands. Most commands is always
95 displayed on the first line and the right half of the screen.
98 'a', 'i' or ^Q : Enter insert mode from command mode
99 ESC or ^Q : Return to command mode from insert mode
100 'q' : Quit the editor (command mode only)
101 'hjkl2468' : Move cursor (command mode only)
102 ^B ^N ^P ^F : Move cursor (always)
103 ^I : Choose an item from inventory/equipment, then insert its name
104 ^S : Rotates action (pick up / destroy / leave on floor)
105 ^U : Rotates identify state (identified / unidentified / ...)
109 --- User Pref Files (Macros) ---
111 The "Interact with macros" command allows you to define or remove
112 "macros", which are mappings from a single logical keypress to a
113 sequence of keypresses, allowing you to use special keys on the
114 keyboard, such as function keys or keypad keys, possibly in conjunction
115 with modifier keys, to "automate" repetitive multi-keypress commands
118 Since macros represent keypress sequences, and not all keypresses have
119 a printable representation, macro triggers and actions must often be
120 "encoded" into a human readable form. This is done using several types
121 of encoding, including "\xHH" for character number HH in hexadecimal,
122 "\e" for the "escape" code, "\n" for the "newline" code, "\r" for the
123 "return" code, "\s" for the "space" code, "\\" for backslash, "\^" for
124 caret, and "^X" for the code for any "control" key "ctrl-X".
126 In Hengband, name of special keys as macro-trigger is displayed using
127 its real name, for example the Control-key plus the F1-key is
128 displayed as "\[control-F2]", and the Alt-key plus the G is displayed
129 as "\[Alt-G]". In other variant these special keys will be, currently,
130 displayed using its key-code.
132 Note that the "action" of a macro will not be checked against other
133 macro triggers, so you cannot make infinite loops. You may specify
134 extremely long macros, but you are limited in length by the underlying
135 input mechanisms, which in general limit you to about 1024 keys in
136 both triggers and actions.
138 The special "\" command (which must be encoded in macros as "\\") is
139 very useful in macros, since it bypasses all keymaps and allows the
140 next keystroke to be considered a command in the underlying Hengband
141 command set. For a list of the Hengband command set, see the
142 "command.txt" help file. For example, a macro which maps Shift-KP6 to
143 "\" + "." + "6" will induce the "run east" behavior, regardless of what
144 keyset the user has chosen, and regardless of what keymaps have been
147 Macros can be specified in user pref files as a pair of lines, one of
148 the form "A:<str>", which defines the encoded macro action, and one of
149 the form "P:<str>", which defines the encoded macro trigger.
153 --- User Pref Files (Keymaps) ---
155 The "Interact with macros" command also allows you to define "keymaps",
156 which are vaguely related to macros. A keymap maps a single keypress to
157 a series of keypresses, which bypass both other keymaps and any macros.
158 Hengband uses keymaps to map the original and the roguelike keysets to
159 the underlying command set, and allows the user to modify or add
160 keymaps of their own. Note that all keymap actions must be specified
161 using underlying commands, not keypresses from the original or
162 roguelike keysets. The original keyset is almost identical to the
163 underlying keyset, except that "numbers" are mapped to ";" plus a
164 direction, "5" is mapped to ",", and a few control-keys are mapped to
165 various things. See "command.txt" for the full set of underlying
166 commands. Some uses for keymaps include the ability to "disable" a
167 command by mapping it to "\x00".
169 Keymaps can be specified in user pref files as pairs of lines of the
170 form "A:<str>" "C:<T>:<key>", where <str> is the encoded keymap
171 action, <T> is the keyset (0 for original and 1 for roguelike), <key>
172 is the encoded trigger key.
176 --- User Pref Files (Visuals) ---
178 You can use the "Interact with visuals" command to change various
179 visual information, currently including the choice of what attr/char
180 values are used to represent various monsters, objects, or terrain
181 features. Note that in combination appropriate support in "main-xxx.c",
182 and with the use of the "use_graphics" flag, you may be able to specify
183 that "graphic bitmaps" should be used instead of normal "colored
184 characters" for various things.
186 When interactively modifying the attr/char values for monsters,
187 objects, or terrain features, pressing "n" or "N" will change which
188 entry you are changing, pressing "a" or "A" will rotate through the
189 available attr values, and pressing "c" or "C" will rotate though the
190 available char values, and pressing "^N", "^A", and "^C" will let you
191 directly enter a number and set the entry, attr or char value to that
192 number. Note that attr/char values with the "high bit" set may induce
193 the display of special "graphic" pictures if the "use_graphics" flag
194 is set, and your system supports the "use_graphics" flag.
196 Note that this command can be abused in various ways, and if you must
197 do so, remember that you are only cheating yourself.
199 Visuals can be modified in user pref files as lines of the form
200 "R:<N>:<A>/<C>" or "K:<N>:<A>/<C>" or "F:<N>:<A>/<C>".
204 --- User Pref Files (Colors) ---
206 The "Interact with colors" command allows you to change the actual
207 internal values used to display various colors. This command may or may
208 not have any effect on your machine. Advanced machines may allow you to
209 change the actual RGB values used to represent each of the 16 colors
210 used by Hengband, and perhaps even allow you to define new colors which
211 are not currently used by Hengband.
213 Colors can be specified in user pref files as lines of the form
214 "V:<N>:<V>:<R>:<G>:<B>".
218 --- User Pref Files (Options) ---
220 The "Interact with options" command allows you to turn options on or
221 off. You may turn options off or on using the user pref commands of the
222 form "X:<option>" or "Y:<option>" respectively.
224 This method of preference line might be useful in the macro. For
225 example, if you want to cast some spell repeatedly, you can use macro
228 A:"X:avoid_abort\rR\rmbc"Y:avoid_abort\r
231 When you press the F1 repeatedly, your character cast spell "c" of
232 spellbook "b", and rest to restore mana, and repeat. "X:avoid_abort"
233 is needed because the Rest command will usually be stopped by any key
236 An explanation of 'avoid_abort' option is found the section on
237 Efficiency Options (see option.txt#Efficiency [b])
238 ***** [b] option.txt#Efficiency
242 ==== Object Auto-picker/Destroyer ====
244 Hengband can automatically pick up or destroy specified objects when
245 you write objects name in the file "pickpref.prf" or
246 "pickpref-<<playername>>.prf" in the user directory, this will be
247 ~/.angband/Hengband/ for UNIX, or Hengband\lib\user\ for other
250 The game will read the file "pickpref-<<playername>>.prf" first and
251 then read the file "pickpref.prf". The first-read file takes
254 You may use the '$' command within the game to reread auto-picker
258 Maximum number of active lines is 1009.
259 A line with a header '#' is a comment.
261 --- Editing the file ---
265 Each line determines the actions taken when you step over a kind
266 of object. Starting a line with '!' indicates that you wish to
267 destroy this kind of object. Starting a line with '~' indicates
268 that you wish to leave this kind of object on the floor. Starting a
269 line with ';' indicates that you wish to force the game to ask you
270 if you want to pick the item up or not. Otherwise, your character
271 will automatically attempt to pick up the object.
272 There is an additional command letter '('. It indicates that
273 you don't wish this item to be displayed in full map. see below.
276 If you want to disable the effect of the '!' indicator temporally,
277 use 'always_pickup' option.
281 After the command letter may come one or more keywords. They are:
283 all : All items match.
284 collecting : Matches if you already have that same item.
285 unaware : Items with unknown effects match.
286 unidentified : Unidentified items match.
287 identified : Identified items match.
288 *identified* : *Identified* items match.
289 dice boosted : Weapons with boosted damage dice match.
290 more than N dice : Weapons with dice (dd * ds) better than +N match.
291 more bonus than N : Items which has more magical bonus than (+N) match.
292 worthless : Items which you cannot sell match.
293 artifact : Artifacts items match.
294 ego : Ego items match.
295 nameless : Non ego/non artifact items match.
296 wanted : Wanted monster's corpses or skeletons match.
297 unique monster's : Unique monster's corpses, skeletons or statues match.
298 human : Human corpses or skeletons match.
299 unreadable : Spellbooks other than those you can read match.
300 first realm's : Your first magic realm's spellbooks match.
301 second realm's : Your second magic realm's spellbooks match.
302 first : First one of four spellbooks in each realm match.
303 second : Second one of four spellbooks in each realm match.
304 third : Third one of four spellbooks in each realm match.
305 fourth : Fourth one of four spellbooks in each realm match.
307 items : All items match. Use it with an adjective for
308 readability (i.e. "unaware items").
309 weapons : All weapons including missile weapons match.
310 armors : All armors match.
311 missiles : Arrows, bolts, and shots match.
312 magical devices : Wands, staffs, rods and scrolls match.
313 lights : Light sources match.
314 junks : Junk items like Shard of Pottery or etc. match.
315 spellbooks : All books match.
316 hafted weapons : Hafted weapons match. For priests.
318 You may also use keywords which match specified kinds of equipment:
319 weapons, armors, missiles, magical devices, lights, junks, spellbooks,
320 hafted weapons, shields, bows, rings, amulets, suits, cloaks, helms,
325 After the keywords, you may write a character string. Only items
326 whose name contains this character string as part of their name match.
327 Upper or lower case makes no difference.
328 You must insert a ':' between your special keywords and character
329 string, if both exist in one line.
331 Force start-of-line matching:
332 If the first character in a character string is '^', then the
333 character string must match the beginning of a line.
335 !Mace // Destroy Maces and Lead-Filled Maces.
336 !^Mace // Destroy only Maces.
342 Meaning: "destroy all items that are worthless"
345 Meaning: "pick up all unaware potions"
348 Meaning: "leave all unidentified light sources on the ground"
350 unidentified more than 25 dice weapons
351 Meaning: "pick up all weapons with dice that total more than 25. A
352 weapon that is 2d13 qualifies, a weapon that is 5d5 does not."
355 Meaning: "pick up anything that includes in its name the word
359 Meaning: "pick up anything named 'potion of experience'"
362 Meaning: "Pick up light sources named stone"
365 Meaning: "Pick up gauntlets of slaying. Not rings of slaying."
370 Lines will be evaluated in order, and first matched line will be
371 applied. So you can write names of specific excellent items to pick
372 up, followed by a general item name with '!' to destroy useless items.
375 ! In full map command ('M'), you can press M, N, K, or D to
376 ! display locations of items for auto-pickup, leaving, auto-destroy
377 ! or both auto-pickup and leaving.
378 ! Additional command letter '(' prevents this display.
381 If you begin the last string in a line with '#', this string will
382 be automatically inscribed on the item.
385 Strict syntax of each line is below.
389 [unaware] [unidentified] [identified] [*identified*]
390 [dice boosted] [more than N dice] [more bonus than N]
391 [worthless] [artifact] [ego] [nameless]
392 [wanted] [unique monster's] [human] [unreadable]
393 [first realm's] [second realm's] [first] [second] [third] [fourth]
394 [items | weapons | armors | missiles | magical devices |
395 lights | junks | spellbooks | hafted weapons | shields | bows |
396 rings | amulets | suits | cloaks | helms | gloves | boots] :]
397 [[^]part-of-item-name] [#auto-inscription-string]
400 ======= How to use Conditional Expressions ========
402 The lines of pickpref.prf can be disabled/enabled using
403 conditional expressions.
404 The syntax is the same as that of other preference files.
406 - usage of condition expressions
408 If result of expr is "0", all lines below are disabled.
409 If result of expr is "1", all lines below are enabled.
410 Caution:It cannot be nested.
412 - usage to include other file
414 Read a file named 'filename' as a new pick-pref file. The file
415 must be in the user directory.
419 If all args are same, returns "1", or else returns "0".
422 IOR evaluates and returns all args' logical OR. IAND is logical AND.
424 Returns "0" if arg is "1", or else returns "1"
427 Compare args as string. LEQ returns "1" if (arg1 <= arg2 <= ...) ,
428 GEQ returns "1" if (arg1 >= arg2 >= ...) otherwise returns "0".
432 Returns name of player race. One of below:
433 Human, Half-Elf, Elf, Hobbit, Gnome, Dwarf, Half-Orc,
434 Half-Troll, Amberite, High-Elf, Barbarian, Half-Ogre,
435 Half-Giant, Half-Titan, Cyclops, Yeek, Klackon, Kobold,
436 Nibelung, Dark-Elf, Draconian, Mindflayer, Imp, Golem,
437 Skeleton, Zombie, Vampire, Spectre, Sprite, Beastman, Ent,
438 Archon, Balrog, Dunadan, Shadow-Fairy, Kutar, Android,
441 Returns name of player class. One of below:
442 Warrior, Mage, Priest, Rogue, Ranger, Paladin,
443 Warrior-Mage, Chaos-Warrior, Monk, Mindcrafter, High-Mage,
444 Tourist, Imitator, BeastMaster, Sorcerer, Archer,
445 Magic-Eater, Bard, Red-Mage, Samurai, ForceTrainer,
446 Blue-Mage, Cavalry, Berserker, Weaponsmith, Mirror-Master,
452 Returns player's first magic realm
453 none, Life, Sorcery, Nature, Chaos, Death, Trump Arcane,
454 Craft, Daemon, Crusade, Music, Kendo
456 Returns player's second magic realm
458 Returns player level as two-character string.
459 Ex. "01","09","10","50" etc.
461 ###############################################################
462 ###############################################################
463 ---------------------------------------------------------------
465 There is an example 'pickpref.prf' file below.
466 You can copy this file to lib\user\ or ~/.angband/Hengband/.
467 (UNIX user must copy to ~/.angband/Hengband/. Others must copy
470 ---------------------------------------------------------------
471 ###############################################################
472 ###############################################################
477 # Berserker cannot use magical devices; rods, wands, and scrolls.
478 ?:[EQU $CLASS Berserker]
485 unidentified lights:^Jewel#!!
486 unidentified lights:^levitation stone#!!
487 unidentified lights:^Palantir#!!
488 unidentified lights:^stone#@A0
489 unidentified lights:^star#!!
490 unidentified lights:^Incandescent Light
491 unidentified lights:^Phial#!!
493 # auto inscribe resistances (see lib/help/objects.txt#Inscriptions)
494 ~*identified* artifacts#%all
497 # pick all items which can stack your inventory without inscription.
508 ~rod of Perception#@z0!k!!
511 ~rod of Enlightenment#k!!
512 ~rod of Detection#!k!!
514 potion of Invulnerability#!k
517 potion of Augmentation
524 potion of constitution
525 potion of intelligence
532 # Magic-Eaters pick up all magical device to absorb.
533 # Skeletons is material of missiles for Archers.
534 # Ninja needs lights of darkness.
535 # Vampire needs darkness.
537 ?:[EQU $CLASS Magic-Eater]
541 ?:[EQU $CLASS Archer]
546 ?:[EQU $RACE Vampire]
551 # Destroy unless very early stage.
553 (!amulet of Adornment
554 (!potion of Apple Juice
559 # These worthless potions have some use at very early stage.
560 # Command letter '(' means, 'Don't display its location in full map command.'
567 # complex example; destroy needless food items.
568 ?:[AND [GEQ $LEVEL 20] [IOR [EQU $REALM1 Life] [EQU $REALM2 Life] [EQU $REALM1 Nature] [EQU $REALM2 Nature] [EQU $REALM1 Craft] [EQU $REALM2 Craft]]]
577 # Destroy useless equipment at high level.
580 # The line '!nameless armors' destroy all dragon armour!
581 # '~identified armors:dragon' will prevent this dangerous behavior.
585 ~identified armors:dragon
586 ~nameless armors:Elven Cloak
587 ~nameless armors:Shadow Cloak
588 ~nameless weapons:Diamond Edge
589 ~nameless weapons:Mace of Disruption
590 ~nameless weapons:Shield of Deflection
595 !nameless weapons:) (+0,+0)
596 !nameless armors:,+0]
599 # higher rank of your spellbooks
600 first realm's fourth Book of Kendo#!k
601 first realm's third Book of Kendo#!k
602 first realm's fourth spellbooks#@md!k
603 first realm's third spellbooks#@mc!k
604 second realm's fourth spellbooks#@mh!k
605 second realm's third spellbooks#@mg!k
607 # unidentified equipment
608 unidentified dice boosted weapons
609 unidentified more than 25 dice weapons
612 ~unidentified missiles
614 # lower rank of your spellbooks
615 collecting spellbooks
616 ~first realm's second spellbooks#@mb!k
617 ~first realm's first spellbooks#@ma!k
618 ~second realm's second spellbooks#@mf!k
619 ~second realm's first spellbooks#@me!k
624 (!unreadable first spellbooks
625 (!unreadable second spellbooks
626 (!unreadable third spellbooks:arcane
627 (!unreadable fourth spellbooks:arcane
630 # pick up for experience
631 ?:[IOR [EQU $CLASS Warrior] [EQU $CLASS Berserker] [AND [EQU $CLASS Paladin] [EQU $REALM1 Life]]]
632 (~unreadable third spellbooks:arcane
633 (~unreadable fourth spellbooks:arcane
634 unreadable fourth spellbooks
635 unreadable third spellbooks
637 ?:[AND [EQU $CLASS Paladin] [EQU $REALM1 Death]]
638 unreadable fourth spellbooks:life
639 unreadable third spellbooks:life
644 (~unreadable third spellbooks:arcane
645 (~unreadable fourth spellbooks:arcane
646 unreadable fourth spellbooks
647 unreadable third spellbooks
650 ############################################################
653 Original : Alexander Cutler and Andy Astrand
654 Updated : (2.7.6) by Russ Allbery (rra@cs.stanford.edu)
655 Updated : (2.7.9) by Ben Harrison (benh@phial.com)
656 Updated : Zangband 2.2.0 through 2.2.6c by Robert Ruehlmann
657 Updated : Zangband DevTeam
658 Updated : Hengband 1.0.11