CONCEPT
	attributes

UPDATE
	Mateese, 08-Jun-95 - 00:15 MET

DESCRIPTION
	Attributes are a special kind of properties.
	Normal properties aren't saved if an save_object() is issued,
	attributes are. Furthermore, it is possible to query and set
	all attributes at once, even the builtin ones (normal
	properties can't do this).
	Attributes are normally used for livings to store sensitive
	data (like stats), but can be used otherwise as well.

	On code level, attributes are a extension of the properties.
	All official attributes are listed in /sys/attributes.h, with
	symbolic names starting with 'A_' instead of the properties'
	'P_'.
	As properties, attributes can be "built in" as well as simply
	stored. The naming for the functions of "built in" attributes
	is the same as for "built in" properties, so an overlap
	between the both worlds exists.

	"Soft" attributes have a special role as their are used to
	store skill values as well. Therefore an own set of functions
	to handle just them exists as well.

	These additional functions used for attributes are:

	  mixed SetAttr (string attribute_name, mixed arg, void|int sc)
	    Sets or changes the attribute <attribute_name> to
	    <value>. Returns the actually set attribute value
	    If it is a standard attribute as defined in
	    <attributess.h>, you should use the A_<NAME> notation
	    instead of the attribute name string.
	    If <sc> is true, the function doesn't look for a
	    Set<Name>(), but instead treats it as true soft attribute.


	  mixed QueryAttr (string attribute_name, void|int sc)
	    Returns the value of attribute <attribute_name>.
	    If <sc> is true, the function doesn't look for a
	    Query<Name>(), but instead treats it as true soft
	    attribute.
	
	  void  RemoveAttr (string name)
	    The entry for the 'soft' attribute <name> is deleted.

	  int ChangeAttr(string aname, int delta)
	  int ChangeAttr(string aname, int delta, int min, int max)
	    The value of attribute <aname> is changed by amount
	    <delta>. If <min> and <max> are given and valid, the new
	    value of the attribute is confirmed to this range.
	    Result is the new attribute value.


	  mapping QueryAttrs (void|int sc)
	    Returns a mapping containing all attributes of the object,
	    "built in" as well as soft ones.
	    If <sc> is non-zero, only the soft attributes are returned
	    (and the function is less costly).
	    This function is very costly.

	  mapping SetAttrs (mapping attributes, void|int sc)
	    The function sets the attributes of the object to the
	    values in the given <attributes> mapping. Builtin and soft
	    attributes are properly handled, resp. if <sc> is
	    non-zero, only the soft attributes are set.
	    Result is a mapping with the values actually set.


	A problem is the safe crash-proof temporary change of
	attributes. For this, the property

	  mapping P_BONI  "Boni"

	records any change in an attribute, yielding the difference
	between the current and the true value (historically called
	"bonus"). During the login of a player, the saved content of
	P_BONI (if any) is used to correct the saved attributes to
	their true value. The property should not be set manually!

	To safely modify an attribute, use

	  int ModifyAttr(string aname, int delta)
	  int ModifyAttr(string aname, int delta, int min, int max)
	    The value of attribute <aname> is changed by amount
	    <delta>. If <min> and <max> are given and valid, the new
	    value of the attribute is confirmed to this range.
	    Result is the new attribute value.

	This function takes care of changing the attribute and its
	bonus.

	Of the functions for direct P_BONI handling, only AddBonus()
	is of (rare) use:

	  int AddBonus(string aname, int delta)
	    The bonus for <aname> is changed by <delta>, the new value
	    is returned.

	  int SetBonus (string aname, int val)
	    Sets the bonus for attribute <aname> to <val>.

	  int QueryBonus (string aname)
	    Returns the current bonus for attribute <aname>.


	Some auxiliary functions make the handling of soft attributes
	easier:

	  mixed SetAttribute(string name, mixed arg)
	    == SetAttr(name, arg, 1).

	  mixed QueryAttribute(string name)
	    == SetAttr(name, 1).

	  void  RemoveAttribute(string name)
	    == RemoveAttr(name).

	  int ChangeAttribute(...)
	  int ModifyAttribute(...)

	  mapping SetAttributes(mapping arg)
	    == SetAttrs(arg, 1).

	  mapping QueryAttributes()
	    == QueryAttrs(1).


	To change attributes in a way modeling natural learning, this
	function can be used:

	  int LearnAttr (string name, int max_value, int decr, void|int sc)
	    The value of attribute <name> (if <sc> is nonzero: the
	    value of the soft attribute) is changed in a way that it
	    approaches <max_value>. The change is derived from <decr>
	    which denotes the decrease in approach.
	    Result is the new attribute value, which is set by the
	    function as well.

	  int ApproxValue (int steps, int value, int max_value, int decr)
	    This auxiliary function estimates the effective value for
	    <value> after <steps> iteration steps using the formula of
	    LearnAttr(). <max_value> and <decr> go into the formula.
	    Result is the estimated value.

IMPORTANT
	Refer to properties(C).

SEE ALSO
	properties(C), living(S)