Information about options, usage of extra windows, colors and symbols, and macros can all be stored in preference files. In addition, you can customize the game in many other ways and save these preferences to file.

The priority order of preference files

Whenever the game starts up, and whenever it creates or loads a character, it opens various preference files and modifies various things according to instructions in them. The preference files below are listed in descending order of priority: anything in higher files overrides anything in a file below it.

1. lib/user/base name of character.prf

   May contain options, color definitions, attr/char remappings (what monsters, objects, and features look like), and many other things. Anything in this file is guaranteed to override anything in any other file.

   What is the "base name" of your character? It is the name of your character, usually with non-alphabetic, non-numeric characters translated to '_'s, and (on IBM/DOS) shortened to eight characters. You may check the base name by trying to save macros or keymaps.

   XXX javascript here

2. lib/user/character race.prf

   Any preferences that you want to apply to all characters of a given race should go here.

3. lib/user/character class.prf

   Any preferences that you want to apply to all characters of a given class should go here.

4. lib/user/user.prf

   Any preferences that you want to apply to all of your characters should go here.

5. lib/pref/user.prf

   This file is loaded just before the one above it. Links to system-specific user-preference files, which tend to be used by porters to customize the game in ways that they think users of their system will appreciate. For example, "user- mac.prf" includes a bunch of extra macros.

6. Your character's savefile

   Always contains your current options and window settings. Never contains macros, keymaps, or visual preferences (these all need to be saved in an external file).

Many players need no other preference files and can stop reading here.

"lib/pref/font.prf": The basic text-mode preference file.

  Links to font.xxx.prf, which defines the exact colors for all spells and

objects in text mode, and contains the default colors used to display object descriptions in inventory (wizard books are light red, priest books are light green, etc.).

  Also links to system-specific text-mode preference files (font-ibm.prf,

font-win.prf, etc.). Each of these files assigns new text-mode characters and attributes (colors) for objects, monsters, features, etc. For example, "font- ibm.prf" changes dungeon walls from '#'s to solid blocks.

"lib/pref/flvr-xxx.prf": graphics for individual flavors of objects.

  Links to flvr-new.prf, which handles Adam Bolt's 16x16 graphics, and to

flvr-dvg, which handles David Gervais's 32x32 graphics.

"lib/pref/graf.prf": The basic graphics-mode preference file.

  Links to font.xxx.prf (but later overrides a lot of the information it

contains).

  Also links to system-specific graphics-mode preference files, all of which

then link to one of two files: graf-xxx.prf: The preference file used for 8x8 graphics.

  Each color of objects and spell effects, and each individual terrain and

monster, are assigned their own graphical representation. graf-new.prf: The preference file used for Adam Bolt's 16x16 graphics. graf-dvg.prf: The preference file used for David Gervais's 32x32 graphics.

"lib/pref/pref.prf":

  This is the source of most default settings except for char/attr

remappings. It contains the default values of options and the keymaps for the original and roguelike keysets. Links to the file "message.prf", which controls the colors of messages. Links to system-specific general preference files (pref-x11.prf, pref-gcu.prf, etc.). These contain system-specific keymappings and allow the game to recognize your keyboard.

message.prf: Message colors.

  Each message can be assigned to a type; each type may have one or more

sounds and a color associated with it.

Writing your own preference files

All preference files use a common system to store information. You must be careful of two things:

1. Make sure that the file will actually be loaded. It needs to be one of the files mentioned above, or be called by one of those files.
2. Watch out for automatic preference dumps. If you try to edit anything between the special markers, your changes will be lost. The solution is to skip past all the automatic stuff, and put your changes at the bottom, below the last marker.

List of preference file instructions

%:human.prf : open up the file "lib/pref/human.prf" or "lib/user/human.prf"

  and read it.  If both files exist, rules in the latter takes priority.

R:0:w/@ : The monster, with index 0 (zero), will be white ('w'),

  and be represented with a '@'.

R:0:0x8C/0x80 : The monster, with index 0 (zero), will get the graphical

  tile at position (0x8C - 0x80), (0x80 - 0x80) = row 12, column 0.  Note
  that values above 0x7F (127) indicate the use of graphics.

K:50:v/~ : The object, with index 50, will be violet ('v'), and be

  represented with a '~'.

K:50:0x83/0x96 : The object, with index 50, will get the graphical

  tile at position (0x83 - 0x80), (0x96 - 0x80) = row 3, column 22.

F:1:1/249 : The feature, with index 1, will be white (color 1), and

  be represented by the character in ASCII position 249 (a centered dot)

