Laine at 20:37, 11 June 2007

2007-06-11T20:37:50Z

New page

==Files==

/def/descriptor/identity.c
/lib/descriptors/identity.h
/mod/basic/identity.c

==Description==

Identity descriptors are used by objects to define the way their identity
(names and short descriptions) are determined.

Identity descriptors which are in used by an object should not be directly
modified; changes may not be properly acknowledged and, because identity
descriptors are shared, serious errors may result. Instead, the function
alter_identity() in the object should be used.

Certain core concepts are critical to understand identity descriptors and
how they are used. The main one is that of assembling names out of nouns,
adjunct nouns, and adjectives. The basic idea is simple: if an object has
a noun of "rock" and an adjective of "big", then it will answer to the
names "big rock" and "rock". If it has nouns of "rock" and "stone" and
adjectives of "big" and "pretty", then it is a "big pretty rock", "big
pretty stone", "big rock", "big stone", "pretty rock", "pretty stone",
"rock", and "stone". (Incidentally, the longest final combination will
be the one that winds up being used as the object's main name; in this
case, "big pretty stone".) All the appropriate combinations will be put
together in determining the object's list of names. An example of an
adjunct noun is "suit" in "suit of armour"; these also will be combined
as appropriate. If no ordinary nouns are available, but adjunct nouns
are, the adjunct nouns will be used as ordinary nouns.

Another concept is the handling of identity codes, in particular multiple
identity codes applying to a given object. There are many sources of
identity codes applying to an object: its own explicit setting, its name
if any, its materials, its weapon and armour type if any. When object
configuration is resolved, an object which has no explicit identity code
setting will have the first code found from any of these sources set as
its identity code. If there are any more applicable identity codes found,
they will be available from query_extra_codes(); also, having multiple
identity codes forces names to be dynamically generated for each viewer
rather than being able to have lists stored. This is much more expensive
in terms of execution time than cacheable lists, so some care should be
taken at an administrative level to see that the bulk of objects in the
game do not require this behavior (though of course it should be used
where appropriate).

Last, the condition of "the object being known to the viewer" is often
referenced. To clarify, this means that the object's primary identity
code (its Identity_Code setting) is known to the viewer; any additional
identity codes do not count in this context.

===Public Fields===

Identity_Type: The identity type determines the general way in which the
object's identity will be constructed. (Integer.) The types are:

Identity_Type_Standard: The usual and default type, under which nouns,
adjunct nouns, and adjectives are collected from the object's identity
settings, its weapon and armour type (if any), and its material
configuration (usually its predominant material by volume). All the
other identity fields described below behave normally with this type.
Note that nouns, adjunct nouns, and adjectives from the identity
descriptor are added to those from other sources.

Identity_Type_Custom: Similar to Identity_Standard, but weapon type,
armour type, and materials do not influence configuration. Basically,
this means that the object's names are determined solely from its
identity settings.

Identity_Type_Unit: Indicates that the object is a unit of its main
material, meaning it is "a strawberry" or "an emerald" rather than,
for example, a "piece of strawberry" or a "piece of emerald". Causes
nouns, adjunct nouns, and adjectives from materials to be assembled
differently, and for weapon and armour type to be ignored.

Identity_Type_Preconfigured: Means that the object is configured with
a preset, static list of names (and possibly also of known names).
This type exists mainly for backward compatibility with the way object
names were configured prior to Ain Soph 2.0; new code should not use
this type, and it may be discontinued at some point. Almost all of
the normal behavior of the fields described below is suppressed when
this type is used; the only one which still retains its behavior is
Identity_Code.

Identity_Nouns: A list of nouns to apply to the object. (String array.)

Identity_Known_Nouns: A list of nouns which, if specified, overrides the
Identity_Nouns setting when the object is known by the viewer. Only has
meaning if the object possesses an identity code. (String array.)

Identity_Adjunct_Nouns: A list of adjunct nouns to apply to the object.
(String array.)

