Man element
From LSWiki
Contents |
Files
/def/descriptor/element.c /lib/descriptors/element.h /mod/basic/identity.c
Description
Element descriptors are used by the core identity mechanics for tracking the material makeup of objects and for several ancillary functions related to that role. "Element" is used here in the sense of "an element of a thing's composition" rather than that of a chemical element.
The element descriptor macros are defined in /lib/descriptors/element.h, but for working with them you will usually want to #include <materials.h> or <item.h>; materials.h includes element.h, and you will almost always need macros from materials.h as well, while item.h (the general-purpose header file for configuring items) in turn includes materials.h.
There are several "types" of element descriptor, though the difference between them is a matter of the context and manner of their use, not any more fundamental attribute. These are:
Finalized Element Descriptor This is a descriptor which is describing the material composition of an object and has had all its values coerced into a valid final form. The contents of query_elements() and find_elements() are finalized element descriptors, as will the return values of add_element() and find_element(). remove_element() requires a finalized element descriptor as its argument. DO NOT directly modify the contents of "live" finalized element descriptors that are in use in objects; your changes will not be properly acknowledged, and you will cause bizarre, nearly untraceable errors via the system's caching facilities. Use alter_element() or transmute_element() in the object for carrying out changes to finalized element descriptors.
Initial Element Descriptor This is an element descriptor which will be used to describe the material composition of an object but which has not yet been finalized; the argument to add_element() is usually one of these. In an initial element descriptor, you generally specify either the Element_Volume or the Element_Mass and allow the other value to be automatically calculated according to the material type's density. If you do specify both Element_Volume and Element_Mass, your settings will be honored, possibly resulting in an element whose density is different from the normal value for the material type and which therefore will return other than 1.0 from Material_Compression().
Element Proportion Descriptor An element descriptor being used to specify a relative proportion of the object's volume which will be made up of a given material. These descriptors are normally only used during initial object configuration. The proportion to be used defaults to 1.0, and if necessary should be specified using the pseudo-field Element_Proportion, which is an alias for Element_Volume. The proportion is a relative amount rather than an absolute volume; for example, if an object has two proportion settings, one of 1.0 and one of 0.5, that means that out of whatever volume is calculated for the object's shape, 2/3 of it will be made up of the first material and 1/3 will be made up of the second. Any setting for Element_Mass in a proportion descriptor will be ignored, but other field settings will be carried onward to the finalized element descriptor. Proportion descriptors always specify Element_Type, sometimes give Element_Color, Element_Part, and Element_Proportion, and rarely specify the other fields.
Element Search Descriptor An element descriptor being used for looking up an element in an object through the functions find_element() and find_elements(). Normally, any values given in this descriptor mean that you only want to find elements that exactly match the value you provide; however, some fields allow special values to be given for element search descriptors, with specific meanings for these alternate forms. This described under each individual field.
For any function argument that is normally interpreted as an array search descriptor, as a special case you may specify a closure rather than a descriptor specification. In this event, any descript for which your closure evaluates true will be considered a match.
Public Fields
Element_Type: The material of the element, generally specified as a material macro such as Material_Gold or Material_Oak, though any of the other valid ways of specifying a material may also be used. A finalized element descriptor will have an integer material code for its type field. If, for some reason, an initial element descriptor does not have this field, it will be set to Material_Iron as the descriptor is finalized, and a warning will be issued. In an element search descriptor, may be given as an array, meaning an element will match if its type is any of those listed.
Element_Volume: The volume of the element, in balaths (liters). A finalized element descriptor will have a floating-point value for this field. As an initial element descriptor is being finalized, if Element_Volume is specified and Element_Mass is not, the appropriate mass will be calculated from the volume and the Element_Type's density. The pseudo-field Element_Proportion, used with element proportion descriptors, is an alias for this field.
Element_Mass: The mass of the element, in dekans (kilograms). A finalized element descriptor will have a floating-point value for this field. As an initial element descriptor is being finalized, if Element_Mass is specified and Element_Volume is not, the appropriate volume will be calculated from the mass and the Element_Type's density.
Element_Color: The color of the element's material. In a finalized element descriptor, this will be a string, defaulting to the Element_Type's default color. In an element search descriptor, may be given as an array, meaning an element will match if its color is any of those listed. In an initial element descriptor, this may be given as Null (-1), which will be converted to a color selected randomly from those normally found in the Element_Type material.
Element_Part: The abstract 'part' of the object that the element makes up. Normally specified as one of the part macros from /lib/materials.h, such as Part_Bulk or Part_Coat, though any valid way of specifying one of these parts may be used. In a finalized element descriptor, this field will be an integer part code, defaulting to Part_Bulk. In an element search descriptor, may be specified as an array, meaning an element will match if its part is any of those listed.
Element_Form: The form into which the element's material is structured. Normally specified as one of the form macros from /lib/materials.h, such as as Form_Solid or Form_Cloth, though any valid way of specifying ones of these forms may be used. In a finalized element descriptor, this field will be an integer form code, defaulting to Form_Solid. In an element search descriptor, may be specified as an array, meaning an element will match if its form is any of those listed.
Element_Component: For objects with components, the component index or indices which the element is associated with. Currently this is only meaningful for livings, in which component indices are limb indices. Defaults to -1, meaning that the element is associated with all components of the object. May otherwise be an integer component index or an array of integer component indices. In an element search descriptor, the value of ({ -1 }) may be specified, meaning that the component field of an element must be -1 in order to match; otherwise, a (default) value of -1 means that any component value matches, and values other than -1 must match exactly.
Element_Flags: Special flags for the element. Flags are bitmasks which may be combined by bitwise or (|). In an element search descriptor, an array with one element may be given, for example ({ Element_Flag_Independent }) or ({ 0 }), meaning that an element will match only if its flags exactly match the value within the array; otherwise, an element will match if any of its flags match those in the value specified. The flag values and their meanings are:
Element_Flag_Independent: Indicates that the element is not intrinsic to the core composition of the object. The current practical meaning of this applies only to livings, where this flag means that the element will not be altered when the living's elements are recalculated due to race change, size change, or the like. An example would be if a living were given a Part_Coat element of Material_Mud; this element would not disappear when the living changed races, and so should be given Element_Flag_Independent. Elements with similar significance to non-living objects should also be given this flag.
Element_Flag_Unmergeable: Indicates that the element should not ever be merged with another element. Normally, when elements are added to an object, the system attempts to combine those that are sufficiently similar; so, for example, if two five-dekan elements of ordinary gold were added, the system would combine these into one ten-dekan element. If for any reason you would not want the element to be combined with another, use this flag.
Element_Flag_Preserve_Color: Indicates that the element's color should normally be preserved through transformations. This means that if the element is transmuted, its color will stay the same unless the transmutation specifies that colors should be overridden. For example, if an element's color were due to something like a permanent stain that would not change if its base material were transmuted, you would want to set this flag.
Element_Flag_Untransmutable: Indicates that the element should never be processed by transmute_element(). Elements with this flag will be skipped when transmute_element() is called with an element search descriptor as argument, and if a finalized element descriptor with this flag is specified, the function will fail with a warning issued.
Element_Flag_Secondary: Indicates that the element should be considered "secondary", which means that it will not be used for generating the host object's names.
Element_Flag_Blend: Indicates that the element "blends" in with the other elements present, and is not used for generating the host object's names and also does not appear in its description. Normally the material type determines this; this flag allows it to be specified for materials that would not normally blend.
Element_Flag_Visible: Indicates that an element which would not normally be considered visible to observation, such as for reason of having Part_Core or Part_Infusion for its Element_Part, should be considered visible.
Element_Flag_Suppress_Color_Override: Indicates that if the element would normally have its color overridden by another element, this behavior should be suppressed.
Element_Flag_Suppress_Override_Color: Indicates that if the element would normally override the colors of other elements, this behavior should be suppressed.
Element_Flag_Suppress_Material_Name: Indicates that the name of the material's element should be prevented from appearing in the names generated for the object.
Element_Flag_Suppress_Part_Description: Indicates that description of the part and form of the element should not be included in generated names, meaning only the basic material name and color will appear.
Element_Flag_Suppress_Material_Blend: Indicates that if the element would normally be considered secondary because of its material's settings, this behavior should be suppressed.
There is also a flag set, Element_Flags_Immutable, which is an alias for the combination of Element_Flag_Independent, Element_Flag_Unmergeable, Element_Flag_Untransmutable, and Element_Flag_Suppress_Color_Override. In situations where you plain do not want an element to be played around with, such as in many situations where you will be keeping track of it and removing it later, it is recommended to use this pseudo-flag; not only is it more convenient, but if more flags are created that you would want to be present in an immutable element, they will be added to this alias.
Element_Info: This is a field for specifying arbitrary user-defined information -- for example, marking an element as having been generated by a specific source so it can later be removed by that source. The data are stored in a mapping, allowing different user code to share the storage space. The support functions Element_Set_Info(), Element_Query_Info(), and Element_Clear_Info(), described below, are for working with this field; they should be used in all situations except when specifying the element initially (when it should be specified as a mapping) or when working with a "live" finalized element descriptor via the function alter_element(), which has its own support for changing Element_Info. When choosing key values for this field, please take care to use a specific enough namespace as to ensure there will be no conflicts; for example, you might use a key like "Project_Source_Type" rather than simply "type". Using string keys is recommended but not required. Keep in mind that most elements are subject to being saved and restored, and any information you put in this field which cannot be successfully serialized and deserialized (pointers to cloned objects, many closures) may be lost at some point. Also, do not rely on the Element_Info field always being the same mapping pointer; it may be copied at various times.
Internal Fields
Element_Tag: The tag for the descriptor system.
Support Functions
float Element_Density(descriptor dxr)
Returns the density of the element descriptor (its mass divided by its volume).
float Element_Compression(descriptor dxr)
Returns the compression factor of the element. This is a matter of its density relative to the normal density for its material. For example, a water element, normal density for which is 1.0, with a volume of 1.0 and a mass of 2.0, would have a compression factor of 2.0, indicating that it is compressed into half its normal volume. A compression factor of 1.0 indicates normal density; factors below 1.0 mean that the material is at less than its normal density rather than more.
descriptor Element_Finalize(descriptor dxr)
The process used to finalize initial element descriptors. Intended only for use by the core system.
status Element_Mergeable(descriptor a, descriptor b)
Determines whether two descriptors can be merged. Intended only for use by the core system.
descriptor Element_Attempt_Merge(descriptor dxr, descriptor array list)
Attempts to merge a descriptor into any suitable element of a list of descriptors. Intended only for use by the core system.
descriptor Element_Universal(descriptor dxr)
Ensures, if possible, that the specified descriptor is shared globally, returning the same descriptor or one which should be used in its place.
closure Element_Match(mixed spec)
Interprets its argument as the specification of an element search descriptor and returns a closure which will match element descriptors appropriate to the search descriptor. Intended only for use by the core system.
void Element_Set_Info(descriptor dxr, mixed key, mixed value)
Sets the specified key within the Element_Info field to the specified value.
mixed Element_Query_Info(descriptor dxr, mixed key)
Returns the value for the specified key within the Element_Info field.
void Element_Clear_Info(descriptor dxr, mixed key)
Removed the specified key from the Element_Info field.
string Element_Full_Name(descriptor dxr) string Element_Unknown_Full_Name(descriptor dxr) string Element_Subjective_Full_Name(descriptor dxr, object who) string Element_Colored_Full_Name(descriptor dxr) string Element_Colored_Unknown_Full_Name(descriptor dxr) string Element_Colored_Subjective_Full_Name(descriptor dxr, object who) These functions each request, from the element's material type, the corresponding version of the material's full name given the color set in the element descriptor.
float Element_Value(descriptor dxr) float Element_Unknown_Value(descriptor dxr) float Element_Subjective_Value(descriptor dxr, object who)
These functions each calculate, using the element's material type, the corresponding version of the material's value given the color and mass set in the element descriptor.
See Also
descriptors(mechanisms), add_element(lfun), add_proportion(lfun), remove_element(lfun), remove_proportion(lfun), find_element(lfun), find_elements(lfun), alter_element(lfun), transmute_element(lfun)