S:0xB1:0x01/0x2D : Index B1 (177) of the flavor table will contain the color

  1 (white) and the character in ASCII position 45 ('-').  A detailed
  look at how the flavor table works is beyond the scope of this document;
  suffice it to say that all characters used to display spell effects, and
  all object kinds with flavors, get 16 entries in the flavor table, one
  for each color.

E:90:0x0C : Tval 90 (magic books) will display in the inventory and

  various listing as color 0x0C (light red).

A:R*\r : The next key listed will be mapped to this set of

  actions (can be either a keymap or a macro).

C:0:x : The previous action listed is a keymap, is active in the

  original keyset (set 0), and will be activated by typing 'x'.

P:1:^O : The previous action listed is a macro, is active in the

  roguelike keyset (set 1), and will be activated by typing control-'O'.

V:1:0x00:0xff:0xff:0xff : The color in position 1 (white), will have a

  special value of 0x00 (zero), a red-value of 0xff (255), a green-value
  of 0xff, and a blue-value of 0xff.

X:rogue_like_commands : The "rogue_like_commands" option will be off.

Y:rogue_like_commands : The "rogue_like_commands" option will be on.

W:2:6:1 : Window 2 (the third one), will display window display #6

  (display messages), and be active (1) as opposed to inactive (0).

M:1:w : Message type 1 (standard hit message) will appear white.

D:4 : The delay factor will be 4 (squared).

H:3 : The hitpoint warning will be at 30%.

?:<<text>> : A conditional expression. If true, allows another

  line to activate.  The tests include:
  AND     - logical AND
  IOR     - inclusive OR
  EQU     - (string) equals
  NOT     - logical negation
  LEQ     - (string) less than or equal to
  GEQ     - (string) greater than or equal to
  [,]     - group expressions
  $CLASS  - current class
  $GRAF   - 3-letter graphics abbr in "graf-***.prf" (old, new)
  $PLAYER - current player name
  $RACE   - current race
  $CLASS  - current class
  $SYS    - 3-letter system abbr in "pref-***.prf" (ami, mac, win,...)
            See the usage in "lib/pref/pref.prf", etc.

Visuals, colors, and multimedia

Interact with Visuals: (command: '%')

You may adjust the character and attribute (color) used to display objects, monsters, and terrain features.

  1) Update your preferences with a specific user preference file.
  2) Save your current monster visuals to file.
  3) Save your current object visuals to file.
  4) Save your current terrain visuals to file.
  %) Save your current flavor preferences to file.
  6) Change monster visuals.
  7) Change object visuals.
  8) Change terrain visuals.
  9) Change the symbol and flavor used for many kinds of objects.
  0) Reset visuals to their last saved values (undo all changes).

  When changing visuals, you may type the following keys:
  n: advance one (wrap around if at the end)
  N: go back one (wrap around if at the beginning)
  a: change to the next color (wrap around if at color 15)
  A: change to the previous color (wrap around if at color 0)
  c: change to the next character in the ASCII sequence (wrap around at 255)
  C: change to the previous character (wrap around if at 0)

  A good way to get used to the interface is to choose option 6:  change

monster visuals, note that the first "monster" is your character, and change it from a white '@' to something silly. Leave, see how weird you look, come back, and (if you like) press '0' to reset the visuals.

  Remember to type Control-R after making any changes.

Interact with colors: (command '&') :

  In the interact with colors display, you have three options available:
  1) Update your preferences with a specific user preference file.
  2) Save your colors to file.
  3) Modify colors.

  When changing colors, you may issue the following commands:
  n: go to the next color (wraps around at 255)
  N: go back one (wrap around if at 0)
  k: change a value (possibly the gamma correction?)
  K: change a value (possibly the gamma correction?)
  r: increase the red in this color (wraps around at hex value 0xff)
  R: decrease the red in this color (wraps around at hex value 0x00)
  g: increase the green in this color (wraps around at hex value 0xff)
  G: decrease the green in this color (wraps around at hex value 0x00)
  b: increase the blue in this color (wraps around at hex value 0xff)
  B: decrease the blue in this color (wraps around at hex value 0x00)

  Note that, while the game is theoretically capable of using more than 16

colors, it is not currently set up to do so. Also, color 0 should not be changed.

  Remember to type Control-R after making any changes.

Interact with multimedia: (command '!') :

  Some ports of this game (but not all) will play sounds and music.  If your

port is one of them, you can adjust volumes, turn sounds off and on entirely, and tweak various other things.