|||||oy
#####R             /----------------------------------------\
#####R            <        Scripting for ToME with lua       >
#####R             \----------------------------------------/

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
[[[[[gfearoffours@moppy.co.uk].

#####R=== 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
[[[[[Ghttp://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\scpt 
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 
[[[[[Ghttp://www.t-o-m-e.net/cvs.php]. 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 
*****lua_pow.txt*0[Scripting a racial power] file.


#####R=== 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 ir, act as a "ball"
 * Allow "target" mode to pass over monsters
 * Affect grids, objects, and monsters
 */

#####GDescription
Cast a ball-beamed spell of type "typ" in direction "dir" for damage
"dam" points with a radius of "rad" grids.

#####GParameters
> "typ" is the type of damage
  *****fields.txt*0[GF_fields]
> "dir" must be from 0 to 9.
  *****fields.txt*0[direction]
> "dam" is the number of points of damage.
> "rad" is the radius of the effect of the damage (must be <= 16).

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

#####R=== fire_ball ===

#####GDeclaration
    extern bool fire_ball(int typ, int dir, int dam, int rad);

#####GFile
    spells2.c

#####GComment
/*
 * Cast a ball spell
 * Stop if we hit a monster, act as a "ball"
 * Allow "target" mode to pass over monsters
 * Affect grids, objects, and monsters
 */

#####GDescription
Cast a ball spell of type "typ" in direction "dir" for "dam" points of
damage. The ball has a radius of "rad" grids.

#####GParameters
> "typ" is the type of damage
  *****fields.txt*0[GF_fields]
> "dir" must be from 0 to 9.
  *****fields.txt*0[direction]
> "dam" is the number of points of damage.
> "rad" is the radius of the effect of the damage (must be <= 16).

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

#####R=== fire_bolt ===

#####GDeclaration
    extern bool fire_bolt(int typ, int dir, int dam);

#####GFile
    spells2.c

#####GComment
/*
 * Cast a bolt spell
 * Stop if we hit a monster, as a "bolt"
 * Affect monsters (not grids or objects)
 */

#####GDescription
Cast a bolt spell of type "typ" in direction "dir" for "dam" points of
damage.

#####GParameters
> "typ" is the type of damage
  *****fields.txt*0[GF_fields]
> "dir" must be from 0 to 9
  *****fields.txt*0[direction]
> "dam" is the number of points of damage.

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

#####R=== fire_beam ===

#####GDeclaration
    extern bool fire_beam(int typ, int dir, int dam);

#####GFile
    spells2.c

#####GComment
/*
 * Cast a beam spell
 * Pass through monsters, as a "beam"
 * Affect monsters (not grids or objects)
 */

#####GDescription
Cast a beam spell of type "typ" in direction "dir" for "dam" points of
damage.

#####GParameters
> "typ" is the type of damage
  *****fields.txt*0[GF_fields]
> "dir" must be from 0 to 9.
  *****fields.txt*0[direction]
> "dam" is the number of points of damage.

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

#####R=== fire_druid_ball ===

#####GDeclaration
    extern bool fire_druid_ball(int typ, int dir, int dam,
        int rad);

#####GFile
    spells2.c

#####GComment
/*
 * Cast a druidic ball spell
 * Stop if we hit a monster, act as a "ball"
 * Allow "target" mode to pass over monsters
 * Affect grids, objects, and monsters
 */

#####GDescription
Cast a ball spell of type "typ" in direction "dir" for "dam" points of
damage. The ball has a radius of "rad" grids. The spell follows a mana
path.

#####GParameters
> "typ" is the type of damage
  *****fields.txt*0[GF_fields]
> "dir" must be from 0 to 9.
  *****fields.txt*0[direction]
> "dam" is the number of points of damage.
> "rad" is the radius of the effect of the damage (must be <= 16).

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

#####R=== fire_druid_bolt ===

#####GDeclaration
    extern bool fire_druid_bolt(int typ, int dir, int dam);

#####GFile
    spells2.c

#####GComment
/*
 * Cast a druidic bolt spell
 * Stop if we hit a monster, as a "bolt"
 * Affect monsters (not grids or objects)
 */

#####GDescription
Cast a bolt spell of type "typ" in direction "dir" for "dam" points of
damage. The spell follows a mana path.

#####GParameters
> "typ" is the type of damage
  *****fields.txt*0[GF_fields]
> "dir" must be from 0 to 9.
  *****fields.txt*0[direction]
> "dam" is the number of points of damage.

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

#####R=== fire_druid_beam ===

#####GDeclaration
    extern bool fire_druid_beam(int typ, int dir, int dam);

#####GFile
    spells2