[an error occurred while processing this directive]
[<a href="index.shtml">Package Index</a></code> | <a href="index_std.shtml">Mudlib Index</a></code> | <a href="index_eff.shtml">Effect Index</a></code>]<br><h2>File /obj/handlers/taskmaster.c</h2>
This handler gives access to the functions needed for the taskmaster
system.

Rewritten by Shrike to include degrees of success.
<p><b>See also:</b><br>help::tasks
.c<br /><p>Written by Deutha<h2>Includes</h2>
This class includes the following files /include/tasks.h<h2>Method index</h2>
<ul>
<li><a href="#attempt_task">attempt_task</a>(int, int, int, mixed, int)<br/>
Do not use this function.
<li><a href="#attempt_task_e">attempt_task_e</a>(int, int, int, int, int)<br/>
Do not use this function.
<li><a href="#compare_skills">compare_skills</a>(object, string, object, string, int, int, int, int)<br/>
This function will compare the skills of two objects and return which one
won and if the winner got a TM.
<li><a href="#is_critical">is_critical</a>(int)<br/>
Figure out whether a given margin of success/failure will result
in a critical or not.
<li><a href="#perform_task">perform_task</a>(object, string, int, int, int)<br/>
This function will perform a task.
<li><a href="#set_control">set_control</a>(mixed *)<br/>
This function should only be used in the very rare situations
where the last skill checked with query_skill_bonus() wasn't the
one relevant for the task attempt.
<li><a href="#success_probability">success_probability</a>(int, int, int)<br/>
This calculates the probability of a skill check succeeding, in 1/1000.
</ul>
<h2>Public Functions</h2>
These are functions that everyone can access.<p>
<dl>
<dt class="autodocfuncname"><a name="attempt_task">
attempt_task</a><pre class="autodocfuncdef">
varargs mixed attempt_task(int difficulty,
                           int bonus,
                           int upper,
                           mixed extra,
                           int degree)
</pre><dd><br />
Do not use this function. Use perform_task instead.<br />
<br /><dl>
<dd><b>See also:</b>
<br /><a href="#perform_task">perform_task()
</a><br /><br /><br /></dl>

<dt class="autodocfuncname"><a name="attempt_task_e">
attempt_task_e</a><pre class="autodocfuncdef">
varargs mixed attempt_task_e(int difficulty,
                             int bonus,
                             int upper,
                             int half,
                             int degree)
</pre><dd><br />
Do not use this function. Use perform_task instead.<br />
<br /><dl>
<dd><b>See also:</b>
<br /><a href="#perform_task">perform_task()
</a><br /><br /><br /></dl>

<dt class="autodocfuncname"><a name="compare_skills">
compare_skills</a><pre class="autodocfuncdef">
varargs mixed compare_skills(object offob,
                             string offskill,
                             object defob,
                             string defskill,
                             int modifier,
                             int off_tm_type,
                             int def_tm_type,
                             int degree)
</pre><dd><br />
This function will compare the skills of two objects and return which one
won and if the winner got a TM.
With equal skills the chances are 50/50 as to who will win. As the balance
shifts so do the chances. Additionally a modifier can be applied to
account for conditions favouring one or the other. This should be
considered a percentage eg. -50 will add 50% to the defenders chances of
winning.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
offob - The attacking object<br />
offskill - The name of the skill the attacker is using<br />
deffob - The defending object<br />
deffskill - The name of the skill the defender is using<br />
modifier - The percentage modifier<br />
off_tm_type - This should be one of the standard definitions in
/include/tasks.h and is for the attacker<br />
def_tm_type - This should be one of the standard definitions in
/include/tasks.h and is for the defender<br />
degree - Enable the degree-of-success code.  If this is used, the
 return value becomes a class instead of an int.
<br />
<br />
<dd><b>See also:</b>
<br /><a href="#perform_task">perform_task()

</a><br /><br /><dd><b>Example:</b>
<br/><pre>This is an example of the simpler, binary success/failure behaviour.

