########################################################################################
#          Important Note:
########################################################################################

  PLEASE READ THE INSTRUCTIONS.TXT FILE BEFORE CONTINUING HERE!
  
########################################################################################
#          function explanation:   skillcheck(victim, input)
########################################################################################
This documentation is to explain the function of how skillchecks work on etheria, what 
input options there are, and what you can expect as an output. Also the skillcheck 
function offers several additional features, that can help to make your life easier.

########################################################################################
# constants:
########################################################################################

  SC_YES        ... commonly defines that the default value (depends on the input 
                    parameter - details see below) should be used for a selected
                    parameter. Note that this differs from not specifying any input,
                    as most all values available here are optional!
                    
  SC_PRIMARY:   ... used for stat checks - This is a primary stat. It is required and has 
                    a major influence on the skillcheck.
  
  SC_SECONDARY: ... used for stat checks - This is a secondary stat. It has only limited
                    influence on the skillcheck result.
                    
  SC_PASSIVE:   ... This stat is used for the skillcheck (the player will gain some skillpoints),
                    yet it will hardly have any affect on the skillcheck result.

########################################################################################
#  Input parameters
########################################################################################
Skillchecks always expects two input parameters:

   - victim     ... which refers to the player/npc who should be tested
   - input      ... this is always a struct, which can have one or many of the following
                    input options:
         
	.type           ... <"award", "dummy"/"clumsy", "fast"/"fastcheck"/"quick","quality"/"default"/"detailed","all"> 
                                        choose which type of skillcheck to do. All parameters specified 
                                        will be evaluated. Default:="all"
     
    #chapter 1: pre-check parameters 
        
        .verified       ... <SC_YES>    This is an option for experienced coders. Using it, will 
                                        disablethe usual verification of input parameters which 
                                        will result in a slight performance increase. Best use
                                        this option after having verified your script is fine.

    #chapter 2: animation, wear & tear, stamina usuage
                                        # Note: These checks are optional, and are merely to relief the 
                                        #       skill script.
     
	.animation	... <integer_animationid or SC_YES> defines if an animation should 
					be made - and which animation id should show
           
	.animationamt	... <integer:=1> defines how often the animation should be run
					(each animation checks both stamina and wear&tear)
         
        .animationdelay ... <integer_ms> defines the time an animation takes in milliseconds.

        .sounddelay      ... <integer_ms> defines an optional time delay between an animation
                                        starting and a sound to be played. 
                                        
        .playsound      ... <integer_soundid or SC_YES> defines a sound to be played on the animation
           
        .moveandcraft   ... <SC_YES> if specified, this will allow the player to move while crafting.
                                        the skillcheck will freeze while moving and continue once the 
                                        player stops. (only applies if there is an animation going on!)
                                        WARNING: If you use this flag, the player CANNOT ABORT the animation
                                                 by simply running away like usual!
                                         
        .tool           ... <objectref> this refers to an object used in working your skill. 
                                        wear&tear will play against this object. 
                                        # Note: This object needs to be equipped, or the task will fail!
                                        
        .targetobject   ... <objectref> This refers to a target object the player is working on (e.g. anvil)
                                        Each animation cycle the player will try face the object if present!

        .wearandtear	... <integer_chance% or SC_YES or {integer_chance%, integer_damage_per_run}>
					defines the chance on each action run to damage the item with 
					wear and tear. More runs means more damage. Default: 30% chance 
					per strike. 
					Integer_damage_per_run is an integer > 0 telling how many damage
					an item can take each run. Default: 1 damage point per run. Note
					that specifying this value will GREATLY increase chances for an
					item to be damaged!
					-> e.g. mining uses 8 anims/skillcheck, 1 damage per run, 
						-> average would be 2.4 damage per skillcheck. A pickaxe 
						   with 100 HPmax could be used ~ 42 times before it breaks! 
					Note: No wear&tear applies to GM's in staffmode!
                                        
                                        # Additional Note: Commonly scripts ensure, that skill levels >70 are
                                        #                  awarded by using less animation cycles (=being faster),
                                        #                  thus also wear and tear would decrease in that case.
                                        #              -> This speedgain has to be done by the individual skill                                        
                                        #                  script though, it is NOT done by the skillsystem.
         
	.staminause	... <real:=1 or SC_YES> this means, that 1 stamina point is consumed 
					each animation round. If no stamina is left, the 
					skillcheck is aborted! 
					# Note: There is no strength influencer on stamina -
					#       if you want that, calculate it in your script
					#       and pass a proper staminause value. 
					# Note2: stamina use sums up, if summ >1 check is done 
                                        # Note3: we asume 1 stamina use every 5 seconds on standard work.
                                        #        -> 720 stamina use per hour on standard work
                                        #        -> comparing work to sleep, we get 5x as hungry and 10x as thirsty
                                        #        -> we'd be using 45 hunger and 150 thirst points per hour
                                        #        ===> as a result, each stamina used, adds 0.06 hunger 0.21 thirst
     
    #chapter 3: clumsiness check        # Note: all clumsiness checks will only be done by special request!
                                        #       a task might be easy enough (like pouring over liquids!)
                                        #       yet on extreme clumsiness, you might yet drop the glass!
                                        #       -> so you see, a clumsiness check may not be skill related!
                                     
        .intclumsy      ... <integer 1-50 or SC_YES> difficulty to pass to avoid a clumsiness 
                                        failure on an intelligence base (default=intdiff/2)
                                        # Note: Clumsiness must be requested or it defaults to 0
        .dexclumsy      ... <integer 1-50 or SC_YES> difficulty to pass to avoid a clumsiness 
                                        failure on an dexterity base (default=dexdiff/2)
                                        # Note: Clumsiness must be requested or it defaults to 0
        .strclumsy      ... <integer 1-50 or SC_YES> difficulty to pass to avoid a clumsiness 
                                        failure on an strength base default=strdiff/2)                   
                                        # Note: Clumsiness must be requested or it defaults to 0    

    #chapter 4 & 5: fast skillcheck     # Note: fastchecks are a way to handle minor challenges and the result
                                        #       will only be evaluated on special request. This should mainly
                                        #       be used for easy or small challenges, were no quality analysis
                                        #       is required.
                                        # Note2: Fast checks merely require either:  
                                        #          *) skillname & difficulty or skilldiff
                                        #          *) skill- and subskillname & difficulty or skilldiff 
                                        #          *) any stat-difficulty
                                        #          *) Any combination of above.
                                        #         -> if both skill and stats are checked here, stats will merely
                                        #            act as a bonus to the players skill-values!
                                        
                    quality skillcheck  # Note: this is the full, quality based skillcheck. It should be used
                                        #       whenever difficult actions are being performed by the player.
                                        #       As a generic rule, such actions should never result in simple
                                        #       "success/failure" responses (that's what fastchecks are for),
                                        #       instead quality skillcheck results are usually used to result
                                        #       in a slight improvent/or deteriation in the quality of an 
                                        #       item. E.g. an alchemist adding a reagent to his potion might 
                                        #       do well and increase the potions quality, or he could maybe 
                                        #       stirr it too little, reducing the overal quality because the 
                                        #       reagents will fail to mix properly. However either way, the
                                        #       alchemist will have many more reagents to add, and many more
                                        #       steps to undertake before he can claim the finished potion,
                                        #       and the overal result will depend on each of these.
                                        #   -> while it may sound silly to do such detailed checks only if 
                                        #       the overal outcome needs even more of these, keep in mind 
                                        #       that this will allow e.g. an apprentice to prepare the base 
                                        #       item (e.g. a potion catalyst) that is later continued by the 
                                        #       master - e.g. even if the apprentice does the first steps at 
                                        #       low quality only, his master can later finish his work on that
                                        #       very item by finishing it with perfect care and yet achieving
                                        #       the highest quality possible.
                                        #       The master can thus delegate simple or time intensive tasks
                                        #       to his apprentices, without having to fear wasting precious 
                                        #       material.
    
        .skillname      ... <string> of the skillname that is to be checked 
        .subskillname   ... <string> of the subskillname that is to be checked
       
        .difficulty     ... <integer 1-125> skillbased difficulty of the task 
                                        (will internally be multiplied *10 as in 1250=>125.0)
        .challenge      ... <SC_EASY, SC_STANDARD, SC_HARD> optional parameter, specifying how good the chances
                                               to pass should be. Default is "SC_STANDARD". Higher difficulty
                                               will decrease the chance for all Skilllevels gradualy. (Thus 
                                               high difficulty checks may result in failure of even the most 
                                               advanced crafter - use only upon special requirement)
                                               Note: this is used on fast-checks only but not for quality checks!
                                               
        .skilldiff      ... <integer 1-125 or SC_YES> difficulty as in skill requirement only
        .statdiff       ... <integer 1-125 or SC_YES> difficulty as in stat requirement only
                                        # Note: unless you want a stat-only or skill-only skillcheck, it is 
                                        #       recommended that you use the default .difficulty setting, as
                                        #       opposed to using .skilldiff and .statdiff

        .int            ... <integer 1-100 or SC_PRIMARY/SC_SECONDARY/SC_PASSIVE> determines how important 
                                        #       intelligence is for the skillcheck
        .dex            ... <integer 1-100 or SC_PRIMARY/SC_SECONDARY/SC_PASSIVE> determines how important 
                                        #       dexterity is for the skillcheck
        .str            ... <integer 1-100 or SC_PRIMARY/SC_SECONDARY/SC_PASSIVE> determines how important 
                                        #       strength is for the skillcheck
                                        # Note: it is not recommended to specify a custom value here, rather
                                        #       if possible, use the three base stat-influencer options:
                                        #   SC_PRIMARY: This is a primary stat. It is required and has a 
                                        #               major influence on the skillcheck.
                                        #   SC_SECONDARY: This is a secondary stat. It has only limited
                                        #                 influence on the skillcheck result.
                                        #   SC_PASSIVE: This stat is used for the skillcheck (the player 
                                        #               will gain some skillpoints), yet it will hardly have
                                        #               any affect on the skillcheck result.
                                     
        .statinf        ... <integer 0-100> compares how strong difficulty tests are affected
                                        by either stats or skills. 
                                        # Note: This value is not absolute though, but rather the maximum
                                        #       influencer at a difficulty rating of 100 skillpoints. 
                                        #       (Default 30% influence) This stat-influence will 
                                        #       AUTOMATICALLY scale down depending on stat-difficulties
                                        #       checked! 
                                        #   -> the lower the difficulty of stats you check, the
                                        #       higher the importance of skill will become!
                                        #       This is to help newbies, who are yet lacking
                                        #       proper stat-values. High Quality items require
                                        #       equally high stats though


    #chapter 6: skillpoint and statpoint award (=skillgain)
                                        
        .award          .... <integer or SC_YES> awards a certain amount of skill and statpoints to the player
                                        # Note: These points will be award by default, even if this parameter
                                        #       is not specified. If you want to avoid skillgain, pass a value
                                        #       of 0 points to either .award or to skillaward/stataward 
                                        #       respectively. SC_YES will have the same result as not specifying
                                        #       that option at all!
                                                
                                        # Note: these points will be distributed depending on skillcheck result.
                                        #       Staff in staffmode will not gain any skillpoints though.

        .skillaward     ... <integer> awards how many skillpoints the player can gain by using 
                                        this skill. Default is the same value as specified in .award
                                        SC_YES will also set a default value based on skikk and statpoints
        .stataward      ... <integer> awards how many statpoints the player can gain by using
                                        this skill. Stataward is influenced by the statinfluence values
                                        Default is the same value as specified in .award
                                        SC_YES will also set a default value based on skill and statpoints
                                        (commonly you donot set this value manualy)                                        
        .intbonus       ... <integer> defines how large the intelligence learning bonus should be, related to
                                        the automatically calculated default value. (this option is commonly 
                                        not recommended to be used - as a global modifier can be set in 
                                        .skillcontrol)
                                        # Note: Default is that each point >75 is 1% learning bonus.
                                        #       Default is that each point <75 is a 1 % learning malus
                                        #       -> learning ranges from 25% at 0 to 125% at 100.

        .intaward       ... <integer> defines how many intelligence points to award. 
        .dexaward       ... <integer> defines how many dexterity points to award. 
        .straward       ... <integer> defines how many strength points to award. 
                                        # Note: These are mainly if you donot do a skillcheck, but rather award 
                                        #       points directly only.. 


