Man identity

From LSWiki

Contents 1 Files 2 Description 2.1 Public Fields 3 See Also

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

descriptors(mechanisms), set_identity(lfun), query_identity(lfun), alter_identity(lfun)