Man belonging

From LSWiki

belonging - belonging descriptors

Contents 1 Files 2 Description 2.1 Fields 3 Working With Belonging Descriptors 4 See Also

Files

/std/autonomon.c
/def/descriptor/belonging.c
/lib/descriptors/belonging.h

Description

Belongings for the belonging system in /std/autonomon.c are specified using belonging descriptors, as defined by /def/descriptor/belonging.c and /lib/descriptors/belonging.h. In order to use the macros described below, you will need to #include <belonging.h>. It will be helpful to be familiar with the general behavior of descriptors, as 'man descriptors' describes.

Fields

The fields of a belonging descriptor that you can use, in order, are:

   Belonging_File
   Belonging_Count
   Belonging_Usage
   Belonging_Priority
   Belonging_Initialize
   Belonging_Equip
   Belonging_Unequip
   Belonging_Alternate

Any of the descriptor specification forms may be used, including implicit form; the belonging functions automatically interpret their arguments in terms of belonging descriptors.

The meaning of each of the fields is:

Belonging_File: Designates the object constituting the belonging. May be any of the following:

   A string: The usual choice.  The object designated will be cloned or
   loaded, as appropriate (this being determined by query_unique()), and
   moved to the character.

   An object: May be used to directly specify an object base class or a
   pre-cloned object to use as the belonging.  The Belonging_File field
   will be converted to the load_name() of the object when the character's
   belongings are processed.

   A closure: Will be called with arguments of 1) the character and 2) the
   belonging descriptor, and must return one of the above types, or zero,
   for which no belonging will be generated.

Belonging_Count: This is the number of clones of the object which you wish the character to have. It defaults to 1, and must be an integer. Values greater than 1 used with unique items will cause errors.

Belonging_Usage: Specifies how and whether the item is to be equipped. The possible values for this field are:

   Belonging_Usage_None: Do not equip the item.
   Belonging_Usage_Hold: Hold the item in a hand, as with wielding a
       weapon.
   Belonging_Usage_Wear: Wear the item, as with armour or clothing.
   Belonging_Usage_Adaptive: Examine the item for the most appropriate
       mode of usage and equip it in that fashion.  This is the default.

Belonging_Priority: Specifies how important it is to load the item onto the character quickly. Items of higher priority are always loaded before items of lower priority. Note that this mechanism will generally attempt to immediately load up as many of the character's belongings as can be handled within eval limitations. The possible values for this field are:

   Belonging_Priority_Low: Low priority.  The character's belonging
       loading process will be delayed if eval passes below Eval_High.
   Belonging_Priority_Normal: Normal priority.  The character's belonging
       loading process will be delayed if eval passes below Eval_High.
       This is the default.
   Belonging_Priority_High: High priority.  The character's belonging
       loading process will be delayed if eval passes below Eval_Medium.
   Belonging_Priority_Override: Overriding priority.  The character's
       belonging loading process will only be delayed if eval passes
       below Eval_Low, and the load deferment mechanism will not defer
       this item's loading.

Belonging_Initialize: Allows you to manipulate the item as it is loaded. This value must be a closure, which will be called with arguments of 1) the item, 2) the character, 3) the belonging descriptor. The return value is ignored. Destruction of the item is allowed, though not exactly recommended.

Belonging_Equip: Allows you to manipulate the item immediately after it is equipped. This value must be a closure, which will be called with arguments of 1) the item, 2) the character, 3) the belonging descriptor. The return value is ignored.

Belonging_Unequip: Allows you to manipulate the item immediately after it is unequipped. This value must be a closure, which will be called with arguments of 1) the item, 2) the character, 3) the belonging descriptor. The return value is ignored.

Belonging_Alternate: An alternate belonging which is used if this one is not available. This is only comes into play with unique items; "not available" means the item exists and has an environment other than the character, or that it is reserved by the keep system. The value of this field is interpreted as a belonging descriptor itself, specified using the exact same rules as any other. Alternates may be unique items with their own alternates in turn.

Working With Belonging Descriptors

To check values in belonging descriptors, #include <belonging.h> and use the macro Belonging_Query(x, y), where x is the descriptor and y is the field (Belonging_File, etc.) you wish to get the value of. It is not recommended to modify the values of belonging descriptors that are in use.

See Also

set_belongings(lfun), add_belonging(lfun), query_belongings(lfun), remove_belonging(lfun), descriptors(mechanisms)