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