HOW TO CREATE A NEW SPELL
-------------------------

General:
--------

First get an idea of the spell you want to code. Then consider the might of
the spell and possible drawbacks. Do think about the sp, the spell will cost.
And make sure, that there isn't already such a spell (or a similar one).
Befor you now start to code, talk to the GM of the mages, if (s)he does allow
such a spell. If you have his/her ok, you may start to code.
When you are done with coding, ask the GM of the mages again, to implement
your spell to game. (S)He will tell you, if you have done anything wrong and
may ask you to correct/modify your spell. It the spell is to his/her
statisfaction, the spell will be implemented in the lib.

REMEMBER: Once the spell is implemented in the lib, you will lose all rights
  at the spell. It is then considered part of the mudlib of HM. You are not
  allowed to change the spell anymore and lose all coding access for the spell.

Generic spell:
--------------

There is a file in the lib, called spell.c. This file contains all functions,
you will need to create the spells and to let ppls and npcs cast the spell.
Most methods of the spell are nomask or even private, so you are not allowed
to override them. If a method can be overridden, it is said at the method.

Methods of the generic spell:
-----------------------------

---------- INITIALISING THE SPELL -------------------------------------------

nomask void set_name( string n )
nomask string name( )
// sets and queries the name of the spell. The name of the spell is the
// argument, the player have to give, when casting the spell
// e.g. the name of the spell is "magic missile" -> cast 'magic missile'
// you MUST call this method !

nomask void set_syntax( string s )
nomask string syntax( )
// info about how to cast the spell, it should begin with cast 'spellname'
// e.g. "cast 'magic missile' [opponent]
// this is just a string displayed in the help of the spell
// you are ADVICED to call this method !

nomask void set_duration_info( string s )
nomask string duration_info( )
// info about the duration of the spell, e.g. "2 rounds", "permanent"
// this is just a string displayed in the help of the spell
// you MAY call this method

nomask void set_damage_info( string e )
nomask string damage_info( )
// info about the damage of the spells, only usefull if the spell makes damage
// e.g. "2D30+5", "lvlD100", "500"
// this is just a string displayed in the help of the spell
// you MUST call this method if the spells makes damage

nomask void set_save_vs_info( string e )
nomask string save_vs_info( )
// info about the saving, it is only a string displayed in the help
// e.g. "for half damage", "to negate"
// you MUST call this method if there is such an info

nomask void set_player_help( string h )
nomask string player_help( string h )
// additional help for the player and detailed information of the spell
// you MUST call this method

nomask void set_guild_allowed( int gn, int lvl )    // initialising
nomask varargs int may_cast( int gn, int lvl )      // query
nomask int level( int gn )                          // query
// which guild (gn) is allowed to cast this spell and at what level (lvl)
// you MUST call this method
// the queries are used in the practise-npc of your guild, see there

nomask void set_kind( int k )
nomask int kind( )
// the kind of the spell.
// This can be one of the following: AGGRESSIVE, NO_COMBAT, NON_AGGRESSIVE
// you MUST call this method

nomask void set_save_vs( int s )
nomask int save_vs( )
// saving versus which resistance/immunity
// the immunites are predefined, look under savings
// you MUST call this method

nomask void set_cost( int c )
nomask int cost( )
// how much mana (spell-points) do you need to cast this spell
// you MUST call this method

nomask void set_speed( int s )
varargs int speed( int lvl, object who )
// how long is the casting-time of the spell
// this must be one of the following: IMMEDIATE, NEXT_HB, int > 1
// you MUST call this method
// you are allowed to override the method speed(). In it you can handle
// different speeds for different levels (e.g. faster cast for legends)
// the arguments passed are the level of the caster (incl. legend-level)
// and the caster him/her/itself.
// return-value is one of the following: INSTANT, NEXT_HB, int > 1
// TAKE CARE: npcs can cast too, so consider their high level !


---------- RELEASING THE SPELL ---------------------------------------------

void release( string arg, int act_skill, int max_skill )
// this method is called, when the spell is triggered
// it is the heart of the spell-system and handles all effects of the spell
// you MUST override it
// arguments: arg       the argument the player give, when casting the spell
//            act_skill the actual skill of the player in this spell
//            max_skill the maximum skill the player can achieve in this spell

object check_target( string arg )
// this method will fetch the target for you. you do not have to worry about
// finding the target or converting it to an object.
// if no argument is given, it will chose your current oppenent as target for
// aggressive spells, otherwise the spellcaster.
// the parameter arg is the parameter arg of the release_spell()-method
// returns 0 if no target can be found, otherwise the target
// error-messages will be displayed within this method

int valid_living( object target )
// this method checks, if the living you want to cast the spell upon, is valid
// it is not valid, when it isn't a living (of course), when it is a ghost,
// when the caster cannot see it (too dark or invis for the caster) or
// when the caster is not allowed to attack (only at AGGRESSIVE spells)
// the caster him/her/itself is ALWAYS valid !
// the argument target is the return-value of the method check_target()
// returns 0 if the target is not valid, 1 if the target is valid
// error-messages will be displayed within this method
// you MUST call this method if the spell is not area-effective

int valid_item( object target )
// always returns 0 at the moment. It will be used to cast spells at scrolls,
// staffs or wand. But this is not yet implemented.
// you MUST call this method if the spell is not area-effective

int check_success( int act_skill, int max_skill )
// checks, if the spell can be successfully casted. This involves the skill
// of the player (with a possible skill-increase at failure), the kind of the
// spell (e.g. no combat), environment/opponent properties (no_fight, ...) and
// spell-points
// arguments: the actual and the max skill of the player (as obtained by
//            release_spell() )
// returns: 0 unsuccessfull cast, 1 successfully casted
// you MUST call this function


---------- METHODS CALLED ONLY BY THE LIB -----------------------------------

void display_utter( int )
// this method is called by the lib. You MUST NOT use it

int abort_spell(object pl)
// this method is called by the lib. You MUST NOT use it



03/02/95