########################################################################################
#  Input parameters planned (not used yet!)
########################################################################################


                                      
        .handscheck     .item   ... <itemref> an item required to hold for the skillcheck 
                        .1hand  ... <integer> % value of how strong equipped item restrictions 
                                        should apply if the player has only one free hand.
                        .2hand  ... <integer> % value of how strong equipped item restrictions
                                        should apply if the player has no free hands left.
                        .armor  ... <integer> % value of how strong equipped item restrictions 
                                        should apply if the player has armor equipped.
                        .horse  ... <integer> % value of how strong mount usuage restrictions
                                        should apply if the player is mounted.
        
     
        
########################################################################################
#  Output parameters
########################################################################################

There's two options of results:

  a) you specified as input.type == "dummy" or "fastcheck" or "award", and only one of these.
     In that case output is integer 0/1 as correspondingly mentioned in below struct.
     This behavior is to help simplify usuage of that function.

  b) in all other cases, the output is either error, or a struct as follows:

  - output <error>       if output is error, this means that the skillcheck failed completely. This may occour, 
  =================      if the player failed to complete the requirements (e.g. if he was moving around while 
                         attempting the skillcheck, or if he was lacking required tools). Alternatively, an error
                         message here could also suggest a programming error. For further details in this case,
                         please check the error message text.
  
  - output <struct> 
  =================
        .skillaward      ... <error, integer> amount of skillpoints awarded to the player
        .stataward       ... <error, array{str-gain,dex-gain,int-gain}> amount of statpoints awarded to the player
        .clumsy          ... <error, 0/1/2/3> reveals if the player was so incredibly clumsy,
                                         he might e.g. have broken the vial he was working with.
                                         Note: Available only for stats <50
                                    error: no check was requested!
                                    0: passed check
                                    1: failed intelligence-check
                                    2: failed dexterity-check
                                    3: failed strength-check   
        .fastcheck      ... <error, 0/1> Does a "traditional" skillcheck, where stats have some
                                         influence. This is used mainly for very small task steps
                                         in a crafting process, where a quality result cannot apply.
                                    error: no check was requested!
                                    1: passed check
                                    0: failed check
                                    Note: the result may somewhat differ from the detailed result.
        .quality        ... <error, 0-8> The result of the real skillcheck. The qualities are 
                                         to be considered as follows:
                                    error: no check was requested!
                                    0: Impossible. Player has no chance and cannot even attempt it.
                                       (applies if 'difficulty > playerskill +30')
                                    1: critical failure. The player did seriously damage the crafted item
                                    2: Standard failure. The player did some decent damage the crafted item 
                                    3: Crap Quality success. Success, but some damage to the item still occoured
                                    4: Reasonable Quality success. Success, but slight damage to the item occoured
                                    5: Good Quality success. Success, no damage to the crafted item occoured
                                    6: GM Quality success. Perfect work, item quality might even improve slightly.
                                       Note: this is the best result players can usually achieve. 
                                    7: Godlike Quality: Perfect work, the item quality is being improved.
                                       Note: this requires extreme stats and skill - usually not player achieveable
                                    8: GAMEMASTER Quality: The result is cheated, the crafter is GM in staffmode.
                                
                                Note: The quality of the final item, is the combination of a multitude of skillchecks.
                                      -> usually only a critical failure will destroy an item... everything else will
                                      merely decrease or increase the overal quality. Even people without skill will 
                                      succeed on crafting simple items - though at a lower quality.
                                  -> E.g. Everyone can prepare a fruit salad - all you do is take some fresh fruits, cut
                                      them to pieces and put them in a bowl. Even if you pick a bad choice of fruits, even 
                                      if you fail to cut them regulary, even if you forget to add sugar to sweeten it... 
                                      the result will still taste reasonable.
                                      On the other hand, if the same person tried to make a stew, there's just too much 
                                      that would go wrong, noone would want to eat the result. The person could still help
                                      an experienced cook though, doing the more simple steps along the crafting process.
                                                                            
