path: root/crawl-ref/docs/crawl_options.txt

This document explains all of the options in the latest version of Dungeon 
Crawl Stone Soup. These options are set in the init.txt file located in the 
Crawl directory (the directory containing crawl.exe on Windows and DOS). On Unix
systems, you need to set options in the ~/.crawlrc file (a file named .crawlrc 
in your home directory).

The contents of this text are:

1-  Starting Screen.
  		name, remember_name, weapon, book,
		chaos_knight, death_knight, priest, 
		race, class, random_pick
2-  File System and Sound.
                crawl_dir, save_dir, sound.
3-  Lua files.
		lua_file,
		base.lua, stash.lua, wield.lua, kills.lua, runrest.lua, 
		gearset.lua, eat.lua, trapwalk.lua
4-  Interface. 
4-a	Dropping and Picking up.
		autopickup, default_autopickup, safe_autopickup, safe_zero_exp,
		pickup_thrown, pickup_dropped, assign_item_slot, ban_pickup, 
		drop_mode, pickup_mode, drop_filter;
		lua: ch_autopickup (advanced autopickup exceptions)
4-b	Targeting. 
		target_zero_exp, target_wrap, target_oos, target_los_first,
		confirm_self_target, default_fizzlecheck
4-c	Passive Sightings (Detection and Rememberance).
		detected_monster_colour, detected_item_colour, 
		remembered_monster_colour, colour_map, clean_map
4-d	Branding (Item and Monster Highlighting).
		heap_brand, friend_brand, stab_brand, may_stab_brand 
4-e	Level Map Functions.
		level_map_cursor_step, item_colour, show_waypoints
4-f	Travel and Exploration. 
		travel_colour, travel_delay, travel_stair_cost, 
                travel_avoid_terrain, travel_exclude_radius2,
                travel_stop_message, explore_stop, runrest_ignore_message,
                runrest_ignore_poison, trapwalk_safe_hp;
		lua: ch_stop_run (ignoring monsters)
4-g	Stashes.
		stash_tracking, stash_filter
4-h	Command Enhancements.
		auto_list, lowercase_invocations, easy_open, easy_butcher, 
		easy_armour, easy_confirm, easy_quit_item_lists, easy_exit_menu,
		default_autoprayer, sort_menus
4-i	Message and Display Improvements.
		show_uncursed, hp_warning, always_greet, terse_hand, 
		delay_message_clear, menu_colour
4-j	Missiles.
		fire_items_start, fire_order
4-k	Message Channels.
		plain, prompt, god, pray, duration, danger, food, warning,
		recovery, multiturn, talk, intrinsic_gain, mutation,
		monster_spell, monster_enchant, monster_damage, rotten_meat
4-l	Inscriptions.
		autoinscribe
4-m	Macro related Options.
		flush.failure, flush.command, flush.message
5-  Character Dump.
5-a	Items and Kills.
		kill_map, dump_kill_places, dump_item_origins, 
		dump_item_origin_price, dump_message_count, dump_order,
                verbose_dump 
5-b	Notes.
		use_notes, note_items, ood_interesting, note_hp_percent, 
		note_skill_levels, note_skill_max, note_monsters, 
		note_messages, note_all_spells
6-  Miscellaneous.
6-a	All OS.
		macro_meta_entry, wiz_mode, colours, char_set, cset_ascii,
                cset_ibm, cset_dec, feature.
6-b	DOS and Windows.
		dos_use_background_intensity
6-c     Unix
                background

--------------------------------------------------------------------------------

There are basically three types of Crawl options: true/false values (booleans),
numbers, and lists. An option is most often specified with its default value (if
there is one); this should also explain which of the above-mentioned types it
is. Each option should have some remarks on how it's typically used - beware
that this depends strongly on your playing style and sometimes also on hardware
or operating system.

Note that the init.txt coming with regular distributions has all boolean options
commented out. The commented-out values are always the _non-defaults_, so you
can toggle boolean options by just uncommenting them.

Some options need a path as an argument; here you have to use a filesystem path
suitable for your system. Other options accept regular expressions (regexes):
here you can simply use ordinary strings, adapt the suggested regexes to your
needs or search the internet for regex syntax.

If you get stuck or some things just won't seem to work properly, please ask for
help on the newsgroup rec.games.roguelike.misc. Flag queries with '-crawl-', as
other roguelikes are also discussed there.

1-  Starting Screen.
====================

The following options are a convenience to help you quickly start your game of
Crawl.

name = Delilah
	If set, that's the name all your Crawl characters will get. 

remember_name = false
	Crawl remembers the options (class, race etc.) you used to create your
	last character. You may recycle them in the starting screen for a new 
	character. If this option is set to true, Crawl will also remember the 
	last name you used.

        If you use this option and want to enter a name _after_ choosing your
        race and class, you must enter . at the initial name prompt - hitting
        Enter at the name prompt will simply reuse your old name if
        remember_name is set.
	
