Man modifier

From LSWiki

Files

/def/descriptor/modifier.c
/lib/descriptors/modifier.h
/mod/character/body.c
/mod/character/skills.c
/obj/extensions/weapon.c
/std/room.c

Description

Modifier descriptors are used to alter various properties of characters and items in a closely-controlled way -- allowing the modifier to be added and removed when desired, controlling the way it interacts with other modifiers, and so on. A variety of different modifier mechanisms use modifier descriptors, ensuring that the same general behaviors apply to all.

Many of these modifiers are specified using interface functions, such as set_stat_mod(), that support both a modifier descriptor specification and an older form. Generally, when using modifier specification with these, you must use mapping specification form. The general discussion of descriptor specification (see 'man descriptors') will give the outline of this; the information below details the information specific to modifier descriptors.

Modifier descriptors should generally not be altered after having been added; serious problems could be caused by changing some fields.

Public Fields

Modifier_Type: The type of the modifier. You generally do not need to specify this field, since the modifier interfaces will provide the appropriate type. The possible values are:

Modifier_Type_Absorption
Modifier_Type_Area_Control
Modifier_Type_Attribute
Modifier_Type_Encumbrance
Modifier_Type_Paralysis
Modifier_Type_Realm
Modifier_Type_Resistance
Modifier_Type_Skill
Modifier_Type_Speed
Modifier_Type_Trait
Modifier_Type_Visibility
Modifier_Type_Weapon_Rating

Modifier_Index: Indicates which values are affected by the modifier. Not all modifiers need this field, but when it is used, it is always an array, and if a non-array value is specified when the descriptor is created, it will be converted to an array. The array will also usually be shared globally to save memory; all this means that you would ever need to worry about is that, if you were to change the index field of a modifier descriptor (which you generally should not do anyway), you must set the entire field rather than changing an element within the current value. The exact contents of this field depend on the modifier type; for instance, attribute and skill modifiers have arrays of attribute and skill numbers, while resistance modifiers have arrays of string damage types.

Modifier_Amount: The amount of the modifier. For most modifier types, it must be an integer. For the weapon modifiers, it must be an integer or floating point value.

Modifier_Duration: The time, in seconds, after which to remove the modifier. If not specified, the modifier will stay until explicitly removed (though note that modifiers in characters are generally not kept through object save and restore).

Modifier_Max_Duration: If defined, this limits the maximum duration that merged modifiers can accumulate to or which a modifier's duration can be increased by resistance effects (i.e. vulnerability to the damage type).

Modifier_Bound: This field places a limit on modifier accumulation. For example, if Modifier_Amount is 5 and Modifier_Bound is 40, that means that this modifier will contribute 5 points up to a maximum of 40, but will not accumulate beyond that point. The same principle applies if the numbers were -5 and -40. If they were -5 and 40, that means that the modifier will counteract positive modifiers only if they would total over 40, and will not reduce them below 40. There are default values for this field, as follows. Positive modifiers receive the positive bound by default and negative modifiers the negative one.

Modifier_Type_Absorption        20               -20
Modifier_Type_Area_Control      __INT_MAX__ - 1  __INT_MIN__ + 1
Modifier_Type_Attribute         200              -200
Modifier_Type_Encumbrance       200              -200
Modifier_Type_Paralysis         __INT_MAX__ - 1  __INT_MIN__ + 1
Modifier_Type_Realm             __INT_MAX__ - 1  __INT_MIN__ + 1
Modifier_Type_Resistance        100              -100
Modifier_Type_Skill             200              -200
Modifier_Type_Speed             300              -300
Modifier_Type_Visibility        __INT_MAX__ - 1  __INT_MIN__ + 1
Modifier_Type_Weapon_Rating     20               -20

Modifier_Specification: For modifiers which need to give additional information about what value they are specifying. This is used by trait modifiers for traits such as Trait_Respiration and Trait_Diet; a modifier for Trait_Respiration might specify a Modifier_Specification of Respiration_None and a Modifier_Amount of 5, indicating the weight it provides toward the specified value.

Modifier_Add_Message: A message to be displayed to the host of the modifier when it is added. May be a string or a message array.

Modifier_Remove_Message: A message to be displayed to the host of the modifier when it is removed. May be a string or a message array.

