Laine at 20:17, 11 June 2007

Laine — Mon, 11 Jun 2007 20:17:06 GMT

New page

==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==

[[man descriptors|descriptors(mechanisms)]], [[man add element|add_element(lfun)]], [[man add proportion|add_proportion(lfun)]], [[man remove element|remove_element(lfun)]], [[man remove proportion|remove_proportion(lfun)]], [[man find element|find_element(lfun)]],
[[man find elements|find_elements(lfun)]], [[man alter element|alter_element(lfun)]], [[man transmute element|transmute_element(lfun)]]

Man element - Revision history

Laine at 20:17, 11 June 2007