This document aims at easier Crawling (in Stone Soup) by explaining:
- macros and keybindings
- lua snippets in init.txt

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

Macros and Keymaps.
===================

Following Brent Ross's phrasing, the simple explanation is:

Command macros make keys into commands.
Keymaps make keys into other keys.

And him a bit more verbose:

For the most part, people will probably want command macros.  They allow 
for things like making a key run a sequence of commands (e.g. associating
a key stroke to the casting of a certain spell) without having to worry 
about messing up what that key does at prompts (e.g. you can macro a 
number or letter without worrying about it making the substitution when 
you're trying to drop an item).

Keymaps are for when you want to fix layout and behavioural problems on 
your keyboard (i.e. unrecognised numpad sequences can by mapped into 
their numbers, foreign keyboard layouts can be modified to be more 
comfortable). There are also special sets of keymaps for the level-map 
and targeting modes, which allow for keymaps that are restricted to just
those situations. 

[The keymap system is currently being overhauled. I hope that the 
examples below will also work in the new version. 
From what I gather, the keybindings will be moved to a file (which is
good). I hope that it will still be possible to define macros in-game:
this makes testing so convenient. And it should be possible to have
macros at all three levels (main, level map, targeting).]

How to create macros?
---------------------
The simplest way is in-game: press the '~' key (this may be a bit
awkward on certain keyboard layouts). Then choose a key to assign
for your macro, and enter the command sequence. In some cases, Crawl
will display a funny number.  These numbers are the key codes for
certain (non-alpanumeric) keys, and can vary between different
systems.

The following keys and combinations are sensible to use:
- The function keys are good choices, possibly modified by Shift, Ctrl, 
  or Shift-Ctrl.
- On some systems, it is possible to also incorporate the Alt (meta) key.
- All alphanumerical keys. Alphanumerical keys can also be combined with 
  Shift or Ctrl keys (note that usually Ctrl-Shift-A is the same thing as 
  Ctrl-A). Be careful that you do not redefine important game keys. 
- All special keys: digits, punctation, etc. These can also be combined 
  with Ctrl. Alt may also work. Again, do not redefine vital game commands.

For example, on my home system (Windows), I get key codes
 F1		    \{368}		A		  A
 Shift-F1	    \{1392}		Ctrl-A		  \{1}
 Ctrl-F1	    \{880}		Alt-A		  a
 Alt-F1		    \{2416}		Ctrl-Shift-A	  \{1}
 Ctrl-Shift-F1	    \{1904}		Ctrl-Shift-Alt-A  \{3905}
 Ctrl-Alt-F1	    \{2928}
 Shift-Alt-F1	    \{3440}
 Ctrl-Shift-Alt-F1  \{3952}

After defining such a macro, you should test it. If you are comfortable
with the macro you have defined, you should then save the macro.
To save all macros and keymaps, press '~' and then 's' to save
macros at the tilde prompt).

The macros are stored in the file macro.txt in your main Crawl directory. 
(You can change where the file is read from and written to by specifying an
alternate directory on the command line with -macro <dir>.)
This file is human readable and editablel you just have to figure out the
magic numbers as shown above for F1, Ctrl-A, etc. When using strange 
keys as triggers for a macro, you may need to edit macro.txt manually.

Note that you can make comments in macro.txt using lines with a
leading '#'. In this manner, you can remind yourself which keys the
numbers belong to (on your system).

See below for examples of macro definitions.

Keymaps work in exactly the same way. There are three different keymaps:
one for the main view, one for the level map, and one
for the targeting map. In macro.txt, these are differentiated by
 K  - main screen
 K1 - level map
 K2 - targeting
However, you should not keymap alphabet letters; otherwise you
will meet difficulties accessing your inventory!

Here are some macros and keymaps that have been considered useful by 
at least a few players. For the sake of completeness, both key line and 
command line are given, but you should really substitute your own keys 
here; these may not always work for you :)

Spellcasting.
-------------
# F1: cast spell a at previous target
M:\{368}
A:Zap

#: Shift-F1: cast spell a at nearest target
M:\{1392}
A:Za+.	 

Note that you can assign new letters to your spells with '=' so,
if you like, you can always have you primary attack spell on a. You
may want to set the option
 target_zero_exp = false
when using macros like this so that you do not accidentally crystal spear
a plant.

Easier Nemelex hoovering.
-------------------------
# F12: Nemelex hoover
K:\{379}
A:w0Eyp,y

This sets up your portable altar, prays there, confirms, and picks it up 
again. The sequence assumes that the altar carries the inscription {@w0}. 
Actually, this can be achieved automatically with the init.txt line
 autoinscribe = portable altar:@w0
If you have your weapon on slot a, feel free to add 'wa' to the end of
the sequence.

Easy surroundings mode.
-----------------------
K:0  
A:x*

K2:0
A:*

Here I use '0' for the numpad, but 'x' would also be a good choice (then 
you should set K2:x A:* only).
This makes going through items in the surroundings very easy. You can use
Enter to go directly to the item under the cursor. 
Options you may want to check here are
 target_wrap, target_oos, target_los_first.
If you want to cycle through items out of sight, set 
 stash_tracking = all
 target_oos = true
(as only out-of-sight _stashes_ will be checked).

# F5: explore (both in main and target screens)
K:\{372}
A:\{15}

K2:\{372}
A:\{32}\{15}

I find the Ctrl-O key awkward to type, so I have mapped it to F5. The 
second keymap makes F5 in target mode do two things: leave target mode 
(\{32} is the Escape key) and then starts exploring. 
Users of BSD terminals will definitely want to remap Ctrl-O, as the terminal
intercepts it by default.

General Keybindings.
--------------------
With my German keyboard layout, the keys '^' and '@' do not work 
properly. The first problem is dealt with the map
K:\{17}
A:@
which maps @ to @ in the main mode :)

Other keymaps I found useful:
- Tab for ' (switching weapons in slots a and b)
- Backspace for p (both Praying in main and Previous in target mode)
  (Unfortunately, Backspace is the same thing as Ctrl-Left. Perhaps 
  something can be done about this.)

Lua snippets.
=============

You can copy the following lua code verbatim in your init.txt; it is up 
to you to apply appropriate modifications. It would be nice of course, 
if someday these snippets turn into full-grown lua files with their own 
options.

For a tutorial of the language Lua, refer to the following link:
         http://lua-users.org/wiki/TutorialDirectory

Advanced autopick: ch_autopickup.
---------------------------------
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. 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
}

Advanced autopick: conditional ban_pickup.
------------------------------------------

There is an overlap in functionality with the above mummy function.

# mummies can't quaff or hunger
<if you.race() == "Mummy" then>
    	ban_pickup = potion
    	ban_pickup = sustenance
<end>

# ban harmful potions for non-Transmuters
<if you.class() ~= "Transmuter" then>
    	ban_pickup = degeneration, decay, potions? of poison
    	ban_pickup = potions? of confusion, potions? of slowing,
    	ban_pickup = potions? of paralysis, strong poison
<end>


# Trog doesn't like Spellcasting
#<if you.religion() == "Trog" then> # (doesn't work), so

<if you.class() == "Berserker" then>
  	ban_pickup = book
<end>

Ignoring certain monsters when running.
---------------------------------------
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
}