Customising the game
********************

Angband allows you to change various aspects of the game to suit your
tastes.  These include:

* Options - which let you change interface or gameplay behaviour

* Ignoring items and inscribing items to change how the game treats
  them

* Showing extra info in subwindows

* Keymaps - a way to assign commonly-used actions to specific keys

* Visuals - allowing you to change the appearance of in-game entities
  like objects and monsters

* Colours - allowing you to make a given color brighter, darker, or
  even completely different

* Interface details - depending on which interface to the game you
  use, these give you control over the font, window placement, and
  graphical tile set

Except for the options, which are linked to the save file, and
interface details, that are handled by the front end rather than the
core of the game, you can save your preferences for these into files,
which are called *user pref files*.  For the options, customize those
using the "=" command while playing.


User Pref Files
===============

User pref files are Angband's way of saving and loading certain
settings.  They can store:

* Altered visual appearances for game entities

* Inscriptions to automatically apply to items

* Keymaps

* Altered colours

* Subwindow settings

* Colours for different types of messages

* What audio files to play for different types of messages

They are simple text files with an easy to modify format, and the game
has a set of pre-existing pref files in the lib/customize/ folder.
It's recommended you don't modify these.

Several options menu ("=") items allow you to load existing user pref
files, create new user pref files, or save to a user pref file.


Where to find them
------------------

On macOS, you can find them in your user directory, in
"Documents/Angband/".

On Linux, they will be stored in "~/.angband/Angband".

On Windows you can find them in "lib/user/".


How do they get loaded?
-----------------------

When the game starts up, after you have loaded or created a character,
some user pref files are loaded automatically.  These are the ones
mentioned above in the "lib/customize/" folder, namely "pref.prf"
followed by "font.prf".  If you have graphics turned on, then the game
will also load some settings from "lib/tiles/".

After these are complete, the game will try to load (in order):

* *race*.prf - where *race* is your character's race, so something
  like "Dwarf.prf"

* *class*.prf - where *class* is your character's class, so something
  like "Paladin.prf"

* *name*.prf - where *name* is your character's name, so something
  like "Balin.prf"

So, you can save some settings - for example, keymaps - to the
"Mage.prf" file if you only want them to be loaded for mages.

