Man belonging
From LSWiki
| Revision as of 14:08, 11 June 2007 (edit) Laine (Talk | contribs) (→Files) ← Previous diff |
Current revision (14:08, 11 June 2007) (edit) Laine (Talk | contribs) (→Working With Belonging Descriptors) |
||
| Line 105: | Line 105: | ||
| their own alternates in turn. | their own alternates in turn. | ||
| - | =Working With Belonging Descriptors= | + | ==Working With Belonging Descriptors== |
| To check values in belonging descriptors, #include <belonging.h> and use | To check values in belonging descriptors, #include <belonging.h> and use | ||
Current revision
belonging - belonging descriptors
Contents |
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)
