Man modifier
From LSWiki
Revision as of 16:49, 11 June 2007
Contents |
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. The exception to this is the message fields (though generally the removal message is the one you would care about) and one of the Modifier_Flags bitmasks, Modifier_Flag_Suspend_Remove_Calc; these are specifically allowed to be altered.
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_Suspend_Add_Calc: Signals that any recalculations that would normally be carried out when the modifier is added should not be performed.
Modifier_Flag_Suspend_Remove_Calc: Signals that any recalculations that would normally be carried out when the modifier is removed should not be performed.
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)