switch(TASKER->compare_skills(attacker, "fighting.melee.sword",
                              defender, "fighting.defence.parry",
                              25, TM_COMMAND, TM_FREE) {
case OFFAWARD:
  tell_object(attacker, "%^YELLOW%^You manage to grasp one of the "
                        "principles of slicing people up more firmly."
                        "%^RESET%^\n");
case OFFWIN:
  say(defender->one_short() + " loses an arm!\n");
  break;
case DEFAWARD:
  tell_object(defender, "%^YELLOW%^You feel better able to keep your arms "
                        "attached when parrying unarmed.%^RESET%^\n");
case DEFWIN:
  say(defender->one_short() + " keeps " + defender->query_possesive() +
      " arm attached.\n");
  break;
}
</pre><br/><pre>
This is an example of the finer grained degree-of-success behaviour.

class tasker_result tr;

tr = (class tasker_result)TASKER->compare_skills(
  attacker, "fighting.melee.sword",
  defender, "fighting.defence.parry",
  25, TM_COMMAND, TM_FREE, 1 );

switch( tr->result ) {
case OFFAWARD:
  tell_object(attacker, "%^YELLOW%^You manage to grasp one of the "
                        "principles of slicing people up more firmly."
                        "%^RESET%^\n");
case OFFWIN:
  switch( tr->degree ) {
  case TASKER_MARGINAL:
    say( "You just barely scrape your opponent's hand.\n" );
    break;
  case TASKER_NORMAL:
    say( "You slice into your opponent's arm.\n" );
    break;
  case TASKER_EXCEPTIONAL:
    say( "You slice deeply into your opponent's muscle and sinew, and "
      "he screams in pain!\n" );
    break;
  case TASKER_CRITICAL:
    say( "You slice your opponent's arm clean off.  Blood spurts "
      "everywhere like a cherry slurpee machine gone insane!\n" );
    break;
  }
  break;
case DEFAWARD:
  tell_object(defender, "%^YELLOW%^You feel better able to keep your arms "
                        "attached when parrying unarmed.%^RESET%^\n");
case DEFWIN:
  switch( tr->degree ) {
     ...
     similar code in here...
     ...
  }
  break;
}
</pre><br /></dl>

<dt class="autodocfuncname"><a name="is_critical">
is_critical</a><pre class="autodocfuncdef">
int is_critical(int margin)
</pre><dd><br />
Figure out whether a given margin of success/failure will result
in a critical or not.  Takes an integer between -100 and 100,
representing the margin by which a skillcheck succeeded, and does
some logarithmic-type equations to figure out whether it should
result in a critical or not.<br />
<br /><dl>
<dd><b>Parameters:</b><br />
margin - the margin of success.<br />
<br />
<dd><b>Returns:</b>
<br />1 if the result is a critical, 0 otherwise.
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="perform_task">
perform_task</a><pre class="autodocfuncdef">
varargs mixed perform_task(object person,
                           string skill,
                           int difficulty,
                           int tm_type,
                           int degree)
</pre><dd><br />
This function will perform a task.  It handles all the stuff about
looking up the skill, and giving the tm advance, but doesn't give
any messages to the player, you'll have to do that.

Please note that while the taskmaster system tries to prevent players
gaining too many TMs these checks only work in conjunction with well
written TM checks. Giving out infinite TM checks will result in players
gaining too many TMs.

In other words, do not write TM checks into your code unless you really
know what you are doing.

As a general rule no task that can be repeated ad infinitum with no
limiting factor should give out TMs. The majority of TM attempts should
use GPs to conotate an active task that cannot be repeated constantly at
no cost.

If you set the 'degree' parameter to 1, it will return a 3-element
class instead of the standard binary success/failure result.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
person - the one attempting the task (could be any living thing)<br />
skill - the skill tested against<br />
difficulty - the lowest bonus where the attempt can succeed<br />
tm_type - This should use one of the standard definitions in
/include/tasks.h. They are:

       TM_FIXED - for use where the difficulty is a fixed value.
       Because the difficulty is fixed the range of skill bonuses
       that can be TMed is fixed so this is a very generous value
       and should be used with great care.

       TM_FREE - for use when the TM attempt doesn't cost anything.
       All the other TM types with the exception of TM_NONE and
       possibly TM_CONTINUOUS should use GPs. If your task does
       not use GPs it should generally use TM_NONE OR TM_FREE.
       Since the TM is free there needs to be some other factor
       that restricts the frequency of attempts, for example
       consumed materials. Using artificial time restrictions is
       not a good way to limit these attempts.

       TM_CONTINUOUS - for use in continuous actions eg. combat or
       sneak.  In general these use up GPs though they may have
       other limiting factors, such as combat requiring an opponent
       and causing damage.

       TM_COMMAND - for use with guild commands. This should only
       be used if you're writing a guild command that uses GPs. The
       precise TM chances are calculated based on the skill to
       maintain balance.

       TM_RITUAL & TM_SPELL - when the action is a spell. These two
       special cases are used by the ritual code and the spell code
       to allow those actions to have specifically calculated
       chances.

       TM_NONE - when you want there to be no chance of a
       TM. Sometimes it is desirable to test the outcome of an
       action using the TM system but where the action does not
       deserve a TM chance due to its passive or repeatable
       nature. In such a case TM_NONE is the correct modifier.
<br />
degree - Whether or not to use the degree of success code
<br />
<br />
<dd><b>Returns:</b>
<br />BARF if something screwed up, AWARD if the task succeeded, and
should give an advance, SUCCEED if it succeeded, FAIL if it failed. If
the degree of success code is used, it will pass out a 3-element class.
<br /><br />
<dd><b>See also:</b>
<br /><a href="#compare_skills">compare_skills()</a> and tasker_result

.c<br /><br /><dd><b>Example:</b>
<br/><pre>This is an example of the simpler, binary success/failure behaviour.

switch(TASKER->perform_task( person, "covert.manipulation.stealing",
                             300, TM_COMMAND ) ) {
 case AWARD :
   tell_object( person, "%^YELLOW%^You manage to grasp the principles "
               "of stealing more firmly.%^RESET%^\n" );
   // Note, no break;
 case SUCCEED :
   // Whatever happens when it succeeds
   break;
 default :
   // Whatever happens when it fails
}
</pre><br/><pre>
This is an example of the finer grained degree-of-success behaviour.

class tasker_result tr;

tr = (class tasker_result)TASKER->perform_task( person,
  "other.direction", 300, TM_FREE, 1 );
switch( tr->result ) {
case AWARD:
  tell_object(attacker, "%^YELLOW%^You feel very aligned!%^RESET%^\n" );
case SUCCEED:
   switch( tr->degree ) {
   case TASKER_MARGINAL:
      say( "You think he went thataway. Maybe.\n" );
      break;
   case TASKER_NORMAL:
      say( "You're pretty sure he went that way.\n" );
      break;
   case TASKER_EXCEPTIONAL:
      say( "He definitely went thataway!\n" );
      break;
   case TASKER_CRITICAL:
      say( "Your surity that he went thataway is so powerful that even "
        "if he didn't go thataway, he'll be in that direction.\n" );
      break;
  }
  break;
case FAIL:
  switch( tr->degree ) {
     ...
     Boy, it's a good thing I've already explained this, or I'd be
     pretty hard-pressed to think of an example of a critical failure
     for other.direction.  You get the idea.
     ...
  }
  break;
}
</pre><br /></dl>

<dt class="autodocfuncname"><a name="set_control">
set_control</a><pre class="autodocfuncdef">
void set_control(mixed * args)
</pre><dd><br />
This function should only be used in the very rare situations
where the last skill checked with query_skill_bonus() wasn't the
one relevant for the task attempt.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
args - an array consisting of ({ object player, string skill })
<br />
<br />
<br /></dl>

<dt class="autodocfuncname"><a name="success_probability">
success_probability</a><pre class="autodocfuncdef">
int success_probability(int difficulty,
                        int bonus,
                        int tm_type)
</pre><dd><br />
This calculates the probability of a skill check succeeding, in 1/1000.
If it returns 500, it's 50% fail or succeed, if it returns 1000 it's success
every time, etc.<br />
<br /><dl>
<dd><b>Parameters:</b><br />
difficulty - The difficulty of the skill check<br />
bonus - The bonus at which the skill check is attempted<br />
tm_type - What kind of skill check, TM_FIXED, TM_COMMAND etc<br />
<br />
<dd><b>Returns:</b>
<br />The probability of the check succeeding, -1 if anything failed
<br /><br />
<br /></dl>

</dl>
[an error occurred while processing this directive]