Modifier_Fail_Message: A message to be displayed if the modifier is not applied due to it being resisted (only possible if Modifier_Damage_Type, below, is specified, and the modifier type supports being resisted).

Modifier_Merge_Message: A message to be displayed if the modifier is merged with another similar modifier, instead of Modifier_Add_Message.

Modifier_Parallel_Add_Message: A message to be displayed instead of the normal add message when there is another modifier already present which this modifier could be merged with if it were set mergeable. (If it actually were set mergeable, Modifier_Merge_Message would be used instead of this.)

Modifier_Parallel_Remove_Message: A message to be displayed instead of the normal remove message when there is another modifier present which this modifier could have been merged with if it were set mergeable.

Modifier_Supplementary_Message: A message whose usage is defined by the particular modifier implementation. Presently, this is only used by visibility modifiers, for which it specifies extra message content to be added to the message displayed when people appear or disappear as a result of visibility modifiers. This can be given in string or message array form. For example, this field could be specified as "in a flash of light" to cause people to appear or disappear in a flash of light rather than simply appearing or disappearing.

Modifier_Damage_Type: An optional field which, if specified, defines a damage type for the modifier so that it can potentially be resisted. The modifier type must support resisted modifiers for this to actually take place; all modifier types except realm and weapon aspect have support for resistance. Usually, only modifiers with negative amounts are interpreted as hostile and so resisted, unless Modifier_Flag_Always_Resist, below, is applied. If the modifier is completely resisted (its amount is reduced to zero or changed in sign), the modifier will not be added the target and Modifier_Fail_Message, if any, will be displayed rather than the normal Modifier_Add_Message.

Modifier_Flags: Flags associated with the modifier. These are standard bitmasks, combinable with bitwise-or (|). The possible flags are:

Modifier_Flag_Static: Modifiers with this flag will not accumulate
with other modifiers.  If more than one static modifier is present,
one with Modifier_Flag_Override, described below, will take priority
over one without; if neither or both have Modifier_Flag_Override,
then the higher absolute value of Modifier_Amount takes effect.  If
both static and accumulative modifiers are present, the static
modifier will take effect if it has Modifier_Flag_Override, otherwise
whichever final amount has the higher absolute value will be used.

Modifier_Flag_Override: As described for Modifier_Flag_Static.  This
flag may only be specified in conjunction with Modifier_Flag_Static.

Modifier_Flag_Always_Resist: If the modifier type supports resisted
modifiers and a Modifier_Damage_Type is specified, this causes the
modifier to always have resistance applied to it, even if it would
normally bypass resistance due to not being interpreted as hostile.

Modifier_Flag_Resist_Duration: Specifies that the modifier's duration
should be resisted rather than its amount.

Modifier_Flag_Resist_Both: Specifies that both the modifier's duration
and its amount should be resisted.

Modifier_Flag_Resistance_Silent: Specifies that no messages should be
generated for the resistance process.

Modifier_Flag_Mergeable: Indicates that the modifier should merge with
other modifiers which are essentially the same as it (usually meaning
from the same source) rather than existing side-by-side with them.
Two modifiers will merge only if they are identical in every respect
other than possibly amount, duration, and max duration, and if their
amounts have the same sign.  They will be merged by adding together the
remaining duration of the presently set modifier and the duration of
the new one, using the higher max duration, and using the amount with
the higher absolute value.  (The duration effects can be safely ignored
for modifiers without duration settings.)

Modifier_Flag_Merge_Duration_Silent: Indicates that if the modifier is
merged, the Modifier_Merge_Message should only be displayed if the
modifier's amount is increased by the merge -- meaning that merging
which only alters duration is silent.

Support Functions

status Modifier_Resist(descriptor dxr)

Returns true if the specified modifier is eligible to be resisted under normal rules (it has a Modifier_Damage_Type and either a negative amount or Modifier_Flag_Always_Resist).

status Modifier_Process_Resistance(descriptor dxr, object who)

Processes resistance as appropriate for the given descriptor to the given target. Returns True if the modifier should still be applied, False if it should not be applied and Modifier_Fail_Message should be displayed. Intended for use by the core system.

See Also

descriptors(mechanisms), modifier_group(descriptors), set_stat_mod(lfun), set_skill_mod(lfun), set_resistance_mod(lfun), set_visibility_mod(lfun)