Ticket #1544: customize.txt

File customize.txt, 15.0 KB (added by PowerWyrm, 8 years ago)

Reviewed version of customize.txt. Fixed one typo.

Line 
1====================
2Customising the game
3====================
4
5Angband supports multiple customizations. These can vary from alternative
6methods for selecting objects, keymaps for different commands, changing the
7visuals (using graphical tiles), creating subwindows, and saving
8customizations for use on future characters.
9
10Special Keys
11============
12 
13Certain special keys may be intercepted by the operating system or the host
14machine, causing unexpected results. In general, these special keys are
15control keys, and often, you can disable their special effects.
16
17If you are playing on a UNIX or similar system, then Ctrl-C will interrupt
18Angband. The second and third interrupt will induce a warning bell, and the
19fourth will induce both a warning bell and a special message, ince the
20fifth will quit the game, after killing your character. Also, ``Ctrl-Z``
21will uspend the game, and return you to the original command shell, until
22you resume the game with the ``fg`` command. There is now a compilation
23option to force the game to prevent the "double ``ctrl-z`` escape death
24trick". The ``Ctrl-\`` and ``Ctrl-D`` and ``Ctrl-S`` keys should not be
25intercepted.
26
27It is often possible to specify "control-keys" without actually pressing
28the control key, by typing a caret (``^``) followed by the key. This is
29useful for specifying control-key commands which might be caught by the
30operating system as explained above.
31
32Pressing backslash (``\``) before a command will bypass all keymaps, and
33the next keypress will be interpreted as an "underlying command" key,
34unless it is a caret (``^``), in which case the keypress after that will be
35turned into a control-key and interpreted as a command in the underlying
36angband keyset. For example, the sequence ``\`` + ``.`` + ``6`` will always
37mean "run east", even if the ``.`` key has been mapped to a different
38underlying command.
39
40The ``0`` and ``^`` and ``\`` keys all have special meaning when entered at
41the command prompt, and there is no "useful" way to specify any of them as
42an "underlying command", which is okay, since they would have no effect.
43
44For many input requests or queries, the special character ESCAPE will abort
45the command. The ``[y/n]`` prompts may be answered with ``y`` or ``n``, or
46``ESCAPE``. The ``-more-`` message prompts may be cleared (after reading
47the displayed message) by pressing ``ESCAPE``, ``SPACE``, ``RETURN``,
48``LINEFEED``, or by any keypress, if the "quick_messages" option is turned
49on.
50 
51Command Counts
52==============
53
54Some commands can be executed a fixed number of times by preceding them
55with a count. Counted commands will execute until the count expires, until
56you type any character, or until something significant happens, such as
57being attacked. Thus, a counted command doesn't work to attack another
58creature. While the command is being repeated, the number of times left to
59be repeated will flash by on the line at the bottom of the screen.
60
61To give a count to a command, type ``0``, the repeat count, and then the
62command. If you want to give a movement command and you are using the
63original command set (where the movement commands are digits), press space
64after the count and you will be prompted for the command.
65
66Counted commands are very useful for time consuming commands, as they
67automatically terminate on success, or if you are attacked. You may also
68terminate any counted command (or resting or running), by typing any
69character. This character is ignored, but it is safest to use a ``SPACE``
70or ``ESCAPE`` which are always ignored as commands in case you type the
71command just after the count expires.
72
73Squelch settings
74================
75     
76Angband allows you to ignore specific items that you don't want to see
77anymore. These items are 'squelched' and any similar items are hidden from
78view. There are several ways to squelch an item. The easiest way is to
79choose the ``s`` option when destroying an object. Whenever you destroy an
80object you are forced to confirm the destruction. One of the options is
81``s``. If you use this option, the object is dropped and then hidden from
82view.
83
84Weapons and armor have quality squelch options. These allow you to specify
85what types of weapons and armor you are no longer interested in seeing.
86There is a quality setting for each weapon and armor type. Squelching
87weapons and armor by destroying the object will prompt you with a question
88about whether you wish to squelch all of that type of armor with a certain
89quality setting. These quality settings are described below:
90
91bad
92  The weapon/armor has negative AC, to-hit or to-dam. It may or may not be
93  cursed
94
95average
96  The weapon/armor has no pluses no minuses.  It is non-magical.
97
98good
99  The weapon/armor has positive AC, to-hit or to-dam. However it does not
100  have any special abilities, brands, slays, stat-boosts, resistances
101 
102excellent, with no high resists
103  Weapons will have some slays. Armor will have resistances, but these are
104  limited to rfire, rcold, racid and relec.
105
106excellent but not splendid
107  Weapons and armor may have high resists but they do not have any stat
108  boosts or brands.
109
110splendid
111  Squelching all splendid items only leaves artifacts unsquelched.
112
113Using Inscriptions
114==================
115
116You can inscribe items to change the selection process. Normally when you
117select an item from your inventory you must enter a letter that corresponds
118to the item. Since the order of your inventory changes as items get added
119and removed, you may want to inscribe alternate methods of item selection.
120Instead of entering letters, you can enter numbers, and automatically
121assign certain items to specific numbers. The way to do this is by using
122the inscribe ``{`` command, which will add an inscription to the item. You
123can add an inscription directly to an item or by using the ``~`` memory
124list you can add an auto-inscription. Then every similar item you find from
125then on will have that inscription placed on this item.
126
127If you enter a number between 0 and 9, the first item engraved with ``@#``
128where ``#`` is the number you entered will be selected. For example, if you
129have a shovel engraved with ``@0`` and you type ``w`` (for wield) and then
130``0``, you will wield the shovel. This is very useful for keymaps (see
131below), since you can use this to select an object regardless of its
132location in your pack. For example, Angband automatically defines a keymap
133for the key ``X`` to do ``w0``. If you then engrave both your digging
134instrument and your primary weapon with ``@0``, pressing ``X`` will wield
135whichever one is not being currently wielded (letting you quickly switch
136between them). Multiple numbers can be engraved on the same object; for
137example, if a sword is engraved with ``@1@0``, then either ``w1`` or ``w0``
138will wield it. Since you may want different items defined with ``@0`` you
139can also make an inscription ``@x#`` will act like ``@#`` but only when the
140current "Angband command" is ``x``. Thus you can put ``@z4`` on a rod and
141``@u4`` on a taff, and then use both ``z4`` and ``u4`` as desired.
142
143Perhaps the most commonly inscribed items are spellbooks. Casting spells
144often takes at least 3 commands. The cast commmand (``m`` or ``p``) the
145book selection and the spell selection. Then you may need to select a
146target. For example, if you are a mage and the beginner's spellbook is the
147first in your inventory, casting ``maa`` will cast magic missile. However,
148if you lose your spellbook, casting ``maa`` will cast the first spell in
149whatever new book is in the top of your inventory. This can be a waste in
150the best case scenario and exceedingly dangerous in the worst. To avoid
151this, it's very useful to inscribe your spellbooks with ``@m1``, ``@m2``,
152``@m3`` etc. Then if you lose your first spellbook and attempt to cast
153magic missile by using ``m1a``, you will not accidentally select the wrong
154spellbook, if the first spellbook is not in your inventory.
155
156You can also use inscriptions to force the game to prompt you on whether or
157not you want to use that object. Any object containing ``!x`` in its
158inscription, where ``x`` is the current "angband command" (or containing
159``!*`` for all commands) will induce "verification" whenever that object is
160"selected". Thus, inscribing, say, ``!v!k!d`` on an object will greatly
161reduce the odds of you "losing" it by accident, and inscribing ``!*`` on an
162object will allow you to be very paranoid about using the object. Note that
163"selling" and "dropping" both use the ``d`` command.
164
165User Pref Files
166===============
167
168Angband allows you to change various aspects of the game to suit your
169tastes. You may define keymaps (changing the way Angband maps your
170keypresses to underlying commands), modify the visuals (allowing you to
171change the appearance of monsters, objects, or terrain features), change
172the colors (allowing you to make a given color brighter, darker, or even
173completely different), or set options (turning them off or on).
174
175Angband stores your preferences in files called "user pref files", which
176contain comments and "user pref commands", which are simple strings
177describing one aspect of the system about which the user has a preference.
178There are many ways to load a user pref file, and in fact, some of these
179files are automatically loaded for you by the game. All of the files are
180kept in the "lib/user/" directory, though you may have to use one of the
181command line arguments to redirect this directory, especially on multiuser
182systems. You may also enter single user pref commands directly, using the
183special "Enter a user pref command" command, activated by "double quote".
184You may have to use the "redraw" command (``^R``) after changing certain of
185the aspects of the game, to allow Angband to adapt to your changes.
186
187When the game starts up, after you have loaded an old character, or created
188a new character, some user pref files are loaded automatically. First, the
189"pref.prf" file is loaded. This file contains some user pref commands which
190will work on all platforms. Then one of ``font-xxx.prf`` (for normal usage)
191or ``graf-xxx.prf`` (for bitmap usage) is loaded. These files contain
192attr/char changes to allow the monsters, objects, and/or terrain features
193to look "better" on your system. Then the ``pref-xxx.prf`` file is loaded.
194This file contains pre-defined system specific stuff (keymaps, color
195definitions, etc). Then, the ``user-xxx.prf`` file is loaded. This file
196contains user-defined system specific stuff. The ``user-xxx.prf`` file is
197used as the "default" user pref file in many places. The ``xxx`` is the
198"system suffix" for your system, taken from the ``main-xxx.c`` file which
199was used to generate your executable. Finally, the ``Race.prf``,
200``Class.prf``, and ``Name.prf`` files are loaded, where ``Race``,
201``Class``, and ``Name`` are replaced by the actual race, class, and name of
202the current character.
203
204Several options menu items allow you to load existing user pref files,
205create new user pref files, append information to existing user pref files,
206and/or interact with various of the user preferences.
207
208Subwindows
209==========
210
211In addition to the main window, you can create additional window displays
212that have other secondary information on them. You can access the subwindow
213menu by using ``=`` then ``w``. You can select what windows to display. You
214may then need to make the window visible using the "window" pull down menu
215from the menu bar. There are a variety of subwindow choices and you should
216experiment to see which ones are the most useful for you.
217
218User Pref Files (Keymaps)
219=========================
220
221The "Interact with keymaps" menu allows you to define "keymaps", which maps
222a single keypress to a series of keypresses. Keymaps are not recursive;
223i.e. keypresses in the action field do not get expanded again. Angband uses
224keymaps to map the original and the roguelike keysets to the underlying
225command set, and allows the user to modify or add keymaps of their own.
226Note that all keymap actions must be specified using underlying commands,
227not keypresses from the original or roguelike keysets. The original keyset
228is almost identical to the underlying keyset, except that "numbers" are
229mapped to ``;`` plus a direction, ``5`` is mapped to ``,``, and a few
230control-keys are mapped to various things. See ``command.txt`` for the full
231et of underlying commands. Some uses for keymaps include the ability to
232"disable" a command by mapping it to ``\x00``.
233
234Keymaps can be specified in user pref files as lines of the form
235``A:<action>`` and ``C:<T>:<keystr>``, where ``<T>`` is the keyset
236(``0``/``1`` for original/roguelike), ``<keystr>`` is the encoded keypress,
237and <action> is the encoded keymap action.
238
239Note that any keys that are not required for access to the underlying
240command set may be used by the user to extend the "keyset" which is being
241used, by defining new "keymaps". To avoid the use of any "keymaps", press
242backslash (``\``) plus the "underlying command" key. You may enter
243"control-keys" as a caret (``^``) plus the key (so ``^`` + "``p`` yields
244``^p``).
245
246User Pref Files (Visuals)
247=========================
248
249You can use the "Interact with visuals" menu to change various visual
250information, currently including the choice of what attr/char values are
251used to represent various monsters, objects, or terrain features. Note that
252in combination appropriate support in ``main-xxx.c``, and with the use of
253the "use_graphics" flag, you may be able to specify that "graphic bitmaps"
254hould be used instead of normal "colored characters" for various things.
255
256When interactively modifying the attr/char values for monsters, objects, or
257terrain features, pressing ``n`` or ``N`` will change which entry you are
258changing, pressing ``a`` or ``A`` will rotate through the available attr
259values, and pressing ``c`` or ``C`` will rotate though the available char
260values. Note that attr/char values with the "high bit" set may induce the
261display of special "graphic" pictures if the "use_graphics" flag is set,
262and your system supports the "use_graphics" flag.
263
264Note that this menu can be abused in various ways, and if you must do so,
265remember that you are only cheating yourself.
266
267Keymaps can be specified in user pref files as lines of the form
268``R:<N>:<A>/<C>`` or ``K:<N>:<A>/<C>`` or ``F:<N>:<A>/<C>`` or
269``U:<N>:<A>/<C>``.
270
271User Pref Files (Colors)
272========================
273
274The "Interact with colors" menu allows you to change the actual internal
275values used to display various colors. This command may or may not have any
276effect on your machine. Advanced machines may allow you to change the
277actual RGB values used to represent each of the 16 colors used by Angband,
278and perhaps even allow you to define new colors which are not currently
279used by Angband.
280
281Colors can be specified in user pref files as lines of the form
282``V:<N>:<V>:<R>:<G>:<B>``.
283
284User Pref Files (Options)
285=========================
286
287The "Interact with options" command allows you to turn options on or off.
288You may turn options off or on using the user pref commands of the form
289``X:<option>`` or ``Y:<option>`` respectively.
290