###################################################################################
#          Welcome Notice & Package Explanation
###################################################################################

Welcome to the Matrixshard Project Skillsystem Package. What you have here, is
an powerful system to handle skillchecks and everything related to it. This 
description here, is to teach you how to use this package, and to teach you the 
difference to the standard pol-native skillfunction.

###################################################################################
#       Differences to the standard pol skillcheck
###################################################################################

Before telling you the advantages of this package, you should be aware of the 
similarities:

- Both POL's functions and matrixshard skillcheck internally use "skillpoints"
  that sum up steadily, whenever a skillcheck is performed. How fast you gain
  skill (and stats) will depend on various factors, such as the difficulty
  of the tasks you perform. The higher you raise in skill, the harder skillgain
  gets, meaning the more points you need to gain "skill%" - a term that in this
  documentation will always refer to the value that the player can see (e.g.
  a skill of 100.0 being maxed out grandmaster skill.)
  
There's als major differences between this package and the pol-native skillcheck
though:

- The individual skills on matrixshard project are put in "skillgroups" whereas
  skills within a group give learning boni to each other. In this package we 
  thus speak of "skills" (meaning skillgroups) and "subskills" (individual skills)
  Please donot confuse these!

- skill% (which as mentioned before, is the skill value displayed to the player)
  will range from 0.0 to 150.0 - However as by default, skillgain is only possible
  up to a value of 100.0. Skills beyond are reserved for monsters or special 
  beings and can only be awarded by special command.
  
- pol skillchecks have various input paramters (e.g. difficulty, skillgain etc) 
  whereas with the matrixshard one, all parameters are packed into a single
  struct variable. The advantage of this is, that you are far more flexible
  in choosing which parameters you wish to use, as most parameters are optional.
  Nevertheless skillchecks can be as simple as in the old system, for 
  example
  
  var result:=skillcheck(who, struct{skillname:="metalworking", 
                         subskillname:="smithing", difficulty:=40, str:=SC_primary});
  
  Now above line would tell that you want to do a skillcheck on the player, testing
  his "smithing" subskill (being part of the "metalworking" skillgroup) whose
  difficulty is 40 and which uses strength as a primary stat. (So you would gain
  boni or mali based on your strength value and you'd gain strength points)
  
  You may already see, that opposed to the pol default command, we donot specify 
  how much skill to gain though... rather the system calculates a default value 
  for itself, which is also influenced by a global admin setting. Changing how
  much skill should be gained is possible though, if we just specify one more 
  parameter in the struct, namely the option 'award:=......', however the good thing
  is, that you only have to specify the parameters that you really need.
  
  The skillcheck system can do far, far more for you though... you can have fast
  skillchecks that only give a yes/no answer, or you can have detailed skillchecks
  for complex tasks, where you will also gain a quality judgement for your result.
  You can have multiple stats checked, or even checks that make skill-checks based
  on a players stats only! You can decide not to check skills but merely award points
  and you can have the system do fun things for you, such as animating the skill
  process, including handling of sounds and wear & tear for your tools.
  
  A full list of options can be found in the 'skillcheck_input-output.txt' file,
  which you hopefully find within the same folder.
  
- As to the next major difference, as already touched in subject just before,
  the pol default commands only return 0/1 as a skillcheck result, whereas
  matrixshard commands have a greater variety. There's 3 (or 4 if you so want)
  types of skillchecks you can do: 
  
   1) clumsiness
   
     this skillcheck is usually done in combination with other skillchecks.
     It might tell you if a player had such low stats, that he maybe has a 
     higher chance to drop his hammer on his toes than hitting the anvil...
     
   2) fastchecks
   
     these are small pol-standard type skillchecks, that only tell you if a 
     player would pass or not. Usually these apply to skillchecks with very
     simplistic tasks - e.g. throwing a ball into a basket, you're usually
     not interested in how smooth or accurate it was thrown, as long as it
     went in.
     
  3) quality skillchecks
  
     Those are detailed skillchecks for complex tasks, not only telling you
     wether or not the player succeeded, but also to what degree he did.
     Several influencers apply here and might decide whether e.g. a weapon 
     made ends as a dull piece of metal or a superb katana.
     Note that crafts on matrixshard usually take several such steps to 
     complete.
     
  4) award only
  
     Not really a 'check' as such, you might run skillchecks also to award
     skill or statpoints only. (e.g. for artifacts granting boni)

  As said, more on this you'll find in the 'skillcheck_input-output.txt' file 
  though.

