OBJECT
        /std/player


LAST UPDATE
        Mateese, 15-Jun-94 00:15 MET


SYNOPSIS
        #include <attributes.h>
        #include <player.h>
        #include <combat.h>
        #include <search.h>

	playerobject->...
        inherit "/std/living";


DESCRIPTION

        The several modules are:
          /std/player              : The wrapper.
	  /std/player/restrictions : Content handling
          /std/living/skills       : Stats and Skills.


DESCRIPTION - /std/living/restrictions
	This module puts some tweaks into the restrictions handling to
	provide the player with some useful messages.

	light_from_inside(), light_from_outside(), emit_light() and
	emit_int_light() are intercepted so that large changes in the
	light levels are announced to the player. Also, if the light
	changes in a way to make the player blind, this is announced
	as well.

        These functions are assumed as being available in other
        modules:
	  /std/living/description: QueryIVision(), QueryUVision(), CantSee()


DESCRIPTION - /std/player/skills
	This module implements the (rather complex) handling of skills
	and stats of players. It builds upon the static management of
	/std/living/stats.

          int UseStat (string name, void|int diff)
            Try to use the stat <name> against the difficulty <diff>.
            Result is the success (0..100).

          int UseSkill (string name, void|int diff)
            Try to use the skill <name> against the difficulty <diff>.
            Result is the success (0..100).

	  int EffectiveSkill (string name)
	    Return the effective value of the skill <name>.

	In contrast to /std/living, these calls remember the number of
	usages and use them for automatic recomputation of the values.

	To aid in this, three additional attributes are implemented:

	  string * A_SKILLSERVER  "SkillServer"
	    An array of filenames denoting the servers where the
	    players skills are found.
	    The standard server SKILLMASTER needn't be stated
	    explicitely.

	  mapping A_STAT_DATA  "StatData"
	    This mapping contains for each stat two integer entries:
	      STDATA_USAGE: the number of 'uses' of this stat
	      STDATA_BONUS: the % bonus to add during recomputation
	                    of the real stat value.

	  mapping A_SKILL_DATA  "SkillData"
	    This mapping contains for each skill the number of 'uses'
	    of it.


	Some functions help with managing these attributes:

	  void AddSkillserver (string svc)
	    The server 'svc' is added at the end of the A_SKILLSERVER
	    list.

	  void RemoveSkillserver (string svc)
	    The server 'svc' is removed from the A_SKILLSERVER list.

	  int SetStatUsage (string name, int nr)
	    The STDATA_USAGE entry of stat 'name' is set to 'nr'.
	    You should not call this.

	  int QueryStatUsage (string name)
	    The STDATA_USAGE entry of stat 'name' is returned.

	  int SetStatBonus (string name, int b)
	    The STDATA_BONUS entry of stat 'name' is set to 'b'.

	  int QueryStatBonus (string name)
	    The STDATA_BONUS entry of stat 'name' is returned.

	  int SetSkillUsage (string name, int nr)
	    The usage entry of skill 'name' is set to 'nr'.
	    You should not call this.

	  int QuerySkillUsage (string name)
	    The usage entry of skill 'name' is returned.


	The recomputation of the stat and skill values is done with
	these functions:

	  void RecomputeStats ()
	    Recompute all stat values according to the number of
	    usages.
	    It also marks all skill values as dirty by a call to
	    RecomputeSkills().


	  void RecomputeSkills ()
	    Mark all effective skill values as dirty, thus triggering
	    a recomputation on next query.


	To reduce the system load, the recomputation takes place only
	every few minutes, called by a function in the /std/player
	wrapper. However, every reset() the recomputation is done as
	well.

	Two other functions are of just internal interest, since they
	deal with the internal cache of skill data. Do not use these
	unless you know what you do!

          static void RecomputeOneSkill ( string name)
	    This function is called if the skill <name> needs to be
	    recomputed.
	    It recomputes the 'effective' value of the skill according
	    to 'usage' and sets 'usage' to 0.

	  static int LoadSkillData (string name)
	    The data for skill 'name' is loaded into the internal
	    cache. For this, all A_SKILLSERVERs (and finally
	    SKILLMASTER) are queried in line, and the first response
	    is used.
	    If no server knows the skill, 0 is returned, else non-zero.


	These standard functions are used as well:

	  void create ()
	    Initializes the internal data (like the skill data cache),
	    and for the blueprint starts the RecomputeAllSkills call_out.

	  void reset ()
	    Calls RecomputeStats() to ensure an update of the skill settings


        These functions are assumed as being available in other
        modules:
          /std/living/attributes: QueryAttr(), SetAttr()
	  /std/living/body      : QueryXP()


	TRIAL MODE
	  By now, the autoincrement of stats and skills is untested.
	  To gather more information, the results of the computations
	  are not stored as true attributes, but instead in the

	    mapping A_SKILL_TRIAL  "SkillTrial"
	      Stored for each <skill> are the autocomputed base value
	      (indexed as "<skill>") and the autocomputed effectiv
	      value (indexed as "<skill>-eff"). This includes the
	      stats.


INHERITANCE TREE
        std/player
	  |- std/player/restrictions
	  |    `- std/living/restrictions
          |         `- std/container/restrictions
          |              |- std/thing/restrictions
          |              `- std/room/restrictions
          |- std/player/stats
	  |    `- std/living/stats
          `- std/base

SEE ALSO
        skills(C), base(S), living(S)
