Lo, wizard, and welcome to version 1.2 of the documentation of the skill 
system. This file is probably outdated, but it wouldn't do much harm to read it
anyway, because it's probably the only one on the skillsystem.

CONTENTS

This file describes the skill system as proposed and written by Ethereal
Cashimor. At the moment only a start is functioning, but it's functioning well
and beyond expectations. One could always use the scroll of documentation
(/players/cashimor/objects/document.c) if one want to have more up to date
documentation that this document.

LIST OF SKILLS

A list of skills supported by this system is available in
/players/cashimor/include/skills.h, at the end. Currently only one skill,
SS_MUSICAL_INSTRUMENT, and a list copied from the advanced dungeons and
dragons player book (second edition) is present, but others are sure to 
follow, if I have time and a list of desired skills. You can always ask an 
arch to add a skill if you really want one.
******************************************************************************
To the arch adding skills: Skills should be added at the end of the array, and
should have a corresponding define (with the correct number) in the include
file. As long as you update both at the same time, there's no need for
worries. However, don't forget to put a comment at the top of each file that
it was modified, including date, your name and the modification.
******************************************************************************

WHEN TO USE THE SKILL SYSTEM

Whenever the player does do something, and there is a chance that this will
go wrong, then the skill system should be used. This skill system will
calculate the chance that the player is able to perform the selected thing,
depending this on the skill, an (optional) penalty and the statistics of the
player.

HOW TO USE THE SYSTEM

Three parameters are necessary for a call to the skill system:

* The object that performs the action (i.e. the player)
* The desired skill (the definition from the skill.h file)
* The adjustment necessary under the circumstances.

The result is an integer, which has certain meanings:

* SS_BLUNDER: Well, it was a blunder. Probably the opposite of the indented
              action occurs. This can be quite funny to implement.
* SS_ABSOLUTE_FAILURE: Something went terribly wrong while performing the
                       skill.
* SS_FAILURE: It didn't work out.
* SS_PARTIAL_SUCCESS: Part of the action succeeded.
* SS_NEAR_SUCCESS: Almost all of the action succeeded.
* SS_SUCCESS: The action succeeded.
* SS_ABSOLUTE_SUCCESS: The action succeeded, and even more was accomplished.

Of course, when jumping over a chasm, only success counts, there is no such
thing as a near succes in that case. So if one checks on larger than
SS_NEAR_SUCCESS, one would split the above table in a binary check.

The check_skill() function resides currently in 
/players/cashimor/objects/skills.c, and can be called using:

"players/cashimor/objects/skills"->check_skill(<object>,<skill>,<penalty>);

EXAMPLES

To check whether a player is able to blow a simple whistle, one could do the
following:

if(SS_PLACE->check_skill(this_player(),SS_MUSICAL_INSTRUMENT,SS_ROUTINE)>
   SS_NEAR_SUCCESS) {
  say(this_player()->query_name()+" blows a whistle.\n");
}
else {
  say(this_player()->query_name()+" tries to blow a whistle, but no sound\n"
    + "can be heard.\n");
}

To check whether she's able to play the third part of Beethoven's Moonlight
Sonata (Op. 27/2):

SS_PLACE->check_skill(this_player(),SS_MUSICAL_INSTRUMENT,SS_ABSURD)

Etc...

Good luck using the skillsystem!