weapon = (random | short sword | hand axe | spear | mace | trident)
        Specifying the weapon option allows you to bypass the weapon selection
        screen.  Note that tridents are restricted to only merfolk and
        gladiators, but you'll get the standard query in illegal cases.

book = (flame | fire | ice | cold | summ | summoning | random)
        Several spellcasting classes can choose their starting spellbook. 
	Note flame=fire and ice=cold and summ=summoning.

chaos_knight = (Xom | Makhleb | random)

death_knight = (necromancy | Yredelemnul | random)

priest       = (Zin | Yredelemnul | random)
	The above three make in advance the additional choices for 
	Chaos Knights, Death Knights, and Priests.

race = (Human |...| Merfolk | random)
	The usual abbrevations (Hu, El, HE, etc.) work.

class = (Fighter |...| Wanderer | random)
	Here again the abbrevations (Fi, Wi, Pr, etc.) can be used.

random_pick = false
	The random_pick option will randomly generate a character.
	The above options (weapons and class options) will override where
	appropriate.


2-  File System.
================

crawl_dir= <path>
	Directory for reading macro.txt and init.txt, and dumping characters.
	It should end with the path delimiter.

save_dir = <path>
        Directory where saves and bones are stored. This option may be ignored
        depending on the settings used to compile Crawl, but should be
        honoured for the official Crawl binaries.

sound = <regex>:<path to sound file>
	Plays the sound file if a message contains regex. The regex should 
	not include commas or colons. For example
	  sound = LOW HITPOINT WARNING:sound\sounds2\danger3.wav
	Getting appropriate sound files may be difficult. Check other
	roguelikes or old computer rpg's. Alternatively, ask for help at
	the newsgroup rec.games.roguelike.misc.


3-  Lua files.
==============

Lua files are scripts which can provide existing commands with a new meaning
or even create new commands (to be used in macros). If you don't know a 
specific reason not to include some or all lua files, you'll do best to just 
include them all.

lua_file = <path/name.lua>

The currently available lua's are
  base.lua	-- needed for other lua scripts
  stash.lua	-- annotates the stash file for better searching (Ctrl-F)
		   Searching for 'Long blades' will also turn up all weapons
		   with the long blade skill. Also, you can now look for
		   spellbooks ('book'), artifacts ('art'), ego items ('ego').	
  wield.lua	-- shows more intelligent options when using 'w?'
  kills.lua	-- improves the Vanquished Creatures list in dump files; 
		   currently gives three lists (Vanquished, Friendly, Others)
  runrest.lua	-- allows to remove certain stop condition when running
		   New options: runrest_ignore_poison, runrest_ignore_message
  gearset.lua	-- provides commands for switching of complete sets via macro
		   New macroable functions: rememberkit, swapkit
  eat.lua	-- prompts to eat chunks in inventory.
  trapwalk.lua  -- allows travel to cross certain traps if you have enough hp.


4-  Interface.
==============

4-a	Picking up and Dropping.
--------------------------------