########################################################################################
#  Player Requirements for quality results:
########################################################################################

This Section only applies to the .quality output of the skillcheck formula. If you consider using
this option, please be aware that certain skill- and stat- levels are required for players, in 
order to achieve the high quality results:
  
    Result:
            - 0 -   no chance whatsoever. Abort attempt, for if you tried it would be ruined.
                    (Imagine "a blind man trying to steal a fighter jet....")
                    ("You don't even know how to attempt it, do you?")
                  
                      WILL NEVER APPLY IF: *) skilldelta > -30.0
              
              
            - 1 -   critical failure. Having an idea how it could work... but it didn't.
                    (Imagine "a 6 year old trying to disarm a nuclear bomb...")
                    ("Goodness, you ruined it completely! What did you think trying to do that?")
                
                      WILL NEVER APPLY IF: *) skilldelta > -10.0
                                        or *) playerskill >= 50.0
              
              
            - 2 -   failure. Actually you may have succeeded... but it's damaged now.
                    (Imagine "drilling a hole into the wall, whole parts of it breaking away")
                    ("ok, in a sense that worked.. but I seriously doubt it's what you wanted")
               
                      WILL NEVER APPLY IF: *) skilldelta > 0.0
                                        or *) playerskill >= 70.0
              
                
            - 3 -   crap success. It's maybe not pretty, but it will do the job.
                    (Imagine either "don't know how to do it better" or "too clumsy to do any better")
                    ("the bookshelf isn't smooth and got scratches... but it will hold your books.")
               
                      WILL NEVER APPLY IF: *) skilldelta > 15.0
                                        or *) playerskill >= 100.0
              
            - 4 -   normal success. Solid work that will do just fine.
                    ("as long as you don't look too closely, it will seem perfectly fine")
               
                      REQUIRES TO APPLY:   *) skilldelta > -20.0
                                       and *) playerskill > 30.0
                                       and *) primary stats > 30
               
                      WILL NEVER APPLY IF: *) skilldelta > 30.0
                                        or *) playerskill > 120.0 (can usually only be reached by monsters!)
                
                
            - 5 -   good success. Actually perfect work. Not a flaw whatsoever.
                    ("Masterful. I couldn't possibly have done it any better")
                    ("You sure know what you're doing, and you did it well")
              
                      REQUIRES TO APPLY:   *) skilldelta > -10.0
                                       and *) playerskill > 50.0
                                       and *) primary stats > 50
              
                
            - 6 -  masterfull success. Perfect work, fixing even prior errors along the way.
                   (Imagine "a master finishing the work of his aprrentice, improving the result")
                   ("Not only did you smith the dagger but you even corrected the flaws it's metal had")
               
                      REQUIRES TO APPLY:   *) skilldelta > -5.0
                                       and *) playerskill > 70.0 
                                       and *) primary stats > 75
               
               
            - 7 -  godlike success. Incredible work, greatly improving quality
                   (Imagine "a smith turning a rusty dagger into a shining katana with only a few blows")
                   ("Wow, I didn't even imagine this being possible!")
              
                      REQUIRES TO APPLY:   *) skilldelta > 0.0
                                       and *) playerskill >= 100.0
                                       and *) primary stats > 100
              
                
            - 8 -  gamemaster success. A gamemaster at work, superb success ensured, greatly improving quality.
                   ("cheaters never win... but they ocationally impress players")
                   ("Maybe I cheated - But trust me, you don't want to fail a skill-check when running quests...")
              
                     REQUIRES TO APPLY:  *) having 'Seer' Command-Level or higher
                                     and *) STAFFMODE being active (use .staffmode to toggle)
              
              
  
########################################################################################
#  Generic Hints on skillcheck() usuage
########################################################################################

  - Even when having very simple tasks, stat difficulty should mostly stick to the 
    default 75, as the lower quality levels can be succeeded even withot any useful
    stats. 

  - Skill-Levels can go up to 150.0, however skillgain is only possible up to 100.
    Greaters levels are mostly reserved for special rewards, special monsters and 
    other super-human beings.
  
########################################################################################
#  Examples for use of commands:
########################################################################################
  
  - for code samples, please see the 'instructions.txt' file in this folder.