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