Fix braces
[crawl.git] / crawl-ref / docs / options_guide.txt
1 Guide to Crawl's options
2 ========================
3
4 This document explains all of the options in the latest version of
5 Dungeon Crawl Stone Soup. If you get stuck or some things don't seem to
6 work properly, ask for help in ##crawl on freenode, or on the Crawl
7 forums at http://crawl.develz.org/tavern/.
8
9 The contents of this text are:
10
11 0-  Generalities.
12 0-a     Standard and additional option files.
13 0-b     Options on the command line.
14 0-c     Options and how to set them.
15 0-d     List options.
16 0-e     Aliases and variables.
17 1-  Starting Screen.
18                 name, remember_name, weapon, species, background, combo,
19                 restart_after_game, restart_after_save, newgame_after_quit,
20                 name_bypasses_menu, default_manual_training,
21                 autopickup_starting_ammo, game_seed, pregen_dungeon
22 2-  File System and Sound.
23                 crawl_dir, morgue_dir, save_dir, macro_dir, sound, hold_sound,
24                 sound_file_path, one_SDL_sound_channel
25 3-  Interface.
26 3-a     Dropping and Picking up.
27                 autopickup, autopickup_exceptions, default_autopickup,
28                 pickup_thrown, assign_item_slot, pickup_menu_limit,
29                 drop_filter, auto_hide_spells
30 3-b     Passive Sightings (detected and remembered entities).
31                 detected_monster_colour, detected_item_colour,
32                 remembered_monster_colour
33 3-c     Branding (Item and Monster Highlighting).
34                 friend_brand, neutral_brand, stab_brand, may_stab_brand,
35                 heap_brand, feature_item_brand, trap_item_brand
36 3-d     Level Map Functions.
37                 level_map_cursor_step
38 3-e     Viewport Display Options.
39                 view_max_width, view_max_height, view_lock_x,
40                 view_lock_y, view_lock, centre_on_scroll,
41                 symmetric_scroll, scroll_margin_x, scroll_margin_y,
42                 scroll_margin, always_show_exclusions
43 3-f     Travel and Exploration.
44                 travel_delay, explore_delay, rest_delay, travel_avoid_terrain,
45                 explore_greedy, explore_stop, explore_stop_pickup_ignore,
46                 explore_wall_bias, travel_key_stop, travel_one_unsafe_move,
47                 tc_reachable, tc_dangerous, tc_disconnected, tc_excluded,
48                 tc_exclude_circle, runrest_ignore_message,
49                 runrest_stop_message, interrupt_<delay>, delay_safe_poison,
50                 runrest_ignore_monster, rest_wait_both, rest_wait_ancestor,
51                 rest_wait_percent, explore_auto_rest, auto_exclude
52 3-g     Command Enhancements.
53                 auto_switch, travel_open_doors, easy_unequip, equip_unequip,
54                 jewellery_prompt, easy_confirm, simple_targeting,
55                 allow_self_target, easy_quit_item_prompts, ability_menu,
56                 easy_floor_use, sort_menus, spell_slot, item_slot,
57                 ability_slot, autofight_stop, autofight_warning,
58                 autofight_throw, autofight_throw_nomove, autofight_fire_stop,
59                 autofight_caught, autofight_wait, autofight_prompt_range,
60                 automagic_enable, automagic_slot, automagic_fight,
61                 automagic_stop, fail_severity_to_confirm, easy_door,
62                 warn_hatches, enable_recast_spell, confirm_action,
63                 regex_search, autopickup_search, bad_item_prompt
64 3-h     Message and Display Improvements.
65                 hp_warning, mp_warning, hp_colour, mp_colour, stat_colour,
66                 status_caption_colour, enemy_hp_colour, clear_messages,
67                 show_more, small_more, show_newturn_mark, show_game_time,
68                 equip_bar, animate_equip_bar, item_stack_summary_minimum,
69                 mlist_min_height, mlist_allow_alternate_layout,
70                 monster_item_view_coordinates, monster_item_view_features,
71                 msg_min_height, msg_max_height, msg_webtiles_height,
72                 messages_at_top, msg_condense_repeats, msg_condense_short,
73                 show_travel_trail, skill_focus, default_show_all_skills,
74                 monster_list_colour, view_delay, use_animations,
75                 darken_beyond_range, force_more_message, flash_screen_message,
76                 cloud_status, always_show_zot
77 3-i     Colours (messages and menus)
78                 menu_colour, message_colour
79 3-j     Missiles.
80                 fire_items_start, fire_order
81 3-k     Message Channels.
82                 plain, prompt, god, duration, danger, warning, recovery,
83                 talk, talk_visual, timed_portal, sound, intrinsic_gain,
84                 mutation, monster_spell, monster_enchant, monster_warning,
85                 friend_spell, friend_enchant, friend_action, monster_damage,
86                 monster_target, banishment, equipment, floor, multiturn,
87                 examine, examine_filter, diagnostic, error, tutorial, orb,
88                 hell_effect, dgl_message
89 3-l     Inscriptions.
90                 autoinscribe, show_god_gift
91 3-m     Macro related Options.
92                 flush.failure, flush.command, flush.message,
93                 additional_macro_file, bindkey
94 3-n     Tiles Options.
95                 tile_show_items, tile_skip_title, tile_menu_icons,
96                 tile_player_col, tile_monster_col, tile_neutral_col,
97                 tile_peaceful_col, tile_friendly_col, tile_plant_col,
98                 tile_item_col, tile_unseen_col, tile_floor_col, tile_wall_col,
99                 tile_mapped_floor_col, tile_mapped_wall_col,
100                 tile_explore_horizon_col, tile_door_col, tile_downstairs_col,
101                 tile_upstairs_col, tile_branchstairs_col, tile_portal_col,
102                 tile_transporter_col, tile_transporter_landing_col,
103                 tile_feature_col, tile_trap_col, tile_water_col,
104                 tile_deep_water_col, tile_lava_col, tile_excluded_col,
105                 tile_excl_centre_col, tile_window_col, tile_update_rate,
106                 tile_runrest_rate, tile_key_repeat_delay, tile_tooltip_ms,
107                 tile_tag_pref, tile_window_width, tile_window_height,
108                 tile_map_pixels, tile_viewport_scale, tile_map_scale,
109                 tile_cell_pixels, tile_filter_scaling, tile_force_overlay,
110                 tile_overlay_col, tile_overlay_alpha_percent, tile_full_screen,
111                 tile_single_column_menus, tile_font_crt_file,
112                 tile_font_stat_file, tile_font_msg_file, tile_font_tip_file,
113                 tile_font_lbl_file, tile_font_crt_family,
114                 tile_font_stat_family, tile_font_msg_family,
115                 tile_font_lbl_family, tile_font_crt_size, tile_font_stat_size,
116                 tile_font_msg_size, tile_font_tip_size, tile_font_lbl_size,
117                 tile_font_ft_light, glyph_mode_font, glyph_mode_font_size,
118                 tile_show_minihealthbar, tile_show_minimagicbar,
119                 tile_show_demon_tier, tile_water_anim, tile_misc_anim,
120                 tile_realtime_anim, tile_show_player_species,
121                 tile_show_threat_levels, tile_layout_priority,
122                 tile_display_mode, tile_level_map_hide_messages,
123                 tile_level_map_hide_sidebar, tile_player_tile,
124                 tile_weapon_offsets, tile_shield_offsets,
125                 tile_web_mouse_control
126 4-  Character Dump.
127 4-a     Saving.
128                 dump_on_save
129 4-b     Items and Kills.
130                 kill_map, dump_kill_places, dump_item_origins,
131                 dump_item_origin_price, dump_message_count, dump_order,
132                 dump_kill_breakdowns
133 4-c     Notes.
134                 user_note_prefix, note_items, note_monsters, note_hp_percent,
135                 note_skill_levels, note_all_skill_levels, note_skill_max,
136                 note_xom_effects, note_messages, note_chat_messages,
137                 note_dgl_messages
138 5-  Miscellaneous.
139 5-a     All OS.
140                 mouse_input, wiz_mode, explore_mode, char_set, colour,
141                 display_char, feature, mon_glyph, item_glyph,
142                 use_fake_player_cursor, show_player_species,
143                 use_modifier_prefix_keys, language, fake_lang,
144                 read_persist_options
145
146 5-b     DOS and Windows.
147                 dos_use_background_intensity
148 5-c     Unix.
149                 blink_brightens_background, bold_brightens_foreground,
150                 best_effort_brighten_background,
151                 best_effort_brighten_foreground, allow_extended_colours,
152                 background_colour, foreground_colour, use_fake_cursor
153
154 6-  Lua.
155 6-a     Including lua files.
156 6-b     Executing inline lua.
157 6-c     Conditional options.
158 6-d     Conditional option caveats.
159
160 7-  Recommended Options for Blind Players.
161
162 ------------------------------------------------------------------------
163
164 0-  Generalities on options.
165 ============================
166
167 0-a     Standard and additional option files.
168 ---------------------------------------------
169
170 Crawl uses the first file of the following list as its option file:
171 * settings/init.txt
172 * init.txt (in the Crawl directory)
173 * .crawlrc (in the Unix home directory)
174
175 Alternatively, you can use the command line option
176     -rc <file>
177 which tells Crawl to use precisely that file.
178
179 On the starting screen, Crawl tells you which init file it uses, if any.
180
181 It is possible to include additional files within the options file via
182     include = <file>
183 Note that these are treated as if their content was entered verbatim
184 in the options file. By default, Crawl searches for all these included
185 files in the settings/ directory but you can specify a special folder
186 using the command line option
187     -rcdir <dir>
188
189 External option files have several uses: They allow quick customisation
190 of Crawl's general appearance (colouring/suppression of messages, and
191 the inventory style). More elaborate option magic (usually containing
192 lua) can also be conveniently hidden this way. Finally, there are some
193 additional option files in the settings/ directory; these allow setting
194 some options and monster glyphs to their defaults from older versions.
195 See the header of the default init.txt for more details.
196
197 The following files are automatically included with Crawl for easy usage, and
198 can be included without any further setup:
199
200 * advanced_optioneering.txt
201 * dvorak_command_keys.txt
202 * colemak_command_keys.txt
203 * neo_command_keys.txt
204 * no_vi_command_keys.txt
205 * safe_move_shift.txt
206
207 0-b     Options on the command line.
208 ------------------------------------
209
210 A quick way to make small changes to the options, without having to
211 switch to a different option file, is to use the command line options
212 -extra-opt-first or -extra-opt-last, which make it as if the given
213 option was (respectively) at the top or bottom of the option file. For
214 example,
215
216     -extra-opt-last wiz_mode=yes
217
218 will cause any new game to start in wizard mode. -extra-opt-first and
219 -extra-opt-last can be used multiple times on the same command line.
220
221 0-c     Options and how to set them.
222 ------------------------------------
223
224 There are three broad types of Crawl options: true/false values
225 (booleans), arbitrary values, and lists of values. In this document,
226 options are usually described with their default values (if there is a
227 default); this should also explain which of the above-mentioned types
228 it is. Each option should have some remarks on how it's typically used
229 - but keep in mind that the options you want to use depend on your
230 playing style and sometimes also on your operating system.
231
232 There are two styles you can use to set options. The classic
233 name=value syntax, one option per-line:
234     remember_name  = true
235     explore_greedy = false
236
237 And the NetHack-style combined option line:
238     OPTION = remember_name, !explore_greedy
239
240 The second style is useful to specify simple options in a few lines,
241 but it cannot be used for options that take complex lists of values
242 (such as the autopickup_exceptions option).
243
244 Some options need a path as an argument; here you have to use a
245 filesystem path suitable for your system. Other options accept regular
246 expressions (regexes): here you can simply use ordinary strings, adapt
247 the suggested regexes to your needs or search the internet for regex
248 syntax.
249
250 Note that in the tutorial and hints modes, some of your options settings may
251 get overwritten to facilitate the explanations. This concerns the following
252 options, and their enforced setting for tutorial games are as follows:
253    clear_messages      = true
254    weapon              = hand axe, for Berserkers in hints mode
255 and, for Tiles,
256    tile_tag_pref       = tutorial
257
258 0-d     List options.
259 ---------------------
260
261 A number of options can have a list of values. Most but not all of these
262 options allow setting multiple values in a single line, separated by commas.
263 It is possible to reset, add items to, or remove items from such an option.
264    Add values to the end of the list (append):
265       drop_filter += useless, enchant
266    Add values to the beginning of the list (prepend):
267       drop_filter ^= forbidden
268    Remove values from the list (exact match only):
269       drop_filter -= enchant
270    Reset the list:
271       drop_filter = bad_item, dangerous_item
272    Empty the list:
273       drop_filter =
274
275 The "listopt = value" syntax first clears the list, then adds values. In
276 previous versions of Crawl it was a synonym for +=, and only bare
277 "listopt =" cleared the list.
278
279 For many options, such as drop_filter, there is effectively no difference
280 between appending and prepending. However, other options, such as
281 message_colour, do care about the order of items; these will be noted as
282 "Ordered list options" in their descriptions. In most cases, earlier items
283 take precedence over later ones, so += defers to existing matches (including
284 defaults) while ^= overrides them. So, for example, with the sequence of
285 options:
286    message_colour  = cyan:hits
287    message_colour ^= red:crimson
288    message_colour += yellow:killer
289 the message "The crimson imp hits you!" will be displayed in red, while "The
290 killer bee hits you!" will be displayed in cyan.
291
292 0-e     Aliases and variables.
293 ------------------------------
294
295 For long option names, you can define option aliases by doing:
296     alias := long_option_name
297 For instance, you can use:
298     ae := autopickup_exceptions
299 and thereafter use "ae" instead of "autopickup_exceptions":
300     ae += >uselessness, >inaccuracy
301
302 You can define shortcuts for option values (variables). For example,
303     $useless := darkgrey
304 could be used in conjunction with
305     menu_colour += $useless:random uselessness
306
307 To prevent a variable from being changed you can make it a constant:
308     constant = useless
309
310 This is useful if you wish to prevent an included file from altering
311 a variable.
312
313 See dat/defaults/standard_colours.txt for usage of aliases and variables. Note
314 that changing the variables defined in these files will only affect your own
315 configuration file, as the default options will have already been loaded. If
316 you want to change them, you will have to override the options themselves.
317
318
319 1-  Starting Screen.
320 ====================
321
322 The following options are a convenience to help you quickly start your
323 game of Crawl, and/or configure the start of the game from a file or the
324 command line.
325
326 name = Delilah
327         If set, that's the name all your Crawl characters will get.
328
329 remember_name = true
330         Crawl remembers the options (species, background etc.) you used
331         to create your last character. You may recycle them in the
332         starting screen for a new character. If this option is set to
333         true, Crawl will also remember the last name you used.
334
335         If you use this option and want to enter a name _after_
336         choosing your species and background, you must enter . at the
337         initial name prompt - hitting Enter at the name prompt will
338         simply reuse your old name if remember_name is set.
339
340 weapon += (short sword |...| unarmed | random | viable), <weapon>, ...
341         (List option)
342         Specifying the weapon option allows you to bypass the weapon
343         selection screen. Tridents, flails, rapiers, long swords, and war
344         axes are restricted to fighters and gladiators, and quarterstaves
345         are restricted to gladiators only. The standard weapon prompt will be
346         shown if an illegal choice for the selected background is specified.
347         The "viable" option makes a random choice from among the "good" weapons
348         for the chosen character. Specifying more than one option causes the
349         game to randomly select a weapon from the given list. The combo option
350         overrides (and is overridden by) this option.
351
352 species += (Human |...| Vampire | random | viable), <species>, ...
353         (List option)
354         The usual abbreviations (Hu, HO, etc.) work. "viable" will choose a
355         viable species for a given background if the background is chosen
356         first. Specifying multiple species causes one to be selected at
357         random from the given species. The combo option overrides (and is
358         overridden by) this option.
359
360 background += (Fighter |...| Wanderer | random | viable), <background>, ...
361         (List option)
362         Here again the abbreviations (Fi, Wz, AK, etc.) can be used. The same
363         caveat applies to "viable": it is only really meaningful if the
364         species option is also set. Specifying multiple backgrounds causes
365         one to be selected at random from the given species. The combo option
366         overrides (and is overridden by) this option.
367
368 combo += (HuFi . short sword | Human Monk | ...), <combo>, ...
369         (List option)
370         Specifies a complete set of species, background, and (where
371         applicable) weapon. If a combo requires a weapon choice and one isn't
372         specified, it is prompted for. Combos may be abbreviated or specified
373         in full. If multiple combos are specified, one is selected randomly
374         from the specified combos. The weapon, species, and background
375         options are overridden by (and override) this option.
376
377 restart_after_game = maybe/true
378         When set to true, at the game end, crawl will return to the main menu.
379         If set to maybe, crawl will return to the main menu only if the startup
380         options don't bypass the main menu, otherwise it will exit. If set to
381         false, it will exit unconditionally. This option is set to true for
382         local tiles builds by default, and maybe by default for other builds.
383         This option is ignored for online games.
384
385 restart_after_save = true
386         When the game is saved, return to the main menu. This option
387         only has an effect if restart_after_game is set to maybe or true.
388         This option is ignored for online games.
389
390 newgame_after_quit = false
391         When true, if a name/combo is set, quit will do a fast restart. On this
392         setting, with restart_after_game as non-false, it may be possible to
393         exit crawl only via saving.
394
395 name_bypasses_menu = true
396         When set to true, having a valid name set via options will skip the main
397         menu and jump right to a game or character selection (if there is no
398         save).
399
400 default_manual_training = false
401         When set to true, new characters will start with skill training
402         set to manual mode instead of automatic mode. This will also set the
403         [!] selection on the skill (m) menu to "cost" by default, instead of
404         "training".
405
406 autopickup_starting_ammo = true
407         When set, at game start, autopickup is forced on (as per the \
408         menu) for the player's starting ammunition type (including stones
409         for Earth Elementalists and arrows for Transmuters). Even when this
410         option is set, autopickup of those items can be disabled from the
411         \ menu once the game has begun.
412
413 game_seed = none
414         A number indicating the seed to initialize the random number generator
415         from. Within certain limits, the same seed will deterministically lead
416         to the same dungeon. If set to "none" or 0, the seed will be chosen
417         randomly. This can also be set directly via the command line with
418         "-seed", which will override any rc file setting. This value is an
419         unsigned 64 bit integer.
420
421 pregen_dungeon = incremental
422         When set to `true` or `full`, the game will pregenerate the entire
423         connected dungeon when starting a new character. This leads to
424         deterministic dungeon generation relative to a particular game seed, at
425         the cost of a slow game start. If set to `incremental`, the game will
426         generate levels as needed so that it always generates them in the same
427         order, also producing a deterministic dungeon. You still may encounter
428         variation in bazaars, the abyss, pandemonium, and ziggurats, and for
429         incremental pregeneration, artefacts. When set to `false` or `classic`,
430         the game will generate all levels on level entry, as was the rule before
431         0.23. Some servers may disallow full pregeneration.
432
433 2-  File System.
434 ================
435
436 crawl_dir = <path>
437         The path used for the relative paths when looking for other
438         files. Defaults to the directory that contains the Crawl
439         executable.
440
441 morgue_dir = morgue
442         Directory where morgue dumps files (morgue*.txt and
443         morgue*.lst) as well as character dumps files are written.
444
445 save_dir = saves
446         Directory where saves and bones are stored. This option may be
447         ignored depending on the settings used to compile Crawl, but
448         should be honoured for the official Crawl binaries.
449
450 macro_dir = settings/
451         Directory for reading macro.txt.
452         For tile games, wininit.txt will also be stored here.
453         It should end with the path delimiter.
454
455 sound ^= <regex>:<path to sound file>, <regex>:<path>,
456         (Requires "Sound support"; check your version info)
457         (Ordered list option)
458         Plays the sound file if a message contains regex. In case of
459         multiple matching regexes, only the sound of the last regex
460         is played. The regex should not include commas or colons.
461         For example
462              sound += LOW HITPOINT WARNING:sound\sounds2\danger3.wav
463         There are certain pre-defined regexes, as well, which can be
464         used to get a sound to trigger for something that cannot
465         otherwise be matched using a regex string. For example,
466         using FIRE_PROMPT_SOUND for the regex will cause Crawl to
467         play a sound whenever the fire prompt is opened. Check
468         sound.h for a full listing of all these pre-defined regex
469         strings.
470
471 sound_file_path = <path>
472         When playing sounds (with the option above), the contents of
473         this variable is appended to the start of the path. This is
474         intended to make it easier to take one configuration across
475         several platforms. These two lines are equivalent to the
476         example above:
477              sound_file_path = sound\sounds2\
478              sound += LOW HITPOINT WARNING:danger3.wav
479         The most recent instance of this option is the one that
480         takes effect, and is not applied retroactively to previous
481         instances of the sound option.
482
483 one_SDL_sound_channel = false
484         When true, only one sound can play at a time (if using SDL).
485         Is false by default since non-SDL sound backends don't
486         support such control.
487
488
489 3-  Interface.
490 ==============
491
492 3-a     Picking up and Dropping.
493 --------------------------------
494
495 autopickup = $?!+"/
496         The above is the default list. The valid symbols are
497         )       Weapons
498         (       Missiles
499         [       Armour
500         /       Wands
501         ?       Scrolls
502         " or =  Jewellery
503         !       Potions
504         + or :  Books
505         |       Staves
506         0       Orbs
507         }       Misc. items
508         $       Gold
509         Note that _whether_ items are picked up automatically or not, is
510         controlled by the in-game toggle Ctrl-A. Also note that picking
511         up takes a turn, but only one turn (regardless of the number of
512         items). If you teleport or blink onto a square with interesting
513         items, these will not be picked up.
514
515 autopickup_exceptions ^= <pickup-regex, >don't-pickup-regex, ...
516         (Ordered list option)
517         A set of regexes that force matching items to be picked up (if
518         prefixed with <), or never picked up (if prefixed with >).
519         Excludes (>) take precedence over includes (<), so if the same
520         item is matched by both an exclude and an include, it will not
521         be subject to autopickup.
522
523         An example:
524              autopickup_exceptions += <curare-tipped dart
525         Forces autopickup to grab all curare-tipped darts, even if
526         missiles are not set in the "autopickup" option.
527
528         Whitespace between <> and the match expression is significant,
529         so the following won't work:
530              autopickup_exceptions += <   box of beasts
531
532         autopickup_exceptions replace the older ban_pickup. Using
533              autopickup_exceptions += >uselessness, >inaccuracy
534         is the same as using
535              ban_pickup += uselessness, inaccuracy
536
537         If the regexes are not prefixed with < or >, > is implied, so
538         the option setting above can also be written as
539              autopickup_exceptions += uselessness, inaccuracy
540
541         You can use multiple autopickup_exceptions lines. Some examples:
542              autopickup_exceptions += inaccuracy, immolation
543              autopickup_exceptions += uselessness, noise, torment
544
545         Unless you clear the list of exceptions, you won't need to set
546         autopickup exceptions for potions except maybe for very special
547         cases.
548
549 default_autopickup = true
550         When set to false, the game starts with autopickup turned off.
551         You can still toggle autopickup in-game with Ctrl-A.
552
553 pickup_thrown = true
554         pickup_thrown = true causes autopickup to pick up thrown/fired
555         missiles, which can make life much easier for hunter types. Be
556         aware that autopickup uses a turn, though it won't trigger if
557         there are hostile monsters in sight.
558
559 assign_item_slot = (forward | backward)
560         When picking up items, the inventory slot into which the item
561         goes is normally the first free slot from a-zA-Z (this is the
562         default "forward" behaviour). Setting assign_item_slot to
563         "backward" changes the slot assignment to the first letter after
564         the last slot.
565         For instance, if you have items on 'a' and 'c', then with
566           assign_item_slot = forward, the next item will go into 'b',
567           assign_item_slot = backward, the next item will go to 'd'
568         instead.
569         With "backward", items dropped/fired and picked up later are
570         more likely to get their old slot back.
571
572 pickup_menu_limit = 1
573         If there are more items than this on your square, a menu will be
574         displayed when picking up multiple items instead of prompting for each
575         item. If zero, never use the menu. If negative, use the value of
576         item_stack_summary_minimum - 1, instead.
577
578         Note that no matter the value of the option, picking up will always
579         take one turn.
580
581 drop_filter += <regex>, <regex>, ...
582         (List option)
583         When selecting items using the global (de)select keys (',' or
584         '-') in a multidrop menu, you can choose to select only items
585         that match a search regex using this option.
586
587         For instance, to quickly select items forbidden by your god, you could
588         use:
589              drop_filter += forbidden
590
591         drop_filter will match against the same keywords menu_colour uses,
592         except that it lacks identification status. It defaults to
593         useless_item.
594
595         When a drop_filter is set, using the select/deselect keys will
596         set/clear selection of items that match the filter
597         expression(s).
598
599 auto_hide_spells = false
600         When set to true, spells added to the library will automatically be
601         hidden.
602
603 3-b     Passive Sightings (detected or remembered entities).
604 ------------------------------------------------------------
605
606 detected_monster_colour = lightred
607         Detected monsters will be given this colour.
608
609 detected_item_colour = green
610         Detected items will be given this colour.
611
612 remembered_monster_colour = darkgrey
613         The colour for monsters you have seen before.
614
615 3-c     Branding (Item and monster highlighting).
616 -------------------------------------------------
617
618 Branding refers to displaying particular monsters (e.g. summons) or
619 items in a special way; special as in reversing fore- and background.
620 There are several branding choices (these will not work everywhere; it
621 depends on OS and terminal):
622    standout         -- often the same as reverse, might be underline or
623                        dim
624    bold             -- used by colour curses for brightening foreground
625                        colours
626    blink            -- used by colour curses for brightening background
627                        colours
628    reverse          -- this will probably work
629    dim              -- probably no effect
630    underline        -- this will probably work
631    highlight:colour -- set background colour of branded monsters to
632                        "colour"
633 The last can be abbreviated to hi:colour.
634 See part DOS and Windows (5-b) for dos_use_background_intensity.
635
636 By default, only two of the item brands are active (and set to reverse):
637    heap_brand, feature_item_brand
638 They can be deactivated by setting them to "none".
639
640 friend_brand = hi:green
641         Brand friends in some way. This is very helpful for summoners. The
642         default setting shows friends with a green background. If the friend is
643         itself green, it'll show up as black on green.
644
645 neutral_brand = hi:lightgrey
646         Brand neutral monsters in some way. Useful both to get out of
647         a neutral monster's path, and to avoid accidentally killing it.
648         The default setting shows neutrals with a dark grey background. Since
649         there are no darkgrey monster glyphs anymore, this works fine.
650
651 stab_brand = hi:blue
652         Some deities object to you stabbing monsters. Certain backgrounds
653         specialise in stabbing monsters. Still other characters are
654         happy if they spot a monster before the monster spots them. In
655         all these cases, it helps to identify monsters that are unaware
656         of the character (and hence susceptible to being stabbed) without
657         using the 'x' command. All the normal 'brand' options apply.
658
659 may_stab_brand = hi:yellow
660         Stabbing may be possible even if the monster is not asleep (if
661         it's confused or distracted, for instance). This option brands
662         monsters that you *might* be able to stab.
663
664 heap_brand = reverse
665         Brand heaps of items (more than one item or stack).
666
667 feature_item_brand = reverse
668         Brands features (stairs, shops, altars) that would otherwise be
669         hidden by items. If you use this brand, the items on the square
670         are hidden by the feature symbol and the feature symbol is
671         branded.
672
673 trap_item_brand = reverse
674         Brands traps that would otherwise be hidden by items. If you
675         use this brand, the items on the square are hidden by the trap
676         symbol (^) and the trap symbol is branded.
677
678 3-d     Level Map Functions.
679 ----------------------------
680
681 level_map_cursor_step = 7
682         How many squares the cursor moves on the level map when using
683         Shift-direction.
684
685 3-e     Viewport Display Options.
686 ---------------------------------
687
688 The viewport is the portion of the map that is displayed during normal
689 play. The viewport is 33x17 by default, but if you use larger terminal
690 sizes, you can set these options to make the game show a larger
691 viewport. (These options are not fully available on DOS.)
692
693 None of these options affects gameplay. In particular, your character's
694 line-of-sight is unaffected by these options.
695
696 view_max_width = 33 (max 81)
697         Sets the maximum width of the viewport (defaults to 33).
698         Making this larger will allow Crawl to show a wider viewport
699         on larger terminals. This is ignored in tiles, the viewport will
700         always use all the available space.
701
702 view_max_height = 21 (max 71)
703         Similar to view_max_width, but sets the viewport's maximum height.
704         In tiles, this value is used to set when space starts to be affected
705         to the message area instead of the viewport. When the message area
706         reaches msg_max_height, the remaining space goes to the viewport.
707         If for performance reason you need a smaller viewport, either reduce
708         the window size, or increase the message area.
709
710 * Note that using large viewports can slow the game down.
711
712 view_lock_x = true
713         Keeps the player character centred horizontally in the
714         viewport, continuously scrolling the viewport to match the
715         PC's movements. If this is not set, the player character can
716         move horizontally within the viewport, and the viewport will
717         scroll only when the character's line-of-sight reaches the
718         left or right edge.
719
720 view_lock_y = true
721         Keeps the character centred vertically in the viewport.
722
723 view_lock = true
724         Aliased option that sets both view_lock_x and view_lock_y.
725
726 centre_on_scroll = false
727         If this is set, the viewport centres on the player character
728         whenever it scrolls (this option is irrelevant if view_lock_x
729         and view_lock_y are set).
730
731 symmetric_scroll = true
732         If this is set, the viewport will scroll in a manner consistent
733         with the character movement that caused the scroll.
734
735         To illustrate, let's say the PC is at the lower edge of the
736         viewport, but is near the horizontal centre. Now the PC moves
737         diagonally down and right, forcing the viewport to scroll up
738         one line. If symmetric_scroll is set, the viewport will also
739         scroll left one column to match the PC's diagonal movement. If
740         symmetric_scroll is not set, the viewport will only scroll up,
741         not horizontally. symmetric_scroll can be less disorienting
742         than free scrolling.
743
744         This option is not relevant if view_lock or centre_on_scroll
745         are set.
746
747 scroll_margin_x = 2
748         How far from the left or right edges scrolling starts. By
749         default, if the PC's square of line-of-sight is closer than
750         two squares from the edge, the viewport scrolls. If set at
751         zero, the viewport scrolls only when the LOS circle reaches
752         the viewport edge.
753
754 scroll_margin_y = 2
755         How far from the top or bottom edges scrolling starts.
756
757 scroll_margin = 2
758         An aliased option that sets both scroll_margin_x and
759         scroll_margin_y.
760
761 always_show_exclusions = true
762         If true, display travel exclusions and their exclusion radius in
763         the viewport. Exclusions are always visible on the level map
764         (access with X) regardless of the value of this option.
765         Exclusions are also visible in terrain-only mode (access with |).
766         This option has no effect in tiles builds, where exclusions are
767         always shown both in the viewport and on the level map.
768
769 3-f     Travel and Exploration.
770 -------------------------------
771
772 travel_delay = 20 (defaults to -1 for online servers)
773         How long travel waits after each move (milliseconds), and also
774         how long auto-explore waits after each move unless explore_delay
775         is set. Depends on platform. Setting to -1 will jump to end of
776         travel - you will not see the individual moves.
777
778 explore_delay = -1
779         How long auto-explore waits after each move (milliseconds). Depends on
780         platform. In particular, setting travel_delay = -1 and
781         explore_delay = 20 means you will see the individual moves of
782         autoexplore, but not the individual moves of other forms of travel.
783         Setting to -1 means the auto-explore delay will be the same as
784         travel_delay.
785
786 rest_delay = 0 (defaults to -1 for online servers)
787         How long resting waits after each move (milliseconds). Depends on
788         platform. Setting rest_delay = -1 will prevent the display updating
789         during resting.
790
791 travel_avoid_terrain = (shallow water | deep water)
792         Prevent travel from routing through shallow water. By default,
793         this option is disabled. For merfolk and/or characters with
794         permanent flight,
795              travel_avoid_terrain = shallow water, deep water
796         will prevent travel or explore from going through any water.
797         This option is not a true list option; in particular, it is not
798         possible to reset the option or to remove terrain types.
799
800 explore_greedy = true
801         Greedy explore travels to items that are eligible for
802         autopickup in addition to exploring the level, but is
803         otherwise identical to regular explore. Explore greed is
804         disabled if autopickup is off (Ctrl-A).
805
806 explore_stop  = items,stairs,shops,altars,portals,branches,runed_doors
807 explore_stop += greedy_pickup_smart,greedy_visited_item_stack
808         (List option)
809         Explore will stop for one of these conditions. Whatever you
810         set this option to, anything that stops travel will also stop
811         explore.
812
813         The "branches" condition stops for branch entrances but not for
814         other kinds of stairs or portals.
815
816         NOTE: runrest_ignore_message has no effect on explore_stop.
817
818         When using non-greedy explore, items causes explore to stop
819         when any new item comes into view. When using greedy explore,
820         the conditions act as follows:
821
822         items: stop when items that aren't eligible for autopickup come
823             into view.
824
825         greedy_items: stop when items that are eligible for autopickup
826             come into view.
827
828         greedy_pickup: stop after you automatically pick up any item
829             eligible for autopickup, excluding gold, but including
830             items thrown/fired by the player. You can make certain items
831             *not* trigger this with the option explore_stop_pickup_ignore
832
833         greedy_pickup_gold: stop when automatically picking up gold during
834             greedy explore.
835
836         greedy_pickup_smart: Similar to greedy_pickup, but tries to be
837             smart about it, meaning only stopping for items which aren't
838             similar to any you already have in your inventory. It
839             doesn't stop for automatically picking up items which were
840             thrown/fired by the player; you can add "greedy_pickup_thrown"
841             if you want to stop for those.
842
843         greedy_pickup_thrown: Stops after you pick up any item you've
844             thrown/fired. greedy_pickup automatically does this, but
845             greedy_pickup_smart does not. explore_stop_pickup_ignore
846             does not affect this condition.
847
848         greedy_visited_item_stack: Stop when visiting a stack of items
849             previously unknown to the player, even if the stack contains
850             nothing eligible for autopickup.
851
852         glowing_items: like items, but only for items which are
853             glowing/runed/embroidered/etc.
854
855         artefacts: like items, but only for artefacts.
856
857         runes: like items, but only for runes.
858
859 explore_stop_pickup_ignore += <regex>, <regex>, ...
860         (List option)
861         If explore_stop has greedy_pickup or greedy_pickup_smart set,
862         then picking up any items matching any of the regexes in the list
863         will *not* stop auto-explore.
864
865         This option has no effect on items which were thrown by the player.
866
867 explore_wall_bias = 0
868         Adjusts how much autoexplore favours attempting to discover room
869         perimeters and corners. At higher values, autoexplore will more
870         heavily favour visiting squares that are next to walls; at 0 it
871         will not favour them at all.
872
873 travel_key_stop = true
874         If set to true then travel will stop at any keypress.
875
876 travel_one_unsafe_move = false
877         If set to true then travel will make one move before conducting safety
878         checks for nearby danger.
879
880 tc_reachable      = blue
881 tc_dangerous      = cyan
882 tc_disconnected   = darkgrey
883 tc_excluded       = lightmagenta
884 tc_exclude_circle = red
885         The above five settle the colouring of the level map ('X').
886         They are
887           reachable: all squares safely reachable (without leaving the
888                      level)
889           dangerous: squares which are only connected to you via traps,
890                      etc.
891           disconnected: squares which cannot be reached without leaving
892                         the level
893           excluded: the colour for the centre of travel exclusions ('e')
894           excluded_circle: the colour for travel exclusions apart from
895                            centre
896
897 runrest_ignore_message += <regex>, <regex>, ...
898 runrest_stop_message += <regex>, <regex>, ...
899         (List option)
900         Use these to force messages to interrupt travel and resting, or
901         not. These are matched against full message text. To limit a
902         substring match to a message channel, prefix the substring with
903         the channel name and a colon (see section 3-k below on Message
904         Channels). For instance, if you want travel to stop when you're
905         hit by divine retribution, you could use:
906              runrest_stop_message += god:wrath finds you
907         Or to remind yourself to renew expiring spells:
908              runrest_stop_message += Your transformation is almost over
909              runrest_stop_message += You are starting to lose your buoyancy
910         Or you can explicitly ignore some messages:
911              runrest_ignore_message += pleased with you,exalted
912
913         Note that monster talk and dungeon noises already do not
914         interrupt running or resting, by default.
915
916         Multiple lines can be used. The earliest match among both
917         ignore and stop messages overrides later lines. The file
918         runrest_messages.txt contains a number of default settings.
919
920         Resetting either option has the effect of resetting both.
921
922         Note also that runrest_ignore_message has no effect on what
923         explore_stop stops for.
924
925 interrupt_<delay> += <activity_interrupt_type>, <activity_interrupt_type>, ...
926         (List option)
927         Use this option to not interrupt a delayed action on a certain trigger.
928         To find the name of a delay type, look for the name() function in
929         delay.h. The list of interruption types is in activity_interrupt_names.
930         For example, use
931             interrupt_travel -= sense_monster
932         to not interrupt autotravel when a monster is sensed but not seen.
933
934 delay_safe_poison = <% of hp>:<% of mhp>
935         Poison damage will be ignored if it is projected to drop your hp
936         by less than x% of your current hp and less than y% of your max
937         hp if you have defined delay_safe_poison = x:y. This applies to all
938         delays. Only one delay_safe_poison line is considered. Note that for
939         this to work with running and resting, Crawl needs to know to ignore
940         the "You feel sick" messages as well as the damage. For example,
941              runrest_ignore_message ^= You feel.*sick
942              delay_safe_poison = 80:100
943         are the defaults.
944
945 runrest_ignore_monster ^= <regex>:<distance>, <regex>:<distance>, ...
946         (Ordered list option)
947         Any monster matching the regular expression will only interrupt your
948         activity if the distance between you and the monster is less than the
949         specified number. E.g. with
950              runrest_ignore_monster ^= bat:3
951         bats, vampire bats, fire bats, and battlespheres will be considered
952         safe for travel, explore and resting as long as the distance is at
953         least 3. If a monster matches multiple expressions, its distance is
954         compared with the first match.
955
956 rest_wait_both = false
957         If rest_wait_both is set to true then resting will only stop
958         when both HP and MP are fully restored, not when either one of
959         them is restored.
960
961 rest_wait_ancestor = false
962         If rest_wait_ancestor is set to true then resting will only stop when
963         the ancestor's health is fully restored in addition to player HP or MP
964         (or both, if rest_wait_both is set).
965
966 rest_wait_percent = 100
967         When resting, if your HP or MP is below this percentage of being full,
968         it will stop resting when this percent of maximum HP or MP is refilled.
969         Resting after this point will still rest up to 100%.
970
971 explore_auto_rest = true
972         If true, auto-explore waits until your HP and MP are both at
973         rest_wait_percent before moving.
974
975 auto_exclude += <monster name>, <monster name>, ...
976         (List option)
977         Whenever you encounter a sleeping or stationary monster during
978         exploration that is included in this list, a travel exclusion is
979         automatically set centred on this monster, meaning autoexplore won't
980         ever bring you into its line of sight. If the monster dies or wakes up
981         while you are in sight, this exclusion is automatically removed again.
982
983 3-g     Command Enhancements.
984 -----------------------------
985
986 auto_switch = false
987         This option will allow you to automatically switch to an appropriate
988         weapon when attacking in melee, as long as the one you are wielding
989         and the one you switch to are both in slot 'a' or 'b'.
990
991 travel_open_doors = (avoid | approach | open)
992         Configure how autoexplore/travel interacts with doors.
993            avoid = Autoexplore/travel will treat closed doors like walls. If
994                    the only way for exploration or travel to continue is through
995                    a closed door, it will stop by a closed door.
996         approach = Autoexplore/travel will not open doors, instead stopping
997                    in front of any door in its path.
998             open = Autoexplore/travel will open doors. (default)
999         This does not affect runed doors, which are always avoided.
1000
1001 easy_unequip = true
1002         Allows auto removal of armour and jewellery when dropping it.
1003
1004 equip_unequip = false
1005         If this is true, selecting an already-equipped piece of equipment via
1006         the 'w', 'W' or 'P' menus (for weapons, armour or jewellery
1007         respectively) will unequip that item.
1008
1009 jewellery_prompt = false
1010         If this is true, equipping rings will always prompt for the slot to
1011         use, instead of automatically equipping the ring if there is an
1012         available empty slot. Unequipping jewellery will also always prompt for
1013         an item to remove, instead of skipping the prompt if only one item
1014         of jewellery is equipped.
1015
1016 easy_confirm = (none | safe | all)
1017         Make confirmation questions easier to answer:
1018            none = force capitals on Y/N questions and stat increases
1019            safe = force only on dangerous questions and stat increases (default)
1020             all = never force capitals
1021         WARNING TO PUTTY USERS: If your Putty configuration sets the
1022         numeric keypad to "NetHack mode", the keypad '7' will be mapped
1023         to the letter 'y', which can result in accidentally answering
1024         yes to questions.
1025
1026 simple_targeting = false
1027         If set to true, disables smart targeting for explosion and bouncing
1028         bolt spells, making them automatically target the closest monster in
1029         range rather than trying to find a spot that affects multiple monsters
1030         while avoiding the player. This applies to target selection when
1031         zapping as well as autotarget selection for quivered spells.
1032
1033 force_targeter = hailstorm, starburst, frozen ramparts, absolute zero, ignition,
1034                  eringya's noxious bog
1035         Force showing a targeter for the listed spells when casting normally,
1036         even if the spell isn't targeted. This for practical purposes only has
1037         an effect on statically targeted spells, such as the ones in the
1038         default value; it is particularly useful for spells with an unusual
1039         targeting pattern. If "all" appears in the options list, the rest of
1040         the list (however constructed) will be ignored, and targeters will
1041         be shown with every spell.
1042
1043 allow_self_target = prompt
1044         Allow targeting yourself with risky magic (e.g., the spell Bolt of Magma
1045         or a wand of paralysis.) Values: (yes | no | prompt).
1046         When set to 'yes', you are a valid target. When set to 'no', you cannot
1047         target yourself with such spells. When set to 'prompt' (the default),
1048         you will be required to confirm self-targeting. This option has no
1049         effect on area-effect spells, such as Mephitic Cloud, where you are
1050         always a valid target.
1051
1052 easy_quit_item_prompts = true
1053         Setting this option to true allows the quitting of item listing
1054         with Space (as well as Escape, which always works). These lists
1055         are essentially all of those that are requesting an inventory
1056         item and accept '?' and '*'. The identify list will never easy
1057         quit.
1058
1059 ability_menu = true
1060         Always show the full-screen 'a'bility menu. If false, 'a' prompts
1061         in the message area, and the menu can be seen with '?' or '*'.
1062
1063         Setting this option to false has no effect in Android tiles builds.
1064
1065 easy_floor_use = true
1066         If set to true, item interaction menus that allow using items from the
1067         ground will respond to switching from inventory items to floor items by
1068         pressing ',' whenever there is only one floor item, by selecting that
1069         item rather than toggling the menu. For example, 'r,' will read the
1070         scroll on the ground, if there is only one. This will work even if
1071         there are no matching items in your inventory.
1072
1073 sort_menus = [menu:](true | false | auto:X)[:sort_order]
1074         Controls if and how items are sorted in inventory and pickup
1075         menus.
1076
1077         When sort_menus = false (the default), items are not sorted, and
1078         will be ordered by inventory letter (or in the order they're
1079         stacked for items on the floor).
1080
1081         When sort_menus = true, items are sorted according to the specified
1082         sort_order, with the default being:
1083              equipped, basename, qualname, curse, qty
1084
1085         If sort_menus = auto:X, items are sorted if there are at least
1086         X items in the same category. For instance:
1087              sort_menus = auto:5
1088         will sort item classes that have at least 5 items. For instance,
1089         having 4 kinds of potions would not sort them, but having 5
1090         would.
1091
1092         You can explicitly specify sort criteria in the sort_menus
1093         option as:
1094              sort_menus = true : art, basename, qualname, curse, qty
1095
1096         Two items will be compared based on the first sort criteria
1097         where they differ. So with the sort_menus line given above,
1098         if only one of two different items is a known artefact, it will be
1099         listed first, else (if both or neither are artefacts) if their
1100         basenames are different they will be alphabetically compared using
1101         their basenames; if the basenames are the same but the qualified
1102         names are different it will compare their qualified names, and so
1103         on.
1104
1105         The available sort criteria are:
1106
1107         * basename:
1108           This is the name of the item type. The basename for all of
1109           "a +0 robe", "an embroidered robe" and "the cursed +2 robe of
1110           Ponies" is just "robe". The basename for both of "a brass
1111           ring" and "a ring of fire resistance" are "ring".
1112
1113         * qualname:
1114           The name of the item without articles (a/an/the), quantities,
1115           enchantments, or curse-status. The qualified names for the
1116           robes described above are "robe", "embroidered robe" and "robe
1117           of Ponies", respectively. The qualified names for the rings
1118           described above are "brass ring" and "ring of fire
1119           resistance", respectively.
1120
1121         * fullname:
1122           This is the name of the item as displayed in menus (including
1123           (quantities, curse-status, etc.)
1124
1125         * dbname:
1126           Sorts based on an item's unique internal name which is linked
1127           to its description. Items with the same description will be
1128           grouped together.
1129
1130         * curse:
1131           Curse-status of the item (if known). Uncursed items show up
1132           first.
1133
1134         * equipped:
1135           Equipped items show up first.
1136
1137         * art:
1138           Identified artefacts show up first.
1139
1140         * ego:
1141           Identified ego items show up first.
1142
1143         * glowing:
1144           Unidentified glowing/shiny/runed/etc items show up first.
1145
1146         * identified:
1147           Identified items show up before unidentified ones of the
1148           same type. An item is regarded as identified once you know
1149           its subtype or ego.
1150
1151         * qty:
1152           The quantity for stackable items (such as scrolls, potions,
1153           etc.)
1154
1155         * slot:
1156           The inventory letter for items in inventory; irrelevant for
1157           items on the floor.
1158
1159         * charged:
1160           Makes wands known or assumed to have some charges left appear
1161           before wands known to be empty; irrelevant for all other item
1162           types.
1163
1164         You can ask for a descending order sort by prefixing one or more
1165         sort criteria with > as:
1166              sort_menus = true : basename, >qty
1167
1168         You can also request sorting only for specific menus:
1169              sort_menus = pickup: true
1170         or
1171              sort_menus = inv: true
1172         (Menu types must be specified as name:, with no space between
1173         name and colon.)
1174
1175         By default only pickup menus are sorted, and the sort criteria are:
1176              "equipped, basename, qualname, curse, qty".
1177         All other menus (drop, inv) will be sorted by inventory letter.
1178
1179         The menu selectors available are:
1180
1181         pickup: All pickup menus, stash-search menus, etc. for items not
1182                 in your inventory.
1183         drop:   The item drop menu.
1184         inv:    Inventory listings for any command (but not for dropping
1185                 items).
1186         any:    All menus; this is the default when unspecified.
1187
1188         For example,
1189              sort_menus = true : equipped, basename, qualname, curse, qty
1190         will produce the same inventory and drop menus as by default,
1191         with the exception that all worn/wielded items come first. This
1192         can be convenient if you use the '.' command to select
1193         subsequent items.
1194         If you define sort_menus differently for two or more selectors,
1195         the last one matching will always take precedence, i.e. "any"
1196         as last setting would override any of the others.
1197
1198 spell_slot ^= <regex>:<list of spell letters>
1199         (Ordered list option, one value per line)
1200         When you memorise any spell that matches the regex, it will assign
1201         itself to the first available letter in the list. A + in the list of
1202         letters turns on "overwrite mode": all letters up to the next "-" are
1203         considered available even if already assigned; in that case, any
1204         spell already assigned to that slot, as long as it does not also
1205         match the same <regex>, will be moved.
1206
1207         If all letters in the list are occupied for each regex the spell
1208         matches, it will use the default ordering abc...xyzABC..XYZ. If a
1209         spell matches multiple regexes, only the first is considered.
1210
1211         Examples:
1212         * if you want Apportation to be placed on A:
1213             spell_slot ^= Apportation:A
1214         * if you want Ozocubu's Armour to be placed on r normally or R if
1215           r is unavailable:
1216             spell_slot ^= Ozocubu's Armour:rR
1217         * if you want the first "Bolt" spell to be placed on a, even if
1218           there is already a non-bolt spell there:
1219             spell_slot ^= Bolt:+a
1220         * if you want to change the default spell slot assignment
1221           to use capital letters: (place this after all other
1222           spell_slot lines):
1223             spell_slot += .*:ABCDEFGHIJKLMNOPQRSTUVWXYZ
1224
1225 item_slot ^= <regex>:<inventory letters>
1226         (Ordered list option, one value per line)
1227         Uses the same interface as spell_slot, except that overwrite mode
1228         is on by default; overwrite mode can be disabled with a - in the
1229         list of letters.
1230
1231         Additionally, the item_slot option is applied on an item when it is
1232         identified, so it can be moved to the right place even if it was
1233         picked up unidentified.
1234
1235 ability_slot ^= <regex>:<ability letters>
1236         (Ordered list option, one value per line)
1237         Uses the same interface as spell_slot, but applies to abilities
1238         in the 'a' menu.
1239
1240 autofight_stop = 50
1241         Autofight will not act if your HP is at or lower than this
1242         percentage of your max HP. Disabled when set to 0. This setting applies
1243         both to autofight and to autofire.
1244
1245 autofight_warning = 0
1246         Enforce a minimum time (in milliseconds) between autofight commands.
1247         If you issue two consecutive autofight commands within this amount
1248         of time (for example, by holding down the tab key), the subsequent
1249         commands will be ignored, and the message "You should not fight
1250         recklessly!" printed to the danger channel. Any value less than
1251         or equal to zero disables this check.
1252
1253 autofight_throw = false
1254         If your quiver contains contains a fireable action that does direct
1255         damage to the enemy, regular CMD_AUTOFIGHT (i.e., tab on the default
1256         binding) will trigger it at enemies out of melee range. Without this
1257         option, only a wielded launcher (a bow, crossbow or sling) will be
1258         triggered by CMD_AUTOFIGHT. If an action that does direct damage is
1259         quivered but out of range, you will move towards the enemy. If an
1260         action is quivered that does not do direct damage, CMD_AUTOFIGHT will
1261         ignore it entirely.
1262
1263 autofight_throw_nomove = true
1264         This works same as above, except only for ===hit_closest_nomove rather
1265         than ===hit_closest; this is usually bound to shift-Tab.
1266
1267 autofight_fire_stop = false
1268         When firing missiles or throwing objects using autofight, if this
1269         option is true, shots will stop at the target (like "f.") rather than
1270         continuing past. Note that this setting may be decidedly suboptimal
1271         for missiles of penetration.
1272
1273 autofight_caught = false
1274         If true, autofight will attempt to escape webs or nets that are
1275         holding you, even if no enemies are in view.
1276
1277 autofight_wait = false
1278         If true, ===hit_closest_nomove while not in range of an enemy will
1279         wait for a turn instead of aborting autofight.
1280
1281 autofight_prompt_range = true
1282         When wielding a weapon that would normally cause a prompt on attacking
1283         (such as a weapon with a !a inscription, or one disliked by your god),
1284         if this option is true then the prompt will be displayed when autofight
1285         tries to walk towards an enemy, instead of only when actually trying
1286         to attack.
1287
1288 automagic_enable = false
1289         Option to enable the old automagic system; new players are recommended
1290         to just use quivered spells. If true, autofight (i.e. tab on the
1291         default bindings) will cast a spell in a designated slot at a target.
1292         Initial spell slot is a. (deprecated)
1293
1294 automagic_slot = a
1295         Setting this changes the initial spell slot for the old automagic
1296         system. Can be changed for games in progress in-game by setting a macro
1297         to call ===am_set_spell.
1298
1299 automagic_fight = false
1300         With the old automagic system enabled, setting this to true causes
1301         a fallback to regular autofight (e.g. melee) when trying to cast a
1302         spell that you either do not have enough magic points for, or are below
1303         the set threshold. If false, a message will appear and no further
1304         action is taken.
1305
1306 automagic_stop = 0
1307         Similar to autofight_stop, if magic points are below this number
1308         (percentage of total), casting via autofight/autofire is prevented.
1309         Disabled when set to 0.
1310
1311 fail_severity_to_confirm = 3
1312         Ask for confirmation when attempting to cast a spell where a miscast
1313         would cause severe penalties. Prompt if the miscast severity of the
1314         spell (the colour shown in the spellcasting menu) is greater than
1315         or equal to the number specified:
1316
1317           5: magenta (miscasting may deal greater damage than max HP)
1318           4: dark red (up to 70% damage)
1319           3: light red (up to 50% damage)
1320           2: yellow (up to 30% damage)
1321           1: white (up to 10% damage)
1322
1323         If the value 0 or -1 is given, never prompt about miscasts.
1324
1325 easy_door = true
1326         When (O)pening or (C)losing doors, do not prompt for a direction
1327         if there is only one adjacent door. This option does not affect
1328         opening doors by walking into them.
1329
1330 warn_hatches = false
1331         Ask for confirmation before using a one-way escape hatch or shaft.
1332
1333 enable_recast_spell = true
1334         If enabled, allows recasting the previously cast spell by pressing
1335         Enter or '.' at the spellcasting prompt.
1336
1337 confirm_action += <regex>, <regex>, ...
1338         (List option)
1339         Casting a spell or ability with a name matching any of the given regular
1340         expressions will prompt before use.
1341
1342 regex_search = false
1343         If enabled, searching for items with ^F uses regular expression syntax
1344         by default, instead of substring searching. Note that regardless of
1345         this setting, queries prefixed with / will be performed as a regular
1346         expression search and queries prefixed with = will be performed as a
1347         substring search.
1348
1349 autopickup_search = false
1350         If enabled, items are annotated with {autopickup} while searching
1351         with ^F if they would be picked up by autopickup. This means that
1352         searching for "autopickup" will list all such items. Note that this
1353         option may slow down your game if you have a complicated custom
1354         autopickup function.
1355
1356 bad_item_prompt = true
1357         Ask for confirmation before using bad or dangerous scrolls and potions.
1358
1359 3-h     Messages and Display Enhancements.
1360 ------------------------------------------
1361
1362 hp_warning = 10
1363         hp_warning gives "* * * LOW HITPOINT WARNING * * *" on the
1364         danger channel when the player takes damage and their hitpoints
1365         are less than this percentage of their maximum (use 0 to turn
1366         off these messages).
1367
1368 mp_warning = 0
1369         mp_warning gives "* * * LOW MAGIC WARNING * * *" on the danger
1370         channel when the player's magic points drop below this
1371         percentage of their maximum (use 0 to turn off these messages).
1372
1373 hp_colour = 50:yellow, 25:red
1374         (List option)
1375         hp_colour colours your Health appropriately in the status
1376         display. In the default setting, your health will appear in
1377         red if at less than 25%, yellow if at less than 50%, and in
1378         the default colour otherwise.
1379
1380 mp_colour = 50:yellow, 25:red
1381         (List option)
1382         mp_colour does to Magic what hp_colour does to Health.
1383
1384 stat_colour = 1:lightred, 3:red
1385         (List option)
1386         stat_colour colours your stats if they drop below a given value,
1387         in the order of their definition. This check takes place before
1388         the ones for e.g. Might or degeneration.
1389         For normal grey colouring, set it to
1390            stat_colour -= 3:red
1391
1392 status_caption_colour = brown
1393         Sets the colour that is used to display the captions in the status
1394         area (for instance the "Health:" in "Health: 10/10").
1395
1396 enemy_hp_colour = green green brown brown magenta red
1397         Colours enemy health appropriately in the monster pane. The
1398         colourings correspond to full health, lightly wounded, moderately
1399         wounded, heavily wounded, severely wounded, and almost dead.
1400
1401 clear_messages = false
1402         Setting this option to true will cause messages to cleared
1403         between player actions (default is false which will delay the
1404         clearing of messages until the message space is full).
1405
1406 show_more = true
1407         Setting this option to false will cause the game not to prompt
1408         if more than a window-full of messages are output at once. This
1409         option has no effect if clear_messages is set. Additionally, it
1410         has no effect on whether force_more_message triggers.
1411
1412 small_more = false
1413         With small_more = false (default), the --more-- prompt is on a
1414         separate line at the bottom of the message window. With
1415         small_more = true, it is just the bottom left character.
1416         Note: This will overwrite the first letter of the last message
1417               line if clear_messages is set.
1418
1419 show_newturn_mark = true
1420         When set to false, this option disables the underscore (_) displayed in
1421         front of the first line of a turn.
1422
1423 show_game_time = true
1424         By default, the counter in the stat area displays elapsed game time.
1425         Most actions take one unit of time, but some are quicker (putting on a
1426         ring, wielding a weapon, ...) and others are slower (swinging a weapon
1427         with low skill, changing armour, ...).
1428         When set to false, the counter will display player turns instead, which
1429         is the number of actions taken regardless of their duration. It is this
1430         turn count which is used for scoring (and this turn count is always
1431         visible on the % overview screen).
1432         The duration of the last action is displayed in parenthesis, after the
1433         time/player turns display.
1434
1435 equip_bar = false
1436         When set to true, this option replaces the noise bar with an
1437         "equipment bar" showing the glyphs of all currently equipped items,
1438         with gaps for available but currently unfilled equipment slots.
1439
1440 animate_equip_bar = false
1441         When set to true, any items displayed in the equipment bar that have a
1442         variable colour will be animated.
1443
1444 item_stack_summary_minimum = 4
1445         If you step over a stack with this number or more of items in
1446         it, the first description line will contain a summary of all the
1447         items in the stack (up to 50 items), in a format which looks
1448         like this:
1449           Items here: !! """ ( )))))) [[[
1450         Known artefacts will be coloured in yellow; glowing or runed
1451         items will be in white, unless you already know that they are
1452         not ego items.
1453
1454 mlist_min_height = 4
1455         If there is extra space available for the message area and
1456         monster list, the monster list will expand to this height
1457         before letting the message area get more.
1458         (Note that the monster list is only available for ASCII.)
1459
1460 mlist_allow_alternate_layout = false
1461         Display the monster list wherever Crawl may find space on
1462         your console display, usually to the left of the map, rather
1463         than using the fixed position below the stat area.
1464         This option is not supported in the tiles build.
1465
1466 monster_item_view_coordinates = false
1467         Display player-centred coordinates in the ^x view description.
1468
1469 monster_item_view_features += <regex>, <regex>
1470         (List option)
1471         Display features matching the <regex> in the ^x view description. Each
1472         <regex> is a regular expression describing a dungeon feature. This
1473         regex should match the description when using the 'x' command. In case
1474         the regex matches several descriptions, all such features are listed.
1475
1476         Two special keywords are active here, if any pattern matches the string
1477         "stair" all features that can be interacted with using the stair
1478         commands are shown; if any pattern matches "trap" all trap features
1479         (including webs) are shown.
1480
1481 msg_min_height = 7
1482         You can reduce this to give more space to the map display. The
1483         minimum value is 5. In console, if this value is large enough
1484         that the map won't fit, crawl will not start.
1485
1486 msg_max_height = 10
1487         In console, if there is extra space available after the monster list
1488         has expanded, the message area will expand up to this height.
1489         The monster list will get the rest.
1490         In tiles, control the maximum size of the message area. The viewport
1491         will get the rest.
1492
1493 msg_webtiles_height = -1
1494         This will set the height of the messages pane in (only) WebTiles,
1495         scaling the map accordingly. Values less than `msg_min_height` will
1496         have no impact; in this case the height of the message pane is
1497         inherited from console (and so will typically be 7). One of these
1498         lines may be reserved for `more` messages depending on other
1499         settings.
1500
1501 messages_at_top = false
1502         Put the message window at the top of the screen. This moves
1503         the last message close to the centre of the view when not
1504         using clear_messages=true.
1505
1506 msg_condense_repeats = true
1507         If the same message is repeated multiple times during the same
1508         turn, then it will be output in a condensed format indicating
1509         how many times it was repeated. If the same output (including the
1510         counter) is repeated over several turns, the Show Previous Message
1511         command (Ctrl-P) will likewise condense them into one. For example:
1512             The killer bee misses you. x5
1513
1514 msg_condense_short = true
1515         If set, short messages on the same channel don't all start a new
1516         line.
1517
1518 show_travel_trail = false (defaults to true for online servers)
1519         When set to true, the path taken during autoexplore or travel
1520         will be highlighted. The console colour and glyph of the travel trail
1521         can be further configured using the feature option to override the
1522         "travel trail" feature. If a travel trail is currently being displayed,
1523         the Clear Map command (Ctrl-C) clears the trail instead of the map
1524         (pressing it a second time then clears the map as usual).
1525
1526 skill_focus = true
1527         When set to true, skills cycle between disabled, enabled and focus in
1528         the skill screen. When set to false, they only toggle between enabled
1529         and disabled. Setting the option to "toggle" adds a toggle to the skill
1530         screen to change the behaviour in-game.
1531
1532 default_show_all_skills = false
1533         When set to true, the skill (m) menu defaults to showing all skills,
1534         even untrained and untrainable ones. As usual, '*' toggles back to
1535         trainable mode. This option does not affect hints and tutorial games.
1536
1537 monster_list_colour += <key>:<colour>, <key>:<colour>
1538 monster_list_colour -= <key>
1539         (List option)
1540         Change the colours used to display monster names in the monster list.
1541         Valid keys, and their default colours, are:
1542
1543            Monster attitudes:
1544              friendly       - green
1545              neutral        - brown ("indifferent")
1546              good_neutral   - brown ("peaceful")
1547              strict_neutral - brown ("fellow slime")
1548
1549            Threat levels for hostile monsters:
1550              trivial        - darkgrey
1551              easy           - lightgrey
1552              tough          - yellow
1553              nasty          - lightred
1554
1555          Removing a key with -= currently has the same effect as setting its
1556          colour to lightgrey.
1557
1558          Note that, for TSO worshippers, monsters whom it is forbidden to
1559          attack will appear in the "evil colour" (magenta by default)
1560          regardless of this option.
1561
1562 view_delay = 600
1563         Controls the speed of animations from, e.g., ranged and magical
1564         attacks and invocations with visual effects.
1565
1566 use_animations -= beam, range, hp, monster_in_sight, pickup, monster, player,
1567                   branch_entry
1568         Controls whether or not to run special animations, such as when being
1569         banished. All animations are enabled by default, and the categories
1570         that can be enabled/disabled independently are:
1571
1572           beam             - Animation for casting a beam spell or throwing a
1573                              ranged weapon.
1574           range            - Flashes the screen with an overlay indicating the
1575                              actual range of an attempted spell, if there are
1576                              no monsters within the spell's range.
1577           hp               - Flashes the screen red whenever you take damage
1578                              below the level indicated by the hp_warning
1579                              option.
1580           monster_in_sight - When attempting to rest, run, travel, or explore
1581                              with dangerous monsters in view, flashes the parts
1582                              of the screen where monsters aren't, in order to
1583                              help make the monsters themselves more visible.
1584           pickup           - Various animations that occur when picking up
1585                              items. Currently only runes and the orb have
1586                              animations.
1587           monster          - Animations that run when a monster uses an ability
1588                              or casts a spell.
1589           player           - Animations that run when the player uses an
1590                              ability or casts a spell.
1591           branch_entry     - Animations that run when you enter a new branch.
1592                              Currently only the Abyss and Zot have animations.
1593
1594 darken_beyond_range = true
1595         If set to true, everything beyond range when targeting will be
1596         coloured grey. Setting this to false will also disable the "range"
1597         category of the use_animations option.
1598
1599 force_more_message += <regex>, <regex>
1600         (List option)
1601         Any message that contains a regex specified here will enforce a
1602         --More-- prompt, so it can be used to highlight really important
1603         events. This option ignores the show_more option. This option will
1604         not interrupt travel delays by default; use runrest_stop_message
1605         for that instead. The syntax is identical to that of
1606         runrest_ignore_message (3-f).
1607
1608 flash_screen_message += <regex>, <regex>
1609         (List option)
1610         Any message that contains a regex specified here will flash the
1611         screen yellow, so it can be used to highlight very important events
1612         indeed.
1613         The syntax is identical to that of force_more_message.
1614
1615 cloud_status = true
1616         Whether to show the "Cloud" status light; defaults to true, except if
1617         playing with tiles, where you can see the cloud on top of you, where it
1618         defaults to false.
1619
1620 always_show_zot = false
1621         Whether to show the "Zot" status light at all times, even when you've
1622         got plenty of time left.
1623
1624 3-i     Colours (messages and menus)
1625 -----------------
1626
1627 menu_colour ^= <match>:<colour>:<regex>, <colour>:<regex>, ...
1628         (Ordered list option)
1629         This prints a line (of the inventory, a menu, or the discoveries
1630         screen) containing regex in the stated colour. There can be
1631         several statements in a list, and also several menu_colour
1632         lines. When using several menu_colour lines, the colour of the
1633         _first_ matching regex is applied. For a list of colours, check
1634         the colour option in 5-a.
1635
1636         The match specifies which listings are affected by the
1637         colouring. If you specify 'any', or completely skip the <match>:
1638         part, then all listings are used. Possible values for match are:
1639            ability       (the A screen)
1640            description   (the \ screen)
1641            equip         (the [, (, ), " screens)
1642            help          (the manual)
1643            inventory     (inventory and pickup menus)
1644            pickup        (specific to pickup menus)
1645            shop          (shop menus)
1646            notes         (the ?: screen)
1647            resists       (the % screen)
1648            spell         (the Z and I screens)
1649            stash         (the results from Ctrl-F)
1650            stats         (the player stats panel)
1651
1652         Crawl has a couple of prefixes defined to make inventory colouring
1653         easier. These are, in order of definition:
1654            identified      (The item is fully identified.)
1655            known           (You recognize the item's subtype.)
1656            unidentified    (You don't recognize the item's subtype.)
1657
1658         Items are also prefixed with their base type (armour, weapon, wand,
1659         etc.)
1660
1661         The following only apply to items whose subtype is known.
1662            forbidden       (Your god would hate it if you used this item.)
1663            emergency_item  (This item is invaluable in emergencies.)
1664            good_item       (This item is generally a good item.)
1665            dangerous_item  (Using this item can be dangerous.)
1666            bad_item        (This item is generally a bad item.)
1667            useless_item    (This item is of no use to you.)
1668
1669         The following apply only to items of certain base types, whether
1670         identified or not:
1671            inedible        (You cannot eat this, or get no nutrition from it.)
1672            equipped        (Equipped items.)
1673            artefact        (For artefacts, whether identified or not.)
1674            melee           (Melee weapons, including rods and magical staves.)
1675            ranged          (Ranged weapons.)
1676
1677         When looking for menu_colour matches, these prefixes are prepended to
1678         the actual item name, e.g. in the form of
1679            identified forbidden wand of random effects (4)
1680
1681         The same prefixes can also be used for highlighting prompts pertaining
1682         to items matching the description, or to define autopickup_exceptions.
1683
1684         If you want to colour all items that contain a certain prefix, use
1685           menu_colour ^= lightgreen:poisonous
1686
1687         To colour worn stuff and highlight cursed items (except where other,
1688         presumably more important, message colours match), use
1689           menu_colour += inventory:lightred:equipped.* cursed
1690           menu_colour += inventory:green:equipped
1691           menu_colour += inventory:red: cursed
1692
1693         To colour identified artefacts, try
1694           menu_colour ^= inventory:white:( [-+] the)
1695         or
1696           menu_colour ^= inventory:white:identified.*artefact
1697
1698         If you frequently die because you forget to use emergency items,
1699         try
1700           menu_colour ^= inventory:cyan:emergency_item
1701           menu_colour ^= inventory:lightcyan:wand of (acid|iceblast)
1702
1703         menu_colour can also be applied to colour the in-game notes (to
1704         be read with '?:'). The following line will show level ups in
1705         white:
1706           menu_colour ^= notes:white:Reached XP level
1707
1708 message_colour ^= <colour>:<channel>:<regex>, <colour>:<regex>, ...
1709         (Ordered list option)
1710         message_colour allows you to override colours for individual
1711         messages. For instance, if you find the low hp warning to be
1712         insufficiently attention grabbing, you could do something like
1713              message_colour += yellow:LOW HITPOINT WARNING
1714         You can also narrow the message match to a specific channel:
1715              message_colour += lightred:god:xom
1716         If you don't want to see a message at all, you can mute it:
1717              message_colour += mute:You start resting
1718
1719 3-j     Quivers, firing, and ammo.
1720 ----------------------------------
1721
1722 fire_items_start = a
1723         Sets the first inventory item to consider when cycling through missiles
1724         to fire via the quiver. The default is a.
1725
1726 fire_order  = launcher, throwing, inscribed, spell, evokable, ability
1727         (Ordered list option)
1728         Controls the order of items when cycling the quiver. Types
1729         should be separated by commas and items that appear first get
1730         higher priority. Absent action types are not used when cycling
1731         the quiver. This option also affects autoquivering on game start.
1732
1733         'launcher' refers to firing the appropriate missile for a
1734         wielded weapon (i.e. crossbow, bow, sling). 'throwing' refers to
1735         all throwing ammo. Specific throwing ammo types can be refered to
1736         by name ('javelin', 'boomerang', 'stone', 'rock', 'net', 'dart'),
1737         but order of these only affects order internal to throwing ammo
1738         types; 'inscribed' can also be used to control the order of ammo
1739         that has been inscribed with "+f". See the "Inscriptions" section of
1740         Crawl's manual for more information about inscriptions. Ammo types
1741         can be separated with a "/" to indicate that inventory order should
1742         determine cycle order. Order within types is determined by letter
1743         order in the relevant submenu (e.g. inventory for throwing, etc).
1744
1745 fail_severity_to_quiver = 2
1746         Exclude spells with this miscast level or higher from quiver cycling
1747         and automatic quivering. -1 can be used to exclude spells entirely from
1748         automatic quivering. See fail_severity_to_confirm for a breakdown of
1749         miscast values.
1750
1751 launcher_autoquiver = true
1752         If set to true, change the main quiver to launcher ammo on wielding
1753         that launcher; if set to false, the main quiver is unaffected by
1754         wielding a launcher. (Firing via tab or `v` still work.). This also
1755         affects rare artefacts that may be evoked.
1756
1757 (See also pickup_thrown in 3-a, and the various autofight settings in 3-g.)
1758
1759 3-k     Message Channels.
1760 -------------------------
1761
1762 Crawl communicates to the players with its message window. Every message
1763 belongs to one of the so-called channels. The behaviour of each channel
1764 can be changed with the option
1765
1766      channel.CHANNEL_NAME = (COLOUR | mute | default | on | off | plain)
1767
1768 CHANNEL_NAME can currently be one of these:
1769    plain           = regular text (and things "uncoloured")
1770    prompt          = input prompts to the player
1771    god             = messages from the gods
1772    duration        = messages about character spells/effects wearing off
1773    danger          = serious threats to the character's existence
1774    warning         = various other warnings
1775    recovery        = recovery from disease/stat loss/poison conditions
1776    talk            = monsters talking
1777    talk_visual     = monster performing some action that the player sees
1778    timed_portal    = portal timeout messages
1779    sound           = other sounds
1780    intrinsic_gain  = level/stat/species power gains
1781    mutation        = gain/lose mutations
1782    monster_spell   = messages about monsters gesturing or casting spells
1783    monster_enchant = messages pertaining to monster enchantments
1784    monster_warning = monsters coming into view
1785    friend_spell    = as monster_spell, but only for friendly monsters
1786    friend_enchant  = as monster_enchant, but only for friendly monsters
1787    friend_action   = other actions by friendly monsters
1788    monster_damage  = messages telling how damaged a monster is
1789    monster_target  = messages marking the monster as a target (unused)
1790    banishment      = messages about banishing and being banished to the Abyss
1791    equipment       = messages indicating worn/wielded equipment
1792    floor           = messages when looking at or walking over a floor item
1793    multiturn       = indicates long actions (wearing armour, dissecting etc.)
1794    examine         = messages from examining your surroundings
1795    examine_filter  = boring messages from examining your surroundings
1796    diagnostic      = debugging messages
1797    error           = error messages
1798    tutorial        = messages from the tutorial
1799    orb             = messages about the Orb of Zot
1800    hell_effect     = messages about environmental effects of the Hells
1801    dgl_message     = messages from watchers (online console games only)
1802
1803 The channel options are
1804    mute      = show no messages from channel (dangerous, be careful!)
1805    default   = turn channel on to its default scheme
1806    alternate = turn channel on to its alternate "colourful" scheme
1807    on        = same as default
1808    plain     = make channel the same colour as the "plain" channel
1809                (won't do anything silly like "mute" if plain == mute,
1810                though)
1811    off       = same as plain
1812
1813 COLOUR can be any of the colours described in section 5-a (colour option).
1814
1815 The only multi-colour channels currently are monster_damage and god. All
1816 other channels are defaulted to on.
1817
1818 3-l     Inscriptions.
1819 ---------------------
1820
1821 See the "Inscriptions" section of the crawl manual for more information
1822 about inscriptions.
1823
1824 autoinscribe += <regex>:<inscription>
1825         (Ordered list option, one value per line)
1826         Any item whose description contains the regex will be automatically
1827         inscribed (if autopickup is toggled on).
1828
1829         For example, it can be used to avoid accidentally using charges of
1830         potentially dangerous wands, as in
1831              autoinscribe += wand of polymorph:!V
1832
1833         The menu colour prefixes (forbidden etc.) can also be used here.
1834         For example:
1835              autoinscribe += (bad|dangerous)_item.*scroll:!r
1836         will prevent accidentally reading any identified bad or
1837         potentially dangerous scrolls.
1838
1839         Unlike most ordered list options, multiple matching entries all have
1840         an effect: the order only determines the order of the inscriptions.
1841
1842 show_god_gift = unident|yes|no
1843         Appends {god gift} to items that originated as one. If set to
1844         "unident", items will lose this tag once their properties are
1845         fully known. Regardless of this setting, you can see the item's
1846         origin in its description.
1847
1848 3-m     Macro related Options.
1849 ------------------------------
1850 macros += M \{9} za
1851         This options adds a macro or keymap.
1852
1853         Each definition consists of exactly three arguments separated by
1854         spaces. The first one describes whether it is a macro or a keymap:
1855         "M" macro,
1856         "K"  default context keymap,
1857         "K1" level-map context keymap,
1858         "K2" targeting context keymap
1859         "K3" confirmation context keymap.
1860
1861         The second argument describes the trigger key and consists the
1862         character or keycode of that key (for example 'a', 'A' or \{9} for the
1863         A, Shift-A or Tab keys). The third argument describes the macro or
1864         keymap action and consists the command sequence to be associated with
1865         the second argument. (for example "zap" for zapping the spell in slot a
1866         at the previous target).
1867
1868         If you have any macros/keymaps in your rc file, they will automatically
1869         be saved to your macro.txt file on load, silently overriding any
1870         macros/keymaps already saved to your macro.txt file.
1871
1872         This syntax is based on but not identical to the format used in the
1873         macro.txt file.
1874
1875 flush.failure = true
1876 flush.command = false
1877 flush.message = false
1878         These are useful when using macros. Setting one of these
1879         sub-options to true will cause the entire input buffer to be
1880         dumped and thus effectively stop the macro. The sub-options
1881         currently are
1882            failure -- when spells/abilities get miscast
1883            command -- whenever the game is about to get the next command
1884            message -- whenever the game outputs a non-mute message
1885
1886 additional_macro_file = path/to/filename
1887         Add an additional macro file to be loaded after macro.txt.
1888         You can have multiple additional_macro_file lines.
1889
1890 bindkey = [^D] CMD_BUTCHER
1891         Change which key invokes which command at a lower level of
1892         operation than macros. Useful in that macros cannot (yet)
1893         invoke each other, but a macro can invoke a command whose
1894         key has changed.
1895         The syntax is always the same: [key] command
1896         First, in square brackets, list the key you want to use, with
1897         ^X meaning Ctrl-X. After that name the command to be bound to
1898         that key. You can bind several commands to the same key, as long
1899         as they take effect in different areas of the game, i.e. one
1900         targeting command and one for the main game. Likewise, you can
1901         bind the same command to different keys.
1902         For a full list of possible commands, see keybind.txt.
1903
1904 3-n     Tiles Options.
1905 ----------------------
1906 In non-tile games the tile options are ignored.
1907
1908 tile_show_items = <glyphs>
1909         This option controls the order of items in the tiles
1910         inventory. By default, its value is: !?/=([)}:|
1911         Items with glyphs not in the list will be shown last.
1912
1913 tile_skip_title = false
1914         When this is set to true, you won't be prompted for a key at the title
1915         screen when the game has finished loading and will be taken directly to
1916         the starting menu.
1917
1918 tile_menu_icons = true
1919         Causes inventory menus and a few other ones to include tiled icons
1920         and the menus to be displayed in up to two columns to make up for
1921         the reduction of space.
1922         If you would rather have the plain menus set this option to false.
1923
1924 tile_player_col              = white
1925 tile_monster_col             = #660000
1926 tile_neutral_col             = #660000
1927 tile_peaceful_col            = #664400
1928 tile_friendly_col            = #664400
1929 tile_plant_col               = #446633
1930 tile_item_col                = #005544
1931 tile_unseen_col              = black
1932 tile_floor_col               = #333333
1933 tile_wall_col                = #666666
1934 tile_mapped_floor_col        = #222266
1935 tile_mapped_wall_col         = #444499
1936 tile_explore_horizon_col     = #6b301b
1937 tile_door_col                = #775544
1938 tile_downstairs_col          = #ff00ff
1939 tile_upstairs_col            = cyan
1940 tile_branchstairs_col        = #ff7788
1941 tile_portal_col              = #ffdd00
1942 tile_transporter_col         = #0000ff
1943 tile_transporter_landing_col = #5200aa
1944 tile_feature_col             = #997700
1945 tile_trap_col                = #aa6644
1946 tile_water_col               = #114455
1947 tile_deep_water_col          = #001122
1948 tile_lava_col                = #552211
1949 tile_excluded_col            = #552266
1950 tile_excl_centre_col         = #552266
1951 tile_window_col              = #558855
1952
1953 These options allow configuring the colours used for the minimap of the dungeon
1954 level. Using RGB hex codes is also allowed, such as #00ff00 for green.
1955    tile_player_col              - colour of player position, as well as of
1956                                   map centre during level map mode ('X')
1957    tile_monster_col             - colour of hostile monsters
1958    tile_neutral_col             - colour of neutral monsters
1959    tile_peaceful_col            - colour of peaceful monsters
1960    tile_friendly_col            - colour of friendly monsters
1961    tile_plant_col               - colour of zero xp monsters (plant and fungus)
1962    tile_item_col                - colour of known or detected items
1963    tile_unseen_col              - colour of unseen areas (usually stone)
1964    tile_floor_col               - colour of floor
1965    tile_wall_col                - colour of any wall type
1966    tile_mapped_floor_col        - colour of floor detected via magic mapping
1967    tile_mapped_wall_col         - colour of walls detected via magic mapping
1968    tile_explore_horizon_col     - colour of the edge of explored territory
1969    tile_door_col                - colour of known doors, open or closed
1970    tile_downstairs_col          - colour of downstairs
1971    tile_upstairs_col            - colour of upstairs, including branch exits
1972    tile_branchstairs_col        - colour of branch entrances
1973    tile_portal_col              - colour of any portal
1974    tile_transporter_col         - colour of transporters
1975    tile_transporter_landing_col - colour of transporter destinations
1976    tile_feature_col             - colour of any non-stair, non-portal feature
1977                                   (altar, shop, fountain, ...)
1978    tile_trap_col                - colour of known traps of any type
1979    tile_water_col               - colour of shallow water
1980    tile_deep_water_col          - colour of deep water
1981    tile_lava_col                - colour of lava
1982    tile_excluded_col            - colour of squares excluded for autotravel
1983                                   (will only override tile_floor_col colour)
1984    tile_excl_centre_col         - colour of exclusion centre (overrides
1985                                   tile_floor_col and tile_item_col, only)
1986    tile_window_col              - colour of the rectangular view window
1987
1988 tile_update_rate = 1000
1989         The number of milliseconds that tick by before the screen is redrawn
1990         without any input. If game response is slow, try increasing this
1991         number. If, on the other hand, response time is fine but it takes too
1992         long for redrawings to happen, set it to a lower value.
1993
1994 tile_runrest_rate = 100
1995         The number of milliseconds that tick by before the screen is redrawn
1996         when running or resting. If Crawl is slow while running or resting,
1997         increase this number.
1998
1999 tile_key_repeat_delay = 200
2000         If you hold down a key, there's a delay until the pressed key will
2001         take action. This option controls this delay, in milliseconds. If it
2002         is set to 0 key presses will never repeat.
2003
2004 tile_tooltip_ms = 500
2005         The number of milliseconds before a tooltip appears when hovering the
2006         mouse over part of the screen. Setting this option to 0 will
2007         deactivate the tooltips entirely.
2008
2009 tile_tag_pref = (none| named | enemy | tutorial )
2010         This option defaults to "enemy" normally and "tutorial" in tutorial
2011         modes. This setting determines which monsters receive text tag
2012             none     - turns off all tags.
2013             named    - shows names of all named monsters, ally or enemy
2014             enemy    - shows names of named enemy monsters
2015             tutorial - shows names of all monsters not yet killed this game
2016                        and of named enemy monsters
2017         Examples for named monsters are uniques and ghosts.
2018
2019 tile_window_height = -90
2020 tile_window_width  = -90
2021         Options for setting the width and height of the window, in pixels. When
2022         positive, these set the window size directly. When set to 0, the window
2023         is auto-sized. When set to a negative number, these values will be
2024         interpreted as the screen's resolution minus the given value. The width
2025         may be overridden by `tile_window_ratio`, below, in which case
2026         `tile_window_width` is used as a maximum width. On some window
2027         managers, the position of OS user interface elements may enforce
2028         smaller values for these. For example, on MacOS the window will not
2029         overlap with the dock or menu bar.
2030
2031 tile_window_ratio  = 1618
2032         When set to a positive value, tiles will use this value to determine
2033         the window width as a ratio of the window height, scaled by 1000. In
2034         particular: w = h * tile_window_ratio / 1000.
2035         If this value is set, `tile_window_width` is used as a maximum width.
2036         The minimum width is determined by UI layout. This value is ignored in
2037         full screen mode. Set to a value <= 0 to disable.
2038
2039 game_scale = 1
2040         An integer scale value between 1 and 8 that will increase the size of
2041         all UI elements. This can be used to simulate high-dpi rendering on
2042         high resolution displays that don't directly support high-dpi, or adjust
2043         scaling for very large displays. For a 4k display, we recommend a value
2044         of 3 or 4, and a 2k display will typically look best with a value of 2.
2045         Local tiles only.
2046
2047 tile_map_pixels = 0
2048         The maximum number of pixels each minimap square should take up. If you
2049         have a low resolution, and feel like the inventory is too small, you
2050         can try setting this to 1 to get more space for the inventory. The
2051         downside is that travelling by clicking on the minimap becomes much
2052         harder. If set to zero, it will auto-size the minimap.
2053
2054 tile_viewport_scale = 1.0
2055         A scale factor to apply to the dungeon view. The minimum value is 0.2
2056         and the maximum value is determined by resolution; zoom will be capped
2057         so that at a minimum, your line of sight is always visible. This can
2058         also be adjusted in-game in local tiles with ctrl-'-' and ctrl-'='.
2059
2060 tile_map_scale = 0.6
2061         A scale factor to apply to the dungeon view in map mode (X). This can
2062         also be adjusted in map mode in tiles with '{' and '}', as well as in
2063         local tiles with ctrl-'-' and ctrl-'='.
2064
2065 tile_cell_pixels = 32
2066         The width and height of tiles in the dungeon view at 1.0 scale, in
2067         (logical) pixels. This is a legacy option, and it is recommended that
2068         you adjust scaling via tile_viewport_scale instead.
2069
2070 tile_filter_scaling = false
2071         Used in conjunction with tile_cell_pixels. Setting it to true filters
2072         the textures resulting in a smoother but blurrier image.
2073
2074 tile_force_overlay = false
2075         Setting this option to true will force the message window to appear as
2076         an overlay on top of the screen. If you use this option, making your
2077         tile_font_msg_size smaller will make the overlay smaller while retaining
2078         the same number of lines. Increase the view_max_height option if you
2079         find yourself with unused screen estate.
2080
2081 tile_overlay_col = #646464
2082         Background color of the message window overlay, as when
2083         tile_force_overlay is set to true. Used in conjunction with
2084         tile_overlay_alpha_percent.
2085
2086 tile_overlay_alpha_percent = 40
2087         Transparency value for the message window overlay background, as when
2088         tile_force_overlay is set to true. Setting this option to 0 will cause
2089         the message window to only display text without any background. And
2090         setting this option to 100 will force an opaque backgroud to the
2091         message window.
2092
2093 tile_full_screen = auto
2094         Setting this option to true or false will force full screen mode to be
2095         on or off. Setting it to anything else will put it in auto mode, which
2096         enables full screen mode only if the screen resolution is smaller than
2097         width 1200, or height 800.
2098
2099 tile_single_column_menus = true
2100         If enabled, all in-game menus will list items in a single column,
2101         regardless of the current screen size or the number of items in the
2102         menu. If disabled, some in-game menus will use two columns if there is
2103         insufficient space to show all items in a single column. This option
2104         is only available on local tiles; all menus on console and on WebTiles
2105         always list items in a single column, as if this option were enabled.
2106
2107 tile_font_crt_file  = VeraMono.ttf
2108 tile_font_stat_file = VeraMono.ttf
2109 tile_font_msg_file  = VeraMono.ttf
2110 tile_font_tip_file  = VeraMono.ttf
2111 tile_font_lbl_file  = Vera.ttf
2112         Fonts used in various sections of the screen for local tiles. For
2113         WebTiles use tile_font_*_family instead. If you want to use another
2114         font, you'll have to place the corresponding *.ttf file into the
2115         dat/tiles/ folder.
2116         Screen regions are as follows:
2117             crt  - non-map screens (menus, message history, etc.)
2118             stat - stat area (hit points, AC, etc.)
2119             msg  - message area
2120             tip  - tooltips (mouseover information)
2121             lbl  - item/monster names in inventory/main map
2122
2123 tile_font_crt_family  = monospace
2124 tile_font_stat_family = monospace
2125 tile_font_msg_family  = monospace
2126 tile_font_lbl_family  = monospace
2127         Fonts used in various sections of the screen for WebTiles. For local
2128         tiles use tile_font_*_file instead.
2129
2130 tile_font_crt_size  = 15
2131 tile_font_stat_size = 16
2132 tile_font_msg_size  = 14
2133 tile_font_tip_size  = 15
2134 tile_font_lbl_size  = 14
2135         Font size for the screen regions listed above. If set to zero (default),
2136         size will be based on screen size.
2137
2138 tile_font_ft_light = false
2139         Selects 'light' font hinting.
2140
2141 glyph_mode_font = monospace
2142         Font used to render the dungeon in glyph mode for WebTiles. If set to
2143         monospace (default) or the font is not available, the browser's default
2144         monospaced font will be used.
2145         This option is only available on WebTiles.
2146
2147 glyph_mode_font_size = 24
2148         Font size (in points) for the dungeon view in glyph mode for WebTiles.
2149         This option is only available on WebTiles.
2150
2151 tile_show_minihealthbar = true
2152 tile_show_minimagicbar  = true
2153         Will show health and magic bars on top of the player tile when the
2154         player gets hurt or spends magic.
2155
2156 tile_show_demon_tier = false
2157         Will overlay demon tiles with an icon intended to represent their
2158         tier (or difficulty rank) among demons, reflecting the glyph
2159         (&, 1, 2, 3, 4, 5) used in non-Tiles builds.
2160
2161 tile_water_anim = true
2162         If disabled, animation of liquids will be suppressed.
2163         Defaults to false on WebTiles.
2164
2165 tile_misc_anim = true
2166         If disabled, animation of miscellaneous things such as altars and
2167         torches will be suppressed.
2168
2169 tile_realtime_anim = false
2170         If enabled, tile animations will run in real time and will not be tied
2171         to player actions.
2172         This option is only available on WebTiles.
2173
2174 tile_show_player_species = false
2175         If enabled, displays the player using the monster tile for her species,
2176         instead of using the normal doll and showing equipment.
2177
2178 tile_show_threat_levels = none
2179         This option controls which monsters will be highlighted with their
2180         threat level. Valid levels include: trivial, easy, tough, nasty.
2181         You can specify multiple levels at once.
2182
2183 tile_layout_priority = minimap, inventory, command, spell, monster
2184         (Ordered list option)
2185         This option allows you to control the order in which elements are
2186         placed on the right of the screen, below the stat area. On small
2187         resolution, there won't be enough room for everything, so only the
2188         first items will be placed. You can also remove items you don't want
2189         to be permanently displayed. The inventory tab will always be placed at
2190         the bottom but is initialised at a minimum size (4 lines). If you put a
2191         tab before it on the option line, the tab will still be placed above it,
2192         but it will have priority over it so the inventory might not be able to
2193         expand to its maximum size (6 lines). The minimap is always placed
2194         between the stat area and the tabs. The memorisation and skill tabs can
2195         be added to the list too, but are not by default. The possible options
2196         are: abilities, commands, inventory, memorisation, minimap, monsters,
2197         navigation, skills, spells, system commands
2198
2199 tile_display_mode = (tiles | glyphs | hybrid)
2200         Controls how the dungeon is rendered. You can use normal tiles (default)
2201         or make it look like the console version by using glyphs. Hybrid
2202         overlays icons on top of the glyph view.
2203         This option is only available on WebTiles.
2204
2205 tile_level_map_hide_messages = true
2206 tile_level_map_hide_sidebar = false
2207         Controls what screen elements are hidden when using the level map.
2208         These options are only available on WebTiles.
2209
2210 tile_player_tile = (normal | playermons | mons:<monster> | tile:<monster-tile>)
2211         If set to playermons, displays the player using the monster tile for
2212         her species, instead of using the normal doll.
2213
2214         If set to a value of the form mons:<monster>, where <monster> is the
2215         name of a monster, use the base tile of <monster> as the player
2216         tile. For example a value of mons:ijyb will cause Ijyb's tile to be
2217         used. Any spaces in the monster name should be included. For instance:
2218         a value of mons:the royal jelly is valid.
2219
2220         If set to a value of the form tile:<player-tile> where <player-tile> is
2221         the name of a tile in the player tile sheet, use this tile as the
2222         player tile. This form is most useful for using specific variant tiles
2223         of monster with multiple tiles, such as hydra and large abominations,
2224         or special tiles like Cigotuvi's Monster or player transformations that
2225         don't have their own base monster. The tile name must be the full name,
2226         e.g. mons_hydra_7. For example, to use the hydra tile with many heads,
2227         use a value of tile:mons_hydra_7. The tile names can be found in the
2228         source tree folder source/rltiles in the files dc-mon.txt,
2229         dc-demon.txt, and dc-player.txt. In these files, the tile name is in
2230         the second word in each entry after the file name of the image, and
2231         case is ignored for matching. Monster tile names are usually of the
2232         form mons_<monster-name>, but other tiles like transformations are
2233         named differently, e.g. tran_tree for the tree transformation tile.
2234
2235 tile_weapon_offsets = (<x>,<y> | reset)
2236 tile_shield_offsets = (<x>,<y> | reset)
2237         When using a custom tile with tile_player_tile, these option set the
2238         pixel x (horizontal) and y (vertical) offsets for the location where
2239         the weapon or shield will be drawn in the tile. The x and y offsets
2240         must be integers between -32 and 32, inclusive. Negative x values will
2241         adjust left, and Negative y values will adjust up. At 0,0, the weapon
2242         is drawn on the left side of the tile, and at 0,0 the shield is drawn
2243         on the right side. A weapon x offset of e.g. 10 to 20 (depending on the
2244         tile) together with a shield x offset of -10 to -20 can therefore be
2245         used to swap locations of weapon and shield.
2246
2247         Using the value "reset" will clear any previously defined offset, which
2248         is using for in-game tile changes via lua.
2249
2250 tile_web_mouse_control = true
2251         Whether to enable mouse control for tooltips/cursor interaction on
2252         WebTiles. Regardless of the value of the setting, the minimap will
2253         respond to mouse control.
2254
2255 4-  Character Dump.
2256 ===================
2257
2258 4-a     Saving.
2259 ---------------
2260
2261 dump_on_save = true
2262         If set to true, a character dump will automatically be created or
2263         updated when the game is saved.
2264
2265 4-b     Items and Kills.
2266 ------------------------
2267
2268 The character dump or morgue files end with a list of all monsters that
2269 perished while the character was active. By default, dead monsters are
2270 grouped in three parts:
2271    Vanquished Creatures    -- monsters killed by the character
2272    Collateral Kills        -- kills of friendly monsters
2273    Others                  -- all other casualties (e.g. traps, hostile
2274                               monsters)
2275
2276 kill_map = friend:you, other:you
2277         will merge friendly and other kills into the main vanquished
2278         creatures list. Note that the merging is only for display (the
2279         game still maintains three separate lists internally) and that
2280         kill places (see below) may be in the wrong order for merged
2281         entries. The default is an empty list.
2282
2283 dump_kill_places = (none | all | single)
2284         In the Vanquished Creatures list, this option controls how the
2285         locations of each kill are displayed. Use 'none' to suppress
2286         place display altogether, 'all' to display all known (up to 5)
2287         kill places, anything else to the default of showing kill places
2288         only for single kills
2289
2290 dump_item_origins = artefacts
2291         The game remembers where you find items. If you want this item
2292         origin memory listed in your dumps, use this option to select
2293         which items get annotated. Available selectors are:
2294                 artefacts, ego_arm, ego_weap, jewellery, runes,
2295                 staves, books, all, none.
2296         If you use multiple dump_item_origins lines, the last line takes
2297         effect; all preceding lines are ignored.
2298
2299         If you don't want any items to be annotated, set
2300         dump_item_origins to none, and set dump_item_origin_price to -1.
2301
2302 dump_item_origin_price = -1
2303         Item origins are dumped if the price of the item is greater than
2304         or equal to this amount. Set this to -1 to prevent selection by
2305         price.
2306
2307 dump_message_count = 20
2308         The number of last messages to be displayed in character dump
2309         files.
2310
2311 dump_order  = header,hiscore,stats,misc,inventory,
2312 dump_order += skills,spells,overview,mutations,messages,screenshot,
2313 dump_order += monlist,kills,notes,screenshots,skill_gains,action_counts
2314         (Ordered list option)
2315         Controls the order of sections in the dump.
2316
2317         Two optional dump sections are "turns_by_place" and
2318         "kills_by_place", which add detailed statistics to where turns
2319         were spent and monsters were killed. You can add them to your
2320         dump as:
2321              dump_order += turns_by_place, kills_by_place
2322
2323         Another optional dump section is "vaults", which will list the
2324         locations and names of all the vaults that have been generated
2325         in the game. This will only be included in the final dump
2326         which happens when you die, quit or win (or in ordinary dumps
2327         while in wizard mode). The "vaults" section is enabled by default
2328         in trunk builds of Crawl (not releases or pre-release betas),
2329         appearing between "notes" and "skill_gains".
2330
2331 4-c     Notes.
2332 --------------
2333
2334 Crawl can automatically log certain events during play. You can read
2335 these in the dump or morgue files. Below are the options for tweaking this
2336 behaviour.
2337 The following events are logged:
2338         - Gaining or losing a level
2339         - Entering a dungeon level for the first time
2340         - Memorising a spell of higher level than any learned before
2341         - Becoming a worshipper of a god
2342         - Abandoning a god
2343         - Being put under penance and being forgiven
2344         - Receiving a gift from a god (except Xom)
2345         - Death of a named orcish ally (when worshipping Beogh)
2346         - Being able to invoke a godly power for the first time
2347         - Picking up a rune, the Orb of Zot, or an artefact for the first time.
2348         - Identifying items.
2349         - Killing OOD or unique monsters (see below)
2350         - Reaching critical HP levels (see below)
2351         - Gaining or losing mutations
2352         - Reaching significant levels in a skill (see below)
2353         - Dying
2354 You can use the command ':' for manually adding notes.
2355
2356 user_note_prefix = <string>
2357         Prefixes manually added notes with the given string, to make
2358         them easier to find. It is not currently possible to add a
2359         space at the end of this or any option, but you can use the
2360         Unicode non-breaking space character ' ' instead.
2361
2362 note_items += <regex>, <regex>, ...
2363         (List option)
2364         When an item is identified for the first time, it will be
2365         noted if its short description matches a regex. E.g.
2366              note_items += book,acquirement
2367         Artefacts (fixed, unrand, or random) will always be noted when
2368         identified, regardless of note_items.
2369
2370         The description matched against has the same prefixes as notes
2371         for the menu_colour option (e.g., "emergency_item").
2372
2373 note_monsters += <regex>, <regex>, ...
2374         (List option)
2375         Monsters whose name matches an item in this comma-separated list
2376         are considered interesting. You can have multiple note_monsters
2377         lines. E.g.
2378              note_monsters += Klown,orb of fire
2379
2380 note_hp_percent = 5
2381         If your HP falls below a certain note_hp_percentage of your max
2382         hit points, a note will be taken. There is some code to avoid
2383         repetitions of notes based on the same incident.
2384
2385 note_skill_levels = 1,5,10,15,27
2386         This sets which skill levels are noteworthy. It's a single line,
2387         although you can use += as a continuation.
2388
2389 note_all_skill_levels = false
2390         This is a shortcut for note_skill_levels = 1,2,..,27. If you set
2391         this to true, all skill levels are considered noteworthy.
2392
2393 note_skill_max = true
2394         Setting this option will cause a note whenever a new maximum in
2395         skill levels is reached. If note_skill_max is true and
2396         note_skill_levels is nonempty, notes will be taken whenever
2397         either of the criteria are met.
2398
2399 note_xom_effects = true
2400         This will add a note whenever Xom does something.
2401
2402 note_messages += <regex>, <regex>, ...
2403         (List option)
2404         Messages which match an item in this comma-separated list are
2405         considered interesting. You can have multiple note_messages
2406         lines. E.g.
2407              note_messages += Something interferes
2408              note_messages += protects you from harm
2409         If you want all banishments to the Abyss noted, use
2410              note_messages += [bB]anish.*Abyss
2411         If you want a note when your draconian scales turn <colour>, use
2412              note_messages += Your scales start
2413
2414 note_chat_messages = false
2415         If set to false, this will disable logging of WebTiles chat
2416         messages from other players. (This setting only applies on the
2417         online servers).
2418
2419 note_dgl_messages = true
2420         If set to false, this will disable logging of DGL messages
2421         sent by other players. (This setting only applies on the online
2422         servers).
2423
2424
2425 5-  Miscellaneous.
2426 ==================
2427
2428 5-a     All OS.
2429 ---------------
2430
2431 mouse_input = false
2432         When enabled, the mouse_input option allows the game to use
2433         mouse input events on certain platforms (Windows and Unix).
2434         Note that the extent of mouse support varies greatly across
2435         platforms and is strongly influenced by your terminal settings.
2436
2437         On Unixes, you're only likely to get mouse support working with
2438         ncurses in xterms (specifically your $TERM probably needs to
2439         contain "xterm" for ncurses to activate its mouse events;
2440         if you're running Crawl in GNU screen in an xterm, the mouse
2441         will probably not work).
2442
2443         On Windows, you'll need to disable QuickEdit Mode on your
2444         console for Crawl to use the mouse (QuickEdit is disabled by
2445         default, so you shouldn't need to change anything if you're
2446         using a stock console). You can disable QuickEdit by
2447         right-clicking the titlebar of your command-prompt, selecting
2448         Properties and disabling QuickEdit in the Options tab.
2449
2450 wiz_mode = (no | never | yes)
2451         Wizard mode options (available only in WIZARD compiles):
2452           yes   -- start games in wizard mode (game will not be scored)
2453           no    -- still allows player to enter wizard mode after start
2454                    of game
2455           never -- never allow a wizard command to be used
2456
2457 explore_mode = (no | never | yes)
2458         Explore mode options (available only in WIZARD compiles):
2459           yes   -- start games in explore mode (game will not be scored)
2460           no    -- still allows player to enter explore mode after start
2461                    of game
2462           never -- never allow explore mode to be entered
2463
2464 char_set = (default | ascii)
2465         Chooses different pre-set character sets for the game play screen.
2466         Unlike previous versions of Crawl, this does not select the I/O
2467         encoding anymore.
2468
2469         You can also include ibm_glyphs.txt, dec_glyphs.txt, or old_unicode_
2470         glyphs.txt to bring back some older character sets that are
2471         no longer built-in.
2472
2473         Has negligible effect in the Tiles build.
2474
2475 colour.OLDCOLOUR = NEWCOLOUR
2476         Useful for terminals where some colours are hard to read (and
2477         cannot be adjusted), as well as for creating a custom scheme,
2478         especially when used with the background option on a terminal
2479         with a non-black background.
2480         Format is colour.OLDCOLOUR = NEWCOLOUR, later rules take
2481         precedence and the NEWCOLOUR is always literal (ie. it won't
2482         re-evaluate to a different colour).
2483         The colours are:
2484                 black, blue, green, cyan, red, magenta, brown, lightgrey,
2485                 darkgrey, lightblue, lightgreen, lightcyan, lightred,
2486                 lightmagenta, yellow, white
2487         with lightgray = lightgrey, darkgray = darkgrey. Some examples:
2488           colour.lightgrey = black
2489           colour.lightcyan = cyan
2490           colour.yellow    = brown
2491
2492 display_char = <dungeon_character_name : symbol>
2493         a list of these is allowed, as well.
2494
2495         The possible entries for dungeon_character_name are: wall, permawall,
2496            wall_magic, floor, floor_magic, door_open, door_closed, trap,
2497            stairs_down, stairs_up, grate, altar, arch, fountain, wavy, statue,
2498            invis_exposed, item_detected, item_orb, item_rune, item_weapon,
2499            item_armour, item_wand, item_scroll, item_ring, item_potion,
2500            item_missile, item_book, item_staff, item_rod, item_miscellany,
2501            item_corpse, item_skeleton, item_gold, item_amulet, cloud,
2502            cloud_weak, cloud_fading, cloud_terminal, tree, transporter,
2503            transporter_landing, space, fired_bolt, fired_zap, fired_burst,
2504            fired_debug, fired_missile, fired_missile, explosion, frame_horiz,
2505            frame_vert, frame_top_left, frame_top_right, frame_bottom_left,
2506            frame_bottom_right, draw_horiz, draw_vert, draw_slash,
2507            draw_backslash, draw_top_left, draw_top_right, draw_bottom_left,
2508            draw_bottom_right, draw_down, draw_up, draw_right, draw_left
2509
2510         Most of these are self-explanatory. "arch" is used for shops and
2511         portals. "floor_magic" and "wall_magic" are used to display magic-mapped
2512         squares on the level map. "invis_exposed" is the character for water
2513         creatures submerged in shallow water, or invisible creatures wading in
2514         shallow water. "wavy" is water and lava. "cloud", "cloud_weak",
2515         "cloud_fading", and "cloud_terminal" distinguish clouds by remaining
2516         duration, listed from furthest to nearest expiry; cloud types that do
2517         not visually reveal their remaining duration always use the "cloud"
2518         glyph.
2519
2520         Symbols can be specified using a letter, or by its ASCII/Unicode
2521         code: a decimal number or a hexadecimal one (prefixed with x).
2522
2523 feature += <regex> { <symbol>, <magicmap symbol>, <view colour>,
2524                     <levelmap_magic_colour>, <levelmap_seen_colour>,
2525                     <emphasised_colour>, <levelmap_emphasised_colour> } ;
2526            <regex> { ... }
2527 feature -= <regex> , <regex>
2528         (List-like option)
2529         where <regex> is a regular expression describing a dungeon
2530         feature. This regex should match the description when using the
2531         'x' command. In case the regex matches several descriptions, all
2532         such features are affected.
2533
2534         The list in {...} specifies the appearance of the dungeon
2535         feature(s), and should be self-explanatory. <symbol> can be used
2536         to override the above display_char options, or also to distinguish
2537         among subtypes of a character.
2538
2539         'magic' refers to magic mapping. So the <magicmap symbol>
2540         entry determines what symbol will be used for features
2541         detected via magic mapping. The <magicmap symbol> will also be used
2542         for stone stairs with unknown destination and unvisited transporters.
2543
2544         'emphasised_colour' refers to the colour used to highlight stone stairs
2545         and transporters with unknown destination; for non-stair features,
2546         setting emphasis colours does nothing useful.
2547
2548         Leading parameters in the {...} list can be omitted by leaving
2549         them blank and using placeholder commas. Trailing parameters can
2550         be omitted without placeholder commas.
2551
2552         Multiple feature option lines can be used, as can multiple
2553         feature descriptions strung together on the same line separated
2554         by semicolons.
2555
2556         Feature overrides can be cleared using -=, providing a regex only
2557         (and not an appearance). This will restore all features whose
2558         descriptions match the regex to their default appearances.
2559
2560         Examples:
2561          * Colour rock walls red:
2562              feature += rock wall { , , red }
2563          * Use # for metal walls in all character sets:
2564              feature += metal wall {#}
2565          * Colour upstairs green and downstairs red:
2566              feature += stone staircase leading up {,,,,green}
2567              feature += stone staircase leading down {,,,,red}
2568
2569         Symbols can be specified as with display_char:
2570              feature += metal wall {#}
2571              feature += metal wall {35}
2572              feature += metal wall {x23}
2573         all do the same thing.
2574
2575 mon_glyph += <monster name or symbol> : (<colour> <glyph> | <monster name>) ,
2576              <monster name or symbol> : <replacement>
2577 mon_glyph -= <monster name or symbol>
2578         (List option)
2579         The mon_glyph option allows you to customise the symbol and
2580         colour used to display a monster.
2581
2582         You can customise symbols based on monster names or their
2583         existing symbols. For instance, if you want to put elves on E
2584         and elementals on e, you can do this:
2585
2586              mon_glyph += e : E
2587              mon_glyph += E : e
2588
2589         You can specify a different symbol, or a colour, or both, in any
2590         order. Here are more examples:
2591
2592              mon_glyph += deep elf annihilator : E lightmagenta
2593              mon_glyph += Xtahua : lightmagenta D
2594              mon_glyph += large zombie : darkgrey
2595              mon_glyph += small simulacrum : x
2596
2597         (The left hand side of the : is case-sensitive.)
2598
2599         You can also specify another monster, so that it copies the base
2600         symbol and colour of that monster (this is not transitive). For
2601         example, if you think that slime creature colours are backwards:
2602
2603             mon_glyph += slime creature : merged slime creature
2604             mon_glyph += merged slime creature : slime creature
2605
2606         You can specify symbols using their code points using the syntax
2607         as shown in the "feature" option. You can also use Unicode code
2608         points:
2609
2610              mon_glyph += draconian scorcher : x6e9
2611
2612         A single _ is treated as a space; if you want a real underscore,
2613         put a \ in front of it like this:
2614
2615              mon_glyph += player ghost : \_
2616
2617         You can also redefine several "pseudo" monsters, them being:
2618
2619              player
2620              sensed monster
2621              {trivial,easy,tough,nasty,friendly} sensed monster
2622              merged slime creature
2623
2624         Playable species that normally have no monster of the same name can
2625         also be redefined, for use with show_player_species = true.
2626
2627         Monster glyph overrides can be cleared using -=, which restores
2628         the named monster (or all monsters of the given glyph) to its default
2629         appearance. Specify only the monster name or glyph for -=, not the
2630         replacement being removed.
2631
2632 item_glyph ^= <regexp> : <colour> <glyph>
2633 item_glyph -= <regexp>
2634         (Ordered list option)
2635         Customizes the symbol and/or colour of all items matching the regexp.
2636         Unlike mon_glyph, this is a partial name match.
2637
2638         Items are prefixed by tags, both those from stash tracking and from
2639         menu colouring. Thus, you can colour {artefact} or useless_item.
2640
2641         Multiple rules can modify a single item, which is useful if you want
2642         to change the colour and glyph separately:
2643             item_glyph += corpse : x625
2644             item_glyph += inedible.* corpse : lightgreen
2645
2646         Rules are applied in order, so later rules are higher priority.
2647
2648         Removing a rule with -= removes all rules using the exact regexp
2649         provided; do not specify a colour or glyph in that case.
2650
2651 use_fake_player_cursor = true
2652         Makes the main view highlight the player without using the
2653         terminal cursor. This means it won't flicker when the cursor
2654         is turned off to move elsewhere for drawing, and allows
2655         turning the cursor off by default. Has no effect in the Tiles build.
2656
2657 show_player_species = false
2658         Displays your character as a member of its species. For example, if
2659         you're a Hill Orc, you will be shown as an 'o' rather than '@'. Has
2660         no effect in Tiles.
2661
2662 use_modifier_prefix_keys = true
2663         When true, '*' behaves as a CTRL keypress, and '/' as SHIFT.
2664
2665 language = <two-letter language code>
2666         Displays some text in the given language. Not all text in Dungeon Crawl
2667         has translations in every supported language, but volunteer translators
2668         have offered translations of particularly wordy text such as god and
2669         monster descriptions. Text with no known translation will be displayed
2670         in English. Some languages may require changing the font.
2671
2672         Partially supported language codes:
2673         cs: Czech
2674         da: Danish
2675         de: German
2676         el: Greek
2677         es: Spanish
2678         fi: Finnish
2679         fr: French
2680         hu: Hungarian
2681         it: Italian
2682         ja: Japanese
2683         ko: Korean
2684         lt: Lithuanian
2685         lv: Latvian
2686         nl: Dutch
2687         pl: Polish
2688         pt: Portuguese
2689         ru: Russian
2690         sv: Swedish
2691         zh: Chinese
2692
2693 fake_lang = <lang1>[,<lang2>[,...]]
2694         Set one or more fake languages, applied in the order provided (order
2695         does matter!) The same language can be set more than once, though it
2696         may not end up making much sense... At most 3 fake langs can be set at
2697         a time.
2698
2699         Options are: (dwarven|jagerkin|kraut|runes|wide|grunt|butt:<n>)
2700         Experiment to find out what they do!
2701
2702 read_persist_options = false
2703         When set to true, the game will read additional options from
2704         the lua variable c_persist.options if it contains a string.
2705
2706 5-b     DOS and Windows.
2707 ------------------------
2708
2709 dos_use_background_intensity = false
2710         On DOS and Windows, if you're using a console that can do
2711         high-intensity background colours, set this option to true for
2712         superior friend-branding. If your console doesn't like this
2713         option, some friendly monsters will appear as blinking
2714         characters (and setting this option to false may be advisable to
2715         preserve your sanity in such cases).
2716
2717 5-c     Unix.
2718 -------------
2719 blink_brightens_background = false
2720         For 8-colour mode, assume that a blink text attribute will end up
2721         brightening the background colour.
2722
2723         If enabled on a terminal where this assumption does not hold, this will
2724         result in invisible glyphs for normal/bright colour combos of the same
2725         base colour.
2726
2727         This option is ignored when running in 16-colour mode via
2728         allow_extended_colours.
2729
2730 bold_brightens_foreground = false
2731         For 8-colour mode, assume that a bold text attribute will end up
2732         brightening the foreground colour.
2733
2734         See blink_brightens_background for more information.
2735
2736 best_effort_brighten_background = false
2737         If set to true, try to brighten a background colour using blink even if
2738         it is not assumed to be successful.
2739
2740         This option only affects colours which are safe to brighten. If the
2741         blink_brightens_background option is set to true, this option is
2742         effectively ignored.
2743
2744         This option is ignored when running in 16-colour mode via
2745         allow_extended_colours.
2746
2747 best_effort_brighten_foreground = true
2748         If set to true, try to brighten a foreground colour using bold even if
2749         it is not assumed to be successful.
2750
2751         This option only affects colours which are safe to brighten. If the
2752         bold_brightens_foreground option is set to true, this option is
2753         effectively ignored.
2754
2755         This option is ignored when running in 16-colour mode via
2756         allow_extended_colours.
2757
2758 allow_extended_colours = false
2759         Allow an *attempt* to use more than the eight basic terminal colours
2760         for crawl's bright colours.
2761
2762         If this option is enabled and there are enough colours available in
2763         the terminal, use the terminal's extended colour palette directly for
2764         internal colours.
2765
2766         An appropriate TERM environment variable must be set for this option to
2767         function as expected for capable terminals. For example:
2768           * XTerm: xterm-256color
2769           * gnome-terminal: vte-256color
2770           * PuTTY: putty-256color
2771             (set in 'Connection->Data->Terminal-type string')
2772
2773         If these conditions are not met, crawl will fall back to 8-colour mode
2774         and use character attributes to render bright colours.
2775
2776 background_colour = black
2777         Sets the default background colour by name (defaults to BLACK).
2778         This may be useful if you're using a terminal with a background
2779         colour other than black and wish to retain the colour scheme for crawl.
2780
2781         Internally, black is mapped to the the passed background colour and
2782         vice-versa.
2783
2784         This option requires extended support by the terminal library as well
2785         as the terminal itself. Additionally, bright default colours are not
2786         available unless extended colour support is present and explicitly
2787         enabled via allow_extended_colours. If support is not present, either
2788         outright or for the selected colour, this option will have an effective
2789         value of black.
2790
2791         See the allow_extended_colours option for more information on enabling
2792         use of bright default colours. Beware of buggy or misleading terminfo
2793         files.
2794
2795 foreground_colour = lightgrey
2796         Sets the default foreground colour by name (defaults to LIGHTGREY).
2797
2798         Internally, lightgrey is mapped to the passed foreground colour and
2799         vice-versa.
2800
2801         This option comes with the same baggage as the background_colour option.
2802         See its documentation for more details.
2803
2804 use_fake_cursor = true
2805         If true, Crawl draws the cursor explicitly on the level-map and
2806         targeting screens instead of relying on the term to draw the
2807         cursor. Use this if your term cannot show a cursor over
2808         darkgrey/black squares.
2809         On non-Unix builds this option defaults to false, and setting it to
2810         to true may have unpredictable results.
2811
2812
2813 6-  Lua.
2814 ========
2815
2816 6-a  Including lua files.
2817 -------------------------
2818
2819 Lua files are scripts which can provide existing commands with a new
2820 meaning or create new commands (to be used in macros). To use Lua
2821 files, Crawl needs to be compiled with support for user Lua scripts.
2822 You can if your Crawl has Lua support by hitting ?V in-game. The list
2823 of features Crawl displays should include "Lua user scripts".
2824
2825 Lua files are included using the lua_file option (one file per line):
2826
2827 lua_file = <path/name.lua>
2828
2829 Lua functions can be macroed in-game by setting the macro action to "===",
2830 followed by the function name.
2831
2832 The wizard-mode Lua interpreter (&^T) will, the first time it's invoked,
2833 load all of the files that are specified with the terp_file option:
2834
2835 terp_file = <path/name.lua>
2836
2837 The Lua in these files will have access to all of the Crawl Lua internals
2838 (that is, will be run in the context of dlua, not clua).
2839
2840 6-b     Executing inline lua.
2841 -----------------------------
2842
2843 Lua code can be used directly in your init.txt/.crawlrc. You can
2844 execute Lua code using the following syntax.
2845
2846 : Single line of lua code
2847
2848 < Possibly multi-line
2849   Lua code >
2850
2851 { Possibly multi-line
2852   Lua code }
2853
2854 In the second and third cases, the restriction is that the delimiter
2855 characters appear at the beginning and end of a line, respectively.
2856 The difference between the <> and {} is when the code gets executed.
2857 Code {}, it is executed right away. Other Lua code is executed only
2858 after the entire init file is read in.
2859
2860 Examples:
2861
2862 # Print a welcome message
2863 : crawl.mpr("Hello " .. you.name())
2864
2865 <
2866 -- Another welcome message (lua code uses lua comments)
2867 crawl.mpr("Hi there")
2868 >
2869
2870 {
2871 function ch_autopickup(it) [ ... body omitted ... ] end
2872 }
2873
2874 6-c     Conditional options.
2875 ----------------------------
2876
2877 You can use Lua to selectively include parts of your init.txt (based
2878 on character type, for instance) using the same syntax.
2879
2880 Example:
2881
2882 : if you.race() == "Mummy" then
2883 autopickup = $?+"/
2884 : else
2885 autopickup = $?+"/!
2886 : end
2887
2888 Options can be referenced by lua via "options.option_name". For
2889 example:
2890
2891 :if string.find(options.autopickup, "!") then
2892 # Do something here if potions are included in autopickup
2893 :end
2894
2895 "options.option_name" can even be used for options that crawl itself
2896 doesn't recognize. This can be combined with setting options on the
2897 command line (see section 0-b) to use the command line to control
2898 conditionalization of options in the options files. For example, on the
2899 command line you could set the option "foobar" with "-extra-opt-first
2900 foobar=true", and then do:
2901
2902 :if options.foobar then
2903 # Do things here
2904 :end
2905
2906 6-d     Conditional option caveats.
2907 -----------------------------------
2908
2909 Note that none of the options listed under "Starting Screen" (section 1)
2910 can be set conditionally. This is because the options files are
2911 actually read in twice: once before character creation with Lua turned
2912 off, and a second time after character creation with Lua turned on. If
2913 you attempt to set a starting-screen option conditionally then the value
2914 furthest down in the options file will be used regardless of what
2915 conditions you set.
2916
2917 The above caveat applies to the "wiz_mode" option as well. Instead of
2918 conditionalized wiz_mode, you can add to the command line
2919 "-extra-opt-last wiz_mode=yes" to make any new game start in wizard
2920 mode.
2921
2922 7-  Recommended Options for Blind Players.
2923 ==========================================
2924
2925 The following settings are recommended to facilitate using crawl in console
2926 with a screenreader.
2927
2928 Disable animations and view delays so the screen updates immediately after each
2929 command:
2930     view_delay = 0
2931     travel_delay = -1
2932     rest_delay = -1
2933     use_animations = 0
2934
2935 Place messages at the top of the screen and remove message condensing for
2936 easier screen reading:
2937     messages_at_top = true
2938     clear_messages = true
2939     msg_condense_short = false
2940
2941 Make the player cursor easier to track with screen reading, by setting a custom
2942 symbol for the player:
2943     use_fake_player_cursor = false
2944     show_player_species = false
2945     mon_glyph += player:x263A
2946
2947 Use mouse input clicks for automove (see the discussion of the mouse_input
2948 option for terminal configuration specifics):
2949     mouse_input = true
2950
2951 Allow auto-travel/move to advance one step even when monsters are present:
2952     travel_one_unsafe_move = true
2953
2954 List player-relative coordinates in the ^x display:
2955     monster_item_view_coordinates = true
2956
2957 The ^x display can list a customizable set of features controlled with regular
2958 expressions. For example, to include all water in ^x set:
2959     monster_item_view_features += water
2960
2961 Mark the path taken by auto-travel and the exploration horizon with special
2962 characters:
2963     show_travel_trail = true
2964     feature += travel trail {x25AA}
2965     feature += explore horizon {x25AB}
2966
2967 Set a separate glyph for unvisited stairs and transporters:
2968     feature += stone staircase leading up {<,x25C2}
2969     feature += stone staircase leading down {>,x25B8}
2970     feature += transporter {xA9, x25CE}