HOW TO CREATE A NEW SPECIAL ABILITY 
-----------------------------------

General:
--------

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

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

Generic ability:
----------------

There is a file in the lib, called ability.c. This file contains all functions,
you will need to create the ability and to let ppls and npcs use it.
Most methods of the ability 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 ability:
-------------------------------

---------- INITIALISING THE ABILITY ----------------------------------------

nomask void set_name( string n )
nomask string name( )
// sets and queries the name of the ability. The name of the ability is the one,
// the player has to give as command (input) to perform the ability
// e.g. name of the ability is "grapple", the player must type "grapple" to 
//      trigger it
// you MUST call this method !

nomask void set_syntax( string s )
nomask string syntax( )
// info about how to initate the ability
// e.g. "grapple [opponent]"
// this is just a string displayed in the help of the ability
// you are ADVICED to call this method !

nomask void set_player_help( string h )
nomask string player_help( string h )
// additional help for the player and detailed information about the ability
// 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 ability and at which 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 ability.
// This can be one of the following: AGGRESSIVE, NO_COMBAT, NON_AGGRESSIVE
// you MUST call this method

nomask void set_cost( int c )
nomask int cost( )
// how much fatigue-points do you need to use the ability
// 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 ability
// 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 use abilities too too, so consider their high level !

nomask void set_auto_inc()
// If you call this method, the skill will automatically raise at usage
// If you do not want the skill to raise at usage, do NOT call it
// default is: no auto increase
// you NEED to call this method if you want the ability to raise automatically

---------- RELEASING THE ABILITY ------------------------------------------

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

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 use the ability upon, is valid
// it is not valid, when it isn't a living (of course), when it is a ghost,
// when the player cannot see it (too dark or invis for the player) or
// when the player is not allowed to attack (only at AGGRESSIVE spells)
// the player 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 process abilities at items
// 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 ability is used successfully. 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
// fatigue-points
// arguments: the actual and the max skill of the player (as obtained by
//            release_spell() )
// returns: 0 unsuccessfull usage, 1 successfully used
// you MUST call this function

void display_prepare( object who )
// this method displays a prepare message. If you do not want to have such
// a message, override it and do nothing in it
// this method is called by the lib after the user entered the command (in the
// next HB)
// arguments: the one, using the skill
// you MUST override this method


03/09/95