You may also enter single user pref commands directly, using the
special "Enter a user pref command" command, activated by pressing
""".

You may have to use the redraw command ("^r") after changing certain
of the aspects of the game to allow Angband to adapt to your changes.


Ignoring items
==============

Angband allows you to ignore specific items that you don't want to see
anymore. These items are marked 'ignored' and any similar items are
hidden from view. The easiest way to ignore an item is with the "k"
(or "^d") command; the object is dropped and then hidden from view.
When ignoring an object, you will be given a choice of ignoring just
that object, or all objects like it in some way. If you accidentally
ignore an item or find yourself in a situation where you want to see
if a previously ignored item is available nearby, one way to handle
that is to turn off ignoring for all items with the "K" (or "O")
command, go to the item you want, unignore it with the "k" (or "^d")
command, and then turn on ignoring again with the "K" (or "O")
command. When ignoring has been turned off for all items, you will see
"Unignoring" in the status line at the bottom of the screen.

The entire ignoring system can also be accessed from the options menu
("=") by choosing "i" for "Item ignoring setup".  This allows ignore
settings for non-wearable items, and quality and ego ignore settings
(described below) for wearable items, to be viewed or changed.

There is a quality setting for each wearable item type. Ignoring a
wearable item will prompt you with a question about whether you wish
to ignore all of that type of item with a certain quality setting, or
of an ego type, or both.

The quality settings are:

bad
   The weapon/armor has negative AC, to-hit or to-dam.

average
   The weapon/armor has no pluses no minuses.  It is non-magical.

good
   The weapon/armor has positive AC, to-hit or to-dam. However it does
   not have any special abilities, brands, slays, stat-boosts,
   resistances

non-artifact
   This setting only leaves artifacts unignored.


Inscribing items
================

Inscriptions are notes you can mark on objects using the "{" command.
You can use this to give the game commands about the object, which are
listed below. You can also set up the game to automatically inscribe
certain items whenever you find them, using the object knowledge
screens, accessed using "~".

Inscribing an item with '!!':
   This will alert you when the item has finished recharging.

Inscribing an item with '=g':
   This marks an item as 'always pick up'.  This is sometimes useful
   for picking up ammunition after a shootout.  If there is a number
   immediately after the 'g', then the amount picked up automatically
   will be limited.  If you have inscribed a spellbook with '=g4' and
   have four or more copies in your pack, you will not automatially
   pick up any more copies when you have the 'pickup if in inventory'
   option enabled.  If you have three copies in your pack with that
   inscription and happen to find a pile of two copies, you'll
   automatically pick up one so there is four in the pack.

Inscribing an item with "!" followed by a command letter or "*":
   This means "ask me before using this item".  '!w' means 'ask me
   before wielding', '!d' means 'ask me before dropping', and so on.
   If you inscribe an item with '!*' then the game will confirm any
   use of an item.

   Say you inscribed your potion of Speed with '!q'.  This would
   prompt you when you try to drink it to see if you really mean to.
   Multiple '!q' inscriptions will prompt multiple times.

   Similarly, using !v!k!d makes it very hard for you to accidentally
   throw, ignore or put down the item it is inscribed on.

   Some adventurers use this for Scrolls of Word of Recall so they
   don't accidentally return to the dungeon too soon.

Inscribing an item with "@", followed by a command letter, followed by
0-9:
   Normally when you select an item from your inventory you must enter
   the letter that corresponds to the item. Since the order of your
   inventory changes as items get added and removed, this can get
   annoying.  You can instead assign certain items numbers when using
   a command so that wherever they are in your backpack, you can use
   the same keypresses. If you have multiple items inscribed with the
   same thing, the game will use the first one.

   For example, if you inscribe a staff of Cure Light Wounds with
   '@u1', you can refer to it by pressing 1 when "u"sing it.  You
   could also inscribe a wand of Wonder with '@a1', and when using
   "a", 1 would select that wand.

   Spellcasters should inscribe their books, so that if they lose them
   they do not cast the wrong spell.  If you are mage and the
   beginner's spellbook is the first in your inventory, casting 'maa'
   will cast magic missile. But if you lose your spellbook, casting
   'maa' will cast the first spell in whatever new book is in the top
   of your inventory. This can be a waste in the best case scenario
   and exceedingly dangerous in the worst! By inscribing your
   spellbooks with '@m1', '@m2', etc., if you lose your first
   spellbook and attempt to cast magic missile by using 'm1a', you
   cannot accidentally select the wrong spellbook.

Inscribing an item with "^", followed by a command letter:
   When you wear an item inscribed with "^", the game prompts you
   before doing that action.  You might inscribe '^>' on an item if
   you want to be reminded to take it off before going down stairs.
   If the item is in your backpack then the game won't prompt you.

   Like with "!", you can use "*" for the command letter if you want
   to game to prompt you every turn whatever you're doing.  This can
   get very annoying!


Showing extra info in subwindows
================================

In addition to the main window, you can create additional windows that
have secondary information on them. You can access the subwindow menu
by using "=" then "w", where you can choose what to display in which
window.

You may then need to make the window visible using the "window" menu
from the menu bar (if you have one in your version of the game).

There are a variety of subwindow choices and you should experiment to
see which ones are the most useful for you.


Keymaps
=======

You can set up keymaps in Angband, which allow you to map a single
keypress, the trigger, to a series of keypresses, the action.  For
example you might map the key F1 to "maa" (the keypresses to cast
"Magic Missile" as a spellcaster).  This can speed up access to
commonly-used features.  To bypass a keymap that's been assigned to a
key, press "\" before pressing the key.

To set up keymaps, go to the options menu ("=") and select "Edit
keymaps" ("e").  There, you can check if a key triggers a keymap:
select "Query a keymap" ("c") and then press the key to check.  You
can also remove an existing keymap:  select "Remove a keymap" ("e")
and then press the key that trigger the keymap to be removed.  To add
a new keymap (or overwrite an existing one), select "Create a keymap"
("d"), it will then prompt you for the key that triggers the keymap.
After pressing the trigger key, you'll be prompted for the keymap's
action, the series of keypresses that'll be generated when the trigger
key is pressed.  If you make a mistake while entering the keypresses
for the action, press "Control-u" to erase the keypresses already
entered for the action.  Once you've finished entering the keypresses
for the action, press "=" to end the sequence; you'll then be prompted
for whether to keep the newly entered keymap.

Within the action for a keymap, it is frequently useful to temporarily
suppress -more- prompts since they can swallow keypresses from the
keymap.  To disable those prompts from within the action, include "(".
To reenable the prompts, include ")".  So, a typical action where
-more- prompts could happen would look like this: "(" your keypresses
here ")".

The keypresses in the action will be interpreted relative to the
keyset you are currently using (original or roguelike).  The game will
remember what keyset was in effect when the keymap was created.  So if
you change keysets, the keymaps which were only defined for the other
keyset won't be visible.  You can have two keymaps, one for the
original keyset and another for the roguelike keyset, bound to the
same trigger.

Keymaps are not recursive.  If you have F1 as the trigger for a
keymap, including F1 as a keypress in the action for that or another
keymap won't invoke that keymap.

Any changes you make to keymaps from the options menu only last as
long as the game is running.  To have them affect future sessions,
save the keymaps to a file.  There's an option to do that from the
menu for editing keymaps.  See User Pref Files for how the name of the
file affects whether the file is loaded when the game reloads your
character.

Note that the game accounts for the modifier keys (Shift, Control,
Alt, Meta) that are pressed along with a key.  On most platforms, the
game also distinguishes between the keys on the numeric keypad that
have equivalents on the main keyboard.  When a keypress is displayed
or saved to the preference file, the modifiers, if any, for the
keypress are displayed by code letters (S for Shift, ^ for Control, A
for Alt, M for Meta, and K for the numeric keypad) within curly braces
prior to the keypress.  There are two exceptions to that:  if Control
is the only modifier it will displayed as ^ before the keypress
without any curly braces and if Shift is the only modifier it will
often be folded into the keypress itself.  For example:

   {^S}& = Control-Shift-&
   {AK}0 = Alt-0 from the numeric keypad
   ^d    = Control-d
   A     = Shift-a

Special keys, like F1, F2, or Tab, are all written within square
brackets []. For example:

   ^[F1]     = Control-F1
   {^S}[Tab] = Control-Shift-Tab

Special keys include [Escape].

You may find it easier to edit the preference files directly to change
a keymap.  Keymaps are written in pref files as:

   keymap-act:<action>
   keymap-input:<type>:<trigger>

The action must always come first,  "`<type>`" means 'keyset type',
which is either 0 for the original keyset or 1 for the roguelike
keyset.  For example:

   keymap-act:maa
   keymap-input:0:[F1]

An action can have more than one trigger bound to it by having more
than one keymap-input line after it and before the next keymap-act
line.  One reason to do that would be to have the keymap work with
either keyset.  For example:

   keymap-act:maa
   keymap-input:0:[F1]
   keymap-input:1:[F1]

Angband uses a few built-in keymaps.  These are for the movement keys
(they are mapped to ";" plus the number, e.g. "5" -> ";5"), amongst
others.  You can see the full list in pref.prf, but they shouldn't
impact you in any way.


Colours
=======

The "Interact with colors" options submenu ("=", then "c") allows you
to change how different colours are displayed.  Depending on what kind
of computer you have, this may or may not have any effect.

The interface is quite clunky.  You can move through the colours using
"n" for 'next colour' and "N" for 'previous colour'.  Then upper and
lower case "r", "g" and "b" will let you tweak the color.  You can
then save the results to user pref file.


Visuals
=======

You can change how various in-game entities are displayed using the
visuals editor.  This editor is part of the knowledge menus ("~").
When you are looking at a particular entity - for example, a monster -
if you can edit its visuals, that will be mentioned in the prompt at
the bottom of the screen.

If you are in graphics mode, you will be able to select a new tile for
the entity.  If you are not, you will only be able to change its
colours.

Once you have made edits, you can save them from the options menu
("=").  Press "v" for 'save visuals' and choose what you want to save.


Interface details
=================

Some aspects of how the game is presented, notably the font, window
placement and graphical tile set, are controlled by the front end,
rather than the core of the game itself.  Each front end has its own
mechanism for setting those details and recording them between game
sessions.  Below are brief descriptions for what you can configure
with the standard Windows, X11, SDL, SDL2 and Mac front ends.


Windows
-------

With the Windows front end, the game, by default, displays several of
the the subwindows and uses David Gervais's graphical tiles to display
the map. You can close a subwindow with the standard close control on
the window's upper right corner.  Closing the main window with the
standard control causes the game to save its current state and then
exit.  You can reopen or also close a subwindow via the "Visibilty"
menu, the first entry in the "Window" menu for the main window.  To
move a window, use the standard procedure: position the mouse pointer
on the window's title bar and then click and drag the mouse to change
the window's position.  Click and drag on the edges or corners of a
window to change its size.  To select the font for a window, use the
"Font" menu, the second entry in the "Window" menu for the main
window.

The "Term Options" entry in the "Window" menu for the main window is a
shortcut to access the core game's method for selecting the contents
of the subwindows. You can read more about that in Showing extra info
in subwindows.  The "Reset Layout" will rearrange the windows to
conform with the current size and will have a similar result to what
you would get from restarting the Windows interface without a preset
configuration.

The "Bizarre Display" entry in the "Window" menu allows to toggle on
or off an alternate text display algorithm for each window.  That was
added for compatibility with Windows Vista and later.  The default
setting, on, should likely be used, unless text display is garbled on
your system and the off setting allows text to be displayed properly.

The "Increase Tile Width" and "Decrease Tile Width" options in the
"Window", let you increment or decrement, by one pixel, the width of
the columns in a window.  The "Increase Tile Height" and "Decrease
Tile Height" options are similar but work with the height of the rows.
For the primary window, you could use the "Term 0 Font Tile Size"
entry as an alternative to those to set the width of the columns and
height of the rows to certain combinations or to match the width and
height of the font, which is the default.  When the "Enable Nice
Graphics" option is on (it's in the "Options" menu for the main
window), the "Increase Tile Width", "Decrease Tile Width", "Increase
Tile Height", "Decrease Tile Height", and "Term 0 Font Tile Size"
entries will have no effect since the column width and row height are
set automatically when that option is on.

To change whether graphical tiles are used, use the "Graphics" menu,
the first entry in the "Options" menu for the main window.  The "None"
option in the "Graphics" menu will disable graphical tiles and use
text for the map.  The next section section in that menu allows you to
select one of the graphical tile sets.  Turning on the "Enable Nice
Graphics" option in the "Graphics" menu is a shortcut for
automatically setting sizes to get a reasonable-looking result.  When
that is turned on or is already on and the tile set is changed, the
width of the columns ("tile width"), height of the rows ("tile
height") and the number of rows and columns used to display a tile
(the "Tile Multiplier") will be adjusted to work well with the current
font size and the native size of the graphical tiles.  You can
manually adjust the number of rows and columns used for displaying a
tile with the "Tile Multiplier" entry in the "Graphics" menu.  Since
typical fonts are often twice as tall as wide, multipliers where the
first value, for the width, is twice the second, often x work better
with the tiles that are natively square (the original ones, Adam
Bolt's, David Gervais's, and the two versions of Shockbolt's tiles).
Nomad's tiles are 8 x 16 and so usually work best with multipliers
that use the same value for both dimensions.

When you leave the game, the current settings for the Windows
interface are saved as "angband.INI" in the directory that holds the
executable.  Those settings will be automatically reloaded the next
time you start the Windows interface.


X11
---

With the X11 front end, the number of windows opened is set by the
'-n' option on the command line, i.e. running "./angband -mx11 -- -n4"
will open the main window and subwindows one through three if the
executable is in the current working directory.  To control the font,
placement, and size used for each of the windows, set enviroment
variables before running Angband.  Those environment variables for
window 'z' where 'z' is an integer between 0 (the main window) and 7
are:

* ANGBAND_X11_FONT_z holds the name of the font to use for the window

* ANGBAND_X11_AT_X_z holds the horizontal coordinate (zero is
  leftmost) for the upper left corner of the window

* ANGBAND_X11_AT_Y_z holds the vertical coordinate (zero is topmost)
  for the upper left corner of the window

* ANGBAND_X11_COLS_z holds the number of columns to display in the
  window

* ANGBAND_X11_ROWS_z holds the number of rows to display in the window


SDL
---

With the SDL front end, the main window and any subwindows are
displayed within the application's rectangular window.  At the top of
the application's window is a status line.  Within that status line,
items highlighted in yellow are buttons that can be pressed to
initiate an action.  From left to right they are:

* The application's version number - pressing it displays an
  information dialog about the application

* The currently selected terminal - pressing it brings up a menu for
  selecting the current terminal; you can also make a terminal the
  current one by clicking on the terminal's title bar if it is visible

* Whether or not the current terminal is visible - pressing it for any
  terminal that is not the main window will allow you to show or hide
  that terminal

* The font for the current terminal - pressing it brings up a menu to
  choose the font for the terminal

* Options - brings up a dialog for selecting global options including
  those for the graphical tile set used and whether fullscreen mode is
  enabled

* Quit - to save the game and exit

To move a terminal window, click on its title bar and then drag the
mouse. To resize a terminal window, position the mouse pointer over
the lower right corner.  That should cause a blue square to appear,
then click and drag to resize the terminal.

To change the graphical tile set used when displaying the game's map,
press the Options button in the status bar.  Then, in the dialog that
appears, press one of the red buttons that appear to the right of the
label, "Available Graphics:".  The last of those buttons, labeled
"None", selects text as the method for displaying the map.  Your
choice for the graphical tile set does not take effect until you press
the red button labeled "OK" at the bottom of the dialog.

When you leave the game, the current settings for the SDL interface
are saved as "sdlinit.txt" in the same directory as is used for
preference files, see User Pref Files for details.  Those settings
will be automatically reloaded the next time you start the SDL
interface.


SDL2
----

With the SDL2 front end, the application has one window that can
contain the main window and any of the subwindows.  The application
may also have up to three additional windows which can contain any of
the subwindows.  A subwindow may not appear in more than of those
application windows.  Unused portions of an application window are
tiled with repetitions of the game's logo.

Each of the application windows has a menu bar along the top.  The
"Menu" entry at the left end of the menu bar has the main menu for
controlling aspects of the SDL2 interface.

Next to "Menu", are a series of one letter labels that act as toggles
for the terminal windows shown in the application window.  Click on
one to toggle it between on (drawn in white) and off (drawn in gray).
It is not possible to toggle off the main window shown in the primary
application window.

At the end of the menu bar are two toggle buttons labeled "Size" and
"Move". Each will be gray if disabled or white if enabled.  Clicking
on "Size" when it is disabled will enable it, disable "Move", turn off
input to the game's core, and cause clicks and drags within the
displayed subwindows to change the sizes for those subwindows.
Clicking on "Move" when it is disabled will enable it, disable "Size",
turn off input to the game's core, and cause clicks and drags within
the displayed subwindows to change the positions for those subwindows.
Disable both "Move" and "Size", by clicking on one if it is enabled,
to restore passing input to the game's core.

Within "Menu", the first entries control properties each of the
displayed terminal windows within that application window.  For the
main window, you can set the font, graphical tile set, whether the
window is shown with borders or not, and whether or not the window
will be shown on top of the other windows. For subwindows, you can set
the font, the purpose (which is a shortcut for enabling the subwindow
content as described in Showing extra info in subwindows), the
opaqueness ("alpha") of the window, whether the window is shown with
borders or not, and whether or not the window will be shown on top of
the other windows.

Below the entries for the contained terminal windows, is an entry,
"Fullscreen" for toggling fullscreen mode for that application window.
That entry will be gray when fullscreen mode is off and white when it
is on.

In the primary application window which contains the main window,
there is an entry, "Send Keypad Modifier", after that for whether key
strokes from the numeric keypad will be sent to the game with the
keypad modifier set.  That entry will be gray when the modifier is not
send and will be white when the modifier is sent.  Sending the
modifier allows some predefined keymaps to work, for instance shift
with 8 from the numeric keypad to run north, at the cost of
compatibility issues with some keyboard layouts that differ from the
standard English keyboard layout for which normal keys have
equivalents on the numeric keypad.
https://github.com/angband/angband/issues/4522 has an example of the
problems that can be avoided by not sending the keypad modifier.

Below "Send Keypad Modifier" in the primary application window's
"Menu" is "Windows", use that to bring up one of the additional
application windows.

The final two entries in "Menu" are "About" for displaying an
information dialog about the game and "Quit" to save the game and
exit.

When you leave the game, the current settings for the SDL interface
are saved as "sdl2init.txt" in the same directory as is used for
preference files, see User Pref Files for details.  Those settings
will be automatically reloaded the next time you start the SDL
interface.


Mac
---

With the Mac-specific front end, you can use Apple's standard
mechanisms to control window placement:  click and drag on a window's
title bar to move it, click and drag on a window's edge or corner to
change the window's dimensions, and click the red button at the top
left corner of a subwindow to close it. To reopen a subwindow that you
closed, use the Window menu from the Mac's menu bar while the game is
the active application and select the entry near the bottom of that
menu that corresponds to the subwindow you want to see.  For a
subwindow's entry to be enabled in the Window menu, that subwindow
must be configured to display at least one category of information:
see Showing extra info in subwindows for details.

To change the font for a window, click on the window's title bar and
select "Edit Font" from the Settings menu in the Mac's menu bar.  That
will open a dialog which displays the family, typeface and size for
the current font. Changing the selection for any of those will change
the font in the window.

Whether the game's map is displayed as text or as graphical tiles can
be set by selecting Settings from the Mac's menu bar while the game is
the active application and then choosing from one of the entries in
the Graphics option. Choosing "Classic ASCII" will display the map as
text.  Any of the other options will use some form of graphical tiles
to display the map.  If you wish to adjust how graphical tiles are
scaled to match up with the currently selected font in the main
window, select 'Change Tile Set Scaling...' in the Settings menu.

When you leave the game, the current Mac-specific settings are saved
and will be automatically reloaded when you restart.  The settings are
stored in "Library/Preferences/org.rephial.angband.plist" within your
user directory. If you suspect those settings have been corrupted in
some way or would like to start again from the default settings, quit
the game if it is running, open a Terminal window (i.e. select
'Go->Utilities->Terminal' from the Finder's menus), and, in that
Terminal window, run this:

   defaults delete org.rephial.angband

to clear the contents of the preferences file and any cached
preferences that may be retained in memory.