autopickup = $?!:"/
	By default, the list is empty. The valid symbols are
 	)	Weapons
	(	Missiles
	[	Armour
	/	Wands
	%	Food
	?	Scrolls
	" or =  Jewellery
	!	Potions
	+ or :	Books
	\ or |	Staves
	0	Orbs
	}	Misc items
	X	Corpses
	$	Gold
	Note that _whether_ items are picked up automatically or not, is 
	controlled by the in-game toggle Ctrl-A. Also note that picking up
	takes a turn, but only one turn (regardless of the number of items).
        If you teleport or blink onto a square with interesting items, these
        will not be picked up.

default_autopickup = true
	When set false, the game starts with autopickup turned off. You can
	still toggle autopickup in-game with Ctrl-A.

safe_autopickup = true
	When set, autopickup will not operate if there are visible unfriendly
	monsters (or statues.) If safe_zero_exp is set (the default), zero-XP
	monsters are considered friendly. 

safe_zero_exp = true
	If set, presence of only zero experience monsters (like plants) will
	cause autopickups, even if safe_autopickup=true is set. This option 
	also settles whether autoprayer considers such monsters risky.

pickup_thrown = false
	Pickup_thrown=true causes autopickup to grab thrown/fired missiles. 
	Many players use this because it eases ranged combat quite a bit. If 
	following suit, be aware that there are situations when there is no 
	time for picking up projectiles. Use Ctrl-A for switching off 
	autopickup altogether in such cases or set safe_autopickup=true.

pickup_dropped = true
	Pickup_dropped lets autopickup affect objects you've dropped. Set to 
	false to block autopickup for dropped objects. This can be convenient.

assign_item_slot = (forward | backward)
	When picking up items, the inventory slot into which the item goes is 
	normally the first free slot from a-zA-Z (this is the default "forward"
	behaviour). Setting assign_item_slot to "backward" changes the slot 
	assignment to the first letter after the last slot. 
	For instance, if you have items on 'a' and 'c', then with
	     assign_item_slot = forward, the next item will go into 'b',
	     assign_item_slot = backward, the next item will go to 'd' instead.
	With "backward", items dropped/fired and picked up later are more 
	likely to get their old slot back.

ban_pickup = <regex>
	List of item name regexes for items which autopickup will never touch. 
	You can use multiple ban_pickup lines. Some typical examples are
	  ban_pickup = degeneration, decay, confusion, potions? of slowing
	  ban_pickup = potions? of strong poison,potions? of poison
	  ban_pickup = inaccuracy
	  ban_pickup = scrolls? of paper, immolation, curse armor, curse weapon
	  ban_pickup = forgetfulness, uselessness, noise, torment

drop_mode = (multi | single)
	Single is the classical behaviour (and default): after pressing another
	key, that item will be dropped. Multi makes an inventory menu appear, 
	allowing the selection of items to be dropped. (You can also switch to 
	multidrop from the classic drop line using the '@' key).
	Multidrops are highly convenient. Be aware of the fact that every 
	single drop takes one turn. (This is different from picking up.) When
	selecting multidrops, the top right corner will show the estimated 
	number of turns.
	The order in which items get dropped is always from top to bottom in 
	the inventory listing.

pickup_mode = (multi | single | auto:X)
        Single is the classical behaviour (and default): when picking up
        items, you are prompted for them one by one. Multi makes a menu
        appear, where you can choose which items to pick up. Note that
        no matter how many items you choose, picking up will always take
        one turn.
        If pickup_mode is auto:X, where X is some number (for example,
        auto:5), then pickup will give a menu if there are at least X
        items on your square, and will prompt one by one otherwise.

drop_filter = <regex>
	When selecting items using the global (de)select keys (',' or '-') in 
	a multidrop listing, you can choose to apply a filter: only items 
	whose names match the filter will be selected. The filter strings are 
	regexes. For instance, to quickly select carrion and rotting chunks of 
	meat, you could use:
	  drop_filter = skeleton, rotting, corpse
	Other choices can come in handy as well, e.g. if you want to sacrifice
	regularly all weapons except axes, use:
	  drop_filter = axe, broadaxe
	Note that if you use this option, you will lose the (de)select all 
        keys. However, '*' inverts the current selection and so salvages this 
	problem.
	The default is empty.

Using a Lua script, you can define a function "ch_autopickup" to select
additional items for autopickup. Let's say you want autopickup to only grab food
if your character can eat it (let's say you're playing a kobold and you want to
stop picking up vegetables). You could use the following (if '%' is not in the
autopickup option):

{
function ch_autopickup(it)
    -- The "false" suppresses hunger checks to see if your character is hungry
    -- enough to eat food/chunks.
    return food.can_eat(it, false)
end
}

Here's a ch_autopickup that a mummy might find useful:

{
-- The mummy special. Remove % and ! from your autopickup option if you use
-- this.
function ch_autopickup(it)
    return food.can_eat(it, false)
        or ( item.class(it) == "Potions" and you.race() ~= "Mummy" )
end
}


4-b	Targeting.
-------------------

target_zero_exp = true
	Set to false to disable targeting zero exp monsters (i.e. plants) 
	in hostile targeting mode. This is usually convenient to do.

target_wrap = true
	Set to true if targeting should wrap around from last to first and 
	vice versa.

target_oos = true
        When cycling through items with 'x' look-around, setting target_oos to
        true allows you to jump the cursor to dungeon features (<> for stairs,
        Tab for shops, ^ for traps) and stashes (with the '*' and '/' keys) that
        are outside line-of-sight but in the main view. This is most sensibly
        used in connection with stash_tracking=all (see 4-g).  Also see also
        target_los_first below.

target_los_first = true
	When cycling through items/features with the 'x' look-around command, 
	setting	target_los_first to true will force the cursor to squares in 
	line-of-sight before going to squares outside LOS. Defaults to true.

confirm_self_target = false
	Setting this to true will make Crawl ask for confirmation whenever
	selecting the character as the target of a non-friendly-targeted spell 
	(i.e., something other than haste, healing or invisibility.)

default_fizzlecheck = false
	If set to true, this will require a confirmation when cancelling 
	target mode in a way which will make the activated ability or spell 
	fizzle (e.g., when casting Magic Dart and cancelling targeting.) 
	It can be further toggled during play with the key Ctrl+T.

4-c	Passive Sightings (via detection and rememberance).
-----------------------------------------------------------

detected_monster_colour = darkgrey
	Monsters found by detect creatures will be coloured this colour; e.g.
	  detected_monster_colour = lightred

detected_item_colour = darkgrey
	Items found by detect items will be given this colour, for example
	  detected_item_colour = green

colour_map = false
	Colours out of sight map features on the playing screen.

clean_map = false
	Cleans up out of sight monsters and clouds on the map. This is like 
	pressing Ctrl-C (clearing both main screen and level map) all the time.
	Setting this to true can be disconcerting for summoners.


4-d	Branding (Item and monster highlighting).
-------------------------------------------------

Branding refers to displaying particular monsters (e.g. summons) or items in a 
special way; special as in reversing fore- and background. There are several 
branding choices (these will not work everywhere; it depends on OS and 
terminal):
   standout         -- often the same as reverse, might be underline or dim
   bold             -- used by colour curses for brightening foreground colours
   blink            -- used by colour curses for brightening background colours
   reverse          -- this will probably work
   dim              -- probably no effect
   underline        -- this will probably work
   highlight:colour -- set background colour of branded monsters to "colour"
The last can be abbreviated to hi:colour.
See part Technical (6-) for dos_use_background_intensity under Windows and DOS.
By default, there is no branding activated.

heap_brand
	Brand heaps of items (more than one item or stack). For, example
	  heap_brand = reverse

friend_brand
	Brand friends in some way. This is very helpful for summoners. E.g.
	  friend_brand = hi:green
	shows friends with a green background. If the friend is itself green, 
	it'll show up as black on green.

stab_brand
	Some deities object to you stabbing monsters. Certain classes 
	specialise in stabbing monsters. Still other characters are happy if 
	they spot a monster before the monster spots them. In all these cases, 
	it helps to identify monsters that are unaware of the character (and 
	hence susceptible to being stabbed) without using the 'x' command. All 
	the normal 'brand' options apply. For example
	  stab_brand = hi:blue

may_stab_brand 
	Stabbing may be possible even if the monster is not asleep (if it's 
	confused or distracted, for instance). This option brands monsters that
	you *might* be able to stab. Primarily useful for worshippers of The 
	Shining One. Purists may consider this unnecessarily spoily.


4-e	Level Map Functions.
----------------------------

level_map_cursor_step = 10
	How many squares the cursor moves on the level map when using 
	Shift-direction or * direction.

item_colour = false
	Colours items on level-map.

show_waypoints = true
        If set to true (the default), waypoints will be numbered on the level
        map, assuming that they're on a floor square with nothing on it.
        Otherwise only a green dot will mark the square.


4-f	Travel and Exploration.
-------------------------------

travel_colour = true
        Option to turn off colouring the level-map with travel information. Few
        will set this to false; it's only there for backwards compatibility.

travel_delay = 20
        How long travel waits after each move (milliseconds). Depends on
        platform. Setting to -1 will jump to end of travel - you will not see
        the individual moves.

travel_stair_cost = 500
	travel_stair_cost determines how costly interlevel travel considers 
	stairs.	With a high travel_stair_cost (such as the default of 500), 
	interlevel travel will always choose routes with the minimum number of 
	level changes possible.	If you set travel_stair_cost to a low value 
	(such as the minimum of 1), interlevel travel will treat a staircase 
	just like a normal move, and it may consequently choose routes that 
	involve extra level transitions. This can be disconcerting in branches 
	with elevator-type stair arrangements, particularly in the Lair, where 
	there are typically long chains of elevator stairs, because travel will 
	go out of its way to use the elevator and minimise total travel 
	distance.
	
travel_avoid_terrain = (shallow water | deep water)
	Prevent travel from routing through shallow water. By default, this 
	option is commented out. For merfolk and/or characters with permanent 
	levitation, 
	  travel_avoid_terrain = shallow water, deep water
	will prevent travel or explore from going through any water.

travel_exclude_radius2 = 68
	The square of the radius around travel-excluded squares where travel 
	will refuse to go. Set to zero if you want to exclude single squares. 
        The default of 68 ensures that travel won't enter line-of-sight of any
        dangerous thing at the travel-exclusion center.

travel_stop_message = <list of regexes>
	Travel will always stop upon hitpoint loss, confusion, stat drain, 
	getting encumbered, catching sight of a non-friendly monster, and 
	teleporting. In	addition, a message containing one of the expressions 
	in travel_stop_message will stop travel. For example, 
             travel_stop_message = Something appears
	stops travel if Xom grants us a gift suddenly. To limit a substring 
	match to a message channel, prefix the substring with the channel name 
	and a colon. For instance, if you want travel to stop when you're hit 
	by divine retribution, you could use:
             travel_stop_message = god:wrath finds you
	If you'd like to stop travel for any message sent to a particular 
        channel, use a travel_stop_message line with that message channel name
        and a colon alone. For example, if you've an amulet of the gourmand, and
        are hankering after rotten meat, or you're playing a ghoul: 
             travel_stop_message = rotten_meat:
	Stop travel for any god messages (including prayer)
             travel_stop_message = god:
        Multiple travel_stop_message lines can be used.

explore_stop = items,stairs,shops,altars
	Explore will stop for one of these conditions. Whatever you set this 
	option to, anything that stops travel will also stop explore. Multiple 
	explore_stop lines are *not* cumulative! The last explore_stop line 
	will override all previous explore_stop lines. 

runrest_ignore_message = <string>
	This only works if runrest.lua has been sourced already in init.txt.
	Any message containing the string will *not* stop your run. E.g.
	  runrest_ignore_message = prayer ends

runrest_ignore_poison = <poison damage>:<minimum hp>
	This only works if runrest.lua has been sourced already in init.txt.
	Poison damage of x will be ignored if you have at least y hp if you've 
	defined a runrest_ignore_poison = x:y option. Running here means 
        shift-running and resting only. Only one runrest_ignore_poison line is
        considered.  Note that for this work, you should also tell Crawl to
        ignore the "You feel sick messages". For example,
	  runrest_ignore_message = You feel.*sick
	  runrest_ignore_poison = 4:100 

trapwalk_safe_hp = <trap_name>:<minimum_hp>, ...
        This only works if trapwalk.lua has been sourced already in init.txt.
        Any square containing one of the listed trap types will be considered
        safe for travel if your hp is greater than or equal to the number
        connected to the trap in question.

        All the existing trap types can be used, but in practice only the
        mechanical traps (dart, bolt, arrow, needle, spear, axe, blade) make
        sense. Note that travel tries to avoid traps if this is easily possible.
        Defaults to none. For example,
              trapwalk_safe_hp = dart:15, needle:25, spear:50

Using small scripts in init.txt, travel can get even more convenient.

* Deciding whether monsters are worth stopping for:

Defining a "ch_stop_run" function affects the monster stop condition for *all*
run modes: shift-running, travel, explore and interlevel travel.

{
function ch_stop_run(mons)
    local name = mons.name

    -- Stop running only if these monsters get closer than 3 squares
    if name == "swamp worm" or name == "big fish" 
            or name == "giant goldfish" or name == "lava worm"
            or name == "butterfly" then
        -- mons.x and y coords are relative to the player.
        local dist = mons.x * mons.x + mons.y * mons.y
        if dist >= 9 then return false end
    end
    
    return true
end
}


4-g	Stashes.
----------------

stash_tracking = (explicit | dropped | all)
        A stash is a heap of items tracked by crawl. You can search in your
        stashes with Ctrl-F. This options rules how stashes are generated.
        When stash_tracking is set to 'explicit' (the default), you have to
        explicitly tell the game what squares you want it to keep track of. You
        do that by stepping onto the square containing your stash of goodies and
        hitting Ctrl+S. The game will now keep track of what's on the square,
        when you add and remove stuff from your stash. If you remove everything
        from that square, the game will stop tracking the square altogether. You
        can also erase a stash square with Ctrl-E.
	
        When stash_tracking is set to 'dropped', any square where you drop 
	something becomes a stash, and the game keeps track of all such 
	squares.

	When stash_tracking is set to 'all', the game marks any square where it 
        sees any object as a stash. That gives you a comprehensive list of
        everything your character sees in the dungeon, but may slow the game
        down and use too much memory on older computers.

4-h	Command Enhancements.
-----------------------------

auto_list = false
	Change to true if you want to automatically list appropriate inventory 
	items for commands like eat and read. This is like immediately hitting 
	'?', and can be confusing to beginners because they won't get to see 
	the prompts. This option does not apply to spell casting... Conjurers 
	would probably find that really annoying. 

lowercase_invocations = false
	Set this option to true if you prefer to have invocations on 'a'-'e' 
	instead of the traditional 'A'-'E' (which is the default). Setting to 
	true save invocations an annoying shift keypress.

easy_open = false
	Open doors by moving on to them. Highly convenient. Note that travel 
	and exploration will automatically open doors depending on this option.

easy_butcher = false
	If true, auto-switch to uncursed short blade for butchery.

easy_armour = true
	Allows auto removal of armour when dropping it. 

easy_confirm = (none | safe | all)
	Make confirmation questions easier to answer:
		none = force capitals on Y/N questions
		safe = force only on questions that will end game (default)
		all  = never force capitals
	WARNING TO KEYPAD USERS: The number 7 is mapped to the letter 'y', 
	which can result in accidentally answering yes to questions; it is 
	suggested that you use a value of 'none' or 'safe'

easy_quit_item_lists = false
	Setting this option to true allows the quitting of item listing with 
	space as well as escape. These lists are essentially all of those that 
	are requesting an inventory item and accept '?' and '*'.
	The identify list will never easy quit. The default is false.

easy_exit_menu = true
	In multidrop (and pickup) menus, paging past the end will drop out of
        the menu if easy_exit_menu is true.

default_autoprayer = false
	When set to true, the game will start with automatic prayers. This 
	option can be toggled in-game with Ctrl-V.
	Letting Crawl pray throughout and automatically can be useful for gods 
        like Trog and Makhleb, who constantly demand kills from their followers.

        Automatic prayers take a turn like manual prayers and will only happen
        if
	- there is no hostile monster in sight
	- some further conditions (like not standing at an altar)
	Note that even when you're praying, you can renew prayer anytime.
	Also note the option safe_zero_exp (see 4-a) decides whether zero 
	experience monsters (like plants) are considered hostile.

sort_menus = auto:5
        When set to true, items are sorted by description in inventory and
        pickup menus. When set to false (default), items are ordered by
        equipment slot. When set to a number - using a syntax of the form
        sort_menus = auto:5 - items are sorted by their description if
        the total number of items in that category is at least that
        number; in the default case, having 4 kinds of potions would not
        sort them, but having 5 would.
	

4-i	Messages and Display Enhancements.
------------------------------------------

show_uncursed = true
	This option adds the text "uncursed" to items where the curse status is 
        relevent and known. Does not bother to show "uncursed" on items that are
        fully identified (showing pluses), since that wound be redundant and 
	waste space. Should be set to true.

hp_warning = 25
	hp_warning gives "* * * LOW HITPOINT WARNING * * *" on the danger 
        channel when the player takens damage and their hitpoints are less than
        this percentage of their maximum (use 0 to turn off these messages). It 
	is recommended to use
	  hp_warning = 55

terse_hand = true
	Set this to false to have the "in hand" description on the main screen 
	the same as the inventory. The default setting of true will give the 
	newer more terse description that should fit the limited space better 
	(but will be harder for new players to understand).

delay_message_clear = false
        Setting this option to true will delay the clearing of messages until
        the message space is full (default is false which results in clearing
        between player actions).

always_greet = false
	always_greet will give the race/class and god messages everytime the 
	game is started. 

menu_colour = <colour>:<regex>
	This prints a line (of the inventory, a menu, or the discoveries 
	screen) containing regex in the	stated colour. There can be several 
	statements in a list, or also several menu_colour lines. When using
	several menu_colour lines, the colour of the _first_ matching regex 
	is applied. For a list of colours, check the colour option in 6-a.
	To colour worn stuff and highlight cursed items, take
	  menu_colour = lightred: cursed.*(worn|neck|hand|weapon)
	  menu_colour = green:(worn|neck|hand|weapon)
	  menu_colour = red: cursed
	If you frequently die because you forget to use emergency items, try
	  menu_colour = cyan:(potions? of heal wounds|teleportation)
	  menu_colour = lightcyan:(blinking|wand of (fire|cold|draining))
	To quickly check what potions were trashed by a mummy curse, use
	  menu_colour = lightred:potions? of (degeneration|decay)


4-j	Missiles.
-----------------

fire_items_start = a
	Sets the first inventory item to consider. Default is a, many use c.

fire_order = launcher, dart, stone, dagger, spear, handaxe, club
	The list should be on one line of items, with commas between items.
	'launcher' refers to firing the appropriate missile for the wielded 
	weapon (ie crossbow, bow, sling, blowgun). You'll almost certainly 
	want it first, as it'll be ignored when you're not wielding a ranged 
	weapon. The default is 
	  fire_order = launcher, dart
	To quickly experiment with a weapon-throwing character - e.g. to 
	make your Berserker actually use those three spears he carries around,
	try a line similar to:
	  fire_order = launcher, dagger, spear, handaxe, stone, dart

<See also pickup_thrown in A.4a.>

4-k	Message Channels.
-------------------------

Crawl communicates to the players with its message window. Every message belongs
to one of the so-called channels. The behaviour of each channel can be changed
with the option

	channel.CHANNEL_NAME = (COLOUR | mute | default | on | off | plain)

CHANNEL_NAME can currently be one of these:
   plain           = regular text (and things "uncoloured")
   prompt          = input prompts to the player
   god             = messages from the gods
   pray		   = standard praying messages (start/end of prayer)
   duration        = messages about character spells/effects wearing off
   danger          = serious threats to the characters existence
   food            = warnings about food
   warning         = various other warnings
   recovery        = recovery from disease/stat loss/poison conditions
   multiturn	   = indicates long actions (wearing armour, dissecting etc.)
   talk            = monsters talking (acting)
   intrinsic_gain  = level/stat/species power gains
   mutation        = gain/lose mutations
   monster_spell   = messages about monsters gesturing and casting spells
   monster_enchant = messages pertaining to monster enchantments (up or down)
   monster_damage  = messages telling how damaged a monster is
   rotten_meat     = messages about chunks/corpses becoming rotten

The channel options are
   mute      = show no messages from channel (dangerous, be careful!)
   default   = turn channel on to it's default scheme
   alternate = turn channel on to it's alternate "colourful" scheme
   on        = same as default
   plain     = make channel the same colour as the "plain" channel
               (won't do anything silly like "mute" if plain == mute, though)
   off       = same as plain
   COLOUR can be any of the colours described in section 6-a (colours option).

The only multi-colour channels currently are monster_damage and god. All other
channels are defaulted to on, except for multiturn, which defaults to mute.
Note that the template init.txt sets 
          channel.multiturn = on
in order to help new players. You may want to comment out this option, if 
the messages are too verbose.      

4-l	Inscriptions.
---------------------

In Crawl, items can be manually inscribed with the '{' command. This adds a 
note in curly braces to the item inscription. Several inscriptions are
functional, namely all containing one of the following
 @w9	-- now typing 'w9' will wield this item
 @*9	-- now any action command followed by '9' will use this item
 !w	-- before wielding this item, Crawl will ask for confirmation
 !*	-- any action with this item causes a prompt
 =g	-- item will be picked up automatically if autopickup is on
 =k     -- item will be ignored in all listings on the ground
	   (it can still be picked up if it's the only item on the ground)
(in the example 'w' could be any sensible command and '9' could be any digit).
An item may contain more than one shortcut. 

autoinscribe = <regex>:<inscription>
	Any item whose description contains the regex will be automatically
	inscribed (if autopickup is toggled on). For example, marking all 
	royal jellies and honeycombs eases the Hive (if food is not in the
	autopickup option):
	  autoinscribe = royal jell:=g
	  autoinscribe = honeycomb:=g


4-m	Macro related Options.
------------------------------

flush.failure = true
flush.command = false
flush.message = false
	These are useful when using macros. Setting one of these sub-options 
	to true will cause the entire input buffer to be dumped and thus 
	effectively stop the macro. The sub-options currently are
		failure -- when spells/abilities get miscast 
		command -- whenever the game is about to get the next command
		message -- whenever the game outputs a non-mute message 


5-  Character Dump.
===================

5-a	Items and Kills.
------------------------

The character dump or morgue files end with a list of all monsters that perished 
while the character was active. By default, dead monsters are grouped in three parts:
   Vanquished Creatures    -- monsters killed by the character
   Collateral Kills	   -- kills of friendly monsters
   Others		   -- all other casualties (e.g. traps, hostile monsters)

kill_map = friend:you, other:you
        will merge friendly and other kills into the main vanquished creatures
        list.  Note that the merging is only for display (the game still
        maintains three separate lists internally) and that kill places (see
        below) may be in the wrong order for merged entries. The default is an
        empty list.

dump_kill_places = (none | all | single)
	In the Vanquished Creatures list, this option controls how the 
	locations of each kill are displayed. Use 'none' to suppress place 
	display altogether, 'all' to display all known (up to 5) kill places, 
        anything else to the default of showing kill places only for single
        kills

dump_item_origins = artifacts, rods
	The game remembers where you find items. If you want this item origin
	memory listed in your dumps, use this option to select which items get 
	annotated. Available selectors are: 
		artifacts, ego_arm, ego_weap, jewellery, runes, 
		rods, staves, books, all, none.
        If you use multiple dump_item_origins lines, the last line takes effect;
        all preceding lines are ignored.

	If you don't want any items to be annotated, set dump_item_origins to 
	none, and set dump_item_origin_price to -1.

dump_item_origin_price = 100
	Item origins are dumped if the price of the item is greater than or 
	equal to this amount. Set this to -1 to prevent selection by price.

dump_message_count = 4
	The number of last messages to be displayed in character dump files. 

dump_order  = header,stats,misc,notes,inventory,skills
dump_order += spells,mutations,messages,screenshot,kills
        Controls the order of sections in the dump. You can use multiple
        dump_order lines - all lines but the first must use dump_order +=

verbose_dump = false
	verbose dump causes less important item details to appear in character 
	dumps.


5-b	Notes.
--------------

Crawl can automatically log certain events during play. You can read these in 
the dump or morgue files. Below are options for tweaking this behaviour.

use_notes = true
	Set to true to get note-taking. The following events are logged:
	- Gaining or losing a level
	- Entering a dungeon level for the first time
	- Memorizing a spell of higher level than any learned before
	- Becoming a worshipper of a god
	- Abandoning a god
	- Receiving a gift from a god (except Xom)
	- Being able to invoke a godly power for the first time
	- Identifying items (see below)
	- Killing OOD or unique monsters (see below)
	- Reaching critical HP levels (see below)
	- Gaining or losing mutations
	- Reaching significant levels in a skill (see below)
	You can use the command ':' for manually adding notes.

note_items = <regexes>
        When an item is identified, it will be noted if it is an artifact
        (fixed, unrand, or random) or if its short description matches a regex.
        E.g.
	  note_items = rod,book,rune,aquirement

ood_interesting = 8
        Monsters which are out of depth (OOD for short) for their current level,
        e.g. a dragon on level 2, will be noted if they are out of depth by at 
	least ood_interesting levels. To disable OOD monster noting, set 
	ood_interesting to 500; the default is 8.
	Unique monsters are always noted, regardless of this setting.
	OOD monsters are only noted in the main dungeon.

note_hp_percent = 5
	If your HP falls below a certain note_hp_percentage of your max HP, a 
	note will be taken. There is some code to avoid repetitions of notes
	based on the same incident. The default is 0, which means no noting.

note_skill_levels = 1,5,13,27
	This sets which skill levels are noteworthy. You can have multiple 
	note_skill_levels lines. The default is nothing (no notes.)

note_skill_max = false
	Setting this option will cause a note whenever a new maximum in skill
	levels is reached. If note_skill_max is true and note_skill_levels is 
	nonempty, notes will be taken whenever either of the criteria are met.
	
note_monsters = <regex list>
	Monsters whose name matches an item in this comma-separated list are 
	considered interesting. You can have multiple note_monsters lines. E.g.
	  note_monsters = Klown,orb of fire
	
note_messages = <regex list>
	Messages which match an item in this comma-separated list are 
	considered interesting. You can have multiple note_messages lines. E.g.
	  note_messages = Something interferes
	  note_messages = protects you from harm
	If you want all banishments to the Abyss noted, use
	  note_messages = [bB]anish.*Abyss
	If you want a note when your draconian scales turn <colour>, use
	  note_messages = Your scales start

note_all_spells = true
	Will add a note for each spell memorised.

6-  Miscellaneous.
==============

6-a	All OS.
---------------

macro_meta_entry = true
        macro_meta_entry lets you specify non-printable keycodes like \{3} when
        creating a macro. For instance, if you want to keymap 0 to Escape, you'd
        use a target keycode of \{27}.

colour.OLDCOLOUR = NEWCOLOUR
	Useful for terminals where some colours are hard to read (and cannot
	be adjusted), as well as for creating a custom scheme, especially when 
	used with the background option on a terminal with a non-black 
	background.
	Format is colour.OLDCOLOUR = NEWCOLOUR, later rules take preference and
	the NEWCOLOUR is always literal (ie. it won't re-evaluate to a 
	different colour).
	The colours are:
		black, blue, green, cyan, red, magenta, brown, lightgrey, 
		darkgrey, lightblue, lightgreen, lightcyan, lightred, 
		lightmagenta, yellow, white
	with lightgray = lightgrey, darkgray = darkgrey. Some examples:
	  colour.lightgray = black
	  colour.lightcyan = cyan
	  colour.yellow    = brown

wiz_mode = (no | never | yes)
	Wizard mode options (available only in WIZARD compiles):
	  yes   -- start games in wizard mode (game will not be scored)
	  no    -- still allows player to enter wizard mode after start of game
	  never -- never allow a wizard command to be used

char_set = (ascii | ibm | dec)
	Chooses different character sets for the game play screen. DOS and
        Windows users will want to use the IBM character set, Unix users will
        prefer DEC or plain ASCII.

cset_ascii, cset_ibm, cset_dec, cset_any
        Can be used to change individual characters in a specific character 
        set (the character set used for display is determined by the char_set 
        option). The syntax is the same for all of these; cset_any changes
        characters in all character sets.

cset_XXX = <dungeon_character_name : symbol>
        a list of these is allowed, as well.

        The possible entries for dungeon_character_name are:
           wall, wall_magic, floor, floor_magic, door_open, door_closed, trap,
           stairs_down, stairs_up, altar, arch, fountain, wavy, statue,
           invis_exposed, item_detected, item_orb, item_weapon, item_armour,
           item_wand, item_food, item_scroll, item_ring, item_potion,
           item_missile, item_book, item_stave, item_miscellany, item_corpse,
           item_gold, item_amulet, cloud
        Most of these are self-explanatory. "arch" is used for shops and
        portals.  "floor_magic" and "wall_magic" are used to display
        magic-mapped squares on the level map. "invis_exposed" is the character
        for water creatures submerged in shallow water, or invisible creatures
        wading in shallow water.

        Symbols can be specified using a letter, or by a number (decimal code).
        For an example on IBM displays,
            cset_ibm = wall:219, arch:0
        shows walls as solid blocks and shops and portals as '0'.

feature = <regex> { <symbol>, <magicmap symbol>, <view colour>,
                    <levelmap_magic_colour>, <levelmap_seen_colour> }
        where <regex> is a regular expression describing a dungeon feature. This
        regex should match the description when using the 'x' command. In case
        the regex matches several descriptions, all such features are affected.

        The list in {...} specifies the appearance of the dungeon feature(s),
        and should be self-explanatory. <symbol> can be used to override the
        above cset options, or also to distinguish among subtypes of a
        character.

        'magic' always refers to magic mapping. So the <magicmap symbol> entry
        determines what symbol will be used for features only detected via magic
        mapping.

        Leading parameters in the {...} list can be omitted by leaving them 
        blank and using placeholder commas. Trailing parameters can be omitted
        without placeholder commas.

        Multiple feature option lines can be used, as can multiple feature
        descriptions strung together on the same line separated by semicolons.

        Examples:
            feature = rock wall { , , red }  # shows rock walls in red
            feature = metal wall {#}         # use '#' for metal walls


6-b	DOS and Windows.
------------------------

dos_use_background_intensity = false
        On DOS and Windows, if you're using a console that can do high-intensity
        background colours, set this option to true for superior
        friend-branding. If your console doesn't like this option, some friendly
        monsters will appear as blinking characters (and setting this option to
        false may be advisable to preserve your sanity in such cases).

6-c     Unix
------------

background = <colour>
        Sets the default background colour by name (defaults to BLACK). This
        may be useful if you're using a terminal with a background colour other
        than black (such as an xterm), but this option is still experimental
        and the results may not be very good.