Identity_Known_Adjunct_Nouns: A list of adjunct nouns which, if specified,
overrides the Identity_Adjunct_Nouns setting when the object is known by
the viewer. Only has meaning if the object possesses an identity code.
(String array.)

Identity_Adjectives: A list of adjectives to apply to the object. (String
array.)

Identity_Known_Adjectives: A list of adjectives which, if specified,
overrides the Identity_Adjectives setting when the object is known by the
viewer. Only has meaning if the object possesses an identity code.
(String array.)

Identity_Special_Names: A list of names which the object should always
respond to, regardless of circumstances. Generally this is used for IDs
of the form PROJECT_TAG and the like. (String array.)

Identity_Code: An identity code for the object, as used by the general
item-identification mechanics. (The old-style function set_code() is
now implemented as an alter_identity() call to set this field.) Often
this field does not need to be set because it will be automatically set
based on other factors, such as the Identity_Name field, below. (String.)

Identity_Name: A name for the object. If Identity_Flag_Proper, described
below, is set, this is considered a proper name, otherwise a generic name.
For example, the artifact Soulshard has "Soulshard" as a proper name,
while iltarixai have "iltarix" as a generic name. Unless another flag,
Identity_Flag_Suppress_Name_Code, is set, an identity code for the object
will generated based on this field; for a proper name, the Identity_Name
field will be used as an identity code unchanged, and for a generic name,
the result of pluralize() applied to the Identity_Name field will be used
as an identity code. Normally, the object's Identity_Name is visible only
when the object is known to the viewer; the exception to this is when the
object has no Identity_Code setting at all. (String.)

Identity_Name_Adjectives: A list of adjectives to be applied to the
object's name when it is visible. Not frequently set. (String array.)

Identity_Effect: Used to designate an object as being "of such-and-thus
effect", in the popular style. For example, a magical ring might have
an Identity_Effect field of "protection"; this will cause names to be
added to it with "of protection" appended. This will only be visible
when the object is known to the viewer. Note that no identity code will
be automatically generated based on this field, and an identity code
should be manually specified. (String array.)

Identity_Image: Can be used in either of two ways. 1) When specified as a
string array, the object is regarded as being an image or representation
of the names listed in the array; for example, if Identity_Nouns were set
to ({ "painting" }) and Identity_Image to ({ "a landscape" }), the
object would be "a painting of a landscape". 2) When specified as a
string, this string is interpreted as the object name, and this object is
considered to be an image of that object. The other object's names are
requested from it (via special functions) and its identity code, is taken
into account, and will apply to this object; for instance, if the object
pointed to is an iltarix, this object will appear as an image "of an
iltarix", "of a silvery metal longsword", or whatever else as appropriate.
See also Identity_Flag_Effect_Suppress_Image, below.

Identity_Color: May be used to specify a color which should be applied to
the object's entire name as viewed by users, overriding any colors normally
supplied by materials or any other source. This is the bare color name,
with no terminal control characters, e.g. "black", "white". (String.)

Identity_Known_Color: Functions like Identity_Color, but only takes effect
when the Identity_Code is known by the viewer. (String.)

Identity_Flags: A set of bitmask flags, combinable with bitwise or (|),
which can alter various aspects of the identity descriptor's behavior.
(Integer.) The flags are:

Identity_Flag_Proper: Indicates that when the object is known to the
viewer, its name is considered a proper name.

Identity_Flag_Unknown_Proper: Indicates that the object's name is
considered proper when it is not known. This is mainly for backward
compatibility and is rarely useful in new code.

Identity_Flag_Suppress_Name_Code: Suppresses the normal behavior of
deriving an identity code from the Identity_Name field.

Identity_Flag_Effect_Override_Image: Indicates that if a viewer would
normally see the results of applying both the Identity_Effect and
Identity_Image fields, to suppress the effect of Identity_Image.

==See Also==

[[man descriptors|descriptors(mechanisms)]], [[man set identity|set_identity(lfun)]], [[man query identity|query_identity(lfun)]], [[man alter identity|alter_identity(lfun)]]

Man identity - Revision history

Laine at 20:37, 11 June 2007