                 /----------------------------------------\
                <        Scripting for ToME with lua       >
                 \----------------------------------------/

    So, you want to patch ToME eh? Maybe you've had a look at how the edit files
    work, maybe even added your own race/class, but want to go further and add
    new racial (U) or magic (m) powers. Well these help files will show a little
    bit of how to do that.

    I am not a master at this kind of thing. I wrote a small script, with much
    help from DarkGod, and he subsequently asked me to write these help files. I
    was looking forward to when the lua help files came out so that I could look
    at them myself. Little did I know I'd be asked to write them. Therefore I
    apologise for any inaccuracies or errors that you find, and if you care to let
    me know of any improvements which could be made (especially if you're an
    experienced programmer/scripter), I'd love to know. Email me at
    fearoffours@moppy.co.uk.

    === The example scripts ===

    These help files take the form of a tutorial, adding a line at a time to a
    script, and explaining important concepts along the way. To see it all in
    action, I strongly suggest that you download my example script pack from
    http://www.moppy.co.uk/angband.htm. As well as including all the
    scripts covered in these help files, they also include the addition of my
    "hina" race which has a Lua scripted racial power which you might like to look
    at. There's also a quest which I will be including documentation for as a
    tutorial soon. Plus there's all the other lua scripts in the lib\scrpt
    directory to look at. Most of what you see in these files has been learned from
    those files anyway!

    The source code is invaluable as well. There's a searchable and browsable
    version of the latest ToME source code available online at
    http://angband.oook.cz/. Use it!

    If you don't want to download and install the example scripts, then just
    follow the tutorials with a text editor open! But I'll say it again, it's a lot
    easier if you download and install the example scripts.

    This file goes on to explain the concepts of scripting, programming,
    variables and functions. If you're familiar with these concepts, you might
    as well take a look at how to add a power to the U menu in the
    Scripting a racial power file.

    === Defining some basic stuff ===

    Computers don't do anything that they're not told to do. When we script, or
    program, we must assume they know nothing. We have to tell them each little
    bit of information from the ground up.

    A program, or a script (we'll talk about exact differences later) is like a
    set of instructions. Let's imagine that people responded to programs, and
    that we had a program called "Housework". Its series of instructions might
    look something like this:

    Do the Washing up.
    Clean the kitchen.
    Dust the shelves.
    Hoover the lounge.

    Each step above could be called a function, as they are all actions that
    need to be carried out. Now to you and me, we'd understand that program just
    fine, but if someone didn't know HOW to wash, or what hoovering was, they'd
    soon run into problems. For those people we'd need to define each function
    clearly. Thus "do the washing up" might be -

    Run hot water into bowl.
    Add washing up liquid.
    Put dirty plates into bowl
    Scrub plates till clean
    Place clean plates on rack to dry,

    There's still plenty of problems here though, We've not said to turn the tap
    off, or what the bowl is, or to wash any dirty cutlery, mugs, saucepans etc
    etc. Whilst this might seem fairly obvious to a person, this is how we need
    to think when writing programs for computers.

    Lets look now at some of the terms we're going to be using, in the rest of
    these help files, and what they mean...

    === Variables and Constants ===
    A variable is a way to store information in a computer.  Just as you store
    things in your own memory, you can store things in the computers memory. And
    just as things change in your memory, so things can change in the computer's
    memory. This factor of change is why they're called "variables" and not
    "statics".

    For instance, you may have a friends email address committed to memory, but
    things change over time, they get a new ISP or domain, and so their email
    address changes. You commit this new address to memory, and eventually
    forget the old one. The thing you have stored in your memory is the same
    (your friends address) but the value(property) of what you have stored has
    changed (from friend@old-address.com to friend@new-address.com).

    Variables are the building blocks out of which you will create your patch.

    A variable which will *never* change its value is called a constant.

    ===Functions===

    A function is a series of steps or statements, grouped together and given
    one name. When you want to carry out those steps, you simply ask the
    computer to carry out that function. To go back to our original example,
    rather than saying, "I'd like you to run some hot water into a bowl, add the
    washing up liquid, put the dirty plates into it, and then scrub them till
    they're clean", we just say "do the washing up".

    This is where we come to the difference between scripting and programming.
    With scripting  we can use the functions and variables that exist in the
    ToME code. Maintainers like DarkGod have already made sure that the
    computer knows how to "do the washing up", including turning the tap off and
    what the bowl is. All we need to do in our script is say "do the washing
    up". Or to look at it in a more relevant way, the game has been coded so
    that when a magic missile is fired, a bolt or beam spell with a black line
    of asterisks will be drawn in the direction indicated by the player, the
    mana of that player will be used up, the monster will take the appropriate
    amount of damage and so on. All we need to do in our script is say "fire a
    magic missile".

    As you script, you will still be designing your own functions, and
    variables, but the hardest parts have been done for you!

    Not every function and global variable in the source-code has been exported to
    use in your scripting. But the ones that have are easily identifiable by
    looking in any source files with the extension .pkg . Chris Hadgis has written
    some excellent documentation which outline the use the most important
    functions in some of these files. They outline the functions from the

    OK, the first tutorial proper is on adding a racial power .

                                 This file by fearoffours (fearoffours@moppy.co.uk)