- Finaly note, that on the matrixshard system, stats are far more important than 
  they are in the default pol module. Without the proper stats, higher quality
  skillcheck results become impossible. The average for stats is estimated at
  roughly a value of ~75. Higher stats give boni, lower stats enforce mali or 
  even restrictions. For further details on this issue, please check the 
  'skillcheck_input-output.txt' file.

###################################################################################
#       Code samples for skillchecks
###################################################################################

  1) e.g. a smith wants to make an item with difficulty 40 and he'll mainly requires strength.
          as a result you wish to know how well he performed...
  
        sample code:
        
          var victim:=who; //make yourself the target of the skillcheck
          var skilldata:=struct{ difficulty:=40, str:=SC_PRIMARY};
          var result:=skillcheck(victim, skilldata);
         
          Sendsysmessage(who,"The detailed result of the skillcheck is: "+result.quality);
         
        Notes:
      
          - the skillcheck will automatically have awarded skillpoints and statpoints too.
        
  --------------------------------------------------------------------------------------------------      
        
  2) Now let's asume this isn't enough for you... you might additionally want to check, if the 
     player wasn't too clumsy to drop the hammer on his feet.
     
        sample code:
        
          var victim:=who; //make yourself the target of the skillcheck
          var skilldata:=struct{ difficulty:=40, str:=SC_PRIMARY, dexclumsy:=SC_YES};
          var result:=skillcheck(victim, skilldata);
         
          if(result.clumsy)
            Sendsysmessage(who, "ouch, the hammer fell on your foot");
            return;
          else
            Sendsysmessage(who,"The detailed result of the skillcheck is: "+result.quality);
          endif
    
  --------------------------------------------------------------------------------------------------
  
  3) Asuming you're getting the hang of it.... you're no longer interested in clumsiness, but you now 
     want to ensure the hammer is equipped and you want the hammering to be animated...
     
             sample code:
         
          var victim:=who; //make yourself the target of the skillcheck
          var hammer:=inputitem; //asuming inputitem is the <object_reference> for the hammer the player dclicked
          
          var skilldata:=struct{ difficulty:=40, str:=SC_PRIMARY, tool:=hammer
                                 animation:=0x95, animationamt:=5, playsound:=67}; 
                                 //hammer 5 times, using animation 0x95, playing sound 67 on each stroke
          var result:=skillcheck(victim, skilldata);
          
          if(result==error) //something went wrong?
            Sendsysmessage(who,"maybe your tools are not equipped?");
            return;
          endif
          
          //still here? then the hammer was equipped... 
          Sendsysmessage(who,"The detailed result of the skillcheck is: "+result.quality);
        
     If you had additionally used stamina, it would have substracted the stamina with each stroke, 
     aborting the action if the player character should get too exhausted.
     
  --------------------------------------------------------------------------------------------------
 
  4) Now on the other hand, let's asume you wanted to do a clumsiness check only - without any real 
     skillcheck - thus try this code...
     
        sample code:
        
          var victim:=who; //make yourself the target of the skillcheck
          var skilldata:=struct{ type:="clumsy", dexclumsy:=SC_YES}; //clumsiness only (dex based)
          var result:=skillcheck(victim, skilldata);
         
          if(result.clumsy)
            Sendsysmessage(who,"oops.. you dropped it!");
            return;
          endif
     
        Notes:
          
          - the 'type' parameter could be left out, but adding it, will prevent normal skill-routines
            to run, which aren't used anyway... thus specifying this parameter will save cpu power.